yolo-datasets

Ultralytics YOLO 数据集

训练悄无声息地失败，首要原因是数据集格式错误——训练前请先验证。

最快捷的方式：在 Platform 中准备数据

1. 打开 Platform，在 Annotate 下创建数据集，并选择其任务。
2. 上传图像、视频、ZIP/TAR 压缩包或 NDJSON。可导入现有的 YOLO 标签和 COCO JSON；云存储集成可让受支持的数据保留在原处。
3. 在全屏编辑器中打开图像。使用手动工具进行检测、分割、语义分割、分类、姿态或 OBB 标注。切换到 Smart 模式，即可使用 SAM（检测、分割、语义分割、OBB）或兼容的官方/自定义 YOLO 模型（上述任务，以及姿态）进行标注。
4. 检查 Classes、Charts 和 Errors 选项卡，修正数据划分，并在重要训练任务开始前创建带编号的数据集版本。

Platform 数据集涵盖所有七种 YOLO 任务。深度目标需导入，不能在编辑器中绘制。请参阅 Platform Data 和 Annotation Editor。

要在本地代码中使用同一数据集进行训练，请在 Settings > API Keys 下创建 API 密钥，设置 ULTRALYTICS_API_KEY，并将数据集的 ul:// URI 作为 data 传入：

yolo train model=yolo26n.pt data=ul://username/datasets/dataset-slug epochs=100

如果需要可移植快照，而不是实时访问 Platform，请导出 NDJSON。

images → labels 镜像规则

Ultralytics 会将路径中最后一个 /images/ 片段替换为 /labels/，并将图像扩展名替换为 .txt，以查找标签文件：

dataset/
├── data.yaml
├── images/train/  img001.jpg ...     ├── images/val/  ...
└── labels/train/  img001.txt ...     └── labels/val/  ...

• 与图像同目录、位于 images/ 目录中，或位于名称不是 labels 的目录中的标签，都无法找到 → 训练会因 No labels found 而停止；如果只有部分标签缺失，这些图像会作为背景图像参与训练。
• 文件名必须与主文件名完全匹配（Linux 上区分大小写）。
• 没有标签文件或标签文件为空的图像会作为背景图像参与训练。少量真实背景图像可减少误报；意外缺失标签则会严重损害召回率。

data.yaml 结构

path: /abs/dataset/root # absolute, or omit to use this yaml's folder; a relative value (even `.`) resolves from the CWD (datasets_dir if missing there)
train: images/train # dir, .txt file of image paths, or list of dirs
val: images/val
test: images/test # optional
names: # 0-based, contiguous indices
  0: person
  1: helmet
# pose only:
kpt_shape: [17, 3] # [num_keypoints, dims]; dims 2 (x,y) or 3 (x,y,visibility)
flip_idx: [0, 2, 1, ...] # L/R keypoint swap map — without it, flip augs are auto-disabled
# semantic only (optional — polygon .txt labels in labels/ also work):
masks_dir: masks # per-pixel PNG mask images
# depth only (replace names above; pair depth/{train,val}/*.png or float .npy maps):
# nc: 1
# names: {0: depth}
# depth_scale: 1000 # PNG units per meter; default millimeters

• 分类数据集不使用 yaml：目录结构即为标签（dataset/train/<class>/*.jpg、dataset/val/<class>/*.jpg）；训练时使用 data=path/to/dataset。
• 各任务的标签行格式及其注意事项：编写或调试标签文件时，请阅读此目录中的 label-formats.md。

从其他格式转换——优先使用内置工具

from ultralytics.data.converter import convert_coco

convert_coco(labels_dir="coco/annotations/", use_segments=True, cls91to80=False)  # → segment
convert_coco(labels_dir="coco/annotations/", use_keypoints=True, cls91to80=False)  # → pose

检测标签请省略 use_segments。cls91to80=False 会保留自定义类别 ID（形式为 category_id - 1）；只有在使用官方 COCO 91 类 ID 时，才保留默认值 True。

ultralytics.data.converter 中还包括：convert_dota_to_yolo_obb(dota_root_path)（DOTA → OBB）、convert_segment_masks_to_yolo_seg(masks_dir, output_dir, classes)（索引 PNG → 多边形）、yolo_bbox2segment(im_dir)（通过 SAM 将检测标签升级为分割标签）、convert_to_multispectral(path, n_channels)。

为原始图像文件夹自动标注（检测器提出边界框，SAM 优化掩码）：

from ultralytics.data.annotator import auto_annotate

auto_annotate(
    data="dataset/images/train", det_model="yolo26x.pt", sam_model="sam_b.pt", output_dir="dataset/labels/train"
)

VOC XML/CSV 没有对应的转换器——请编写一个小脚本，按各任务的行格式生成数据（坐标归一化，边界框以中心点为基准）。

划分

from ultralytics.data.split import autosplit

autosplit(path="dataset/images", weights=(0.9, 0.1, 0.0))  # writes autosplit_*.txt lists

将 train:/val: 指向生成的 .txt 文件。同一视频/场景中的帧必须放在同一个数据划分中——按图像随机划分视频帧会导致近似重复内容泄漏到 val 中，并抬高 mAP。对于分类：使用 split_classify_dataset(source_dir, 0.8)。

训练前验证（按顺序执行与任务相关的步骤）

1. YAML/路径检查（非分类） — 验证必填字段、解析配置的路径、检查请求的划分（默认为 val），并且可能自动下载已知数据集。不会统计或解析单张图像及其目标：

   from ultralytics.data.utils import check_det_dataset
   
   check_det_dataset("data.yaml")  # detect/segment/pose/obb/semantic/depth
   

2. 仅用于检测的目视抽查 — 此辅助工具接受五列格式的 class cx cy w h 行；归一化错误或轴顺序颠倒都会显现出来：

   from ultralytics.data.utils import visualize_image_annotations
   
   visualize_image_annotations(
       "images/train/img001.jpg",
       "labels/train/img001.txt",
       label_map={0: "person", 1: "helmet"},
   )
   

   不要将此辅助工具用于分割、姿态、OBB、语义、深度或分类目标；请改用相应任务的训练器绘图。

3. 任务加载器冒烟测试 — 使用匹配的任务/模型/数据运行 1 个 epoch；这会构建真实数据集并生成任务专用的训练图（检测示例）：

   yolo detect train data=data.yaml model=yolo26n.pt epochs=1 fraction=0.1
   # inspect runs/detect/train/train_batch0.jpg — boxes must sit on objects
   

4. 分布合理性检查 — 检查与任务相适应的类别/目标均衡情况及划分泄漏。对于边界框任务，还要检查在训练 imgsz 下的极小边界框，以及背景图像占比。

用于流水线冒烟测试的已知可用小型数据集（自动下载）：coco8.yaml、coco8-seg.yaml、coco8-pose.yaml、dota8.yaml、cityscapes8.yaml、depth8.yaml、imagenet10。

相关页面

• label-formats.md — 各任务精确的标签行格式 + 症状→原因对照表。在编写标签、转换格式或遇到任何与标签相关的错误时阅读。

如果已安装的版本不接受此处的参数或格式，请以错误消息和 yolo checks 为准。