Ultralytics YOLO27：

配置#

YOLO 设置和超参数对模型的性能、速度和准确率起着关键作用。这些设置会影响模型在训练、验证和预测等不同阶段的行为。



Watch: Mastering Ultralytics YOLO: Configuration

Ultralytics 命令使用以下语法：

示例
yolo TASK MODE ARGS

其中：

默认的 ARG 值定义在此页面中，来源于 cfg/default.yaml 文件。

任务#

Ultralytics YOLO 模型可以执行各种计算机视觉任务，包括：

  • Detect：目标检测用于识别图像或视频中的对象并确定其位置。
  • Segment：实例分割将图像或视频划分为对应不同对象或类别的区域。
  • Semantic segmentation (semantic)：语义分割为图像中的每个像素分配类别标签，以实现密集场景理解。
  • Depth (depth)：单目深度估计根据单张 RGB 图像预测每个像素以米为单位的深度图。
  • Classify：图像分类预测输入图像的类别标签。
  • Pose：姿态估计识别图像或视频中的对象并估计其关键点。
  • OBB：定向边界框使用旋转边界框，适用于卫星图像或医学影像。
参数默认值描述
task'detect'指定 YOLO 任务：detect 用于目标检测，segment 用于实例分割，semantic 用于语义分割，depth 用于单目深度估计，classify 用于分类，pose 用于姿态估计，obb 用于定向边界框。每项任务都针对图像和视频分析中的特定输出与问题进行了设计。

任务指南

模式#

Ultralytics YOLO 模型支持不同模式，每种模式都针对模型生命周期中的特定阶段而设计：

  • Train：在自定义数据集上训练 YOLO 模型。
  • Val：验证训练好的 YOLO 模型。
  • Predict：使用训练好的 YOLO 模型对新图像或视频进行预测。
  • Export：导出 YOLO 模型以进行部署。
  • Track：使用 YOLO 模型实时跟踪对象。
  • Benchmark：评测 YOLO 导出模型（ONNX、TensorRT 等）的速度和准确率。
参数默认值描述
mode'train'指定 YOLO 模型的运行模式：train 用于模型训练，val 用于验证，predict 用于推理，export 用于转换为部署格式，track 用于目标跟踪，benchmark 用于性能评估。每种模式支持从开发到部署的不同阶段。

模式指南

训练设置#

YOLO 模型的训练设置包括会影响模型性能、速度和准确率的超参数与配置。关键设置包括批次大小、学习率、动量和权重衰减。优化器、损失函数和数据集构成的选择也会影响训练。调参与实验对于获得最佳性能至关重要。更多详情请参阅 Ultralytics 入口函数。

