📚 课程目录第4章配置文件详解

4、配置文件详解：模型配置文件（yaml）结构、数据集配置文件（yaml）编写、超参数配置文件解析

配置文件这东西，说白了就是 YOLO 的「说明书」。你想想看，一个模型怎么搭、数据从哪读、训练怎么跑，全得靠这几个 yaml 文件来告诉它。我刚开始接触 YOLOv5 的时候，总觉得配置文件可有可无，直接改代码多痛快。结果有一次改乱了网络结构，模型直接不收敛，查了两天才发现是 yaml 里一个缩进写错了。嗯，从那以后我再也不敢小看这些配置文件了。

YOLOv11 延续了 Ultralytics 的设计哲学——配置驱动。你不需要动一行 Python 代码，改改 yaml 就能换模型、调参数。这一章，我就带你把这几个配置文件彻底吃透。

核心要点：YOLOv11 的三大配置文件——模型配置（model.yaml）、数据集配置（dataset.yaml）、超参数配置（hyp.yaml）。掌握它们，你就掌握了 YOLOv11 的「遥控器」。

4.1 模型配置文件（model.yaml）结构

模型配置文件，就是 YOLOv11 的「骨架图纸」。它定义了网络长什么样——从输入到输出，每一层用什么模块、参数怎么设，全写在这里面。

YOLOv11 的模型配置沿用了 Ultralytics 的 yaml 格式，核心结构就三部分：参数区（parameters）、主干网络（backbone）、检测头（head）。我带你拆开看。

4.1.1 参数区

文件最开头，一般是几个全局参数：

# YOLOv11 模型配置示例（精简版）
nc: 80                    # 类别数量
scales:                   # 模型缩放因子
  n: [0.50, 0.25, 1024]  # [深度因子, 宽度因子, 最大通道数]
  s: [0.50, 0.50, 1024]
  m: [0.50, 0.75, 1024]
  l: [1.00, 1.00, 1024]
  x: [1.00, 1.25, 1024]

这里 nc 就是你要检测的类别数。COCO 数据集是 80 类，换成你自己的数据集，记得改这个值。scales 定义了不同版本模型的缩放系数——n/s/m/l/x 分别对应 Nano 到 XLarge。我个人习惯先用 m 版本调参，稳定了再换 l 或 x 冲精度。

小技巧：如果你显存不够，把 scales 里的宽度因子调小一点，模型立马瘦身。我曾经在 4GB 显存的卡上跑 YOLOv11n，宽度因子降到 0.25，照样能跑，就是精度掉了点。

4.1.2 主干网络（backbone）

主干网络负责提取特征。YOLOv11 的 backbone 主要用 C2f 和 SPPF 模块：

backbone:
  - [-1, 1, Conv, [64, 3, 2]]     # 0-P1/2
  - [-1, 1, Conv, [128, 3, 2]]    # 1-P2/4
  - [-1, 3, C2f, [128, True]]     # 2
  - [-1, 1, Conv, [256, 3, 2]]    # 3-P3/8
  - [-1, 6, C2f, [256, True]]     # 4
  - [-1, 1, Conv, [512, 3, 2]]    # 5-P4/16
  - [-1, 6, C2f, [512, True]]     # 6
  - [-1, 1, Conv, [1024, 3, 2]]   # 7-P5/32
  - [-1, 3, C2f, [1024, True]]    # 8
  - [-1, 1, SPPF, [1024, 5]]      # 9

每一行的格式是：[输入层, 重复次数, 模块名, [参数列表]]。-1 表示上一层的输出作为输入。你看第 2 行，C2f 重复了 3 次，通道数 128。YOLOv11 的 C2f 比 v8 多了个残差连接，梯度流更顺畅。

注意：修改 backbone 结构时，一定要保证下采样倍数正确。P3/8 表示下采样 8 倍，P4/16 是 16 倍，P5/32 是 32 倍。搞错了这个，特征图尺寸对不上，模型直接报错。

