MediaPipe 手部检测迁移实录：从 Legacy Solutions 到 Tasks API

MediaPipe 手部检测迁移实录：从 Legacy Solutions 到 Tasks API

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

上周给一个小组做技术分享，有人现场提问：他们的项目还在用旧版mp.solutions跑手部检测，想升级到新架构却不知道从哪下手。我把那次分享整理成了这篇文章。

先说下背景。旧版 API 的process()会把图像预处理、模型推理、结果拼装全塞进一次调用，跑在老机器上能明显感觉到卡。我们在 M1 芯片的 macOS 笔记本上用 4K 测试图实测，迁移前后差距不小：

下面是迁移时真正踩过的路径。

先判断：你的代码需不需要动手

别急着改代码，先花 30 秒对一下自己的情况：

如果你的项目还在mp.solutions.hands.Hands上，后面四节就是按你实际会遇到的顺序排的。

新范式的本质：把"怎么算"交给模型

旧版的心智模型是"搭一条流水线"：你负责输入怎么切、中间怎么传、输出怎么拼。Tasks 的思路反过来——手部检测器 是一个独立组件，给它一个.task模型文件和一个图像对象，它还你一份强类型的结构化结果，中间过程你不用管。

最小可运行的样子大概是这样：

# 旧：一行 process，返回的 proto 要自己拆开用 results = hands.process(rgb_image) print(results.multi_hand_landmarks) # 新：两行创建，结果字段直接可读 with landmarker := vision.HandLandmarker.create_from_options(options): print(landmarker.detect(mp_image).hand_landmarks)

变化不止写法。multi_hand_landmarks变成了hand_landmarks，multi_handedness变成handedness，坐标不用再手算缩放，直接拿x / y / z。这些字段名的映射表是迁移时最常查的东西。

单张图片：改完就能跑的场景

这是最轻的一步，也是建议先跑通的最小单元。模型要先从 MediaPipe 官方模型库下载.task格式（旧的.pb不再更新了）：

# hand_landmarker 模型，约 7MB，放到 models/ 下 # 下载地址见官方文档里的模型列表页

import mediapipe as mp from mediapipe.tasks import python from mediapipe.tasks.python import vision options = vision.HandLandmarkerOptions( base_options=python.BaseOptions(model_asset_path="models/hand_landmarker.task"), num_hands=2, ) with vision.HandLandmarker.create_from_options(options) as lm: # RGB 是硬要求，OpenCV 读出来是 BGR，必须转，不然模型输出全空 rgb = cv2.cvtColor(bgr, cv2.COLOR_BGR2RGB) result = lm.detect(mp.Image(image_format=mp.ImageFormat.SRGB, data=rgb)) print(len(result.hand_landmarks))

⚠️ 你可能会遇到：FileNotFoundError: models/hand_landmarker.task。 原因：model_asset_path是相对路径，解析基准是你的工作目录而不是脚本目录。 一行修复：os.path.abspath("models/hand_landmarker.task")。

⚠️ 你可能会遇到：能跑通但返回空列表，一点关键点都没有。 原因：传了 BGR 格式的图，通道顺序不对。 一行修复：cv2.cvtColor(img, cv2.COLOR_BGR2RGB)再传。

检测出关键点之后，如果你的下一步是做手势识别（判断剪刀手、比心这类离散手势），直接接上仓库里的 手势识别器，范式是一样的：换个 Options、换个 detect 方法，结果字段照样是强类型。

视频流：时间戳这一关最容易卡住

如果你的输入是摄像头或录像，别沿用上面的 IMAGE 模式。改成 VIDEO 模式后，追踪器会跨帧维护状态，而状态同步依赖你每帧传入的时间戳——这就是"这一步卡住的人最多"的原因。

options = vision.HandLandmarkerOptions( base_options=python.BaseOptions(model_asset_path="models/hand_landmarker.task"), running_mode=vision.RunningMode.VIDEO, ) frame_ts = 0 while True: ok, frame = cap.read() if not ok: break # 时间戳必须严格递增，重复或回退会直接抛错 result = lm.detect_for_video(to_mp_image(frame), frame_ts) frame_ts += 1

⚠️ 你可能会遇到：timestamps must be monotonically increasing。 原因：视频丢帧或你手动跳帧时，时间戳没跟着动。 一行修复：frame_ts = int(time.time() * 1000)，用系统时钟而不是自增计数器。

用真实时钟比用自增计数更稳：自增计数在丢帧时会"虚高"，时钟在丢帧时会"跳"但顺序不乱，追踪器只在乎顺序。

生产部署：三件必须做的事

从 demo 到上线，有三件旧版时代不用操心、现在要自己做的事：

• 模型随包发布。.task文件别指望运行时下载，要么打进安装包，要么走你自己的分发通道。发布前确认models/目录在产物里。
• GPU 委托。BaseOptions里加delegate=python.BaseOptions.Delegate.GPU，前提是目标设备有可用的推理后端。CPU 兜底逻辑留着，别假设 GPU 一定在。
• 基准回归。仓库里带了 benchmark 入口，见 hand_landmarker 基准脚本，迁移前后各跑一遍，把 P50 / P99 写进变更记录。数字对得上，才有底气切流量。

部署形态上，C++、Java、iOS 三端的 Tasks 接口是同一套选项字段的映射，Python 端调通的参数可以直接照搬到其他端，不用重新踩一遍坑。

迁移完成的四步自检

跑完后，你应该能看到这四件事都成立：

• 单图场景：新旧两版在 10 张固定测试图上，检测到的手数和关键点坐标误差在 1 个像素以内。
• 视频场景：连续跑 60 秒摄像头流，无时间戳报错，追踪 ID 不跳变。
• 基准：P99 延迟不高于旧版，内存占用降到原来的六成左右。
• 依赖：requirements里旧版 Solutions 相关的包已经清干净，grep -r "mp.solutions" .无命中。

四条都勾上，旧依赖就可以从工程里拆掉了。迁移这件事到这里才算真正落地，而不是"代码换了、旧包还挂着"。

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