参数类型默认值描述
modelstrNone指定用于训练的模型文件。接受指向 .pt 预训练模型或 .yaml 配置文件的路径。对于定义模型结构或初始化权重至关重要。
datastrNone数据集 YAML 的路径（例如 coco8.yaml），其中包含训练和验证数据的路径、类别名称和类别数量。分类任务则使用数据集目录或内置数据集名称（例如 imagenet10）。
epochsint100训练周期总数。每个周期表示完整遍历整个数据集一次。调整此值会影响训练时长和模型性能。
timefloatNone最大训练时间（小时）。设置后，它会覆盖 epochs 参数，使训练在达到指定时长后自动停止。适用于受时间限制的训练场景。
patienceint100在验证指标没有改善的情况下，等待多少个周期后提前停止训练。通过在性能趋于稳定时停止训练，有助于防止过拟合。
batchint 或 float16批次大小有三种模式：设置为整数（例如 batch=16）、自动模式（使用 60% 的 GPU 内存，batch=-1），或带指定利用率比例的自动模式（batch=0.70）。
imgszint640训练目标图像尺寸。图像会被调整为边长等于指定值的正方形（如果为 rect=False）；对于 YOLO 模型会保持宽高比，但 RT-DETR 不会。会影响模型准确率和计算复杂度。
saveboolTrue启用训练检查点和最终模型权重的保存。适用于恢复训练或部署模型。
save_periodint-1模型检查点的保存频率，以周期数指定。值为 -1 时禁用此功能。适用于在长时间训练期间保存中间模型。
cacheboolFalse启用将数据集图像缓存到内存（True/ram）、磁盘（disk），或禁用缓存（False）。通过减少磁盘 I/O 提高训练速度，但会增加内存使用量。
deviceint 或 str 或 listNone指定训练使用的计算设备：单个 GPU（device=0）、多个 GPU（device=[0,1]）、CPU（device=cpu）、Apple silicon 上的 MPS（device=mps）、Huawei Ascend NPU（device=npu:0 或 device=npu:0,1），或自动选择空闲 GPU（device=-1）或多个空闲 GPU（device=[-1,-1]）。
workersint8数据加载的工作线程数（Multi-GPU 训练时为每个 RANK）。会影响数据预处理和输入模型的速度，在多 GPU 配置中尤其有用。
projectstrNone保存训练输出的项目目录名称。便于有序存储不同实验。
namestrNone训练运行名称。用于在项目文件夹中创建子目录，以存储训练日志和输出。
exist_okboolFalse如果为 True，则允许覆盖现有的项目/名称目录。便于迭代实验，无需手动清除之前的输出。
save_dirstrNone指定保存运行输出的确切目录，覆盖 project/name 组合。路径将按原样使用，不会自动递增，因此连续运行会重复使用同一目录。
pretrainedbool 或 strTrue决定是否从预训练权重开始训练。可以是布尔值，也可以是要加载的权重文件路径。pretrained=False 会使用随机初始化的权重进行训练，同时保留模型架构。
cls_remapboolTrue跨数据集微调时，会将预训练分类头中与新模型类别名称匹配的行复制到新模型中，因此重叠类别会保留已学习的偏置；当分类头宽度不变时，还会保留其权重。无论类别数量不同，还是数量相同但类别顺序不同，均适用。
optimizerstr'auto'训练所使用的优化器。选项包括 SGD、MuSGD、Adam、Adamax、AdamW、NAdam、RAdam、RMSProp，或 auto，根据训练迭代次数选择 AdamW 或 MuSGD。会影响收敛速度和稳定性。
seedint0设置训练的随机种子，确保使用相同配置运行时结果具有可复现性。
deterministicboolTrue强制使用确定性算法，确保结果可复现，但由于限制使用非确定性算法，可能会影响性能和速度。
verboseboolTrue启用训练期间的详细输出，在控制台中显示进度条、每周期指标和其他训练信息。
single_clsboolFalse训练期间将多类别数据集中的所有类别视为单一类别。适用于二分类任务，或关注对象是否存在而非其类别的场景。
classeslist[int]None指定要训练的类别 ID 列表。适用于过滤掉某些类别，仅关注指定类别。
rectboolFalse启用最小填充策略——批次中的图像只进行最小程度的填充以达到统一尺寸，最长边等于 imgsz。可以提高效率和速度，但可能影响模型准确率。
multi_scalefloat0.0每个批次随机改变 imgsz，变化范围为 +/- multi_scale（例如从 0.25 -> 0.75x 到 1.25x），并四舍五入到模型步幅的倍数；0.0 会禁用多尺度训练。
cos_lrboolFalse使用余弦学习率调度器，在各个周期内按照余弦曲线调整学习率。有助于管理学习率，从而实现更好的收敛。
close_mosaicint10在最后 N 个周期中禁用马赛克数据增强，以便在训练结束前稳定训练。设置为 0 时禁用此功能。
resumeboolFalse从最后保存的检查点恢复训练。自动加载模型权重、优化器状态和周期计数，无缝继续训练。
ampbool 或 strTrue设置训练精度：True 或 "fp16" 使用 FP16，"bf16" 在受支持的 CUDA 设备上使用 BF16，False 或 "fp32" 使用 FP32。
quantizeint 或 strNone设为 8（或 "int8"）以进行 INT8 量化感知训练（QAT），该训练在循环中使用伪量化进行微调，从而使权重能够承受 INT8 导出。请参阅量化感知训练。
fractionfloat、int 或 list1.0数据集子集，可指定比例/数量或 [train, val, test] 列表。1 表示完整拆分，超过 1 的整数表示图像数量，只有可选的测试项接受 0/0.0 来表示无数据。包含两个项目的列表会保留完整测试集。
profileboolFalse启用训练期间对 ONNX 和 TensorRT 速度进行分析，有助于优化模型部署。
freezeint 或 listNone冻结模型的前 N 层，或按索引或模块名称指定的层（23.cv2，不含开头的 model.），从而减少可训练参数数量。适用于微调或迁移学习。
lr0float0.01初始学习率（即 SGD=1E-2、Adam=1E-3）。调整此值对优化过程至关重要，会影响模型权重更新的速度。
lrffloat0.01最终学习率占初始学习率的比例 =（lr0 * lrf），与调度器结合使用，以随时间调整学习率。
momentumfloat0.937SGD 的动量因子或 Adam 优化器的 beta1，影响当前更新中对历史梯度的整合。
weight_decayfloat0.0005L2 正则化项，通过惩罚较大的权重来防止过拟合。
warmup_epochsfloat3.0学习率预热周期数，将学习率从较低值逐步提高到初始学习率，以在训练早期稳定训练。
warmup_momentumfloat0.8预热阶段的初始动量，在预热期间逐步调整到设定的动量。
warmup_bias_lrfloat0.1预热阶段偏置参数的学习率，有助于稳定最初几个周期的模型训练。在默认 optimizer='auto' 下会自动设置为 0.0，因此需要显式指定优化器才能使用它。
distill_modelstrNone用于知识蒸馏的教师模型检查点路径（例如 yolo26x.pt）。设置后，学生模型会在冻结教师模型的指导下，通过额外的蒸馏损失进行训练。
disfloat6.0添加到标准检测损失中的蒸馏损失权重。值越大，教师模型特征指导的影响越大。
boxfloat7.5损失函数中框损失分量的权重，影响模型对准确预测边界框坐标的重视程度。
clsfloat0.5总损失函数中的分类损失权重，影响正确类别预测相对于其他分量的重要性。
cls_pwfloat0.0使用类别频率倒数处理类别不平衡时的类别加权幂。0.0 禁用类别加权，1.0 应用完整的频率倒数加权。0 到 1 之间的值表示部分加权。
dflfloat1.5框距离回归项的权重：当检测头使用 reg_max > 1 时为分布式焦点损失（DFL），在无 DFL 的 YOLO26（reg_max: 1）中为对归一化框距离计算的 L1 损失。
posefloat12.0姿态估计模型中姿态损失的权重，影响模型对准确预测姿态关键点的重视程度。
kobjfloat1.0姿态估计模型中关键点目标性损失的权重，用于平衡检测置信度与姿态准确率。
rlefloat1.0姿态估计模型中残差对数似然估计损失的权重，影响关键点定位的精度。
anglefloat1.0obb 模型中角度损失的权重，影响定向边界框角度预测的精度。
dlogfloat1.0深度估计模型中尺度不变对数（SILog）损失的权重，这是驱动深度准确率的主要项。
dgradfloat0.5深度估计模型中梯度损失的权重，用于惩罚深度边缘误差并促使表面边界更加清晰。
dlamfloat1.0深度估计模型中 SILog 损失的方差关注因子。1.0 使损失完全具有尺度不变性，而 0.0 会将其简化为普通的对数均方根误差。
nbsint64用于归一化损失的名义批次大小。
overlap_maskboolTrue决定是否将对象掩码合并为单个掩码进行训练，或为每个对象分别保留掩码。发生重叠时，合并过程中较小的掩码会叠加在较大的掩码上方。
mask_ratioint4分割掩码的下采样比例，影响训练期间使用的掩码分辨率。
dropoutfloat0.0分类任务中的正则化丢弃率，通过在训练期间随机忽略单元来防止过拟合。
valboolTrue启用训练期间的验证，从而可以定期在独立数据集上评估模型性能。
nmsbool，可选None选择用于轮次验证、检查点选择和早停的推理头。None 或 True 使用带 NMS 的一对多（one-to-many）；False 在可用时使用无 NMS（NMS-free）的头。两个头都保留其训练损失。
plotsboolTrue生成并保存训练和验证指标图，以及预测示例，为模型性能和学习进展提供可视化洞察。
compilebool 或 strFalse使用 backend='inductor' 启用 PyTorch 2.x 的 torch.compile 图编译。接受 True → "default"、False → 禁用，或使用 "default"、"reduce-overhead"、"max-autotune-no-cudagraphs" 等字符串模式。不支持时会发出警告并回退到 eager 模式。
channels_lastboolNone在训练期间为卷积使用 channels_last (NHWC) 内存格式。None 会在配备 PyTorch 1.11 或更新版本的 CUDA 上自动启用它，但在测得运行较慢的 Windows 系统上除外。False 会禁用它，而 True 会显式请求它。PyTorch 1.10 及更旧版本、CPU 和 MPS 默认保持 NCHW 格式。
max_detint300训练验证期间每张图像的最大检测数。对于 detect、segment、pose 和 OBB，默认的 300 只有在训练集/验证集标注对象最大数量超过 300 时才会增加到该数量。其他值保持固定；超出限制会触发警告。
批次大小设置说明

