企业官网建设流程全解析

MediaPipe 多平台部署实战：3 条命令在桌面、Android、iOS 上跑通手部跟踪

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

你要完成的目标很具体：让一段摄像头画面在本地实时标出手部关键点，先在桌面端用 C++ 跑通验证效果，再把同一套逻辑打包成可安装的 Android APK 和 iOS 应用。MediaPipe 把模型推理、状态管理封装在计算图（graph）里，你真正要做的只有三件事：选对部署路径、装好依赖、运行对应的 bazel 目标。

先定路径：按"验证还是发布"做取舍

部署 MediaPipe 时最常见的弯路，是一上来就在目标平台搭全套工具链。正确的顺序是先回答一个问题：你是要验证模型效果，还是要发布一个应用？

• 只验证效果、写算法原型：用 Python 包即可，pip install mediapipe一条命令，不需要 bazel，也不需要 clone 仓库。官方 Python 包在 docs/getting_started/python.md 有说明。
• 要在桌面跑 C++ 推理、或嵌入到自己的 Linux/macOS 程序：需要 clone 源码，用 bazel 构建mediapipe/examples/desktop下的命令行示例。
• 要上架 Android / iOS 商店：需要 bazel 交叉编译，产出 APK 和 IPA，入口在mediapipe/examples/android与mediapipe/examples/ios。

三条路径共享同一批 pbtxt 计算图配置，所以先在 Python 里选定效果，再切到原生路径基本不用改逻辑。边缘设备（如 Coral）也属于第三种路径的变体，示例见 mediapipe/examples/coral/。

用 Python 包 10 分钟验证模型效果

这条路的环境准备最轻，适合所有平台（Windows、macOS、Linux x86_64）。

1. 创建并激活虚拟环境：

python3 -m venv mp_env && source mp_env/bin/activate

2. 安装官方包并导入：

pip install mediapipe

import mediapipe as mp mp_hands = mp.solutions.hands with mp_hands.Hands(max_num_hands=2, min_detection_confidence=0.5) as hands: # 对任意 BGR 图像或视频帧调用 process() # results.multi_hand_landmarks 即 21 个关键点 pass

如果pip install报No matching distribution found，先确认你的 Python 是 64 位且版本受支持（Linux/macOS x86_64、Windows amd64），排错细节见 docs/getting_started/troubleshooting.md。

在 Linux/macOS 桌面上构建并运行 C++ 手部跟踪

Python 验证通过后，桌面端 C++ 路径的价值在于性能与可嵌入性。环境准备和部署实操在这里是交织的：每装一个依赖，就顺手跑一个更小的构建目标来验证它是否生效。

第 1 步：clone 仓库并确认 bazel 可用。使用 bazelisk 代替直接装 bazel，它会自动选中仓库要求的版本。

git clone https://gitcode.com/GitHub_Trending/med/mediapipe cd mediapipe bazel version # 应能输出版本号；未安装则先装 bazelisk

第 2 步：装 OpenCV。桌面示例强依赖 OpenCV 与 FFmpeg。Ubuntu/Debian 上最省事的方式是装系统包：

sudo apt-get install -y libopencv-dev libopencv-video-dev

macOS 上用 Homebrew 装 OpenCV 3，并卸掉冲突的 glog：

brew install opencv@3 brew uninstall --ignore-dependencies glog

如果系统包版本与仓库默认配置不匹配，可以改用仓库自带的 setup_opencv.sh 从源码编译并自动改写WORKSPACE指向。这一步的详细分支（含 OpenCV 4 需要改third_party/opencv_linux.BUILD）见 docs/getting_started/install.md。

第 3 步：跑 hello_world 验证工具链。这一步能独立暴露 OpenCV/Python 配置问题，成本最低：

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

终端连续打印 10 行Hello World!即工具链就绪。

第 4 步：运行手部跟踪。CPU 版一条命令即可，程序会打开摄像头实时标注 21 个手部关键点：

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

如果 Linux 机器带 EGL 驱动的 GPU，可改用 GPU 子图获得更高帧率：

sudo apt-get install mesa-common-dev libegl1-mesa-dev libgles2-mesa-dev bazel run --copt -DMESA_EGL_NO_X11_HEADERS --copt -DEGL_NO_X11 \ mediapipe/examples/desktop/hand_tracking:hand_tracking_gpu

完整构建命令（含--calculator_graph_config_file换图方式）见 docs/getting_started/cpp.md。想换算法时，直接指向 mediapipe/graphs/hand_tracking/ 下的其他 pbtxt 文件，代码一行不用改。

构建可安装的 Android APK 与 iOS 应用

