编写数据集 YAML
编写 data.yaml，将 Ultralytics 指向你的文件夹并为类别命名；确保无论从哪个位置都能解析其中的路径，并用 yolo val 进行快速测试。
数据集 YAML 是你的文件夹与每条 Ultralytics 命令之间的约定。路径写错，命令就无法运行；类别顺序写错，命令仍会正常运行，但所有预测都会带上错误的名称，而且没有任何提示。
本课将为药片数据集编写 data.yaml，准确了解 Ultralytics 如何解析其中的路径，让队友在自己的机器上也能使用，并通过一行验证命令进行确认；该命令还会给出训练结果必须超越的基准。
实践操作
编写文件#
Ultralytics Platform 上的数据集自带类别和数据划分；训练时通过类似 data=ul://username/datasets/name 的 URI 指向数据集。在自己的机器上，YAML 就是这个约定。将以下内容保存为 my_dataset/data.yaml：
path: my_dataset # dataset root: absolute, or relative to where you run yolo
train: images/train # relative to path
val: images/val # relative to path
# test: images/test # optional held-out split
names:
0: pill| 键 | 必填 | 含义 |
|---|---|---|
path | 否 | 数据集根目录；train、val 和 test 都是相对于该目录的路径。如果省略，则使用 YAML 文件所在的文件夹 |
train, val | 是 | 图像文件夹、列出图像路径的 .txt 文件，或上述任一类型组成的列表 |
test | 否 | 留出的测试图像，仅使用 split=test 进行评估 |
names | 是 | 类别索引 → 名称；列表长度决定类别数 |
download | 否 | 当图像缺失时，用于获取数据集的 URL 或脚本 |
train 和 val 指向图像文件夹；查找标注时，会将 images 替换为 labels。coco8 YAML 是一个可运行的最简参考，VOC YAML 则展示了更大型的示例。
示例：快速测试#
使用预训练模型进行验证，是最快的端到端检查方式。它会读取每张图像及其标注、报告问题并计算指标：
yolo val model=yolo26n.pt data=my_dataset/data.yamlval: Scanning my_dataset/labels/val... 23 images, 0 backgrounds, 0 corrupt: 100%
Class Images Instances Box(P R mAP50 mAP50-95)
all 23 399 0.0256 0.00251 0.001 0.0002按顺序查看输出：
Scanning my_dataset/labels/val：Ultralytics 实际解析到的文件夹。检查一下它是否是你想要的目录。23 images, 0 backgrounds, 0 corrupt：每张验证图像都有有效的标注文件。如果出现非预期的背景图像或任何文件损坏计数，请返回上一课检查。399个实例：标注文件中共有 399 颗药片。- mAP50-95 为 0.0002：这是正确结果，不是程序出错。COCO 没有药片类别，因此预训练模型无法检测到药片。接近零的分数就是你的基准。如果你的类别确实存在于 COCO 中，例如人或汽车，同一条命令就会给出有意义的基准。
让路径在任何位置都能正确解析#
大多数“找不到图像”错误都是路径错误。Ultralytics 按以下方式解析 path：
datasets_dir 是 Ultralytics 的一项设置；yolo settings 会打印该设置，设置指南则说明如何修改。内置数据集依赖这个回退机制：coco8.yaml 会设置 path: coco8，并提供一个 download: URL，因此无论从哪个文件夹运行，data=coco8.yaml 都能正常工作。
决策规则：
- 只有你自己使用，并且始终从项目文件夹运行？ 使用相对路径
path即可。 - 队友、服务器、CI 或其他文件夹中的笔记本？ 使用绝对路径
path。 - 数据存放在别处，需要自动获取？ 添加带有 zip URL 的
download:。
将类别索引视为契约#
每行标签开头的整数是 names 中的索引。Ultralytics 会检查索引范围——Label class 1 exceeds dataset class count 1——但无法检查 含义。如果你的标注工具导出的是 0: forklift, 1: person，而 YAML 中写的是 0: person, 1: forklift，训练仍会成功，验证 mAP 看起来也正常，但每个预测都会带上错误的名称。为类别列表保留唯一可信来源，并让标注工具、转换脚本、YAML 和部署代码共用它。
避免这些错误#
症状：出现 FileNotFoundError: Dataset 'data.yaml' images not found, missing path '.../datasets/my_dataset/images/val'，并提示数据集下载目录。原因：你从另一个文件夹运行，因此相对路径 path 不存在，Ultralytics 转而在 datasets_dir 下查找。解决方法：从项目文件夹运行，或将 path 设为绝对路径。
在不重新标注的情况下交换或删除 names 中的条目，会悄无声息地改变每个标签的含义。模型仍会训练和预测，但类别会错，而且不会报错。将新类别添加到末尾，并使用下一个可用索引；绝不要给现有类别重新编号。
val: [images/val_day, images/val_night] 会将两个文件夹合并为一个验证集，并报告一个数值。若要分别查看白天和夜间的数据，或将精心筛选的回归集与新采集的生产样本进行对比，请为每个数据集保留一个 YAML 文件，并分别进行验证。只评估一次、使用 split=test 的 test 划分在正确划分数据集中有介绍。
增强和缓存等训练设置是传给 train 的参数，而不是 YAML 键；所有设置都在配置参考中。
显示解答
path: /home/you/projects/pills/my_dataset # absolute path to the dataset root
train: images/train
val: images/val
names:
0: pillval: Scanning /home/you/projects/pills/my_dataset/labels/val... 23 images, 0 backgrounds, 0 corrupt
all 23 399 0.0256 0.00251 0.001 0.0002在另一个文件夹中，相对路径版本因 Dataset ... images not found 而失败，因为 my_dataset 在那里不存在，datasets_dir 回退路径中也没有副本。绝对路径 path 消除了这一步查找。基线 mAP50-95 约为 0：预训练模型没有药丸类别。