batch 参数提供三种配置选项：

  • 固定批次大小：使用整数指定每个批次中的图像数量（例如 batch=16）。
  • 自动模式（60% GPU 内存）：使用 batch=-1 自动调整到约 60% 的 CUDA 内存利用率。
  • 带利用率比例的自动模式：设置一个比例（例如 batch=0.70），根据指定的 GPU 内存使用率进行调整。
  • 未找到合适配置：如果没有候选批次大小能够生成可用的分析结果，AutoBatch 会抛出明确的 RuntimeError，而不是静默回退到无关的默认值。

训练指南

预测设置#

YOLO 模型的预测设置包括会影响推理期间性能、速度和准确率的超参数与配置。关键设置包括置信度阈值、非极大值抑制 (NMS)阈值和类别数量。输入数据的大小与格式，以及掩码等附加功能，也会影响预测。调优这些设置对于获得最佳性能至关重要。

推理参数：

参数类型默认值描述
sourcestr 或 int 或 NoneNone指定推理的数据源。可以是图像路径、视频文件、目录、URL 或实时流的设备 ID。如果省略，系统会记录警告，并将模型回退到内置演示资源（ultralytics/assets，或 OBB 的演示 URL）。支持多种格式和数据源，可灵活应用于不同类型的输入。
conffloat0.25设置检测的最低置信度阈值。置信度低于此阈值的检测对象将被忽略。调整此值有助于减少误报。
ioufloat0.7交并比 (IoU) 阈值，用于非极大值抑制 (NMS)。较低的值会通过消除重叠框来减少检测结果，有助于减少重复检测。
imgszint 或 tuple640Letterbox 目标尺寸。整数值表示正方形 N×N；元组表示 (height, width)。使用 rect=True 时，由于最小矩形填充，实际张量可能小于此目标尺寸。使用 rect=False 可指定固定尺寸。参见固定形状与最小矩形。
rectboolTrue如果为 True，则在可能时使用最小矩形填充（相同形状的批次和受支持的后端）。如果为 False，则始终填充到完整的 imgsz。参见固定形状与最小矩形。
quantizeint 或 strNone推理精度：16/"fp16" 与 32/"fp32"/未设置为 PyTorch 和 TorchScript 模型选择 FP16 或 FP32 计算；其他格式则在其构件与运行时所选的精度下进行计算。在 16 下，OpenVINO 仍在客户端将输入进行 FP16 舍入并将其展宽回 FP32，但这不会改变运行时实际的计算精度。INT8/PTQ 量化在导出期间进行配置，然后通过加载导出的模型来使用。该参数替代了已弃用的 half 标志。
devicestrNone指定推理设备（例如 cpu、cuda:0、0、npu 或 npu:0）。允许你在 CPU、特定 GPU、华为 Ascend NPU 或其他计算设备之间进行选择，以执行模型推理。
dnnboolFalse如果为 True，则在 ONNX 模型推理中使用 OpenCV DNN 模块，而不是 ONNX Runtime。
datastrNone数据集 YAML 的路径（例如 coco8.yaml），仅读取其中的 names，且仅当加载的模型不包含自身的类别名称时使用：例如第三方导出模型，或与其附带元数据分离的 Ultralytics 导出模型。否则，此类模型会报告 class0、class1 等。
batchint1指定推理的批次大小（仅当源是目录、视频文件或 .txt 文件时有效）。较大的批次大小可以提供更高的吞吐量，从而缩短推理所需的总时间。
max_detint300每张图像允许的最大检测数量。限制模型在单次推理中可以检测的对象总数，防止密集场景产生过多输出。
vid_strideint1视频输入的帧步长。允许跳过视频帧以加快处理速度，但会降低时间分辨率。值为 1 时处理每一帧，值更高时跳过部分帧。
stream_bufferboolFalse决定是否为视频流排队接收到的帧。如果为 False，则会丢弃旧帧以容纳新帧（针对实时应用进行了优化）。如果为 True，则会将新帧加入缓冲区，确保不跳过任何帧，但当推理 FPS 低于流 FPS 时会产生延迟。
visualizeboolFalse在每个预测结果旁保存类别激活热力图，显示哪些像素提高了预测类别的分数。遵循 conf 和 classes，因此 classes=[0] 仅映射该类别。仅适用于 Ultralytics PyTorch 模型。
augmentboolFalse为预测启用测试时增强 (TTA)，可能提升检测鲁棒性，但会降低推理速度。仅适用于 Ultralytics PyTorch 模型。
agnostic_nmsboolFalse启用类无关的 NMS，压制不同类别中得分较低的重叠框，而不仅仅是同一类别内。在类别重叠常见的多类检测场景中很有用。使用无 NMS 推理（在 YOLO26 或 YOLOv10 上为 nms=False）时，这仅防止同一检测结果出现多个类别标签（IoU=1.0 重复），而不会在不同框之间执行基于 IoU 阈值的压制。
classeslist[int]None将预测结果过滤为一组类别 ID。仅返回属于指定类别的检测结果。适用于在多类别检测任务中聚焦相关对象。
retina_masksboolFalse返回高分辨率分割掩码。启用后，返回的掩码（masks.data）将匹配原始图像尺寸。禁用后，掩码将使用推理期间的图像尺寸。
embedlist[int]None指定用于提取特征向量或嵌入的层。使用 model.embed(source) 获取倒数第二层嵌入，或使用 model.predict(source, embed=[layer]) 选择特定层。适用于聚类或相似性搜索等下游任务。仅适用于 Ultralytics PyTorch 模型。
projectstrNone项目目录的名称；启用 save 后，预测输出将保存到该目录。
namestrNone预测运行的名称。用于在项目文件夹中创建子目录；启用 save 后，预测输出将保存到该子目录。
streamboolFalse通过返回 Results 对象生成器，而不是一次性将所有帧加载到内存中，为长视频或大量图像启用节省内存的处理方式。
verboseboolTrue控制是否在终端中显示详细的推理日志，为预测过程提供实时反馈。
compilebool 或 strFalse使用 backend='inductor' 启用 PyTorch 2.x 的 torch.compile 图编译。接受 True → "default"、False → 禁用，或使用 "default"、"reduce-overhead"、"max-autotune-no-cudagraphs" 等字符串模式。不支持时会发出警告并回退到 eager 模式。
channels_lastboolNone对原生 PyTorch 推理使用 channels_last (NHWC) 内存格式。None 会在启用 oneDNN 的 Linux 和 Windows x86 CPU 上、PyTorch 1.13 或更高版本中自动启用该格式，False 会禁用该格式，True 会在受支持的 x86 CPU 或 CUDA 设备上请求该格式。ARM64、MPS、较旧的 PyTorch 版本、不支持 oneDNN 的 CPU，以及 TensorRT 和 ONNX 等导出格式均保持不变。
nmsbool，可选None默认运行带 NMS 的一对多推理（None 或 True）。设置 False 以在可用时使用无 NMS 的一对一（one-to-one）头。详见端到端检测指南。

