YOLO模型的配置参数文件详细解释

date

Nov 25, 2025

slug

2025-11-25-the-detailed-explanation-of-YOLO-configuration-file

status

Published

task与mode

default.yaml配置文件的开头，使用 task 和 mode 这两个参数设定了模型的基本运行模式。这两个参数共同决定了YOLO模型的运行方式，不同的task会加载不同的模型架构和损失函数，而不同的mode则会执行相应的工作流程（训练、验证、推理等）。

task参数用于指定模型的任务类型，指定task参数以后，项目会根据指定的任务类型创建网络结构。当前的Ultralytics项目的实现中，包含有五种任务类型：

目标检测（detect)：目标检测任务，用于检测和定位图像中的目标对象。detect是该项目最常用的任务类型，也是default.yaml中的默认task。

实例分割 (segment)：实例分割任务，不仅检测对象位置，还提供像素级的分割掩码。

图像分类 (classify)：图像分类任务，仅对整个图像进行分类。

姿态估计 (pose)：姿态估计任务，用于识别人或动物的关键点/关节位置，提供类似火柴人一样的识别和检测效果。

obb ：旋转边界框检测任务，用于检测非轴向对齐的目标（如无人机视角下的物体）

对于以上各种不同类型的task，可以参考计算机视觉类AI应用领域及其主流模型总结一文。

mode参数用于指定当前的运行模式：

train：训练模式，用于执行模型训练过程。

val：验证模式，用于评估当前训练好的模型在验证集上的性能，生成验证指标文件。

predict：预测推理模式，用于使用训练好的模型对指定的数据进行推理输出。

export：导出模式，用于将模型导出为不同的部署格式（如ONNX、TensorRT等）。

track：在detect模型上启用跟踪模式，可用于对视频中的为每个检测到的目标分配唯一ID并持续跟踪其运动轨迹。启用后需通过tracker参数指定跟踪配置文件。

benchmark：基准测试模式，用于更全面地评估模型在不同硬件和配置下的性能、速度与精度。

训练相关参数

default.yaml文件中与模型训练流程相关的参数及其解释如下表所示：

以下对上面的部分参数做更为详细的解释和说明。

save（默认为True）和save_period（默认为-1）参数用于指定是否保存训练的权重文件到save_dir/weights/目录下。在save设置为true的情况下，每个epoch结束以后，都会把当前训练的权重覆盖保存在last.pt文件中，而如果当前训练的效果比之前的指标更好的话，该权重文件也会保存在best.pt文件中；当save_period参数设置为N时（N不等于-1），每隔N个epoch就会在save_dir/weights/目录下多保存一个epoch_N.pt的中间训练权重文件。

cache参数决定了是否以及如何在训练开始的时候，将数据集预先加载并缓存起来，以避免在训练过程中重复进行耗时的磁盘读取和数据处理操作。设置为False（默认值）表示不做缓存处理，每次都是从磁盘加载新一个batch的训练数据；设置为True或'ram'表示提前把训练集中的数据缓存在RAM中，每次从RAM中取数据；设置为‘disk’时在第一个epoch期间，训练程序会将处理好的图像以特殊格式（.npy）保存到硬盘的临时目录，后续的epoch从该缓存读取。

project和name参数搭配起来可以按照自定义的方式指定模型训练文件的保存路径。不设置这两个参数的话，默认训练流程所产生的文件会保存在runs/detect/train/exp这样的目录下，而如果设置以后，这些文件的保存路径就是project/name。exist_ok这个选项则表示多次执行的时候是覆盖这个project/name还是在name指定的目录名后面加执行次数的索引后缀名来对多次执行的结果进行区分。

pretrained参数设置为False的情况下，模型训练只会使用model参数所指定的模型，模型各层的权重使用完全随机的参数进行初始化；pretrained参数设置为True的情况下，表示直接使用model参数所指定的模型文件中的权重；pretrained参数设置为某个权重文件路径时，表示使用model参数所指定的模型，但是模型的各层参数用pretrained所指定的参数文件进行设置和初始化。

seed和deterministic这两个参数用于控制模型训练过程和结果的随机性和可复现性。默认的配置下（seed=0，deterministic=False），模型训练的流程和结果保留了一定的随机性，比较适合日常的开发情况。而对于一些要求更为严谨的应用（如论文发表等），模型的训练需要提供严格的确定性和可复现性，此时应该把这两个参数设置为seed=42，deterministic=True。

single_cls参数是一个布尔值，默认为False。当设置为 True时，模型的输出会强制将所有对象都视为同一个类别，即模型只输出一个类别。如果应用只关心画面中是否有某个类别的物体存在时，可以把这个参数设置为True以将复杂的多类别检测问题简化为更基础的目标存在性检测问题。

