Ultralytics COCO128 数据集详解：YOLO26 目标检测训练调试与流水线验证的轻量级方案

COCO128 是 Ultralytics 提供的小型目标检测数据集，由 COCO train 2017 集合的前 128 张图片构成，覆盖全部 80 个 COCO 物体类别，是测试与调试检测模型、验证训练流水线错误、以及在上完整数据集之前做"sanity check"的理想选择。本文围绕仓库中的官方文档 docs/en/datasets/detect/coco128.md 展开，结合数据集 YAML 配置、自动下载机制和默认增广参数等仓库源码，完整讲解 COCO128 的结构、配置、训练用法与底层实现细节，读完后可直接复制文中的 Python/CLI 示例完成一次端到端的检测训练验证。

一、COCO128 的定位：小而全的检测测试集

COCO128 取自语料库规模庞大的 COCO（Common Objects in Context）数据集，仅保留 train 2017 的前 128 张图像，因此它具备"规模可控 + 类别完整"的特点：

• 规模小：完整压缩包仅 7 MB，首次训练时自动下载即可，几分钟内即可完成一个完整训练周期，非常适合快速迭代；
• 类别全：128 张图片覆盖了全部 80 个 COCO 目标检测类别（person、car、dog、cup 等），足以暴露类别相关的流水线错误（如标签越界、类别名与索引不匹配）；
• 训验同源：train 与 val 使用同一批 128 张图片。这个设计是刻意的——COCO128 的目标不是评估模型泛化能力，而是以最小的数据开销验证"训练-验证"整条链路能正常跑通。

在 Ultralytics 的 COCO 系列数据集中，COCO128 处于中间位置：

数据集	规模	适用场景
COCO8	8 张图（4 train / 4 val）	极快速的冒烟测试与调试
COCO128	128 张图（train/val 同源）	平衡多样性与开销，训练流水线验证
完整 COCO	118K+ 张训练图	完整基准训练，资源开销大

因此典型的工程流程是：先用 COCO128 验证环境与代码无异常，再切换到完整 COCO 或自建数据集做正式训练。

二、数据集目录结构

解压后的目录结构非常简洁，图片与标签按同一划分目录组织：

coco128/
├── images/
│   └── train2017/   # 128 张图片（同时用作训练与验证）
└── labels/
    └── train2017/

标签采用 YOLO 标签格式：每张图片对应一个 .txt 文件，每行一个目标，格式为 class_id x_center y_center width height（坐标均已归一化到 0–1）。这种"图像目录 + 同级 labels 目录"的组织方式可以直接套用到自建数据集上，COCO128 因而也是一个现成的标注组织参考样例。

三、数据集 YAML 配置：逐字段解读

Ultralytics 用一份 YAML 文件描述数据集的路径、类别与下载源。COCO128 的配置维护在 ultralytics/cfg/datasets/coco128.yaml，完整内容如下（注释与 80 个类别做了整理，原文包含全部类别列表）：

# COCO128 dataset (first 128 images from COCO train2017)
# parent
# ├── ultralytics
# └── datasets
#     └── coco128 ← downloads here (7 MB)

# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list
path: coco128            # dataset root dir
train: images/train2017  # train images (relative to 'path'), 128 images
val: images/train2017    # val images (relative to 'path'), 128 images
test:                    # test images (optional)

# Classes（完整列表见仓库文件，共 80 类）
names:
  0: person
  1: bicycle
  2: car
  3: motorcycle
  # ...
  77: teddy bear
  78: hair drier
  79: toothbrush

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

各字段的作用：

• path：数据集根目录。相对路径会基于当前工作目录解析；训练框架会在本地找不到数据集时按 path 定位下载目标位置；
• train / val：图像子目录（相对于 path），二者都指向 images/train2017，印证了训验同源的设计。字段值支持三种形式：目录、图像路径列表文件（.txt）、或路径列表；
• test：可选，COCO128 未设置测试集；
• names：0–79 的类别索引到类别名的映射。这是 YOLO 数据格式的核心约定——标签文件里只写整型 class id，模型输出到人类可读名称的翻译完全依赖这份映射；
• download：可选的自动下载地址。训练时若本地无数据集，框架会直接从这个 URL 拉取压缩包并解压，这正是"首次训练自动下载 7 MB 数据"的实现来源。

源码视角：YAML 是如何被解析与校验的

训练入口并不是直接读文件，而是经过数据集检查函数 check_det_dataset。从源码结构看，它的处理流程为：

1. 支持裸数据集名：即使传入 coco128 而不是 coco128.yaml，函数也会尝试补全为 coco128.yaml；
2. 若传入的是 zip/tar 压缩包，会先解压到数据集目录并自动定位其中的 YAML；
3. 加载 YAML 后强制校验 train、val 键必须存在（缺失会抛出 SyntaxError），并校验 names 或 nc 至少提供其一，同时对各键做类型检查（如 nc 必须是整数值）；
4. 最后解析并返回数据集信息字典（路径、类别、训练/验证目录），供训练器构建 Dataset 对象使用。

此外，check_images_labels 这类逐对校验函数会检查每张图片与其标签文件：标签行数是否匹配检测（5 列：class + xywh）、segment（5 列以上）或关键点格式，坐标是否归一化（容差 ±0.01），以及 class id 是否越界超过 num_cls。对 COCO128 而言，这意味着 80 个类别索引的任何写错都会在训练启动阶段被明确报错，而不是静默错标。

四、获取数据集的两种方式

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

首次执行训练命令时，框架检测到本地没有 coco128 数据集，会自动从 YAML 中 download 字段指向的地址下载并解压，无需任何手动操作。