可视化参数：

参数类型默认值描述
showboolFalse如果为 True，则会在窗口中显示带标注的图像或视频。适用于开发或测试期间获取即时视觉反馈。
saveboolFalse or True启用后将带注释的图像或视频保存到文件。适用于文档记录、进一步分析或分享结果。使用 CLI 时默认为 True，使用 Python 时默认为 False。
save_framesboolFalse处理视频时，将单独的帧保存为图像。适用于提取特定帧或进行详细的逐帧分析。
save_txtboolFalse将检测结果按照 [class] [x_center] [y_center] [width] [height] [confidence] 格式保存到文本文件中。适用于与其他分析工具集成。
save_confboolFalse在保存的文本文件中包含置信度分数。增加可用于后处理和分析的详细信息。
save_cropboolFalse保存检测对象的裁剪图像。适用于数据集增强、分析，或为特定对象创建专用数据集。
show_labelsboolTrue在可视化输出中显示每个检测结果的标签，帮助你立即了解检测到的对象。
show_confboolTrue在每个检测结果旁显示其置信度分数，让你了解模型对每个检测结果的确定程度。
show_boxesboolTrue在检测到的对象周围绘制边界框。对于在图像或视频帧中直观识别和定位对象至关重要。
line_widthint or NoneNone指定边界框的线宽。如果为 None，则会根据图像尺寸自动调整线宽。可自定义视觉效果以提高清晰度。

预测指南

验证设置#

YOLO 模型的验证设置包括用于在验证数据集上评估性能的超参数和配置。这些设置会影响性能、速度和准确率。常见设置包括批次大小、验证频率和性能指标。验证数据集的大小与组成，以及具体任务，也会影响验证过程。

