YOLOv5+HRnet姿态估计：多人关键点检测与部署实战

简介：面向目标检测与姿态估计方向的学习者和开发者，提供基于YOLOv5、HRnet与SimDR的开箱即用工程，可直接对图片、视频及摄像头画面进行人体关键点检测。包内共2000个文件，以1867个Python脚本为主，辅以C源码、txt配置、Markdown说明等，压缩包约841.53MB，结构覆盖环境配置到结果演示。工程内含权重文件配置、SPPF模块添加、yaml修改、关键点提取与骨骼绘制等完整流程，并给出照片、视频和实时演示效果；同时整理路径报错、Upsample属性异常、gbk编码等常见问题的解决方案。作者提供原工程文件，免去自行配置参数和下载权重的麻烦，适合复现人体姿态估计项目的中高级开发者。目前已有1749人学习下载，目录清晰、排错思路详实，对实验与二次开发有实用参考价值。

1. YOLOv5姿态估计：为什么检测框之外还要再养一个HRnet

YOLOv5姿态估计这个说法，第一次听的人容易误以为YOLOv5自己能直接吐骨架点，其实真正负责人体关键点定位的是HRnet。它的落地形态是两条模型串成一条流水线：YOLOv5先给出画面里每个人体的检测框，HRnet再在每个框内回归17个关键点的坐标。两个任务各管一段，精度可控，速度也能推到实时。健身房动作计数、安防跌倒检测、门店行为分析这类场景，要的都是同一件事：单帧多人、关键点稳定、不卡顿。这篇文章适合已经跑通过YOLOv5检测、想把关键点能力接到自有数据集上的工程师，我会把数据准备、训练、级联推理和部署量化的坑一并讲清。

2. 多人姿态估计的选型：top-down方案里YOLOv5与HRnet各司其职

2.1 为什么多人姿态估计实时方案普遍选top-down

人体关键点检测有两种主流流派。bottom-up方案直接在一张图上预测所有关键点，再做分组配对，代表是OpenPose。它表面上只需要一次推理，但关键点分组这一步在人多、遮挡、交叉的情况下会退化成组合爆炸，而且分组逻辑本身难以GPU并行加速，实际帧率比看起来低得多。top-down方案则把问题拆成「先找到人，再看这个人的姿势」：检测到几个人，就做几次单人关键点回归。每次回归输入的都是被裁剪出来的人体区域，背景干扰少，模型只需要学人的结构，负担小很多。

多人姿态估计的实时项目里，top-down能成为默认选择，根本原因是它的两个子任务都足够成熟。检测部分用YOLOv5，已经是工程上验证过无数次的组件，NMS、anchor、多尺度这些超参数社区里都有成熟经验；关键点回归部分用HRnet，负责在一个人形框内把关节位置做到像素级准确。反过来，bottom-up的精度上限受分组算法拖累，投入产出比不划算。我自己的项目里，只有舞台、球场这类「人贴人」到检测框几乎重叠的场景才会考虑bottom-up，其他情况一律top-down。

2.2 HRnet的设计：多分辨率并行，而不是简单堆深度

HRnet在关键点任务上的核心贡献，是它没有走「编码-解码」这条路。SimpleBaseline那种ResNet加反卷积的结构，先把图片下采样到1/32，再靠反卷积把空间分辨率找回来，丢失的空间细节很难完全恢复，关键点这种需要精确定位的任务会很吃亏。HRnet的思路是始终保持一个高分辨率分支，同时不断加入低分辨率分支，让不同分辨率的特征在训练过程中反复交换信息。高分辨率支保留空间位置，低分辨率支提供语义信息，两者通过exchange模块反复融合，最后输出仍然保有1/4分辨率的特征图。

用人话讲：YOLOv5把人的位置框得再准，HRnet如果分辨率不够，关键点还是会飘在关节附近抖动。HRnet从结构上保证了它拿到的特征图天生就是「高清」的，这对手腕、脚踝这类小区域尤其重要。以下是HRnet与常见关键点主干网在关键细节上的对比：

用HRnet做关键点回归还有一个工程上的好处：它有不同宽度的版本，w32、w48，小模型跑在树莓派4b这类边缘设备上也是可行的，不会像Hourglass那样一上来就压垮算力。它的heatmap输出是17个通道，每个通道对应一个关键点，通道内的二维高斯峰位置就是关键点所在。

2.3 别指望YOLOv5直接吐关键点：检测头的边界

