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如果你还在用 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需要手动转颜色、手动剥 protoimport mediapipe as mp import cv2 hands mp.solutions.hands.Hands(max_num_hands2) 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_optionspython.BaseOptions( model_asset_pathhand_landmarker.task), num_hands2) 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) # 拇指尖直接取属性结果结构对照迁移时基本是改名Legacy 字段Tasks 字段说明results.multi_hand_landmarksresult.hand_landmarks每只手 21 个点的列表results.multi_handednessresult.handedness左右手分类取category_namelm.landmark[i].xproto 对象hand[i].x普通属性免去手动转 proto迁移实战按场景来先装好新版包并确认 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_optionspython.BaseOptions( model_asset_pathmodels/hand_landmarker.task), running_modevision.RunningMode.IMAGE, num_hands2) 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_optionspython.BaseOptions( model_asset_pathmodels/hand_landmarker.task), running_modevision.RunningMode.VIDEO, num_hands2) 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_formatmp.ImageFormat.SRGB, datacv2.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_optionspython.BaseOptions( model_asset_pathmodels/hand_landmarker_int8.task, delegatepython.BaseOptions.Delegate.GPU), # CPU / GPU / LITERT running_modevision.RunningMode.VIDEO)delegate目前支持CPU、GPU、LITERTGPU 路径目前只在部分平台Ubuntu 系上验证过其它环境先默认跑 CPU确认无误再切。踩坑速查现象、原因、处理现象常见原因怎么处理ValueError/ 建实例即报模型相关错误model_asset_path指向的路径不对或没下载.task用绝对路径或确认相对路径基于工作目录ls -l看文件在不在、权限对不对报错说图像格式不支持 / 解码失败把 BGR 帧直接塞进mp.Image或 numpy 不是uint8先cv2.cvtColor(..., cv2.COLOR_BGR2RGB)再声明ImageFormat.SRGBtimestamp相关报错要求单调递增时间戳重复或回退比如用帧号但丢帧用墙钟int((time.time()-start)*1000)保证每帧严格变大LIVE_STREAM模式报错说缺回调该模式必须在HandLandmarkerOptions里给result_callback加回调函数接收(result, image, ts)同步逐帧处理则改用VIDEO排查顺序建议先看模型文件再看输入格式最后看运行模式与时间戳——这三处覆盖了绝大多数报错。迁移后的验证怎么确认没白迁跑通单图用场景 A 对一张手部图片detect()能打印出 21 个点的坐标说明模型和加载都 OK。校验关键点确认拇指尖索引 4、手腕索引 0落在画面合理位置result.handedness的Left/Right和肉眼一致。对比耗时拿同一组帧分别跑新旧接口记录单帧处理时长想量化整体性能可参考 性能基准测试工具 的方法自建一组对照。两条可选优化把模型换成 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考