Ultralytics YOLO 医疗药片检测数据集实战：从 medical-pills.yaml 配置到训练推理全流程

本文基于 Ultralytics 仓库中的 Medical Pills 检测数据集文档（docs/en/datasets/detect/medical-pills.md），完整讲解这一单类药片（pill）目标检测数据集的结构、YAML 配置、自动下载机制，以及如何用 YOLO26 模型完成训练与推理。读完后，你可以直接复用文档中的 Python/CLI 命令在药片质检、包装自动化等制药场景下训练自己的检测模型，并能从源码层面理解 Ultralytics 是如何解析数据集 YAML、触发下载与校验的。

数据集概述：115 张图、单类 pill 的 POC 数据集

Ultralytics Medical Pills 是一个概念验证（proof-of-concept, POC）级别的目标检测数据集，面向制药行业的计算机视觉应用。数据集共包含 115 张标注图片，只有一个类别 pill，按训练/验证划分为两个子集（由 medical-pills.yaml 配置定义）：

划分 (Split)	图片数	说明
Train	92	用于模型训练的标注图片
Validation	23	留作评估与基准测试的验证图片

该数据集没有独立的测试集（test split），其定位是演示模型在制药领域的可用性，典型应用场景包括：

• 药品分拣（Pharmaceutical Sorting）：基于尺寸、形状或颜色自动分拣药片，提升生产效率；
• AI 研发（AI Research and Development）：作为制药用例下计算机视觉算法开发与测试的基准；
• 数字化库存系统（Digital Inventory Systems）：结合自动药片识别实现实时库存监控与补货规划；
• 质量控制（Quality Control）：识别缺陷、异常或污染，保证药片生产的一致性；
• 假药检测（Counterfeit Detection）：将视觉特征与已知标准比对，辅助识别潜在假药。

数据集配置：medical-pills.yaml 逐行解读

数据集的核心配置文件是 ultralytics/cfg/datasets/medical-pills.yaml，定义了数据集路径、类别和下载源。文件实际内容如下：

# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license

# Medical-pills dataset by Ultralytics
# Documentation: https://docs.ultralytics.com/datasets/detect/medical-pills
# Example usage: yolo train data=medical-pills.yaml
# parent
# ├── ultralytics
# └── datasets
#     └── medical-pills ← downloads here (8.19 MB)

# Train/val/test sets as 1) dir: path/to/imgs, 2) file: path/to/imgs.txt, or 3) list: [path/to/imgs1, path/to/imgs2, ..]
path: medical-pills # dataset root dir
train: images/train # train images (relative to 'path') 92 images
val: images/val # val images (relative to 'path') 23 images

# Classes
names:
  0: pill

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

各字段的作用：

• path: medical-pills：数据集根目录名。相对路径会解析到全局数据集目录 DATASETS_DIR 下；
• train / val：相对 path 的图片目录，分别对应 92 张训练图与 23 张验证图；
• names：类别字典，本数据集仅有一类 0: pill；
• download：可选的自动下载地址，压缩包含 8.19 MB 的 zip 包，首次训练时若本地缺少图片会自动拉取。

源码级解读：训练时 YAML 如何被校验与自动下载

当你执行 yolo detect train data=medical-pills.yaml 时，训练器的 get_dataset 流程会进入 ultralytics/engine/trainer.py：对 detect 任务，它调用 check_det_dataset(self.args.data) 完成数据集的下载、校验与路径解析。该函数实现在 ultralytics/data/utils.py，关键行为有：

1. YAML 查找与解析：check_file(dataset) 定位 YAML 文件后读取为字典；若传入的是 zip 文件，会先解压到数据集目录并从中寻找 YAML；
2. 必填键校验：train 和 val 为必需键（validation 会被自动重命名为 val），且必须有 names 或 nc 之一，names 数量与 nc 必须一致——对 Medical Pills 而言即 nc 推导为 1；
3. 路径解析：path 为相对路径且本地不存在时，会解析为 DATASETS_DIR / path，其中 DATASETS_DIR 定义在 ultralytics/utils/init.py，取值为 SETTINGS["datasets_dir"]（默认 ~/ultralytics/datasets，可在 settings 中修改）；
4. 自动触发下载：当 val（或指定的 split）图片路径不存在、且 YAML 提供了以 .zip 结尾的 download URL、且 autodownload=True 时，调用 safe_download 将包下载到数据集目录并解压，完成后日志会打印 Dataset download success。这正是 medical-pills.yaml 中 download 字段的实际生效路径。

此外，若训练时附加 single_cls=True，get_dataset 会把类别名统一覆盖为 item、nc 覆盖为 1（见 ultralytics/engine/trainer.py）——对本身就只有一类 pill 的 Medical Pills 数据集，这一参数通常不需要显式使用。

训练：Python 与 CLI 两种方式

在 Medical Pills 数据集上训练 YOLO26n 模型，100 个 epoch、图像尺寸 640，文档给出了两种等价写法。更完整的参数说明可参考 Training 模式文档。

Python

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="medical-pills.yaml", epochs=100, imgsz=640)

CLI

# Start training from a pretrained *.pt model
yolo detect train data=medical-pills.yaml model=yolo26n.pt epochs=100 imgsz=640

几点源码层面的补充说明：

