配置
YOLO 设置和超参数对模型的性能、速度和准确率至关重要。这些设置会影响模型在训练、验证和预测等不同阶段的行为。
观看: 精通 Ultralytics YOLO:配置
Ultralytics 命令采用以下语法:
yolo TASK MODE ARGS其中:
TASK(可选)为以下选项之一(detect、segment、semantic、depth、classify、pose、obb)MODE(必需)为以下选项之一(train、val、predict、export、track、benchmark)ARGS(可选)是arg=value键值对,例如imgsz=640,用于覆盖默认值。
默认的 ARG 值定义在此页面中,并来自 cfg/default.yaml 文件。
任务#
Ultralytics YOLO 模型可以执行多种计算机视觉任务,包括:
- 检测:目标检测可识别图像或视频中的对象并确定其位置。
- 分割:实例分割可将图像或视频划分为与不同对象或类别对应的区域。
- 语义分割(
semantic):语义分割会为图像中的每个像素分配类别标签,以实现密集场景理解。 - 深度(
depth):单目深度估计可根据单张 RGB 图像预测以米为单位的逐像素深度图。 - 分类:图像分类可预测输入图像的类别标签。
- 姿态:姿态估计可识别对象并估计其在图像或视频中的关键点。
- OBB:有向边界框采用旋转边界框,适用于航空或卫星图像。
| 参数 | 默认值 | 说明 |
|---|---|---|
task | 'detect' | 指定 YOLO 任务:detect 表示目标检测,segment 表示实例分割,semantic 表示语义分割,depth 表示单目深度估计,classify 表示分类,pose 表示姿态估计,obb 表示有向边界框。每项任务都针对图像和视频分析中的特定输出与问题进行了设计。 |
模式#
Ultralytics YOLO 模型支持不同模式,每种模式都针对模型生命周期中的特定阶段设计:
- 训练:使用自定义数据集训练 YOLO 模型。
- 验证:验证已训练的 YOLO 模型。
- 预测:使用已训练的 YOLO 模型对新图像或视频进行预测。
- 导出:导出 YOLO 模型以供部署。
- Track:使用 YOLO 模型实时跟踪对象。
- 基准测试:对 YOLO 导出模型(ONNX、TensorRT 等)的速度和准确率进行基准测试。
| 参数 | 默认值 | 说明 |
|---|---|---|
mode | 'train' | 指定 YOLO 模型的运行模式:train 表示模型训练,val 表示验证,predict 表示推理,export 表示转换为部署格式,track 表示目标跟踪,benchmark 表示性能评估。每种模式都支持从开发到部署的不同阶段。 |
训练设置#
YOLO 模型的训练设置包括会影响模型性能、速度和准确率的超参数与配置。关键设置包括批次大小、学习率、动量和权重衰减。优化器、损失函数的选择以及数据集组成也会影响训练。调优和实验对于获得最佳性能至关重要。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model | str | None | 指定用于训练的模型文件。接受指向.pt预训练模型或.yaml配置文件的路径。这是定义模型结构或初始化权重的必要设置。 |
data | str | None | 数据集 YAML 文件的路径(例如 coco8.yaml),其中包含训练和验证数据的路径、类别名称和类别数量。分类任务则使用数据集目录或内置数据集名称(例如 imagenet10)。 |
epochs | int | 100 | 训练总轮数。每个轮次都表示完整遍历整个数据集一次。调整此值会影响训练时长和模型性能。 |
time | float | None | 最长训练时间(小时)。如果设置此项,它会覆盖epochs参数,让训练在达到指定时长后自动停止。适用于训练时间受限的情况。 |
patience | int | 100 | 验证指标未改善时,等待多少轮后提前停止训练。性能趋于平稳时停止训练,有助于防止过拟合。 |
batch | int 或 float | 16 | 批次大小有三种模式:设为整数(例如 batch=16)、自动模式(使用可用 GPU 内存的 60%,batch=-1),或自动模式(使用指定比例的可用 GPU 内存,batch=0.70)。 |
imgsz | int | 640 | 训练时的目标图像尺寸。图像会被缩放为边长等于指定值的正方形(如果是rect=False),YOLO 模型会保持宽高比,但 RT-DETR 不会。这会影响模型准确率和计算复杂度。 |
save | bool | True | 启用训练检查点和最终模型权重的保存功能。适用于恢复训练或模型部署。 |
save_period | int | -1 | 保存模型检查点的频率,以轮数指定。值为 -1 时会禁用此功能。适合在长时间训练过程中保存中间模型。 |
cache | bool 或 str | False | 启用数据集图像缓存:缓存到内存(True/ram)、磁盘(disk),或禁用缓存(False)。通过减少磁盘 I/O 提高训练速度,但会增加内存使用量。 |
tile | bool 或 int | False | 将每张源图像扩展为固定大小的训练切片,并裁剪标签、保留负样本窗口。True 使用 imgsz;正整数用于设置切片大小。参见 高分辨率切片。 |
device | int 或 str 或 list | None | 指定训练使用的计算设备:单个 GPU(device=0)、多个 GPU(device=[0,1])、CPU(device=cpu)、Apple 芯片上的 MPS(device=mps)、华为昇腾 NPU(device=npu:0 或 device=npu:0,1)、Intel XPU(device=xpu:0)、自动选择空闲 GPU(device=-1)或多个空闲 GPU(device=[-1,-1])。 |
workers | int | 8 | 用于数据加载的工作线程数(多 GPU 训练时为每个RANK配置)。此设置会影响数据预处理和输入模型的速度,在多 GPU 配置中尤其有用。 |
project | str | None | 保存训练输出的项目目录名称。相对路径会置于 runs_dir/<task> 下,绝对路径则按原样使用。 |
name | str | None | 训练运行名称。用于在项目文件夹中创建子目录,以存储训练日志和输出。 |
exist_ok | bool | False | 如果为 True,则允许覆盖已有的项目/名称目录。适用于迭代实验,无需手动清理之前的输出。 |
save_dir | str | None | 指定保存运行输出的确切目录,覆盖project/name组合。路径会按原样使用,不会自动递增,因此连续运行会复用同一目录。 |
pretrained | bool 或 str | True | 指定是否从预训练权重开始训练。可以是布尔值,也可以是要加载的权重文件路径字符串。pretrained=False会使用随机初始化的权重训练,同时保留模型架构。 |
cls_remap | bool | True | 跨数据集微调时,只要类别名称匹配,就会将预训练分类头的行复制到新模型中,让重叠类别保留已学习的偏置;如果分类头宽度不变,也会保留权重。无论类别数量是否相同,或类别顺序是否不同,都会应用此设置。 |
optimizer | str | 'auto' | 选择训练使用的优化器。选项包括 SGD、MuSGD、Adam、Adamax、AdamW、NAdam、RAdam、RMSProp 或 auto,可根据训练迭代次数选择 AdamW 或 MuSGD。这会影响收敛速度和稳定性。 |
seed | int | 0 | 设置训练的随机种子,确保使用相同配置进行多次运行时结果可复现。 |
deterministic | bool | True | 强制使用确定性算法,确保结果可复现;但由于限制使用非确定性算法,可能会影响性能和速度。 |
verbose | bool | True | 启用训练过程中的详细输出,在控制台显示进度条、每轮指标及其他训练信息。 |
single_cls | bool | False | 训练时将多类别数据集中的所有类别视为一个类别。适用于二分类任务,或关注对象是否存在而非类别的情况。 |
classes | list[int] | None | 指定要参与训练的类别 ID 列表。适用于筛选并仅关注训练中的特定类别。 |
rect | bool | False | 启用最小填充策略——批次中的图像只进行最少填充,以达到统一尺寸,且最长边等于 imgsz。这可以提升效率和速度,但可能影响模型精度。无论此设置如何,标准 YOLO 训练器在检测、分割、姿态和 OBB 验证中都会使用 rect=True。 |
multi_scale | float | 0.0 | 每个批次随机调整imgsz,变化范围为 +/- multi_scale(例如,0.25 -> 0.75x 到 1.25x),并四舍五入到模型步幅的倍数;0.0会禁用多尺度训练。 |
cos_lr | bool | False | 使用余弦学习率调度器,在各轮训练中按余弦曲线调整学习率。这有助于管理学习率,从而更好地收敛。 |
close_mosaic | int | 10 | 在最后 N 轮训练中禁用马赛克数据增强,以便在训练结束前稳定模型。设为 0 可禁用此功能。 |
resume | bool | False | 从上次保存的检查点恢复训练。自动加载模型权重、优化器状态和 epoch 计数,并从中断处继续训练。 |
amp | bool 或 str | True | 设置训练精度:True 或 "fp16" 使用 FP16,"bf16" 在支持的 CUDA 设备上使用 BF16,False 或 "fp32" 使用 FP32。 |
quantize | int 或 str | None | 设为8(或"int8")以启用 INT8 量化感知训练(QAT)。该训练会在循环中进行伪量化微调,使权重能够适应 INT8 导出。请参阅量化感知训练。 |
fraction | float、int 或 list | 1.0 | 数据集子集,可按比例/数量或[train, val, test]列表指定。1表示完整划分;大于1的整数表示图像数量;只有可选的 test 项接受0/0.0来表示无测试集。包含两项的列表会保留完整测试集。 |
profile | bool | False | 启用训练期间对 ONNX 和 TensorRT 速度的性能分析,适用于优化模型部署。 |
freeze | int 或 list | None | 冻结模型的前 N 层,或按索引或模块名称冻结指定层(23.cv2,不带前导model.),以减少可训练参数数量。适用于微调或迁移学习。 |
lr0 | float | 0.01 | 初始学习率(例如 SGD=1E-2、Adam=1E-3)。使用默认的 optimizer='auto' 时会忽略此项;若要使用该值,请明确指定优化器名称。 |
lrf | float | 0.01 | 最终学习率与初始学习率的比值 = (lr0 * lrf),与调度器配合使用,以便随时间调整学习率。 |
momentum | float | 0.937 | SGD/MuSGD 的动量,或 Adam 优化器的 beta1。使用 optimizer=auto 时,AdamW 使用 0.9;MuSGD 从 0.9 开始,然后预热会在 warmup_momentum 和 momentum 之间进行插值。不进行预热时,自动 MuSGD 保持在 0.9。 |
weight_decay | float | 0.0005 | L2 正则化项,用于惩罚较大的权重以防止过拟合。 |
warmup_epochs | float | 3.0 | 预热轮数(允许小数),并设置上限以确保最后一个 epoch 不进行预热。学习率从 0(偏置项来自 warmup_bias_lr)线性上升到计划值,动量从 warmup_momentum 线性上升到 momentum,梯度累积则从 1 个批次增加到标称值(参见 nbs);所有参数都会在预热结束时达到目标值。 |
warmup_momentum | float | 0.8 | 对于带有动量项的优化器(SGD、MuSGD、RMSprop),这是起始动量,并会在预热结束时线性升至 momentum。Adam 系列优化器的 beta1 不参与预热。 |
warmup_bias_lr | float | 0.1 | 预热阶段偏置参数的学习率,有助于稳定训练初期的模型。使用默认optimizer='auto'时会自动设为0.0;要使用此设置,请明确指定优化器。 |
distill_model | str | None | 用于知识蒸馏的教师模型检查点路径(例如 yolo26x.pt)。设置后,学生模型会在冻结教师模型的指导下,通过额外的蒸馏损失进行训练。 |
dis | float | 6.0 | 添加到标准检测损失中的蒸馏损失权重。值越大,教师模型特征指导的影响越大。 |
box | float | 7.5 | 损失函数中边界框损失分量的权重,影响模型对准确预测边界框坐标的重视程度。 |
cls | float | 0.5 | 总损失函数中分类损失的权重,影响相对于其他分量而言正确类别预测的重要性。 |
cls_pw | float | 0.0 | 用于处理类别不平衡的类别权重指数,按类别频率的倒数加权。0.0会禁用类别加权,1.0会应用完整的逆频率加权。介于 0 和 1 之间的值可进行部分加权。 |
dfl | float | 1.5 | 边界框距离回归项的权重:检测头使用reg_max > 1时为分布焦点损失(DFL);不使用 DFL 的 YOLO26(reg_max: 1)则采用归一化边界框距离的 L1 损失。 |
pose | float | 12.0 | 姿态估计模型中姿态损失的权重,影响模型对准确预测姿态关键点的重视程度。 |
kobj | float | 1.0 | 姿态估计模型中关键点目标置信度损失的权重,用于平衡检测置信度与姿态准确率。 |
rle | float | 1.0 | 姿态估计模型中残差对数似然估计损失的权重,会影响关键点定位的精度。 |
angle | float | 1.0 | OBB 模型中角度损失的权重,会影响有向边界框角度预测的精度。 |
dlog | float | 1.0 | 深度估计模型中尺度不变对数(SILog)损失的权重,是影响深度准确率的主要项。 |
dgrad | float | 0.5 | 深度估计模型中梯度损失的权重,用于惩罚深度边缘误差并促使表面边界更加清晰。 |
dlam | float | 1.0 | 深度估计模型中 SILog 损失的方差聚焦因子。1.0会使损失完全具有尺度不变性,而0.0会将其简化为普通的对数 RMSE。 |
nbs | int | 64 | 标称批量大小。每次优化器更新前累积 round(nbs / batch) 个批次的梯度(至少为 1;除 time 模式外,不超过本次运行的批次数),并按 batch * accumulate / nbs 缩放 weight_decay 以使其匹配。 |
overlap_mask | bool | True | 确定训练时是否将所有对象掩码合并为单个掩码,或为每个对象分别保留掩码。合并时如果发生重叠,较小的掩码会叠加在较大的掩码之上。 |
mask_ratio | int | 4 | 分割掩码的下采样比例,会影响训练时所用掩码的分辨率,但不会改变预测掩码的分辨率。 |
dropout | float | 0.0 | 分类任务中的正则化丢弃率,通过在训练期间随机丢弃单元来防止过拟合。 |
val | bool | True | 启用训练期间的验证,以便定期在单独的数据集上评估模型性能。 |
split | str | 'val' | 训练期间用于验证的数据集划分:val、test 或 train。这些指标用于选择 best.pt 并触发提前停止。 |
nms | bool,可选 | None | 选择用于每轮验证、检查点选择和提前停止的推理头。None 或 True使用带 NMS 的一对多头;False在可用时使用无 NMS 头。两种头都会保留各自的训练损失。 |
plots | bool | True | 生成并保存训练和验证指标图,以及预测示例,直观呈现模型性能和学习进度。 |
compile | bool 或 str | False | 使用backend='inductor'启用 PyTorch 2.x torch.compile图编译。接受True → "default"、False → 禁用,或"default"、"reduce-overhead"、"max-autotune-no-cudagraphs"等字符串模式。如果不受支持,则会发出警告并回退到即时执行模式。 |
channels_last | bool | None | 训练卷积时使用 channels_last(NHWC)内存格式。None会在 PyTorch 1.11 或更高版本的 CUDA 上自动启用此格式,但 Windows 除外,因为实测速度更慢。False会禁用此格式,True则会显式启用此格式。CPU 或 MPS 上的训练始终使用 NCHW(True会被忽略,并发出警告)。 |
max_det | int | 300 | 训练验证期间每张图像的最大检测数量。对于 detect、segment、pose 和 OBB,默认值 300 仅在最大训练/验证标注对象数量超过 300 时才会增大到该数量。其他值保持不变;超出上限时会触发警告。 |
batch参数提供三种配置选项:
- 固定批次大小:使用整数指定每批图像数量(例如
batch=16)。 - 自动模式(60% GPU 内存):使用
batch=-1,自动调整训练使用的 CUDA 内存,使其约为可用内存的 60%。 - 使用内存占用比例的自动模式:设置一个比例(例如
batch=0.70),根据指定的可用 GPU 内存比例进行调整。
如果没有候选批次大小能生成可用的性能分析结果,AutoBatch 会清晰地抛出 RuntimeError,而不会悄悄回退到无关的默认值。
预测设置#
YOLO 模型的预测设置包括影响推理性能、速度和准确率的超参数与配置。关键设置包括置信度阈值、非极大值抑制 (NMS)阈值和类别筛选。输入数据的大小与格式,以及掩码等辅助功能也会影响预测结果。要获得最佳性能,必须调整这些设置。
推理参数:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
source | str 或 int 或 None | None | 指定推理的数据源。可以是图像路径、视频文件、目录、URL,或实时画面的设备 ID。如果未指定,系统会记录警告,并使用内置演示资源(ultralytics/assets;对于 OBB,则使用演示 URL)作为模型输入。此功能支持多种格式和来源,可灵活应用于不同类型的输入。 |
conf | float | 0.25 | 设置检测的最低置信度阈值。置信度低于此阈值的检测结果会被忽略。调整此值有助于减少误报。 |
iou | float | 0.5 | 用于非极大值抑制(NMS)的交并比(IoU)阈值。较低的值会通过消除重叠框来减少检测结果,有助于减少重复检测。 |
imgsz | int 或 tuple | 640 | Letterbox 的目标尺寸。整数表示正方形N×N;元组表示(height, width)。使用rect=True时,由于采用最小矩形填充,实际张量可能小于此目标尺寸。使用rect=False可设为固定尺寸。请参阅固定尺寸与最小矩形。 |
rect | bool | True | 如果 True,则尽可能使用最小矩形填充(批次中图像形状相同且后端支持时)。如果 False,则始终使用完整的 imgsz。请参阅固定形状与最小矩形。对 depth 和 RT-DETR 模型会忽略此设置,这些模型会将图像拉伸到完整的 imgsz,且不进行填充。 |
quantize | int 或 str | None | 推理精度:16/"fp16" 和 32/"fp32"/unset 用于为 PyTorch 和 TorchScript 模型选择 FP16 或 FP32 计算(CPU 上为 FP32);其他格式使用其模型文件和运行时所选的精度。在 16 中,OpenVINO 仍会在客户端将输入舍入为 FP16,再扩展回 FP32,但不会更改运行时精度。INT8/PTQ 量化在导出期间配置,然后通过加载导出的模型来使用。此参数替代已弃用的 half 标志。 |
device | str | None | 指定用于推理的设备(例如 cpu、cuda:0、0、npu 或 npu:0)。允许用户在 CPU、指定的 GPU、华为昇腾 NPU 或其他计算设备之间进行选择,以运行模型。OpenVINO 和 LiteRT 模型会在 Intel GPU 和 NPU 上运行 xpu 和 npu;有关各种格式对应的设备,请参阅推理设备。 |
dnn | bool | False | 如果 True,则使用 OpenCV DNN 模块,而不是 ONNX Runtime 执行 ONNX 模型推理。 |
data | str | None | 数据集 YAML 文件的路径(例如 coco8.yaml)。仅读取其中的 names,且仅当加载的模型没有自带类别名称时才会读取:例如第三方导出模型,或与随附元数据分离的 Ultralytics 导出模型。否则,此类模型会报告 class0、class1 等。 |
batch | int | 1 | 指定推理的批次大小(仅在来源为目录、视频文件或 .txt 文件时有效)。较大的批次大小可以提高吞吐量,缩短推理所需的总时间。 |
tile | bool 或 int | False | 运行固定切片推理,并以原始图像坐标返回结果。True 使用 imgsz;正整数用于设置切片大小。参见 高分辨率切片。 |
max_det | int | 300 | 每张图像允许检测的最大数量。限制模型在单次推理中可检测的对象总数,避免密集场景中产生过多输出。 |
vid_stride | int | 1 | 视频输入的帧步长。允许跳过视频帧以加快处理速度,但会降低时间分辨率。值为 1 时处理每一帧;值越大,跳过的帧越多。 |
stream_buffer | bool | False | 决定是否为视频流的传入帧排队。如果 False,则会丢弃旧帧以容纳新帧(针对实时应用进行了优化)。如果 True,则会将新帧放入缓冲区,确保不跳过任何帧;但如果推理 FPS 低于视频流 FPS,就会产生延迟。 |
visualize | bool | False | 在每个预测结果旁保存类别激活热力图,显示哪些像素提高了预测类别的分数。遵循 conf 和 classes,因此 classes=[0] 只映射该类别。仅适用于 Ultralytics PyTorch 模型。 |
augment | bool | False | 为预测启用测试时增强(TTA),可能提升检测的稳健性,但会降低推理速度。仅适用于 Ultralytics PyTorch 模型。 |
agnostic_nms | bool | False | 启用类别无关的非极大值抑制(NMS),抑制不同类别之间得分较低且重叠的框,而不只是同一类别内的框。适用于类别间常有重叠的多类别检测场景。对于无 NMS 推理(YOLO26 或 YOLOv10 上的 nms=False),此选项仅防止同一检测结果带有多个类别标签(IoU=1.0 的重复项),不会根据 IoU 阈值抑制不同的框。 |
classes | list[int] | None | 将预测结果筛选为指定的类别 ID。只返回属于指定类别的检测结果。适用于在多类别检测任务中聚焦相关对象。 |
retina_masks | bool | False | 返回高分辨率分割掩码。启用后,返回的掩码(masks.data)将与原始图像尺寸一致。禁用后,掩码尺寸与推理时使用的图像尺寸一致。 |
embed | list[int] | None | 指定要提取特征向量或嵌入的层。使用 model.embed(source) 获取倒数第二层的嵌入,或使用 model.predict(source, embed=[layer]) 选择特定层。适用于聚类或相似度搜索等下游任务。仅适用于 Ultralytics PyTorch 模型。 |
project | str | None | 如果启用了 save,则此项为保存预测输出的项目目录名称。相对路径会置于 runs_dir/<task> 下,绝对路径则按原样使用。 |
name | str | None | 预测运行的名称。启用 save 时,用于在项目文件夹中创建子目录以存储预测输出。 |
stream | bool | False | 通过返回 Results 对象生成器,而不是一次性将所有帧加载到内存中,为长视频或大量图像启用节省内存的处理方式。 |
verbose | bool | True | 控制是否在终端中显示详细的推理日志,以实时反馈预测过程。 |
compile | bool 或 str | False | 使用backend='inductor'启用 PyTorch 2.x torch.compile图编译。接受True → "default"、False → 禁用,或"default"、"reduce-overhead"、"max-autotune-no-cudagraphs"等字符串模式。如果不受支持,则会发出警告并回退到即时执行模式。 |
channels_last | bool | None | 对原生 PyTorch 推理使用 channels_last(NHWC)内存格式。对于启用了 oneDNN 的 Linux 和 Windows x86 CPU,且 PyTorch 版本为 1.13 或更高版本时,None 会自动启用该格式;False 会禁用该格式;True 会在受支持的 x86 CPU 或 CUDA 设备上请求使用该格式。ARM64、MPS、较旧的 PyTorch 版本、未启用 oneDNN 的 CPU,以及 TensorRT 和 ONNX 等导出格式均不受影响。 |
nms | bool,可选 | None | 默认使用 NMS 执行一对多推理(None 或 True)。设置 False 可在可用时使用无 NMS 的一对一检测头。详情请参阅端到端检测指南。 |
可视化参数:
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
show | bool | False | 如果 True,则在窗口中显示带标注的图像或视频。适用于在开发或测试期间即时查看结果。 |
save | bool | False or True | 启用后将带标注的图像或视频保存到文件。适用于文档编写、进一步分析或分享结果。使用 CLI 时默认为 True,在 Python 中使用时默认为 False。 |
save_frames | bool | False | 处理视频时,将单独的帧保存为图像。适用于提取特定帧或逐帧详细分析。 |
save_txt | bool | False | 按照 [class] [x_center] [y_center] [width] [height] [confidence] 格式将检测结果保存到文本文件。适用于与其他分析工具集成。 |
save_conf | bool | False | 在保存的文本文件中包含置信度分数。增加可用于后处理和分析的详细信息。 |
save_crop | bool | False | 保存检测对象的裁剪图像。适用于数据集增强、分析,或为特定对象创建专用数据集。 |
show_labels | bool | True | 在可视化输出中显示每个检测结果的标签,便于立即了解检测到的对象。 |
show_conf | bool | True | 在每个检测结果的标签旁显示置信度分数,帮助了解模型对该检测结果的确信程度。 |
show_boxes | bool | True | 在检测到的对象周围绘制边界框,便于在图像或视频帧中直观识别和定位对象。 |
line_width | int or None | None | 指定边界框的线宽。如果 None,则会根据图像尺寸自动调整线宽,便于自定义显示效果并提高清晰度。 |
验证设置#
YOLO 模型的验证设置包含用于在验证数据集上评估性能的超参数与配置。这些设置会影响性能、速度和准确率。常见设置包括批次大小、图像尺寸、置信度和 IoU 阈值,以及用于评估的数据集划分。验证数据集的大小和组成以及具体任务也会影响验证过程。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
data | str | None | 指定数据集 YAML 文件的路径(例如 coco8.yaml),其中应包含验证数据的路径。分类任务则使用数据集目录或内置数据集名称(例如 imagenet10)。 |
imgsz | int | 640 | 定义输入图像的尺寸。处理前会将所有图像调整为此尺寸。较大的尺寸可能提高小对象的检测准确率,但会增加计算时间。 |
batch | int | 16 | 设置每个批次的图像数量。较大的值能更高效地利用 GPU 内存,但需要更多 VRAM。请根据可用硬件资源进行调整。 |
tile | bool 或 int | False | 运行固定切片推理,并将合并后的结果与原始整张图像的标注进行评估。True 使用 imgsz;正整数用于设置切片大小。参见 高分辨率切片。 |
save_json | bool | False | 如果 True,则将结果保存到 JSON 文件,以便进一步分析、与其他工具集成,或提交到 COCO 等评估服务器。在检测数据集上,它还会使用 faster-coco-eval 评估预测结果,并报告小、中、大目标的 mAP;训练期间,这些指标会记录为 results.csv 中的 metrics/mAP_small(B)、metrics/mAP_medium(B) 和 metrics/mAP_large(B)。对于语义分割,则会将 PNG 类别掩码保存到 results/ 下,并保留图像子目录结构。 |
conf | float | 0.001 | 设置检测结果的最低置信度阈值。较低的值会提高召回率,但可能引入更多假阳性。精确率-召回率曲线、mAP 和检测混淆矩阵均使用此值;较高的 conf(例如 0.25)会使矩阵更接近预测输出,但可能降低 mAP。汇总精确率和召回率使用最大 F1 值对应的置信度,因此可能与根据 confusion_matrix.png 得出的值不同。OBB 验证的默认值为 0.01,以降低内存使用量。 |
iou | float | 0.7 | 设置用于非极大值抑制的交并比阈值。控制重复检测的消除。 |
max_det | int | 300 | 限制每张图像的最大检测数量。对于 detect、segment、pose 和 OBB,如果保持 300,当图像中的标注对象数量超出此值时,该上限会提高到验证集划分中最大的标注对象数量,并发出警告;使用其他值时则保持不变,并会在图像中的对象数量超出上限时警告召回率可能受限。 |
quantize | int 或 str | None | 验证精度:16/"fp16" 和 32/"fp32"/unset 用于为 PyTorch 和 TorchScript 模型选择 FP16 或 FP32 计算(CPU 上为 FP32);其他格式使用其模型文件和运行时所选的精度。在 16 中,OpenVINO 仍会在客户端将输入舍入为 FP16,再扩展回 FP32,但不会更改运行时精度。INT8/PTQ 量化在导出期间配置,然后通过验证导出的模型来使用。此参数替代已弃用的 half 标志。 |
device | str | None | 指定用于验证的设备(cpu、cuda:0、npu、npu:0 等)。当使用 None 时,会自动选择当前可用的最佳设备。多个 CUDA 设备可以用逗号分隔来指定。OpenVINO 和 LiteRT 模型会在 Intel GPU 和 NPU 上运行 xpu 和 npu;有关各种格式对应的设备,请参阅推理设备。 |
dnn | bool | False | 如果 True,则使用 OpenCV DNN 模块执行 ONNX 模型推理,作为 PyTorch 推理方法的替代方案。 |
plots | bool | True | 设为 True 时,会生成并保存预测结果与真实标注的对比图、混淆矩阵和 PR 曲线,以便直观评估模型性能。 |
classes | list[int] | None | 指定要评估的类别 ID 列表。适用于在评估期间筛选并只关注某些类别。 |
rect | bool | True | 如果 True,则会按宽高比将相似图像分组成矩形形状。每个维度向上取整到步幅的倍数之前,会先增加半个步幅(semantic 不会额外增加半个步幅)。步幅为 32 时,imgsz=640 下的 640×640 图像会变为 672×672,并产生 16 px 的偏移;而 predict 使用 640×640,因此指标可能不同。对于正方形图像,rect=False 与 predict 一致。对 depth 和 RT-DETR 会忽略此设置,这些模型会将图像拉伸为 imgsz 的正方形。 |
split | str | 'val' | 决定验证时使用的数据集划分(val、test 或 train),便于灵活选择用于性能评估的数据部分。 |
fraction | float、int 或 list | 1.0 | 已验证数据划分的子集。使用 [train, val, test] 列表时,应用与 split 对应的条目(1 = 完整数据划分,大于 1 的整数 = 图像数量;省略的条目表示完整数据划分)。标量仅适用于 split=train;val 和 test 随后会使用完整数据划分。 |
project | str | None | 保存验证输出的项目目录名称。相对路径会置于 runs_dir/<task> 下,绝对路径则按原样使用。 |
name | str | None | 验证运行的名称。用于在项目文件夹中创建子目录,以存储验证日志和输出。 |
verbose | bool | True | 如果 True,则在验证过程中显示详细信息,包括每个类别的指标、批次进度和其他调试信息。 |
save_txt | bool | False | 如果 True,则将检测结果保存到文本文件中,每张图像对应一个文件,便于进一步分析、自定义后处理或与其他系统集成。 |
save_conf | bool | False | 如果 True,且启用了 save_txt,则在保存的文本文件中包含置信度值,为分析和筛选提供更详细的输出。 |
workers | int | 8 | 用于加载数据的工作线程数。较大的值可以加快数据预处理,但可能增加 CPU 使用率。设置为 0 时使用主线程,在某些环境中会更稳定。 |
augment | bool | False | 在验证期间启用测试时增强(TTA),通过对输入的变换版本运行推理,可能提高检测准确率,但会降低推理速度。仅适用于 Ultralytics PyTorch 模型。 |
agnostic_nms | bool | False | 启用类别无关的非极大值抑制,无论预测类别为何,都会抑制得分较低且相互重叠的框。适用于以实例为核心的应用。对于无 NMS 推理(在 YOLO26 或 YOLOv10 上使用 nms=False),此功能仅用于防止同一检测结果带有多个类别标签(IoU=1.0 的重复项),不会根据 IoU 阈值抑制不同的框。 |
single_cls | bool | False | 在验证期间将所有类别视为单个类别。适用于评估模型在二元检测任务上的性能,或类别区分不重要的情况。 |
visualize | bool | False | 可视化每张图像的真实标注、真正例、假正例和假负例。适用于调试和模型解读。 |
show_labels | bool | True | 当 visualize=True 时,在验证可视化中显示类别标签。设置为 False 可更清晰地查看匹配项和错误。 |
show_conf | bool | True | 当 visualize=True 时,在验证可视化中显示置信度分数。设置为 False 可更清晰地查看匹配项和错误。 |
compile | bool 或 str | False | 使用backend='inductor'启用 PyTorch 2.x torch.compile图编译。接受True → "default"、False → 禁用,或"default"、"reduce-overhead"、"max-autotune-no-cudagraphs"等字符串模式。如果不受支持,则会发出警告并回退到即时执行模式。 |
channels_last | bool | None | 对原生 PyTorch 验证使用 channels_last(NHWC)内存格式。对于启用了 oneDNN 的 Linux 和 Windows x86 CPU,且 PyTorch 版本为 1.13 或更高版本时,None 会自动启用该格式;False 会禁用该格式;True 会在受支持的 x86 CPU 或 CUDA 设备上请求使用该格式。ARM64、MPS、较旧的 PyTorch 版本、未启用 oneDNN 的 CPU,以及导出格式均不受影响;训练期间的验证会保持训练模型的布局。 |
nms | bool,可选 | None | 默认使用 NMS 执行一对多推理(None 或 True)。设置 False 可在可用时使用无 NMS 的一对一检测头。详情请参阅端到端检测指南。 |
谨慎调整和反复试验对于确保获得最佳性能以及检测和防止过拟合至关重要。
导出设置#
YOLO 模型的导出设置包括将模型保存或导出以供不同环境使用的配置。这些设置会影响性能、大小和兼容性。关键设置包括导出文件格式(例如 ONNX、TensorFlow SavedModel)、目标设备(例如 CPU、GPU),以及通过量化设置数值精度(quantize)。模型任务和目标环境的限制也会影响导出过程。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
format | str | 'torchscript' | 导出模型的目标格式,例如 'onnx'、'torchscript'、'engine'(TensorRT)或其他格式。每种格式都支持不同的部署环境。 |
name | str | None | 需要指定目标硬件的格式所用的硬件目标名称:Hailo 架构('hailo8'、'hailo8l'、'hailo10h'、'hailo15h'、'hailo15l';默认为 'hailo8l')、Rockchip RKNN 芯片(默认为 'rk3588')、Huawei Ascend SoC(CANN --soc_version;默认为 'Ascend310B4')、Qualcomm QNN HTP 目标(默认为 '73'),或 AMD Xilinx Versal AI Edge Series Gen 2 设备(默认为 've2-xc2ve3858',即 VEK385 评估套件)。这与其他模式使用的 project/name 运行命名组合不同。 |
imgsz | int 或 tuple | 640 | 模型输入的目标图像尺寸。可以是整数(表示正方形图像,例如,640 表示 640×640),也可以是元组 (height, width)(表示指定尺寸)。如果未传入,导出时会复用已加载检查点中记录的训练尺寸:官方 YOLO26 检查点中,基于 Cityscapes(yolo26n-sem.pt)预训练的语义模型记录为 1024,深度模型记录为 768,分类模型记录为 224,OBB 模型记录为 1024,其他任务(包括基于 ADE20K(yolo26n-sem-ade20k.pt)预训练的语义模型)记录为 640;微调模型则记录其训练时使用的 imgsz。由 YAML 构建的模型没有记录训练尺寸,会使用 640。 |
optimize | bool | False | 为 DEEPX 启用更高等级的编译器优化,以降低推理延迟,但会增加编译时间。 |
quantize | int 或 str | None | 量化精度:16(FP16,可减小模型体积,并在受支持的硬件上加快推理速度)或 8(INT8/PTQ,可进一步压缩模型,同时将精度损失降至最低,主要用于边缘设备;需要校准 data/fraction);32 会在支持的情况下选择 FP32;如果未设置,则使用 FP32,除非目标设备要求量化,例如 NXP 要求 INT8。使用 quantize=8 训练的检查点始终导出为 INT8:onnx 和 engine 无需校准,即可根据检查点包含的范围进行导出;其他格式或精度则不受支持。'w8a8' 和 'w16a16' 是 8 和 16 的别名;混合精度 'w8a16'(INT8 权重与 16 位激活:CoreML、LiteRT、QNN)和 'w8a32'(动态 INT8:LiteRT)仅受对应格式支持。此参数取代了已弃用的 half/int8 标志(half=True → 16,int8=True → 8,这些标志仍可使用,但会显示弃用警告)。仅允许使用目标格式支持的精度(见下文)。 |
dynamic | bool | False | 允许 TorchScript、ONNX、OpenVINO、TensorRT、CoreML 和 MNN 导出采用动态输入尺寸,提高处理不同图像尺寸时的灵活性。 |
simplify | bool | True | 对于会构建 ONNX 中间图的导出,使用 onnxslim 简化该图(参见导出格式),可能提高性能并改善与推理引擎的兼容性。 |
opset | int | None | 指定用于构建 ONNX 图的导出格式的 ONNX opset 版本(参见导出格式),以兼容不同的 ONNX 解析器和运行时。如果未设置,则使用 opset 18(PyTorch < 2.4 时使用较低版本),且不高于已安装的 onnx 版本。RKNN、Ascend、AMD Xilinx、Hailo 和 RT-DETR TensorFlow 导出会设置各自的 opset。 |
workspace | float 或 None | None | 设置 TensorRT 优化的最大工作区大小(单位为 GiB),以平衡内存使用量和性能。使用 None 可让 TensorRT 自动分配工作区,最大不超过设备上限。 |
nms | bool,可选 | None | None 会导出原始的一对多预测结果,以便进行外部 NMS(YOLO26 在 Axelera 上保留其无 NMS 检测头);True 会在支持的情况下嵌入 NMS;False 会在可用时选择无 NMS 检测头。CoreML 嵌入式 NMS 支持静态形状的 detect、segment 和 pose。请参阅端到端检测指南。 |
conf | float | None | 用于所有导出时生成 NMS 的置信度阈值:nms=True 导出、Hailo 的非端到端 detect 导出,以及 IMX 的 detect、pose 和 segment 导出;后者会在内部强制使用 nms=True。未设置时默认为 0.25。 |
iou | float | 0.5 | 用于所有导出时生成 NMS 的 IoU 阈值:nms=True 导出、Hailo 的非端到端 detect 导出,以及 IMX 的 detect、pose 和 segment 导出;后者会在内部强制使用 nms=True。 |
max_det | int | 300 | 导出模型输出中保留的最大检测数量。适用于所有格式的 nms=True 导出,但 CoreML 检测除外,其原生 NMS 流程没有检测数量上限;也适用于无 NMS 的端到端检测导出(YOLO26、YOLOv10,上限限制为可用锚点数量)以及 IMX 的 detect、pose 和 segment 导出。 |
agnostic_nms | bool | False | 在通过标准 nms=True 流程生成导出时的 NMS(包括 CoreML 自带的 NMS 阶段)中启用类别无关 NMS,抑制不同类别之间得分较低且重叠的框,而不只是同一类别内的框。Hailo 或 IMX 自行生成的 NMS 配置不支持此选项,因此不会采用该设置,仍会按类别进行处理。此选项也会应用于无 NMS 的端到端导出(YOLO26、YOLOv10),但仅用于防止同一检测结果带有多个类别标签(IoU=1.0 的重复项),不会根据 IoU 阈值抑制不同的框。 |
batch | int | 1 | 指定导出模型的批量推理大小,或导出模型在 predict 模式下将并发处理的最大图像数。导出参数中不包含 batch 的格式会以批量大小 1 导出,并拒绝其他值。 |
device | str | None | 指定用于导出的设备:GPU(device=0)、CPU(device=cpu)、Apple 芯片的 MPS(device=mps)、华为昇腾 NPU(device=npu 或 device=npu:0),或 NVIDIA Jetson 的 DLA(device=dla:0 或 device=dla:1)。TensorRT 导出会自动使用 GPU,但 TensorRT 11 不支持 DLA。使用 device=npu 的 OpenVINO INT8 导出针对 Intel NPU 进行了优化。 |
verbose | bool | False | 在 format='engine' 导出期间,将 TensorRT 构建器日志级别提高到 VERBOSE。其他导出格式会忽略此设置。 |
data | str | None | 校准数据集:YAML 路径(非分类任务)、NDJSON 路径或 URL、平台数据集 URI(ul://owner/datasets/name)或网页 URL。平台数据集需要 API 密钥和 Python 3.11+。分类任务还接受数据集目录或内置数据集名称。如果启用了 INT8 但未指定校准数据集,Ultralytics 会在需要时选择特定任务的校准数据集,否则使用模型任务的默认数据集。使用 quantize=8 训练的检查点自带 INT8 范围,无需校准数据。 |
split | str | 'val' | 用于从 data 构建 INT8 量化校准数据加载器的数据集划分('train'、'val' 或 'test')。 |
fraction | float、int 或 list | 1.0 | 用于 INT8 校准的数据集子集:比例、图像数量或 [train, val, test] 值。1 表示完整数据划分,大于 1 的整数表示图像数量;只有可选的 test 条目接受 0/0.0 表示不使用任何数据。两项列表会保留完整的 test。 |
合理配置可确保导出的模型针对其使用场景进行了优化,并能在目标环境中有效运行。
解决方案设置#
Ultralytics Solutions 配置设置提供了灵活性,可根据对象计数、热力图生成、锻炼追踪、数据分析、区域追踪、队列管理和基于区域的计数等任务自定义模型。这些选项便于进行调整,从而根据特定需求获得准确且实用的结果。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model | str | None | Ultralytics YOLO 模型文件的路径。 |
region | list 或 dict | None | 定义感兴趣区域的点,可以是 (x, y) 元组列表,也可以是将区域名称映射到点列表的字典(仅支持多个 RegionCounter 区域)。如果为 None,则需要区域的解决方案会退回到预定义的默认区域。 |
show_in | bool | True | 控制是否在视频流中显示流入计数的标志。 |
show_out | bool | True | 控制是否在视频流中显示流出计数的标志。 |
analytics_type | str | 'line' | 图表类型,即 line、bar、area 或 pie。 |
colormap | int | cv2.COLORMAP_DEEPGREEN | 要用于热力图的颜色映射。 |
line_width | int | 2 | 解决方案绘制的框、关键点和计数的线条粗细。 |
verbose | bool | True | 启用逐帧日志,记录输入形状、类别计数和处理速度。跟踪调用本身始终不会输出日志。 |
json_file | str | None | 包含所有停车位坐标数据的 JSON 文件路径。 |
up_angle | float | 145.0 | “向上”姿势的角度阈值。 |
kpts | list[int] | [6, 8, 10] | 用于监测锻炼动作的三个关键点索引组成的列表。这些关键点对应身体关节或部位,例如肩部、肘部和手腕,可用于俯卧撑、引体向上、深蹲和腹部锻炼等动作。 |
down_angle | float | 90.0 | “向下”姿势的角度阈值。 |
blur_ratio | float | 0.5 | 调整模糊强度百分比,取值范围为 0.1 - 1.0。 |
crop_dir | str | 'cropped-detections' | 用于存储裁剪后检测结果的目录名称。 |
records | int | 5 | 触发安全警报系统发送邮件所需的检测总数。 |
vision_point | tuple[int, int] | (20, 20) | 视觉系统使用 VisionEye Solution 跟踪对象并绘制路径的位置。 |
source | str | None | 输入源的路径(视频、RTSP 等)。仅适用于 Solutions 命令行界面 (CLI)。 |
figsize | tuple[float, float] | (12.8, 7.2) | Analytics 图表的图幅尺寸(英寸);(12.8, 7.2) 会渲染 1280×720 的帧。 |
fps | float | 30.0 | 用于速度计算的每秒帧数。 |
max_hist | int | 5 | 每个对象用于速度/方向计算的最大历史跟踪点数。 |
meter_per_pixel | float | 0.05 | 用于将像素距离转换为实际单位的缩放系数。 |
max_speed | int | 120 | 最高速度(km/h);估算速度超过此值时将按此值封顶。 |
data | str | 'images' | 用于相似性搜索的图像目录路径。 |
imgsz | int | 640 | 模型推理的输入图像尺寸。 |
recognizer | str 或 Callable | 'paddleocr' | 文本识别后端:'paddleocr'(在 ONNX Runtime 上运行的 PP-OCRv6)、'tensorrt'(在 NVIDIA GPU 上以 FP16 TensorRT 引擎运行的 PP-OCRv6)、类似 'korean_PP-OCRv5_mobile_rec' 的 PaddleOCR 语言模型名称,或接受 BGR 裁剪图像并返回 (text, confidence) 的可调用对象。 |
增强设置#
数据增强 技术通过在训练数据中引入多样性,对于提升 YOLO 模型的鲁棒性和性能至关重要,并帮助模型更好地泛化到未见过的数据。下表概述了每个增强参数的用途和效果:
| 参数 | 类型 | 默认值 | 支持的任务 | 范围 | 说明 |
|---|---|---|---|---|---|
hsv_h | float | 0.015 | detect, segment, semantic, depth, classify, pose, obb | 0.0 - 1.0 | 按色轮的一定比例调整图像色调,增加颜色变化。帮助模型适应不同光照条件。对于 classify,仅在 auto_augment=None 时应用。 |
hsv_s | float | 0.7 | detect, segment, semantic, depth, classify, pose, obb | 0.0 - 1.0 | 按一定比例改变图像饱和度,从而影响颜色强度。适用于模拟不同的环境条件。对于 classify,仅在 auto_augment=None 时应用。 |
hsv_v | float | 0.4 | detect, segment, semantic, depth, classify, pose, obb | 0.0 - 1.0 | 按一定比例修改图像的明度(亮度),帮助模型在各种光照条件下保持良好表现。对于 classify,仅在 auto_augment=None 时应用。 |
degrees | float | 0 | detect, segment, semantic, depth, pose, obb | 0.0 - 180 | 在指定角度范围内随机旋转图像,提升模型识别不同朝向对象的能力。 |
translate | float | 0.1 | detect, segment, semantic, depth, pose, obb | 0.0 - 1.0 | 按图像尺寸的一定比例水平和垂直平移图像,帮助模型学会检测部分可见的对象。 |
scale | float | tuple | 0.5 | detect, segment, semantic, depth, classify, pose, obb | 0 - 1,或显式指定的 (min, max) 元组(不适用于 classify) | 按增益系数缩放图像,模拟与摄像头距离不同的对象。 |
shear | float | 0 | detect, segment, semantic, depth, pose, obb | -180 - +180 | 按指定角度剪切图像,模拟从不同角度观察对象的效果。 |
perspective | float | 0 | detect, segment, semantic, depth, pose, obb | 0.0 - 0.001 | 对图像应用随机透视变换,增强模型理解 3D 空间中对象的能力。 |
flipud | float | 0 | detect, segment, semantic, depth, classify, pose, obb | 0.0 - 1.0 | 按指定概率将图像上下翻转,增加数据变化性,同时不影响对象特征。 |
fliplr | float | 0.5 | detect, segment, semantic, depth, classify, pose, obb | 0.0 - 1.0 | 按指定概率将图像左右翻转,适用于学习对称对象并提高数据集多样性。 |
bgr | float | 0 | detect, segment, semantic, depth, pose, obb | 0.0 - 1.0 | 按指定概率将图像通道从 RGB 翻转为 BGR,适用于提升模型对通道顺序错误的鲁棒性。 |
mosaic | float | 1 | detect, segment, semantic, pose, obb | 0.0 - 1.0 | 将四张训练图像合并为一张,模拟不同的场景构成和对象交互。适用于复杂场景理解。 |
mixup | float | 0 | detect, segment, semantic, pose, obb | 0.0 - 1.0 | 混合两张图像及其标签,生成一张合成图像。通过引入标签噪声和视觉变化,提升模型的泛化能力。 |
cutmix | float | 0 | detect, segment, semantic, pose, obb | 0.0 - 1.0 | 合并两张图像的部分区域,形成局部混合,同时保留清晰的区域边界。通过构造遮挡场景增强模型鲁棒性。 |
copy_paste | float | 0 | segment, semantic, obb | 0.0 - 1.0 | 粘贴符合条件对象的比例;flip 会在图像内镜像这些对象,而 mixup 还会将此值用作跨图像应用概率。 |
copy_paste_mode | str | flip | segment, semantic, obb | - | 指定要使用的 copy-paste 策略。选项包括 'flip' 和 'mixup'。 |
auto_augment | str | randaugment | classify | - | 应用预定义的增强策略('randaugment'、'autoaugment' 或 'augmix'),通过增加视觉多样性来提升模型性能。 |
erasing | float | 0.4 | classify | 0.0 - 1.0 | 训练期间随机擦除图像区域,促使模型关注不那么明显的特征。 |
augmentations | list | None | detect, segment, semantic, depth, pose, obb | - | 用于高级数据增强的自定义 Albumentations 变换(仅限 Python API)。接受变换对象列表,以满足特定的增强需求。 |
根据数据集和任务需求调整这些设置。尝试不同的取值有助于找到性能最佳的增强策略。
日志记录、检查点和绘图设置#
训练 YOLO 模型时,日志记录、检查点、绘图和文件管理都很重要:
- 日志记录:使用 TensorBoard 等库或写入文件,跟踪模型进度并诊断问题。
- 检查点:定期保存模型,以便恢复训练或尝试不同配置。
- 绘图:使用 Matplotlib 或 TensorBoard 等库可视化性能和训练进度。
- 文件管理:整理训练期间生成的文件(例如检查点、日志文件和图表),以便轻松访问和分析。
有效管理这些方面有助于跟踪进度,并让调试和优化更加轻松。
| 参数 | 默认值 | 说明 |
|---|---|---|
project | None | 指定运行任务的项目目录。相对路径会置于 runs_dir/<task> 下(例如,使用默认的 runs_dir 和运行名称进行检测训练时,project="my_proj" 会将结果保存到 runs/detect/my_proj/train);绝对路径则按原样使用。如果未指定,运行结果会保存在 runs_dir/<task> 下。每次运行都会保存在单独的子目录中。 |
name | None | 定义实验名称。如果未指定,YOLO 会使用模式名称,并为每次运行递增编号(例如 train、train-2),以避免覆盖。 |
exist_ok | False | 确定是否覆盖现有实验目录。True 允许覆盖;False 则禁止覆盖。 |
plots | True | 控制训练和验证图表的生成与保存。设为 True 可创建损失曲线、精确率-召回率曲线和预测样例等图表,直观跟踪性能。 |
save | True | 启用训练检查点和最终模型权重的保存。设为 True 可定期保存模型状态,以便恢复训练或部署模型。 |
自定义配置文件#
加载已保存的 YAML 文件,以便重复使用一整组参数,而无需在命令中逐项传入。cfg 参数会覆盖 default.yaml 中的值,而同时传入的其他参数仍具有更高优先级。
| 参数 | 默认值 | 说明 |
|---|---|---|
cfg | None | YAML 文件的路径,其值会替换 default.yaml 条目。请参阅覆盖默认配置文件,了解 CLI 示例。 |
常见问题#
通过调优批次大小、学习率、动量和权重衰减等超参数来提升性能。调整数据增强设置,选择合适的优化器,并使用提前停止或混合精度等技术。
影响精度的关键超参数包括:
- 批量大小 (
batch):较大的批量大小可以稳定训练,但需要更多内存。 - 学习率 (
lr0):较小的学习率有助于精细调整,但收敛速度更慢。 - 动量 (
momentum):加速梯度向量,同时抑制振荡。 - 图像尺寸 (
imgsz):较大的图像尺寸可以提高精度,但会增加计算负载。
根据你的数据集和硬件进行调整。请参阅训练设置了解更多信息。
- 批量大小 (
评论119
提出问题、分享结果,或帮助其他人。
ykn96
@glenn-jocher alright thanks! I am going to be experimenting among the imgsz, multi_scale and all the batch size stuff
Glenn JocherUltralyticsThat sounds like a good plan — I’d start with
batch=-1to auto-fit GPU memory, then sweepimgszand a modestmulti_scalesuch as0.25; the Train Settings section is the best reference, and feel free to drop any results or blockers here.
ykn96
Hello! I have a question about best practices for training and runnining inference, question about the parameters rect and imgsz. So my dataset has a wide variety of resolutions and aspect ratios, but my video feed only has 1920x1080
Question;
- During training, should i set rect = True ?
- During training, should i set imgsz = 1920?
- During inference, do i need to set imgsz as the tuple 1920 x 1080?
Thank you!
A-tavv
Hi. You’re thinking about the right things, this mostly comes down to how well you want training to match your real inference scenario.
-
rect=True during training? Yes, generally a good idea in your case. Since your dataset has mixed aspect ratios, this helps preserve them instead of forcing everything into square shapes. That reduces distortion and usually improves performance, especially when your inference input (1920×1080) is not square.
-
imgsz=1920 during training? No, this is usually not practical. Training at 1920 will:
Use a lot of VRAM Slow training significantly Give diminishing returns
A better approach:
Use something like imgsz=640 or imgsz=1280 (depending on your GPU) The model will still generalize well to higher resolutions at inference
- imgsz=(1920,1080) during inference? You can, but you usually don’t need to.
Most YOLO implementations:
Resize while keeping aspect ratio (letterboxing) Expect a single integer like imgsz=640 or imgsz=1280
Recommended practical setup:
Train: imgsz=640 or 1280, rect=True Inference: same imgsz as training (e.g., 640 or 1280)
If you really want max detail at inference, you can increase imgsz, but:
It increases latency Gains are often small unless objects are very tiny
Rule of thumb: Train at a reasonable resolution, keep it consistent, and only scale up inference if you see a real accuracy bottleneck
-
Glenn JocherUltralyticsThat’s mostly right; the main correction is that if you pass a tuple for inference it should be
imgsz=(1080, 1920)because Ultralytics expects(height, width), andrect=Trueis already the default in predict mode. For training,rect=Truecan help with mixed aspect ratios, but I’d still keepimgszpractical like640or1280rather than1920unless you specifically need more small-object detail; feel free to post follow-ups here so the Ultralytics team can see them, and the relevant args are in the Configuration docs and Predict mode docs.ykn96
@glenn-jocher @A-tavv thank you for your help! Hmm im trying to train a head detector, so i think the heads are really small. Problem is i am encountering an out of memory problem even if i try to use an intermediate size such as 960.
I wil probably just stick to 640, since increasing the max_dets also makes me run into the OOM much earlier.
Glenn JocherUltralyticsYes, that sounds reasonable; for tiny heads
max_detusually won’t improve learning and mainly affects retained detections during val/predict, so I’d leave it near default, keepimgsz=640, reducebatchor trybatch=-1withamp=True, and if small-object recall is still limited the better next step is usually tiling/cropping your1920x1080frames into patches rather than pushing full-frame resolution higher; the relevant args are in the Configuration docs.
ykn96
Hey there! I have a question about the max_det parameter during training. So i am using the NWPU crowd dataset, which sometimes has 4000+ boxes in an image, i was wondering if it is necessary for me to increase max_det such that it can cover that number?
A-tavv
It is not necessary to match max_det to the number of ground truth boxes. It’s a post-processing limit, not a training constraint.
max_det mainly affects inference, not training.
During training, the model still sees all ground-truth boxes and learns from them max_det only limits how many predictions are kept after NMS (non maximum suppression) during inference/validation
So even if your images have 4000+ objects, the model is still learning from all of them.
When would increasing max_det matter?
Only if during validation/inference:
You notice predictions getting cut off Or evaluation metrics look artificially low because detections are being capped
In that case, you can increase it (e.g., 1000 → 3000 or higher), but keep in mind:
Higher max_det = slower NMS More memory usage
For dense datasets, in your case: NWPU-Crowd:
A practical setup:
Keep max_det moderate (e.g., 1000–2000) to start Check if predictions are being truncated Only increase if you see an actual limitation, not just based on GT count
ykn96
Will capping the max_det at a lower number affect the error that is being used for the back propagation during learning?
As i am trying to train a head detector, i can see that there are some heads that are not being detected, especially when they are closer to the background of the image i.e. further in the background and are thus smaller.
AlexShaGH
Greetings. I’m trying to understand what the best combination of training and inference parameters pertaining to image size for my specific imagery is. The training dataset is 16 bits depth images of the identical static size – 720 x 1280. The images coming for inference will be of the same specification. The model will be quantized to FP16 and deployed on edge device. It is my understanding that for the best speed, it’s better to specify the exact image size for training and for inference. How do I do this? If I issue model.train(…, imgsz=(720, 1280), rect=True) or model.train(…, imgsz=[720, 1280], rect=True), I get a warning:
WARNING ⚠️ updating to 'imgsz=1280'. 'train' and 'val' imgsz must be an integer, while 'predict' and 'export' imgsz may be a [h, w] list or an integer, i.e. 'yolo export imgsz=640,480' or 'yolo export imgsz=640'`
There is also a warning that it cannot be done on multiple GPUs and will default to rect=False. This I can solve by specifying only one cuda device.
Please, advise on how exactly to set the parameters for training and for inference so the model performs the best on static size imagery on edge device.
Brenda-Caroline
Hello everyone, the default image size for imgsz is 640. I have a question about resizing the image size. When choosing a size for the images, are they resized in a square or rectangular format? For example: 640 x 640; 256 x 256; 480 x 480 or 1080 x 1920
BaoQuoc285
How can I use focal loss in YOLOv11 CLI training to handle an imbalanced dataset?
e-roe
Hello, Does YOLOv11 actually perform data augmentation by increasing the dataset size, or does it only enhance diversity without expanding the dataset? My impression is that it doesn’t increase the dataset size—for example, it applies a filter to an image, and only the modified image is presented to the model, not the original one.
Glenn JocherUltralytics(已编辑)@e-roe YOLO11's data augmentation applies real-time transformations during training without permanently expanding the dataset size. Each epoch presents new variations of original images through techniques like mosaic and mixup (see Augmentation Settings). The original images remain in the dataset but are dynamically modified during training iterations.
1
rohith-aiunika
Hi yolo team, Is there any way to reduce the font size and hide the box in yolo object tracking? i am using this to track my video, results = model.track(source=video_path, show=False, stream=True, save=False)
Glenn JocherUltralytics(已编辑)@rohith-aiunika to hide the boxes and labels in tracking, set
show_boxes=Falseandshow_labels=False. Theline_widthargument controls the box thickness and scales the label text size, so lowering it reduces both. For more details, refer to the Predict Settings documentation.
rohith-aiunika
is there any way to reduce the font size and hide the box in yolo object tracking?
Glenn JocherUltralytics@rohith-aiunika to reduce the font size and hide the bounding boxes in YOLO object tracking, you can modify the visualization arguments in the code. Specifically, set
show_labels=False,show_boxes=False, and adjust theline_widthparameter if necessary. For more details, refer to the Predict Guide.
D3RK0
Is it possible to use Cutmix and Mixup data augmentations for training YOLOv8 analogously to this PyTorch code example: https://pytorch.org/vision/main/auto_examples/transforms/plot_cutmix_mixup.html#after-the-dataloader
Glenn JocherUltralytics(已编辑)YOLO supports both through training arguments:
mixupandcutmixset the probability (default 0.0) of applying each augmentation, e.g.model.train(data="coco8.yaml", mixup=0.2, cutmix=0.2). See Augmentation Settings.D3RK0
@glenn-jocher Many thanks for replying!
I have taken steps to manually implement cutmix-mixup augmentations for YOLOv8 training. As you may know, implementing cutmix-mixup augmentations will transform (at least for the version of PyTorch) the labels from integers to one-hot. Do you know if YOLOv8 is compatible with one-hot labels, especially in respect to its default loss function? Or will it require additional customisation?
Glenn JocherUltralyticsYOLOv8 does not natively support one-hot encoded labels, so using them may require adjustments to the loss function. You may need to customize the model to handle one-hot labels appropriately. If you have further questions, feel free to ask!
