从壹开始解读Yolov11【源码研读系列】——cfg：模型配置加载功能
目录
一、模型配置操作：cfg.__init__.py
1.cfg.cfg2dict：yaml转字典
2.cfg.get_cfg：读取覆盖配置
3.cfg全局配置参数查询表
①*基础参数配置：
②*训练参数配置：
③验证测试参数配置：
④*预测参数配置：
⑤可视化参数配置：
⑥导出部署模型参数配置：
⑦*训练超参数配置
⑧*数据增强参数配置
在之前的从零开始使用YOLO系列文章中，简单记录了训练部署YOLO模型到自己的应用场景的一般方法。ultralytics平台的代码设计，让用户可以非常便捷轻易的使用命令行或者python接口脚本使用模型。
从零开始使用YOLO系列——基础使用博文快速链接：https://blog.csdn.net/qq_58718853/article/details/140501645
在此基础上，尝试使用Pycharm自带的debug模块，通过动态运行代码查看使用其便捷接口时具体调用模块的逻辑和结构。这样检视的好处是可以了解模型运作的流程，如加载模型要么调用model类中的self._load，要么调用self._new。
从零开始使用YOLO系列——debug源码博文快速链接：https://blog.csdn.net/qq_58718853/article/details/141122605
但是debug的方法是跳跃式的，在不同文件下python文件跳转，对于一些模块只能了解其部分，而对类的整体理解审视缺失。因此，新开本系列——按源码子文件顺序，研读官方参考文档，结合源码和实验解读YOLO源码。此系列可以作为YOLO内置功能函数的查询文档，也可以搭配debug系列深度理解YOLO运行逻辑。下见所有源码子文件夹。
一、模型配置操作：cfg.__init__.py
cfg 内文件夹结构如下图。其中datasets存放了相关数据集的 yaml 配置文件，models存放从Yolov3到11的模型 yaml 配置文件。__init__.py 文件中编写了处理cfg的相关函数。
1.cfg.cfg2dict：yaml转字典
官方文档参考地址：https://docs.ultralytics.com/reference/cfg/__init__/
这是一个读取yaml配置文件并转为字典的功能函数。下例分别读取了yolo11的模型yaml配置文件和整体环境yaml配置。
输入：yaml配置环境地址
输出：具体配置参数的字典dict格式
yaml配置环境可以在克隆下载的源码内找到。详见下图。
# 测试代码
from ultralytics.cfg import cfg2dictmodel_yaml = cfg2dict('yolo11.yaml')
print(model_yaml)
config = cfg2dict('default.yaml')
print(config)cfg2dict解析了yaml文件中的设置，并将其转为模型方便取用的dict字典格式。
2.cfg.get_cfg：读取覆盖配置
读取并修改覆盖配置参数函数。
输入：空（默认配置）或配置文件地址， override=输入修改参数的字典
输出：ultralytics.utils.IterableSimpleNamespace是ultralytics自定义的类
自定义配置文件my_cfg只修改mode为val验证模式，下述测试代码可以验证使用override覆盖后，将my_cfg改回了默认配置。
from ultralytics.cfg import get_cfgconfig1 = get_cfg('default.yaml')
config2 = get_cfg('my_cfg.yaml')
print(type(config1))
print(config1==config2)config3 = get_cfg('default.yaml', overrides={'mode':'val'})
print(config3==config2)3.cfg全局配置参数查询表
官方参考文档地址：https://docs.ultralytics.com/usage/cfg/
①*基础参数配置：
| task | 任务模式：检测（detect）、语义分割（segment）、分类（classify）、姿态检测（pose）、定向边界框（obb） |
| mode | 模型模式：训练（train）、验证（val）、预测（predict）、导出部署格式模型（export）、目标追踪（track）、基准评估（benchmark） |
②*训练参数配置：
| model | 模型参数地址 .pt 或 .yaml 格式（path/yolo11.yaml） |
| data | 数据 .yaml 文件存放地址（path/coco8.yaml） |
| epochs | 训练轮次数（100） |
| time | 最长的训练时长-小时数，超出时间终止轮次epochs（10） |
| patience | 验证指标没有改进下，最大容忍的训练轮次（10） |
| batch | 训练一轮的批量大小——图片数量（batch = -1：自动选择） |
| imgsz | 输入模型图片矩阵大小，所有输入图片都会调整为这一大小的正方形矩阵（640） |
| save | 是否保存模型检查点参数——恢复训练 & 最终模型结果参数——部署模型（True） |
| save_period | 保存模型参数的频率——每几个轮次保存一次 （save_period = -1：禁用此功能） |
| cache | 数据加载在ram内存（True）——增加内存占用但提高训练速度 or 禁用此功能（False） |
| device | 训练设备：单gpu（device=0）、多gpu（device=0,1,2,3）、cpu（device=cpu）、Apple芯片（device=mps） |
| workers | 工作线程数（8），在多gpu中影响数据预处理和训练速度 |
| project | 保存项目名称（my_project） |
| name | 实验项目具体保存文件名称（name=train1：保存在my_project/train1） |
| exist_ok | 用于迭代训练覆盖同名name文件（True）or 新增改名文件保存——my_project/train2（False） |
| pretrained | 是否启用预训练模型参数（True / False），或者直接输入预训练模型参数地址（path/yolo11.yaml） |
| optimizer | 训练优化器：（SGD）、（Adam）、（Adamax）、（AdamW）、（NAdam）、（RAdam）、（RMSProp）、自动（auto） |
| verbose | 训练中详细打印出训练过程（True），如训练loss、精度、召回率、map等指标 |
| seed | 设置训练随机种子（0） |
| deterministic | 强制使用确定性算法（True），可能影响性能和速度 |
| single_cls | 专注于提升预测框的精度，而不考虑框内目标分类（True） |
| rect | 启用矩形训练，提高速度，降低精度（True） |
| cos_lr | 启用余弦学习率调节，控制学习速度，帮助收敛（True） |
| close_mosaic | 在最后几（10）个轮次里禁用马赛克数据增强，以提高模型稳定性（close_mosaic=0：禁用此功能） |
| resume | 从最后的中断点开始恢复训练（True） |
| amp | 启动自动混合精度训练，减少内存加快速度（True） |
| fraction | 选择使用数据集的比例分数（fraction=1.0：完整数据集训练；fraction=0.5：使用数据集一半训练） |
| profile | 在训练期间对ONNX和TensorRT速度进行分析，这对于优化模型部署非常有用（True） |
| freeze | 冻结模型的前几层参数不参加训练，对微调和迁移学习有帮助，减少内存提高速度（2）；禁用功能，完整模型训练（None） |
| multi_scale | 是否启动多尺度图像训练（True），帮助模型识别远近物体关系 |
| overlap_mask | 仅对分割（segment）任务有用：训练中掩码需重叠（True） |
| mask_ratio | 仅对分割（segment）任务有用：掩码下采样比率（4） |
| dropout | 仅对分类（classify）任务有用：使用dropout正则化（0.0） |
③验证测试参数配置：
| val | 是否在训练时启用验证，验证集计算模型指标map（True） |
| split | 使用数据集 yaml 文件中的 val 目录下的数据作为验证集（val） |
| save_json | 使用 json 作为保存格式（True） |
| save_hybrid | 保存将原始预测标签与其他模型预测相结合的标签的混合版本（True） |
| conf | 设置检测的最小置信阈值。置信度低于此阈值的检测将被丢弃（conf=None：禁用此功能，将保留所有检测框） |
| iou | 设置非最大抑制（NMS）的联合交叉口（IoU）阈值。有助于减少重复检测。高于阈值的重叠框将选出唯一置信度最高的（iou=0.7：高于0.7的重叠框将舍弃到唯一框） |
| max_det | 一张图片中最多的检测数量（300） |
| half | 启用半精度计算——FP16，减少内存（True） |
| dnn | PyTorch推理的替代方法：使用OpenCV DNN模块——图像处理与模型推理的集成，进行ONNX模型推理——支持跨架构跨模型的硬件加速优化（True） |
| plots | 保存模型结果的可视化图片（True） |
④*预测参数配置：
| source | 指定推理的数据源。可以是图像路径、视频文件、目录、URL或设备ID（/path/xxx.img） |
| vid_stride | 视频输入的帧步长。允许跳过视频中的帧，以时间分辨率为代价加快处理速度。值为1时处理每一帧，值越大则跳过帧（1） |
| stream_buffer | 确定是否为视频流的传入帧排队：禁用功能旧帧将被丢弃以容纳新帧（False）；启用此功能，新帧排队到缓冲区中，确保没有帧被跳过，但如果推理FPS速度低于传入流FPS，则会导致延迟（True） |
| visualize | 在推理过程中激活模型特征图的可视化，提供对模型“看到”内容的洞察。可用于调试和模型解释（True） |
| augment | 启用预测的测试时间增强（TTA）——图像翻转、旋转、缩放、裁剪、色彩调整等，以牺牲推理速度为代价提高检测鲁棒性（True） |
| agnostic_nms | 启用类无关的非最大抑制NMS，合并不同类的重叠框（True） |
| classes | 选择专注的目标类别，可以是单个类别的索引整数值（0），也可以是关注的类别索引列表（[ 0,2,5 ]） |
| retina_masks | 仅对分割（segment）任务有用：使用高分辨率分割掩模（True） |
| embed | 返回指定层数结果的特征向量，列表形式（[ 1 ]），可用于下游任务如聚类或相似性分析 |
⑤可视化参数配置：
| show | 启用在窗口显示带标签检测结果的实时图片或视频（True） |
| save_frames | 仅在处理视频输入时可用（True）：将单个帧保存为图片 |
| save_txt | 将检测结果保存在文本文件中（True），格式为[class][x_center][y_center][width][height][confidence] |
| save_conf | 启用保存检测框的置信度得分（True） |
| save_crop | 启用保存检测的裁剪图像结果（True）可用于数据集增强、分析或为特定对象创建聚焦数据集 |
| show_labels | 启用展示当前框的框内目标类别名称（True） |
| show_conf | 启用展示当前框的置信度（True） |
| show_boxes | 启用展示当前框的边界框（True） |
| line_width | 设置画框的线条粗细（4），默认为（None：此时根据输入图片大小自动选择） |
⑥导出部署模型参数配置：
| format | 选择导出模型的目标格式（【onnx、torchscript、tensorflow...】） |
| keras | 允许导出TensorFlow SavedModel的Keras格式，提供与TensorFlow服务和API的兼容性（True） |
| optimize | 移动端导出设置：导出到TorchScript时，对移动设备进行优化，减小模型大小并提高性能（True） |
| int8 | 边缘设备设置：使用 int8 量化，进一步压缩模型，以最小的精度损失加速推理（True） |
| dynamic | 动态图片输入大小设置：允许ONNX、TensorRT和OpenVINO导出的动态输入大小，增强了处理不同图像尺寸的灵活性（True） |
| simplify | 使用onnxslim简化ONNX导出的模型图（True） |
| opset | 指定ONNX opset版本，以与不同的ONNX解析器和运行时兼容。如果未设置，则使用最新支持的版本（opset vision / None） |
| workspace | 设置TensorRT优化的最大工作空间大小（GiB），平衡内存使用和性能（4：默认） |
| nms | 在Apple生态框架CoreML导出中添加非最大抑制（NMS） |
⑦*训练超参数配置
| lr0 | 初始学习率：SGD（0.01），Adam（0.001） |
| lrf | 最终学习率：初始学习率 lr0*lrf = 最终学习率（0.01） |
| momentum | SGD的动量因子或Adam优化器的beta1：影响更新过程中之前梯度的权重（0.937） |
| weight_decay | L2正则化项增加惩罚项实现权重衰退：增大值（0.001）增加惩罚，模型权值变小——过拟合风险减少，欠拟合风险增加；减小值（0.0001）减小惩罚，模型权值变大——过拟合风险增加（0.0005：默认） |
| warmup_epochs | 学习率预热的迭代次数：逐渐将学习率从较低值提高到初始学习率，以在早期稳定训练（3.0：默认） |
| warmup_momentum | 学习率预热的初始势头：调大值（0.9）可以在稳定梯度方向更快收敛，适合大规模数据；调小值（0.7）可以使得更新更加平滑稳定（0.8：默认） |
| warmup_bias_lr | 预热阶段偏差参数的学习率：初始阶段稳定模型训练（0.1：默认） |
| box | 损失函数中框坐标损失的权重：影响对精确预测边界框坐标的重视程度，调大模型将更重视框的精确度（7.5：默认） |
| cls | 损失函数中框内目标分类的权重：影响对目标正确分类预测的重视程度（0.5：默认） |
| dfl | 分布焦点损失权重：box损失——预测边界框的坐标值的回归问题；dfl损失——每个坐标预测拆分为一个离散分布，预测坐标值的概率分布的分类问题（1.5：默认） |
| pose | 姿态估计训练模型中姿态损失的权重：影响对准确预测姿态关键点的重视程度（12.0：默认） |
| kobj | 姿态估计模型中关键点物体损失的权重：平衡检测置信度和姿态精度（1.0：默认） |
| label_smoothing | 硬标签“软化”：将单一绝对值的标签如0,1转为概率分布的软标签如【0.9,0.1】，【0.15，0.85】。 硬标签“平滑化”：此参数的值大小决定标签的平滑程度，如（0.0：默认）代表使用传统硬标签【1,0】，【0,1】。取值越大越平滑，最大为（1.0：max），此时每个标签都是一个均匀分布【0.5,0.5】，【0.5,0.5】 |
| nbs | 标准化损失名义批次大小：在不同批次大小下对损失值进行归一化处理，防止批次大小对梯度稳定性的影响（64：默认） |
⑧*数据增强参数配置
此处参数较为抽象，将在后续对数据增强源码解析的实验中，记录调整相关参数的数值，会对最终生成的数据增强图片造成怎样的影响。
| hsv_h | 数据增强参数——图像色轮色调调整：模拟不同光照条件的图像亮度，提高模型泛化性，数值越高亮度越大（0.0-1.0：取值范围） |
| hsv_s | 数据增强参数——图像饱和度：调整图像颜色强度以模拟不同环境，数值越大，颜色越强（0.0-1.0：取值范围） |
| degrees | 数据增强参数——图片随机旋转：在指定范围内随机旋转图片，提高模型对不同方向目标的泛化能力。特别的，如果输入值为正数（如45：旋转范围为-45到45度），如果输入值为负数（如-45：旋转范围为-45到0度）（单值，-180-180：取值范围） |
| translate | 数据增强参数——图片水平或垂直平移：数值大小代表平移距离占图片高（宽）的比例（0.1：平移图片的十分之一长度或宽度），提高模型对图片部分不可见时的泛化能力（0.0-1.0：取值范围） |
| scale | 数据增强参数——图片缩放：数值代表缩放比例，模拟相机不同距离下的目标物体（>=0.0：取值范围） |
| shear | 数据增强参数——图片“剪切”：根据设定度数拉伸或倾斜物体，模拟不同角度观测物体效果（-180-180：取值范围） |
| perspective | 数据增强参数——图片3D透视变换：提高模型对三维物体的理解（0.0-0.001：取值范围） |
| flipud | 数据增强参数——指定概率上下翻转图片：数值是随机翻转图片的概率值，越大越可能生成翻转图片（0.0-1.0：取值范围） |
| fliplr | 数据增强参数——指定概率左右翻转图片：同上描述，随机左右翻转图片（0.0-1.0：取值范围） |
| bgr | 数据增强参数——指定概率翻转颜色通道：以一定概率随机将图片颜色通道从RGB转为BGR，提高对不正确通道输入的鲁棒性（0.0-1.0：取值范围） |
| mosaic | 数据增强参数——图像组合复杂化：将四个图片组合成一张图片，模拟不同场景对象交互形成的复杂检测环境（0.0-1.0：取值范围） |
| mixup | 数据增强参数——混合图像：将两张图片及其标签信息混合，形成合成图片，模拟图片存在标签噪音和视觉变化（0.0-1.0：取值范围） |
| copy_paste | 数据增强参数——混合目标：将一个图像中的目标区域剪贴到另一种图像，模拟图像中目标被其他目标遮盖的场景（0.0-1.0：取值范围） |
| copy_paste_mode | 数据增强参数——混合目标模式：翻转剪贴目标（‘flip’）；混合目标图像（‘mixup’） |
| auto_augment | 数据增强参数——自动增强模式选择：自动应用预定义的增强策略（randaugment、autoaugment、augmix） |
| erasing | 数据增强参数——随机擦除：在分类训练过程中随机擦除图像部分，模拟图像中目标特征不太明显时识别状况（0.0-0.9：取值范围） |
| crop_fraction | 数据增强参数——目标小图裁剪：将目标裁剪到其边界检测框大小，以减小背景干扰，强调中心特征（0.1-1.0：取值范围） |