参数类型默认值描述
datastrNone指定数据集 YAML 的路径（例如 coco8.yaml），其中应包含验证数据的路径。分类任务则使用数据集目录或内置数据集名称（例如 imagenet10）。
imgszint640定义输入图像的尺寸。处理前会将所有图像调整为此尺寸。较大的尺寸可能提高小目标的准确率，但会增加计算时间。
batchint16设置每个批次中的图像数量。较高的值可以更高效地利用 GPU 内存，但需要更多 VRAM。请根据可用硬件资源进行调整。
save_jsonboolFalse若使用 True，则会将结果保存至 JSON 文件中，以便进行进一步分析、与其它工具集成或提交至 COCO 等评估服务器。在检测数据集上，它还会使用 faster-coco-eval 对预测结果进行评估，并报告小、中、大目标 mAP，在训练过程中会将其作为 metrics/mAP_small(B)、metrics/mAP_medium(B) 和 metrics/mAP_large(B) 记录在 results.csv 中。
conffloat0.001设置检测的最低置信度阈值。较低的值会提高召回率，但可能引入更多误检。精确率-召回率曲线默认为 0.001；检测混淆矩阵使用显式的 conf 值，未设置时则使用 0.25。汇总精确率和召回率使用最大 F1 值对应的置信度，因此可能与根据 confusion_matrix.png 得出的值不同。OBB 验证默认为 0.01，以减少内存使用。
ioufloat0.7设置交并比（IoU）和非极大值抑制（NMS）的阈值。用于控制重复检测的消除。
max_detint300限制每张图像的最大检测数。对于 detect、segment、pose 和 OBB，如果保持默认的 300，当某张图像超过该值时，它会提升至验证集中标注对象最大数量，并伴有警告；任何其他值都会保留，同时发出当图像超过该值时召回率可能会受限的警告。
quantizeint 或 strNone验证精度：16/"fp16" 与 32/"fp32"/未设置为 PyTorch 和 TorchScript 模型选择 FP16 或 FP32 计算；其他格式则在其构件与运行时所选的精度下进行计算。在 16 下，OpenVINO 仍在客户端将输入进行 FP16 舍入并将其展宽回 FP32，但这不会改变运行时实际的计算精度。INT8/PTQ 量化在导出期间进行配置，然后通过验证导出的模型来使用。该参数替代了已弃用的 half 标志。
devicestrNone指定验证所使用的设备（cpu、cuda:0、npu、npu:0 等）。当设置为 None 时，会自动选择可用的最佳设备。多个 CUDA 设备可以使用逗号分隔指定。
dnnboolFalse如果为 True，则使用 OpenCV DNN 模块执行 ONNX 模型推理，为 PyTorch 推理方法提供替代方案。
plotsboolTrue设置为 True 时，会生成并保存预测结果与真实标注、混淆矩阵以及 PR 曲线的图表，以直观评估模型性能。
classeslist[int]None指定要评估的类别 ID 列表。在评估期间过滤并仅关注特定类别时很有用。
rectboolTrue如果为 True，则在批处理中使用矩形推理，减少填充，并通过按照图像原始宽高比处理图像来提高速度和效率。对于 depth 验证会忽略此设置，因为该验证会将每张图像拉伸为固定的 imgsz 正方形，而不是进行填充。
splitstr'val'确定用于验证的数据集划分（val、test 或 train）。你可以灵活选择用于性能评估的数据部分。
fractionfloat、int 或 list1.0验证集的一个子集。使用 [train, val, test] 列表时，匹配 split 的条目生效（1 = 完整切片，大于 1 的整数 = 图像数量；省略的条目表示完整）。标量仅在配合 split=train 时生效；此时 val 和 test 使用完整切片。
projectstrNone保存验证输出的项目目录名称。帮助整理不同实验或模型的结果。
namestrNone验证运行的名称。用于在项目文件夹中创建子目录，保存验证日志和输出。
verboseboolTrue如果为 True，则在验证过程中显示详细信息，包括每类指标、批次进度和其他调试信息。
save_txtboolFalse如果为 True，则将检测结果保存到文本文件中，每张图像对应一个文件，便于进一步分析、自定义后处理或与其他系统集成。
save_confboolFalse如果为 True，且已启用 save_txt，则在保存的文本文件中包含置信度值，为分析和筛选提供更详细的输出。
workersint8数据加载的工作线程数。较高的值可以加快数据预处理，但可能增加 CPU 使用率。设置为 0 时使用主线程，在某些环境中可能更加稳定。
augmentboolFalse在验证期间启用测试时增强（TTA），通过对输入的变换版本执行推理来提升检测准确率，但会降低推理速度。仅适用于 Ultralytics PyTorch 模型。
agnostic_nmsboolFalse启用类无关的非极大值抑制，压制得分较低的重叠框，无论其预测类别如何。适用于以实例为核心的应用。使用无 NMS 推理（在 YOLO26 或 YOLOv10 上为 nms=False）时，这仅防止同一检测结果出现多个类别标签（IoU=1.0 重复），而不会在不同框之间执行基于 IoU 阈值的压制。
single_clsboolFalse在验证期间将所有类别视为单一类别。适用于评估模型在二分类检测任务中的性能，或类别区分不重要的场景。
visualizeboolFalse可视化每张图像的真实标注、真正例、假正例和假负例。适用于调试和模型解读。
show_labelsboolTrue当 visualize=True 时，在验证可视化中显示类别标签。设置为 False 可更清晰地查看匹配结果和错误。
show_confboolTrue当 visualize=True 时，在验证可视化中显示置信度分数。设置为 False 可更清晰地查看匹配结果和错误。
compilebool 或 strFalse使用 backend='inductor' 启用 PyTorch 2.x 的 torch.compile 图编译。接受 True → "default"、False → 禁用，或使用 "default"、"reduce-overhead"、"max-autotune-no-cudagraphs" 等字符串模式。不支持时会发出警告并回退到 eager 模式。
channels_lastboolNone原生 PyTorch 验证使用 channels_last（NHWC）内存格式。在启用 oneDNN 的 Linux 和 Windows x86 CPU 上，且 PyTorch 版本为 1.13 或更高版本时，None 会自动启用该格式；False 会禁用该格式；True 会在受支持的 x86 CPU 或 CUDA 设备上请求该格式。ARM64、MPS、较旧的 PyTorch 版本、不支持 oneDNN 的 CPU 以及导出格式均保持不变；训练期间的验证会保留训练模型布局。
nmsbool，可选None默认运行带 NMS 的一对多推理（None 或 True）。设置 False 以在可用时使用无 NMS 的一对一（one-to-one）头。详见端到端检测指南。

仔细调优和实验对于确保最佳性能，以及检测和防止过拟合，至关重要。

验证指南

导出设置#

