配置#

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

Watch: Mastering Ultralytics YOLO: Configuration

Ultralytics 命令使用以下语法：

示例

yolo TASK MODE ARGS

其中：

TASK（可选）是 (detect、segment、semantic、depth、classify、pose、obb) 之一
MODE（必需）是 (train、val、predict、export、track、benchmark) 之一
ARGS（可选）是诸如 imgsz=640 的 arg=value 键值对，用于覆盖默认设置。

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

任务#

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

检测 (Detect)：目标检测用于识别并定位图像或视频中的对象。
分割 (Segment)：实例分割将图像或视频划分为对应不同对象或类别的区域。
语义分割 (semantic)：语义分割为图像中的每个像素分配一个类别标签，以实现密集的场景理解。
深度 (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 入口函数。

参数	类型	默认值	描述
`model`	`str`	`None`	指定用于训练的模型文件。接受 `.pt` 预训练模型或 `.yaml` 配置文件之一的路径。对于定义模型结构或初始化权重至关重要。
`data`	`str`	`None`	数据集配置文件的路径（例如 `coco8.yaml`）。此文件包含特定于数据集的参数，包括训练和验证数据的路径、类名和类别数。
`epochs`	`int`	`100`	训练轮次的总数。每个轮次代表对整个数据集的完整遍历。调整此值会影响训练持续时间和模型性能。
`time`	`float`	`None`	以小时为单位的最大训练时间。如果设置，这会覆盖 `epochs` 参数，允许训练在指定持续时间后自动停止。对于时间受限的训练场景非常有用。
`patience`	`int`	`100`	在验证指标没有改善的情况下等待提前停止训练的轮数。通过在性能停滞时停止训练来帮助防止过拟合。
`batch`	`int` 或 `float`	`16`	批次大小，具有三种模式：设置为整数（例如 `batch=16`）、用于 60% GPU 内存利用率的自动模式（`batch=-1`），或带有指定利用率分数的自动模式（`batch=0.70`）。
`imgsz`	`int`	`640`	训练的目标图像大小。图像被调整大小为边长等于指定值的正方形（如果 `rect=False`），对于 YOLO 模型会保留宽高比，但对于 RT-DETR 则不然。会影响模型的准确率和计算复杂度。
`save`	`bool`	`True`	启用训练检查点和最终模型权重的保存。对于恢复训练或模型部署非常有用。
`save_period`	`int`	`-1`	保存模型检查点的频率，以 epoch 为单位。值为 -1 会禁用此功能。这对于在长时间训练期间保存中间模型非常有用。
`cache`	`bool`	`False`	启用在内存（`True`/`ram`）或磁盘（`disk`）中缓存数据集图像，或将其禁用（`False`）。通过减少磁盘 I/O 来提高训练速度，代价是增加内存使用量。
`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`），或者自动选择闲置 GPU（`device=-1`）或多个闲置 GPU（`device=[-1,-1]`）。
`workers`	`int`	`8`	用于数据加载的工作线程数（多 GPU 训练时每个 `RANK` 的线程数）。影响数据预处理和输入模型的速度，在多 GPU 设置中尤其有用。
`project`	`str`	`None`	保存训练输出的项目目录名称。允许对不同的实验进行有组织的存储。
`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`。影响收敛速度和稳定性。
`seed`	`int`	`0`	设置训练的随机种子，确保在相同配置下的运行结果具有可重复性。
`deterministic`	`bool`	`True`	强制使用确定性算法，确保可重复性，但由于对非确定性算法的限制，可能会影响性能和速度。
`verbose`	`bool`	`True`	在训练期间启用详细输出，在控制台中显示进度条、每个 epoch 的指标以及其他训练信息。
`single_cls`	`bool`	`False`	在训练期间将多类别数据集中的所有类别视为单个类别。适用于二分类任务或专注于对象是否存在而非分类的情况。
`classes`	`list[int]`	`None`	指定要训练的类别 ID 列表。有助于在训练期间过滤掉其他类别，仅关注特定类别。
`rect`	`bool`	`False`	启用最小填充策略——批次中的图像被最小限度地填充以达到共同的大小，最长边等于 `imgsz`。可以提高效率和速度，但可能会影响模型准确率。
`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`	`True`	启用自动混合精度 (AMP) 训练，在对准确率影响极小的情况下减少内存使用量并可能加快训练速度。
`fraction`	`float`	`1.0`	指定用于训练的数据集比例。允许在完整数据集的子集上进行训练，适用于实验或资源受限的情况。
`profile`	`bool`	`False`	在训练期间启用 ONNX 和 TensorRT 速度分析，有助于优化模型部署。
`freeze`	`int` 或 `list`	`None`	冻结模型的前 N 层或按索引指定的层，减少可训练参数的数量。对于微调或迁移学习非常有用。
`lr0`	`float`	`0.01`	初始学习率（即 `SGD=1E-2`、`Adam=1E-3`）。调整此值对优化过程至关重要，它会影响模型权重的更新速度。
`lrf`	`float`	`0.01`	作为初始率的分数的最终学习率 =（`lr0 * lrf`），与调度器结合使用以随时间调整学习率。
`momentum`	`float`	`0.937`	SGD 的动量因子或Adam 优化器的 beta1，影响当前更新中过去梯度的纳入。
`weight_decay`	`float`	`0.0005`	L2 正则化项，惩罚大权重以防止过拟合。
`warmup_epochs`	`float`	`3.0`	学习率预热的 epoch 数，将学习率从一个较小的值逐渐提高到初始学习率，以便在早期稳定训练。
`warmup_momentum`	`float`	`0.8`	预热阶段的初始动量，在预热期间逐渐调整到设定的动量值。
`warmup_bias_lr`	`float`	`0.1`	预热阶段偏置参数的学习率，有助于在初始 epoch 中稳定模型训练。
`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`	分布焦点损失 (DFL) 的权重，这是一种用于回归边界框边缘距离的边界框定位项。
`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` 将其简化为普通的 log-RMSE。
`nbs`	`int`	`64`	用于损失归一化的标称批次大小。
`overlap_mask`	`bool`	`True`	确定训练时是否应将对象掩码合并为单个掩码，还是为每个对象保持独立。如果重叠，在合并期间较小的掩码会覆盖在较大的掩码之上。
`mask_ratio`	`int`	`4`	分割掩码的下采样比率，影响训练期间所用掩码的分辨率。
`dropout`	`float`	`0.0`	分类任务中用于正则化的 Dropout 率，通过在训练期间随机省略单元来防止过拟合。
`val`	`bool`	`True`	在训练期间启用验证，允许在单独的数据集上定期评估模型性能。
`plots`	`bool`	`True`	生成并保存训练和验证指标的绘图以及预测示例，从而提供关于模型性能和学习进度的视觉见解。
`compile`	`bool` 或 `str`	`False`	启用 PyTorch 2.x `torch.compile` 图编译与 `backend='inductor'`。接受 `True` → `"default"`、`False` → 禁用，或诸如 `"default"`、`"reduce-overhead"`、`"max-autotune-no-cudagraphs"` 的字符串模式。如果不支持，则会发出警告并回退到 eager 模式。
`channels_last`	`bool`	`False`	在训练期间为卷积使用 channels_last (NHWC) 内存格式，以此加速 CUDA Tensor Core GPU，且不改变结果。在 CPU 和 MPS 上会自动忽略，因为它们无法从中获得收益。
`max_det`	`int`	`300`	指定在训练验证阶段保留的对象最大数量。

关于批次大小设置的说明

batch 参数提供了三个配置选项：

固定批次大小：用整数指定每个批次的图像数量（例如 batch=16）。
自动模式（60% GPU 内存）：使用 batch=-1 自动调整到大约 60% 的 CUDA 内存利用率。
带利用率分数的自动模式：设置一个分数（例如 batch=0.70），以便根据指定的 GPU 内存使用情况进行调整。

训练指南

预测设置#

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

推理参数：

参数	类型	默认值	描述
`source`	`str` 或 `int` 或 `None`	`None`	指定推理的数据源。可以是图像路径、视频文件、目录、URL 或用于实时流的设备 ID。如果省略，将记录一条警告，并且模型将回退到内置的演示资产（`ultralytics/assets`，或 OBB 的演示 URL）。支持广泛的格式和来源，从而能够在不同类型的输入中进行灵活应用。
`conf`	`float`	`0.25`	设置检测的最低置信度阈值。置信度低于此阈值的检测对象将被忽略。调整此值有助于减少误报。
`iou`	`float`	`0.7`	用于非极大值抑制 (NMS) 的交并比 (IoU) 阈值。较低的值通过消除重叠的框来减少检测结果，对于减少重复项非常有用。
`imgsz`	`int` 或 `tuple`	`640`	Letterbox 目标。整数给出正方形 `N×N`；元组给出 `(height, width)`。对于 `rect=True`，由于最小矩形填充，实际张量可能小于此目标。使用 `rect=False` 获取固定大小。请参阅固定形状与最小矩形。
`rect`	`bool`	`True`	如果为 `True`，则在可能的情况下使用最小矩形填充（相同形状的批次和受支持的后端）。如果为 `False`，则始终填充到完整的 `imgsz`。请参阅固定形状与最小矩形。
`quantize`	`int` 或 `str`	`None`	推理精度：`16`/`"fp16"` 在支持的 GPU 上启用 FP16 推理；`32`/`"fp32"`/未设置则为 FP32。INT8/PTQ 量化在导出期间配置，然后通过加载导出的模型来使用。替换了已弃用的 `half` 标志。
`device`	`str`	`None`	指定推理设备（例如 `cpu`、`cuda:0`、`0`、`npu` 或 `npu:0`）。允许用户在 CPU、特定 GPU、华为昇腾 NPU 或用于模型执行的其他计算设备之间进行选择。
`batch`	`int`	`1`	指定推理的批次大小（仅当源为目录、视频文件或 `.txt` 文件时有效）。更大的批次大小可以提供更高的吞吐量，从而缩短推理所需的总时间。
`max_det`	`int`	`300`	每张图像允许的最大检测数。限制模型在单次推理中可检测的对象总数，防止在密集场景中输出过多结果。
`vid_stride`	`int`	`1`	视频输入的帧步长。允许跳过视频中的帧以加快处理速度，代价是牺牲时间分辨率。值为 1 处理每一帧，更高的值会跳过帧。
`stream_buffer`	`bool`	`False`	决定是否为视频流排队传入的帧。如果为 `False`，旧帧会被丢弃以适应新帧（针对实时应用进行了优化）。如果为 `True`，则将新帧排队放入缓冲区，确保不会跳过任何帧，但如果推理 FPS 低于流 FPS，则会导致延迟。
`visualize`	`bool`	`False`	在每个预测旁边保存一个类激活热图，显示哪些像素提高了预测的类得分。遵循 `conf` 和 `classes`，因此 `classes=[0]` 仅映射该类。仅适用于 PyTorch 模型。
`augment`	`bool`	`False`	启用测试时增强 (TTA) 进行预测，可能会提高检测的稳健性，但会以牺牲推理速度为代价。
`agnostic_nms`	`bool`	`False`	启用类别无关的非极大值抑制 (NMS)，它会合并不同类别的重叠框。在类别重叠常见的多类检测场景中非常有用。对于端到端模型（YOLO26、YOLOv10），这仅防止相同的检测以多个类别标签出现（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])` 选择特定的层。对聚类或相似性搜索等下游任务很有用。
`project`	`str`	`None`	如果启用了 `save`，则为保存预测输出的项目目录的名称。
`name`	`str`	`None`	预测运行的名称。用于在项目文件夹内创建一个子目录，如果启用了 `save`，预测输出将存储在该子目录中。
`stream`	`bool`	`False`	通过返回 Results 对象的生成器而不是一次将所有帧加载到内存中，为长视频或大量图像启用内存高效处理。
`verbose`	`bool`	`True`	控制是否在终端中显示详细的推理日志，提供关于预测过程的实时反馈。
`compile`	`bool` 或 `str`	`False`	启用 PyTorch 2.x `torch.compile` 图编译与 `backend='inductor'`。接受 `True` → `"default"`、`False` → 禁用，或诸如 `"default"`、`"reduce-overhead"`、`"max-autotune-no-cudagraphs"` 的字符串模式。如果不支持，则会发出警告并回退到 eager 模式。
`channels_last`	`bool`	`False`	在推理期间为卷积使用 channels_last (NHWC) 内存格式，以此加速 CUDA Tensor Core GPU，且不改变结果。仅适用于原生 PyTorch 模型；对于 CPU、MPS 以及 TensorRT 和 ONNX 等导出格式将被忽略。
`end2end`	`bool`	`None`	覆盖支持无 NMS 推理的 YOLO 模型（YOLO26、YOLOv10）中的端到端模式。将其设置为 `False` 允许您使用传统的 NMS 管道运行预测，此外还允许您使用 `iou` 参数。有关详细信息，请参阅端到端检测指南。

可视化参数：

参数	类型	默认值	描述
`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 模型的验证设置涉及用于评估验证数据集上性能的超参数和配置。这些设置会影响性能、速度和准确率。常见设置包括批次大小、验证频率和性能指标。验证数据集的大小和组成以及特定任务也会影响此过程。

