Ultralytics YOLO27：
Get Started

配置#

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



观看： 精通 Ultralytics YOLO：配置

Ultralytics 命令采用以下语法：

示例
yolo TASK MODE ARGS

其中：

默认的 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 模型以供部署。
  • 跟踪：使用 YOLO 模型实时跟踪对象。
  • 基准测试：对 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 时会禁用此功能。适合在长时间训练过程中保存中间模型。
cachebool 或 strFalse启用数据集图像缓存：缓存到内存（True/ram）、磁盘（disk），或禁用缓存（False）。通过减少磁盘 I/O 提高训练速度，但会增加内存使用量。
deviceint 或 str 或 listNone指定训练使用的计算设备：单个 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]）。
workersint8用于数据加载的工作线程数（多 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的整数表示图像数量；只有可选的 test 项接受0/0.0来表示无测试集。包含两项的列表会保留完整测试集。
profileboolFalse启用训练期间对 ONNX 和 TensorRT 速度的性能分析，适用于优化模型部署。
freezeint 或 listNone冻结模型的前 N 层，或按索引或模块名称冻结指定层（23.cv2，不带前导model.），以减少可训练参数数量。适用于微调或迁移学习。
lr0float0.01初始学习率（即SGD=1E-2、Adam=1E-3）。默认optimizer='auto'下会忽略此设置；要使用此设置，请明确指定优化器。
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会将其简化为普通的对数 RMSE。
nbsint64用于损失归一化的标称批次大小。
overlap_maskboolTrue确定训练时是否将所有对象掩码合并为单个掩码，或为每个对象分别保留掩码。合并时如果发生重叠，较小的掩码会叠加在较大的掩码之上。
mask_ratioint4分割掩码的下采样比例，会影响训练时所用掩码的分辨率，但不会改变预测掩码的分辨率。
dropoutfloat0.0分类任务中的正则化丢弃率，通过在训练期间随机丢弃单元来防止过拟合。
valboolTrue启用训练期间的验证，以便定期在单独的数据集上评估模型性能。
nmsbool，可选None选择用于每轮验证、检查点选择和提前停止的推理头。None 或 True使用带 NMS 的一对多头；False在可用时使用无 NMS 头。两种头都会保留各自的训练损失。
plotsboolTrue生成并保存训练和验证指标图，以及预测示例，直观呈现模型性能和学习进度。
compilebool 或 strFalse使用backend='inductor'启用 PyTorch 2.x torch.compile图编译。接受True → "default"、False → 禁用，或"default"、"reduce-overhead"、"max-autotune-no-cudagraphs"等字符串模式。如果不受支持，则会发出警告并回退到即时执行模式。
channels_lastboolNone训练卷积时使用 channels_last（NHWC）内存格式。None会在 PyTorch 1.11 或更高版本的 CUDA 上自动启用此格式，但 Windows 除外，因为实测速度更慢。False会禁用此格式，True则会显式启用此格式。CPU 或 MPS 上的训练始终使用 NCHW（True会被忽略，并发出警告）。
max_detint300训练验证期间每张图像的最大检测数。对于检测、分割、姿态和 OBB，仅当训练/验证集中带标签对象的最大数量超过默认值 300 时，最大检测数才会增加到该数量。其他值保持不变；超出限制时会触发警告。
批次大小设置说明

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

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

训练指南

预测设置#

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

推理参数：

参数类型默认值说明
sourcestr 或 int 或 NoneNone指定推理的数据源。可以是图像路径、视频文件、目录、URL，或实时画面的设备 ID。如果未指定，系统会记录警告，并使用内置演示资源（ultralytics/assets；对于 OBB，则使用演示 URL）作为模型输入。此功能支持多种格式和来源，可灵活应用于不同类型的输入。
conffloat0.25设置检测的最低置信度阈值。置信度低于此阈值的检测结果会被忽略。调整此值有助于减少误报。
ioufloat0.7用于非极大值抑制（NMS）的交并比（IoU）阈值。较低的值会通过消除重叠框来减少检测结果，有助于减少重复检测。
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、华为昇腾 NPU 或其他计算设备来运行模型。
dnnboolFalse如果 True，则使用 OpenCV DNN 模块，而不是 ONNX Runtime 执行 ONNX 模型推理。
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"等字符串模式。如果不受支持，则会发出警告并回退到即时执行模式。
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，以及 TensorRT 和 ONNX 等导出格式均不受影响。
nmsbool，可选None默认使用 NMS 执行一对多推理（None 或 True）。设置 False 可在可用时使用无 NMS 的一对一检测头。详情请参阅端到端检测指南。