YOLO 模型的导出设置包括用于保存或导出模型、以便在不同环境中使用的配置。这些设置会影响性能、大小和兼容性。关键设置包括导出文件格式（例如 ONNX、TensorFlow SavedModel）、目标设备（例如 CPU、GPU）以及掩码等功能。模型任务和目标环境的限制也会影响导出过程。

参数类型默认值描述
formatstr'torchscript'导出模型的目标格式，例如 'onnx'、'torchscript'、'engine' (TensorRT) 或其他格式。每种格式都支持与不同部署环境的兼容性。
namestrNone需要硬件目标的格式所使用的硬件目标名称：Hailo 架构（'hailo8'、'hailo8l'、'hailo10h'、'hailo15h'、'hailo15l'；默认为 'hailo8l'）、Rockchip RKNN 芯片（默认为 'rk3588'）、华为 Ascend SoC（CANN --soc_version；默认为 'Ascend310B4'）或 Qualcomm QNN HTP 目标（默认为 '73'）。不同于其他模式使用的 project/name 运行命名组合。
imgszint 或 tuple640模型输入所需的图像尺寸。可以使用整数表示正方形图像（例如，640 表示 640×640），也可以使用元组 (height, width) 指定具体尺寸。未传入该参数时，导出会复用加载的检查点中记录的训练尺寸：官方 YOLO26 检查点会为检测深度记录 768，为分类记录 224，为 OBB 记录 1024，为其他任务记录 640；而微调模型会记录其训练时使用的 imgsz。根据 YAML 构建的模型没有记录的训练尺寸，会使用 640。
kerasboolFalse启用导出为 Keras 格式，以生成 TensorFlow SavedModel，并兼容 TensorFlow serving 和 API。
optimizeboolFalse为 DEEPX 启用更高级别的编译器优化，降低推理延迟，但会增加编译时间。
quantizeint 或 strNone量化精度：16（FP16，可减小模型大小并在支持的硬件上加快推理速度）或 8（INT8/PTQ，以极小的准确率损失进一步压缩模型，主要用于边缘设备；需要校准 data/fraction）；32/未设置时为 FP32。使用 quantize=8 训练的检查点始终导出 INT8：onnx 和 engine 无需校准即可从其携带的范围内导出，其他格式或精度将被拒绝。支持混合权重/激活精度的导出格式也接受 'w8a8'/'w16a16'/'w8a16'/'w8a32' 表示法。替代已废弃的 half/int8 标志（half=True → 16，int8=True → 8，目前仍可接受但会发出废弃警告）。仅允许使用目标格式支持的精度（见下文）。
dynamicboolFalse允许 TorchScript、ONNX、OpenVINO、TensorRT 和 CoreML 导出使用动态输入尺寸，从而更灵活地处理不同的图像尺寸。
simplifyboolTrue对于会构建中间 ONNX 图的导出格式，使用 onnxslim 简化该图（参见导出格式），可能提升性能以及与推理引擎的兼容性。
opsetintNone指定会构建 ONNX 图的导出格式所使用的 ONNX opset 版本（参见导出格式），以兼容不同的 ONNX 解析器和运行时。未设置时，使用最新的受支持版本。
workspacefloat 或 NoneNone为 TensorRT 优化设置最大工作空间大小（单位为 GiB），在内存使用量与性能之间进行平衡。使用 None 可由 TensorRT 自动分配，最大不超过设备上限。
nmsbool，可选NoneNone 导出生的一对多预测以供外部 NMS 使用；True 在支持的地方嵌入 NMS；False 在可用时选择无 NMS 的头。CoreML 嵌入式 NMS 支持具有静态形状的检测、分割和姿态估计。详见端到端检测指南。
conffloatNone在生成导出时 NMS 的所有场景中使用的置信度阈值：nms=True 导出；Hailo 的非端到端检测导出；以及 IMX 的检测、姿态和分割导出，它们会在内部强制使用 nms=True。未设置时默认为 0.25。
ioufloat0.7在生成导出时 NMS 的所有场景中使用的 IoU 阈值：nms=True 导出；Hailo 的非端到端检测导出；以及 IMX 的检测、姿态和分割导出，它们会在内部强制使用 nms=True。
max_detint300导出模型输出中保留的最大检测数量。适用于所有格式的 nms=True 导出（CoreML 检测除外，其原生 NMS 流水线没有检测上限），以及无 NMS 的端到端检测导出（YOLO26、YOLOv10，上限为可用锚点数量）和 IMX 的检测、姿态估计与分割导出。
agnostic_nmsboolFalse只要通过标准 nms=True 流程生成导出时 NMS，就启用类别无关的 NMS，包括 CoreML 自身的 NMS 阶段，抑制不同类别之间分数较低的重叠框，而不仅仅是同一类别内的重叠框。Hailo 或 IMX 自身生成的 NMS 配置不支持此选项，因此无论此标志如何设置，它们始终使用类别相关的 NMS。该选项也会内置到无 NMS 的端到端导出中（YOLO26、YOLOv10），此时仅防止同一检测结果出现在多个类别标签下（IoU=1.0 的重复项），不会对不同框执行基于 IoU 阈值的抑制。
batchint1指定导出模型的批次推理大小，或导出模型在 predict 模式下可并发处理的最大图像数量。对于 Edge TPU 导出，此值会自动设置为 1。
devicestrNone指定导出设备：GPU（device=0）、CPU（device=cpu）、Apple silicon 上的 MPS（device=mps）、华为 Ascend NPU（device=npu 或 device=npu:0）或 NVIDIA Jetson 上的 DLA（device=dla:0 或 device=dla:1）。TensorRT 导出会自动使用 GPU，但 TensorRT 11.0 不支持 DLA。
verboseboolFalse在 format='engine' 导出期间，将 TensorRT 构建器日志级别提升为 VERBOSE。其他导出格式会忽略该参数。
datastrNone数据集 YAML 的路径，对于 INT8 量化校准至关重要；分类任务则改为使用数据集目录或内置数据集名称。如果在启用 INT8 的情况下未指定，Ultralytics 会在需要时选择特定于任务的校准数据集，或者回退到模型任务的默认数据集。使用 quantize=8 训练的检查点带有自己的 INT8 范围，不需要校准数据。
splitstr'val'数据集划分（'train'、'val' 或 'test'），用于从 data 构建 INT8 量化校准数据加载器。
fractionfloat、int 或 list1.0用于 INT8 校准的数据集子集：可以是比例、图像数量或 [train, val, test] 值。1 表示完整划分；大于 1 的整数表示图像数量；只有可选的测试项接受 0/0.0 来表示无数据。包含两个元素的列表会保留 test 的完整内容。

