Ultralytics YOLO 关键点标注指南：一次讲透关键点格式、3 档工具选型与 5 个避坑点

Ultralytics YOLO 关键点标注指南一次讲透关键点格式、3 档工具选型与 5 个避坑点【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics本文以 Ultralytics YOLO 为主线手把手带你完成关键点检测数据集从想清楚难点到标注、转换、质检的完整闭环。适合第一次做 YOLO 关键点标注的新手先搞清楚难点在哪再吃透 YOLO 关键点格式然后按团队规模选标注工具最后用避坑清单和自查表兜底质量。全程不堆代码只在关键处给出最小可用示例。难点拆解YOLO 关键点标注到底难在哪很多人从目标检测转过来做姿态估计以为只是多标几个点结果第一批数据就被模型打回。关键点标注的难点集中在三处框与点必须一一绑定点不能游离与纯检测不同YOLO 的关键点标注是复合标注每个关键点必须挂在某个边界框实例上一行文本里框在前、点在后框和点的位置一一对应。如果标注工具导出的点没有归属到具体实例训练时根本无法对齐——这是新手最常踩的结构性错误。可见性是三态而不是有/没有一个人被柱子挡住一半他的左手腕是没标还是标了但看不见两者的语义完全不同前者模型该忽略这个点后者模型该学到这个位置有手腕但被遮挡。把 1标注但不可见错标成 0未标注会直接污染遮挡场景下的学习信号。标注量与一致性压力成倍上升一张图里每个人要标 17 个点以 COCO 人体为例10 张图就是 10 个人 × 17 个点。工作量上去之后同一类物体的关键点顺序在不同标注者手里保持一致就成了必须靠规范来保障的事情而不是靠自觉。YOLO 关键点格式一次讲透一行文本装下框、点和可见性一行 5 个框字段 N 组关键点三元组YOLO 关键点格式的核心规则只有一条一张图对应一个.txt一行一个实例行内先用 5 个字段描述框后面紧跟该实例的所有关键点。class_id cx cy w h x1 y1 v1 x2 y2 v2 ... xn yn vn字段含义取值class_id类别索引整数从 0 开始cx cy边界框中心点坐标归一化到 0–1w h边界框宽高归一化到 0–1x y关键点坐标归一化到 0–1v关键点可见性标记0 / 1 / 2见下表坐标归一化指的是除以图像自身宽高与后续训练时的imgsz无关。框用的是中心点 宽高不是左上角——这一点和 COCO 不同转换时最容易错后文避坑清单第 1 条。可见性标记 v 的三态定义别记混标记语义标注时的判断口径0未标注这个点确实找不到、也不需要标例如裁剪掉了1标注但不可见点坐标已给出但被遮挡2标注且可见点坐标已给出且清晰可见注意1和0都保留坐标位——三元组x y v的位置永远占满模型靠v的值区分状态。若数据集完全没有可见性信息也可以只用x y双元组但 YAML 里的kpt_shape要相应声明为 2 维官方 Tiger-Pose 数据集就是kpt_shape: [12, 2]的无可见性案例。YAML 里的 kpt_shape 与 flip_idx格式的地基配置数据集的 YAML 文件负责声明关键点结构训练框架靠它解析每行.txt。以仓库自带的 coco8-pose.yaml 为例# Keypoints kpt_shape: [17, 3] # 17 个关键点每点 3 维x, y, visible flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15] names: 0: person kpt_names: 0: [nose, left_eye, right_eye, left_ear, right_ear, ...] # 17 个部位名顺序即索引kpt_shape: [17, 3]17 个点 × 3 维。若你的任务是手部 21 点就写[21, 3]。flip_idx左右镜像翻转增强时的关键点下标映射。人体骨架是左右对称的不配置它水平翻转增强后左手腕会跑到右边标签与图像错位。kpt_names定义关键点顺序——这个顺序就是所有标注者必须遵守的点序契约。官方对整套格式的完整定义在 Pose 数据集文档建议收藏备用。关键点标注工具对比按使用场景分三档选不要先找工具再想需求反过来先确定你的团队规模和协作方式再对号入座。个人开发者档本地轻量工具导出即训练RectLabelMac单机桌面工具原生支持导出 YOLO 关键点格式class cx cy w h x y v一行搞定无需二次转换界面轻量适合一个人快速标几百张图的场景。小团队档可配置的 Web 平台Label Studio开源可自建标注界面模板化配置关键点区域可绑定到目标区域内支持多人分任务标注、批量导出导出 COCO JSON 后可用 Ultralytics 自带工具一步转成 YOLO 格式见下一节。大型协作档工业化平台CVATIntel 开源可自建面向大规模标注团队支持视频帧间关键点追踪前一帧的点可拖动续标效率远超逐帧手点、内置质检与任务分配流程适合万图以上、多人并行的关键点检测数据集项目。三档工具关键维度对比表维度RectLabelLabel StudioCVAT适用规模个人 / 几百张图小团队 / 数千张图大团队 / 万图以上关键点标注支持绑定到框支持模板可配支持含骨架连线YOLO 关键点导出直接导出导出 COCO JSON 再转换导出 COCO JSON 再转换多人协作弱中强任务分配 质检视频/帧间追踪无有限有关键点跨帧可续标部署方式单机 App开源自建开源自建选型口诀一个人就选导出 YOLO 格式最直接的要多人分工上可自建的平台要视频级标注和质检体系直接 CVAT。COCO 转 YOLO5 个坑一次列全如果标注工具导出的是 COCO JSONLabel Studio、CVAT 都是就要走 COCO 转 YOLO 这条链路。Ultralytics 在 ultralytics/data/converter.py 内置了转换函数官方流程见 COCO 转 YOLO 指南。下面是转换时真正会翻车的 5 个点坑 1坐标没归一化或者归一化用错了图COCO 的框是[x_min, y_min, w, h]像素坐标YOLO 要求中心点 归一化宽高。转换时cx (x_min w/2) / 图像宽、cy (y_min h/2) / 图像高关键点同样除以图像宽高。常见错误拿错了图片宽高用了训练尺寸 640 而不是原图尺寸、把左上角直接当中心点。坑 2可见性语义映射错位COCO JSON 的keypoints同样是[x, y, v, ...]展平存储v的三态定义0未标注 / 1标注但不可见 / 2标注且可见与 YOLO 一致但 COCO 里未标注的点坐标常是(0, 0, 0)这类占位值。转换时必须保留坐标并正确搬运 v不能因为坐标是 0 就把它当无效点丢掉否则框和点数量对不上。坑 3框与点的绑定错位COCO JSON 里每个 annotation 同时携带bbox和keypoints转成 YOLO 单行时两者必须来自同一条 annotation。自行手写转换脚本时最容易犯的错是先把所有框收集一遍、再把所有点拼一遍多实例图片一图多人直接串位。坑 4自定义数据集忘了 cls91to80Falseconvert_coco的cls91to80参数默认为True它是专门给标准 COCO 80 类做的 91→80 类映射。你自己的关键点数据集必须显式传cls91to80False否则类别索引会被静默映射错模型学到的是错类别。坑 5没开 use_keypoints关键点被整个丢掉转换函数面向检测/分割/姿态多任务关键点不是默认开启的。最小可用示例from ultralytics.data.converter import convert_coco convert_coco( labels_dirmy_dataset/annotations/, # 存放 COCO JSON 的目录 save_dirmy_dataset/converted/, use_keypointsTrue, # 姿态任务必须显式开启 cls91to80False, # 自定义数据集必须关闭 )转换完成后用后文的自查清单抽几张图人工比对JSON 原文 → 生成的 .txt确认点数、点序、可见性与原文件一致再进训练。标注质量自查清单训练前逐项打勾 数据标完不等于能训下面这张清单建议每批数据或每换一批标注者过一遍点序契约一致同一类别的所有实例关键点顺序与 YAMLkpt_names完全一致抽查 10 个实例逐一核对部位名。遮挡标注有口径团队内明确完全看不到→0能看到轮廓/位置→1清晰可见→2遮挡样本单独抽审 20 张。归一化在合理区间所有cx cy w h x y都在[0, 1]内w h不为 0 或负数框贴边时可能出现极小正值但不应越界。每行点数 kpt_shape 声明数[17, 3]的 YAML 配 17 组三元组行数对不上的 .txt 整行作废。flip_idx 已配置且正确对称骨架人体、动物必须配置左右交换映射并验证翻转后第 i 个点确实落在原第 flip_idx[i] 个点的镜像位置。数据分布均衡按姿态站/坐/俯身、朝向正面/侧面/背面、遮挡比例分桶统计单桶占比不超过总量 60%否则模型会在少数姿态上过拟合。动手验证先用 8 张图把链路跑通正式标注前先用官方 COCO8-Pose4 张训练 4 张验证约 1 MB做一次冒烟测试from ultralytics import YOLO model YOLO(yolo26n-pose.pt) model.train(datacoco8-pose.yaml, epochs3, imgsz640) # 跑通即止它能在几分钟内验证你的环境、格式解析和 YAML 配置没有问题。链路通了再把你自查清单全部打勾的自定义数据集喂进去——标注质量是姿态模型上限的第一决定因素格式对了只是及格标得一致才算合格。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考