• data="medical-pills.yaml" 可以直接写裸名：check_det_dataset 会尝试把 coco8 这类裸名称自动补全为 coco8.yaml（ultralytics/data/utils.py），因此也可以传 data="medical-pills"；
• YOLO26n 的体量：从模型配置 ultralytics/cfg/models/26/yolo26.yaml 可以看到，yolo26n 对应 scaling 常量 [0.50, 0.25, 1024]，共 260 层、约 257 万参数、6.1 GFLOPs，是五档（n/s/m/l/x）中最轻的一档，非常适合这种百张图片规模的小数据集；该模型为端到端模式（end2end: True，reg_max: 1）；
• 小数据集训练提示：92 张训练图规模很小，epochs=100 配合 640 输入尺寸是文档推荐的起点。若出现过拟合，可考虑减小 epochs、开启 single_cls=True，或结合数据增强参数（见下文 Mosaic 说明）调整。更多模型能力细节见 YOLO26 文档。

推理：用微调后的模型检测药片

训练完成后，使用微调得到的 best.pt 进行推理。示例使用官方提供的样图 URL 作为输入源：

Python

from ultralytics import YOLO

# Load a model
model = YOLO("path/to/best.pt")  # load a fine-tuned model

# Inference using the model
results = model.predict("https://ultralytics.com/assets/medical-pills-sample.jpg")

CLI

# Start prediction with a fine-tuned *.pt model
yolo detect predict model='path/to/best.pt' imgsz=640 source="https://ultralytics.com/assets/medical-pills-sample.jpg"

更多推理参数（如置信度阈值、NMS 等）可参考 Predict 模式文档。

样本图像与 Mosaic 数据增强

文档在“Sample Images and Annotations”一节展示了一张来自数据集的标注样例图，并特别说明：图中展示的是一个经过 Mosaic 拼接的训练批次——把多张数据集图片合并到一张画布上，以增加训练多样性、提升模型泛化能力。

这一增强在源码中的实现是 ultralytics/data/augment.py 中的 Mosaic 类，它将 4 张（n=4）或 9 张图片拼接为一张 mosaic 图像，并同步拼接、裁剪对应的实例标签。其默认行为由 ultralytics/cfg/default.yaml 中的两个参数控制：

• mosaic: 1.0：每个 batch 应用 Mosaic 增强的概率，默认 1.0，即全程开启；
• close_mosaic: 10：最后 10 个 epoch 关闭 Mosaic（设为 0 则始终开启），让模型在训练末期“看到”未经拼接的真实单图分布。

对 Medical Pills 这类单类、小样本数据集而言，Mosaic 的价值在于：每张药片图片都能以不同位置、不同邻接背景参与训练，等效扩充了样本的构图多样性。

与其他数据集的集成

若需要构建更完整的制药视觉方案，文档建议将 Medical Pills 数据集与其他数据集组合使用：

• 与 package-seg 实例分割数据集结合，用于药盒/药板等包装的识别与分割；
• 与 brain-tumor 等医学影像检测数据集结合，探索端到端的医疗 AI 流水线。

Ultralytics 的 data YAML 机制（train/val 支持目录、txt 清单或路径列表三种形式）使得自定义合并数据集时，只需编写新的 YAML 指向这些子集即可。

引用与许可

Medical Pills 数据集在 AGPL-3.0 许可（LICENSE）下提供。若在研究或开发工作中使用了该数据集，建议按以下 BibTeX 格式引用：

@dataset{Jocher_Ultralytics_Datasets_2024,
    author = {Jocher, Glenn and Rizwan, Muhammad},
    license = {AGPL-3.0},
    month = {Dec},
    title = {Ultralytics Datasets: Medical-pills Detection Dataset},
    url = {https://docs.ultralytics.com/datasets/detect/medical-pills},
    version = {1.0.0},
    year = {2024}
}

常见问题（FAQ）

1. 数据集有多少图片和类别？ 共 115 张图片（92 训练 + 23 验证），无独立测试集，每张图片只标注单一类别 pill。它以 8.19 MB 的自动下载包形式提供，下载配置定义在 ultralytics/cfg/datasets/medical-pills.yaml 中。

2. 如何用 YOLO26 训练该数据集？ 使用上文 Python 或 CLI 方式，100 epoch、imgsz 640。训练细节见 Training 文档，模型细节见 YOLO26 文档。

3. 这个数据集对 AI 项目的价值是什么？ 它支撑药片检测的自动化，服务于假药防范、质量保障与制药流程优化，同时是开发药品安全与供应链效率类 AI 方案的良好起步基准。

4. 如何执行推理？ 用微调后的 YOLO26 模型，通过 Python 或 CLI（见上文推理示例），更多选项参考 Predict 模式文档。

5. 在哪里可以找到 YAML 配置文件？ 仓库内路径为 ultralytics/cfg/datasets/medical-pills.yaml，包含数据集路径、类别与 download 等训练所需的全部元数据。

小结

Medical Pills 数据集虽然只有 115 张图片、单一 pill 类别，但它完整演示了 Ultralytics 检测数据集的“YAML 描述 → 自动下载 → 校验解析 → 训练 → 推理”全链路：配置在 ultralytics/cfg/datasets/medical-pills.yaml，下载与校验逻辑在 check_det_dataset，训练入口在 BaseTrainer.get_dataset，Mosaic 增强在 ultralytics/data/augment.py。对于想在制药质检、药品分拣等垂直场景快速搭建检测基线的开发者，这是一条可直接复制运行的最短路径。