如何将 COCO JSON 标注转换为 YOLO 格式？

使用 Ultralytics 的 convert_coco() 函数将 COCO JSON 标注转换为 YOLO .txt 格式。为自定义数据集设置 cls91to80=False：. 转换完成后，重新组织你的标签文件，使 labels/ 与 images/ 目录相对应，然后创建一个 dataset.yaml 文件。有关完整的工作流程，请参阅分步指南。

为什么 COCO 转换后 YOLO 训练显示 "No labels found"？

出现这种情况是因为 convert_coco() 将标签保存到 save_dir/labels/ 内部的子目录中（例如 save_dir/labels/train/），而不是直接保存到数据集与 images/train/ 并列的 labels/train/ 中。YOLO 要求标签与图片并行放置——例如，images/train/img.jpg 需要 labels/train/img.txt。请移动已转换的标签以匹配此结构。请参阅修复目录结构。

cls91to80 在 convert_coco() 中有什么作用？

cls91to80 参数控制 COCO category_id 值如何映射到 YOLO 类别 ID。当为 True（默认值）时，它会应用专为标准 COCO dataset 设计的 coco91_to_coco80_class() 查找表，该数据集包含 80 个具有非连续 ID（1-90）的类别。对于自定义数据集，请务必设置 cls91to80=False——这只会从每个 category_id 中减去 1，以创建从零开始索引的类别 ID。

我可以直接在 COCO JSON 上训练 YOLO 而无需转换吗？

当前的 YOLO 训练流程不支持此操作 — 标注必须是 YOLO .txt 格式，并且每张图像一个文件。请先使用 convert_coco() 转换你的 COCO JSON，然后按照此指南进行组织和训练。有关支持格式的更多信息，请参阅数据集格式。

我可以将 COCO 分割标注转换为 YOLO 格式吗？

可以，在调用 convert_coco() 时使用 use_segments=True，以便在转换后的 YOLO 标签中包含多边形分割掩码。这会生成兼容 YOLO segmentation models 的标签文件：

如何将 COCO 关键点标注转换为 YOLO 格式？

使用 use_keypoints=True 转换 COCO 关键点标注以进行姿态估计训练：. 请注意，如果 use_segments 和 use_keypoints 都设置为 True，则只有关键点会被写入标签文件中 — 分割会被静默忽略。

如何将 COCO 标注转换为 YOLO 格式#

训练 Ultralytics YOLO 模型需要 YOLO 格式的标注，但许多热门的标注工具改为导出 COCO JSON 格式。本指南将向你展示如何将 COCO 标注转换为 YOLO 格式，并开始训练目标检测、实例分割和姿态估计模型。

想要跳过转换步骤吗？

如需直接在 COCO JSON 上训练而不生成 .txt 文件，请参阅在不转换的情况下在 COCO JSON 上训练 YOLO。

为什么要从 COCO 转换为 YOLO？#

COCO JSON 格式将所有标注存储在单个文件中，而 YOLO 为每张图像使用一个带有归一化坐标的文本文件。进行转换是必要的，因为：

YOLO 模型需要 .txt 标签文件，每张图像对应一个文件，其中包含带有归一化坐标的 class x_center y_center width height。
COCO JSON 使用像素坐标，采用 [x_min, y_min, width, height] 格式，并且所有图像共用一个 JSON 文件。
类别 ID 各不相同 — COCO 使用任意的 category_id 值，而 YOLO 要求使用从零开始索引的类别 ID。

功能	COCO JSON	YOLO TXT
结构	所有图像共用一个 JSON 文件	每张图像一个 `.txt` 文件
BBox 格式	以像素为单位的 `[x_min, y_min, width, height]`	`class x_center y_center width height` 已归一化 (0-1)
类别 ID	`category_id`（可以从任意数字开始）	从零开始的索引（从 0 开始）
分割	`segmentation` 字段中的多边形数组	类别 ID 后紧跟多边形坐标
关键点	以像素为单位的 `[x, y, visibility, ...]`	`[x, y, visibility, ...]` 已归一化

