Ultralytics YOLO 上的 COCO 数据集实战：配置、自动下载与训练全流程解析

COCO（Common Objects in Context）是目标检测、实例分割与姿态估计领域最广泛使用的基准数据集。在 Ultralytics 仓库中，围绕 COCO 已形成一套完整的工作流：从 coco.yaml 数据集配置 定义 80 个类别与数据划分，到 check_det_dataset() 在首次训练时自动下载 20.3 GB 数据，再到 Python/CLI 两种训练入口与 COCO JSON 到 YOLO 格式的转换工具 convert_coco()。本文基于仓库文档与源码，完整讲清这套工作流的配置细节、执行路径与实操要点。

COCO 数据集概览与核心特性

COCO 是一个大规模的对象检测、分割与图像描述数据集，旨在推动多类别物体识别研究，也是计算机视觉模型基准测试的通用标尺。其核心特性包括：

• 330K 张图像，其中 200K 张针对检测、分割与描述任务提供了标注；
• 80 个物体类别，涵盖汽车、自行车、动物等常见物体，以及雨伞、手提包、运动器材等更具体的类别；
• 标注形式包括每个图像的目标边界框（bounding boxes）、分割掩码（segmentation masks）以及图像描述文本（captions）；
• 提供 mAP（mean Average Precision，检测任务）与 mAR（mean Average Recall，分割任务）等标准化评测指标，便于横向比较不同模型的表现。

在 Ultralytics 生态中，官方 YOLO 系列模型（如 YOLO26n/s/m/l/x）均以 COCO2017 训练，因此该数据集同时承担"官方预训练权重复现"和"自研模型基准对比"两个角色。仓库中对训练指标的定义可见 ultralytics/utils/metrics.py，验证模式输出的 mAP50、mAP50-95 等指标计算均基于此。

数据集结构：三个子集与各自的用途

COCO2017 划分为三个子集，各自的定位与规模如下：

子集	图像数	用途	标注获取方式
Train2017	118,287 张	训练检测、分割、描述模型	公开发布
Val2017	5,000 张	训练过程中的验证	公开发布
Test2017	20,288 张 test-dev 图像	已训练模型的基准评测	真值不公开，需提交结果至 COCO 评测服务器

需要注意 Test2017 的一个关键约束：其 ground truth 标注不对外公开，模型在该子集上的输出需要提交到 COCO 官方评测服务器才能获得分数。这也是为什么仓库中 coco.yaml 的自动下载脚本只下载 train2017.zip（19 GB，118k 图像）与 val2017.zip（1 GB，5k 图像），并明确注释"test2017.zip excluded: ground truth is withheld, only used for the eval-server test-dev split"——本地训练与验证根本用不到它。

数据集 YAML 配置：coco.yaml 全字段解读

Ultralytics 使用 YAML 文件声明数据集的路径、类别与下载逻辑。COCO 对应配置文件为 ultralytics/cfg/datasets/coco.yaml，其结构可以拆成四部分理解：

路径与数据划分

path: coco # dataset root dir
train: train2017.txt # train images (relative to 'path') 118287 images
val: val2017.txt # val images (relative to 'path') 5000 images
test: test-dev2017.txt # 20288 of 40670 images, submit via COCO eval

• path 是数据集根目录。从源码的 check_det_dataset() 可以看到路径解析规则：若 path 是相对路径且当前目录不存在，会自动回退到数据集默认下载目录 DATASETS_DIR（即 ../datasets/coco）下的同名目录；train/val/test 若为字符串会与 path 拼接为绝对路径。因此标准布局为：

parent/
├── ultralytics        # 本仓库
└── datasets
    └── coco          # 数据下载位置（20.3 GB）
        ├── images/
        │   ├── train2017/
        │   └── val2017/
        ├── labels/
        │   ├── train2017/
        │   └── val2017/
        ├── train2017.txt
        └── val2017.txt

• train2017.txt / val2017.txt 是图像清单文件（每行一个图像相对路径），它们随标签压缩包一起分发，避免依赖目录扫描。

80 个类别定义

names 字段以 0: person … 79: toothbrush 的形式完整列出 80 个类别，从交通类（person、car、airplane、bus）、动物类（bird、cat、elephant、giraffe）到食品类（banana、pizza、cake）与家具家电类（bed、microwave、toaster、refrigerator）。这份类别表是官方预训练权重的标签空间——任何加载官方权重做推理或迁移的模型，输出类别都严格对应这张表。

自动下载块（download 字段）

download: |
  from pathlib import Path

  from ultralytics.utils import ASSETS_URL
  from ultralytics.utils.downloads import download

  # Download labels
  segments = True  # segment or box labels
  dir = Path(yaml["path"])  # dataset root dir
  urls = [ASSETS_URL + ("/coco2017labels-segments.zip" if segments else "/coco2017labels.zip")]
  download(urls, dir=dir.parent)

  # Download data (test2017.zip excluded)
  urls = [
      "http://images.cocodataset.org/zips/train2017.zip",  # 19G, 118k images
      "http://images.cocodataset.org/zips/val2017.zip",   # 1G, 5k images
  ]
  download(urls, dir=dir / "images", threads=3)

