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

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

配置文件这东西，说白了就是告诉YOLO「你要学什么、怎么学、学到什么程度」。很多新手一上来就调代码，改完参数跑不起来，回头一看——yaml格式写错了。嗯，我刚开始也犯过这毛病。

YOLOv5/v8系列用yaml作为配置载体，结构清晰，但坑也不少。今天我把三个核心配置文件拆开讲清楚：模型结构、数据集定义、超参数设置。

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

这个文件定义了YOLO的骨架——从输入到输出的每一层怎么搭。YOLOv5和v8的写法略有不同，但核心逻辑一致。

一句话总结：模型yaml就是一张「网络搭建蓝图」，告诉代码用哪些模块、按什么顺序堆叠。

4.1.1 基本结构

拿YOLOv5s.yaml举例，结构分三块：

# YOLOv5s 模型配置文件
nc: 80  # 类别数（COCO默认80类）
depth_multiple: 0.33  # 深度缩放因子
width_multiple: 0.50  # 宽度缩放因子

# 骨干网络
backbone:
  # [from, number, module, args]
  [[-1, 1, Conv, [64, 6, 2, 2]],   # 0-P1/2
   [-1, 1, Conv, [128, 3, 2]],      # 1-P2/4
   [-1, 3, C3, [128]],
   [-1, 1, Conv, [256, 3, 2]],      # 3-P3/8
   [-1, 6, C3, [256]],
   [-1, 1, Conv, [512, 3, 2]],      # 5-P4/16
   [-1, 9, C3, [512]],
   [-1, 1, Conv, [1024, 3, 2]],     # 7-P5/32
   [-1, 3, C3, [1024]],
   [-1, 1, SPPF, [1024, 5]],        # 9
  ]

# 检测头
head:
  [[-1, 1, Conv, [512, 1, 1]],
   [-1, 1, nn.Upsample, [None, 2, 'nearest']],
   [[-1, 6], 1, Concat, [1]],
   [-1, 3, C3, [512, False]],       # 13
   ...
  ]

每行格式固定：[from, number, module, args]

from：输入来自哪一层（-1表示上一层，数字表示具体层索引）
number：该模块重复次数（会被depth_multiple缩放）
module：模块类型（Conv、C3、SPPF、Concat等）
args：参数列表（通道数、卷积核大小、步长等）

我的习惯：改模型结构时，先看depth_multiple和width_multiple。这两个参数控制模型大小，比直接改层数更优雅。YOLOv5s用0.33/0.50，YOLOv5m用0.67/0.75，YOLOv5l用1.0/1.0。

4.1.2 关键参数解读

参数	作用	典型值	说明
depth_multiple	控制网络深度（层数）	0.33 / 0.67 / 1.0	值越大，层数越多，模型越深
width_multiple	控制网络宽度（通道数）	0.50 / 0.75 / 1.0	值越大，通道越多，特征图更宽
nc	检测类别数	80 / 自定义	必须与数据集类别数一致

我曾经踩过的坑：有一次把nc写成了10，但数据集有12类。训练了两天，mAP一直上不去。检查才发现类别数对不上。改回12后，指标直接涨了15个点。所以——nc一定要和数据集严格一致。

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

这个文件告诉YOLO：你的数据在哪儿、有多少类、每类叫什么名字。说白了就是一份「数据地图」。

4.2.1 标准格式

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

# 类别信息
nc: 80  # 类别数
names: ['person', 'bicycle', 'car', 'motorcycle', 'airplane', 'bus', 'train', 'truck', ...]

4.2.2 路径写法注意事项

路径 vs 相对路径：我个人习惯用相对路径，方便项目迁移。如果团队协作，建议统一根目录。
train/val/test：test不是必须的。没有test时，训练完会用val做评估。
names顺序：必须和标注文件中的类别ID一一对应。ID从0开始。

避坑指南：我曾经把names写成了['cat','dog','person']，但标注文件里person是ID 0、cat是ID 1。结果模型把猫认成人，把人认成猫。嗯，这种低级错误，检查一遍就能避免。

