MediaPipe Python 安装指南：3步装完跑通人脸检测，真正需要时才从源码编译

MediaPipe Python 安装指南3步装完跑通人脸检测真正需要时才从源码编译【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipeMediaPipe 是面向媒体处理的跨平台实时机器学习框架人脸关键点、手势、姿态都只要几行代码。这篇文章带你装好 Python 版先用 pip 三步装完并跑通第一个人脸检测案例只有在需要定制时才进入源码编译分支坑和解法一并给到。先判断你大概率不需要编译 结论放前面90% 的场景直接用 PyPI 上的预编译包就够了。MediaPipe 的 Python 包在 PyPI 上已经打包好了 Linuxx86_64、macOS、Windowsamd64三个平台的二进制装完就能import。只有下面三种情况才值得走源码编译你要改源码新增自定义 calculator、修一个上游 bug、给团队打包定制 wheel你的平台是aarch64 LinuxNvidia Jetson、树莓派PyPI 没有这个架构的 wheel只能自己编译你需要离线交付一个可控版本的安装包如果你不在这三种情况里直接跳到下一节的主路径别碰编译。MediaPipe 能做的事情远不止人脸上图为 3D 物体跟踪Objectron效果主路径pip 三步装好 MediaPipe 第一步确认环境你需要64 位的 Python 3.9 ~ 3.12。一行命令确认python3 --version版本不在范围内时先升级 Python后面所有步骤都依赖它。第二步建虚拟环境并安装python3 -m venv mp_env source mp_env/bin/activate pip install mediapipe第一条命令创建并激活一个叫mp_env的隔离环境不污染系统 Python第二条安装 MediaPipe 及其全部依赖numpy、opencv-contrib-python、absl-py 等清单见仓库根目录的 requirements.txt。第三步验证import mediapipe as mp print(mp.__version__)能打印出版本号、不报ImportError安装就完成了。以后退出环境用deactivate。第一个完整案例给照片画上人脸检测 安装成功不等于会用。跑一个最小的人脸检测案例顺便记住一个最容易踩的坑MediaPipe 吃 RGBOpenCV 读出来是 BGR必须转换否则识别率会莫名变差。import cv2 import mediapipe as mp image cv2.imread(your_photo.jpg) # 换成你自己的照片 rgb cv2.cvtColor(image, cv2.COLOR_BGR2RGB) with mp.solutions.face_detection.FaceDetection( model_selection1, min_detection_confidence0.5) as detector: result detector.process(rgb) for face in result.face_landmarks: for p in face.landmark: # 每张脸 6 个关键点 cv2.circle(image, (int(p.x * image.shape[1]), int(p.y * image.shape[0])), 2, (0, 255, 0), -1) cv2.imwrite(detected.jpg, image)model_selection1选择通用人脸模型适合远距离、正脸偏多的照片min_detection_confidence0.5是置信度门槛。各参数含义可以查 docs/getting_started/python.md 里的 Face Detection 章节。上图就是这类输出检测框、6 个关键点眼、鼻、嘴和置信度分数分支源码编译什么时候上、怎么上 只有前面说过的那三种情况才走这里。核心是三个工具链Bazel3.4.0 及以上setup.py 里有硬检查版本过旧会直接报错退出、OpenCV、Protobuf 编译器。Debian / Ubuntu 一条命令装依赖sudo apt install python3-dev python3-venv protobuf-compilermacOS 用brew install protobuf需要源码编译 OpenCV 时再加cmake。OpenCV 本身用系统包管理器装好即可不必自己编。然后是克隆、装依赖、编译git clone https://gitcode.com/GitHub_Trending/med/mediapipe cd mediapipe python3 -m venv mp_env source mp_env/bin/activate pip install -r requirements.txt python3 setup.py install --link-opencv两个关键点说清楚--link-opencv要不要加加了就链接你系统里现成的 OpenCV省掉从源码构建 OpenCV 的几十分钟不加则走 Bazel 静态编译 OpenCV更慢但环境更干净。日常用建议加。想打 wheel 而不是直接装把最后一条换成python3 setup.py bdist_wheel产物在dist/下pip install dist/mediapipe-*.whl即可。还有一个不显眼但真实的坑setup.py 里MEDIAPIPE_DISABLE_GPU环境变量默认值是关闭 GPU 编译的。如果你要一个带 GPU 支持的自编译包编译前先export MEDIAPIPE_DISABLE_GPU0。三个最常见的坑和解法 Bazel 找不到 Python 路径报错里带local_execution_config_python和Repository command failed字样意思是 Bazel 没定位到你的 Python 解释器。给构建命令补一个环境变量即可bazel build --action_env PYTHON_BIN_PATH$(which python3) ...链接 OpenCV 4 报 undefined reference系统的 OpenCV 4Debian 11 / Ubuntu 21.04 起常见和仓库默认构建配置不匹配。解法是编辑 third_party/opencv_linux.BUILD 里的cc_library把hdrs glob([include/opencv4/opencv2/**/*.h*])和includes [include/opencv4/]两行加上多架构系统按gcc -print-multiarch的结果换成对应子目录。aarch64 装不上报找不到匹配的 wheel这不是错误是缺失PyPI 官方不提供 aarch64 的 wheel。Jetson、树莓派用户没有捷径只能按上一节自己编译耗时以小时计。建议预留时间并且把机器上的 OpenCV 也一并装齐再动手。装完之后往哪走Python 框架与 Solutions 用法总览docs/getting_started/python.md源码编译各平台环境搭建docs/getting_started/install.md常见构建错误全集docs/getting_started/troubleshooting.md各方案Face Mesh、Hands、Pose 等细节docs/solutions/各平台运行示例mediapipe/examples/记住一条主线先用 pip 跑通能跑就不要编译要编译就带着--link-opencv和PYTHON_BIN_PATH上工能省掉大部分折腾。【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考