使用 Ultralytics YOLO 进行模型验证#
简介#
验证是机器学习流程中的关键步骤，可帮助你评估训练模型的质量。Ultralytics YOLO26 的 Val 模式提供了一套完善的工具和指标，用于评估你的目标检测模型的性能。本指南将全面介绍如何有效使用 Val 模式，确保你的模型既准确又可靠。
请查看未发布的 YOLO27 预览以获取初步验证结果。
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 和参数保留为模型属性。有关完整的验证参数列表，请参阅下方的 Arguments 部分。
在 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 等评估服务器。在检测数据集上，它还会使用 faster-coco-eval 对预测结果进行评估，并报告小、中、大目标 mAP，在训练过程中会将其作为 metrics/mAP_small(B)、metrics/mAP_medium(B) 和 metrics/mAP_large(B) 记录在 results.csv 中。 |
conf | float | 0.001 | 设置检测的最低置信度阈值。较低的值会提高召回率，但可能引入更多误检。精确率-召回率曲线默认为 0.001；检测混淆矩阵使用显式的 conf 值，未设置时则使用 0.25。汇总精确率和召回率使用最大 F1 值对应的置信度，因此可能与根据 confusion_matrix.png 得出的值不同。OBB 验证默认为 0.01，以减少内存使用。 |
iou | float | 0.7 | 设置交并比（IoU）和非极大值抑制（NMS）的阈值。用于控制重复检测的消除。 |
max_det | int | 300 | 限制每张图像的最大检测数。对于 detect、segment、pose 和 OBB，如果保持默认的 300，当某张图像超过该值时，它会提升至验证集中标注对象最大数量，并伴有警告；任何其他值都会保留，同时发出当图像超过该值时召回率可能会受限的警告。 |
quantize | int 或 str | None | 验证精度：16/"fp16" 与 32/"fp32"/未设置为 PyTorch 和 TorchScript 模型选择 FP16 或 FP32 计算；其他格式则在其构件与运行时所选的精度下进行计算。在 16 下，OpenVINO 仍在客户端将输入进行 FP16 舍入并将其展宽回 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）。你可以灵活选择用于性能评估的数据部分。 |
fraction | float、int 或 list | 1.0 | 验证集的一个子集。使用 [train, val, test] 列表时，匹配 split 的条目生效（1 = 完整切片，大于 1 的整数 = 图像数量；省略的条目表示完整）。标量仅在配合 split=train 时生效；此时 val 和 test 使用完整切片。 |
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 | 启用类无关的非极大值抑制，压制得分较低的重叠框，无论其预测类别如何。适用于以实例为核心的应用。使用无 NMS 推理（在 YOLO26 或 YOLOv10 上为 nms=False）时，这仅防止同一检测结果出现多个类别标签（IoU=1.0 重复），而不会在不同框之间执行基于 IoU 阈值的压制。 |
single_cls | bool | False | 在验证期间将所有类别视为单一类别。适用于评估模型在二分类检测任务中的性能，或类别区分不重要的场景。 |
visualize | bool | False | 可视化每张图像的真实标注、真正例、假正例和假负例。适用于调试和模型解读。 |
show_labels | bool | True | 当 visualize=True 时，在验证可视化中显示类别标签。设置为 False 可更清晰地查看匹配结果和错误。 |
show_conf | bool | True | 当 visualize=True 时，在验证可视化中显示置信度分数。设置为 False 可更清晰地查看匹配结果和错误。 |
compile | bool 或 str | False | 使用 backend='inductor' 启用 PyTorch 2.x 的 torch.compile 图编译。接受 True → "default"、False → 禁用，或使用 "default"、"reduce-overhead"、"max-autotune-no-cudagraphs" 等字符串模式。不支持时会发出警告并回退到 eager 模式。 |
channels_last | bool | None | 原生 PyTorch 验证使用 channels_last（NHWC）内存格式。在启用 oneDNN 的 Linux 和 Windows x86 CPU 上，且 PyTorch 版本为 1.13 或更高版本时，None 会自动启用该格式；False 会禁用该格式；True 会在受支持的 x86 CPU 或 CUDA 设备上请求该格式。ARM64、MPS、较旧的 PyTorch 版本、不支持 oneDNN 的 CPU 以及导出格式均保持不变；训练期间的验证会保留训练模型布局。 |
nms | bool，可选 | None | 默认运行带 NMS 的一对多推理（None 或 True）。设置 False 以在可用时使用无 NMS 的一对一（one-to-one）头。详见端到端检测指南。 |
这些设置在验证过程中都发挥着重要作用，使 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）。验证完成后，可以通过 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 | 图像的真正例数量。 |
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-95使用 CLI 的示例：
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在检测数据集上，
save_json=True还会通过faster-coco-eval报告小型、中型和大型物体的 mAP。查看 Arguments for YOLO Model Validation 了解更多详情。