Ultralytics YOLO 模型验证Val完整参数指南从数据输入到指标输出的 29 项配置详解【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics模型验证Validation是判断目标检测、分割、姿态估计等模型是否真实可用的关键一步。本指南以 Ultralytics 仓库中docs/macros/validation-args.md参数清单为骨架逐一拆解 YOLO Val 模式下的data、conf、iou、quantize、compile等全部参数的含义、默认值、适用任务与底层实现并结合 Python API 与 CLI 给出可直接运行的验证示例。读完本文你将能够按需定制一次高效、准确、结果可复现的模型评测并读懂 Ultralytics 在default.yaml、BaseValidator与YOLO.val()中如何消费这些配置。什么是 YOLO 的 Val验证模式验证是机器学习流水线中的质量把关环节。在 Ultralytics 中Val 模式用于在独立的验证集或测试集上评估训练完成的模型输出 mAP50、mAP75、mAP50-95 等核心精度指标并生成混淆矩阵、PR 曲线等可视化结果。Val 模式有三个显著特点自动继承训练设置YOLO 模型会把训练时的data、imgsz等参数记录为模型属性因此验证时常常不需要传任何参数直接yolo val modelyolo26n.pt或YOLO(yolo26n.pt).val()即可在原始数据集与图像尺寸上复现评测多任务统一入口同一套验证参数同时适用于检测detect、分割segment、姿态pose、旋转框OBB、分类classify、深度估计depth、语义分割semantic等任务个别参数会按任务产生差异行为CLI 与 Python API 双通道配置既可写成命令行键值对也可作为 Python 方法关键字传入。在仓库中验证功能的核心实现位于 验证器基类BaseValidator文档字符串中列出了yolo modeval modelyolo26n.pt datacoco8.yaml imgsz640的标准用法而YOLO.val()方法则是 Python 侧的入口见 model.py。所有参数的默认值集中定义在 default.yaml 的Val/Test settings与Predict settings区块中。验证参数总览表下表即当前仓库docs/macros/validation-args.md维护的官方参数清单本文后续将按分组深入展开每一参数背后的行为细节与源码依据。ArgumentTypeDefaultDescriptiondatastrNone指定数据集 YAML 的路径如coco8.yamlYAML 中需包含验证数据路径。分类任务改为接收一个数据集目录或内置数据集名称如imagenet10。imgszint640定义输入图像尺寸所有图像在送入前都会被缩放到该尺寸。更大的尺寸对小目标精度有提升但同时增加计算开销。batchint16每批处理的图像数量。更大的批量能更高效地利用 GPU 显存但需要更多显存应根据硬件资源调整。save_jsonboolFalse若为True将结果保存为 JSON 文件便于进一步分析、与其他工具集成或提交给 COCO 等评测服务器。conffloat0.001检测的最低置信度阈值。更小的值提高召回率但可能引入更多误报。PR 曲线默认用0.001检测混淆矩阵使用显式给定的conf若省略则用0.25。汇总的精确率与召回率使用最大 F1 对应的置信度因此可能与confusion_matrix.png推导的值不同。OBB 验证默认用0.01以减少内存占用。ioufloat0.7非极大值抑制NMS的 IoU 阈值控制重复检测框的消除强度。max_detint300限制每张图像的最大检测数量在密集场景下防止过量检测并控制计算资源。quantizeintorstrNone验证精度16/fp16与32/fp32/不设置时PyTorch 与 TorchScript 模型分别选用 FP16 或 FP32 计算其他格式的计算精度由产物与运行时自行决定。设为16时 OpenVINO 与 Triton 仍会在客户端把输入舍入为 FP16——OpenVINO 之后会放大回 FP32Triton 在发送前转换为服务器声明的 dtype 并以其输出的 FP16 返回——但两者实际计算的精度不受影响。INT8/PTQ 量化在导出阶段配置然后通过验证导出模型来使用。该参数取代了已弃用的half标志。devicestrNone指定验证设备cpu、cuda:0、npu、npu:0等。为None时自动选择最佳可用设备。多个 CUDA 设备可用逗号分隔指定。dnnboolFalse若为TrueONNX 模型推理改用 OpenCV DNN 模块作为 PyTorch 推理的替代方案。plotsboolTrue为True时生成并保存预测与真值对比图、混淆矩阵与 PR 曲线用于可视化评估模型性能。classeslist[int]None指定要评估的类别 ID 列表用于过滤并只聚焦评测某些类别。rectboolTrue若为True使用矩形推理进行批处理减少填充、按图像原始宽高比处理从而可能提升速度与效率。对depth深度验证忽略该参数此时每张图都被拉伸到固定的imgsz正方形而非填充。splitstrval决定用于验证的数据集划分val、test或train便于灵活选择评估数据段。projectstrNone保存验证输出的项目目录名用于组织不同实验或模型的产出。namestrNone验证运行的名称用于在项目目录下创建存放日志与输出的子目录。verboseboolTrue若为True验证过程输出详细信息包括每类指标、批处理进度与额外调试信息。save_txtboolFalse若为True将检测结果保存为文本文件每张图像一个文件便于进一步分析、自定义后处理或与其他系统集成。save_confboolFalse若为True且启用了save_txt在保存的文本文件中附带置信度为分析与过滤提供更详细的输出。workersint8数据加载的工作线程数。更高数值可加速数据预处理但会提高 CPU 占用设为0使用主线程在某些环境中更稳定。augmentboolFalse开启测试时增强TTA验证对输入的多种变换版本分别推理可能提升精度但牺牲推理速度。仅对 Ultralytics PyTorch 模型可用。agnostic_nmsboolFalse启用类别无关的 NMS无论预测类别如何都抑制低分的重叠框适合面向实例的应用。对端到端模型YOLO26、YOLOv10而言该参数只阻止同一次检测以多个类别标签出现IoU1.0 重复并不会对不同框执行基于 IoU 阈值的抑制。single_clsboolFalse验证时将所有类别视为单一类别适用于二分类检测任务或类别区分无关紧要的评测场景。visualizeboolFalse逐图可视化真值、真阳性、假阳性与假阴性便于调试与模型解释。show_labelsboolTrue当visualizeTrue时在验证可视化中显示类别标签设为False可获得更清爽的匹配与错误视图。show_confboolTrue当visualizeTrue时在验证可视化中显示置信度分数设为False可获得更清爽的视图。compileboolorstrFalse启用 PyTorch 2.xtorch.compile图编译backendinductor。接受True→default、False→ 禁用或字符串模式如default、reduce-overhead、max-autotune-no-cudagraphs。若当前环境不支持则回退到 eager 模式并给出警告。channels_lastboolNone对原生 PyTorch 验证使用 channels_lastNHWC内存格式。None时在一DNN 使能的 Linux/Windows x86 CPU 且 PyTorch ≥1.13 上自动开启False禁用True在受支持的 x86 CPU 或 CUDA 设备上请求开启。ARM64、MPS、旧版 PyTorch、无 oneDNN 的 CPU 及导出格式保持不变训练期间的验证保留训练时的模型布局。end2endboolNone覆盖支持免 NMS 推理的 YOLO 模型YOLO26、YOLOv10的端到端模式。设为False可走传统 NMS 流程验证从而让iou参数生效。上述参数在default.yaml的Val/Test settings、Predict settings、Visualize settings区块中均有对应默认值注释如conf的“predict0.25, val0.001”、iou: 0.7、max_det: 300、save_json: False等CLI、Python 调用时若未显式给出最终都会回落到这套全局默认。数据与输入侧参数data、imgsz、batch、rect、split、workers、devicedata选择评测数据集data指向数据集 YAML仓库内置示例位于 ultralytics/cfg/datasets如coco8.yaml、coco128.yamlYAML 内需声明val及可选的test/train路径与类别名。实际加载时验证器通过check_det_dataset/check_cls_dataset解析数据集见 validator.py。分类任务的data用法不同直接给一个数据集目录或内置名称如imagenet10。另一个易踩的坑是验证使用的是模型自带的类别名model.names可能与数据集 YAML 里定义的类别名不一致做自定义数据集评测前请先核对两者。imgsz 与 batch分辨率与批量的权衡imgsz默认640所有图像先缩放到该尺寸再送入网络。增大尺寸对小目标更友好但预处理、推理与后处理的时间都会上升。可用check_imgsz校验是否对齐模型步长batch默认16批量越大越能榨干 GPU 显存带宽但受 VRAM 上限约束显存不足时应调小。rect按原图宽高比分桶的矩形批处理默认验证时rectTrue即把同批图像按相近宽高比分组、做最小填充从而减少无效像素计算。这一默认值在 model.py 的val()中以custom {rect: True}方式注入优先级高于default.yaml中的rect: False但低于用户显式传入值。注意depth任务会忽略rect把每张图直接拉伸为固定正方形属于深度估计任务的特例。split在 val / test / train 之间切换默认评测val划分当需要向竞赛/评测服务器提交前先看test效果或想看训练集上的拟合度时可分别指定splittest或splittrain。default.yaml中split: val为默认。workers 与 deviceworkers默认8控制 DataLoader 的工作线程数调大可加快图像读取与预处理但需预留 CPU 余量在多进程/某些受限环境下设为0走主线程反而更稳定device为None时由select_device自动挑选最佳可用设备也可以显式给cpu、cuda:0、npu:0Ascend等多卡可用逗号分隔如0,1在 validator.py 的select_device导入中可看到统一设备选择逻辑。检测质量与过滤参数conf、iou、max_det、classes、single_cls、agnostic_nms、end2endconf置信度阈值的“三套用法”conf在验证中默认是0.001但它实际影响三处不同逻辑各自取用的默认值并不相同这也是最容易误解的参数之一PR 曲线默认使用0.001保证尽可能低的阈值以覆盖完整召回区间画出全曲线混淆矩阵优先用显式给出的conf若调用时省略则取0.25汇总的 Precision / Recall基于最大 F1 对应的置信度计算因此与直接从confusion_matrix.png反推出来的数值可能不一致OBB 验证默认0.01用于降低内存占用。若手动把conf调到较高值如0.25会牺牲低置信度目标而提升精确率若要追求高召回如安全巡检场景应保持低阈值。iou 与 max_det抑制重复框与控制检测上限iou默认0.7NMS 的 IoU 阈值。值越高保留的重叠框越多更宽松值越低去重越激进。端到端模型YOLO26、YOLOv10默认不走 IoU 阈值型 NMS若想用它需把end2endFalse切回传统 NMS 管线max_det默认300限制每图最多返回的检测框数量密集小目标场景可适当调大如 1000但要接受更高的后处理开销。classes 与 single_cls按需裁剪评测范围classes[0, 2, 3]只统计指定类别的结果适合单独评估某个类别或排除无关类别single_clsTrue把所有类别合并为一类对应二分类检测或类别区分不重要的评估。agnostic_nms 与 end2endagnostic_nmsTrue忽略类别做全局抑制同一物体即使被判为不同类别也只保留一个框面向“数实例”类应用关键约束对于端到端模型该参数并不做基于 IoU 阈值的框间抑制仅移除同一次检测带多个类别标签IoU1.0 重复的情况end2end默认None表示沿用模型导出/训练时决定的端到端状态显式设False即用传统 NMS 分支验证此时iou、agnostic_nms等传统参数才会按预期生效。精度与计算参数quantize、dnn、compile、channels_last、augmentquantize验证时的数值精度策略quantize取代了旧版half标志接受整数或字符串16/fp16、32/fp32/不设置。注意其行为依模型格式而不同PyTorch / TorchScript16用 FP16 计算32或不设置用 FP32其他导出格式计算精度由产物与运行时决定该参数不干预特例设为16时 OpenVINO 与 Triton 只在客户端把输入舍入成 FP16OpenVINO 随后内部放大回 FP32 计算Triton 发送前转为服务器声明 dtype返回时以 FP16 输出但两者服务端实际计算精度不变INT8/PTQ 量化属于导出阶段配置参见 export 文档 的量化选项之后通过验证量化产物来评估精度损失。default.yaml中该参数注释明确指出它同时“replaces deprecated half/int8 args”。dnn切换 ONNX 的推理后端dnnTrue时.onnx模型用 OpenCV DNN 而非默认的 ONNX Runtime 推理。当你想交叉验证两种后端的数值一致性或规避特定运行时问题时可开启。compile用 torch.compile 加速验证compile支持布尔或字符串True等价于defaultFalse禁用字符串模式可填default、reduce-overhead、max-autotune-no-cudagraphs底层对应torch.compile(..., backendinductor)若环境不支持相应编译能力会打印警告并回退到 eager 模式不影响结果正确性。该参数与训练侧共享同一套attempt_compile辅助函数位于 torch_utils.pydefault.yaml中训练与验证均可见compile: False。channels_last内存布局优化channels_lastNHWC针对原生 PyTorch 验证None默认在启用 oneDNN 的 Linux/Windows x86 CPU 且 PyTorch ≥1.13 时自动启用False强制禁用True在受支持的 x86 CPU 或 CUDA 设备上请求 NHWC 布局。ARM64、MPS、旧版 PyTorch、无 oneDNN 的 CPU 与所有导出格式均不受其影响训练中的验证保持训练时的模型布局不会中途切换。augment测试时增强TTAaugmentTrue对输入的多种几何/颜色变换分别推理再融合结果可小幅提升 mAP但推理时间成倍增加且仅对 Ultralytics PyTorch 模型可用导出格式与部分后端不支持。适合精度优先、时间充裕的最终评测。输出与结果管理参数project、name、verbose、plots、save_json、save_txt、save_conf、visualize、show_labels、show_conf目录与日志project、name、verboseprojectname决定结果落盘目录project/name与训练/预测共享同一套输出目录逻辑get_save_dir见 validator.py便于把不同模型、不同数据集的评测分目录归档verboseTrue时打印逐类 AP/AR、批处理进度等详细日志False可减少终端刷屏。结果文件save_json、save_txt、save_confsave_jsonTrue保存 COCO 格式 JSONdetect/segment/pose可提交到 COCO 评测服务器或继续做离线分析分类/语义分割任务另有各自导出行为save_txtTrue每张图一个文本结果文件xywh 归一化格式save_confTrue在save_txt基础上把置信度一并写入文本行。可视化与调试plots、visualize、show_labels、show_confplotsTrue默认开启会产出预测 vs 真值对比、混淆矩阵与 PR 曲线。混淆矩阵对象还能通过results.confusion_matrix.to_df()以 DataFrame 导出前提是先完成一次plotsTrue的验证visualizeTrue逐图标注真值GT、真阳性TP、假阳性FP、假阴性FN配合show_labels/show_conf开关默认均为True可置False获得更干净的对比视图用于定位漏检与误检的具体图像按 val 模式文档验证还会在每个 IoU0.5 下保存逐图 precision/recall/F1/TP/FP/FN分类除外检测与 OBB 经results.box.image_metrics、分割经results.seg.image_metrics、姿态经results.pose.image_metrics访问键为图像文件名值为含precision、recall、f1、tp、fp、fn的字典。在 Python 与 CLI 中组合使用这些参数参数可以任意组合覆盖默认值。Python 侧model.val(**kwargs)会按{self.overrides, 方法默认值, 用户 kwargs, modeval}的优先级合并配置后出现的覆盖先出现的见 model.py。最简验证模型自动记忆数据与设置from ultralytics import YOLO model YOLO(yolo26n.pt) # 加载官方预训练模型 metrics model.val() # 数据集与参数均继承训练设置 print(metrics.box.map) # mAP50-95 print(metrics.box.map50) # mAP50 print(metrics.box.map75) # mAP75 print(metrics.box.maps) # 每个类别的 mAP50-95 列表自定义验证参数metrics model.val( datacoco8.yaml, imgsz640, batch16, conf0.25, iou0.7, device0, plotsTrue, save_jsonTrue, )同样的配置写成 CLIyolo val modelyolo26n.pt datacoco8.yaml imgsz640 batch16 conf0.25 iou0.7 device0 yolo detect val modelpath/to/best.pt # 自定义训练权重评测导出格式模型时的典型组合yolo val modelyolo26n.onnx dnnTrue # ONNX 走 OpenCV DNN yolo val modelyolo26n_openvino_model quantize16 # OpenVINO FP16 输入 yolo val modelyolo26n.engine device0 # TensorRT 引擎注意在 Windows 上以脚本方式运行验证可能触发多进程RuntimeError官方文档建议把验证代码放进if __name__ __main__:块。参数选择与结果解读的实用建议按评测目的分层选择 conf 与 iou要画完整 PR 曲线、评估模型上限保持默认conf0.001不要手动抬高要模拟部署阈值下的真实误检率把conf设成与线上一致的数值如0.25并理解汇总 Precision/Recall 基于 max-F1 置信度故与混淆矩阵截图数值可能有出入端到端模型要获得 IoU 阈值控制能力先设end2endFalse。精度与资源平衡追求小目标精度可放大imgsz但先确认显存与batch的余量显存紧张优先降batch或对 OBB 保持默认conf0.01以控内存大批量评测且 CPU 富余时调高workers在 docker/受限容器环境遇到 dataloader 卡死可试workers0。多模型横向对比用projectname为每次评测建独立目录例如projectruns/val nameyolo26n_coco8再配合save_json与verbose即可对多个候选模型做一致的指标归档与横向比较。小结验证参数的精细控制是把“训练完的模型”变成“可放心上线的模型”的最后一道工序。掌握docs/macros/validation-args.md这张参数表等于拿到了 Ultralytics Val 模式的完整遥控器输入侧用data/imgsz/batch/rect/split定义评测环境评估侧用conf/iou/max_det/classes/agnostic_nms/end2end校准评测口径输出侧用plots/save_json/save_txt/visualize沉淀可复用的评测报告再叠加quantize/compile/channels_last/augment在不同运行时与精度策略之间穿梭。参数默认值与代码入口均可在 default.yaml、validator.py 与 model.py 中进一步核对完整的 Val 模式使用指引与指标导出方法summary()、to_df()、to_csv()、to_json()见 Val 模式文档 与 配置参数文档。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ultralytics YOLO 模型验证（Val）完整参数指南：从数据输入到指标输出的 29 项配置详解
Ultralytics YOLO 模型验证Val完整参数指南从数据输入到指标输出的 29 项配置详解【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics模型验证Validation是判断目标检测、分割、姿态估计等模型是否真实可用的关键一步。本指南以 Ultralytics 仓库中docs/macros/validation-args.md参数清单为骨架逐一拆解 YOLO Val 模式下的data、conf、iou、quantize、compile等全部参数的含义、默认值、适用任务与底层实现并结合 Python API 与 CLI 给出可直接运行的验证示例。读完本文你将能够按需定制一次高效、准确、结果可复现的模型评测并读懂 Ultralytics 在default.yaml、BaseValidator与YOLO.val()中如何消费这些配置。什么是 YOLO 的 Val验证模式验证是机器学习流水线中的质量把关环节。在 Ultralytics 中Val 模式用于在独立的验证集或测试集上评估训练完成的模型输出 mAP50、mAP75、mAP50-95 等核心精度指标并生成混淆矩阵、PR 曲线等可视化结果。Val 模式有三个显著特点自动继承训练设置YOLO 模型会把训练时的data、imgsz等参数记录为模型属性因此验证时常常不需要传任何参数直接yolo val modelyolo26n.pt或YOLO(yolo26n.pt).val()即可在原始数据集与图像尺寸上复现评测多任务统一入口同一套验证参数同时适用于检测detect、分割segment、姿态pose、旋转框OBB、分类classify、深度估计depth、语义分割semantic等任务个别参数会按任务产生差异行为CLI 与 Python API 双通道配置既可写成命令行键值对也可作为 Python 方法关键字传入。在仓库中验证功能的核心实现位于 验证器基类BaseValidator文档字符串中列出了yolo modeval modelyolo26n.pt datacoco8.yaml imgsz640的标准用法而YOLO.val()方法则是 Python 侧的入口见 model.py。所有参数的默认值集中定义在 default.yaml 的Val/Test settings与Predict settings区块中。验证参数总览表下表即当前仓库docs/macros/validation-args.md维护的官方参数清单本文后续将按分组深入展开每一参数背后的行为细节与源码依据。ArgumentTypeDefaultDescriptiondatastrNone指定数据集 YAML 的路径如coco8.yamlYAML 中需包含验证数据路径。分类任务改为接收一个数据集目录或内置数据集名称如imagenet10。imgszint640定义输入图像尺寸所有图像在送入前都会被缩放到该尺寸。更大的尺寸对小目标精度有提升但同时增加计算开销。batchint16每批处理的图像数量。更大的批量能更高效地利用 GPU 显存但需要更多显存应根据硬件资源调整。save_jsonboolFalse若为True将结果保存为 JSON 文件便于进一步分析、与其他工具集成或提交给 COCO 等评测服务器。conffloat0.001检测的最低置信度阈值。更小的值提高召回率但可能引入更多误报。PR 曲线默认用0.001检测混淆矩阵使用显式给定的conf若省略则用0.25。汇总的精确率与召回率使用最大 F1 对应的置信度因此可能与confusion_matrix.png推导的值不同。OBB 验证默认用0.01以减少内存占用。ioufloat0.7非极大值抑制NMS的 IoU 阈值控制重复检测框的消除强度。max_detint300限制每张图像的最大检测数量在密集场景下防止过量检测并控制计算资源。quantizeintorstrNone验证精度16/fp16与32/fp32/不设置时PyTorch 与 TorchScript 模型分别选用 FP16 或 FP32 计算其他格式的计算精度由产物与运行时自行决定。设为16时 OpenVINO 与 Triton 仍会在客户端把输入舍入为 FP16——OpenVINO 之后会放大回 FP32Triton 在发送前转换为服务器声明的 dtype 并以其输出的 FP16 返回——但两者实际计算的精度不受影响。INT8/PTQ 量化在导出阶段配置然后通过验证导出模型来使用。该参数取代了已弃用的half标志。devicestrNone指定验证设备cpu、cuda:0、npu、npu:0等。为None时自动选择最佳可用设备。多个 CUDA 设备可用逗号分隔指定。dnnboolFalse若为TrueONNX 模型推理改用 OpenCV DNN 模块作为 PyTorch 推理的替代方案。plotsboolTrue为True时生成并保存预测与真值对比图、混淆矩阵与 PR 曲线用于可视化评估模型性能。classeslist[int]None指定要评估的类别 ID 列表用于过滤并只聚焦评测某些类别。rectboolTrue若为True使用矩形推理进行批处理减少填充、按图像原始宽高比处理从而可能提升速度与效率。对depth深度验证忽略该参数此时每张图都被拉伸到固定的imgsz正方形而非填充。splitstrval决定用于验证的数据集划分val、test或train便于灵活选择评估数据段。projectstrNone保存验证输出的项目目录名用于组织不同实验或模型的产出。namestrNone验证运行的名称用于在项目目录下创建存放日志与输出的子目录。verboseboolTrue若为True验证过程输出详细信息包括每类指标、批处理进度与额外调试信息。save_txtboolFalse若为True将检测结果保存为文本文件每张图像一个文件便于进一步分析、自定义后处理或与其他系统集成。save_confboolFalse若为True且启用了save_txt在保存的文本文件中附带置信度为分析与过滤提供更详细的输出。workersint8数据加载的工作线程数。更高数值可加速数据预处理但会提高 CPU 占用设为0使用主线程在某些环境中更稳定。augmentboolFalse开启测试时增强TTA验证对输入的多种变换版本分别推理可能提升精度但牺牲推理速度。仅对 Ultralytics PyTorch 模型可用。agnostic_nmsboolFalse启用类别无关的 NMS无论预测类别如何都抑制低分的重叠框适合面向实例的应用。对端到端模型YOLO26、YOLOv10而言该参数只阻止同一次检测以多个类别标签出现IoU1.0 重复并不会对不同框执行基于 IoU 阈值的抑制。single_clsboolFalse验证时将所有类别视为单一类别适用于二分类检测任务或类别区分无关紧要的评测场景。visualizeboolFalse逐图可视化真值、真阳性、假阳性与假阴性便于调试与模型解释。show_labelsboolTrue当visualizeTrue时在验证可视化中显示类别标签设为False可获得更清爽的匹配与错误视图。show_confboolTrue当visualizeTrue时在验证可视化中显示置信度分数设为False可获得更清爽的视图。compileboolorstrFalse启用 PyTorch 2.xtorch.compile图编译backendinductor。接受True→default、False→ 禁用或字符串模式如default、reduce-overhead、max-autotune-no-cudagraphs。若当前环境不支持则回退到 eager 模式并给出警告。channels_lastboolNone对原生 PyTorch 验证使用 channels_lastNHWC内存格式。None时在一DNN 使能的 Linux/Windows x86 CPU 且 PyTorch ≥1.13 上自动开启False禁用True在受支持的 x86 CPU 或 CUDA 设备上请求开启。ARM64、MPS、旧版 PyTorch、无 oneDNN 的 CPU 及导出格式保持不变训练期间的验证保留训练时的模型布局。end2endboolNone覆盖支持免 NMS 推理的 YOLO 模型YOLO26、YOLOv10的端到端模式。设为False可走传统 NMS 流程验证从而让iou参数生效。上述参数在default.yaml的Val/Test settings、Predict settings、Visualize settings区块中均有对应默认值注释如conf的“predict0.25, val0.001”、iou: 0.7、max_det: 300、save_json: False等CLI、Python 调用时若未显式给出最终都会回落到这套全局默认。数据与输入侧参数data、imgsz、batch、rect、split、workers、devicedata选择评测数据集data指向数据集 YAML仓库内置示例位于 ultralytics/cfg/datasets如coco8.yaml、coco128.yamlYAML 内需声明val及可选的test/train路径与类别名。实际加载时验证器通过check_det_dataset/check_cls_dataset解析数据集见 validator.py。分类任务的data用法不同直接给一个数据集目录或内置名称如imagenet10。另一个易踩的坑是验证使用的是模型自带的类别名model.names可能与数据集 YAML 里定义的类别名不一致做自定义数据集评测前请先核对两者。imgsz 与 batch分辨率与批量的权衡imgsz默认640所有图像先缩放到该尺寸再送入网络。增大尺寸对小目标更友好但预处理、推理与后处理的时间都会上升。可用check_imgsz校验是否对齐模型步长batch默认16批量越大越能榨干 GPU 显存带宽但受 VRAM 上限约束显存不足时应调小。rect按原图宽高比分桶的矩形批处理默认验证时rectTrue即把同批图像按相近宽高比分组、做最小填充从而减少无效像素计算。这一默认值在 model.py 的val()中以custom {rect: True}方式注入优先级高于default.yaml中的rect: False但低于用户显式传入值。注意depth任务会忽略rect把每张图直接拉伸为固定正方形属于深度估计任务的特例。split在 val / test / train 之间切换默认评测val划分当需要向竞赛/评测服务器提交前先看test效果或想看训练集上的拟合度时可分别指定splittest或splittrain。default.yaml中split: val为默认。workers 与 deviceworkers默认8控制 DataLoader 的工作线程数调大可加快图像读取与预处理但需预留 CPU 余量在多进程/某些受限环境下设为0走主线程反而更稳定device为None时由select_device自动挑选最佳可用设备也可以显式给cpu、cuda:0、npu:0Ascend等多卡可用逗号分隔如0,1在 validator.py 的select_device导入中可看到统一设备选择逻辑。检测质量与过滤参数conf、iou、max_det、classes、single_cls、agnostic_nms、end2endconf置信度阈值的“三套用法”conf在验证中默认是0.001但它实际影响三处不同逻辑各自取用的默认值并不相同这也是最容易误解的参数之一PR 曲线默认使用0.001保证尽可能低的阈值以覆盖完整召回区间画出全曲线混淆矩阵优先用显式给出的conf若调用时省略则取0.25汇总的 Precision / Recall基于最大 F1 对应的置信度计算因此与直接从confusion_matrix.png反推出来的数值可能不一致OBB 验证默认0.01用于降低内存占用。若手动把conf调到较高值如0.25会牺牲低置信度目标而提升精确率若要追求高召回如安全巡检场景应保持低阈值。iou 与 max_det抑制重复框与控制检测上限iou默认0.7NMS 的 IoU 阈值。值越高保留的重叠框越多更宽松值越低去重越激进。端到端模型YOLO26、YOLOv10默认不走 IoU 阈值型 NMS若想用它需把end2endFalse切回传统 NMS 管线max_det默认300限制每图最多返回的检测框数量密集小目标场景可适当调大如 1000但要接受更高的后处理开销。classes 与 single_cls按需裁剪评测范围classes[0, 2, 3]只统计指定类别的结果适合单独评估某个类别或排除无关类别single_clsTrue把所有类别合并为一类对应二分类检测或类别区分不重要的评估。agnostic_nms 与 end2endagnostic_nmsTrue忽略类别做全局抑制同一物体即使被判为不同类别也只保留一个框面向“数实例”类应用关键约束对于端到端模型该参数并不做基于 IoU 阈值的框间抑制仅移除同一次检测带多个类别标签IoU1.0 重复的情况end2end默认None表示沿用模型导出/训练时决定的端到端状态显式设False即用传统 NMS 分支验证此时iou、agnostic_nms等传统参数才会按预期生效。精度与计算参数quantize、dnn、compile、channels_last、augmentquantize验证时的数值精度策略quantize取代了旧版half标志接受整数或字符串16/fp16、32/fp32/不设置。注意其行为依模型格式而不同PyTorch / TorchScript16用 FP16 计算32或不设置用 FP32其他导出格式计算精度由产物与运行时决定该参数不干预特例设为16时 OpenVINO 与 Triton 只在客户端把输入舍入成 FP16OpenVINO 随后内部放大回 FP32 计算Triton 发送前转为服务器声明 dtype返回时以 FP16 输出但两者服务端实际计算精度不变INT8/PTQ 量化属于导出阶段配置参见 export 文档 的量化选项之后通过验证量化产物来评估精度损失。default.yaml中该参数注释明确指出它同时“replaces deprecated half/int8 args”。dnn切换 ONNX 的推理后端dnnTrue时.onnx模型用 OpenCV DNN 而非默认的 ONNX Runtime 推理。当你想交叉验证两种后端的数值一致性或规避特定运行时问题时可开启。compile用 torch.compile 加速验证compile支持布尔或字符串True等价于defaultFalse禁用字符串模式可填default、reduce-overhead、max-autotune-no-cudagraphs底层对应torch.compile(..., backendinductor)若环境不支持相应编译能力会打印警告并回退到 eager 模式不影响结果正确性。该参数与训练侧共享同一套attempt_compile辅助函数位于 torch_utils.pydefault.yaml中训练与验证均可见compile: False。channels_last内存布局优化channels_lastNHWC针对原生 PyTorch 验证None默认在启用 oneDNN 的 Linux/Windows x86 CPU 且 PyTorch ≥1.13 时自动启用False强制禁用True在受支持的 x86 CPU 或 CUDA 设备上请求 NHWC 布局。ARM64、MPS、旧版 PyTorch、无 oneDNN 的 CPU 与所有导出格式均不受其影响训练中的验证保持训练时的模型布局不会中途切换。augment测试时增强TTAaugmentTrue对输入的多种几何/颜色变换分别推理再融合结果可小幅提升 mAP但推理时间成倍增加且仅对 Ultralytics PyTorch 模型可用导出格式与部分后端不支持。适合精度优先、时间充裕的最终评测。输出与结果管理参数project、name、verbose、plots、save_json、save_txt、save_conf、visualize、show_labels、show_conf目录与日志project、name、verboseprojectname决定结果落盘目录project/name与训练/预测共享同一套输出目录逻辑get_save_dir见 validator.py便于把不同模型、不同数据集的评测分目录归档verboseTrue时打印逐类 AP/AR、批处理进度等详细日志False可减少终端刷屏。结果文件save_json、save_txt、save_confsave_jsonTrue保存 COCO 格式 JSONdetect/segment/pose可提交到 COCO 评测服务器或继续做离线分析分类/语义分割任务另有各自导出行为save_txtTrue每张图一个文本结果文件xywh 归一化格式save_confTrue在save_txt基础上把置信度一并写入文本行。可视化与调试plots、visualize、show_labels、show_confplotsTrue默认开启会产出预测 vs 真值对比、混淆矩阵与 PR 曲线。混淆矩阵对象还能通过results.confusion_matrix.to_df()以 DataFrame 导出前提是先完成一次plotsTrue的验证visualizeTrue逐图标注真值GT、真阳性TP、假阳性FP、假阴性FN配合show_labels/show_conf开关默认均为True可置False获得更干净的对比视图用于定位漏检与误检的具体图像按 val 模式文档验证还会在每个 IoU0.5 下保存逐图 precision/recall/F1/TP/FP/FN分类除外检测与 OBB 经results.box.image_metrics、分割经results.seg.image_metrics、姿态经results.pose.image_metrics访问键为图像文件名值为含precision、recall、f1、tp、fp、fn的字典。在 Python 与 CLI 中组合使用这些参数参数可以任意组合覆盖默认值。Python 侧model.val(**kwargs)会按{self.overrides, 方法默认值, 用户 kwargs, modeval}的优先级合并配置后出现的覆盖先出现的见 model.py。最简验证模型自动记忆数据与设置from ultralytics import YOLO model YOLO(yolo26n.pt) # 加载官方预训练模型 metrics model.val() # 数据集与参数均继承训练设置 print(metrics.box.map) # mAP50-95 print(metrics.box.map50) # mAP50 print(metrics.box.map75) # mAP75 print(metrics.box.maps) # 每个类别的 mAP50-95 列表自定义验证参数metrics model.val( datacoco8.yaml, imgsz640, batch16, conf0.25, iou0.7, device0, plotsTrue, save_jsonTrue, )同样的配置写成 CLIyolo val modelyolo26n.pt datacoco8.yaml imgsz640 batch16 conf0.25 iou0.7 device0 yolo detect val modelpath/to/best.pt # 自定义训练权重评测导出格式模型时的典型组合yolo val modelyolo26n.onnx dnnTrue # ONNX 走 OpenCV DNN yolo val modelyolo26n_openvino_model quantize16 # OpenVINO FP16 输入 yolo val modelyolo26n.engine device0 # TensorRT 引擎注意在 Windows 上以脚本方式运行验证可能触发多进程RuntimeError官方文档建议把验证代码放进if __name__ __main__:块。参数选择与结果解读的实用建议按评测目的分层选择 conf 与 iou要画完整 PR 曲线、评估模型上限保持默认conf0.001不要手动抬高要模拟部署阈值下的真实误检率把conf设成与线上一致的数值如0.25并理解汇总 Precision/Recall 基于 max-F1 置信度故与混淆矩阵截图数值可能有出入端到端模型要获得 IoU 阈值控制能力先设end2endFalse。精度与资源平衡追求小目标精度可放大imgsz但先确认显存与batch的余量显存紧张优先降batch或对 OBB 保持默认conf0.01以控内存大批量评测且 CPU 富余时调高workers在 docker/受限容器环境遇到 dataloader 卡死可试workers0。多模型横向对比用projectname为每次评测建独立目录例如projectruns/val nameyolo26n_coco8再配合save_json与verbose即可对多个候选模型做一致的指标归档与横向比较。小结验证参数的精细控制是把“训练完的模型”变成“可放心上线的模型”的最后一道工序。掌握docs/macros/validation-args.md这张参数表等于拿到了 Ultralytics Val 模式的完整遥控器输入侧用data/imgsz/batch/rect/split定义评测环境评估侧用conf/iou/max_det/classes/agnostic_nms/end2end校准评测口径输出侧用plots/save_json/save_txt/visualize沉淀可复用的评测报告再叠加quantize/compile/channels_last/augment在不同运行时与精度策略之间穿梭。参数默认值与代码入口均可在 default.yaml、validator.py 与 model.py 中进一步核对完整的 Val 模式使用指引与指标导出方法summary()、to_df()、to_csv()、to_json()见 Val 模式文档 与 配置参数文档。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考