这段内嵌 Python 脚本是"首次训练自动下载"的执行体。源码层面，check_det_dataset() 的处理逻辑是：

1. 校验 YAML 中 train/val 等键存在、names/nc 合法（L590-L619）；
2. 解析出 val 实际路径后，若对应文件不存在且 autodownload=True，则取出 YAML 的 download 字段：若以 http 开头且以 .zip 结尾走 safe_download()，若以 bash 开头则按脚本执行（L656-L658），否则像 COCO 这样直接 exec() 内嵌 Python 脚本（L659-L660）；
3. 脚本中 ASSETS_URL 指向 ultralytics/utils/init.py 定义的资产发布地址，标签文件（含 .txt 清单与 YOLO 格式 .txt 标签，约 169 MB segments 版）从该地址下载，而图像本体直接从 images.cocodataset.org 拉取，threads=3 表示并发下载。

segments = True 这一行值得注意：下载的是含分割多边形坐标的标签版本，这样同一份数据即可同时服务 detect 与 segment 两种任务（detect 训练时分割字段会被自动忽略）。

两种下载方式：自动下载与手动脚本

方式一：训练时自动下载（推荐）

首次执行训练时，若本地找不到 val2017.txt 指向的数据，上述 download 块会自动触发，COCO2017 训练+验证数据共 20.3 GB 会下载到 datasets/coco。无需任何预配置。

方式二：手动下载脚本

仓库提供 ultralytics/data/scripts/get_coco.sh 用于手动/部分下载，支持参数：

# 默认下载 train + val 的 box 标签与图像
bash ultralytics/data/scripts/get_coco.sh

# 指定子集与标签类型
bash ultralytics/data/scripts/get_coco.sh --train --val --test --segments

参数	作用
--train	下载 train2017.zip（19 GB，118k 图像）
--val	下载 val2017.zip（1 GB，5k 图像）
--test	下载 test2017.zip（7 GB，41k 图像，可选）
--segments	标签使用含分割多边形的 segments 版本（169 MB），否则为 box 标签版（46 MB）
--sama	标签使用 SAMA 社区精选标注版本（199 MB）

脚本内部通过 curl -L 拉取并 unzip 解压，各下载任务在后台并行执行后 wait 汇总。默认行为（不带参数）等价于 --train --val，与自动下载的内容一致，适合带宽受限需要断点重试或只取验证集的场景。

在 COCO 上训练与验证 YOLO

训练示例

以 YOLO26n 在 COCO2017 上训练 100 个 epoch、图像尺寸 640 为例：

# Python API
from ultralytics import YOLO

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

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

# CLI：从预训练权重开始训练
yolo detect train data=coco.yaml model=yolo26n.pt epochs=100 imgsz=640

关键点说明：

• data="coco.yaml" 是裸数据集名：check_det_dataset() 允许传入不带路径、不带扩展名的数据集名，会自动在 ultralytics/cfg/datasets/ 下查找并补全为 coco.yaml，所以无需写明完整路径。
• 必须传 data 参数：训练命令显式指定数据集后，模型的训练配置会被持久化为模型属性（见下文验证部分）。
• 完整可训练参数（batch、optimizer、lr0、patience 等）详见 训练模式文档；YOLO26 系列的模型结构定义位于 ultralytics/cfg/models/26/，如 yolo26.yaml（detect）、yolo26-seg.yaml（segment）、yolo26-pose.yaml（pose）。

验证示例

训练完成后，在 Val2017 上验证只需：

from ultralytics import YOLO

model = YOLO("path/to/best.pt")
metrics = model.val(data="coco.yaml", imgsz=640)
metrics.box.map   # mAP50-95
metrics.box.map50  # mAP50
metrics.box.maps   # 每个类别的 mAP50-95

yolo detect val model=path/to/best.pt data=coco.yaml imgsz=640

如果验证时不传 data，模型会读取训练时记住的数据集与参数（yolo val model=yolo26n.pt 即可），这是官方权重复现 COCO 指标最省事的方式。

测试用例中的使用方式

仓库测试脚本直接以 coco.yaml 作为真实数据集成件测试对象，例如 tests/test_engine.py 中有 model.train(data="coco.yaml", epochs=1, imgsz=32) 这样的冒烟训练用例，以及 YOLO("yolo26n.pt").val(data="coco.yaml", ...) 的验证用例；tests/test_cli.py 与 tests/test_exports.py 也复用 coco.yaml 覆盖 CLI 与模型导出路径。这意味着只要本地 datasets/coco 存在 val 子集，这些测试就是端到端链路（下载校验 → 训练 → 验证 → 导出）的最直接参照。