快速入门#

转换 COCO 标注并开始训练的最快方法：

from ultralytics.data.converter import convert_coco

convert_coco(
    labels_dir="my_dataset/annotations/",  # directory containing your JSON files
    save_dir="my_dataset/converted/",  # where to save converted labels
    cls91to80=False,  # set False for custom datasets (see warning below)
)

转换完成后，组织你的目录结构、创建 dataset.yaml 并开始训练。请参阅下方的完整分步指南。

自定义数据集：始终使用 `cls91to80=False`

cls91to80=True 默认值仅专为包含 80 个对象类别的标准 COCO dataset 设计，它将 91 个不连续的类别 ID 映射到 80 个连续的类别 ID。对于任何自定义数据集，你必须设置 cls91to80=False — 否则你的类别 ID 将被静默错误映射，导致你的模型学习到错误的类别。

分步转换指南#

准备你的 COCO 数据集#

从标注工具导出的典型 COCO 格式数据集具有以下结构：

my_dataset/
├── images/
│   ├── train/
│   │   ├── img_001.jpg
│   │   ├── img_002.jpg
│   │   └── ...
│   └── val/
│       ├── img_100.jpg
│       └── ...
└── annotations/
    ├── instances_train.json
    └── instances_val.json

每个 JSON 文件均遵循 COCO 数据格式规范，包含三个必需字段 — images、annotations 和 categories：

{
    "images": [{ "id": 1, "file_name": "img_001.jpg", "width": 640, "height": 480 }],
    "annotations": [
        {
            "id": 1,
            "image_id": 1,
            "category_id": 1,
            "bbox": [100, 50, 200, 150],
            "area": 30000,
            "iscrowd": 0
        }
    ],
    "categories": [
        { "id": 1, "name": "helmet" },
        { "id": 2, "name": "vest" }
    ]
}

转换标注#

使用 convert_coco() 函数将你的 COCO JSON 标注转换为 YOLO .txt 格式：

将 COCO 转换为 YOLO 格式

from ultralytics.data.converter import convert_coco

convert_coco(
    labels_dir="my_dataset/annotations/",
    save_dir="my_dataset/converted/",
    cls91to80=False,
)

convert_coco() 为每张标注的图片写入一个 .txt 文件，存放在以各个 JSON 文件命名的 labels/ 子目录中，并删除了 instances_ 前缀（因此 instances_train.json 会生成 labels/train/）。没有标注的图片将被跳过且不会生成标签文件，因此 labels/ 目录树可能不会完全对应每一张图片：

my_dataset/converted/
└── labels/
    ├── train/   # from instances_train.json
    │   ├── img_001.txt
    │   └── ...
    └── val/     # from instances_val.json
        └── ...

重新运行会创建一个新的输出文件夹

convert_coco() 绝不会覆盖现有的 save_dir：如果 my_dataset/converted/ 已经存在，再次运行将会写入到 my_dataset/converted-2/ 中。在重新运行之前请删除先前的输出（或更改 save_dir），否则接下来的步骤将会读取到旧的标签。

组织目录结构#

转换完成后，标签文件需要与你的图片放在同一目录下。YOLO 要求 labels/ 目录与 images/ 目录结构相对应：

import shutil
from pathlib import Path

converted_dir = Path("my_dataset/converted/labels")
dataset_dir = Path("my_dataset")

# convert_coco names each subdirectory after its JSON file (minus the "instances_" prefix),
# so iterate the actual subdirectories instead of assuming "train"/"val".
for src in converted_dir.iterdir():
    if not src.is_dir():
        continue
    dst = dataset_dir / "labels" / src.name
    dst.mkdir(parents=True, exist_ok=True)
    for f in src.glob("*.txt"):
        shutil.move(str(f), str(dst / f.name))

你最终的数据集结构应该如下所示：