YOLOv5本身是一个目标检测器，它的输出是box、置信度和类别概率。有人会把YOLOv5的anchor头改一改、加一个关键点分支，做成yolov5-pose形态，这确实是存在的做法，一个模型同时出框和关键点，省一次前向。但要注意它的边界：检测头和关键点头共享特征，训练时多任务loss互相牵制，关键点精度通常不如专门的HRnet。如果项目要求关键点精度高于「大概能用」，我的经验是别在这上面省。

标题里的组合方式，本质上是用两个模型各做自己最擅长的事。YOLOv5负责召回——把每个人都找出来，哪怕框稍微松一点都能接受；HRnet负责精度——在框内把关键点钉在关节上。检测的漏检可以通过调置信度阈值补回来，关键点不准就只能换更大输入或换更强网络。这条分工边界在后续部署调优时特别有用：帧率不够先优化检测部分，精度不够则集中看HRnet的输入分辨率和训练数据，两边的排查维度是分开的。

3. 用HRnet训练自己的关键点模型：数据格式、超参数与评估指标

3.1 从COCO的person_keypoints.json开始准备训练数据

要训练HRnet，第一步是准备关键点标注数据。COCO的person_keypoints_train2017.json是最常用的起点，它的annotations数组里每一条是一个人，bbox字段是[x, y, w, h]，keypoints字段是17个关键点的扁平列表，排列顺序是x0, y0, v0, x1, y1, v1……其中v表示可见性，v=0不可见，v=1遮挡但可见，v=2完全可见。先写一段脚本把这份JSON解析成训练可用的格式：