马赛克增强：文档示例背后的训练细节

COCO 文档配图展示的训练批次马赛克（mosaic）图像，对应的是 Ultralytics 默认开启的数据增强策略：将 4 张图像拼合为一张训练样本，提高每个 batch 内物体尺度、长宽比与场景背景的多样性，从而增强模型对不同上下文中小/大目标的泛化能力。增强参数定义在 ultralytics/data/augment.py，其默认值（如 mosaic=1.0、mixup、copy_paste 等）在 ultralytics/cfg/default.yaml 中声明。COCO 作为"多尺度、密背景"数据集，从这种组合增强中受益尤为明显；若需关闭，训练时传 mosaic=0.0 即可。

从 COCO JSON 到 YOLO 格式：自有数据的转换路径

COCO 文档中有一句关键提示："Annotations exported from labeling tools in COCO JSON follow this same structure"——大量标注工具（Label Studio、CVAT 等）导出的正是 COCO JSON。Ultralytics 训练使用 YOLO TXT 格式（每图一个 .txt，归一化坐标 class x_center y_center width height），因此仓库提供 ultralytics/data/converter.py 中的 convert_coco()：

from ultralytics.data.converter import convert_coco

convert_coco(
    labels_dir="my_dataset/annotations/",  # 存放 JSON 文件的目录
    save_dir="my_dataset/converted/",      # 转换结果输出目录
    cls91to80=False,                        # 自定义数据集必须设为 False
)

两种格式的字段差异对照：

维度	COCO JSON	YOLO TXT
结构	全部图像共用一个 JSON	每图一个 .txt 标签文件
框格式	[x_min, y_min, w, h]（像素）	class x_center y_center w h（归一化 0-1）
类别 ID	任意 category_id	从 0 开始的连续 ID
分割	segmentation 多边形数组	类别 ID 后跟随多边形坐标

关于 cls91to80 参数，这是理解 COCO 类别体系的一个常见误区：COCO 原始 JSON 的 category_id 并不连续（1-90 共 91 个 ID 中只有 80 个有效类别），因此标准 COCO 数据需要一张 91→80 的映射表，源码即 coco91_to_coco80_class()，返回 91 元素的列表，索引为原始 category_id、值为连续 ID 或 None。转换时：

• 标准 COCO 数据集：cls91to80=True（默认）是正确的；
• 自定义数据集：必须 cls91to80=False，否则类别会被静默地按 COCO 映射表错配；若 category_id 在映射表中无对应项，转换会抛出 TypeError: must be real number, not NoneType 而非生成错误标签。

转换完成后，按转换输出建立目录结构、编写自己的 dataset.yaml（参照 coco.yaml 的 path/train/val/names 结构即可），即可用同一套 model.train(data=...) 接口开始训练。完整的分步指南（含分割与姿态估计变体）见 COCO 标注转 YOLO 文档；若希望直接以 COCO JSON 训练而不生成 .txt，则见 COCO JSON 训练文档。

相关数据集与延伸阅读

• COCO 80 类小子集 coco8.yaml：8 张图像 + 对应标注，用于快速验证环境与代码链路，是仓库测试最常用的数据集；
• COCO128.yaml：128 张图像的中量级子集，适合快速调参；
• coco.yaml 中 test-dev2017.txt 的说明：本地无法评测 test-dev，仅用于向评测服务器提交；
• 其他检测基准数据集（VisDrone、Open Images、Objects365 等）均在 ultralytics/cfg/datasets/ 下提供对应 YAML；
• 完整的检测任务数据集索引见 docs/en/datasets/detect/index.md。

引用与致谢

若在你的研究或开发中使用 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}
}

COCO 数据集采用 CC-BY-4.0 许可，由 COCO Consortium 创建并维护，是计算机视觉社区不可多得的公共资源。

常见问题（FAQ）

问：COCO 数据集为什么对计算机视觉如此重要？ 它是大规模检测/分割/描述三任务数据集，330K 图像、80 类别，且提供 mAP 等标准指标，是模型横向比较的公共标尺。Ultralytics 官方权重全部基于其训练，因此它也是复现官方性能表的基准。

问：如何只用 COCO 训练我自己的 YOLO 模型？ 无需手动下载——model.train(data="coco.yaml", ...) 首次运行时自动下载 20.3 GB 数据；或运行 get_coco.sh 手动控制下载子集与标签类型。

问：官方预训练 YOLO26 模型（yolo26n 等）从哪里来？ 它们正是以本数据集 train2017 子集训练的产物，各尺寸（n/s/m/l/x）在精度与推理速度上形成梯度，可依据部署资源选择；用 data="coco.yaml" 重新训练即可获得可复现的对照基线。

问：Test2017 为什么不在自动下载范围内？ 其真值标注被官方保留，仅用于向评测服务器提交结果打分，本地训练验证链路完全用不到，下载它只会多占 7 GB 空间。