google-ai-edge/mediapipe · 上手攻略

  • 仓库：google-ai-edge/mediapipe
  • 链接：https://github.com/google-ai-edge/mediapipe
  • 分类：ai
  • 作者：Tom
  • 更新：2026-07-10

这是什么

MediaPipe 是 Google 开源的端侧机器学习框架，专注于在手机（Android/iOS）、Web、桌面、边缘设备和 IoT 上实时运行 ML 模型。它不是训练框架，而是推理框架——帮你把 Google 训练好的模型快速部署到各类设备上，以低延迟处理图像、视频、音频和文本。

Google 于 2023 年将 MediaPipe 主开发文档迁移至 developers.google.com/mediapipe，GitHub 仓库保留了源代码和部分旧文档。当前推荐使用的是 MediaPipe Tasks（高层 API，无需了解底层机制）和 MediaPipe Model Maker（用你自己的数据微调模型）。

解决什么问题

在端侧部署 ML 模型有几个核心难点：

  • 性能优化：手机/边缘设备算力有限，需要手工 SIMD/NEON/Metal 优化
  • 跨平台：Android/iOS/Web/桌面各有一套 API，写四份代码
  • 预训练模型难找：自己训一个 hand detection 模型成本很高
  • 隐私：视频流不想上传服务器，但用户又需要实时响应

MediaPipe 解决了上述所有问题：它自带预训练模型（face/hand/pose 等），跨平台 API 统一推理接口，数据完全在本地处理（不发送至 Google 服务器），且经过深度优化。

快速安装

Python（最简单）

pip install mediapipe
# MediaPipe Python 支持 Python 3.9–3.12（注：截至 2025年9月，最新支持到 3.12）

Android（Gradle）

// build.gradle
dependencies {
    implementation 'com.google.mediapipe:mediapipe-android:0.10.14'
}

iOS（CocoaPods）

# Podfile
pod 'MediaPipe', '~> 0.10.14'

或 Swift Package Manager，详见官方文档。

Web（npm）

npm install @mediapipe/tasks-vision

MediaPipe Studio（浏览器可视化调试）

无需安装，访问 https://mediapipe.dev/ 或 https://developers.google.com/mediapipe/studio 直接在浏览器里体验所有 Task 模型的效果。

核心用法

MediaPipe 分为三层，按使用频率从高到低：

MediaPipe Tasks（推荐，90% 场景用这个）

手部关键点检测

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

base_options = python.BaseOptions(model_asset_path='hand_landmarker.task')
options = vision.HandLandmarkerOptions(base_options=base_options, num_hands=2)
detector = vision.HandLandmarker.create_from_options(options)

image = mp.Image.create_from_file('photo.jpg')
result = detector.detect(image)

print(f"检测到 {len(result.hand_landmarks)} 只手")
print(f"手部关键点：{result.hand_landmarks[0][:5]}")  # 前5个关键点

人脸检测

from mediapipe.tasks import vision

base_options = python.BaseOptions(model_asset_path='face_detector.task')
options = vision.FaceDetectorOptions(base_options=base_options)
detector = vision.FaceDetector.create_from_options(options)

image = mp.Image.create_from_file('selfie.jpg')
result = detector.detect(image)
print(f"检测到 {len(result.detections)} 张人脸")

姿态关键点检测（Pose Estimation）

options = vision.PoseLandmarkerOptions(
    base_options=base_options,
    output_segmentation_masks=True
)
detector = vision.PoseLandmarker.create_from_options(options)

result = detector.detect(image)
# result.pose_landmarks: 33个身体关键点 [x, y, z, visibility]
# result.segmentation_masks: 分割蒙版（背景抠图）

图像分类 / 文本分类 / 音频分类

# 图像分类
classifier = vision.ImageClassifier.create_from_options(options)
result = classifier.classify(image)

# 文本分类
text_classifier = vision.TextClassifier.create_from_options(options)
result = text_classifier.classify("This is great!")

# 音频分类（实时麦克风输入）
audio_classifier = vision.AudioClassifier.create_from_options(options)

实时视频流模式

# VIDEO 模式：逐帧处理视频文件或摄像头流
options = vision.HandLandmarkerOptions(
    base_options=base_options,
    running_mode=vision.RunningMode.VIDEO  # 区别于 IMAGE（单帧）
)
detector = vision.HandLandmarker.create_from_options(options)

