企业官网建设流程全解析

MediaPipe 迁移完整指南：从 Legacy Solutions 到新版 Tasks API 怎么用

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

如果你还在用 MediaPipe 的旧版 Legacy Solutions，这篇迁移教程带你完成 legacy API 替换、升级到新版 Tasks API：先判断要不要迁，再讲清新旧差异，最后按三个真实场景给出代码写法并排查常见报错。

我需要迁移吗？先做三个判断

迁移不是强制的，下面三条满足任意一条，就值得花半小时把代码换掉：

• 代码里还在调mp.solutions.hands.Hands(...)这类接口——这些属于 Legacy Solutions，仓库文档里已经明确标注为旧版方案（见 MediaPipe Solutions 总览）。
• 你用的模型是旧的.pb/graph格式——新版 Tasks 需要.task打包模型，模型来源和加载方式都变了。
• 想跑在 Android / iOS / 桌面 / Web 上——Tasks API 用同一套接口覆盖多端，Legacy 则要为每个平台单独接线。

三条都不沾边的话，继续用 Legacy 也没问题，不必为了迁移而迁移。

新旧差异：把一条流水线拆成独立工位

打个比方：Legacy 像一条焊死的流水线，检测、追踪、出结果都揉在一起，你只能整体process()然后自己去剥结果；Tasks API 把这段拆成了独立工位——加载模型、喂图、解析结果各自独立，结果直接是结构化数据。

Legacy 写法（mp.solutions，需要手动转颜色、手动剥 proto）：

import mediapipe as mp import cv2 hands = mp.solutions.hands.Hands(max_num_hands=2) cap = cv2.VideoCapture(0) while cap.isOpened(): ok, frame = cap.read() if not ok: break results = hands.process(cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)) if results.multi_hand_landmarks: for hand in results.multi_hand_landmarks: print(hand.landmark[4].x) # 拇指尖 hands.close()

新版 Tasks 写法（模型、输入、结果解耦，坐标直接取属性）：

from mediapipe.tasks import python from mediapipe.tasks.python import vision import mediapipe as mp options = vision.HandLandmarkerOptions( base_options=python.BaseOptions( model_asset_path="hand_landmarker.task"), num_hands=2) with vision.HandLandmarker.create_from_options(options) as lm: image = mp.Image.create_from_file("hand.jpg") result = lm.detect(image) for hand in result.hand_landmarks: print(hand[4].x) # 拇指尖，直接取属性

结果结构对照，迁移时基本是改名：

迁移实战：按场景来

先装好新版包并确认 Python ≥ 3.8（安装细节见 Python 安装说明），再准备一个.task模型，从 官方模型库文档 下载手部模型并放到项目里。下面三个场景，由易到难。

🎯 场景 A：处理单张图片（门槛最低）

一次性读图、出结果，最适合先跑通。RunningMode.IMAGE是默认模式，detect()直接返回：

from mediapipe.tasks import python from mediapipe.tasks.python import vision import mediapipe as mp options = vision.HandLandmarkerOptions( base_options=python.BaseOptions( model_asset_path="models/hand_landmarker.task"), running_mode=vision.RunningMode.IMAGE, num_hands=2) with vision.HandLandmarker.create_from_options(options) as landmarker: image = mp.Image.create_from_file("hand.jpg") result = landmarker.detect(image) for hand, handed in zip(result.hand_landmarks, result.handedness): name = handed[0].category_name # Left / Right tip = hand[4] # 拇指尖 print(name, round(tip.x, 3), round(tip.y, 3))

关键点索引和 Legacy 一致：0是手腕，4是拇指尖，8是食指指尖，枚举定义在vision.HandLandmark里。

🎥 场景 B：摄像头 / 视频流实时处理

实时场景的关键是运行模式 + 时间戳两件事：模式要设成VIDEO（或LIVE_STREAM走回调），每帧传一个单调递增的毫秒时间戳。

import time import cv2 from mediapipe.tasks import python from mediapipe.tasks.python import vision import mediapipe as mp options = vision.HandLandmarkerOptions( base_options=python.BaseOptions( model_asset_path="models/hand_landmarker.task"), running_mode=vision.RunningMode.VIDEO, num_hands=2) with vision.HandLandmarker.create_from_options(options) as landmarker: cap = cv2.VideoCapture(0) start = time.time() while cap.isOpened(): ok, frame = cap.read() if not ok: break ts_ms = int((time.time() - start) * 1000) # 严格递增 mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)) result = landmarker.detect_for_video(mp_image, ts_ms) cv2.imshow("hand", frame) if cv2.waitKey(5) & 0xFF == 27: break cap.release()

注意mp.Image接收的是RGB的 numpy 数组，所以从 OpenCV 的 BGR 帧要cvtColor一下；时间戳别用帧号硬凑，用墙钟换算成毫秒更稳。

⚙️ 场景 C：性能要求高时

要压低延迟，从两个方向入手：

• 换量化模型：优先用 int8 版.task，体积和推理都更省，精度损失通常可接受。
• 开硬件加速：在BaseOptions里指定delegate。

options = vision.HandLandmarkerOptions( base_options=python.BaseOptions( model_asset_path="models/hand_landmarker_int8.task", delegate=python.BaseOptions.Delegate.GPU), # CPU / GPU / LITERT running_mode=vision.RunningMode.VIDEO)

delegate目前支持CPU、GPU、LITERT；GPU 路径目前只在部分平台（Ubuntu 系）上验证过，其它环境先默认跑 CPU，确认无误再切。

踩坑速查：现象、原因、处理

排查顺序建议：先看模型文件，再看输入格式，最后看运行模式与时间戳——这三处覆盖了绝大多数报错。

迁移后的验证：怎么确认没白迁

1. 跑通单图：用场景 A 对一张手部图片detect()，能打印出 21 个点的坐标，说明模型和加载都 OK。
2. 校验关键点：确认拇指尖（索引 4）、手腕（索引 0）落在画面合理位置，result.handedness的Left/Right和肉眼一致。
3. 对比耗时：拿同一组帧分别跑新旧接口，记录单帧处理时长；想量化整体性能，可参考 性能基准测试工具 的方法自建一组对照。

两条可选优化：把模型换成 int8 版先看延迟变化；再按场景 C 切delegate试硬件加速。两项都别一次上，方便定位是哪个带来收益。

写在最后

迁移的核心其实是三件事：换成.task模型、结果改成结构化读取、实时模式带上正确的时间戳。接口名会随版本变，但「加载—输入—解析」这条主线是稳定的，抓住它就够应付后续迭代。

• 想扩展到手势、人脸、姿态，接口形态与手部检测一致，直接换对应的*Landmarker即可。
• 多端部署时，先用桌面 Python 跑通，再迁移到 Android / iOS，能少走很多弯路。
• 遇到具体报错，优先核对上面那张踩坑表，再翻对应模块源码的 docstring，通常比外部检索更快。

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