企业官网建设流程全解析

MediaPipe 手部追踪升级实战：三步把 Hands 迁移到 Hand Landmarker 的完整避坑指南

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

打开最新版 MediaPipe，你熟悉的mp.solutions.hands.Hands已经被新的 Hand Landmarker 取代——包路径变了、模型要手动指定、参数名换了一整套。如果你正卡在这一步，别慌，按下面三步走，10 分钟内就能把手部追踪升级到新 API 并跑起来。

为什么要换：从"一坨"到"拆开装"

旧版Hands把检测、跟踪、关键点识别全塞在一个类里，配置只能靠构造函数几个参数，想单独换模型、切 CPU/GPU 都很别扭。Hand Landmarker 走的是 MediaPipe Tasks 这套新范式：先定义一个 options 对象，再据此创建检测器，内部用可复用的子图组装流程。从 手部模型子图定义 能看到，它把检测、关键点识别拆成hand_landmark_cpu、hand_landmark_gpu、hand_landmark_tracking_*等独立子图，CPU/GPU 可自动切换，还能按需只装轻量部分。

下面这张表把两套 API 的差别一次说清：

最后一行是新 API 独有的：它支持把结果通过回调异步抛给你，实时摄像头场景不用再每帧干等。

三步完成迁移 🚀

第一步：环境准备

先确认 MediaPipe 版本够新，模型文件放在仓库里就能直接引用。

# 升到最新版，Hand Landmarker 需要 0.9+ pip install mediapipe --upgrade

装完后你会看到mediapipe.modules.hand_landmark下有hand_landmark_full.tflite和hand_landmark_lite.tflite两个模型文件，稍后就用它们。

第二步：代码改造

把"构造即运行"的旧写法，换成"先配 options 再创建检测器"的新写法。

# 旧写法 hands = mp.solutions.hands.Hands(max_num_hands=2) result = hands.process(rgb_frame) # 新写法 base = python.BaseOptions(model_asset_path='hand_landmark_full.tflite') opts = vision.HandLandmarkerOptions(base_options=base, num_hands=2) landmarker = vision.HandLandmarker.create_from_options(opts)

改完你会看到detect、detect_for_video、detect_async三个方法对应三种运行模式，比旧版更明确。

第三步：参数调优

参数映射如下，旧参数基本都是改名，还多了一个"手部存在"阈值：

# 三个阈值一起调，控制"稳不稳、准不准" opts = vision.HandLandmarkerOptions( min_hand_detection_confidence=0.7, min_hand_presence_confidence=0.7, min_tracking_confidence=0.7)

调完你就能看到关键点既不容易掉，也不容易乱飘。

跑通一个最小示例 ✅

这段代码演示怎么用 Hand Landmarker 对一张静态图做手部追踪，把每只手 21 个关键点画出来并保存，是验证"跑起来了"最快的方式。

import cv2 import mediapipe as mp from mediapipe.tasks import python from mediapipe.tasks.python import vision # 图像模式，无需时间戳和回调 base = python.BaseOptions(model_asset_path='hand_landmark_full.tflite') opts = vision.HandLandmarkerOptions(base_options=base, running_mode=vision.RunningMode.IMAGE) landmarker = vision.HandLandmarker.create_from_options(opts) # 读图并转成 MediaPipe 需要的 RGB img = cv2.cvtColor(cv2.imread('hand.jpg'), cv2.COLOR_BGR2RGB) mp_img = mp.Image(image_format=mp.ImageFormat.SRGB, data=img) result = landmarker.detect(mp_img) # 把每只手的 21 个关键点画成小圆点 for hand in result.hand_landmarks: for lm in hand: x, y = int(lm.x * img.shape[1]), int(lm.y * img.shape[0]) cv2.circle(img, (x, y), 3, (0, 255, 0), -1) cv2.imwrite('out.jpg', cv2.cvtColor(img, cv2.COLOR_RGB2BGR)) print(f'检测到 {len(result.hand_landmarks)} 只手')

运行后你会看到命令行打印"检测到 1 只手"，保存出的out.jpg上手掌和每根手指关节处各有一个绿色小圆点，连起来正好是一只手。

5 个容易踩的坑 ⚠️

模型路径找不到

创建检测器时直接报错说模型加载失败，多半是用了相对路径但当前工作目录不在那儿，或者文件名打错。跑之前先断言一下文件存在最省心：

import os assert os.path.exists('hand_landmark_full.tflite'), '模型文件不存在'

关键点乱飘或整只手消失

实时画面里手一快，关键点就抖动、甚至整只手消失，原因是三个阈值默认都是 0.5，对手部存在判定偏严。想让跟踪更稳，把跟踪阈值往下放一点：

opts = vision.HandLandmarkerOptions(min_tracking_confidence=0.4)

时间戳不连续

调detect_for_video或detect_async时报ValueError，或者结果卡住不动，是因为timestamp_ms必须每帧单调递增，不能固定给一个值。用真实毫秒即可：

timestamp_ms = int(frame_time * 1000) # 别写死

图像模式却带了回调

用IMAGE或VIDEO模式却塞了result_callback，创建时会直接抛错，因为只有LIVE_STREAM模式才收回调。图像模式把回调删掉就行：

opts = vision.HandLandmarkerOptions(base_options=base, num_hands=2)

颜色通道画反了

画出来偏蓝、或detect报格式错，是因为 OpenCV 默认读进来是 BGR，而 MediaPipe 要 RGB，进任务前转一下通道：

img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)

性能调优 3 招 ⚡

1. 换轻量模型：移动端把hand_landmark_full.tflite换成hand_landmark_lite.tflite，推理更快、更省电。base = python.BaseOptions(model_asset_path='hand_landmark_lite.tflite')
2. 降输入分辨率：手一般占不了整张图，缩到 640×480 再喂，速度明显上来。img = cv2.resize(img, (640, 480))
3. 选对运行模式：实时摄像头用LIVE_STREAM+ 回调，别每帧同步等结果，延迟会低很多。

调完记得对比一下帧率再定稿，别凭感觉。

接下来可以玩什么 🧩

Hand Landmarker 只是 Tasks 家族的起手式，把返回的 21 个关键点接上 iOS 端的 MPPHandLandmarker，就能在 AR 交互、虚拟手势里用；再往上叠一层规则判断，还能做成手势识别。更多细节可以看 官方文档。

觉得这篇帮你省了时间的，点个赞收藏一下，遇到问题评论区见。

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