周密的配置可确保导出模型针对其使用场景进行了优化，并能在目标环境中有效运行。

导出指南

Solutions 设置#

Ultralytics Solutions 配置设置提供了灵活性，可针对对象计数、热力图创建、锻炼跟踪、数据分析、区域跟踪、队列管理和基于区域的计数等任务自定义模型。这些选项可以轻松调整模型，以获得针对特定需求的准确且实用的结果。

参数类型默认值描述
modelstrNoneUltralytics YOLO 模型文件的路径。
regionlist 或 dictNone定义感兴趣区域的点，可以是 (x, y) 元组列表，也可以是将区域名称映射到多区域点列表的字典（仅限 RegionCounter）。当 None 时，需要区域的解决方案会回退到预定义的默认区域。
show_inboolTrue控制是否在视频流中显示进入计数的标志。
show_outboolTrue控制是否在视频流中显示离开计数的标志。
analytics_typestr'line'图表类型，即 line、bar、area 或 pie。
colormapintcv2.COLORMAP_DEEPGREEN用于热力图的颜色映射。
line_widthint2解决方案绘制的框、关键点和计数的线条粗细。
verboseboolTrue启用解决方案逐帧记录输入形状、类别计数和处理速度的日志。跟踪调用本身始终保持静默。
json_filestrNone包含所有停车坐标数据的 JSON 文件路径。
up_anglefloat145.0“向上”姿态的角度阈值。
kptslist[int]'[6, 8, 10]'用于监控训练的三个关键点索引列表。这些关键点对应肩部、肘部和手腕等身体关节或部位，适用于俯卧撑、引体向上、深蹲和腹部训练等练习。
down_angleint90“向下”姿态的角度阈值。
blur_ratiofloat0.5调整模糊强度百分比，取值范围为 0.1 - 1.0。
crop_dirstr'cropped-detections'用于存储裁剪检测结果的目录名称。
recordsint5触发安防报警系统发送电子邮件所需的检测总数。
vision_pointtuple[int, int](20, 20)VisionEye 解决方案跟踪对象并绘制路径的视觉点。
sourcestrNone输入源（视频、RTSP 等）的路径。仅可与解决方案命令行界面（CLI）配合使用。
figsizetuple[float, float](12.8, 7.2)分析图表（如热力图或图形）的图像尺寸。
fpsfloat30.0用于速度计算的每秒帧数。
max_histint5速度/方向计算中每个对象要跟踪的最大历史点数。
meter_per_pixelfloat0.05用于将像素距离转换为现实世界单位的缩放因子。
max_speedint120视觉叠加层中的最大速度限制（用于警报）。
datastr'images'用于相似性搜索的图像目录路径。
imgszint640模型推理的输入图像尺寸。

解决方案指南

增强设置#

数据增强技术对于提升 YOLO 模型的鲁棒性和性能至关重要。它们通过向训练数据引入变化，帮助模型更好地泛化到未见数据。下表概述了每个增强参数的用途和效果：

参数类型默认值支持的任务范围描述
hsv_hfloat0.015detect、segment、semantic、depth、classify、pose、obb0.0 - 1.0按色轮的一定比例调整图像色调，引入颜色变化。帮助模型适应不同的光照条件。对于 classify，仅当 auto_augment=None 时应用。
hsv_sfloat0.7detect、segment、semantic、depth、classify、pose、obb0.0 - 1.0按一定比例调整图像饱和度，影响颜色的强度。适用于模拟不同的环境条件。对于 classify，仅当 auto_augment=None 时应用。
hsv_vfloat0.4detect、segment、semantic、depth、classify、pose、obb0.0 - 1.0按一定比例修改图像的明度（亮度），帮助模型在各种光照条件下保持良好表现。对于 classify，仅当 auto_augment=None 时应用。
degreesfloat0detect、segment、semantic、depth、pose、obb0.0 - 180在指定的角度范围内随机旋转图像，提升模型识别不同方向对象的能力。
translatefloat0.1detect、segment、semantic、depth、pose、obb0.0 - 1.0按图像尺寸的一定比例水平和垂直平移图像，帮助模型学习检测部分可见的对象。
scalefloat | tuple0.5detect、segment、semantic、depth、classify、pose、obb0 - 1，或显式的 (min, max) 元组（不适用于 classify）按照增益因子缩放图像，模拟距离摄像头远近不同的对象。
shearfloat0detect、segment、semantic、depth、pose、obb-180 - +180按指定角度剪切图像，模拟从不同角度观察对象的效果。
perspectivefloat0detect、segment、semantic、depth、pose、obb0.0 - 0.001对图像应用随机透视变换，增强模型理解三维空间中对象的能力。
flipudfloat0detect、segment、semantic、depth、classify、pose、obb0.0 - 1.0以指定概率将图像上下翻转，在不影响对象特征的情况下增加数据变化。
fliplrfloat0.5detect、segment、semantic、depth、classify、pose、obb0.0 - 1.0以指定概率将图像左右翻转，适用于学习对称对象并增加数据集多样性。
bgrfloat0detect、segment、semantic、depth、pose、obb0.0 - 1.0以指定概率将图像通道从 RGB 翻转为 BGR，适用于增强模型对错误通道顺序的鲁棒性。
mosaicfloat1detect、segment、semantic、pose、obb0.0 - 1.0将四张训练图像合并为一张，模拟不同的场景构成和对象交互。对复杂场景理解非常有效。
mixupfloat0detect、segment、semantic、pose、obb0.0 - 1.0混合两张图像及其标签，创建合成图像。通过引入标签噪声和视觉变化，增强模型的泛化能力。
cutmixfloat0detect、segment、pose、obb0.0 - 1.0组合两张图像的部分区域，在保留清晰区域的同时创建局部混合效果。通过创建遮挡场景增强模型鲁棒性。
copy_pastefloat0segment、obb0.0 - 1.0要粘贴的符合条件对象所占的比例；flip 会在图像内镜像这些对象，而 mixup 还会将该值用作跨图像应用概率。
copy_paste_modestrflipsegment、obb-指定要使用的 copy-paste 策略。选项包括 'flip' 和 'mixup'。
auto_augmentstrrandaugmentclassify-应用预定义的增强策略（'randaugment'、'autoaugment' 或 'augmix'），通过增加视觉多样性来提升模型性能。
erasingfloat0.4classify0.0 - 1.0在训练期间随机擦除图像区域，促使模型关注不太明显的特征。
augmentationslistNonedetect、segment、semantic、depth、pose、obb-用于高级数据增强的自定义 Albumentations 变换（仅限 Python API）。接受变换对象列表，以满足特殊的增强需求。