4.2.3 自定义数据集示例

# 我的工业缺陷检测数据集
path: /home/user/projects/defect_detection
train: images/train
val: images/val

nc: 3
names: ['scratch', 'dent', 'crack']

4.3 超参数配置文件（hyp.yaml）

超参数配置，说白了就是「训练策略说明书」。它控制学习率怎么变、数据增强做多狠、正则化用多强。

核心观点：模型结构决定上限，超参数决定你能不能达到这个上限。

4.3.1 核心超参数一览

参数	默认值	作用	调优建议
lr0	0.01	初始学习率	模型大时减小，模型小时增大
lrf	0.2	最终学习率 = lr0 * lrf	一般保持0.1~0.5
momentum	0.937	SGD动量	0.9~0.98之间，越大越稳定
weight_decay	0.0005	权重衰减（L2正则化）	数据少时适当增大
warmup_epochs	3.0	预热轮数	大batch时适当增加
box	0.05	边框损失权重	检测精度低时增大
cls	0.5	分类损失权重	类别混淆时增大
hsv_h	0.015	色调增强幅度	光照变化大时增大
degrees	0.0	旋转增强角度	目标方向多变时设置

4.3.2 数据增强参数详解

YOLO内置了丰富的数据增强策略，都在hyp.yaml里控制：

# 数据增强部分
hsv_h: 0.015       # 色调抖动
hsv_s: 0.7         # 饱和度抖动
hsv_v: 0.4         # 明度抖动
degrees: 0.0       # 旋转角度
translate: 0.1     # 平移比例
scale: 0.5         # 缩放比例
shear: 0.0         # 剪切角度
perspective: 0.0   # 透视变换
flipud: 0.0        # 上下翻转概率
fliplr: 0.5        # 左右翻转概率
mosaic: 1.0        # Mosaic增强概率
mixup: 0.0         # MixUp增强概率

我曾经犯过的错：做车牌检测时，把degrees设成了30度。结果训练集里车牌各种歪，模型学歪了。真实场景下车牌哪有那么大角度？后来改成5度，mAP从0.72涨到0.89。数据增强不是越强越好，要贴合真实场景。

4.3.3 损失权重调优思路

box、cls、obj三个损失权重，控制模型关注什么：

box偏小：边框回归不准确，框的位置飘
cls偏小：类别容易分错，尤其是相似类别
obj偏小：漏检增多，置信度偏低

我个人的调优顺序：先固定cls和obj，调box；框准了再调cls解决分类问题；最后调obj减少漏检。

4.4 三个配置文件的协作关系

训练时，这三个文件各司其职：

model.yaml：告诉代码「网络长什么样」
dataset.yaml：告诉代码「数据在哪里、有多少类」
hyp.yaml：告诉代码「怎么训练、增强多狠」

启动训练时，一行命令把它们串起来：

python train.py --data dataset.yaml --cfg model.yaml --hyp hyp.yaml --epochs 300 --batch-size 16

我的工作流：拿到一个新项目，先花10分钟把三个yaml配好。配好后跑一个mini训练（50个epoch），看看loss能不能正常下降。能下降，再上全量训练。这10分钟能省下后面几天的debug时间。

4.5 常见配置错误与排查

错误现象	可能原因	排查方法
训练报错 KeyError	yaml格式错误（缩进不对）	用在线yaml校验工具检查
loss 不下降	学习率过大或过小	打印lr曲线，检查是否正常衰减
mAP 一直为0	nc与数据集类别数不匹配	打印类别分布，核对names顺序
训练速度极慢	数据增强过强（mosaic+ mixup同时开）	先关掉mixup，只开mosaic
验证集精度远低于训练集	数据增强过强，过拟合到增强后的分布	降低degrees、scale等参数

配置文件看着简单，但每个参数背后都有讲究。嗯，花时间理解它们，比盲目调参高效得多。