my_dataset/
├── images/
│   ├── train/
│   │   ├── img_001.jpg
│   │   └── ...
│   └── val/
│       └── ...
├── labels/
│   ├── train/
│   │   ├── img_001.txt
│   │   └── ...
│   └── val/
│       └── ...
└── dataset.yaml

创建 dataset.yaml#

创建一个将你的 COCO 类别映射到 YOLO 类别名称的 dataset.yaml 配置文件。该文件会告诉 YOLO 你的数据在哪里以及要检测哪些类别：

import json
from pathlib import Path

import yaml

# Read categories from your COCO JSON
with open("my_dataset/annotations/instances_train.json") as f:
    coco = json.load(f)

# Build class names matching convert_coco output (category_id - 1)
categories = sorted(coco["categories"], key=lambda x: x["id"])
names = {cat["id"] - 1: cat["name"] for cat in categories}
# NOTE: convert_coco maps class IDs as category_id - 1, so category_id must
# start from 1. If your categories start from 0, add 1 to each ID first.

# Create dataset.yaml
dataset = {
    "path": str(Path("my_dataset").resolve()),
    "train": "images/train",
    "val": "images/val",
    "names": names,
}

with open("my_dataset/dataset.yaml", "w") as f:
    yaml.dump(dataset, f, default_flow_style=False)

生成的 YAML 文件：

path: /absolute/path/to/my_dataset
train: images/train
val: images/val
names:
    0: helmet
    1: vest

有关数据集 YAML 格式的更多详细信息，请参阅数据集配置指南。

训练你的 YOLO 模型#

准备好转换后的数据集后，训练 YOLO 模型：

在转换后的 COCO 数据上进行训练

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # load a pretrained model
results = model.train(data="my_dataset/dataset.yaml", epochs=100, imgsz=640)

有关训练技巧和最佳实践，请参阅模型训练指南。

验证你的转换#

训练前，抽查几个标签文件以确认类别 ID 和坐标是否正确：

from pathlib import Path

label_file = Path("my_dataset/labels/train/img_001.txt")
for line in label_file.read_text().strip().splitlines():
    parts = line.split()
    cls_id = int(parts[0])
    coords = [float(v) for v in parts[1:5]]
    assert cls_id >= 0, f"Negative class ID {cls_id} — category_id in your JSON may start from 0"
    assert all(0 <= v <= 1 for v in coords), f"Coordinates out of [0, 1] range: {coords}"

提示

如果你看到负数的类别 ID，说明你的 COCO JSON 很可能使用了从 0 开始的 category_id。在运行 convert_coco() 之前，请给 JSON 中的所有 category_id 值加 1，因为它会将类别 ID 映射为 category_id - 1。

常见问题排查#

转换后类别 ID 错误#

如果你的模型能够训练但检测出错误的对象类别，则说明你可能在自定义数据集上使用了 cls91to80=True（默认值）。这会通过 COCO 91 到 80 的查找表来映射你的 category_id 值，该查找表仅对标准 COCO dataset 正确。

解决方法：对于自定义数据集，请始终使用 cls91to80=False。

训练期间未找到标签#

如果训练显示 WARNING: No labels found 或 0 images, N backgrounds，则说明你的标签文件不在预期的目录中。convert_coco() 会将标签保存到单独的输出目录中（例如 save_dir/labels/train/），但 YOLO 要求 labels/ 与数据集目录中的 images/ 平级。

解决方法：移动标签文件以匹配预期的目录结构。确保 labels/train/ 是 images/train/ 的同级目录。

转换期间出现 KeyError#

如果在运行 convert_coco() 时遇到 KeyError: 'bbox' 或类似错误，说明你的 labels_dir 可能包含非实例的 JSON 文件（例如 captions_train2017.json），这些文件具有不同的标注结构。

解决方法：只将实例标注 JSON 文件（例如 instances_train2017.json）放在 labels_dir 中。

转换后标签文件为空#

如果转换完成但 .txt 文件为空或丢失，则所有标注可能都具有 iscrowd: 1（这在使用 SAM 生成的掩码时很常见），或者边界框的宽度或高度为零。