可视化参数：

参数类型默认值说明
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设置检测结果的最低置信度阈值。较低的值会提高召回率，但可能引入更多假阳性。精确率-召回率曲线、mAP 和检测混淆矩阵均使用此值；较高的 conf（例如 0.25）会使矩阵更接近预测输出，但可能降低 mAP。汇总精确率和召回率使用最大 F1 值对应的置信度，因此可能与根据 confusion_matrix.png 得出的值不同。OBB 验证的默认值为 0.01，以降低内存使用量。
ioufloat0.7设置用于非极大值抑制的交并比阈值。控制重复检测的消除。
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"等字符串模式。如果不受支持，则会发出警告并回退到即时执行模式。
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 的一对一检测头。详情请参阅端到端检测指南。

谨慎调整和反复试验对于确保获得最佳性能以及检测和防止过拟合至关重要。

验证指南

导出设置#

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

参数类型默认值说明
formatstr'torchscript'导出模型的目标格式，例如 'onnx'、'torchscript'、'engine'（TensorRT）或其他格式。每种格式都支持不同的部署环境。
namestrNone需要指定目标硬件的格式所用的硬件目标名称：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 运行命名组合不同。
imgszint 或 tuple640模型输入的目标图像尺寸。可以是表示正方形图像的整数（例如，640 表示 640×640），也可以是表示特定尺寸的元组 (height, width)。如果未传入，导出时会沿用加载的检查点中记录的训练尺寸：官方 YOLO26 检查点记录的尺寸分别为：检测任务 768，分类任务 224，OBB 任务 1024，其他任务 640；微调模型则记录训练时使用的 imgsz。根据 YAML 构建的模型没有记录训练尺寸，因此使用 640。
optimizeboolFalse为 DEEPX 启用更高等级的编译器优化，以降低推理延迟，但会增加编译时间。
quantizeint 或 strNone量化精度：16（FP16，可减小模型大小，并可能加快受支持硬件上的推理速度）或 8（INT8/PTQ，可进一步压缩模型，且准确率损失极小，主要用于边缘设备；需要校准 data/fraction）；32/未设置表示 FP32。使用 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；仍可使用，但会显示弃用警告）。只能使用目标格式支持的精度（见下文）。
dynamicboolFalse允许 TorchScript、ONNX、OpenVINO、TensorRT、CoreML 和 MNN 导出采用动态输入尺寸，提高处理不同图像尺寸时的灵活性。
simplifyboolTrue对于会构建 ONNX 中间图的导出，使用 onnxslim 简化该图（参见导出格式），可能提高性能并改善与推理引擎的兼容性。
opsetintNone指定会构建 ONNX 图的导出所使用的 ONNX opset 版本（参见导出格式），以兼容不同的 ONNX 解析器和运行时。如果未设置，则使用最新的受支持版本。
workspacefloat 或 NoneNone设置 TensorRT 优化的最大工作区大小（单位为 GiB），以平衡内存使用量和性能。使用 None 可让 TensorRT 自动分配工作区，最大不超过设备上限。
nmsbool，可选NoneNone 导出原始一对多预测结果，以便外部执行 NMS；True 会在受支持时嵌入 NMS；False 会在可用时选择无 NMS 检测头。CoreML 嵌入式 NMS 支持静态形状的 detect、segment 和 pose。详情请参阅端到端检测指南。
conffloatNone用于所有导出时生成 NMS 的置信度阈值：nms=True 导出、Hailo 的非端到端 detect 导出，以及 IMX 的 detect、pose 和 segment 导出；后者会在内部强制使用 nms=True。未设置时默认为 0.25。
ioufloat0.7用于所有导出时生成 NMS 的 IoU 阈值：nms=True 导出、Hailo 的非端到端 detect 导出，以及 IMX 的 detect、pose 和 segment 导出；后者会在内部强制使用 nms=True。
max_detint300导出模型输出中保留的最大检测数量。适用于所有格式的 nms=True 导出，但 CoreML 检测除外，其原生 NMS 流程没有检测数量上限；也适用于无 NMS 的端到端检测导出（YOLO26、YOLOv10，上限限制为可用锚点数量）以及 IMX 的 detect、pose 和 segment 导出。
agnostic_nmsboolFalse在通过标准 nms=True 流程生成导出时的 NMS（包括 CoreML 自带的 NMS 阶段）中启用类别无关 NMS，抑制不同类别之间得分较低且重叠的框，而不只是同一类别内的框。Hailo 或 IMX 自行生成的 NMS 配置不支持此选项，因此不会采用该设置，仍会按类别进行处理。此选项也会应用于无 NMS 的端到端导出（YOLO26、YOLOv10），但仅用于防止同一检测结果带有多个类别标签（IoU=1.0 的重复项），不会根据 IoU 阈值抑制不同的框。
batchint1指定导出模型的批量推理大小，或导出模型在 predict 模式下并发处理的最大图像数量。导出参数中不包含 batch 的格式（Edge TPU、IMX500、DEEPX、Hailo、AMD Xilinx）会以批量大小 1 导出，并拒绝其他值。
devicestrNone指定导出设备：GPU（device=0）、CPU（device=cpu）、Apple silicon 上的 MPS（device=mps）、Huawei 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'用于从 data 构建 INT8 量化校准数据加载器的数据集划分（'train'、'val' 或 'test'）。
fractionfloat、int 或 list1.0用于 INT8 校准的数据集子集：比例、图像数量或 [train, val, test] 值。1 表示完整数据划分，大于 1 的整数表示图像数量；只有可选的 test 条目接受 0/0.0 表示不使用任何数据。两项列表会保留完整的 test。

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