4.1.3 检测头（head）

检测头负责在特征图上做预测。YOLOv11 的 head 用了 Detect 模块：

head:
  - [-1, 1, nn.Upsample, [None, 2, "nearest"]]  # 10 上采样
  - [[-1, 6], 1, Concat, [1]]                    # 11 拼接
  - [-1, 3, C2f, [512]]                          # 12
  - [-1, 1, nn.Upsample, [None, 2, "nearest"]]  # 13
  - [[-1, 4], 1, Concat, [1]]                    # 14
  - [-1, 3, C2f, [256]]                          # 15
  - [15, 1, Conv, [256, 3, 2]]                   # 16 下采样
  - [[-1, 12], 1, Concat, [1]]                   # 17
  - [-1, 3, C2f, [512]]                          # 18
  - [18, 1, Conv, [512, 3, 2]]                   # 19
  - [[-1, 9], 1, Concat, [1]]                    # 20
  - [-1, 3, C2f, [1024]]                         # 21
  - [[15, 18, 21], 1, Detect, [nc]]              # 22 Detect(P3, P4, P5)

这里用了 FPN+PAN 结构，上采样拼接再下采样。最后 Detect 模块从三个尺度（P3、P4、P5）输出预测结果。我刚开始看这个配置时，总觉得层数太多记不住。后来发现一个规律——看数字编号，负数是引用前面的层，正数是层号。搞明白这个，读配置就快了。

4.2 数据集配置文件（dataset.yaml）编写

数据集配置文件，就是告诉 YOLO：「你的训练数据在哪、验证数据在哪、要检测哪些东西」。

一个标准的 dataset.yaml 长这样：

# 数据集配置文件示例
path: ../datasets/coco128  # 数据集根目录
train: images/train2017    # 训练集图片路径（相对 path）
val: images/val2017        # 验证集图片路径（相对 path）
test:                      # 测试集（可选）

# 类别信息
nc: 80                     # 类别数量
names:                     # 类别名称列表
  0: person
  1: bicycle
  2: car
  # ... 省略中间类别
  79: toothbrush

这里有几个坑，我一个个说。

第一，路径问题。path 是根目录，train 和 val 是相对路径。我建议用路径，省得出错。曾经有一次我换了台机器跑训练，相对路径对不上，折腾了半小时才发现是路径问题。

第二，类别名称顺序。names 的索引必须从 0 开始连续编号，不能跳号。你的标注文件里的类别 ID 要和这里一一对应。比如标注里 ID 是 2，那 names[2] 就应该是「car」。

第三，图片和标签的对应关系。YOLO 要求图片和标签文件名相同，只是后缀不同。图片是 000001.jpg，标签就是 000001.txt。标签文件放在和图片同名的目录下，但目录名是 labels 而不是 images。比如：

datasets/coco128/
├── images/
│   ├── train2017/
│   │   ├── 000001.jpg
│   │   └── ...
│   └── val2017/
│       ├── 000100.jpg
│       └── ...
└── labels/
    ├── train2017/
    │   ├── 000001.txt
    │   └── ...
    └── val2017/
        ├── 000100.txt
        └── ...

重要：YOLOv11 会自动根据 train 路径推断标签路径——把 images 换成 labels，目录结构不变。所以你的数据集目录结构必须严格遵循这个约定。

4.3 超参数配置文件解析

超参数配置文件，就是训练的「调节旋钮」。学习率、批量大小、数据增强强度……全在这里调。

YOLOv11 的超参数配置在 ultralytics/cfg/default.yaml 里，核心参数我整理成了一张表：

