简介这是一个基于姿态估计技术的健身评分系统项目使用Python搭建面向对AI健身、动作分析感兴趣的开发者及科研人员。项目以举哑铃动作为例通过提取人体关键点、组合不同肢节、实时计算骨骼向量角并与标准动作比对从而对每个肢体部位给出评分并汇总总分帮助用户量化动作准确性。资源包为zip压缩格式共114个文件整体约225.1MB涵盖Python脚本、C扩展源码pafprocess、预训练模型pb/h5、演示视频及说明文档等便于直接运行与二次开发。目前已有42人学习下载。从中可获得完整的项目代码与模型文件理解姿态估计在动作评估中的落地流程也可参考其关键点提取、角度计算与评分逻辑迁移至其他健身动作或实时反馈场景是学习人工智能与体育应用相结合的实用资料。1. 健身评分系统把一个摄像头变成懂动作标准的 AI 教练健身房最贵的是教练但教练一次只能盯一个人。你刚做了三个深蹲塌腰了他没看见你卷腹脖子代偿他也未必每次都提醒。健身评分系统干的事就是用一个普通 RGB 摄像头实时捕捉你的骨骼关键点按动作标准算出分数再把“哪一节角度不对”反馈到屏幕或手机上。它解决的不是“你在不在动”而是“动得标不标准”。这套东西最早火起来是跟着姿态估计技术成熟起来的现在落地最多的地方是体测设备、智能镜、动作类 App 和健身房 AI 摄像头。实现上完全可以用 Python 走通核心库是开源姿态估计方案加一段评分规则代码不涉及自训练大模型普通后端工程师和有一定 Python 基础的学生就能动手做。先泼一盆冷水评分精度不会像裁判那样带主观审美但稳定性和客观性远高于人眼抽查。这篇笔记把我自己做这套系统时踩过的坑、参数和排错路径完整讲一遍。2. 技术选型原理为什么用 MediaPipe 而不是自训练动作识别模型2.1 姿态估计解决的是“关键点在哪”评分解决的是“关键点摆得对不对”整套评分系统只有两个环节。前一个环节是姿态估计也叫 Pose Estimation从一帧画面里找人的关节位置输出 33 个关键点的坐标后一个环节是评分把坐标换成角度再拿角度和标准动作的阈值比较综合出分数。这两个环节是解耦的姿态估计的结果不管你是深蹲还是推举它都只给坐标因此动作类型完全由评分层判断。MediaPipe Pose 是 Google 开源的单目姿态估计方案输入一张 RGB 图输出 33 个关键点每个点带三维坐标(x, y, z)和可见度。其中 x、y 是图像归一化坐标范围 01z 是以臀部中心为原点的深度估计值。对评分来说真正常用的是 x、y 和可见度z 只用来辅助判断身体朝向直接拿 z 算角度误差会很大。我选 MediaPipe 而不是自训练动作分类模型原因是评分这个场景对“是什么动作”敏感度低对“关节偏差量”敏感度高。自训练动作识别模型学的是时序特征输出一个动作类别比如“深蹲”或“卧推”但给不出“膝关节外翻了 12 度”这种量化数据。而评分系统的核心输出恰恰就是这类量化偏差规则引擎可以直接消费的关键点坐标远比黑盒分类结果可控。2.2 三个候选方案的取舍MediaPipe、OpenPose、MMPose先看 OpenPose。它在学术场景非常强输出的关键点更稳多人检测也更强但缺点明显模型文件大、依赖 CUDA、单帧推理在 CPU 上跑不快。健身评分这种面向普通摄像头的场景用户机器上大概率没有独立显卡百度到的各种 OpenPose 部署教程往往还要自己编译体验很差。再看 MMPose。它是 OpenMMLab 的姿态估计工具箱精度上限最高适合学术研究和需要微调的业务场景。代价是代码体系复杂需要理解配置文件、数据格式、训练流程对想快速验证“能不能做”的团队来说太重。MediaPipe Pose 的好处是模型小、CPU 上能跑实时、Python 包一条命令装完而且对遮挡和远景的鲁棒性足够好。代价是精度上限不如 OpenPose 和 MMPose但对“角度偏差 5 度以上”这种评分粒度来说完全够用。另外它自带 BlazePose 的模型架构针对移动端和网页端做过优化后面要移植到小程序或浏览器端也有现成方案。根据模型的复杂度参数MediaPipe 提供 0、1、2 三档在我的测试里 0 档 CPU 单帧大约 812ms1 档 1525ms2 档 30ms 以上评分系统选 1 档性价比最高选 0 档能获得更低延迟适合低配设备。2.3 系统架构定位逐帧坐标流不是视频片段分类这里要强调一个关键认知MediaPipe 是逐帧处理不是整段视频识别。你的完整管线是“读帧 → 关键点检测 → 角度计算 → 评分 → 叠加显示”每一帧独立完成打分。这意味着系统天然就是实时流式的不需要等动作结束才能出分。从工程架构看它很适合把关键点检测封装成独立服务上层业务只消费坐标数组。我做的时候是先把关键点坐标保存成 CSV离线调试评分规则再接入实时视频流整个调试周期缩短了一大截。如果你的目标是做一套产品建议第一版就用“坐标流 规则引擎”的架构别一上来就想着上 AI Agent 编排流程先把单一动作评分跑通再谈流程编排。3. 搭建最小可跑通系统环境、摄像头取流和关键点提取代码3.1 环境准备Python、OpenCV、MediaPipe 的版本搭配环境配置是新手最多翻车的地方先把版本说清楚。Python 用 3.9 到 3.11 之间任意一个版本都行不建议用 3.12 以上MediaPipe 的轮子对最新 Python 版本的支持会滞后。在 VSCode 或 PyCharm 里配置 Python 环境时记得给项目单独建虚拟环境别把包装进全局环境后面换项目会互相污染。安装命令如下conda create -n fitness python3.10 conda activate fitness pip install opencv-python mediapipe numpy如果下载慢可以给 pip 换国内镜像源。装完验证一下版本是否正常python -c import mediapipe as mp; print(mp.__version__)逻辑说明先把 Python 虚拟环境隔离出来是为了让后面安装的 opencv-python、mediapipe、numpy 三个包只服务于这个项目。mediapipe 自带解决方案 API不需要单独安装模型文件opencv-python 负责摄像头读取和图像显示numpy 用来快速做坐标运算和数组处理。参数说明Python 版本 3.10 是当前兼容性卡的比较紧的版本如果你用的是 3.11安装失败时先看点 3.10 重装opencv-python 不要装成 opencv-contrib-python后者体积大且有些版本与 mediapipe 依赖的 numpy 版本冲突。3.2 实时提取关键点的最小代码跑通摄像头再说别的下面这段代码是整套系统的地基打开摄像头检测人体关键点把骨头画到画面上。先把这一步跑通再做评分。import cv2 import mediapipe as mp mp_pose mp.solutions.pose pose mp_pose.Pose( model_complexity1, # 模型复杂度0/1/21 是精度和速度的平衡点 min_detection_confidence0.5, # 检测置信度阈值低于 0.5 会频繁丢失目标 min_tracking_confidence0.5 # 跟踪置信度阈值低于 0.3 时关键点会抖动 ) mp_draw mp.solutions.drawing_utils cap cv2.VideoCapture(0) cap.set(cv2.CAP_PROP_FRAME_WIDTH, 1280) cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 720) while True: ret, frame cap.read() if not ret: break frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results pose.process(frame_rgb) if results.pose_landmarks: mp_draw.draw_landmarks( frame, results.pose_landmarks, mp_pose.POSE_CONNECTIONS, mp_draw.DrawingSpec(color(0, 255, 0), thickness2, circle_radius2), mp_draw.DrawingSpec(color(0, 0, 255), thickness2) ) cv2.imshow(Fitness Pose, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()逻辑说明视频帧默认是 BGR 格式MediaPipe 要求 RGB 输入所以先用 cv2.cvtColor 转换。pose.process 返回的 results 里包含 pose_landmarks也就是 33 个关键点如果画面里没有人这个值是 None要做空值判断否则直接访问会报错。draw_landmarks 把关键点和连接线画回原始帧绿色圆点是关节点红色线是骨骼连接。这段代码跑通后你能在窗口里看到自己的骨架这说明姿态估计链路已经通了。参数说明model_complexity 是核心参数取值 0、1、2。0 档在低端 CPU 也能跑 30 帧以上但角度抖动略大1 档对大部分家用电脑无压力2 档适合离线分析视频不建议接到实时摄像头。min_detection_confidence 控制“首次检测”的严格程度值设得越高检测越严格但容易把大半个身体出画面的状态判成无人值设得越低误检越多。min_tracking_confidence 控制“上一帧跟踪到这一帧”的置信度跟踪模式下检测速度更快但如果画面快速运动跟踪会丢丢帧后系统会重新走一次完整检测。摄像头分辨率我建议设成 1280×720太高 MediaPipe 处理时间变长太低角度计算误差变大。3.3 坐标落盘到 CSV没有数据别谈调评分规则很多人跳过这一步直接写评分结果分数忽高忽低根本不知道是哪里的问题。正确做法是先录一段标准的深蹲视频把每一帧的 33 个关键点坐标全部保存下来离线分析。import csv import cv2 import mediapipe as mp mp_pose mp.solutions.pose pose mp_pose.Pose(model_complexity1) cap cv2.VideoCapture(squat.mp4) csv_file open(squat_landmarks.csv, w, newline) writer csv.writer(csv_file) # 写入表头帧号、关键点索引、x、y、可见度 writer.writerow([frame, landmark_idx, x, y, visibility]) frame_idx 0 while True: ret, frame cap.read() if not ret: break frame_rgb cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results pose.process(frame_rgb) if results.pose_landmarks: for idx, lm in enumerate(results.pose_landmarks.landmark): writer.writerow([frame_idx, idx, round(lm.x, 6), round(lm.y, 6), round(lm.visibility, 4)]) frame_idx 1 csv_file.close() cap.release()逻辑说明landmark 是一个长度为 33 的列表下标对应固定的人体位置比如 11 是左肩12 是右肩23 是左髋24 是右髋25 是左膝26 是右膝。把每一帧每个点的坐标和可见度写入 CSV后面做评分脚本时直接读取这个文件反复调整阈值不用一直开着摄像头实时调试。round 保留小数位数是为了减小文件体积角度计算用 6 位小数的坐标完全够。参数说明visibility 是关键它表示模型对这个关键点有多确定范围 01。低于 0.5 的关节坐标基本不可信。保存 CSV 时我会额外过滤一遍如果一个点的 visibility 低于 0.5就把这一帧的这个点标记成无效避免它在评分阶段拖垮整帧结果。这一步为你后面调试评分算法留了“后悔药”每个版本规则跑了什么数据都能回溯。4. 评分算法设计角度计算、阈值映射、平滑策略与反馈显示4.1 用余弦定理把三个关键点算成一个关节角度评分最基础的单位是角度。比如深蹲蹲多深看膝关节角度躯干有没有前倾看髋关节和肩关节的相对位置卷腹有没有脖子代偿看颈部和躯干的角度。角度求法用的是三点坐标的余弦定理已知关节 A、B、C 的坐标求以 B 为顶点的角 ABC。import math def calc_angle(a, b, c): 计算角度 ABC单位度 a、b、c 分别是三个关键点的 (x, y) 坐标 radians math.atan2(c[1] - b[1], c[0] - b[0]) - math.atan2(a[1] - b[1], a[0] - b[0]) angle abs(radians * 180.0 / math.pi) if angle 180.0: angle 360.0 - angle return angle # 示例深蹲时左膝关节角度 # 关键点 23 左髋、25 左膝、27 左踝 hip (landmarks[23].x, landmarks[23].y) knee (landmarks[25].x, landmarks[25].y) ankle (landmarks[27].x, landmarks[27].y) knee_angle calc_angle(hip, knee, ankle)逻辑说明atan2 求两个向量与 x 轴的夹角差再把弧度转成角度。abs 保证角度为正超过 180 度做一次镜像确保输出落在 0180 区间。这套公式只要三个点的坐标不重不漏就没有其他难度。参数说明坐标用归一化坐标(x, y)即可不需要转成像素坐标因为角度本身是比例不变的画面分辨率不影响结果。但要注意如果三个点里有任何一个的 visibility 低于 0.5这一帧的角度就是不可信的应该在进入评分前直接丢弃。4.2 深蹲评分规则阈值、分档和加权综合单关节角度算出来后下一步就是把角度映射成分数。我以深蹲为例把评分规则完整展开其他动作按同样思路套。深蹲主要看三个指标膝关节角度蹲的深度、躯干前倾角腰背是否挺直、髋关节角度屈髋是否充分。膝关节角度从站立位约 170 度蹲到最低点约 60 度角度越小说明蹲得越深。评分规则用分档映射而不是线性映射角度小于 90 度给满分90 到 120 度给 80 分120 到 150 度给 50 分超过 150 度说明根本没怎么下蹲直接 0 分。def score_knee_angle(angle_deg): 膝关节角度评分角度是膝盖处的屈曲角 if angle_deg 90: return 100 elif angle_deg 120: return 80 elif angle_deg 150: return 50 else: return 0 def score_torso_angle(torso_angle_deg): 躯干前倾角度评分角度是躯干与垂直方向的夹角 if torso_angle_deg 15: return 100 elif torso_angle_deg 30: return 70 elif torso_angle_deg 45: return 40 else: return 0 def overall_score(knee_score, torso_score, hip_score): 最终得分 膝关节 40% 躯干 30% 髋关节 30% return round(knee_score * 0.4 torso_score * 0.3 hip_score * 0.3, 1)逻辑说明分档映射的好处是打分行为可解释产品经理和健身教练能直接看懂规则。权重根据深蹲动作中各个关节的重要性分配膝关节是最关键的权重最高躯干和髋关节各占三成。调权重时用手头的 CSV 数据反复跑找一个能让“标准动作得 90 分以上、错误动作得 60 分以下”的权重组合。参数说明阈值会随动作变化深蹲的膝关节 90 度是标准深度硬拉看的是髋关节铰链膝关节角度只要不锁死就行阈值要重新标卷腹看的是颈椎和胸椎夹角阈值完全不一样。建议每个动作单独建一份阈值配置用 JSON 或 YAML 存别写死在代码里。4.3 时间维度平滑解决单帧噪声最有效的一招单帧角度噪声是这套系统最大的体验杀手。上一帧 85 分下一帧突然跳到 60 分再下一帧又回到 82 分用户会觉得这就是个坏产品。分数跳变的根源是 MediaPipe 关键点自身有微小抖动两个点相距很近时一点抖动就会让角度变化很大。平滑策略首选指数移动平均EMA既简单又有效class AngleSmoother: 对连续帧的角度做指数移动平均 def __init__(self, alpha0.3): self.alpha alpha self.smoothed None def update(self, new_angle, visibility_okTrue): if not visibility_ok: return self.smoothed if self.smoothed is None: self.smoothed new_angle else: self.smoothed self.alpha * new_angle (1 - self.alpha) * self.smoothed return self.smoothed逻辑说明alpha 表示新帧的权重值越大响应越快但越不平滑值越小曲线越平滑但延迟越大。我一般设 0.3也就是新帧只占三成权重剩下七成是历史值。这样分数不会因为一帧抖动大幅跳变。参数说明alpha 的调节要看你的目标帧率30 帧/秒的视频用 0.3 大约滞后 45 帧也就是 150ms 左右体感不明显如果你跑到 15 帧/秒建议把 alpha 降到 0.2因为帧率低的时候历史值更宝贵。visibility 异常时不要更新平滑值否则会把不可信数据混进来。4.4 实时反馈把分数和提示直接画到画面上评分最终要落到界面反馈。第一版不需要做花哨的 UI直接 OpenCV 把文字画在画面上后面再换 Web 或 App 前端。if results.pose_landmarks: knee_angle calc_angle(hip, knee, ankle) smoothed_knee smoother.update(knee_angle, visibility_ok) if smoothed_knee is not None: knee_score score_knee_angle(smoothed_knee) total_score overall_score(knee_score, torso_score, hip_score) cv2.putText( frame, fScore: {total_score}, (50, 80), cv2.FONT_HERSHEY_SIMPLEX, 2, (0, 255, 0), 4, cv2.LINE_AA ) if smoothed_knee 150: cv2.putText(frame, Too Shallow!, (50, 140), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 0, 255), 2, cv2.LINE_AA)逻辑说明先算角度再经过平滑器然后查表打分最后把人能读懂的分数和提示写到画面左上角。这里有个细节值得注意提示文案要具体不要写“动作错误”这种废话“蹲太浅了”用户才知道怎么改。参数说明字体大小和颜色按展示设备调投影仪和手机屏幕的显示比例差很多字号写死前先确认展示分辨率。实际产品中反馈至少要有三个层级数字分数、文字提示、声音提示声音提示在用户看不到屏幕时尤其重要比如 AirPods 连接状态下用 TTS 播报“再蹲深一点”体验会上一个台阶。5. 健身评分避坑五个我实际踩过的问题现象、原因与解法5.1 分数像过山车明明动作没变分数自己跳了二十分现象动作保持静止画面上的分数还在 70 和 90 之间来回跳录视频回放检查关键点骨架也在轻微晃动。原因单帧关键点存在固有抖动关节坐标有微小噪声。如果直接拿单帧角度打分噪声会被角度计算放大。尤其是当三个点接近直线时微小位移会让角度产生剧烈变化这就是所谓“180 度附近放大器”现象。解决先把角度接入平滑器再做评分映射。同时检查 min_tracking_confidence 是否设置过低低于 0.3 时关键点抖动会明显加重。如果平滑后依然跳把平滑器的 alpha 从 0.3 降到 0.2但要注意延迟会增大。这一招解决了我实验中最常见的分数不稳问题。5.2 左右关键点经常弄反深蹲变成“镜像深蹲”现象在屏幕前测试用户抬左手系统判定成抬右手深蹲时左膝外翻被检测成右膝内翻。原因MediaPipe 关键点的左右是相对人体的语义左右不是画面左右。如果摄像头是前置镜头画面默认是镜像的这时屏幕左边对应的是人体右边。评分如果不做一次左右交换映射所有单侧动作的判定都是反的。解决先确定你的展示是否做镜像。如果摄像头画面直接给用户看通常会做镜面翻转方便用户像照镜子一样调整动作此时评分逻辑要把关键点 11 和 12 互换、23 和 24 互换、25 和 26 互换、27 和 28 互换。最简单的方式是写一个左右交换函数在取坐标前统一处理如果直接用后置摄像头录屏画面不镜像就不用换。提前确认这一点能省掉大量返工。5.3 深色衣服加逆光人体直接“消失”了现象用户穿黑 T 恤身后是窗户逆光摄像头里姿势是标准的但系统提示未检测到人骨架时有时无。原因MediaPipe 的检测依赖图像对比度和纹理信号。纯深色衣服在低曝光环境下信号弱逆光环境下人脸和躯干部位过曝也会降低关键点可见度。解决min_detection_confidence 调低到 0.4 能缓解一部分但治标不治本。真正有效的是给用户明确的环境指引不要逆光站、穿浅色或紧身衣、摄像头略高于视线水平。在检测层加一个提示逻辑当 visibility 全部低于 0.5 且持续 2 秒时在画面上提示“请调整光线或位置”。这属于产品化问题不是算法问题但如果你没提前做用户会以为是评分系统坏了。5.4 侧面角度被遮挡一个人趴在地上做动作分数却很高现象瑜伽垫上的动作比如平板支撑和卷腹身体接近水平摄像头从正面拍时肩膀和髋部互相遮挡结果某个角度正好落在满分区分数虚高。原因关键点可见度低时模型会“猜测”位置经常猜得比较合理但实际上是错误的。评分逻辑没有对关键点可见度做强制校验把不可信的坐标当真了。解决在取坐标的统一入口加一道校验任意角度依赖的三个点里只要有一个点 visibility 低于 0.5就跳过这一帧不参与评分。不要用补点或插值的方式硬凑宁可少打一帧也不要输出错误分数。另外侧面相机位建议抬高到 1.2 米以上让躯干有更好的观测角。5.5 动作没做完分数就开始算了半蹲也拿到高分现象用户做深蹲刚下蹲到一半还没蹲到位就开始显示分数而且分数不低。原因评分逻辑没有状态机只要检测到人体就持续打分。半蹲状态下膝关节角度可能恰好在 120 度区间得了 50 分随后用户继续下蹲分数才慢慢涨上来。用户在屏幕上看到分数上涨会误以为自己做得越来越好其实只是蹲得越来越深。解决给每个动作加一个状态机分三个阶段预备姿态检测、动作开始触发、动作完成结算。深蹲以“膝关节角度连续 5 帧小于 100 度”作为动作到位标记到位后再出总分。这样不会在半路报高分也不会在用户还没蹲下去时就给 0 分。状态机的实现不复杂用一个全局变量记录当前阶段每帧判断是否满足切换条件即可。6. 验证评分结果与进阶调优用数据说服自己也说服用户6.1 录制带标注的验证集算误差均值和相关性评分系统上线前你要回答一个最基本的问题这个分数和教练的判断差多少。做法是找 10 个人每人录 3 组动作请一位健身教练对每帧动作的“标准度”打 110 分你的系统同时输出 0100 分归一化后算误差绝对值平均值和相关系数。实测中规则型和教练打分的相关系数通常在 0.75 以上就算可用低于 0.6 说明你的评分规则有严重漏项比如漏掉了膝盖内扣这个常见错误或躯干角度权重太低。6.2 模型复杂度三档的实测对比别盲目上高精度model_complexity单帧耗时(CPU)关键点抖动适用场景0812ms较大低配设备、流畅优先11525ms适中大多数家用电脑、推荐默认230ms更稳离线视频分析、精度优先这张表是我在普通笔记本上实测的经验值具体数字和 CPU 型号有关但趋势是准的。0 档速度快但角度抖动会加大2 档精度最高但接入实时摄像头时画面延迟能明显感觉到不适合做交互反馈。我一般默认设成 1因为评分系统要的是“稳”的实时输出不是离线追帧精度。如果你要部署到树莓派或 Jetson Nano 这类设备上建议直接降到 0同时把画面分辨率调到 640×480否则处理队列会堆积延迟越来越大。6.3 分数如何接入产品从 OpenCV 画字到 WebSocket 推送OpenCV 画字只能用于本地验证真实产品里分数要推给前端。最省事的方案是把关键点检测和评分封成一个类暴露 get_score(frame) 接口后端用 WebSocket 把分数和提示推给前端前端可以是小程序、Web 或 App。注意接口频率不要按每帧推按每秒 23 次推就足够前端播放 30 帧的流畅动画评分数值却低频更新这种设计既省带宽又避免数字跳动过快。如果想再进一步把多个动作的阈值配置抽成 JSON 文件后端通过接口热更新就不需要每次改评分规则重新发版。这就是把一套 OpenCV 脚本提升成可用产品的最小路径。我自己走过最大的弯路就是跳过 CSV 落盘直接调实时评分结果分数不稳时完全分不清是算法问题还是环境光线问题白白折腾了两天。后来老实先录数据、离线调参、再回接实时流一套流程跑顺后新动作的评分规则基本一天就能调完。希望这篇能让你把姿势检测到评分落地的整条链路走通少踩一点我踩过的坑。本文还有配套的精品资源点击获取