rect参数用于指定是否使用固定的正方形长宽比作为模型训练图像的输入。在rect=False（默认值）的情况下，所有进行训练的图像无论其长宽比是什么，都会先通过缩放+填充的手段转换为正方形送入模型进行训练，这种模式一般是针对数据集长宽比不一致且差异比较大的情况；而设置rect=False的情况下，YOLO会首先会对每个批次的图像长宽比信息进行统计，找到最合适的长宽比，然后在训练的过程中，把这个批次的所有图像转换到新的长宽比送入模型进行训练，针对数据集中所有图片长宽比基本相同的情况（例如监控摄像头一般为4:3或者16:9），这种方式可以提升训练效率。设置rect参数的作用主要是可以根据数据集长宽比的情况对输入图像尺寸进行调整，尽量减少GPU计算的浪费，提升训练的效率和速度。

close_mosaic参数用于指定在训练过程的最后N轮训练禁用mosaic数据增强的功能。mosaic数据增强技术可以通过把四张训练图片以不同的、每个批次随机的方式剪切并且合并到一起，形成一张新的训练图片对模型参数进行训练，这种方式可以通过训练数据的多样性变化提升训练的效果。但是在训练的末期，我们一般希望参数尽快稳定下来，而mosaic增强会导致参数发生的变化过于剧烈，所以此时可以通过设置close_mosaic参数指定训练过程提前N轮禁用mosaic增强，确保参数在训练过程的最后阶段尽快稳定下来。

amp参数用于控制训练过程中所使用的数据及其计算精度。在传统的模型训练过程中，一般在全流程中使用FP32精度进行训练。当开启AMP模式以后，对于前向、后向运算等环节使用更节省内存的FP16精度，仅对梯度等计算相关的部分采用更高的FP32精度。这样做的好处是可以基本保持训练指标不变的情况下，大幅度减少训练过程对于内存的需求，以及加快训练速度。默认情况下一般推荐使能AMP模式，但是需要注意的是部分比较老旧的硬件不支持AMP模式。

fraction参数用于指定训练过程中参与训练的数据量占总的数据集数量的比例。一般情况下，我们对于模型的训练肯定都是要把100%的训练集数据送入模型对模型参数进行训练。但是在某些需要快速验证、并且数据集数据量很大的情况下，可以通过设置fraction参数只使用一定比例的训练集数据对模型进行训练，在这种情况下，每个epoch就只会随机的从训练集中提取出来fraction参数指定比例的数据进行训练。

Profile参数用于控制是否启用训练过程中的性能指标分析。在启用（Profile=true）后，整个训练过程中会详细的针对每一步的操作进行细粒度统计和分析，最终给出非常详细的性能分析数据。因此这个过程会需要更多的内存保存这些统计信息，并且大幅度拖慢训练的速度。因此除非是要对模型的框架进行调整，需要从很详细的程度上了解模型的执行效率，否则不建议开启profile模式。

freeze参数用于指定在训练的过程中哪些层的权重需要冻结，在训练中不更新这些层的参数。如果是在官方预训练的YOLO模型的基础上，基于自己的数据集进行模型的微调，因为官方的模型参数一般都是COCO这类比较大的数据集上进行了非常充分的训练，因此其预训练参数已经包含了非常强大的特征提取能力。在自己的数据集数量不是很大（几千张之内）、并且检测任务区别不大的话，建议可以使用freeze参数把网络的主干网络部分冻结，只使用自己的数据训练颈部网络和检测头部分。可以使用freeze参数控制冻结前N层或以列表的形式冻结指定的层参数。

multi_scale参数用于控制训练过程中输入图像的尺寸大小。如果multi_scale设置为False，训练过程中输入的图像尺寸大小固定为imgsz设置为640x640。而在multi_scale设置为True的情况下，首先针对每个batch随机选择一个图像尺寸大小（必须以32为单位），然后在这个batch的图片的训练过程中，图像在送入模型进行训练之前，首先会被缩放为这个新的尺寸。这样每个batch的输入图像尺寸大小都不同，可以随机调整训练数据的多样性，从而提升模型的适应性和泛化能力。

compile参数是YOLOv8基于Pytorch2.0的torch.compile引入的新功能，在开启的情况下，可以在训练的过程中优化模型的计算图代码来加速训练执行的代码运行效率，降低训练时间。如果训练数据集比较大、且训练所使用的硬件规格比较新的话，可以开启这个选项来加速训练过程。

图像分割与分类参数

以下的overlap_mask，mask_ratio以及dropout这三个参数仅在图像分割和图像分类任务中有效。

验证和测试参数

下表为default.yaml配置文件中Val/Test settings部分的配置参数、默认值及其简单的解释说明。

