MediaPipe 迁移指南：从 Legacy Solutions 到 Tasks API，这 4 处改动就够

MediaPipe 迁移指南从 Legacy Solutions 到 Tasks API这 4 处改动就够【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe一个再熟悉不过的开头你项目里是不是还留着import mediapipe as mp后面紧跟mp.solutions.hands的行每次pip install -U都得提心吊胆生怕哪天旧版 Solutions 直接消失。现在可以安心动手了MediaPipe 的官方主线已经切到 Tasks API本文陪你把迁移完整走一遍——不用重写整个项目真正要改的就是配置、入口、结果字段这几处。旧版 Solutions 怎么跑Tasks API 怎么跑MediaPipe 旧版 Solutions 本质是一个封装好的流程式图你调hands.process(image)图计算在内部悄悄跑完然后把一整个 results 对象抛给你。代价是两头都得你自己收拾——进来前手动转 RGB出来后自己翻 proto 字段。Tasks API 把同一套图计算拆成了三个独立的组件BaseOptions管模型和算力。模型路径或内存 buffer、CPU/GPU delegate 都在这里指定HandLandmarkerOptions管任务行为。运行模式、手数上限、三个置信度阈值结果对象强类型 dataclass坐标、手性直接取没有中间层。旧版把这三件事全藏在一个process调用里新版摊开成显式的配置 → 创建 → 调用。最小可运行的新版调用长这样import mediapipe as mp from mediapipe.tasks import python from mediapipe.tasks.python import vision # 先声明任务怎么跑模型文件、运行模式、最多检测几只手 options vision.HandLandmarkerOptions( base_optionspython.BaseOptions(model_asset_pathhand_landmarker.task), running_modevision.RunningMode.IMAGE, num_hands2, ) # 用配置创建检测器with 语句负责用完自动释放 with vision.HandLandmarker.create_from_options(options) as landmarker: # 直接从磁盘构造 mp.Image颜色格式转换不用自己写 image mp.Image.create_from_file(test_photo.jpg) result landmarker.detect(image) print(len(result.hand_landmarks)) # 检测到的手数量下面这张仓库里的示例输出可以当作任务该长什么样的参照参数映射速查旧参数在新版叫什么先把高频参数的对照放在这里迁移时照着抄就行旧版mp.solutions.hands新版HandLandmarkerOptions默认值变化模型随 solution 内置base_options.model_asset_path新增必填运行模式不可选running_mode默认IMAGEmax_num_hands2num_hands1默认值从 2 变 1min_detection_confidence0.5min_hand_detection_confidence0.5仅改名无对应项min_hand_presence_confidence0.5新增min_tracking_confidence0.5min_tracking_confidence0.5不变三个最容易踩的坑一句话症状加一句话解决模型文件打不开旧版 solution 内置的.tflite图不能直接喂给 Tasks API换成.task格式的任务包确认你用的模型在官方模型列表里有对应的 Tasks 版本具体以官方文档为准调错方法直接抛异常running_mode决定调用方式IMAGE 模式用detectVIDEO 模式必须用detect_for_video选错会直接报错视频跑到一半崩掉detect_for_video要求每帧的timestamp_ms严格单调递增丢帧、回帧都算先别慌把时间戳生成逻辑挪到读帧成功之后就行。完整迁移对照一段真实的手部追踪代码下面这段旧代码是典型形态BGR 转 RGB、关writeable、用完手动 close五行里全是胶水。hands mp.solutions.hands.Hands( static_image_modeTrue, max_num_hands2, min_detection_confidence0.5) image cv2.cvtColor(image, cv2.COLOR_BGR2RGB) results hands.process(image) landmarks results.multi_hand_landmarks hands.close()新版等价实现逐行对应上面的每件事from mediapipe.tasks import python from mediapipe.tasks.python import vision # running_mode 选 IMAGE 还是 VIDEO决定后面调 detect 还是 detect_for_video options vision.HandLandmarkerOptions( base_optionspython.BaseOptions( model_asset_pathhand_landmarker.task), running_modevision.RunningMode.VIDEO, num_hands2, min_hand_detection_confidence0.5, min_tracking_confidence0.5, ) with vision.HandLandmarker.create_from_options(options) as landmarker: # mp.Image 收 numpy 数组BGR→RGB 这一步仍由你做 frame cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) mp_image mp.Image(image_formatmp.ImageFormat.SRGB, dataframe) result landmarker.detect_for_video(mp_image, timestamp_ms) # multi_hand_landmarks 改叫 hand_landmarks坐标直接取 for hand in result.hand_landmarks: for pt in hand: x, y int(pt.x * w), int(pt.y * h) cv2.circle(frame, (x, y), 2, (0, 255, 0), -1)结果字段的重命名值得单独记一下results.multi_hand_landmarks变成result.hand_landmarksresults.multi_handedness变成result.handedness每只手多了一个hand_world_landmarks世界坐标旧版没有。绘制环节如果还习惯用solutions.drawing_utils也可以整体切到 Tasks 侧的绘图工具签名以仓库mediapipe/tasks/python/vision/drawing_utils.py里的定义为准。迁移完顺手拿到的三样东西GPU 加速一行开启delegatepython.BaseOptions.Delegate.GPU注意官方注释里写明 GPU 支持目前仅限 Ubuntu 平台其余环境以 CPU 为准一套框架接多模态任务文本、音频、图像走同一套 options 约定摄像头实时流模式result_callback回调也是这条路上顺带的模型自己造仓库自带 Model Maker在公开模型上微调后直接产出.task文件配合官方 benchmark 工具 验证前后差距。今天就做的一步把依赖升到mediapipe0.10.0跑通 examples/ 里的第一个 vision demo确认.task模型能加载、参数名能和上面的表对上一一对应旧代码就算安全落地了。迁移中撞到什么奇怪的报错欢迎贴到仓库 issue 里一起看。【免费下载链接】mediapipeCross-platform, customizable ML solutions for live and streaming media.项目地址: https://gitcode.com/GitHub_Trending/med/mediapipe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考