参数名	默认值	说明	我的建议
`lr0`	0.01	初始学习率	小数据集用 0.001，大数据集用 0.01
`lrf`	0.01	最终学习率（lr0 的倍数）	一般保持默认
`momentum`	0.937	SGD 动量	0.9~0.98 之间调，越大越稳定
`weight_decay`	0.0005	权重衰减（L2 正则化）	防止过拟合，小数据集可适当增大
`warmup_epochs`	3.0	预热轮数	大 batch 时建议增加到 5
`batch`	16	批量大小	根据显存调整，能大则大
`hsv_h`	0.015	色调增强强度	0~0.1，颜色变化大的场景可调高
`hsv_s`	0.7	饱和度增强强度	0~1，光照变化大时调高
`hsv_v`	0.4	明度增强强度	0~1，暗光场景可调高
`degrees`	0.0	旋转角度范围	0~180，物体方向多变时使用
`translate`	0.1	平移比例	0~1，物体位置多变时使用
`scale`	0.5	缩放比例	0~1，物体尺寸多变时使用
`fliplr`	0.5	水平翻转概率	0.5 一般够用，对称物体可调高

数据增强这部分，我多说两句。YOLOv11 默认的增强策略已经很猛了，但具体场景要具体调。比如我做工业检测时，产品方向是固定的，就把 degrees 设成 0，fliplr 也关了——因为翻转后的样本不符合实际情况，反而会误导模型。

反过来，做自动驾驶场景时，光照变化大、物体角度多变，我就把 hsv_h 调到 0.05，degrees 调到 30，模型鲁棒性明显提升。

调参经验：我一般先跑 50 个 epoch 看 loss 曲线。如果 loss 降得慢，就调大 lr0；如果 loss 震荡厉害，就调大 momentum 或减小 lr0。数据增强别一上来就拉满，先默认跑一轮，再根据过拟合情况逐步增加。

4.4 配置文件实战：从零搭建一个自定义数据集

光说不练假把式。我带你走一遍完整流程——从标注好的数据到跑通训练。

第一步：整理数据集目录

my_dataset/
├── images/
│   ├── train/
│   │   ├── img_001.jpg
│   │   ├── img_002.jpg
│   │   └── ...
│   └── val/
│       ├── img_100.jpg
│       └── ...
└── labels/
    ├── train/
    │   ├── img_001.txt
    │   ├── img_002.txt
    │   └── ...
    └── val/
        ├── img_100.txt
        └── ...

第二步：编写 dataset.yaml

# my_dataset.yaml
path: /home/user/projects/my_dataset
train: images/train
val: images/val

nc: 3
names:
  0: cat
  1: dog
  2: bird

第三步：选择模型配置

直接用官方提供的 yolov11n.yaml，只改 nc 为 3：

# yolov11n_custom.yaml
nc: 3  # 改成你的类别数
# 其他部分保持原样

第四步：调整超参数

新建一个 hyp_custom.yaml，只覆盖你要改的参数：

# hyp_custom.yaml
lr0: 0.005          # 小数据集，学习率调低
degrees: 0.0        # 我的物体方向固定，不旋转
fliplr: 0.0         # 不翻转
hsv_h: 0.02         # 轻微颜色增强

第五步：启动训练

yolo train model=yolov11n_custom.yaml data=my_dataset.yaml hyp=hyp_custom.yaml epochs=100 batch=16 imgsz=640

搞定。就这么简单。

避坑提醒：我曾经犯过一个低级错误——标注文件里类别 ID 从 1 开始，但 yaml 里 names 从 0 开始。结果模型把「猫」识别成「狗」，因为 ID 对不上。检查标注文件时，记得确认 ID 从 0 开始。

4.5 本章小结

配置文件是 YOLOv11 的「遥控器」。你不需要改一行代码，改改 yaml 就能换模型、换数据、调参数。记住三个核心：

模型配置：定义网络骨架，改 nc 和 scales 最常用
数据集配置：告诉 YOLO 数据在哪、要检测什么，路径和类别名别搞错
超参数配置：训练过程的调节旋钮，数据增强要因场景而异

把这些搞明白了，YOLOv11 你就掌握了三分之一。剩下的，就是跑数据、调参数、看结果——这些我们后面章节慢慢聊。