import json import numpy as np with open('person_keypoints_train2017.json') as f: coco = json.load(f) JOINT_NAMES = ['nose', 'left_eye', 'right_eye', 'left_ear', 'right_ear', 'left_shoulder', 'right_shoulder', 'left_elbow', 'right_elbow', 'left_wrist', 'right_wrist', 'left_hip', 'right_hip', 'left_knee', 'right_knee', 'left_ankle', 'right_ankle'] records = [] for ann in coco['annotations']: if ann['num_keypoints'] == 0: continue kp = np.array(ann['keypoints'], dtype=np.float32).reshape(-1, 3) x, y, w, h = ann['bbox'] records.append({ 'image_id': ann['image_id'], 'bbox': [x, y, x + w, y + h], # 转成左上角/右下角 'keypoints': kp[:, :2], # 只取坐标 'visibility': kp[:, 2], # 可见性单独保留 'area': w * h, }) print(f'有效人体实例：{len(records)}')

这段代码的作用是把COCO原始标注转成更紧凑的结构。bbox从[x, y, w, h]转成[x1, y1, x2, y2]是为了后续裁剪方便；num_keypoints为0的实例直接丢弃，因为对训练毫无信息量。visibility字段不要丢，训练loss里通常只计算v>=1的关键点，标注为不可见的点不该参与反向传播。如果你是自己标注数据集，关键点顺序一定要和这个JOINT_NAMES严格一致，否则模型学到的东西全乱了。

3.2 训练HRnet：命令行、关键超参数与预训练初始化

数据准备好之后，训练环节常见做法是在MMPose这类框架上做二次开发。以HRNet-w32、输入分辨率256x192为例，训练脚本大概长这样：

python train.py --config hrnet_w32_coco_256x192.py \ --data-root ./datasets/coco \ --work-dir output/hrnet_w32 \ --batch-size 64 \ --lr 1e-3 \ --epochs 210 \ --warmup-iters 1000 \ --gpus 4

几个关键参数值得展开说。batch-size 64是COCO训练常用值，显存不够可以等比例降到32，同时把lr跟着降到5e-4，二者要保持缩放关系。lr用了1e-3而不是检测模型常见的更大的学习率，因为关键点回归本质上是一个稠密回归问题，损失面比较敏感，步子太大容易震荡。210个epoch是COCO姿态估计的标准训练长度，自己小数据集不必这么久，我一般先跑到100个epoch看验证集是否收敛。

说到超参数，很多从YOLOv5转过来的人容易把YOLOv5那套调参经验直接搬过来，这是常见的翻车点。YOLOv5训练自己的数据集，大家习惯调anchor尺寸、box loss权重、置信度阈值这些；但HRnet这一支的关键超参数完全不一样，最该关注的是heatmap的sigma值、生成heatmap时的正样本半径、随机翻转和半身增强的概率。sigma=2是256x192输入的常见设置，决定高斯峰的宽窄；sigma太小，关键点标注微小的标注误差就会让loss变得异常大，训练不稳；sigma太大，峰糊成一片，定位精度下降。这是关键点模型的玄学所在，没有捷径，只能靠验证集说话。

3.3 用OKS评估：准确率、召回率与关键点质量的关系

关键点模型的评估不能直接套目标检测的mAP，业界通用指标是OKS（Object Keypoint Similarity）。它的核心思想是：把预测点与标注点的距离除以该人物的尺度s再除以一个关键点类别常数k，最终映射到0到1。同样是5个像素的误差，一个身高占满画面的成年人和一个远处的路人，得分应当完全不同。COCO官方的AP就用OKS在0.5到0.95之间取多个阈值计算，它同时衡量了模型「找得到关键点」和「找得准关键点」两件事。

评估命令一般长这样：

python eval.py --checkpoint output/hrnet_w32/best_epoch.pth \ --dataset coco --metric AP_OKS \ --flip-test

评估时把flip-test打开，意思是原图和水平翻转图各推理一次，取两次heatmap的平均值再做解码，通常能给AP带来0.5到1个点的稳定提升。代价是推理耗时翻倍，所以它只用于离线验证，线上实时推理一般不启用。如果要在自己的数据集上看效果，建议按OKS的AP@0.5和AP@0.75两个阈值分开看：AP@0.5低说明模型经常找不到关键点，AP@0.75低说明关键点找到了但对不准，两个方向排查的问题完全不同。

4. YOLOv5与HRnet级联推理：最小实现、跟踪复用与坐标还原

4.1 级联推理的最小Python实现与逐段说明

把训练好的两个模型串起来，最直接的方式是用Python脚本逐帧处理。以下是一段最小可跑的推理逻辑，YOLOv5负责出框，HRnet负责对每个框做关键点回归：

import cv2 import numpy as np import torch det_model = load_yolo('yolov5s.pt') # 你的YOLOv5权重 pose_model = load_hrnet('hrnet_w32.onnx') # 你的HRnet导出模型 INPUT_H, INPUT_W = 256, 192 HEATMAP_H, HEATMAP_W = 64, 48 def decode_heatmap(hm): """将17通道heatmap解码成亚像素坐标""" hm = torch.from_numpy(hm).softmax(dim=1) coords = [] for k in range(hm.shape[0]): idx = hm[k].argmax() xs, ys = np.meshgrid(np.arange(HEATMAP_W), np.arange(HEATMAP_H)) px = (hm[k] * xs).sum().item() py = (hm[k] * ys).sum().item() coords.append([px, py]) return np.array(coords) def pose_one_person(img, box): x1, y1, x2, y2 = [int(v) for v in box] person = img[y1:y2, x1:x2] resized = cv2.resize(person, (INPUT_W, INPUT_H)) tensor = normalize(resized) # /255 + imagenet均值方差 with torch.no_grad(): hm = pose_model(tensor)[0].cpu().numpy() # [17, 64, 48] pts = decode_heatmap(hm) scale_x = (x2 - x1) / INPUT_W scale_y = (y2 - y1) / INPUT_H pts[:, 0] = pts[:, 0] * (INPUT_W / HEATMAP_W) * scale_x + x1 pts[:, 1] = pts[:, 1] * (INPUT_H / HEATMAP_H) * scale_y + y1 return pts

这里有两个容易踩坑的细节。第一，decode_heatmap用的不是argmax取整数坐标，而是对整张热力图做softmax后求期望，等价于soft-argmax，能拿到亚像素精度，关键点不会出现肉眼可见的锯齿抖动。第二，坐标还原时要乘上「heatmap尺寸到输入尺寸」的缩放比，再乘上「输入尺寸到裁剪框尺寸」的缩放比，最后加回box左上角坐标。很多人在这一步漏掉第一层缩放，导致所有关键点偏向框的右上角。

运行时的主循环里，对YOLOv5输出的每个框调用一次pose_one_person。这里要注意，人框的大小差异很大，一个很小的路人被放大到256x192，图像会变得模糊，HRnet的精度会下降；常见做法是把最小框面积作为一个过滤条件，太小的框直接不送HRnet。可以在YOLOv5输出侧加一个判断：框的宽高小于输入尺寸的一半时跳过，按经验这类目标即使出了关键点也几乎没有可信度。

4.2 引入跟踪器复用检测结果，把YOLOv5从每帧流水线上撤下来

级联推理最直接的性能瓶颈在YOLOv5而不是HRnet。YOLOv5在640x640输入下，单帧推理要10到20毫秒，看起来不多，但视频流是每帧都要跑；HRnet对单个256x192小图只有几毫秒，人数少的时候完全不是问题。所以工程上最常见的优化思路是给检测加一个「降频」机制：检测只每N帧跑一次，中间帧用跟踪器把上一帧的框延续下来。下面是一段用IoU做骨架跟踪的最小实现：

class Track: def __init__(self, box, track_id): self.box = box self.track_id = track_id self.alive = 5 def update_tracks(tracks, det_boxes, iou_thr=0.3): for dbox in det_boxes: best, best_iou = None, iou_thr for t in tracks: i = compute_iou(dbox, t.box) if i > best_iou: best, best_iou = t, i if best: best.box = dbox # 用新检测框覆盖跟踪框，防止漂移 best.alive = 5 else: tracks.append(Track(dbox, len(tracks))) for t in tracks: t.alive -= 1 if t.alive <= 0: tracks.remove(t)

这段代码的逻辑是：新检测框优先匹配IoU最高的旧跟踪框，匹配上就更新位置，匹配不上就新开一个track；每帧把alive减1，减到0的track删除。真实工程里直接换用ByteTrack能处理更多边界情况，但骨架思路完全一致。它的意义在于让YOLOv5每5帧才跑一次，中间帧直接沿用上一帧的框，省下的时间相当可观。

注意：跟踪器负责的是「框的位置」，HRnet的关键点检测仍然每帧都要跑。因为人体姿态是高度动态的，框可以用上一帧的，姿势不能，否则动作稍快就会出现关键点滞后。这是一种比较平衡的取舍：检测降频省的是YOLOv5的大开销，关键点保持全帧率保证输出流畅。如果设备实在太弱，也可以把关键点降到每两帧一次，中间帧用线性插值补，但动作幅度大时骨架会有可感知的漂移。

4.3 关键点坐标还原、可视化与匿名化输出

推理完成后，输出端的处理同样影响观感。骨架可视化常用的连接对可以参考以下列表，它对应COCO的17个关键点定义：左右眼分别与鼻子相连，肩膀、手肘、手腕串成手臂两条线，髋部、膝盖、脚踝串成腿两条线，左右髋部之间连一条横线，肩膀之间也连一条横线。一条实用的代码片段是：

LIMBS = [ (0, 1), (0, 2), (0, 5), (0, 6), # 鼻子到眼睛、肩膀 (5, 7), (7, 9), (6, 8), (8, 10), # 手臂 (5, 6), (5, 11), (6, 12), (11, 12), # 肩髋 (11, 13), (13, 15), (12, 14), (14, 16), # 腿 ] def draw_skeleton(img, pts, visible): for a, b in LIMBS: if visible[a] and visible[b]: cv2.line(img, tuple(pts[a].astype(int)), tuple(pts[b].astype(int)), (0, 255, 0), 2)

VISIBLE这个数组来自HRnet输出或是你训练时的visibility字段，画线时跳过不可见的关键点，否则会把同一侧的断肢连成一条奇怪的长线。可视化的另一层目的是做日志留档，记录每帧关键点坐标JSON和对应的骨架图片，方便后续回溯数据质量问题。如果你的场景涉及行人隐私，也可以在输出阶段只保留关键点坐标和骨架图，不保存原始画面，既能验证算法效果，又减少合规压力。这个「保存骨架、丢弃原图」的做法是我见过最省事的落地策略。

5. 部署避坑：NMS阈值、分辨率、量化与rk3568/树莓派4b上的血泪记录

5.1 现象：一个边框重复出现、关键点成双——NMS和阈值没配对

第一次把级联流水线接到视频流上时，最常看到的现象是一个人身上叠了两个框，HRnet被调用两次，骨架图出现重影。原因是YOLOv5默认的NMS参数是按目标检测场景调的，多人密集场景里一个人被重复检出的概率明显上升，而NMS的IoU阈值设得太高，没有把重复框合并掉。

原因是NMS的IoU阈值与置信度阈值之间存在联动关系。人框重叠率高，但两个重复框的置信度相差不大时，NMS需要更激进的合并策略。解决方法是把conf_thres调到0.25左右，把nms_iou从默认的0.5调低到0.4到0.45。如果你的框架支持「按类别做NMS」，确认单个类别的场景不需要跨类NMS，跨类NMS会把人框和别的物体框一起合并，反而引入新的漏检。调完之后数一帧画面里框的数量和真实人数是否一致，这个是线下就能验证的。

5.2 现象：离线精度正常、板子上掉点——量化与预处理翻转

在rk3568上部署时，常见翻车是把模型从FP16量化到INT8之后，OKS AP从0.75掉到0.62，尤其手腕和脚踝这类小关键点偏移最严重。直接原因有两个：量化校准集选得不对，以及HRnet的softmax输出对数值分布极敏感。校准集如果只用了几十张训练集图片，没有覆盖现场的光照和动作分布，量化后的激活值截断就会把这些少见场景的分布切掉。

解决路径分三步。第一，校准集至少准备200到300张与现场场景接近的图，尽量包含不同体型、不同光照的人。第二，对HRnet的输出层和softmax之前的层保持FP16，不参与INT8量化，这两个地方的数值范围窄、量化误差容易被放大。第三，用混合量化看每个层的量化误差报告，优先把误差大的层留在高精度。具体到rk3568的工具链，可以先转ONNX再到rknn，中间明确指定量化层。树莓派4b的CPU部署反而没有这一层问题，直接用ONNX Runtime跑FP16就行，但帧率上不要抱太高期望，720p输入下能跑到15帧就算不错。

5.3 现象：多人遮挡时关键点乱跳——检测框不贴合与分辨率冲突

top-down方案有个结构性弱点：关键点质量完全依赖检测框质量。当两个人前后重叠，YOLOv5给出的框往往把两个人的区域混在一起，HRnet在这个框里会试图回归出「一个人」的关键点，结果就是骨架在两个人之间切换跳跃，表现为关节点在相邻帧里大范围抖动。

原因不在HRnet本身，而是框的尺度不匹配人的实际范围。解决思路通常是给HRnet一个「更紧的框」：对YOLOv5输出的框，在送入HRnet之前按比例向内收缩一点。把框缩小，裁剪出来的人体更居中，评分更高，关键点反而更稳定。具体做法是x方向的框向内收缩5%到10%，y方向尽量不动，因为人体高度变化比宽度大。还有一个辅助手段是过滤「框内关键点数量过少」的结果，比如一个框里只有两个关键点可见，那大概率是框混入了多个人，直接丢弃这一帧的骨架输出更合理。

5.4 现象：训练loss很低、推理全乱——数据增强在推理时忘了关

这类问题最隐蔽，因为它错得无声无息。训练脚本里用了random flip、随机旋转、半身增强，loss曲线一路降到0.2以下，验证也没问题；一旦接上摄像头，所有的关键点都出现在错误的位置。排查半天发现是推理脚本里的预处理忘了做同样的normalize，比如训练时图像除以255并减了ImageNet均值，推理时只做了resize。

原因是关键点模型对输入的数值分布极度敏感，差一个通道均值的量级，整个heatmap就会偏移。解决方法是把预处理函数单独抽出来，和模型一起封装成一个推理类，训练脚本和推理脚本共用同一个函数；更彻底的做法是在导出ONNX时把归一化做成模型内部的第一个节点，这样部署侧永远不需要再传参数。另一个容易漏的是flip-test：训练时开了random flip，推理时如果没做flip-test的等效处理，模型看到的输入分布和训练时不一致，也会出现精度莫名下降。我的习惯是把「训练开的增强」和「预处理标准化」写在一个配置里，部署时直接带配置走，绝不手写第二份。

6. 压实时帧率的三个小技巧：先跟踪、再降分辨率、最后量化

6.1 按「帧率先行」的方式验证，别一上来就调heatmap高斯核

很多人在部署时第一步就去调HRnet输入分辨率或heatmap sigma，走了弯路。正确的验证顺序是先量化各模块耗时，再决定优化哪里。我习惯先用一个计时脚本分别测YOLOv5单帧耗时、HRnet单框耗时、整体流水线耗时，把数据摆出来再做取舍。一个参考的验证表格如下：

三个技巧按性价比排序：第一，YOLOv5降频到每5帧一次，配合跟踪器补中间的框，这是收益最大的改动，几乎不损失精度；第二，HRnet输入分辨率从256x192降到192x144，精度掉1个点左右但耗时下降三分之一，适合硬件实在吃紧的情况；第三，模型量化放到最后做，因为它带来的不确定性最多，要在前两步做完之后再评估是否还需要。如果做完这三步帧率还是不够，我才会考虑裁剪HRnet宽度，比如w48换w32。

6.2 一个让我少走三个月弯路的导出习惯

最后分享一个我自己养成的习惯：模型导出时一定把预处理一起打进去。无论是导出ONNX还是rknn，都让模型的输入直接是BGR原始图像，把除以255、减均值、通道顺序转换全部变成一个内部节点。这样做之后，我在rk3568和树莓派4b上的部署代码几乎不用改，也不存在「桌面端正常、板子上全错」的预处理不一致问题。刚开始做姿态估计时，我在这上面翻过车，查了一个月，最后发现只是推理脚本里忘了做normalize。后来所有模型一律按这个方式导出，再没出过同类问题。如果你刚开始做YOLOv5姿态估计这个方向，就从第一天把这条固化进流程，能帮你省掉大量排错时间。希望帮到你。

本文还有配套的精品资源，点击获取