timestamp = 0
while cap.isOpened():
    ret, frame = cap.read()
    mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=frame)
    result = detector.detect_for_video(mp_image, timestamp)
    timestamp += 33  # 约30fps

MediaPipe Model Maker（用你自己的数据微调）

当预训练模型不满足需求时，用 Model Maker 在你的数据上微调：

from mediapipe.model_maker import image_classifier

# 加载自定义训练数据
data = image_classifier.DataLoader.from_folder('dataset/')

# 从头训练或微调
model = image_classifier.ModelMaker(model_type='image_classifier')
model.export(export_dir='exported_model/')

MediaPipe Framework（底层自定义管道）

适合需要深度定制 pipeline 的场景，例如自定义多级检测器串联（先 palm detection → 再 hand landmark）：

# 需要从源码编译，支持 C++ / Android / iOS
# 详见 https://developers.google.com/mediapipe/framework

典型适用场景

  • 实时手势交互：AR/VR 应用、游戏手势操控、智能摄像头手势控制
  • 健身/运动 App：俯卧撑/深蹲计数、瑜伽姿势纠正（Pose Estimation）
  • 视频会议特效：虚拟背景、人像分割、AR 滤镜（Google Meet 背景模糊同款技术）
  • 无障碍辅助：手语识别、眼动追踪（Iris Detection）
  • 移动端 AI 相机：实时贴纸、人脸变形、物体识别
  • 工业检测：生产线视觉质量检测（结合 Model Maker 自定义训练）
  • Web 端 AI：Chrome 扩展、Web 应用中的摄像头 ML 特效（WebAssembly 加速）

坑与注意

  1. Legacy Solutions 已停止维护：2023 年 3 月后，旧的 MediaPipe 解决方案不再更新，建议统一使用 MediaPipe Tasks 新 API（mediapipe.tasks.vision 系列）。

  2. Python 版本限制：截至 2025 年 9 月，MediaPipe Python 包仅支持到 Python 3.12，且 Windows 支持相对不完善（推荐 macOS/Linux）。如果 Windows 环境有兼容问题，考虑用 Docker 或 WSL。

  3. 数据隐私：MediaPipe Tasks 不发送用户数据到 Google 服务器（这是官方明确承诺的），但 MediaPipe Tasks 本身会发送使用量和性能指标给 Google 用于产品改进，如果你的 App 有严格隐私合规要求（如 GDPR），需要向用户披露或在 App 隐私政策中说明。

  4. iOS Swift 支持较弱：MediaPipe iOS 主要支持 Objective-C++，Swift 支持通过 bridging header 实现但体验不完整，部分高级功能需要写 Objective-C 代码。

  5. Web 版本依赖：Web 端依赖 WebAssembly + WebGL，在低性能设备或 Safari 上可能降速明显，生产 Web 应用建议做设备能力检测。

  6. 模型版权：MediaPipe 提供的预训练模型（如 face/hand/pose）是 Google 自己的模型，可以商用，但如果你用 Model Maker 微调，数据来源需要合规。

与同类对比

框架 定位 预训练模型 跨平台 实时性 上手难度
MediaPipe 端侧 ML 推理 丰富（face/hand/pose等） ✅ 全平台 极高 低
TensorFlow Lite 端侧 ML 推理 一般 ✅ 高 中
PyTorch Mobile 端侧 ML 推理 无（需自己转换） ✅ 较高 中
OpenCV DNN 传统 CV + 轻量 DL 有限 ✅ 中 低
ML Kit (Google) 移动端 ML 丰富 仅 Android/iOS 高 极低（但封闭）
Apple Vision/Core ML 苹果平台 ML 丰富 仅 Apple 高 低（Apple生态）

MediaPipe 的核心优势是：Google 级别的优化性能 + 开源可定制 + 跨全平台，且预训练模型质量高。如果是纯移动端且不考虑 iOS+Android 以外平台，ML Kit 更省心；如果需要跨 Web/桌面/IoT，MediaPipe 是唯一成熟开源选择。

一句话推荐结论

需要快速在手机/Web/桌面部署一个经过生产验证的 face/hand/pose 检测能力，MediaPipe 是目前开源最成熟、模型最丰富、优化最好的选择，配合 Model Maker 还能用你自己的数据微调，适合几乎所有端侧视觉 AI 场景。

来源：GitHub README (https://github.com/google-ai-edge/mediapipe)、Google Developers MediaPipe 官方文档 (developers.google.com/mediapipe)