YOLOv8-pose关键点检测实战：从COCO数据标注到训练部署

简介这是一套基于YOLOV8-pose的人体姿态关键点检测项目面向计算机视觉开发者与科研人员可用于姿态识别、运动分析、人机交互等场景的模型训练与推理。包内含完整源码、预训练权重、标注数据集和配置文件并附有README说明可直接运行验证无需从零构建数据处理流程。资源共1369个文件以py脚本、yaml配置文件、jpg图像数据集、md说明文档为主体另有pt模型权重、txt标注、log训练日志及json结果等整体约89.04MB目录结构清晰。数据集中包含多样环境下的人体关键点标注图像可支撑模型微调与泛化测试。目前已有6214人学习下载。通过该资源可掌握YOLOV8-pose的网络结构、多任务损失设计与关键点检测全流程并可直接基于现有权重开展实验和二次开发适合希望快速上手指姿态估计的开发者或研究者。1. 姿态识别没有想象中那么难一份YOLOv8-pose关键点检测资源能帮你走到哪姿态识别这几年从「实验室里跑 COCO 比赛」变成了「课程设计、毕设、项目 demo 都能用」的常规技术关键点检测就是把人体的眼睛、肩膀、手肘、手腕这些位置当作坐标点预测出来。YOLOv8-pose 是这个方向里最省心的实现之一自带 backbone、自带训练和推理脚本、预训练权重直接下配合这份资源自带的数据集拿到手就能把一条「图像 → 17 个关键点」的完整链路跑通。它适合两类人一类是做课程设计或毕设、需要在限定时间内交出一个能演示的成果另一类是刚开始接触关键点检测、想搞清楚数据格式和训练参数到底怎么配的从业者。这篇文章不聊理论推导只讲怎么把数据集、格式、训练、推理串起来。2. 数据集与标注格式COCO 17 点约定和 data.yaml 的写法2.1 目录结构与标注文件的对应关系这份资源自带的姿态数据集目录结构是标准 YOLOv8-pose 布局datasets/ ├── pose_data/ │ ├── images/ │ │ ├── train/ # 训练图片每张图一张或多个人 │ │ └── val/ # 验证图片 │ └── labels/ │ ├── train/ # 与 images/train 一一对应的标注 txt │ └── val/ # 与 images/val 一一对应的标注 txt ├── data.yaml # 数据集配置文件 └── README.md # 数据说明图片和标注文件的对应关系是靠文件名一致的.jpg与.txt来绑定的images/train/000001.jpg对应的标注就是labels/train/000001.txt。在部分自采数据集里同一张图可能有多个人那这个 txt 里就会有多个标注行。2.2 标注 txt 每一行的 7 个基础字段每一行标注对应一个人体目标格式比目标检测多一段关键点坐标class_id x_center y_center width height px1 py1 p1v px2 py2 p2v ... px17 py17 p17v前 5 个值的含义和目标检测完全一致类别 ID、归一化后的目标框中心点 x、中心点 y、框宽度、框高度。从第 6 个值开始是 COCO 17 个关键点的坐标每 3 个值一组分别是该点的归一化 x、归一化 y、可见性标志位。这里有两处容易理解错的地方。第一框和关键点的坐标都必须除以图片的宽和高得到 01 之间的小数如果有一张 1920×1080 的图某个点的像素坐标是 (960, 540)那写入标注的就是 (0.5, 0.5)。第二pNv这个可见性标志位取 0 或 10 表示这个点在图上被遮挡或没有标注1 表示可见且在画面内。超出图片边界的点同样写 0不写负数。YOLOv8-pose 训练时会把v0的点当作缺失点来处理在 loss 计算里跳过。17 个关键点的顺序是 COCO 原版约定不能自己随便排索引关键点索引关键点索引关键点0鼻子6右手腕12左髋1左眼7左手腕13右髋2右眼8右手肘14左膝3左耳9左手肘15右膝4右耳10右肩16左踝5左肩11左肩注意 dup 关系需要说明的是第 5 到第 12 的左右顺序在工程里经常有人记错后面第 5 章会专门展开讲它对训练结果的影响。2.3 data.yaml 的关键字段data.yaml是训练入口必须和目录结构严格对应。下面是这份资源自带数据集的配置示例#文件名: data.yaml path: ./datasets/pose_data # 数据集根目录 (相对此 yaml 所在位置) train: images/train val: images/val names: 0: person # 关键点相关配置 kpt_shape: [17, 3] # [关键点数量, 每个点的维度]; 维度3 代表 (x, y, visibility)第一个容易踩的坑是把path写成绝对路径一旦项目目录移动训练就报AssertionError: train dataset not found。第二个坑是kpt_shape必须写成[17, 3]这里的3表示每个点除了 xy 以外还有一个 visibility 标志。如果你手里只有 2D 坐标可以写成[17, 2]但代价是训练时不会按遮挡点做 loss 遮蔽所有点都按可见处理遇到遮挡情况会拉低精度。另外YOLOv8-pose 在训练时会做随机水平翻转的数据增强左右手会互换。模型得知道「水平翻转之后原来的左肩变成右肩、右肩变成左肩」才能让新增出来的样本和标注匹配。这个对应关系写在flip_idx里。在最新版的训练配置中是自动推导的前提是你在data.yaml里按 COCO 原版顺序写点不要自己打乱顺序。2.4 从 COCO JSON 转换到 YOLO Pose TXT很多数据集以 COCO JSON 格式发布需要转成上面的 txt。转换脚本的常见做法是遍历annotations数组把bbox转成x_center y_center width height把keypoints按 [x, y, v, x, y, v ...] 截成 17 组再全部除以图片宽高。下面的脚本是转换核心逻辑你可以把它接在自己的数据集转换流程里# convert_coco_to_yolo_pose.py import json, os def coco_to_yolo_pose(coco_json, img_dir, out_label_dir): with open(coco_json, r) as f: data json.load(f) # 先建图片 id 到文件名的索引 img_map {img[id]: img for img in data[images]} os.makedirs(out_label_dir, exist_okTrue) # 按图片分组整理标注 anns_by_img {} for ann in data[annotations]: anns_by_img.setdefault(ann[image_id], []).append(ann) for img_id, anns in anns_by_img.items(): img img_map[img_id] w, h img[width], img[height] out_lines [] for ann in anns: x, y, bw, bh ann[bbox] cx (x bw / 2) / w # 框中心归一化 cy (y bh / 2) / h bw_n bw / w bh_n bh / h kpts ann[keypoints] # 形如 [x, y, v, x, y, v, ...] 共 51 个数 kpt_str [] for i in range(0, len(kpts), 3): kx kpts[i] / w ky kpts[i1] / h kv kpts[i2] kpt_str.append(f{kx:.6f} {ky:.6f} {kv}) # 类别 id 固定为 0 (person) out_lines.append(f0 {cx:.6f} {cy:.6f} {bw_n:.6f} {bh_n:.6f} .join(kpt_str)) out_path os.path.join(out_label_dir, img[file_name].replace(.jpg, .txt)) with open(out_path, w) as f: f.write(\n.join(out_lines)) # 参数说明: # coco_json: COCO 格式标注文件路径 # img_dir: 图片目录 (这里只用于拿 id 和尺寸) # out_label_dir: 输出 YOLO 格式标签目录这个脚本里最核心的除法要保留小数 6 位归一化不精确会直接造成关键点坐标抖动。实际操作时还需要注意ann[keypoints]里如果某个人不是 17 个点比如标注工具没标全要先过滤掉样本或者补 0否则写入的 txt 缺列训练时代码直接崩。我一般会在写文件前加一段校验assert len(kpts) 51, 关键点数量不是17个。3. 训练与验证从命令行到模型选型的完整跑法3.1 环境安装和依赖这份资源自带源码包通常基于 ultralytics 框架我建议先建一个干净的虚拟环境再装依赖避免和已有环境的 PyTorch 版本打架。常规做法是# 创建 python 3.9 虚拟环境 conda create -n pose python3.9 -y conda activate pose # 安装 CPU 版可以不加 CUDA 参数; 用 GPU 训练请装对应 cuda 版本的 torch pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118 pip install ultralytics albumentations装完以后检查一下 GPU 是否可见这一步能省掉后面很多莫名其妙的报错import torch print(torch.cuda.is_available(), torch.cuda.get_device_name(0) if torch.cuda.is_available() else CPU)3.2 训练命令与参数表直接用这个资源根目录下的train.py会简单一点但如果你自己写训练入口核心命令就一行yolo pose train data./datasets/pose_data/data.yaml \ modelyolov8s-pose.pt \ epochs120 \ imgsz640 \ batch16 \ lr00.001 \ device0 \ project./runs \ namepose_train从入门角度出发第一次跑通先用yolov8s-pose.pt预训练权重作为起点不要从零训练随机初始化效果差两个量级。batch16只在 GPU 显存 8GB 左右时成立如果训练时报CUDA out of memory先把 batch 降到 8 或者 4imgsz降到 512。常用参数的意义做了一张表方便后续调整参数推荐起点含义与调参方向epochs120数据集小就 100~200观察 val/pose_loss 不再降就停imgsz640训练输入尺寸显存不够降到 512精度略降但速度更快batch16每批图片数显存不足时先减半lr00.001初始学习率使用预训练权重时 0.001 起步比较稳lrf0.01最终学习率占比配合 cosine 衰减到 lr0*lrfpatience50早停耐心验证集指标 50 个 epoch 不涨就停warmup_epochs3前 3 个 epoch 用小学习率热身稳定梯度close_mosaic10最后 10 个 epoch 关闭 mosaic 增强避免标注被切碎workers4数据加载线程数Windows 上可能设 0 才能跑device0第一个 GPU无 GPU 写 cpu3.3 训练输出文件与权重管理训练结束后会在runs/pose_train/下生成以下文件这也是判断训练是否正常的直接依据runs/pose_train/ ├── weights/ │ ├── best.pt # 验证集指标最好的权重 │ └── last.pt # 最后一个 epoch 的权重 ├── results.csv # 每个 epoch 的 loss 和指标 ├── confusion_matrix.png ├── results.png # loss 曲线和指标曲线 └── train_batch*.jpg # 训练可视化样本我拿到任何训练结果的第一步都是看results.png里val/pose_loss那条曲线它在 100 个 epoch 内平滑下降说明数据没问题如果曲线在某个点突然上翘就是过拟合了需要提前停或用早停参数接管。last.pt是断点续训用的别只留best.pt。3.4 验证用 val.py 复现指标评估模型用的是 COCO 关键点指标主要包括 box AP 和 pose AP 两套yolo pose val modelruns/pose_train/weights/best.pt \ data./datasets/pose_data/data.yaml \ imgsz640 \ device0输出里有两个关键指标AP50和AP50-95。AP50是宽松指标预测关键点与真实关键点距离小于阈值一半就算对容易虚高AP50-95是多阈值平均更苛刻也更接近实际效果。做课程设计展示时看AP50做项目交付我给到的目标是姿势估计 mAP50-95 ≥ 0.75COCO 验证集上 s 模型正常值约 0.75。4. 推理与部署把训练好的权重用起来4.1 推理接口与结果对象姿态推理同样有现成命令但工程上通常直接写在 Python 里方便后续做队列、取流、后处理# inference.py from ultralytics import YOLO model YOLO(runs/pose_train/weights/best.pt) # 加载训练好的权重 results model.predict( sourcedemo.mp4, # 也支持图片路径、摄像头编号、文件夹 conf0.25, # 低于该置信度的目标直接丢弃 imgsz640, device0, saveTrue, # 直接把结果图/视频保存到 runs/pose_predict ) # 结果对象里最重要的数据 r results[0] # 第一帧/第一张图的结果 keypoints r.keypoints # (人数, 17, 3) 的张量最后一维是 x, y, conf boxes r.boxes # 目标框r.keypoints.conf里存了每个关键点的置信度r.keypoints.xy存的是像素坐标。注意这里返回的坐标已经还原到原图尺寸不需要再做缩放。对于演示视频把saveTrue打开就直接产出了可视化结果这比手动画点省事不少。4.2 骨架绘制与关键点信度过滤画骨架线的需求很常见特别是做演示和答辩展示时。要点是先按置信度过滤掉那些预测很差的点再连线段。下面的代码就是我在比赛 demo 里经常用的画法# draw_pose.py import cv2 import numpy as np # COCO 17 点骨架连接顺序: (起点索引, 终点索引) SKELETON [ (0, 1), (0, 2), (1, 3), (2, 4), (0, 5), (0, 6), (5, 7), (7, 9), (6, 8), (8, 10), (5, 11), (6, 12), (11, 13), (13, 15), (12, 14), (14, 16) ] def draw_kpts(img, kpts, conf_thr0.3): # kpts: (17, 3) 的 numpy 数组, 每行为 x, y, conf kpts kpts.cpu().numpy() if hasattr(kpts, cpu) else kpts for i, (x, y, c) in enumerate(kpts): if c conf_thr: continue cv2.circle(img, (int(x), int(y)), 3, (0, 0, 255), -1) for a, b in SKELETON: if kpts[a, 2] conf_thr and kpts[b, 2] conf_thr: cv2.line(img, (int(kpts[a, 0]), int(kpts[a, 1])), (int(kpts[b, 0]), int(kpts[b, 1])), (0, 255, 0), 2) return img画完点之后有一个小建议demo 或答辩展示时把conf_thr调到 0.250.35 之间比较均衡。调太低会出现大量的乱线调太高骨架上全是断线。4.3 导出 ONNX 和部署边界演示做完之后如果要集成到项目里最常见的部署方式是导出 ONNXyolo pose export modelruns/pose_train/weights/best.pt formatonnx imgsz640 opset12导出时会提示ONNX: export success同时生成best.onnx文件。等部署到 CPU 上推理时用onnxruntime加载就行# onnx_infer.py import cv2, onnxruntime as ort import numpy as np sess ort.InferenceSession(best.onnx) input_name sess.get_inputs()[0].name img cv2.imread(test.jpg) img cv2.resize(img, (640, 640))[:, :, ::-1] # BGR - RGB x img.astype(np.float32) / 255.0 x x.transpose(2, 0, 1)[None] # (1, 3, 640, 640) out sess.run(None, {input_name: x})[0] # 输出 (1, 56, 8400) # 解析方式: 前 17*3 行是关键点, 后 4 行用于目标检测这里有个常见的认知偏差yolo pose export导出的 ONNX 里其实不包含 NMS输出是原始的(batch, 56, 8400)特征图。其中 56 维由 51 维关键点17 点 × 3加 4 维框坐标再加 1 维类别组成8400 是三个尺度的 anchor 总数。如果你在部署时直接把输出当作最终结果会发现同一个目标被框好几次——必须自己加 NMS 或使用带有nmsTrue参数的导出版本。对于在 CPU 上做实时推理的场景nmsTrue的 ONNX 会省很多事代价是线程并发时会有点延迟。5. 避坑从标注到训练的四条血泪记录5.1 关键点 AP 过了 0.8画出图来左右手反了现象训练完成了AP50也高但把预测结果画到图上左手腕的点和真实的左手腕偏差小右手腕却经常连到左边去。原因标注数据结构里左右定义和预训练权重里定义不一致。YOLOv8-pose 预训练权重基于 COCO 标注COCO 左边是「人视角的左边」和图片的左右视图正好是镜像关系。有一些自采数据集标注工具默认按「图像左边为左手」标导致模型强行学到了一个镜像映射在训练时即使 loss 表现正常左右判定却出现问题。解决先检查数据集的左右定义再检查data.yaml里是否通过flip_idx正确配置了翻转。如果关闭水平翻转增强左右手不会互相切换模型学习难度变大但不会学反。我处理这个问题是在训练脚本中打印model.model[-1].flip_idx对应的 17 个索引逐一和 COCO 标准表比对。5.2 训练时报Keypoints can not be 0现象训练刚开始几千步后崩溃提示Keypoints can not be 0。原因标注文件里有坐标为 0 的关键点但这和「可见性标志位 v0」不是一回事。代码在预处理阶段就读取所有关键点坐标只要发现(x, y)中出现了 0 或负数直接报错。解决清洗数据脚本把标注为不可见的点v0坐标改成接近 0 的占位值比如0.0001或者干脆在离线阶段把 v0 点的坐标替换成 bbox 中心点坐标。这个处理必须发生在训练前而不是训练中否则你会发现每次跑到第 2000 步才崩一次非常难排查。5.3 训练 loss 降了但迁移到新数据集效果断崖下跌现象在资源自带数据集上AP50-95达到 0.8换成自己收集的另一个姿势数据集后跌到 0.4 多。原因这只模型没有做微调直接把在资源自带数据集上训练出来的权重当成通用模型用。关键点检测对场景很敏感光照、人的身型占比、拍摄角度一变精度就掉得很快。解决拿到新数据集后做两步。第一步先在新数据集上验证看那张分类别 AP 表里具体是哪类场景掉得多。第二步用yolo pose train加resume的方式在旧权重上续训 30~50 个 epoch用lr00.0005这种小学习率微调一遍。微调之后再做推理一般能在原有基础上提升 5~20 个点。5.4 无 GPU 环境训练速度慢到怀疑人生现象CPU 训练 120 epoch 需要 40 小时以上跑了 10 个 epoch 前后验证集指标不变直接弃坑。原因关键点模型每个 epoch 要处理大量的图片一百多张图片在 CPU 上就要跑五六分钟小批量、多 epoch 叠加后时间成倍增长。解决如果是个人笔记本先用yolov8n-pose.pt做轻量预训练试跑把imgsz降到 416batch4。如果只是为了验证整套代码能否跑通用epochs3 workers0小规模跑先把代码链路验证完再上 GPU 跑正式训练。另一方面这份资源的训练脚本里建议直接把project和name参数设好别让每次训练都生成奇怪的目录名否则后续找权重文件同样浪费时间。6. 一个很实用的技巧用 warmup 和 close_mosaic 保住关键点细节训练关键点模型时最容易出现的怪异现象是 loss 前 20 个 epoch 一直降不下来但第 30 个 epoch 突然掉一大截。这不是模型问题而是学习率和增强策略没有配合好。我习惯的做法是第一轮训练就固定warmup_epochs5。预训练权重虽然已经收敛过一轮但新数据集的关键点分布不同一上来就用大学习率会把预训练里学到的骨架空间关系冲掉。前 5 个 epoch 用lr*0.1慢慢热起来相当于先给模型一段时间适应新标注分布再正式进入高学习率阶段。YOLOv8-pose 的训练默认有 warmup但很多基于旧版修改的训练脚本会把它省略所以第一件事是确认yolo pose train ... warmup_epochs5 warmup_bias_lr0.1第二件事是调close_mosaic。YOLOv8 的数据增强里有 Mosaic把四张图拼在一起缩放到 640好处是小目标变多坏处是人体的四肢连接关系被四个图的边缘切碎。关键点模型对肢体结构的连续性比目标检测敏感得多一个手肘被切成两半后学习出来的骨架语义就会扭曲。把close_mosaic10留在最后 10 个 epoch 里关闭让模型在接近正常的图片尺寸上做最后的精修通常能让骨架线画出来更连贯。第三用patience30而不是让它跑满。课程设计时间一般不够跑完整 200 epoch观察results.csv里跑满 30 个 epoch 还没有下降趋势就手动停掉换更小学习率重启。如果已经调过一轮就在验证集上比较两次的val/pose_loss选低的那个权重来推理。这个步骤说起来简单但很多人做完演示才发现素材是从最后一轮生成的等于白忙活。从那以后我每次拿到新的姿态数据集都会先在训练日志里看一遍 warmup 和 mosaic 的时间线再决定要不要重训这套习惯帮我避开了大量「训练很辛苦效果很尴尬」的夜晚。希望帮到你。本文还有配套的精品资源点击获取