使用 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 | 指定数据集配置文件的路径（例如 coco8.yaml）。此文件应包含 验证数据 的路径。 |
imgsz | int | 640 | 定义输入图像的大小。所有图像在处理前都会调整为此尺寸。较大的尺寸可能会提高小对象的准确度，但会增加计算时间。 |
batch | int | 16 | 设置每个批次的图像数量。更高的值可以更有效地利用 GPU 内存，但需要更多 VRAM。根据可用的硬件资源进行调整。 |
save_json | bool | False | 如果设为 True，则将结果保存到 JSON 文件中，以便进行进一步分析、与其它工具集成或提交到 COCO 等评估服务器。 |
conf | float | 0.001 | 设置检测的最低置信度阈值。较低的值会增加召回率，但可能会引入更多的误报。在 验证 过程中用于计算查准率-召回率曲线。 |
iou | float | 0.7 | Sets the Intersection Over Union threshold for Non-Maximum Suppression. Controls duplicate detection elimination. |
max_det | int | 300 | 限制每张图片的最大检测数量。在密集场景中很有用，可以防止过多的检测结果并管理计算资源。 |
half | bool | False | 启用半 精度 (FP16) 计算，减少内存使用量，并可能在对 准确度 影响最小的情况下提高速度。 |
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 | 将每张图像的真实标签、真阳性、假阳性和假阴性可视化。对调试和模型解释很有用。 |
compile | bool 或 str | False | 启用 PyTorch 2.x torch.compile 图编译，使用 backend='inductor'。接受 True → "default"，False → 禁用，或字符串模式如 "default"、"reduce-overhead"、"max-autotune-no-cudagraphs"。如果不支持，将回退到 eager 模式并显示警告。 |
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")你还可以使用提供的代码以不同格式保存混淆矩阵结果。
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 时）。验证完成后，可以通过 results.box.image_metrics（针对检测和 OBB）、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 | 该图像的真正例 (True Positive) 数量。 |
fp | 该图像的假正例 (False Positive) 数量。 |
fn | 该图像的假负例 (False Negative) 数量。 |
此功能适用于检测、分割、姿态和 OBB 任务。
| 方法 | 返回类型 | 描述 |
|---|---|---|
summary() | List[Dict[str, Any]] | 将验证结果转换为汇总字典。 |
to_df() | DataFrame | 以结构化的 Polars DataFrame 形式返回验证结果。 |
to_csv() | str | 以 CSV 格式导出验证结果并返回 CSV 字符串。 |
to_json() | str | 以 JSON 格式导出验证结果并返回 JSON 字符串。 |
更多详细信息，请参见 DataExportMixin 类文档。
常见问题 (FAQ)
如何使用 Ultralytics 验证我的 YOLO26 模型？
要验证你的 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 模型验证中获得哪些指标？
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 进行验证有什么优势？
使用 Ultralytics YOLO 进行验证有几个优点：
- 精度： YOLO26 提供准确的性能指标，包括 mAP50、mAP75 和 mAP50-95。
- 便捷： 模型会记住其训练设置，使验证变得简单直接。
- 灵活性： 你可以针对相同或不同的数据集和图像尺寸进行验证。
- 超参数调优： 验证指标有助于微调模型以获得更好的性能。
这些优势确保你的模型得到全面评估，并能优化以获得卓越结果。在 为什么要使用 Ultralytics YOLO 进行验证 部分了解有关这些优势的更多信息。
我可以使用自定义数据集验证我的 YOLO26 模型吗？
可以，你可以使用 自定义数据集 验证你的 YOLO26 模型。指定 data 参数为你数据集配置文件所在的路径。该文件应包含 验证数据 的路径。
验证是使用模型自己的类名进行的，你可以通过 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-95使用 CLI 的示例：
yolo val model=yolo26n.pt data=path/to/your/custom_dataset.yaml如需在验证期间获得更多可定制的选项，请参见 带参数的验证示例 部分。
如何在 YOLO26 中将验证结果保存到 JSON 文件？
要将验证结果保存到 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 模型验证参数 以了解更多详细信息。