需要注意的是，下表中的部分参数虽然被归类在配置文件的Val/Test settings部分，但是这些参数同样会被用于predict过程。例如NMS算法相关的iou、max_det、conf等参数。

split参数用于指定当验证功能启用时（即val参数设置为True），验证过程执行时所使用的数据集。其取值范围为[val, test, train]，分别表示使用验证集、测试集或训练集进行模型评估。绝大多数情况下应设置为val，以避免测试集数据泄露和确保评估的公正性。

conf，iou，max_det这几个参数是NMS算法的过滤参数。conf是目标检测的置信度，iou用于对重叠框进行过滤，max_det用于限制一张图片最大输出的检测结果数量。

half参数用于指定在模型前向推理的过程中使用的精度是FP32还是FP16。dnn参数用于指定在模型执行前向推理的过程中使用OpenCV的dnn模块还是使用pytorch框架。

预测参数

下表为default.yaml配置文件中Predict settings部分的配置参数、默认值及其简单的解释说明。

visualize参数用于控制在验证和推理执行过程中是否生成可视化统计分析结果以及图像识别的中间层特征图、热力图等信息，通过查看这些结果，可以辅助调试和定位模型所存在的问题。当设置为True的情况下，因为要生成这些额外的文件并写入磁盘，所以会显著增加内存需求以及影响推理的速度。

augment参数用于控制推理过程的执行，是否需要对输入的图像执行增强操作。在augment=False的情况下，模型在推理的过程中只会把原始图像输入后执行一次推理并给出结果；如果设置为True，模型会对输入的图像做各种增强操作（如翻转、缩放等）后执行多次推理操作，最后合并多次推理的结果为最终输出，因此预测的精度会有所提升，但是耗时会大幅增加。

agnostic_nms参数是一个NMS算法执行流程中的参数，用于在NMS对重复框过滤的过程中，是否需要区分不同的类别。agnostic_nms参数设置为False的标准NMS流程中，NMS算法会对不同类别进行区分，各个类别的检测框不会相互影响；如果设置为True，NMS会在过滤的过程中，把所有的类别放在一起进行过滤，这种情况下当两个不同类别的物体相距比较近的时候，有可能会被错杀。

classes参数指定推理过程中需要检测的目标类别索引列表。该参数未设置的情况下，表示对模型所支持的所有目标类型进行检测并输出；设置为某个列表时表示在执行NMS过滤的过程中仅关注该列表中的目标类型，其他目标都会被过滤掉。

超参数

模型在训练过程中的学习率与优化器方面的参数、默认值及其解释说明如下所示。

lr0和lrf这两个参数是与模型训练过程中反向运算时对参数调整的学习率参数。训练过程中的学习率参数会依据训练的优化器optimizer动态调整，其中lr0是模型开始训练时的初始学习率，此后学习率会逐渐变小，最终降低到lr0 * lrf的程度。momentum参数同样是一个optimizer优化器算法对模型参数进行调整的技术。引入momentum机制后，每次对参数的更新不仅依赖于当前计算的梯度和学习率，而且依赖于历史梯度，momentum参数用于指定历史梯度在本次参数调整中的加权系数。momentum的值越高，历史梯度对参数调整的影响越显著。

weight_decay参数用于控制权重参数的大小，避免权重参数过大导致过拟合问题。具体在训练过程中，通过把weight_decay参数和当前模型的总体权重信息增加到损失函数计算出来的损失值以及参数的调整量中，确保在权重参数过大的情况下，刻意的抑制参数的大小。

模型刚开始训练时，模型内部的部分参数处于随机初始化的状态，这个时候如果直接使用最大的学习率lr0对参数进行调整，会容易导致模型参数调节幅度过大而处于不稳定的状态。因此YOLO模型的warmup机制，就是指在刚开始训练的前几个epoch，把参数更新的学习率从0逐渐线性上升到lr0设置值，一开始的学习率很低，然后逐渐增大到lr0，有助于模型的参数快速达到基本稳定的状态，然后再开始正式的训练。warmup_epochs、warmup_momentum、warmup_bias_lr这三个参数均为warmup执行流程的相关参数。其中warmup_epochs是指该机制在前几个epoch中发挥作用，在warmup阶段，momentum会从warmup_momentum逐步线性上升到momentum参数的设置值，学习率（非偏置项）会从0逐步上升到lr0参数的设置值，偏置项学习率会从0逐步上升到warmup_bias_lr设置值，最后warmup阶段完成后，统一从学习率lr0参数开始正式训练。

与损失函数相关的参数、默认值及其解释说明如下所示：

