MediaPipe 多平台上手：从克隆仓库到首个实时手部跟踪 Demo

MediaPipe 多平台上手：从克隆仓库到首个实时手部跟踪 Demo

【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe

在桌面端打开摄像头，把手伸到镜头前，21 个关键点连成的骨架线条实时跟着你的动作走——这是你用 MediaPipe 能搭出来的第一个效果。MediaPipe 是跨平台的实时媒体处理框架，把人脸、手势、姿态、物体检测这些相机流任务变成一次 bazel 构建。读完这篇，你能在本地构建并运行桌面实时手部跟踪 Demo，并掌握 Android、iOS、Web、Python 四端的三步落地路径。

先弄清 MediaPipe：一套代码，六种运行目标

MediaPipe 做两层事：一层是开箱即用的 Solutions（比如手部跟踪、人脸网格，直接调用即可），一层是底层 Framework（用 Packet、Graph、Calculator 三个基础概念拼接自定义推理管线）。新手先玩 Solutions，需要定制时再学 Framework。

当前仓库里，旧版 Legacy Solutions 已停止更新，能力覆盖以 docs/solutions/solutions.md 的表格为准，主要任务的平台支持如下：

MediaPipe 桌面端 Demo：三步跑通手部跟踪

Linux 桌面是最快的上手路径，macOS 同理，只需三步。

第 1 步：装依赖、克隆仓库。先安装 Bazelisk（它会自动选对 Bazel 版本），再装 OpenCV 开发库：

sudo apt-get install -y libopencv-core-dev libopencv-highgui-dev \ libopencv-calib3d-dev libopencv-features2d-dev \ libopencv-imgproc-dev libopencv-video-dev

克隆仓库并进入目录：

git clone --depth 1 https://gitcode.com/GitHub_Trending/med/mediapipe cd mediapipe

第 2 步：构建并运行手部跟踪 Demo。CPU 版无需任何额外配置：

GLOG_logtostderr=1 bazel run --define MEDIAPIPE_DISABLE_GPU=1 \ mediapipe/examples/desktop/hand_tracking:hand_tracking_cpu

第 3 步：验证结果。窗口打开后把摄像头对准手，21 个关键点和连线应实时跟随。想更轻量地确认环境可用，可以先跑 hello_world，终端连续打印Hello World!即代表构建环境就绪：

GLOG_logtostderr=1 bazel run --define MEDIAPIPE_DISABLE_GPU=1 \ mediapipe/examples/desktop/hello_world:hello_world

各平台完整说明：docs/getting_started/install.md。

按任务选子图：一张表查模块

不同任务对应不同的 Solution 和现成子图（子图是一个描述推理管线的 pbtxt 文件，不用你手写）。先查表，再翻对应文档：

子图文件集中在 mediapipe/modules/ 下。自己写图时，把 CPU 子图换成 GPU 子图，是最直接的提速手段。

其他平台落地：Android、iOS、Web、Python 各三步

• Android：先在仓库根目录执行./setup_android_sdk_and_ndk.sh装好 SDK/NDK；再用--config=android_arm64构建 APK，例如 3D 物体检测示例：

bazel build -c opt --config=android_arm64 \ mediapipe/examples/android/src/java/com/google/mediapipe/apps/objectdetectiongpu:objectdetectiongpu

构建产物用 adb 安装到真机即可，详见 docs/getting_started/android.md。

• iOS：装好 Bazelisk 和 OpenCV 3 后，用仓库自带的 Tulsi 工程 mediapipe/MediaPipe.tulsiproj/ 生成 Xcode 项目，选定目标设备运行；示例 App 在 mediapipe/examples/ios/，文档见 docs/getting_started/ios.md。

• Web：无需本地构建，在 HTML 中引入对应 Solution 的 JS 库，用getUserMedia取相机帧后逐帧送入推理即可，接入方式见 docs/getting_started/javascript.md。

• Python：通过 pip 安装 mediapipe 包后，几行代码即可读帧、推理、拿到关键点结果，见 docs/getting_started/python.md。

排坑清单：五个卡住构建的问题

• OpenCV 链接报错：版本不匹配是主因，官方推荐 OpenCV 3.x 至 4.1；OpenCV 4 必须把 third_party/opencv_linux.BUILD 的头文件路径改成include/opencv4/。图省事可以直接跑仓库自带的./setup_opencv.sh从源码编译并自动改配置。
• macOS 构建卡在 glog：brew install opencv@3之后执行brew uninstall --ignore-dependencies glog，去掉冲突依赖。
• 桌面 GPU 跑不起来：Linux 纯 CPU 环境保留--define MEDIAPIPE_DISABLE_GPU=1；启用 GPU 需装 mesa EGL 开发包并追加编译参数：

bazel run --copt -DMESA_EGL_NO_X11_HEADERS --copt -DEGL_NO_X11 \ mediapipe/examples/desktop/hello_world:hello_world

注意 macOS 桌面端不支持 GPU 推理，只能走 CPU。

• Bazel 版本异常：统一用 Bazelisk 管理 Bazel 版本，不要手动固定某个 Bazel 发行版。
• 推理偏慢：把 CPU 子图换成 GPU 子图（如 HandLandmarkCpu 换 HandLandmarkGpu），或对 TFLite 模型做量化压缩；基准测试方法见 docs/tools/performance_benchmarking.md。

下一步方向与关键资源

Demo 跑通后，下一步是两条线：一是学 Framework 的 Graph、Calculator、Packet 三个概念，搭自己的推理管线，概念文档在 docs/framework_concepts/framework_concepts.md；二是用 Model Maker 拿自己的数据微调模型，代码在 mediapipe/model_maker/。

关键资源：

• 安装与环境配置：docs/getting_started/install.md
• 构建故障排查：docs/getting_started/troubleshooting.md
• 解决方案总表：docs/solutions/solutions.md
• 桌面端示例代码：mediapipe/examples/desktop/
• 性能基准测试指南：docs/tools/performance_benchmarking.md

【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe