简介：面向智能医疗、养老监护与计算机视觉初学者，这份资源是一套完整的跌倒检测实战项目，基于Mediapipe提取人体3D骨架关键点，并使用KNN算法对姿态进行分类，判断是否发生跌倒。源码共9个文件，包含3个Python脚本（模型训练、姿态估计与KNN推理）、2个CSV数据集、1个joblib模型文件、演示视频与动图，以及说明文档，整体压缩包仅7.98MB，结构清晰，便于快速上手和二次开发。项目覆盖Mediapipe模型加载、关键点解析、数据预处理、KNN参数调整与结果可视化等完整流程；通过阅读源码可掌握骨骼关键点提取与分类算法结合的实现思路，在智能监护场景中具备较强的参考价值。目前该资源已有259人学习，适合需要从零构建跌倒检测原型或深入研究人体姿态识别应用的开发者。
1. 跌倒检测为什么值得做：Mediapipe 3D 骨架加 KNN 的轻量落地组合
独居老人夜里起夜滑倒，没人及时发现，后果很严重。这类场景需要的不是录像回放，而是自动判断「人是否已跌倒」并立刻告警的系统。用 Mediapipe 从单目摄像头提取人体 3D 骨架，再用 KNN 算法对骨架特征分类，是低成本做跌倒检测最常见的组合，也是这个标题的核心。
比端到端视频分类模型，这个组合有两个实在的好处：Mediapipe 开源跨平台，普通摄像头就能拿 3D 骨架，不用额外买深度相机；KNN 训练成本低，几十条标注样本就能跑出可用的分类器，误检时也能反查是哪类特征错了。它适合独居老人监护、病房看护、工地安全监测等想快速上线的场景，但边界也明显：KNN 对样本分布敏感，换机位、换人、换光线，准确率都会往下掉。
这篇笔记把 Mediapipe 骨架提取、特征设计、KNN 训练到排错的完整路径讲清楚，照着做能跑通，跑完也知道坑在哪。
2. 方案选型：为什么是 Mediapipe 3D 骨架 + KNN，而不是端到端 CNN
2.1 Mediapipe 在骨架检测上的定位：3D 关键点不是黑匣子
Mediapipe Pose 是 Google 开源的人体姿态估计模块，从单帧图像里给出 33 个关键点，每个关键点带归一化的 x、y 像素坐标、z 深度值和 visibility 置信度。说它是「3D 骨架」，指的就是它额外推断出了深度信息，这个深度是相对摄像机位置的估值，精度比不上深度相机，但在跌倒检测这种「位置变化剧烈、方向大致确定」的场景里足够用。
我一般把 Mediapipe 的输出分成两类来用。一是pose_landmarks，坐标相对图像尺寸归一化，适合画框、画点做可视化；二是pose_world_landmarks，坐标以骨盆中心为原点的 3D 相机坐标系，x、y、z 三个维度不再受画面尺寸影响，更适合算速度、角度和高度变化。跌倒检测的特征，尽量从world_landmarks上取，不要拿画面坐标直接算，否则人的远近一变，特征就失真。
刚接触时容易把 Mediapipe 当成「识别是否跌倒」的黑匣子，实际上它只负责把人体简化成 33 个点，怎么判断是模型之外的事。这恰好是这个方案的优势：骨架出来后，你可以自己定义「什么算跌倒」。骨盆高度骤降、躯干角度接近水平、倒地后位移变小，这三个条件都能写进逻辑里，而不是像端到端 CNN 那样，模型内部判断完你也说不清。
2.2 KNN 参与分类的理由：小样本、可解释、部署成本低
KNN（K 近邻）算法的核心是：一条未知样本去和训练集所有样本比距离，取距离最近的 K 条，投票决定类别。它没有显式训练过程，没有反向传播和训练轮数，本质上是在样本空间里做最朴素的近邻判断。用在跌倒检测上，它正好和 Mediapipe 互补。
第一，跌倒样本天然难收集。真实跌倒图像很难大批量标注，而 KNN 在小样本下表现相对稳定；第二，可解释性强。某次误检，可以把误判样本的 K 个近邻调出来，看到底是算成了「弯腰捡东西」还是「蹲下」，就知道该补什么样本；第三，推理成本低。骨架特征只有几十维，一个 KNN 分类器在树莓派级别的设备上也能实时跑，不需要 GPU。真正的问题在特征：KNN 把所有希望寄托在距离上，两条样本在特征空间里挨得近就认为行为相同。这就要求喂给它的特征向量必须能区分跌倒和弯腰、蹲下、坐下这些干扰动作，否则特征不辨，K 值调得再细也白搭。
2.3 这个组合的边界：什么场景不建议用
不是所有跌倒检测都适合这个方案。如果摄像头装在墙角，人的躯干经常被桌子、床沿遮挡，Mediapipe 关键点置信度会大幅下降，骨架断断续续，后面所有特征都失真；如果要求遮挡条件下的高召回率，或者要区分「晕倒但没倒」「靠墙慢慢滑坐」这类模糊行为，KNN 在特征层面很难分，建议直接换基于视频序列的时序模型或者毫米波雷达方案。
另一个边界是视角。这个组合最舒服的视角是侧面或斜侧方，能看到完整人像；正上方俯视时 Mediapipe 对人体估计会变差，因为俯瞰时关键点遮挡严重。架设摄像头尽量让躯干在画面里占足够比例，成年人大概占画面高度的三分之一到一半。远距离小目标会频繁低于置信度阈值，误检率也会跟着往上走。
2.4 骨架方案对比：Mediapipe、OpenPose 与 MMPose 的取舍
| 方案 | 输出 | 部署成本 | 适合场景 |
|---|---|---|---|
| Mediapipe Pose | 33 点 3D 坐标 + 置信度 | CPU 可实时，跨平台 | 快速落地、嵌入式、实时告警 |
| OpenPose | 25/135 点，2D 为主 | 依赖 Caffe，计算量大 | 实验室离线分析 |
| MMPose / RTMPose | 2D 关键点，精度高 | 需 GPU，可自训练 | 换视角换人频繁、追求精度 |
总结一句话：要快速跑通且设备一般，选 Mediapipe；要刷准确率且有 GPU，考虑 RTMPose；不要为了「看起来专业」上 OpenPose，骨架更新率一掉，后面 KNN 全受影响。Mediapipe 对 OpenCV 视频流有官方接口，读摄像头、读视频文件、读图片都统一成帧处理，代码不用为视频格式专门分叉。
3. 跑通源码与 3D 骨架提取：mediapipe 安装的关键步骤与最小代码
3.1 mediapipe 安装的版本雷区与最小验证命令
拿到项目源码，解压后常见模块划分是数据采集、特征提取、KNN 训练、实时检测四部分。在跑这些代码之前，先把环境钉死。我一般用 conda 创建干净虚拟环境，Python 版本选 3.9：
conda create -n fall python=3.9 -y conda activate fall pip install "mediapipe>=0.10,<1.0" "numpy<2.0" opencv-python scikit-learn这里第一个坑就是依赖冲突。mediapipe 对 protobuf、opencv 有版本约束，最容易遇到的是 protobuf 版本冲突或 numpy 2.x 不兼容。把 mediapipe 限制在 0.10 到 1.0 之间，是因为这个区间内solutions接口最稳定，开箱即用的 Pose 模块能直接调用。装完用一条命令验证：
python -c "import mediapipe as mp; print(mp.__version__); print(mp.solutions.pose)"如果不报错，说明基础环境通了。若提示缺少 libGL.so.1，在 Debian 系执行apt install libgl1 libglib2.0-0；Windows 上一般不会缺，但要确认 Python 是 64 位。参数说明：fall是环境名可自改；四个包分别是姿态估计、数值计算、视频读取、KNN 训练必需的；numpy 固定到 2.0 以下是为了避开 mediapipe 旧 wheel 的兼容问题。
提示：遇到 protobuf 报错时，优先查 mediapipe 对应的 protobuf 版本约束，不要单独把 protobuf 升到最新版。
3.2 用 Mediapipe 提取 3D 骨架：最小可运行代码
环境就绪后，用一段最小代码从摄像头读取画面并输出 33 个关键点的 3D 坐标：
import cv2 import mediapipe as mp mp_pose = mp.solutions.pose pose = mp_pose.Pose( static_image_mode=False, model_complexity=1, smooth_landmarks=True, min_detection_confidence=0.5, min_tracking_confidence=0.5, ) cap = cv2.VideoCapture(0) while cap.isOpened(): ret, frame = cap.read() if not ret: break frame = cv2.resize(frame, (640, int(frame.shape[0] * 640 / frame.shape[1]))) rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) results = pose.process(rgb) if results.pose_world_landmarks: lm = results.pose_world_landmarks.landmark # 0 鼻子, 11/12 左右肩, 23/24 左右髋, 25/26 左右膝, 27/28 左右踝 print(f"nose: {lm[0].x:.3f}, {lm[0].y:.3f}, {lm[0].z:.3f}") print(f"left_hip: {lm[23].x:.3f}, {lm[23].y:.3f}, {lm[23].z:.3f}") if cv2.waitKey(1) & 0xFF == ord('q'): break cap.release()逻辑说明：先用 cv2 读一帧，缩到宽度 640 后再进 Mediapipe，压缩不是为了省显存，是让单帧推理时间稳定。cv2 默认读进来是 BGR，必须转成 RGB，否则骨架会错位，这是新手最容易翻车的一步。results.pose_world_landmarks给的是以骨盆为原点的 3D 坐标，打印鼻子和左髋的坐标，确认 z 值有变化，说明 3D 通道通了。不同版本的坐标轴方向可能不同，以打印值为准，不要背死轴方向。
参数说明：static_image_mode=False表示视频流模式，会启用跟踪优化让连续帧更平滑；model_complexity有 0/1/2 三档，0 最快但角度抖动明显，2 最稳但 CPU 上很难实时，日常折中选 1；smooth_landmarks=True做时间平滑，对跌倒这种突发动作影响不大；两个 confidence 都设 0.5 是常用起始值，误检多就往上调，丢帧多就往下调。Debug 阶段把坐标打印出来，眼见为实。
3.3 骨架输出的数据结构与坐标说明
理解 33 个关键点怎么组织，后面特征设计才不虚。每个 Landmark 对象是五元组：x、y、z、visibility、presence。pose_world_landmarks的 x/y/z 是世界坐标，以骨盆为原点，单位是米量级的相对值，不是像素；visibility 是关键点可见性置信度，范围 0 到 1，低于 0.5 的点基本不可信，采样本时应该直接丢掉。常用关键点编号列一张表，写特征时直接查：
| 关键点 | 编号 | 用途 |
|---|---|---|
| 鼻 | 0 | 头部位置参考 |
| 左/右肩 | 11/12 | 躯干上端 |
| 左/右髋 | 23/24 | 躯干下端、重心参考 |
| 左/右膝 | 25/26 | 腿部弯曲程度 |
| 左/右踝 | 27/28 | 脚是否离地 |
| 左/右肘 | 13/14 | 手臂动作 |
需要注意，像素坐标系里 y 向下，但 world 坐标系的 y 轴是向上的。很多人在算「骨盆高度」时把两者搞反，导致高度下降被算成上升。我习惯统一用 world 坐标，定义「骨盆中心 = (left_hip + right_hip) / 2」，摔倒时骨盆中心 y 值会快速下降，这个符号方向在代码注释里写清楚，避免三个月后自己都看不懂。采集阶段，建议把每帧的骨盆中心、肩中心、角度存成轻量结构，比如 CSV 或内存列表，后面滑窗特征和 KNN 训练样本都依赖这段序列，而不是单帧判断。滑窗的意思就是取最近 N 帧的组合特征，跌倒是一个持续 0.5 到 1.5 秒的过程，单帧姿态再典型也不能代表行为过程。
4. 跌倒识别的特征设计：从 3D 关键点序列到 KNN 能用的向量
4.1 特征选项：重心高度、躯干角度与速度变化
跌倒过程最显著的变化有三个：重心突然降低、躯干从竖直变成接近水平、倒地后身体基本静止。围绕这三个变化，我常用的特征有四类，只依赖上面那些关键点：
- 重心高度：取骨盆中心 y 的世界坐标，跌倒时在滑窗内快速下降。用变化量而不是绝对高度，避免镜头远近的影响。
- 躯干角度：向量（肩中心 → 骨盆中心）与竖直方向的夹角。站立时接近 0°，跌倒时接近 90°，弯腰捡东西通常在 30° 到 60° 之间。这是区分「跌倒」和「弯腰」最核心的一维。
- 垂直速度：窗口内骨盆中心 y 的帧间变化率，摔倒瞬间速度会突然放大，普通坐下不会。
- 静止度：窗口末尾若干帧骨盆中心的位移方差。真正跌倒后，人多数时间躺着不动；蹲下又站起，方差不会一直压得很低。
这些特征合起来正好覆盖「跌得快、倒得平、倒后不动」。特征不是越多越好，KNN 在维度高时容易受无关维度干扰，四到六维一般够用。若只取一维，比如只看重心高度，从床上滑坐到地上也会被误判为跌倒。躯干角的计算代码很短，注意用 3D 向量而不是只靠 y 值：
import numpy as np def torso_angle(shoulder, hip): vertical = np.array([0.0, 1.0, 0.0]) vec = np.array(hip) - np.array(shoulder) cos = np.dot(vec, vertical) / (np.linalg.norm(vec) + 1e-6) return float(np.degrees(np.arccos(np.clip(cos, -1.0, 1.0))))逻辑说明：这里假设世界坐标 y 向上，如果打印出的坐标方向相反，把vertical改成[0, -1, 0]。用 3D 向量算角度，对侧对摄像头的情况更鲁棒，2D 投影在侧面视角下会把角度算偏。clip把余弦值限制在 [-1, 1]，避免浮点误差造成 arccos 报错。
4.2 滑窗与骨架序列切片：怎么把连续帧变成一条样本
实时检测时每帧都会来一组关键点，但跌倒是一个过程。我一般维护一个长度 30 到 45 帧的环形缓冲（对应 1 到 1.5 秒 @30fps），每次滑入新帧、弹出旧帧，然后对窗口提取特征向量：
import numpy as np def extract_window_features(window_frames, fps=30): """window_frames: list[dict]，每个 dict 含 pelvis_y, pelvis_x, torso_angle""" ys = np.array([f['pelvis_y'] for f in window_frames]) xs = np.array([f['pelvis_x'] for f in window_frames]) angles = np.array([f['torso_angle'] for f in window_frames]) y0 = ys[0] y_min = ys.min() drop_ratio = (y0 - y_min) / (abs(y0) + 1e-6) # 重心高度下降比例 angle_max = angles.max() # 最大倾斜角（度） velocity = np.mean(np.abs(np.diff(ys))) * fps # 平均垂直速度 still_var = np.var(ys[-5:]) + np.var(xs[-5:]) # 末尾静止度 return np.array([drop_ratio, angle_max, velocity, still_var])逻辑说明：window_frames是最近 N 帧的关键点字典列表，每帧只存骨盆中心 y、骨盆中心 x、躯干角度三个量。drop_ratio用相对变化而不是绝对值，避免不同身高、不同距离的人量纲不一致；angle_max取窗口内最大角度，跌倒瞬间角度会冲高；velocity把平均帧间差乘 fps 换成每秒变化量，让不同帧率采集的数据可比；still_var取窗口最后 5 帧的位移方差，捕捉「倒地后静止」。
参数说明：窗口长度 30 帧 @30fps 对应 1 秒，适合快速跌倒；如果场景有慢速滑坐等动作，可以加长到 45 帧，但延迟同步增加到 1.5 秒左右，实时性要求高的场景要权衡。fps 参数必须传实际帧率，否则 velocity 特征在不同设备间不可比。这段代码可以实时循环调用，也可以离线读视频时对整个时间轴做滑窗，生成监督训练数据。
4.3 特征归一化：为什么这步不做 KNN 就白训
KNN 用距离度量相似度，而四个特征量纲差异巨大：drop_ratio 是 0 到 1 的小数，angle_max 是 0 到 90 的角度，velocity 可能是每秒几米的量级。不归一化的话，angle_max 和 velocity 会在欧氏距离里占绝对主导，drop_ratio 的作用被淹没。常见做法是标准化，让每个特征均值为 0、方差为 1：
from sklearn.preprocessing import StandardScaler scaler = StandardScaler() X_scaled = scaler.fit_transform(X_train) # X_train: (样本数, 4)逻辑说明：fit_transform只在训练集上执行一次，得到每个特征的均值和方差；之后实时推理和验证时，对每一条新样本只调用scaler.transform，不能重新 fit，否则会把测试集信息泄露到模型里，导致验证指标虚高。这个习惯不养成，线上表现和离线评估会对不上。
参数说明：StandardScaler 没有需要特别调的超参，真正要注意的是 fit 的时机。之后补充了新的跌倒样本，把新老样本合在一起重新 fit 一次。归一化看着基础，但在 KNN 里它比换模型还重要，这也是项目源码里通常会把数据预处理单独抽成函数而不是和训练代码揉在一起的原因。
提示：训练集的 scaler 和模型一起保存，实时推理时加载同一份 scaler，不要现场重新算。
5. 避坑：Mediapipe 跌倒检测项目里最常见的 5 个实际问题
5.1 现象：mediapipe 装不上或 import 就报错
现象是执行pip install mediapipe后，import mediapipe直接报错，或提示 protobuf 运行时冲突、numpy 数据类型错误。原因分两类：一是 Python 版本或 numpy 主版本不在 wheel 支持范围内；二是 Linux 环境缺少 libGL 系统库。解决：用 3.9 或 3.10 建干净虚拟环境；把 numpy 固定到 1.x；Debian 系执行apt install libgl1 libglib2.0-0。如果之前装过旧版 opencv，建议一并升级到 opencv-python 4.5 以上，避免视频帧格式不兼容。
5.2 现象：骨架跳变、抖动剧烈，特征值忽高忽低
现象是画面里人站着不动，肩点和髋点来回跳，躯干角度抖动，KNN 频繁误报。原因通常是目标离摄像头太远、分辨率太低，或遮挡导致置信度低于阈值，Mediapipe 在 tracking 丢失后重新做 detection，两个阶段的抖动程度不同。解决：把人的成像高度调整为画面高度的 1/3 以上；把min_detection_confidence和min_tracking_confidence都提到 0.6 到 0.7；打开smooth_landmarks并对关键点做指数平滑。要注意的是，smooth_landmarks会引入约一帧延迟，对跌倒检测这种突发动作可以接受，但判断「倒地瞬间」不要依赖单帧精确值，用滑窗特征天然消除抖动。
5.3 现象：跌倒和弯腰、蹲下分不清楚，误报集中在日常动作
现象是现场测试时弯腰系鞋带、蹲下整理东西都触发报警。原因往往是特征设计只用了重心高度或只用了速度，没把躯干角度放进来。跌倒的核心特征是「躯干接近水平 + 高度骤降 + 倒地后静止」，弯腰和蹲下的躯干角度通常不会到 80° 以上。解决：把躯干角度作为必选特征；或者在规则层加前置判断，只有「高度下降比例大于阈值且最大角度大于 60°」的窗口才进入 KNN 分类。先用硬规则过滤明显不是跌倒的片段，再让 KNN 精分类，这能显著降低误报率。「规则粗筛 + KNN 精分类」的做法在源码工程里很常见，也适合现场快速调试。
5.4 现象：KNN 训练精度很高，实际场景一测就翻车
现象是训练集准确率 95% 以上，拿到现场换个摄像头角度就掉到 70%。原因主要有三个：样本全来自同一个机位；训练和验证用同一个划分，评估过拟合；没做标准化。解决：采集样本至少包含三个机位、三个以上的人、不同时间的光线条件；评估用留一法而不是固定切分，因为跌倒样本通常只有几十条，随机切分很容易把一类样本全留在验证集；所有特征必须经过训练集的 scaler 再做推理。还有一个容易被忽略的点：正负样本比例失衡时，KNN 投票会被多数类带偏，给近邻加距离权重weights='distance'，让离得近的样本说话更响。
5.5 现象：实时检测延迟高，画面卡顿
现象是笔记本上跑通了，但画面明显掉帧，KNN 还没来得及判断人已经站起来了。原因通常是每帧跑完整推理且没有跳帧，视频分辨率设置过高，可视化绘制也放在关键路径上。解决：统一把帧缩放到宽度 640 进 Mediapipe；每 2 到 3 帧做一次姿态估计，中间帧沿用上一帧骨架；可视化绘制精简，DrawLandmarks 的线和点不要每帧重画。更省的做法是实时链路里不绘制骨架，只在调试模式输出可视化。推理延迟瓶颈基本在 Mediapipe 而不是 KNN，所以调优顺序是先压骨架提取，再调 KNN 参数。
6. 留一法验证与参数网格搜索：让 KNN 跌倒检测模型的指标可信
跌倒样本少是这类项目逃不开的现实，KNN 的评估方式一旦错了，后面所有调参都是自我欺骗。我一般用留一法（LeaveOneOut）：每次只拿一条样本当验证集，其余全部当训练集，循环到每条都被验证过。几十条样本计算量很小，但能让评估结果接近真实泛化水平，比一次性切分可信得多。代码很短：
from sklearn.model_selection import LeaveOneOut from sklearn.neighbors import KNeighborsClassifier import numpy as np def loo_evaluate(X, y, n_neighbors=5, weights='distance'): loo = LeaveOneOut() preds, trues = [], [] for train_idx, test_idx in loo.split(X): clf = KNeighborsClassifier(n_neighbors=n_neighbors, weights=weights) clf.fit(X[train_idx], y[train_idx]) preds.append(clf.predict(X[test_idx])[0]) trues.append(y[test_idx][0]) return np.mean(np.array(preds) == np.array(trues))逻辑说明：训练和验证严格分离，不会出现数据泄露。scaler 的 fit 必须发生在进这个函数之前，否则训练和验证都会间接学到全局统计量。评估指标除了准确率，更要看误报率和漏报率。跌倒检测里漏报的代价远高于误报，宁可多几次误报，也要先保证不漏。weights='distance'在跌倒检测里更稳，因为跌倒样本少，距离权重能削弱远处多数类样本的投票权。
参数调优用网格搜索，范围收紧：n_neighbors 取 3 到 9，metric 只试 euclidean 和 manhattan，小样本下范围太大会把评估拉回过拟合区间。
from sklearn.model_selection import GridSearchCV param_grid = { 'n_neighbors': [3, 5, 7, 9], 'weights': ['uniform', 'distance'], 'metric': ['euclidean', 'manhattan'], } grid = GridSearchCV(KNeighborsClassifier(), param_grid, cv=LeaveOneOut(), scoring='recall') grid.fit(X, y) print(grid.best_params_)逻辑说明：scoring 选 recall 而不是 accuracy，因为跌倒样本是少数类，accuracy 在小样本下几乎没参考价值；recall 高代表漏报少，符合监护场景诉求。网格跑完后把 best_params_ 填回实时检测里的 KNN 模型即可。GridSearchCV 配 LeaveOneOut 在样本量很大时计算慢，但跌倒样本通常不过百条，可以放心用。
我自己跑这类项目养成的习惯是：每次现场调完阈值，把误报和漏报的样本补进训练集，重新跑一遍上面这段留一法，把准确率和 recall 记在一个小表格里，改一次记一次。KNN 的调参没有太多玄学，就是样本、特征、距离权重三件事轮着来；真正花时间的往往是数据采集和特征验证，而不是模型本身。希望这个流程能帮你少走一点弯路，也希望你的跌倒检测项目早日上线，帮到真正需要被看见的人。
本文还有配套的精品资源，点击获取
