MediaPipe — Google ML 多模态流水线

是什么

MediaPipe Google 端侧 ML 流水线：姿态、手势、人脸等 Graph 计算。

日常类比：像乐高积木拼视觉任务：检测块+跟踪块+渲染块串成实时管线。

典型用法：克隆仓库读 README，跑官方最小示例，再对照源码目录理解模块边界。

为什么重要

• 学 Calculator/Graph 式 CV 管线
• 移动端实时推理部署
• 对照 opencv 传统链
• AR/健身计数产品参考

核心要点

1. 架构分层：先分清 UI/核心库/IO 边界，再读入口 main。
2. 数据流：跟踪一份输入如何变成输出（帧、包、tensor）。
3. 依赖：看清系统库与第三方，避免装错环境。
4. 扩展点：插件、配置、钩子在哪里暴露。
5. 运维：日志、指标、崩溃复现路径。

核心架构

MediaPipe 的核心抽象是计算图（Graph）加处理器（Calculator）：

• Graph：以 Protobuf 文本格式描述的有向计算图，节点为 Calculator，边为 Stream（数据流）。图定义与代码解耦，可热切换不同拓扑。
• Calculator：每个处理器实现 Open/Process/Close 三接口。MediaPipe 内置 100+ Calculator，涵盖解码、推理、NMS、可视化等。
• Packet：图中传递的不可变消息单元，携带时间戳与类型擦除的数据载体，支持 cv::Mat、Tensor、Landmark 等类型。
• 跨平台支持：同一套图定义可运行于 Android、iOS、Web（WASM）和 Desktop（C++/Python）。
• TFLite 后端：推理节点默认对接 TensorFlow Lite，支持 GPU Delegate（OpenGL ES / Metal）和 NNAPI，实现移动端硬件加速。

新版 MediaPipe Tasks API 提供更高级封装，以任务（Task）为单位暴露接口，隐藏底层 Graph 细节，降低使用门槛。

性能与规格

任务	关键点数	典型帧率（移动端）	典型帧率（桌面 GPU）
手部检测	21 点/手	30 FPS	60+ FPS
人脸 Mesh	468 点	25~30 FPS	60+ FPS
姿态估计	33 点（含 3D）	20~25 FPS	50+ FPS
人脸检测	6 关键点	60 FPS	120+ FPS

手部关键点检测延迟（USB Camera 到结果）：桌面约 1525ms；移动端约 3050ms。模型尺寸：手部检测 Palm Detection 约 2.8MB，Hand Landmark 约 3.9MB，均适合端侧部署。

代码示例

import cv2
import mediapipe as mp

mp_hands = mp.solutions.hands
mp_drawing = mp.solutions.drawing_utils

cap = cv2.VideoCapture(0)
with mp_hands.Hands(max_num_hands=2, min_detection_confidence=0.7) as hands:
    while cap.isOpened():
        ret, frame = cap.read()
        if not ret:
            break
        rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
        results = hands.process(rgb)
        if results.multi_hand_landmarks:
            for lm in results.multi_hand_landmarks:
                mp_drawing.draw_landmarks(frame, lm, mp_hands.HAND_CONNECTIONS)
                tip = lm.landmark[mp_hands.HandLandmark.INDEX_FINGER_TIP]
                print(f"食指指尖: x={tip.x:.3f} y={tip.y:.3f}")
        cv2.imshow("MediaPipe Hands", frame)
        if cv2.waitKey(1) == ord('q'):
            break
cap.release()

实践案例

案例 1：最小可运行

pip install mediapipe
python -c "import mediapipe; print(mediapipe.__version__)"

对照 README 的参数表，改一个选项观察输出变化。

案例 2：读源码入口

从计算图配置文件（.pbtxt）找模块边界，追踪 Calculator 注册宏 REGISTER_CALCULATOR，画出数据流草图。

案例 3：与邻居项目对照

对照 opencv 的实现差异：MediaPipe 强调图声明式编排，OpenCV 强调命令式逐帧处理；各写一条适用场景笔记。

案例 4：接入自己的管线

把手势检测结果（关键点坐标）接入鼠标控制或 OSC 消息发送，记录延迟与坐标系转换约束。

案例 5：Bazel 构建 vs pip 包对比

在相同任务上对比 pip 预编译包（简单快速）与源码 Bazel 构建（可定制 Calculator）的开发体验差异，记录各自适用场景。

案例 6：与双千 atlas 交叉阅读

写完本篇后，在 projects-atlas 打开同子类邻居 1 篇，检查实践案例是否覆盖安装/命令/排障。

踩过的坑

1. 依赖版本漂移：按文档锁版本，否则编译失败难定位。
2. 硬编解码路径：GPU/驱动差异导致黑屏或崩溃，准备软解回退。
3. 权限与端口：服务器组件忘开端口或 HTTPS 证书，客户端连不上。
4. 路径写死：示例用绝对路径，换机器必挂。
5. 行数与模板：交付前用 quality-gate 扫一遍，避免关联链到未写 slug。
6. Bazel 构建缓慢：从源码编译需要 Bazel，首次构建可能需 30~60 分钟；优先使用 pip install mediapipe 预编译包。
7. Android GPU Delegate 兼容性：部分 Adreno GPU 驱动版本与 OpenGL ES 委托不兼容，降级到 CPU 推理时需在 Gradle 配置中手动指定。
8. 坐标归一化：MediaPipe 输出的关键点坐标是 0~1 归一化值，需乘以图像宽高才能得到像素坐标，混淆会导致覆盖绘制错位。

适用 vs 不适用场景

适用：

• 学习该领域开源架构与模块边界
• 做原型验证或自建服务
• 与专题内邻居对照读

不适用：

• 闭源 SaaS 一键替代（若需合规审计）
• 超大规模不经优化的默认配置
• 不看文档直接改内核 fork

历史小故事（可跳过）

• 项目源于社区/公司开源贡献，Stars 随场景周期性上涨。
• 近年多与云原生、GPU、WebRTC 生态交叉。
• 文档与 issue 常比论文更新快，读 release note 很重要。
• 与 study 站邻居项目常构成「编码-传输-播放」全链。

学到什么

• 先跑通再读码，效率高于反过来。
• 开源多媒体/系统栈多为「薄壳 + 厚库」。
• 配置即架构，改一个 flag 可能换一条数据路径。
• 关联笔记要优先链到 written.txt 已有 slug。

延伸阅读

• 官方仓库：https://github.com/google-ai-edge/mediapipe
• opencv
• ultralytics
• dlib
• insightface
• sam2

关联

• opencv —— 同专题对照阅读
• ultralytics —— 同专题对照阅读
• dlib —— 同专题对照阅读
• insightface —— 同专题对照阅读
• sam2 —— 同专题对照阅读

维护备注

• 合并后运行 npm run atlas 刷新反向链接。

反向链接

• dlib —— dlib — C++ 机器学习 / CV 工具箱
• insightface —— InsightFace — 人脸识别 / 检测 SOTA
• opencv —— OpenCV — 开源计算机视觉库与跨平台图像视频处理
• sam2 —— SAM 2 — Segment Anything Model 2
• scrcpy —— scrcpy — Android 屏幕镜像 / 录制
• ultralytics —— Ultralytics — YOLOv8/v11 实现