方式二：手动运行下载脚本

仓库提供了独立脚本 ultralytics/data/scripts/get_coco128.sh，可以预先下载数据集：

bash data/scripts/get_coco128.sh

脚本内部使用 curl 从 Ultralytics assets 发布页拉取 coco128.zip，解压到 ../datasets 目录（即工作目录下的 datasets/coco128）。脚本注释还提示存在 coco128-segments.zip（68 MB）变体——该变体在标签中保留了分割多边形信息，用于实例分割任务，对应配置文件 ultralytics/cfg/datasets/coco128-seg.yaml。

五、在 COCO128 上训练 YOLO26

以 YOLO26n 模型为例，在 COCO128 上训练 100 个 epoch、输入尺寸 640 的标准示例如下。完整参数列表参见 训练模式文档。

Python 方式

from ultralytics import YOLO

# 加载模型
model = YOLO("yolo26n.pt")  # 加载预训练权重（训练时推荐）

# 训练模型
results = model.train(data="coco128.yaml", epochs=100, imgsz=640)

CLI 方式

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

关键点说明：

• data 参数只写 coco128.yaml（不带路径）即可，因为该 YAML 内置在 ultralytics/cfg/datasets/ 目录中，框架会自动在内置数据集目录中查找；
• model=yolo26n.pt 使用预训练权重，比随机初始化收敛更快，官方文档明确建议训练时加载预训练模型；
• 训练完成后，results 对象（Python）或日志指标即可用来判断流水线是否健康：如果 loss 正常下降、mAP 能出数值，说明数据路径、标签格式、增广管线全部正确，可以放心切换到正式数据集。

测试用例中的验证方式

仓库的测试套件本身就是"用 COCO128 做快速回归验证"的实践样板。例如 tests/test_cuda.py 中的 GPU 测试以极小配置跑通完整训练链路：

results = YOLO(MODEL).train(data="coco128.yaml", imgsz=64, epochs=1, device=device, batch=15, val=False)

而 tests/test_python.py 则用分割变体 coco128-seg.yaml 验证 YOLOE 模型的分割推理路径。这类调用展示了 COCO128 的典型用法：配合小 imgsz、少 epochs 做低成本回归测试。

六、Mosaic 增广：小数据集上的关键增益

COCO128 文档中给出的示例图展示了一个经过 Mosaic 拼接的训练批次——多张图片被拼成一张大图共同输入网络。这解释了文档中关于 Mosaic 的说明：它把多个样本组合成单张训练图像，从而增加每个批次内目标种类与场景的多样性，改善模型对不同尺度、长宽比目标的泛化能力。

从源码默认配置 ultralytics/cfg/default.yaml 可以看到 Mosaic 的两个关键参数：

close_mosaic: 10  # (int) 最后 N 个 epoch 关闭 mosaic 增广（0 表示全程开启）
mosaic: 1.0        # (float) mosaic 增广触发概率

• mosaic=1.0 表示默认每个 batch 都会触发 Mosaic 拼接；
• close_mosaic=10 表示最后 10 个 epoch 自动关闭 Mosaic，让模型在真实单图分布上收尾，避免训练后期见到的人造分布干扰收敛。

对 COCO128 这类仅 128 张图的数据集，Mosaic 的价值尤为突出：128 张图按常规 batch 划分，每张图每 epoch 只被"独立"见到一次，而 Mosaic 让每张图在拼接中与多张不同场景的图反复组合，等价于以极低成本放大了样本的组合多样性——这正是文档 FAQ 中"小数据集上 Mosaic 特别有价值"结论的技术原因。

七、COCO128 能否用于检测以外的任务

COCO128 默认面向目标检测，但文档同时给出了扩展到其它任务的可行路径：

• 实例分割：需要使用包含分割多边形的标签变体。仓库中已有现成配置 coco128-seg.yaml，配合 coco128-segments.zip 下载即可用于分割训练；
• 关键点检测：COCO train 2017 中的人体标注含 17 个关键点，理论上 COCO128 对应图像可适配关键点任务，但仓库未提供对应的 128 子集关键点 YAML，实际使用时可参考完整的 COCO-pose 类配置；
• 迁移学习：将 COCO128 作为预训练后微调自定义任务的起点，先验证微调流程再上业务数据。

更系统的任务划分可参考 任务概览 与 数据集总览 文档。

八、常见问答（FAQ）

COCO128 的用途是什么？ 它是 COCO train 2017 前 128 张图片的紧凑子集，主要用于测试和调试目标检测模型、实验新的检测方案，以及在扩展到更大数据集之前验证训练流水线。体积可控、类别完整，适合快速迭代。

如何训练？ 见第五节的 Python 与 CLI 示例：model.train(data="coco128.yaml", epochs=100, imgsz=640) 或 yolo detect train data=coco128.yaml model=yolo26n.pt epochs=100 imgsz=640。更多训练参数（batch、optimizer、lr0、增广开关等）见 训练文档。

COCO128 与其它 COCO 变体如何取舍？ COCO8（8 张）适合最快速的冒烟测试；COCO128（128 张）在多样性与开销之间取得平衡，是训练验证的推荐基准；完整 COCO（118K+ 张）用于正式模型训练，资源开销大。三者的 YAML 配置均在 ultralytics/cfg/datasets/ 中，切换只需替换 data 参数。

九、引用与致谢

若在研究中使用 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}
}

COCO128 作为其中面向工程调试的子集，由 Ultralytics 整理维护；YOLO26 模型本身可参考 YOLO26 模型文档。