参数	类型	默认值	描述
`data`	`str`	`None`	指定数据集配置文件的路径（例如 `coco8.yaml`）。此文件应包含验证数据的路径。
`imgsz`	`int`	`640`	定义输入图像的大小。所有图像在处理前都会调整为此尺寸。较大的尺寸可能会提高小对象的精度，但会增加计算时间。
`batch`	`int`	`16`	设置每批图像的数量。更高的值更有效地利用 GPU 显存，但需要更多的 VRAM。请根据可用的硬件资源进行调整。
`save_json`	`bool`	`False`	如果为 `True`，则将结果保存到 JSON 文件中，以便进行进一步分析、与其他工具集成或提交给 COCO 等评估服务器。
`conf`	`float`	`0.001`	设置检测的最低置信度阈值。较低的值会增加召回率，但可能会引入更多误报。在验证期间用于计算精度-召回率曲线。对于 OBB 验证，默认为 `0.01` 以减少内存使用量。
`iou`	`float`	`0.7`	设置用于 Non-Maximum Suppression 的 Intersection Over Union 阈值。用于控制消除重复检测。
`max_det`	`int`	`300`	限制每张图像的最大检测数。在密集场景中非常有用，可以防止过多的检测并管理计算资源。
`quantize`	`int` 或 `str`	`None`	验证精度：`16`/`"fp16"` 在支持的 GPU 上启用 FP16 验证；`32`/`"fp32"`/未设置则为 FP32。INT8/PTQ 量化在导出期间配置，然后通过验证导出的模型来使用。替换了已弃用的 `half` 标志。
`device`	`str`	`None`	指定验证设备（`cpu`、`cuda:0`、`npu`、`npu:0` 等）。当为 `None` 时，自动选择最佳可用设备。可以使用逗号分隔指定多个 CUDA 设备。
`dnn`	`bool`	`False`	如果为 `True`，则使用 OpenCV DNN 模块进行 ONNX 模型推理，为PyTorch 推理方法提供替代方案。
`plots`	`bool`	`True`	当设置为 `True` 时，生成并保存预测与真实情况的对比图、混淆矩阵和 PR 曲线，以便对模型性能进行视觉评估。
`classes`	`list[int]`	`None`	指定需要评估的类别 ID 列表。这在评估过程中过滤并仅关注特定类别时非常有用。
`rect`	`bool`	`True`	如果为 `True`，则使用矩形推理进行批处理，通过以原始宽高比处理图像来减少填充并可能提高速度和效率。
`split`	`str`	`'val'`	决定用于验证的数据集划分（`val`、`test` 或 `train`）。在选择性能评估的数据段方面提供了灵活性。
`project`	`str`	`None`	保存验证输出的项目目录名称。有助于整理来自不同实验或模型的结果。
`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），通过对输入的转换版本运行推理，以牺牲推理速度为代价，潜在地提高检测准确率。
`agnostic_nms`	`bool`	`False`	启用与类别无关的非极大值抑制，该抑制会合并重叠的框，而不管其预测的类别如何。对以实例为中心的应用程序很有用。对于端到端模型（YOLO26、YOLOv10），这仅防止同一检测以多个类别标签出现（IoU=1.0 重复项），并且不在不同框之间执行基于 IoU 阈值的抑制。
`single_cls`	`bool`	`False`	在验证过程中将所有类别视为单一类别。对于评估二分类任务的模型性能，或者当类别区分并不重要时非常有用。
`visualize`	`bool`	`False`	为每张图像可视化真值（ground truths）、真阳性、假阳性及假阴性。有助于调试和模型解释。
`show_labels`	`bool`	`True`	当为 `visualize=True` 时，在验证可视化中显示类别标签。设置为 `False` 以更清晰地查看匹配项和错误项。
`show_conf`	`bool`	`True`	当为 `visualize=True` 时，在验证可视化中显示置信度得分。设置为 `False` 以更清晰地查看匹配项和错误项。
`compile`	`bool` 或 `str`	`False`	启用 PyTorch 2.x `torch.compile` 图编译与 `backend='inductor'`。接受 `True` → `"default"`、`False` → 禁用，或诸如 `"default"`、`"reduce-overhead"`、`"max-autotune-no-cudagraphs"` 的字符串模式。如果不支持，则会发出警告并回退到 eager 模式。
`channels_last`	`bool`	`False`	在验证期间对卷积使用 channels_last (NHWC) 内存格式，可加速 CUDA Tensor Core GPU 且结果保持不变。仅适用于原生 PyTorch 模型；对于 CPU、MPS 以及导出格式（如 TensorRT 和 ONNX）则会忽略。
`end2end`	`bool`	`None`	覆盖支持无 NMS 推理的 YOLO 模型（YOLO26、YOLOv10）中的端到端模式。将其设置为 `False` 允许您使用传统的 NMS 管道运行验证，此外还允许您使用 `iou` 参数。

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

验证指南

导出设置#

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

参数	类型	默认值	描述
`format`	`str`	`'torchscript'`	导出模型的目标格式，例如 `'onnx'`、`'torchscript'`、`'engine'` (TensorRT) 或其他格式。每种格式都能实现与不同部署环境的兼容性。
`imgsz`	`int` 或 `tuple`	`640`	模型输入的期望图像大小。可以是正方形图像的整数（例如 `640` 表示 640×640），也可以是特定尺寸的元组 `(height, width)`。
`keras`	`bool`	`False`	启用导出为 Keras 格式以用于 TensorFlow SavedModel，从而提供与 TensorFlow 服务和 API 的兼容性。
`optimize`	`bool`	`False`	为 DEEPX 启用更高的编译器优化，在增加编译时间的同时减少推理延迟。
`quantize`	`int` 或 `str`	`None`	量化精度：`16`（FP16，减小模型大小并可加速受支持硬件上的推理）或 `8`（INT8/PTQ，在对准确率影响极小的情况下进一步压缩模型，主要用于边缘设备；需要校准 `data`/`fraction`）；`32`/未设置则为 FP32。支持混合权重/激活精度的导出格式也接受 `'w8a8'`/`'w16a16'`/`'w8a16'`/`'w8a32'` 符号。替换了已弃用的 `half`/`int8` 标志（`half=True` → `16`，`int8=True` → `8`，仍然被接受但会发出弃用警告）。仅允许目标格式支持的精度（见下文）。
`dynamic`	`bool`	`False`	允许 TorchScript、ONNX、OpenVINO、TensorRT 和 CoreML 导出采用动态输入尺寸，增强了处理不同图像尺寸时的灵活性。
`simplify`	`bool`	`True`	对于构建中间 ONNX 图的导出，使用 `onnxslim` 简化该图（请参阅导出格式），这可能会提高性能以及与推理引擎的兼容性。
`opset`	`int`	`None`	为构建 ONNX 图的导出指定 ONNX opset 版本（请参阅导出格式），以实现与不同 ONNX 解析器和运行时的兼容性。如果未设置，则使用支持的最新版本。
`workspace`	`float` 或 `None`	`None`	为 TensorRT 优化设置最大工作空间大小（以 GiB 为单位），在内存使用和性能之间取得平衡。使用 `None` 可由 TensorRT 自动分配，最高可达设备最大值。
`nms`	`bool`	`False`	在支持时向导出的模型添加非极大值抑制 (NMS)（请参阅导出格式），从而提高检测后处理效率。对于端到端模型不可用。对于 CoreML，仅支持检测模型。
`batch`	`int`	`1`	指定导出模型的批次推理大小或导出的模型在 `predict` 模式下将并发处理的最大图像数。对于 Edge TPU 导出，此值自动设置为 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.0 不支持 DLA。
`data`	`str`	`None`	数据集配置文件的路径，对于 INT8 量化校准至关重要。如果在启用 INT8 的情况下未指定，Ultralytics 会在需要时选择特定于任务的校准数据集，或者回退到模型任务的默认数据集。
`fraction`	`float`	`1.0`	指定用于 INT8 量化校准的数据集比例。允许在完整数据集的一个子集上进行校准，这对实验或资源受限时非常有用。如果启用 INT8 但未指定，将使用完整数据集。
`end2end`	`bool`	`None`	覆盖支持无 NMS 推理的 YOLO 模型（YOLO26、YOLOv10）中的端到端模式。将其设置为 `False` 允许您导出这些模型以与传统的基于 NMS 的后处理管道兼容。有关详细信息，请参阅端到端检测指南。

周全的配置能确保导出模型针对其用例进行优化，并在目标环境中有效运行。

导出指南

解决方案设置#

Ultralytics 解决方案配置设置提供了灵活性，可自定义对象计数、热图生成、运动跟踪、数据分析、区域跟踪、队列管理和基于区域的计数等任务的模型。这些选项允许轻松调整，以根据特定需求获得准确且有用的结果。

参数	类型	默认值	描述
`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`	用于热力图的颜色映射。
`json_file`	`str`	`None`	包含所有停车坐标数据的 JSON 文件路径。
`up_angle`	`float`	`145.0`	“向上”姿势的角度阈值。
`kpts`	`list[int]`	`'[6, 8, 10]'`	用于监控健身锻炼的三个关键点索引列表。这些关键点对应于身体关节或部位，例如肩膀、肘部和手腕，适用于俯卧撑、引体向上、深蹲和腹部锻炼等练习。
`down_angle`	`int`	`90`	“向下”姿势的角度阈值。
`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 解决方案跟踪对象并绘制路径的视点。
`source`	`str`	`None`	输入源路径（视频、RTSP 等）。仅适用于解决方案命令行界面 (CLI)。
`figsize`	`tuple[float, float]`	`(12.8, 7.2)`	用于热力图或图表等分析图表的图片尺寸。
`fps`	`float`	`30.0`	用于速度计算的每秒帧数。
`max_hist`	`int`	`5`	用于速度/方向计算时，每个对象可跟踪的最大历史点数。
`meter_per_pixel`	`float`	`0.05`	用于将像素距离转换为现实世界单位的比例因子。
`max_speed`	`int`	`120`	视觉叠加中的最高限速（用于警报）。
`data`	`str`	`'images'`	用于相似度搜索的图像目录路径。
`imgsz`	`int`	`640`	用于模型推理的输入图像尺寸。

