Ultralytics COCO8-Pose 数据集实战指南：用 8 张图片跑通 YOLO26 姿态估计的完整训练流程

本文围绕 Ultralytics YOLO 仓库中的 COCO8-Pose 数据集文档展开，完整讲解其数据构成、YOLO 姿态标签格式、coco8-pose.yaml 数据集配置文件的每个字段含义，以及如何使用 YOLO26-pose 模型完成训练、验证与推理调试。读完本文，你可以独立使用该数据集对姿态估计训练管线做“健康检查”，并定位常见配置错误（如 kpt_shape 缺失），为扩展到完整 COCO-Pose 数据集打下基础。

COCO8-Pose 是什么：定位与数据构成

Ultralytics COCO8-Pose 是一个小而精的姿态估计数据集：它取 COCO train 2017 的前 8 张图片，其中 4 张用于训练、4 张用于验证，使用 COCO 标准的 17 关键点 schema，只标注单一 person 类别。其下载体积仅约 1 MB。

这个数据集的核心定位不是“训练出高精度模型”，而是：

• 测试与调试姿态估计模型：快速验证数据加载、标签解析、可视化、损失计算等训练链路是否正常；
• 实验新的关键点检测思路：改动代码后能在秒级到分钟级内观察训练是否收敛；
• 训练前的 sanity check：在投入时间训练完整的 COCO-Pose 数据集 之前，先用 COCO8-Pose 把整个管线跑通。

数据集结构要点（继承自官方文档）：

属性	说明
图片总数	8（4 train / 4 val）
类别数	1（person）
关键点	每个标注实例 17 个关键点，含可见性维度
下载体积	约 1 MB
推荐目录结构	datasets/coco8-pose/images/{train,val} 与 datasets/coco8-pose/labels/{train,val}，关键点以 YOLO 格式存于 .txt 文件

标签格式：每行 55 个字段的 YOLO 姿态标注

COCO8-Pose 遵循 Ultralytics YOLO 姿态标注格式（详见 docs/en/datasets/pose/index.md）：每张图对应一个同名 .txt 标签文件，每个目标实例占一行。含可见性维度的格式为：

<class-index> <x> <y> <width> <height> <px1> <py1> <p1-visibility> <px2> <py2> <p2-visibility> ... <pxn> <pyn> <pn-visibility>

对 COCO8-Pose 而言，<class-index> 恒为 0（person），<x> <y> <width> <height> 是归一化到 0~1 的边界框中心与宽高，其后是 17 个关键点、每个关键点 3 个数值（x、y、visibility），因此每行共 5 + 17 × 3 = 56 个字段。坐标均相对图片尺寸归一化，可见性通道用于表达关键点遮挡情况（0=未标注、1=被遮挡、2=可见标注）。

数据集 YAML 配置文件详解

数据集通过 YAML 文件定义配置。COCO8-Pose 对应的 coco8-pose.yaml 随仓库内置，完整内容如下：

# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license

# COCO8-pose dataset (first 8 images from COCO train2017) by Ultralytics
# Documentation: https://docs.ultralytics.com/datasets/pose/coco8-pose
# Example usage: yolo train data=coco8-pose.yaml
# parent
# ├── ultralytics
# └── datasets
#     └── coco8-pose ← downloads here (1 MB)

# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..]
path: coco8-pose # dataset root dir
train: images/train # train images (relative to 'path') 4 images
val: images/val # val images (relative to 'path') 4 images
test: # test images (optional)

# Keypoints
kpt_shape: [17, 3] # number of keypoints, number of dims (2 for x,y or 3 for x,y,visible)
flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15]

# Classes
names:
  0: person

# Keypoint names per class
kpt_names:
  0:
    - 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

# Download script/URL (optional)
download: https://github.com/ultralytics/assets/releases/download/v0.0.0/coco8-pose.zip

逐字段说明

