使用 Ultralytics YOLO 进行模型验证#
简介#
验证是机器学习流水线中的关键步骤，能让你评估训练模型的质量。Ultralytics YOLO26 中的 Val 模式提供了一套强大的工具和指标，用于评估目标检测模型的性能。本指南是一个完整的资源，帮助你理解如何有效使用 Val 模式，以确保你的模型既准确又可靠。
Watch: Ultralytics Modes Tutorial: Validation
为什么要使用 Ultralytics YOLO 进行验证？#
使用 YOLO26 的 Val 模式具有以下优势：
- 精度： 获取 mAP50、mAP75 和 mAP50-95 等准确指标，以全面评估你的模型。
- 便捷性： 利用内置功能记住训练设置，从而简化验证过程。
- 灵活性： 使用相同或不同的数据集和图像尺寸来验证你的模型。
- **超参数调优：**使用验证指标微调模型以获得更好的性能。
Val 模式的主要功能#
以下是 YOLO26 的 Val 模式提供的显著功能：
- 自动化设置： 模型会记住它们的训练配置，以便进行直接的验证。
- 多指标支持： 基于一系列准确率指标评估你的模型。
- CLI 和 Python API： 根据你的喜好选择命令行界面或 Python API 进行验证。
- 数据兼容性： 与训练阶段使用的数据集以及自定义数据集无缝协作。
- YOLO26 模型会自动记住其训练设置，因此只需通过
yolo val model=yolo26n.pt或YOLO("yolo26n.pt").val()即可轻松在相同的图像尺寸和原始数据集上验证模型
使用示例#
在 COCO8 数据集上验证已训练的 YOLO26n 模型准确率。无需任何参数，因为 model 保留了其训练 data 和参数作为模型属性。请参阅下方的参数部分以获取完整的验证参数列表。
在 Windows 上，以脚本形式启动验证时可能会收到 RuntimeError。在验证代码前添加一个 if __name__ == "__main__": 块即可解决此问题。
from ultralytics import YOLO
# Load a model
model = YOLO("yolo26n.pt") # load an official model
model = YOLO("path/to/best.pt") # load a custom model
# Validate the model
metrics = model.val() # no arguments needed, dataset and settings remembered
metrics.box.map # map50-95
metrics.box.map50 # map50
metrics.box.map75 # map75
metrics.box.maps # a list containing mAP50-95 for each category
metrics.box.image_metrics # per-image metrics dictionary with precision, recall, F1, TP, FP, and FNYOLO 模型验证参数#
在验证 YOLO 模型时，可以微调多个参数以优化评估过程。这些参数控制输入图像尺寸、批处理和性能阈值等方面。下方是每个参数的详细分解，帮助你有效地自定义验证设置。
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
data | str | None | 指定数据集 YAML 的路径（例如 coco8.yaml），其中应包含验证数据的路径。分类任务则改为接受数据集目录或内置数据集名称（例如 imagenet10）。 |
imgsz | int | 640 | 定义输入图像的大小。所有图像在处理前都会调整为此尺寸。较大的尺寸可能会提高小对象的精度，但会增加计算时间。 |
batch | int | 16 | 设置每批图像的数量。更高的值更有效地利用 GPU 显存，但需要更多的 VRAM。请根据可用的硬件资源进行调整。 |
save_json | bool | False | 如果为 True，则将结果保存到 JSON 文件中，以便进行进一步分析、与其他工具集成或提交给 COCO 等评估服务器。 |
conf | float | 0.001 | 设置检测的最低置信度阈值。较低的值会提高召回率，但可能会引入更多假阳性。准确率-召回率曲线默认使用 0.001；检测混淆矩阵使用显式的 conf 值，或在省略时使用 0.25。汇总准确率和召回率使用最大 F1 置信度，因此它们可能与从 confusion_matrix.png 派生的值不同。对于 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，则在批处理时使用矩形推理，通过以原始宽高比处理图像来减少填充并可能提高速度和效率。对于 depth 验证，该设置会被忽略，验证会将每张图像拉伸为固定的 imgsz 正方形而不是进行填充。 |
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），通过对输入的变换版本运行推理，可能会以牺牲推理速度为代价提高检测准确率。仅适用于 Ultralytics PyTorch 模型。 |
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 模型可定制且高效的评估。根据你的具体需求和资源调整这些参数，有助于在准确性和性能之间取得最佳平衡。
带参数的验证示例#
Watch: How to Export Model Validation Results in CSV, JSON, SQL, Polars DataFrame & More
以下示例展示了如何在 Python 和 CLI 中使用自定义参数进行 YOLO 模型验证。
from ultralytics import YOLO
# Load a model
model = YOLO("yolo26n.pt")
# Customize validation settings
metrics = model.val(data="coco8.yaml", imgsz=640, batch=16, conf=0.25, iou=0.7, device="0")你也可以使用提供的代码以不同格式保存混淆矩阵 (ConfusionMatrix) 结果。
from ultralytics import YOLO
model = YOLO("yolo26n.pt")
results = model.val(data="coco8.yaml", plots=True)
print(results.confusion_matrix.to_df())验证会为除分类之外的所有任务存储每张图像的精确率、召回率、F1、TP、FP 和 FN 指标（在 IoU 阈值为 0.5 时）。验证完成后，可通过检测和 OBB 的 results.box.image_metrics、分割的 results.seg.image_metrics 以及姿态的 results.pose.image_metrics 来访问它们。
from ultralytics import YOLO
# Load a model
model = YOLO("yolo26n.pt")
# Validate and access per-image metrics
results = model.val(data="coco8.yaml")
# image_metrics is a dictionary with image filenames as keys
print(results.box.image_metrics)
# Output: {'image1.jpg': {'precision': 0.85, 'recall': 0.92, 'f1': 0.88, 'tp': 17, 'fp': 3, 'fn': 1}, ...}
# Access metrics for a specific image
results.box.image_metrics["image1.jpg"] # {'precision': 0.85, 'recall': 0.92, 'f1': 0.88, 'tp': 17, 'fp': 3, 'fn': 1}image_metrics 中的每个条目包含以下键：
| 键 | 描述 |
|---|---|
precision | 图像的精确率得分（tp / (tp + fp)）。 |
recall | 图像的召回率得分（tp / (tp + fn)）。 |
f1 | 精度和召回率的调和平均数。 |
tp | 图像的真正例数。 |
fp | 图像的假正例数。 |
fn | 图像的假负例数。 |
此功能适用于检测、分割、姿态估计和 OBB 任务。
| 方法 | 返回类型 | 描述 |
|---|---|---|
summary() | List[Dict[str, Any]] | 将验证结果转换为汇总字典。 |
to_df() | DataFrame | 以结构化的 Polars DataFrame 返回验证结果。 |
to_csv() | str | 以 CSV 格式导出验证结果并返回 CSV 字符串。 |
to_json() | str | 以 JSON 格式导出验证结果并返回 JSON 字符串。 |
有关更多详细信息，请参阅 DataExportMixin 类文档。
下一步#
对指标满意吗？将模型导出为部署格式。如果准确率不佳，请返回并使用不同的超参数或更多训练数据重新训练。
常见问题解答#
要验证你的 YOLO26 模型，可以使用 Ultralytics 提供的 Val 模式。例如，使用 Python API，你可以加载模型并运行验证：
from ultralytics import YOLO # Load a model model = YOLO("yolo26n.pt") # Validate the model metrics = model.val() print(metrics.box.map) # map50-95或者，你可以使用命令行界面 (CLI)：
yolo val model=yolo26n.pt如需进一步自定义，你可以在 Python 和 CLI 模式下调整各种参数，例如
imgsz、batch和conf。查看YOLO 模型验证参数部分以获取完整的参数列表。YOLO26 模型验证提供了几个关键指标来评估模型性能。其中包括：
- mAP50（IoU 阈值为 0.5 时的平均精度均值）
- mAP75（IoU 阈值为 0.75 时的平均精度均值）
- mAP50-95（IoU 阈值从 0.5 到 0.95 的平均精度均值）
使用 Python API，你可以按如下方式访问这些指标：
metrics = model.val() # assumes `model` has been loaded print(metrics.box.map) # mAP50-95 print(metrics.box.map50) # mAP50 print(metrics.box.map75) # mAP75 print(metrics.box.maps) # list of mAP50-95 for each category print(metrics.box.image_metrics) # per-image metrics dictionary with precision, recall, F1, TP, FP, and FN为了进行完整的性能评估，审查所有这些指标至关重要。有关更多详细信息，请参考Val 模式的核心功能。
使用 Ultralytics YOLO 进行验证有以下几个优势：
- **精确率：**YOLO26 提供准确的性能指标，包括 mAP50、mAP75 和 mAP50-95。
- 便捷性： 模型会记住其训练设置，使验证变得简单直接。
- 灵活性： 你可以针对相同或不同的数据集和图像尺寸进行验证。
- 超参数调优： 验证指标有助于对模型进行微调以获得更好的性能。
这些优势确保了你的模型得到全面评估，并能针对卓越的结果进行优化。在为什么使用 Ultralytics YOLO 进行验证部分了解有关这些优势的更多信息。
可以，你可以使用自定义数据集来验证你的 YOLO26 模型。请指定
data参数并传入你的数据集 YAML 路径，其中应包含验证数据的路径。分类任务则接收数据集目录或内置数据集名称（例如imagenet10）。注意验证过程使用模型自身的类别名称（你可以通过
model.names查看），这些名称可能与数据集本身定义的类别不同。Python 示例：
from ultralytics import YOLO # Load a model model = YOLO("yolo26n.pt") # Validate with a custom dataset metrics = model.val(data="path/to/your/custom_dataset.yaml") print(metrics.box.map) # map50-95CLI 示例：
yolo val model=yolo26n.pt data=path/to/your/custom_dataset.yaml有关验证期间更多可自定义选项，请参阅带参数的验证示例部分。
要将验证结果保存到 JSON 文件，你可以在运行验证时将
save_json参数设置为True。这可以在 Python API 和 CLI 中完成。Python 示例：
from ultralytics import YOLO # Load a model model = YOLO("yolo26n.pt") # Save validation results to JSON metrics = model.val(save_json=True)CLI 示例：
yolo val model=yolo26n.pt save_json=True此功能对于进一步分析或与其它工具集成特别有用。查看YOLO 模型验证参数了解更多详情。