解决方案指南

增强设置#

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

参数	类型	默认值	支持的任务	范围	描述
`hsv_h`	`float`	`0.015`	`detect`, `segment`, `semantic`, `depth`, `classify`, `pose`, `obb`	`0.0 - 1.0`	通过色轮的一小部分调整图像的色调，引入颜色变异性。有助于模型在不同光照条件下实现泛化。
`hsv_s`	`float`	`0.7`	`detect`, `segment`, `semantic`, `depth`, `classify`, `pose`, `obb`	`0.0 - 1.0`	通过一小部分比例改变图像的饱和度，影响颜色的强度。适用于模拟不同的环境条件。
`hsv_v`	`float`	`0.4`	`detect`, `segment`, `semantic`, `depth`, `classify`, `pose`, `obb`	`0.0 - 1.0`	通过一小部分比例修改图像的值（亮度），帮助模型在各种光照条件下表现良好。
`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`	`0.5`	`detect`, `segment`, `semantic`, `depth`, `classify`, `pose`, `obb`	`0 - 1`	通过增益因子缩放图像，模拟相机与物体距离不同的情况。
`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`, `pose`, `obb`	`0.0 - 1.0`	结合两张图像的部分内容，在保持不同区域的同时创建一个部分混合图像。通过创建遮挡场景来增强模型的鲁棒性。
`copy_paste`	`float`	`0`	`segment`	`0.0 - 1.0`	在图像之间复制和粘贴物体，以增加物体实例。
`copy_paste_mode`	`str`	`flip`	`segment`	-	指定要使用的 `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`, `pose`, `obb`	-	用于高级数据增强的自定义 Albumentations 转换（仅限 Python API）。接受转换对象列表以满足特定的增强需求。