• path: coco8-pose：数据集根目录名。训练时框架会在当前工作目录下自动创建 coco8-pose/ 子目录，并按 download 字段指向的 URL 自动下载约 1 MB 的数据包，解压为 images/{train,val} 与 labels/{train,val}——首次使用无需手动准备任何文件。
• train / val / test：相对 path 的图片目录。这三个字段均支持三种写法：目录路径、*.txt 图片清单文件、或目录列表；test 为可选项。
• kpt_shape: [17, 3]：姿态数据集的必填项，表示 17 个关键点、每个关键点 3 维（x, y, visibility；若不标注可见性则为 2 维）。这个字段直接决定模型头与标签解析行为：
  • 在 ultralytics/models/yolo/pose/train.py 中，PoseTrainer.get_dataset() 会显式检查该字段，缺失时抛出 KeyError: No 'kpt_shape' in the ... 并指向姿态数据集文档页；
  • 在 ultralytics/data/dataset.py 中，YOLO 数据集类会用 kpt_shape 解包 nkpt, ndim 来解析每个标签行，格式不符会直接报错。
• flip_idx: [0, 2, 1, 4, 3, ...]：水平翻转增强时左右关键点的镜像映射。人体骨架是左右对称的（左眼↔右眼、左肩↔右肩……），翻转图像后必须同步交换左右关键点索引，否则监督信号自相矛盾。COCO8-Pose 的映射中每对相邻左右索引互换（0↔1、2↔3、4↔5……），nose（索引 0 的对称对象）等中线点保持自身。
• names: 0: person：类别字典，索引顺序必须与标签文件中的 class index 一致。
• kpt_names：每个类别的关键点名称列表，用于结果可视化时给关键点标注语义名。17 个名称与 姿态估计任务文档 中的 COCO 人体关节映射一致（nose → left_ankle）。
• 可选扩展项 kpt_oks_sigmas：自定义每个关键点的 OKS sigma（用于训练与验证中的关键点 IoU 计算），列表长度必须等于 kpt_shape 的关键点数且全部为正数；省略时，kpt_shape: [17, 3] 会自动使用 COCO 官方 17 关键点 sigma，其他形状则使用均匀 1/N（见 docs/en/datasets/pose/index.md）。

从源码看，这些配置最终会注入模型对象：PoseTrainer.set_model_attributes() 把 kpt_shape、kpt_oks_sigmas 和 kpt_names 写入 PoseModel 的对应属性；若 YAML 未提供 kpt_names，则会退化为 "0".."16" 的数字索引名。

训练 YOLO26-pose 模型

COCO8-Pose 文档给出的标准用法是：加载 yolo26n-pose.pt 预训练权重，训练 100 个 epoch、图片尺寸 640。完整 Python 与 CLI 示例如下：

from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n-pose.pt")  # load a pretrained model (recommended for training)

# Train the model
results = model.train(data="coco8-pose.yaml", epochs=100, imgsz=640)

# Start training from a pretrained *.pt model
yolo pose train data=coco8-pose.yaml model=yolo26n-pose.pt epochs=100 imgsz=640

除上述“加载预训练权重”方式外，还有两种常见的模型构建方式（见 docs/en/tasks/pose.md）：

model = YOLO("yolo26n-pose.yaml")                        # 从 YAML 构建全新模型
model = YOLO("yolo26n-pose.yaml").load("yolo26n-pose.pt")  # 从 YAML 构建并迁移预训练权重

# Build a new model from YAML and start training from scratch
yolo pose train data=coco8-pose.yaml model=yolo26n-pose.yaml epochs=100 imgsz=640

# Build from YAML and transfer pretrained weights
yolo pose train data=coco8-pose.yaml model=yolo26n-pose.yaml pretrained=yolo26n-pose.pt epochs=100 imgsz=640

yolo26n-pose 对应的网络定义见 ultralytics/cfg/models/26/yolo26-pose.yaml：backbone 输出 P3/8、P4/16、P5/32 三个尺度特征，末尾由 Pose26 头完成框 + 关键点联合回归（该文件中 kpt_shape: [17, 3] 与 COCO8-Pose 的数据配置一致）。n 规格约 370 万参数、10.7 GFLOPs，适合在 COCO8-Pose 上快速迭代。完整的 train 模式参数清单见 Train 模式文档。

验证、推理与工程化检查

训练完成后，模型会记住训练时的数据配置，验证无需重复传参：

from ultralytics import YOLO

model = YOLO("path/to/best.pt")  # 自定义训练产物，或官方 "yolo26n-pose.pt"

metrics = model.val()  # dataset and settings remembered
metrics.pose.map    # map50-95(P)
metrics.pose.map50   # map50(P)
metrics.pose.map75   # map75(P)
metrics.pose.maps    # 每类的 mAP50-95(P)
metrics.box.map      # map50-95（框分支）

