简介：面向计算机相关专业学生与机器学习初学者，这是一套基于MediaPipe实现手势数字识别的完整项目资源，包含Python源码和详细项目说明，覆盖从手部关键点提取、特征处理到数字分类的完整流程，适合用于课程设计、毕业设计或大作业实战。压缩包共2014个文件，其中1991个npy数据文件集中存放训练与测试所需的特征样本，另有3个py源文件负责核心代码，5个xml配置文件用于参数或管线配置，1个md说明文档详解实现思路与运行方式，整体仅11.64MB，数据与代码组织清晰、便于对照学习。读者可以通过阅读md快速理解MediaPipe手部关键点提取、数据组织与分类模型训练的衔接关系，再直接运行py源码观察实际识别效果。目前已有318人学习下载，对于希望在真实项目中熟悉手势识别流程、积累机器学习实战经验的学习者具有较高借鉴价值。
1. 为什么这个手势数字识别项目选 mediapipe：关键点比轮廓检测省一半的事
如果你第一次做手势数字识别，很容易照着老教程走一遍轮廓检测加凸包分析：背景一杂、光线一变、手稍微偏个角度就全线翻车。基于 mediapipe 实现手势数字识别，本质上是把问题从“图像检测”换成了“关键点分类”——mediapipe 直接给出手部 21 个关键点坐标，你不需要自己写分割、不需要算手指数量，只需要把这些关键点整理成特征，交给机器学习模型分出 0-9。对正在做课程项目、想练 cv 加机器学习完整流程、或者想快速做出交互原型的开发者来说，这是当前投入产出比最高的一条路。这篇文章按我实际做过的手势数字识别方案，把环境搭建、数据采集、模型训练、实时推理和踩坑记录一整套写给你。
2. 搭建环境与最小管线：用 mediapipe 提取手势 21 关键点的详细步骤
2.1 安装 mediapipe 与 opencv：先确认 python 版本再动手
常见做法是先创建一个干净的 python 环境，再装依赖。用手势数字识别项目最常用的一套组合是 mediapipe 加 opencv-python，训练部分加 scikit-learn，数据运算加 numpy。安装命令如下：
python -m pip install mediapipe opencv-python numpy scikit-learn这里有两个细节。第一，要用python -m pip而不是直接pip install，因为很多人的电脑里同时存在 python2 和 python3 的 pip，直接敲 pip 可能装进了错误的环境。第二，mediapipe 对 python 版本有要求，建议使用 3.8 到 3.11 之间的版本，不要一上来就装最新的 python 3.13，否则很可能会遇到没有对应轮子、编译失败或者 import 报错。
装完之后验证一下环境是否干净。打开终端执行python -c "import mediapipe; print(mediapipe.__version__)"，能打印出版本号就说明安装成功。如果报错，多半是 protobuf 或 numpy 版本冲突。我遇到这种情况一般会执行python -m pip install --upgrade mediapipe numpy重新拉一遍依赖，少数情况需要卸载重装 mediapipe。这些是安装阶段最常见的坑，没必要死磕，重装一次通常能解决。
2.2 第一段识别代码：从摄像头取帧打印 hand landmark 坐标
环境就绪后，先写一段最小代码跑通摄像头取流和关键点提取，确认 mediapipe 在你的机器上能正常工作，再往下做数据集和模型。
import cv2 import mediapipe as mp mp_hands = mp.solutions.hands mp_draw = mp.solutions.drawing_utils cap = cv2.VideoCapture(0) with mp_hands.Hands( static_image_mode=False, max_num_hands=1, min_detection_confidence=0.5, min_tracking_confidence=0.5) as hands: while cap.isOpened(): ret, frame = cap.read() if not ret: break # 自拍镜像：让画面和真实动作方向一致，方便调试 frame = cv2.flip(frame, 1) # mediapipe 的 process 接口吃 RGB，OpenCV 读出来是 BGR rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) result = hands.process(rgb) if result.multi_hand_landmarks: for hand_landmarks in result.multi_hand_landmarks: mp_draw.draw_landmarks( frame, hand_landmarks, mp_hands.HAND_CONNECTIONS) lm = hand_landmarks.landmark # 打印手腕点坐标，验证数据通路 print(lm[0].x, lm[0].y, lm[0].z) cv2.imshow("hand", frame) if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows()这段代码的逻辑分三步：OpenCV 读帧、mediapipe 提关键点、OpenCV 画出来。其中cv2.flip(frame, 1)是做水平镜像，摄像头正对着自己时画面左右是反的，镜像后手往右挥，画面里也往右，调试直觉好很多。cv2.cvtColor这一步很容易漏，mediapipe 的训练数据是 RGB，直接喂 BGR 帧虽然不会报错，但坐标会不准。
参数方面，static_image_mode=False表示使用视频流模式，mediapipe 会在帧间做跟踪，速度比逐帧检测快很多，适合实时场景。min_detection_confidence控制检测器的最低置信度，取值 0.5 是保守起点：调低到 0.4 更容易检测到手但误检也变多，调高到 0.7 更准确但手出画面再回来时会短暂丢失。min_tracking_confidence控制跟踪置信度，低于阈值会触发重新检测，一般保持默认 0.5 就好。
2.3 为什么是 21 点不是图像：关键点特征对数字识别意味着什么
mediapipe 的手部关键点模型输出 21 个点，编号固定，含义固定。下面是数字识别最常用到的几个关键点：
| 编号 | 位置 | 在数字识别中的作用 |
|---|---|---|
| 0 | 手腕 | 归一化基准点，所有坐标以它为原点 |
| 4 | 食指尖 | 判断 1、9、8 的关键 |
| 8 | 中指尖 | 判断 2、3、4 的关键 |
| 12 | 无名指尖 | 配合 8 判断三指、四指 |
| 16 | 小指尖 | 判断 6 的关键 |
| 20 | 食指根部 | 与 4 的距离反映食指弯曲程度 |
数字识别不关心图像本身长什么样，关心的是“哪几个指尖伸出来了”“手指弯了多少”。这些信息可以从关键点之间的相对距离和角度算出来。这就是为什么说关键点方案比轮廓检测省事：轮廓方案要做背景分割、找轮廓、算凸包、定位指尖谷底，每一步都可能因为光线或者背景翻车，而 mediapipe 把这一整套封装成黑匣子，你拿到的直接是稳定坐标。
有一点需要提醒：mediapipe 输出的 x、y 是相对图像宽高的 0 到 1 归一化坐标，不是像素坐标。这意味着手在画面左上角和右下角，原始坐标完全不同，训练出来的模型会把“位置”也学进去。这个问题留到下一章数据预处理部分专门解决，现在先记住：原始坐标不能直接拿来训练。
3. 自建手势数字数据集：采集、标注与归一化的一站式脚本
3.1 数字手势约定：先把 0-9 的定义写清楚再采数据
很多人做手势识别最隐蔽的坑是：数据还没采，手上动作已经不一致了。比如数字 0，有人用握拳，有人用 OK 手势；数字 7，有人用拇指食指中指捏合，有人用食指中指无名指并拢。训练时采集和推理时动作不同，模型精度直接崩掉。
所以第一个步骤不是写代码，是定一套明确的数字手势约定。我一般用下面这套：
| 数字 | 手势定义 | 说明 |
|---|---|---|
| 0 | 拇指与食指成环，其余三指自然伸开 | 比握拳更好识别，和 5 区分度高 |
| 1 | 食指伸直，其余手指握拳 | 指尖朝上，不要弯曲 |
| 2 | 食指和中指伸直成 V | 常见剪刀手 |
| 3 | 食指、中指、无名指伸直 | 小指和拇指自然弯曲 |
| 4 | 食指、中指、无名指、小指伸直 | 拇指内扣或外展均可 |
| 5 | 五指全部张开 | 手指间适当分开 |
| 6 | 拇指和小指伸直，其余弯曲 | 常见打电话手势 |
| 7 | 拇指、食指、中指三指捏合 | 指尖聚拢成一撮 |
| 8 | 拇指和食指张开成枪形 | 其余三指弯曲 |
| 9 | 食指弯曲成钩状，其余握拳 | 或者用拇指食指成环但拇指在上 |
注意：这套约定不是标准答案，关键是“训练和推理用同一套动作”。你自己定义一套完全没问题，但要把约定表写进项目说明里，不然过两周自己都忘了当时怎么比的。
3.2 采集脚本：按数字键采集并保存 CSV
约定确定后写采集脚本。思路很简单：摄像头实时跑 mediapipe，检测到手就把 21 个点的 x、y 坐标（共 42 个数值）写进 CSV，最后一列是标签。你按下键盘数字键 1 到 9、0，程序就把当前帧的关键点存成对应类别的样本。
import csv import cv2 import mediapipe as mp LABELS = {'0': 0, '1': 1, '2': 2, '3': 3, '4': 4, '5': 5, '6': 6, '7': 7, '8': 8, '9': 9} save_path = 'gesture_data.csv' f = open(save_path, 'w', newline='') writer = csv.writer(f) mp_hands = mp.solutions.hands cap = cv2.VideoCapture(0) num_per_class = 200 # 每类至少采 200 个样本 with mp_hands.Hands( static_image_mode=True, max_num_hands=1, min_detection_confidence=0.6) as hands: collected = {k: 0 for k in LABELS} while cap.isOpened(): ret, frame = cap.read() if not ret: break frame = cv2.flip(frame, 1) rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) result = hands.process(rgb) if result.multi_hand_landmarks: lm = result.multi_hand_landmarks[0].landmark pts = [] for p in lm: pts.extend([p.x, p.y]) cv2.putText(frame, "counts: " + str(collected), (10, 30), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2) key = cv2.waitKey(1) & 0xFF label_char = chr(key) if key < 256 else '' if label_char in LABELS: label = LABELS[label_char] writer.writerow(pts + [label]) collected[label_char] += 1 print(f'label {label}: {collected[label_char]}/{num_per_class}') else: key = cv2.waitKey(1) & 0xFF if key == ord('q'): break cv2.imshow('collect', frame) if all(v >= num_per_class for v in collected.values()): print('done') break cap.release() cv2.destroyAllWindows()这里几个参数值得说清楚。static_image_mode=True表示每一帧都走完整检测，不用跟踪模式，采集阶段不需要速度，反而需要每次检测稳定独立。min_detection_confidence=0.6比上一章的 0.5 稍高，宁可漏掉几帧也不要存进去一堆低置信度脏样本。num_per_class=200是我建议的最少样本量，低于 100 模型很容易过拟合，高于 500 边际收益明显下降。
采集时的动作习惯直接影响数据质量。手要放在画面中央偏下一点，不要超出边缘；每次按键采样时手不要快速移动，静止一拍；同一个数字换几种角度来几组，比如手掌稍微内偏、外偏。这样模型泛化能力会好很多。
3.3 位移与尺度归一化：让模型不再依赖手在画面的位置
CSV 里的原始坐标不能直接训练，原因前文已经提到了：坐标是相对图像宽高的 0 到 1 值，手在画面不同位置、离摄像头远近不同，都会让同一手势的坐标分布完全不同。这时就要做归一化，是机器学习中的数据处理最典型的一步。
import numpy as np def normalize_landmarks(lm): # 输入 lm: shape (21, 2)，已经取出的 21 点 x,y 坐标 lm = np.array(lm, dtype=np.float32) wrist = lm[0] # 手腕点作为原点 diff = lm - wrist # 所有点相对手腕的偏移 scale = np.linalg.norm(lm[9] - wrist) # 中指根部到手腕的距离 return diff / scale这套归一化分两步。第一步，把所有坐标减去手腕点坐标，消除位置影响——手在画面左上角和右下角，归一化后坐标相同。第二步，除以中指根部到手腕的距离，消除尺度影响——手离摄像头近时整体坐标偏大，离得远时偏小，除以这个距离后两种情况下指尖相对位置可比。选第 9 点（中指根部）做尺度基准是因为它到手腕的距离在大多数手势中变化不大，而且不像指尖那样容易弯曲变形。
训练和推理必须使用同一套归一化逻辑。我见过太多人训练时做了归一化，推理时忘了，结果模型精度从 95% 掉到 50% 还找不到原因。建议把归一化写成一个独立函数，采集、训练、推理三个环节都调用同一个函数，从源头杜绝这件事。
4. 训练与实时推理：随机森林与 MLP 的取舍，跑通 0-9 识别
4.1 模型选型：为什么先选随机森林而不是深度学习
到这一步，你已经有了一个形状为 (N, 42) 的特征矩阵和对应的标签，接下来要选机器学习模型。标准的机器学习应用流程是：特征提取、数据预处理、模型训练、评估、推理。这个项目的特征维度只有 42 维，类别只有 10 个，样本量通常在几千的量级，用深度学习属于杀鸡用牛刀。
| 模型 | 数据量要求 | 训练速度 | 实时推理 | 调参难度 |
|---|---|---|---|---|
| 随机森林 | 几百样本即可 | 快 | 极快 | 几乎不用调 |
| MLPClassifier | 千样本起步 | 快 | 极快 | 需要调网络层数和迭代次数 |
| CNN/LSTM | 上万样本 | 慢 | 有压力 | 高 |
实际项目里我最常用随机森林起步，因为它对特征维度和样本量的要求很低，训练快、背书少、调参空间小，出结果非常快。如果你想要稍微连续一点的分类边界，用 scikit-learn 的 MLPClassifier 也完全可以，两者在这个任务上的准确率差距一般不超过 2 个百分点。真正拉开精度差距的不是模型选择，而是数据质量和归一化是否做对。
4.2 训练脚本与参数：从 CSV 到可保存的模型文件
训练脚本把三件事串起来：读取 CSV、归一化、交叉验证并保存模型。
import csv import numpy as np from sklearn.ensemble import RandomForestClassifier from sklearn.model_selection import cross_val_score import joblib def load_csv(path): rows = [] with open(path, 'r') as f: reader = csv.reader(f) for r in reader: rows.append([float(v) for v in r]) data = np.array(rows) X = data[:, :42].reshape(-1, 21, 2) # 42 列还原成 21 个二维点 y = data[:, 42].astype(int) # 最后一列是标签 wrist = X[:, 0, :] X_rel = X - wrist[:, None, :] # 平移归一化 scale = np.linalg.norm(X_rel[:, 9, :], axis=1) X_norm = X_rel / scale[:, None, None] # 尺度归一化 return X_norm.reshape(-1, 42), y X, y = load_csv('gesture_data.csv') print('样本分布:', np.bincount(y)) clf = RandomForestClassifier( n_estimators=300, min_samples_leaf=1, random_state=42, n_jobs=-1) print('5折交叉验证准确率:', cross_val_score(clf, X, y, cv=5).mean()) clf.fit(X, y) joblib.dump(clf, 'gesture_rf.pkl')几个参数的调法要说明。n_estimators=300是随机森林里的树数量，300 棵足够收敛，加到 1000 准确率提升很有限但模型文件体积会变大许多。min_samples_leaf=1是叶子节点最少样本数，默认 1 在数据量大时会过拟合，如果你发现训练准确率很高而交叉验证准确率掉很多，把这个值调到 2 或 4 会有改善。n_jobs=-1让所有 CPU 核并行训练，小数据集上差距不明显，但样本上万时能省下大量时间。
交叉验证用的是简单 5 折，但有个隐患：采集数据时每类样本是连续按出来的，时序上高度相关，同一手势的连续帧可能同时落在训练集和验证集里，导致交叉验证分数虚高。想更可靠一点，可以在采集脚本里做成每类轮换采样，或者用StratifiedKFold(shuffle=True)先把数据打乱再划分。
4.3 实时推理 demo：把模型接回摄像头输出数字
训练完会得到一个gesture_rf.pkl文件，推理代码就是把采集脚本中的“保存坐标”替换成“预测并显示”。
import cv2 import mediapipe as mp import joblib import numpy as np clf = joblib.load('gesture_rf.pkl') mp_hands = mp.solutions.hands mp_draw = mp.solutions.drawing_utils cap = cv2.VideoCapture(0) with mp_hands.Hands( static_image_mode=False, max_num_hands=1, min_detection_confidence=0.5, min_tracking_confidence=0.5) as hands: while True: ret, frame = cap.read() if not ret: break frame = cv2.flip(frame, 1) rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) result = hands.process(rgb) if result.multi_hand_landmarks: lm = result.multi_hand_landmarks[0].landmark pts = np.array([[p.x, p.y] for p in lm]) pts = pts - pts[0] # 平移 pts = pts / np.linalg.norm(pts[9]) # 尺度 pred = clf.predict(pts.reshape(1, -1))[0] cv2.putText(frame, f'num: {pred}', (20, 60), cv2.FONT_HERSHEY_SIMPLEX, 2, (0, 255, 0), 3) mp_draw.draw_landmarks( frame, result.multi_hand_landmarks[0], mp_hands.HAND_CONNECTIONS) cv2.imshow('recognition', frame) if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release() cv2.destroyAllWindows()推理部分的归一化和训练脚本保持完全一致：减去手腕点、除以第 9 点到手腕的距离。这里再次强调，训练和推理不一致是这类项目里最隐蔽的翻车点。如果你发现模型在自己摄像头下准确率奇低，优先检查推理代码里的归一化步骤是不是和训练时一模一样。
5. 避坑清单：手势数字识别项目中最常见的五个翻车现场
5.1 数字 0 和 5、6 和 7 总混淆：约定不一致比模型不行更常见
现象：自己测试其他数字都对，只有 0 经常识别成 5，6 和 7 互相串。原因：如果约定里 0 是握拳，那么握拳姿态下指尖弯曲，mediapipe 检测到的关键点实际落在手掌表面，和五指张开的 5 相比，只有手指间距的差别，特征边界很薄。解决方法是把 0 的约定改成拇指和食指成环的 OK 手势，环形的关键点分布和 5 的张开状态差异非常大，识别稳定性立刻上一个台阶。6 和 7 混淆通常是因为动作幅度太小，拇指小指伸出不够明确，采集时把动作做夸张，比如 6 的小指和拇指尽力向外张开，不要含在掌心里。
5.2 实时推理卡顿、掉帧：瓶颈在摄像头读取和绘制
现象：摄像头画面明显发卡，识别延迟接近半秒。原因：很多人以为是模型太慢，其实是 mediapipe 检测、OpenCV 读取和画面绘制全挤在同一帧的主线程里，cv2.waitKey(1)又限制了帧循环速度。解决思路是降分辨率加隔帧处理：把摄像头分辨率调到 640×480，每两帧取一帧做识别，中间帧直接画上一次的检测结果。另一个有效手段是把static_image_mode保持在 False，让 mediapipe 在帧间走跟踪而不是重新检测，能省掉大量计算量。模型本身在 CPU 上单次推理不到 1 毫秒，根本不构成瓶颈。
5.3 换个人、换个背景就不准：采集数据太“干净”了
现象：自己一个人测准确率 95% 以上，换同事测直接掉到 60%。原因：采集是在固定光线、固定背景、固定手型下完成的，模型学到的不仅是手型，还包括了肤色、光照、手大小的分布。解决的办法是采集阶段就引入多样性：至少找三个人各采一部分，分别在白天和晚上采两轮，每个人的手型都不一样，模型被迫去学真正区分数字的特征。还有一个常见增强手段是手部翻转，但注意不能直接对关键点做水平翻转——左右手交换后关键点的对应关系也变了，不加映射的翻转只会让模型学到错误信息。
5.4 mediapipe 首次运行要下载模型，离线环境直接报错
现象：第一次运行时一切正常，第二次在没网环境运行，程序卡在hands.process然后报错退出。原因：mediapipe 的 Hands 接口在第一次实例化时会从官方仓库下载手部关键点模型文件，下载成功后缓存到本地目录。离线环境下模型文件不存在就会直接失败。解决方法是联网状态下先跑通一次程序，把模型缓存到本地，部署到离线机器时把这部分缓存文件一起带上。另外，mediapipe 2.x 换了新的 tasks API，初始化写法完全不一样，如果你拿到的压缩包里的代码是旧版写法而安装的 mediapipe 是新版，运行会直接报错找不到solutions.hands，这时候去查对应版本的官方样例，照着改初始化部分即可。
5.5 多只手同时出现或手出画面边缘：关键点能拿到但输出乱跳
现象：一只手正常识别，另一只手从画面边缘伸进来时，识别结果在两个数字之间疯狂横跳。原因：max_num_hands=1参数只是限制了最多检测一只手的模型输出上限，但多只手同时出现时 mediapipe 会返回置信度最高的那只，置信度可能在两只手之间反复横跳，导致每帧取到的关键点来源不一致。解决方法是固定只用画面中心区域的手：检测到多只手时，选离画面中心最近的那只进行识别，另一只直接忽略。手出画面边缘时关键点会被截断，坐标不可信，这种情况直接丢弃这一帧，宁可不识别也不要输出错误结果。
6. 进阶：多帧投票与关键点平滑，把实时识别精度再稳定一档
单帧识别做到 90% 很容易，要做到 98% 以上，就得在时序上下功夫。先看两个小技巧。
from collections import deque, Counter import numpy as np class EMAFilter: """指数移动平均，平滑关键点坐标，抑制逐帧抖动""" def __init__(self, alpha=0.7): self.alpha = alpha self.old = None def __call__(self, pts): if self.old is None: self.old = pts else: self.old = self.alpha * pts + (1 - self.alpha) * self.old return self.old class VoteFilter: """近 N 帧多数投票，输出稳定类别""" def __init__(self, window=5): self.buf = deque(maxlen=window) def __call__(self, cls): self.buf.append(cls) return Counter(self.buf).most_common(1)[0][0]EMA 平滑的作用对象是关键点坐标。把上一帧的关键点坐标和当前帧按比例混合，alpha=0.7表示当前帧占 70%，历史占 30%。alpha 太大会让手部动作显得迟钝，太小起不到平滑效果，0.6 到 0.9 之间是安全区。平滑后的坐标再进分类器，预测结果就不容易因为一两帧的关键点抖动而跳变。投票过滤器作用于类别输出，连续 5 帧中出现次数最多的数字作为最终结果，窗口越大越稳定但延迟越高，实时场景建议用 3 到 5 帧。
验证方法上，我不建议对着摄像头反复挥手，自己觉得准但量化不了。更好的做法是录一段 30 秒的视频，每帧标注真实数字，然后离线跑推理脚本计算逐帧准确率和混淆矩阵，这样才能定位到底是哪两个数字在互相打架。做完这两步平滑，再动手去优化数据分布，效果通常比换模型更明显。
我做这个项目最大的教训是：花了大量时间调模型参数，结果发现是采集时 0 的约定前后不一致，脏数据占到三成，任何调参都救不回来。希望你上手时先把数字手势约定写死在项目说明里，再开始采集，能省掉后面一整轮的返工。希望帮到你。
本文还有配套的精品资源，点击获取