解决方法：检查你的 JSON 标注中是否存在 iscrowd 值。如果使用的是 SAM 掩码，请预处理 JSON 以设置 iscrowd: 0。

来自掩码标注的框形多边形#

如果 use_segments=True 记录了 annotations without a usable polygon，则某些标注不包含 segmentation 值，或者包含一个不是至少三个坐标对列表的值。常见原因包括仅检测导出（这会使该字段缺失或为空）以及 COCO 运行长度编码（{"counts": ..., "size": ...}），诸如 SAM 之类的位掩码导出器会写入该编码；没有外围多边形列表的扁平坐标列表、一到两点轮廓以及其他格式错误的值会以相同方式处理。标注会保留剩余的任何多边形，并且在没有任何多边形时退回到形状与其边界框相似的区段行，因此标签保持有效，但这些行不包含掩码细节。

解决方法：重新导出带有多边形分割的标注，在运行 convert_coco() 之前将 RLE 掩码解码为多边形，或者修正任何格式错误的 segmentation 值。

转换后的标签中类别 ID 不连续#

如果标签文件中的类别 ID 是不连续的（例如 0、4、9 而不是 0、1、2），则说明你的标注工具使用了不连续的 category_id 值。

解决方法：请验证 .txt 文件中的类别 ID 是否与 dataset.yaml 中的 names 字典相匹配。如有必要，请将 ID 重新映射为连续的值。

有关完整的 API 详细信息和参数描述，请参阅 convert_coco API 参考。

常见问题解答#

使用 Ultralytics 的 convert_coco() 函数将 COCO JSON 标注转换为 YOLO .txt 格式。为自定义数据集设置 cls91to80=False：
from ultralytics.data.converter import convert_coco convert_coco(labels_dir="path/to/annotations/", save_dir="output/", cls91to80=False)
转换完成后，重新组织你的标签文件，使 labels/ 与 images/ 目录相对应，然后创建一个 dataset.yaml 文件。有关完整的工作流程，请参阅分步指南。
出现这种情况是因为 convert_coco() 将标签保存到 save_dir/labels/ 内部的子目录中（例如 save_dir/labels/train/），而不是直接保存到数据集与 images/train/ 并列的 labels/train/ 中。YOLO 要求标签与图片并行放置——例如，images/train/img.jpg 需要 labels/train/img.txt。请移动已转换的标签以匹配此结构。请参阅修复目录结构。
cls91to80 参数控制 COCO category_id 值如何映射到 YOLO 类别 ID。当为 True（默认值）时，它会应用专为标准 COCO dataset 设计的 coco91_to_coco80_class() 查找表，该数据集包含 80 个具有非连续 ID（1-90）的类别。对于自定义数据集，请务必设置 cls91to80=False——这只会从每个 category_id 中减去 1，以创建从零开始索引的类别 ID。
当前的 YOLO 训练流程不支持此操作 — 标注必须是 YOLO .txt 格式，并且每张图像一个文件。请先使用 convert_coco() 转换你的 COCO JSON，然后按照此指南进行组织和训练。有关支持格式的更多信息，请参阅数据集格式。
可以，在调用 convert_coco() 时使用 use_segments=True，以便在转换后的 YOLO 标签中包含多边形分割掩码。这会生成兼容 YOLO segmentation models 的标签文件：
from ultralytics.data.converter import convert_coco convert_coco(labels_dir="annotations/", save_dir="output/", use_segments=True, cls91to80=False)
使用 use_keypoints=True 转换 COCO 关键点标注以进行姿态估计训练：
from ultralytics.data.converter import convert_coco convert_coco(labels_dir="annotations/", save_dir="output/", use_keypoints=True, cls91to80=False)
请注意，如果 use_segments 和 use_keypoints 都设置为 True，则只有关键点会被写入标签文件中 — 分割会被静默忽略。

贡献者

RAraimbekovm⁴ GLglenn-jocher³

创建于 4个月前更新于上周