调整这些设置以满足数据集和任务的要求。尝试不同的数值可以帮助找到实现最佳模型性能的最优增强策略。

增强指南

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

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

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

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

参数	默认值	描述
`project`	`None`	指定用于保存训练运行的根目录。如果未指定，运行将保存在 `runs/<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 示例，请参阅覆盖默认配置文件。

常见问题解答#

如何提升 YOLO 模型在训练期间的性能？#

通过调整批大小、学习率、动量和权重衰减等超参数来提高性能。调整数据增强设置，选择正确的优化器，并使用早停或混合精度等技术。有关详细信息，请参阅训练指南。

哪些是影响 YOLO 模型准确率的关键超参数？#

影响准确率的关键超参数包括：

批大小（batch）：较大的批大小可以稳定训练，但需要更多内存。
学习率（lr0）：较小的学习率可以提供微调，但收敛速度较慢。
动量（momentum）：加速梯度向量，抑制振荡。
图像尺寸（imgsz）：较大的尺寸可以提高准确率，但会增加计算负载。

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

如何设置训练 YOLO 模型时的学习率？#

学习率 (lr0) 至关重要；对于 SGD，请从 0.01 开始，或者对于 Adam optimizer，请从 0.001 开始。监控指标并根据需要进行调整。使用余弦学习率调度器 (cos_lr) 或预热 (warmup_epochs，warmup_momentum)。详情请参阅Train Guide。

YOLO 模型的默认推理设置是什么？#

默认设置包括：

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

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

为什么要对 YOLO 模型使用混合精度训练？#

混合精度训练（amp=True）使用 FP16 和 FP32 减少内存使用并加快训练速度。这对现代 GPU 非常有利，允许使用更大的模型和更快的计算而不会明显损失准确率。在训练指南中了解更多信息。

贡献者

GLglenn-jocher²⁹ RIRizwanMunawar⁵ RAraimbekovm³ LALaughing-q³ MAMatthewNoyce³ AMambitious-octopus² FCfcakyon² BOBovey0809¹ MImiles-deans-ultralytics¹ GIGiantAxeWhy¹ PDpderrenger¹ JKjk4e¹ PLplashchynski¹ BUBurhan-Q¹ AYAyushExel¹ TEtensorturtle¹

创建于 2023年11月12日更新于 2周前

配置#

任务#

模式#