yolo pose val model=path/to/best.pt   # 验证自定义模型
yolo pose val model=yolo26n-pose.pt  # 验证官方模型

推理时每个 Results 对象提供 result.keypoints（含 .data（N,K,2/3）、.xy、.xyn）与 result.boxes 字段，可用于后续骨骼绘制或下游逻辑：

results = model("path/to/image.jpg")
for result in results:
    xy = result.keypoints.xy       # 像素坐标
    xyn = result.keypoints.xyn     # 归一化坐标
    kpts = result.keypoints.data   # x, y, visibility

COCO8-Pose 也被仓库自身的测试套件用作回归基准，这可以作为“管线是否正常”的可验证依据：

• tests/test_engine.py 将 PoseTrainer、PoseValidator、PosePredictor 三个类与 coco8-pose.yaml + yolo26n-pose.yaml 组合，在引擎级测试中跑通 train/val/predict 全流程；
• tests/test_python.py 中专门验证了 val(save_txt=True, save_json=True) 输出的关键点处于原图坐标系（使用 imgsz=640，因为 coco8-pose 图片非正方形，letterbox 偏移不可忽略）；
• 同一测试文件还展示了最小化超参搜索的用法：YOLO("yolo26n-pose.pt").tune(data="coco8-pose.yaml", plots=False, imgsz=32, epochs=1, ...)，在小图上把调参循环压到极短。

Mosaic 增强：小数据集也能制造多样 batch

COCO8-Pose 文档特别指出，训练日志中的“mosaiced image”可视化图展示了一个由多张数据集图片拼接而成的训练 batch。Mosaic 增强将多张图片（典型为 4 张）拼成一张，使每个 batch 内出现更多样的目标尺度、宽高比与场景组合，提升模型对不同上下文下关键点位置的泛化能力——这在仅有 4 张训练图的 COCO8-Pose 上尤为关键：单看每张图信息量极少，但 Mosaic 让模型在有限数据内反复见到不同组合与遮挡关系。

从 Sanity Check 到完整 COCO-Pose 的升级路径

COCO8-Pose 通过后的标准扩展动作是切换到 coco-pose.yaml 训练完整 COCO-Pose 数据集（COCO Keypoints 2017：58,945 张含关键点标注的图片、156,165 个标注人物，同为 17 关键点 person 类别）。由于两者共享相同的 kpt_shape: [17, 3] 与类别定义，在 COCO8-Pose 上产出的 best.pt 可直接作为完整数据集训练的初始化权重，形成“小数据验证管线 → 大数据量训练”的两阶段流程。

若使用 COCO 系列数据集用于研究，请引用 COCO 原始论文：

@misc{lin2015microsoft,
      title={Microsoft COCO: Common Objects in Context},
      author={Tsung-Yi Lin and Michael Maire and Serge Belongie and Lubomir Bourdev and Ross Girshick and James Hays and Pietro Perona and Deva Ramanan and C. Lawrence Zitnick and Piotr Dollár},
      year={2015},
      eprint={1405.0312},
      archivePrefix={arXiv},
      primaryClass={cs.CV}
}

常见问题

COCO8-Pose 适合直接用于生产级模型训练吗？ 不适合。8 张图无法让模型学到有效的姿态先验。它的价值在于以最小成本验证数据加载、标签格式、增强、损失与可视化链路，确认无误后再上完整数据集。

为什么训练报 No 'kpt_shape' in ...？ 姿态任务要求数据集 YAML 中声明 kpt_shape: [N, 2/3]。检测数据集（如 coco8.yaml）没有该字段，直接用于 yolo pose train 会触发 PoseTrainer.get_dataset() 的 KeyError。请确认使用的是 coco8-pose.yaml 这类姿态数据集配置。

COCO8-Pose 与 COCO-Pose 的关键区别？ 数据量（8 张 vs 5.8 万张）与用途（sanity check vs 正式训练）；两者标注 schema 完全一致（单 person 类、17 关键点含可见性），模型与配置可以无缝迁移。

没有现成的姿态标注，如何准备自定义数据集？ 可先用 ultralytics/data/converter.py 中的 convert_coco(labels_dir=..., use_keypoints=True) 将 COCO 格式 JSON 转为 YOLO 姿态格式，再按上文 YAML 模板编写自己的数据集配置，流程详见 docs/en/datasets/pose/index.md 的 “Adding your own dataset” 一节。