导出指南

解决方案设置#

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_anglefloat90.0“向下”姿势的角度阈值。
blur_ratiofloat0.5调整模糊强度百分比，取值范围为 0.1 - 1.0。
crop_dirstr'cropped-detections'用于存储裁剪后检测结果的目录名称。
recordsint5触发安全警报系统发送邮件所需的检测总数。
vision_pointtuple[int, int](20, 20)视觉系统使用 VisionEye Solution 跟踪对象并绘制路径的位置。
sourcestrNone输入源的路径（视频、RTSP 等）。仅适用于 Solutions 命令行界面 (CLI)。
figsizetuple[float, float](12.8, 7.2)Analytics 图表的图幅尺寸（英寸）；(12.8, 7.2) 会渲染 1280×720 的帧。
fpsfloat30.0用于速度计算的每秒帧数。
max_histint5每个对象用于速度/方向计算的最大历史跟踪点数。
meter_per_pixelfloat0.05用于将像素距离转换为实际单位的缩放系数。
max_speedint120最高速度（km/h）；估算速度超过此值时将按此值封顶。
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对图像应用随机透视变换，增强模型理解 3D 空间中对象的能力。
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, semantic, pose, obb0.0 - 1.0合并两张图像的部分区域，形成局部混合，同时保留清晰的区域边界。通过构造遮挡场景增强模型鲁棒性。
copy_pastefloat0segment, semantic, obb0.0 - 1.0粘贴符合条件对象的比例；flip 会在图像内镜像这些对象，而 mixup 还会将此值用作跨图像应用概率。
copy_paste_modestrflipsegment, semantic, 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，并显式设置 optimizer，因为默认的 auto 会忽略 lr0。监控指标并根据需要进行调整。使用余弦学习率调度器（cos_lr）或预热（warmup_epochs、warmup_momentum）。详情请参阅训练指南。

  • 默认设置包括：

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

    完整概述请参阅预测设置和预测指南。

  • 混合精度训练（amp=True）通过使用 FP16 和 FP32 来降低内存占用并加快训练速度。混合精度对现代 GPU 很有益，可在不显著损失精度的情况下使用更大的模型并加快计算。请参阅训练指南了解更多信息。

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

评论