box，cls和dfl参数分别对应于YOLO模型的三个损失函数值的权重，其中cls对应于分类准确性的损失值，box和dfl一起对应了预测框位置准确度的损失值，box主要是从IOU的角度评估预测框与真值框的重合性，dfl则从上下左右坐标偏移量的角度来评估定位的准确性。适当调节box，cls和dfl参数可以用于调整不同类型的损失值在整体损失值中所占的比例，从而调整不同损失值所对应的指标。

nbs参数是名义上的batch size。实际的训练过程中，因为训练所使用的硬件限制方面的原因，batch size没办法设置的比较大，一般会设置为16。在batch size设置相对比较小的情况下，模型在训练过程中往往会存在波动较大、难以收敛的问题。比较理想的情况是使用batch size=64这样的配置。那么针对硬件配置限制的问题，batch size以及实际送入模型进行训练的图像batch仍然是按照实际设置的batch size（例如16）来进行训练，然后训练结果得到的损失值按照名义batch size与实际batch size的比例进行放大，当nbs设置为64时，两者相差4倍，把损失值乘以4倍送入模型反向传递进行参数更新。使用这种方法也可以解决实际batch size不足带来的模型训练稳定性问题。

训练数据颜色与几何增强相关的参数、默认值及其解释说明如下所示：

hsv_h，hsv_s，hsv_v这三个参数对应的是训练过程中针对图像输入数据的颜色增强参数。HSV颜色空间包含色调H、色彩饱和度S和亮度V三个维度，以上三个参数以比例因子的形式定义了在训练过程中，训练图片数据会在原始图像的色调、饱和度以及亮度这三个维度上随机调整的幅度，通过这种对图像HSV空间三个维度的动态随机调整，来提升模型针对不同光照、色彩环境下的泛化能力。

degree参数用于指定训练集图片送入模型训练之前，在原始图像角度的基础上，以多大的幅度随机旋转一定的角度再进行训练。translate参数用于指定训练图片在原始图像的基础上，以多大的幅度向上下左右四个方向平移一定的比例再进行训练。scale参数用于指定在训练图片的原始图像基础上，以多大的比例范围内进行随机缩放后再进行训练。

shear和perspective这两个参数用于控制图像增强处理的几何变形功能，用于应对自动驾驶、无人机这类运动场景下的图像状况。其中shear是指把原始的长方形图像变形为平行四边形的拉伸动作，而perspective是指把原始的长方形图像从上到下或者从下到上逐渐变小的俯仰视角的变形动作，这两个参数的大小分别指定了两者变形的幅度大小。

图像变换增强参数部分的参数名、默认值及其解释说明如下所示：

以上三个参数比较简单。flipud表示训练图像在送入模型训练时有多大的概率上下翻转，fliplr表示有多大比例左右翻转，bgr表示训练图像有多大比例在训练之前首先把RGB通道顺序的图像转换为BGR通道顺序。三个参数均用于基于现有图像提升图像的多样化和模型的泛化能力。

高级混合增强参数部分的参数名、默认值及其解释说明如下所示：

mosaic参数用于控制在训练过程以多大的比例开启mosaic增强。mosaic增强是指把四张训练图片缩放、裁切等处理后按照2x2的方式拼接为一张图像送入模型进行训练。该参数设置为1.0表示100%的训练数据都使用mosaic拼接处理后的图片，设置为0表示禁用mosaic增强，0-1之间表示训练数据采用mosaic增强处理的比例。

mixup参数用于控制多大比例的训练图片在训练之前首先进行mixup增强处理。mixup是指通过两张图片的像素值大小，乘以随机大小的比例，把两张图片的像素叠加在一起形成一张图片（两张图片的标签置信度也按照相同的比例处理），送入模型进行训练。cutmix参数用于多大比例的训练图片在进行训练之前首先进行cutmix增强处理。cutmix增强处理是指从一张图片随机裁切出来一部分矩形区域，粘贴到另外一张图片上，形成新的训练图像。

copy_paste和copy_paste_mode这两个参数仅用于图像分割模型。

auto_augment和earsing这两个参数仅用于图像分类模型。

配置文件相关参数

如果通过命令行或者在此处设置cfg参数，在YOLO模型的各项任务执行时，会把此处配置的yaml格式的cfg配置文件中的参数合并到default.yaml中。同名参数会以cfg传递的配置文件中的参数优先。

此外如之前部分对于mode中的track模式选项所解释的，track模式用于在detect模型上启用跟踪模式。此时需要在此通过tracker参数来指定跟踪模式运行的跟踪配置文件：

tracker参数对应的配置文件所在的目录为ultralytics\cfg\trackers，当前版本中包含两种跟踪模式：botsort和bytetrack。前者是默认的跟踪模式，跟踪精度更高；后者主要针对实时性要求较高的跟踪类型，跟踪计算的速度更快。