移动端路径的核心思路：复用仓库里的现成示例工程，只改你需要的部分。示例工程目录（handtrackinggpu、facemeshgpu、posetrackinggpu等）与你的最终 App 结构基本一致，方便对照。

Android：

1. 在仓库根目录准备 SDK/NDK 环境（需要已装 Android Studio）：

./setup_android_sdk_and_ndk.sh

2. 构建单个或多个 APK。单目标：

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

或者用仓库自带的脚本一次构建全部示例并自动安装到已连接设备（-d指定 APK 输出目录，-i只安装已构建产物）：

./build_android_examples.sh -d out_android

3. 把产物装到真机验证：

adb install bazel-bin/mediapipe/examples/android/src/java/com/google/mediapipe/apps/handtrackinggpu/handtrackinggpu.apk

iOS（只能在 macOS 上构建）：

./build_ios_examples.sh -d out_ios

该脚本内部执行bazel build -c opt --config=ios_arm64产出 IPA；也可以打开仓库里的mediapipe/MediaPipe.tulsiproj工程，用 Xcode 直接对真机 Build and Run。更多平台参数见 docs/getting_started/ios.md。

避坑与调优

以下问题按"现象 → 原因 → 解法"组织，覆盖从构建到运行的最常见卡点。

现象：链接阶段报undefined reference to 'cv::VideoCapture'等大量 cv 符号。原因：本地 OpenCV 版本或安装路径与WORKSPACE里new_local_repository(name = "linux_opencv", ...)指向的路径不一致，或 OpenCV 4 的 include 目录结构（多了opencv4/一层）没同步到third_party/opencv_linux.BUILD。 解法：核对两处路径，确保path指向真实安装前缀；OpenCV 4 需在cc_library的hdrs/includes中放开include/opencv4/对应行。修完执行bazel clean再重建。

现象：构建前报错An error occurred during the fetch of repository 'local_execution_config_python'。原因：bazel 找不到 Python 可执行文件（PATH 里没有或 conda 环境未激活）。 解法：显式传入路径，例如bazel build ... --action_env PYTHON_BIN_PATH=$(which python3)。

现象：下载依赖时java.io.IOException或Connection timed out，卡在某个或多个 remote 仓库。原因：bazel 拉取第三方依赖的源在你的网络环境下不稳定。 解法：给 bazel 加代理参数--host_jvm_args "-DsocksProxyHost=<ip> -DsocksProxyPort=<port>"；排除网络因素后执行bazel clean --expunge重试。

现象：GPU 桌面示例启动后黑屏、崩溃或提示找不到 EGL。原因：Linux 桌面 GPU 需要 EGL/GLES 驱动，很多最小化系统只装了 X11。 解法：安装mesa-common-dev libegl1-mesa-dev libgles2-mesa-dev后加--copt -DMESA_EGL_NO_X11_HEADERS --copt -DEGL_NO_X11重建；驱动短期解决不了就先退回 CPU 版（--define MEDIAPIPE_DISABLE_GPU=1），逻辑完全一致。

现象：Android 示例启动即崩，日志含Native method not found。原因：NDK 未正确配置导致 native 库没编进 APK，或应用包名与 JNI 注册路径不一致。 解法：重跑setup_android_sdk_and_ndk.sh，adb install -r强制覆盖安装，并用adb logcat抓取完整堆栈定位缺失的 .so。

🛠 性能调优按收益排序：把*_desktop_live.pbtxt换成*_desktop_live_gpu.pbtxt启用 GPU 子图（如 mediapipe/graphs/hand_tracking/hand_tracking_desktop_live_gpu.pbtxt）；其次对 TFLite 模型做量化压缩输入尺寸；最后才考虑改图裁剪无用节点。用内置 profiler 定位瓶颈的方法见 docs/tools/performance_benchmarking.md 与 docs/tools/tracing_and_profiling.md。

下一步：把示例变成你自己的应用

跑通三条路径后，按这个顺序深入：

1. 读懂计算图：学习 node/calculator 概念并手写图，从 docs/framework_concepts/building_graphs_cpp.md 和 docs/framework_concepts/calculators.md 入手，配合 docs/tools/visualizer.md 的可视化方式验证图结构。
2. 换成自己的模型：用仓库内的 mediapipe/model_maker/ 基于自有数据微调检测/关键点模型，产出 tflite 后替换图中模型路径。
3. 浏览全部解决方案：人脸、姿态、分割等完整清单在 docs/solutions/solutions.md，每个方案文档都标注了各平台的支持情况。
4. Python 里跑自定义图：不想写 C++ 时，docs/getting_started/python_framework.md 展示了如何在 Python 中直接执行 pbtxt 图。

遇到构建问题，第一手排错入口始终是 docs/getting_started/troubleshooting.md。

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