根据数据集和任务需求调整这些设置。尝试不同的值有助于找到最佳增强策略，从而获得最佳模型性能。

数据增强指南

日志记录、检查点和绘图设置#

在训练 YOLO 模型时，日志记录、检查点、绘图和文件管理非常重要：

  • 日志记录：使用 TensorBoard 等库，或写入文件，以跟踪模型进度并诊断问题。
  • 检查点：定期保存模型，以便恢复训练或使用不同配置进行实验。
  • 绘图：使用 Matplotlib 或 TensorBoard 等库将性能和训练进度可视化。
  • 文件管理：整理训练期间生成的文件，例如检查点、日志文件和绘图，以便访问和分析。

有效管理这些方面有助于跟踪进度，并使调试和优化更加容易。

参数默认值描述
projectNone指定保存训练运行的根目录。如果未指定，运行结果将保存到 runs/<task> 下。每次运行都会保存到单独的子目录中。
nameNone定义实验名称。如果未指定，YOLO 会使用模式名称，并为每次运行递增编号（例如 train、train-2），以避免覆盖已有内容。
exist_okFalse决定是否覆盖已有的实验目录。True 允许覆盖；False 则禁止覆盖。
plotsTrue控制训练和验证图表的生成与保存。设置为 True 可创建损失曲线、精确率-召回率曲线以及样本预测结果，以便直观跟踪性能。
saveTrue启用训练检查点和最终模型权重的保存。设置为 True 可定期保存模型状态，从而支持恢复训练或部署模型。

自定义配置文件#

加载已保存的 YAML 文件，无需以内联方式传递参数即可复用完整的参数集。cfg 参数会覆盖 default.yaml 中的值，而同时传入的其他参数仍具有更高优先级。

参数默认值描述
cfgNoneYAML 文件的路径，其值会替换 default.yaml 条目。有关 CLI 示例，请参阅覆盖默认配置文件。

常见问题#

  • 通过调整批量大小、学习率、动量和权重衰减等超参数来提升性能。调整数据增强设置，选择合适的优化器，并使用提前停止或混合精度等技术。详情请参阅训练指南。

  • 影响精度的关键超参数包括：

    • 批量大小 (batch)：较大的批量大小可以稳定训练，但需要更多内存。
    • 学习率 (lr0)：较小的学习率便于进行精细调整，但收敛速度更慢。
    • 动量 (momentum)：加速梯度向量并抑制振荡。
    • 图像尺寸 (imgsz)：较大的尺寸可以提升精度，但会增加计算负载。

    根据你的数据集和硬件进行调整。请在训练设置中了解更多信息。

  • 学习率 (lr0) 至关重要；对于 SGD，可以从 0.01 开始，对于Adam 优化器，可以从 0.001 开始。监控指标并根据需要进行调整。使用余弦学习率调度器 (cos_lr) 或预热 (warmup_epochs、warmup_momentum)。训练指南中提供了详细信息。

  • 默认设置包括：

    • 置信度阈值 (conf=0.25)：检测结果所需的最低置信度。
    • IoU 阈值 (iou=0.7)：用于非极大值抑制 (NMS)。
    • 图像尺寸 (imgsz=640)：调整输入图像的大小。
    • 设备 (device=None)：选择 CPU、GPU、Apple MPS 或华为 Ascend NPU (npu)。

    如需完整概览，请参阅预测设置和预测指南。

  • 混合精度训练 (amp=True) 使用 FP16 和 FP32 来减少内存占用并加快训练速度。这对现代 GPU 很有益，可以在不显著损失精度的情况下使用更大的模型并加快计算。请在训练指南中了解更多信息。

贡献者
GLglenn-jocher29RIRizwanMunawar5RAraimbekovm3LALaughing-q3MAMatthewNoyce3AMambitious-octopus2FCfcakyon2JEJESUSROYETH1BOBovey08091MImiles-deans-ultralytics1GIGiantAxeWhy1PDpderrenger1JKjk4e1PLplashchynski1BUBurhan-Q1AYAyushExel1TEtensorturtle1

评论