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

4. 配置文件解读：data.yaml、model.yaml、hyp.yaml 三大核心配置文件逐行解析

说实话，很多新手拿到 YOLO 项目，第一反应就是直接跑训练脚本。结果呢？要么报错说路径找不到，要么 loss 直接炸了。我当年也踩过这个坑——花了一整天 debug，最后发现是 data.yaml 里少写了一个冒号。

配置文件就是 YOLO 的「说明书」。你告诉它数据在哪、模型长什么样、训练怎么调参。今天我就带你把这三大文件从头到尾捋一遍。

  核心认知： data.yaml 管数据，model.yaml 管网络结构，hyp.yaml 管训练超参。三个文件各司其职，缺一不可。

4.1 data.yaml —— 数据说明书

这个文件最简单，但也最容易出错。我见过有人把路径写错，训练跑了两天发现模型学了一堆空气。

# 训练集和验证集的图片路径
train: /data/dataset/images/train
val: /data/dataset/images/val

# 类别数量
nc: 80

# 类别名称列表（顺序必须和标注文件一致）
names: ['person', 'bicycle', 'car', 'motorcycle', 'airplane', 'bus', ...]

逐行拆开看：

train / val：图片文件夹路径。支持路径和相对路径。我个人习惯用路径，省得换目录时出幺蛾子。
nc：类别总数。这个数要是写错了，模型输出维度全乱套。
names：类别名称列表。顺序必须和标注文件里的 class_id 一一对应。我曾经接手一个项目，names 顺序和标注对不上，模型 mAP 一直 0.0，查了三天才发现。

避坑指南： 如果你用了 test 字段，记得检查测试集路径是否存在。YOLOv5/v8 对 test 的处理方式不太一样，有的版本直接忽略，有的会报错。

4.2 model.yaml —— 网络结构蓝图

这个文件决定了你的模型长什么样。YOLOv5 和 YOLOv8 的写法略有不同，但核心逻辑是一样的。

拿 YOLOv5 的 model.yaml 举例：

# parameters
nc: 80  # number of classes
depth_multiple: 0.33  # model depth multiple
width_multiple: 0.50  # layer channel multiple

# anchors
anchors:
  - [10,13, 16,30, 33,23]  # P3/8
  - [30,61, 62,45, 59,119]  # P4/16
  - [116,90, 156,198, 373,326]  # P5/32

# YOLOv5 backbone
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
  ]

# YOLOv5 head
head:
  [[-1, 1, Conv, [512, 1, 1]],
   [-1, 1, nn.Upsample, [None, 2, 'nearest']],
   [[-1, 6], 1, Concat, [1]],  # cat backbone P4
   [-1, 3, C3, [512, False]],  # 13

   [-1, 1, Conv, [256, 1, 1]],
   [-1, 1, nn.Upsample, [None, 2, 'nearest']],
   [[-1, 4], 1, Concat, [1]],  # cat backbone P3
   [-1, 3, C3, [256, False]],  # 17 (P3/8-small)

   [-1, 1, Conv, [256, 3, 2]],
   [[-1, 14], 1, Concat, [1]],  # cat head P4
   [-1, 3, C3, [512, False]],  # 20 (P4/16-medium)

   [-1, 1, Conv, [512, 3, 2]],
   [[-1, 10], 1, Concat, [1]],  # cat head P5
   [-1, 3, C3, [1024, False]],  # 23 (P5/32-large)

   [[17, 20, 23], 1, Detect, [nc, anchors]],  # Detect(P3, P4, P5)
  ]

关键参数解读：

参数	含义	我的经验
depth_multiple	控制网络层数的缩放系数	0.33 是 nano，0.67 是 small，1.0 是 medium
width_multiple	控制通道数的缩放系数	0.50 对应 small，0.75 对应 medium
anchors	预设的锚框尺寸	小目标用小的 anchor，大目标用大的
backbone	特征提取网络	负责从图片中提取特征
head	检测头	负责在特征图上做预测

小技巧： 如果你要改模型结构，建议先跑一次小数据集验证。我习惯用 100 张图片跑 10 个 epoch，确认 loss 能正常下降再上全量数据。

4.3 hyp.yaml —— 训练超参调优手册

这个文件是调参的核心。说白了，它控制着模型怎么学、学多快、学多久。

# 学习率相关
lr0: 0.01          # 初始学习率
lrf: 0.01          # 最终学习率（lr0 * lrf）
momentum: 0.937    # SGD momentum / Adam beta1
weight_decay: 0.0005  # 权重衰减

# 热身阶段
warmup_epochs: 3.0     # 热身 epoch 数
warmup_momentum: 0.8   # 热身初始 momentum
warmup_bias_lr: 0.1    # 热身初始偏置学习率

# 损失函数权重
box: 0.05        # box loss 增益
cls: 0.5         # cls loss 增益
cls_pw: 1.0      # cls BCELoss 正样本权重
obj: 1.0         # obj loss 增益
obj_pw: 1.0      # obj BCELoss 正样本权重
iou_t: 0.20      # IoU 训练阈值
anchor_t: 4.0    # anchor 匹配阈值

# 数据增强
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 增强概率

几个我特别想强调的点：

lr0 和 lrf：学习率是训练的灵魂。我一般从 0.01 开始试，如果 loss 震荡就降到 0.001。
warmup_epochs：前几个 epoch 用小学习率热身，防止模型一开始就学偏。我习惯设 3 个 epoch。
mosaic：把四张图拼成一张，对小目标检测特别有效。但注意，训练后期可以关掉，否则模型会依赖这种拼接模式。
mixup：两张图混合，能提升泛化能力。但计算量也翻倍，小数据集慎用。

避坑指南： 我曾经在一个项目中把 hsv_h 设到 0.1，结果模型把红色和橙色搞混了。数据增强不是越大越好，要跟实际场景匹配。

4.4 三个文件的协作关系

训练时，YOLO 会按这个顺序加载配置：

先读 data.yaml，确定数据在哪、有多少类
再读 model.yaml，根据 nc 和 depth/width 构建网络
最后读 hyp.yaml，设置训练超参

任何一个文件出问题，训练都会翻车。我建议你把这三个文件放在同一个目录下，方便管理。

  最佳实践： 每次开始新项目，先复制一份默认配置，再逐行修改。不要在原文件上改，否则想回退都找不到原始版本。

4.5 常见问题与排查

问题	可能原因	解决方案
训练报错「No labels found」	data.yaml 路径不对	检查 train/val 路径，确保图片和标签在同一级目录
loss 一直不下降	学习率太大或太小	先试 lr0=0.01，不行就降到 0.001
mAP 很低	anchors 不匹配	用 k-means 重新聚类 anchors
训练速度极慢	depth_multiple 或 width_multiple 太大	换小模型，或者降低 batch size

嗯，配置文件这块其实不难，但细节特别多。我每次开新项目，都会花 10 分钟把这三个文件从头到尾检查一遍。别嫌麻烦，这 10 分钟能省你后面 10 小时的 debug 时间。