YOLO Vision 2026：

使用 Ultralytics YOLO 进行模型导出#

Ultralytics YOLO ecosystem and integrations

简介#

训练模型的最终目标是将其部署到现实世界的应用程序中。Ultralytics YOLO26 中的导出模式提供了一系列通用的选项，用于将训练好的模型导出为不同格式，使其能够部署在各种平台和设备上。本综合指南旨在带你了解模型导出的细节，展示如何实现最大的兼容性和性能。



Watch: How to Export Ultralytics YOLO26 in different formats for Deployment | ONNX, TensorRT, CoreML 🚀

为什么要选择 YOLO26 的导出模式？#

  • **通用性：**可导出至多种格式，包括 ONNX、TensorRT、CoreML 等。
  • **性能：**使用 TensorRT 可获得高达 5 倍的 GPU 提速，使用 ONNX 或 OpenVINO 可获得高达 3 倍的 CPU 提速。
  • 兼容性： 使你的模型能够在众多的硬件和软件环境中实现通用部署。
  • 易用性： 提供简单的 CLI 和 Python API，实现快速直接的模型导出。

导出模式的主要功能#

以下是一些出色的功能：

  • 一键导出： 用于导出为不同格式的简单命令。
  • 批量导出： 导出支持批量推理的模型。
  • 优化推理： 导出的模型针对更快的推理时间进行了优化。
  • 教程视频： 提供深入的指南和教程，带来顺畅的导出体验。
提示
  • 导出为 ONNX 或 OpenVINO 可获得高达 3 倍的 CPU 提速。
  • 导出为 TensorRT 可获得高达 5 倍的 GPU 提速。

使用示例#

将 YOLO26n 模型导出为其他格式，例如 ONNX 或 TensorRT。有关完整的导出参数列表，请参阅下方的参数部分。

示例
from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n.pt")  # load an official model
model = YOLO("path/to/best.pt")  # load a custom-trained model

# Export the model
model.export(format="onnx")

参数#

此表格详细说明了将 YOLO 模型导出为不同格式时可用的配置和选项。这些设置对于优化导出模型的性能、大小以及在各种平台和环境下的兼容性至关重要。正确的配置可确保模型能够以最佳效率准备好在预期的应用程序中进行部署。

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

调整这些参数可以自定义导出过程，以适应特定要求，例如部署环境、硬件限制和性能目标。选择适当的格式和设置对于在模型大小、速度和准确率之间取得最佳平衡至关重要。

导出格式#

可用的 YOLO26 导出格式见下表。你可以使用 format 参数导出为任何格式，即 format='onnx' 或 format='engine'。你可以直接对导出的模型进行预测或验证，即 yolo predict model=yolo26n.onnx。导出完成后，会为你的模型显示使用示例。模型也可以直接在浏览器中从 Ultralytics Platform 导出，无需任何本地设置。

格式format 参数模型元数据参数
PyTorch-yolo26n.pt✅-
TorchScripttorchscriptyolo26n.torchscript✅imgsz, quantize, dynamic, nms, batch, device
ONNXonnxyolo26n.onnx✅imgsz, quantize, dynamic, simplify, opset, nms, batch, data, fraction, device
OpenVINOopenvinoyolo26n_openvino_model/✅imgsz, quantize, dynamic, nms, batch, data, fraction, device
TensorRTengineyolo26n.engine✅imgsz, quantize, dynamic, simplify, opset, workspace, nms, batch, data, fraction, device
CoreMLcoremlyolo26n.mlpackage✅imgsz, dynamic, quantize, nms, batch, device
TF SavedModelsaved_modelyolo26n_saved_model/✅imgsz, keras, quantize, opset, nms, batch, data, fraction, device
TF GraphDefpbyolo26n.pb❌imgsz, opset, batch, device
TF Edge TPUedgetpuyolo26n_edgetpu.tflite✅imgsz, quantize, opset, data, fraction, device
PaddlePaddlepaddleyolo26n_paddle_model/✅imgsz, batch, device
MNNmnnyolo26n.mnn✅imgsz, batch, dynamic, quantize, simplify, opset, nms, device
NCNNncnnyolo26n_ncnn_model/✅imgsz, quantize, batch, device
IMX500imxyolo26n_imx_model/✅imgsz, quantize, data, fraction, nms, device
RKNNrknnyolo26n_rknn_model/✅imgsz, batch, name, quantize, simplify, opset, data, fraction, device
ExecuTorchexecutorchyolo26n_executorch_model/✅imgsz, batch, device
Axeleraaxelerayolo26n_axelera_model/✅imgsz, batch, quantize, data, fraction, device
DEEPXdeepxyolo26n_deepx_model/✅imgsz, quantize, simplify, opset, data, optimize, device
Qualcomm QNNqnnyolo26n_qnn.onnx✅imgsz, batch, name, quantize, simplify, opset, data, fraction, device
LiteRTlitertyolo26n.tflite✅imgsz, quantize, batch, data, fraction, device
Hailohailoyolo26n_hailo_model/✅imgsz, name, quantize, data, fraction, simplify, conf, iou
Huawei Ascendascendyolo26n_ascend_model/✅imgsz, batch, name, quantize, opset, simplify, nms

量化选项#

使用 quantize 参数请求导出精度。字符串值不区分大小写，Ultralytics 会在导出前对接受的别名进行规范化处理：

请求值规范化值含义
8, "8", "int8", "w8a8"8INT8 权重和激活
16, "16", "fp16", "w16a16"16FP16 权重和激活
32, "32", "fp32", "w32a32"32FP32 导出；与未设置时相同，但 CoreML NMS ML Programs 默认为 FP16
"w8a16""w8a16"INT8 权重和 16 位激活（FP16；LiteRT 上为 INT16）
"w8a32""w8a32"INT8 权重和 FP32 激活（LiteRT 动态 INT8，无需校准）

旧版的 half=True 和 int8=True 标志仍然被接受，但会带有弃用警告，并会转发至 quantize=16 和 quantize=8。

并非每个导出格式都支持所有精度。显式的 quantize 请求要么生成该精度，要么在导出前失败：

格式FP32（32 / 未设置）FP16（16）INT8（8）W8A16（"w8a16"）注意事项
PyTorch✅不适用不适用不适用原生训练/检查点格式。
TorchScript✅✅ 仅限 GPU❌❌FP16 TorchScript 导出需要 device=0；CPU 导出为 FP32。
ONNX✅✅✅❌INT8 使用 ONNX Runtime 静态量化和校准数据。
OpenVINO✅✅✅❌INT8 使用 NNCF 训练后量化。
TensorRT✅✅✅❌INT8 需要具有代表性的校准数据。
CoreML✅¹✅✅✅CoreML INT8 是权重量化；W8A16 使用 INT8 权重和 FP16 激活。¹未设置的 NMS ML Programs 默认为 FP16。
TF SavedModel✅❌✅❌INT8 导出使用 TensorFlow 校准。
TF GraphDef✅❌❌❌无导出时的精度转换。
Edge TPU❌❌✅ 自动❌Edge TPU 需要 INT8；未设置时会自动启用。
PaddlePaddle✅❌❌❌无导出时的精度转换。
MNN✅✅✅❌INT8 是通过 MNN 转换进行的权重量化。
NCNN✅✅❌❌移动端/嵌入式运行时格式。
IMX500❌❌✅ 自动✅IMX500 需要量化；未设置时会自动启用 INT8。
RKNN❌✅ 视芯片而定✅❌RK3588/RK3576/RK3566/RK3568/RK3562/RK2118/RV1126B 支持 FP16 或 INT8；RV1103/RV1106 变体仅支持 INT8。
ExecuTorch✅❌❌❌无导出时的精度转换。
Axelera❌❌✅ 自动❌Axelera 导出需要 INT8；未设置时会自动启用。
DEEPX❌❌✅ 自动❌DEEPX 导出需要 INT8；未设置时会自动启用。
Qualcomm QNN❌❌❌✅ 自动QNN HTP 导出固定为 INT8 权重和 16 位激活。
LiteRT✅❌✅✅静态 INT8（8）和 "w8a16"（int8 权重 + int16 激活）使用校准数据；还支持 "w8a32" 动态 INT8（无需校准）。quantize=16 不是单独的导出；FP32 模型在运行时通过 GPU 代理以 FP16 运行。
华为昇腾❌✅ 自动❌❌昇腾 AI 核心卷积仅接受 FP16/INT8 输入，因此 ATC 会编译 FP16；未设置时会自动启用。

对于 INT8 和 W8A16 导出，请使用 data 提供具有代表性的校准数据（例如 data="coco8.yaml"），除非目标集成文档中规定了默认或自动启用的行为。LiteRT "w8a32"（动态 INT8）方案不需要校准数据。

下一步#

寻找你的部署目标的集成指南——ONNX、TensorRT、CoreML 等均可在完整集成列表中找到——以了解如何运行导出的模型。

常见问题解答#

如何将 YOLO26 模型导出为 ONNX 格式？#

使用 Ultralytics 将 YOLO26 模型导出为 ONNX 格式非常简单。它提供了用于导出模型的 Python 和 CLI 方法。

示例
from ultralytics import YOLO

# Load a model
model = YOLO("yolo26n.pt")  # load an official model
model = YOLO("path/to/best.pt")  # load a custom-trained model

# Export the model
model.export(format="onnx")

有关该过程的更多详细信息（包括处理不同输入大小等高级选项），请参考 ONNX 集成指南。

使用 TensorRT 进行模型导出的好处是什么？#

使用 TensorRT 进行模型导出可带来显著的性能提升。导出为 TensorRT 的 YOLO26 模型可实现高达 5 倍的 GPU 加速，非常适合实时推理应用。

  • 多功能性： 针对特定硬件配置优化模型。
  • 速度： 通过高级优化实现更快的推理。
  • 兼容性： 与 NVIDIA 硬件无缝集成。

要了解有关集成 TensorRT 的更多信息，请参阅 TensorRT 集成指南。

在导出 YOLO26 模型时，如何启用 INT8 量化？#

INT8 量化是压缩模型和加速推理的绝佳方式，特别是在边缘设备上。以下是你如何启用 INT8 量化的方法：

示例
from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # Load a model
model.export(format="onnx", quantize=8, data="coco8.yaml")

INT8 量化可以应用于 ONNX、TensorRT、OpenVINO、CoreML 和 Rockchip RKNN 等格式。为了获得最佳量化效果，请使用 data 参数提供一个具有代表性的 dataset。有关接受的 quantize 值和支持的格式，请参阅量化选项。

为什么导出模型时动态输入大小很重要？#

动态输入大小允许导出的模型处理不同的图像尺寸，从而为不同的用例提供灵活性并优化处理效率。当导出到 ONNX 或 TensorRT 等格式时，启用动态输入大小可确保模型能够无缝适应不同的输入形状。

要启用此功能，请在导出期间使用 dynamic=True 标志：

示例
from ultralytics import YOLO

model = YOLO("yolo26n.pt")
model.export(format="onnx", dynamic=True)

动态输入大小对于输入尺寸可能会变化的应用程序特别有用，例如视频处理或处理来自不同来源的图像时。

优化模型性能时需要考虑哪些关键导出参数？#

理解和配置导出参数对于优化模型性能至关重要：

  • format: 导出模型的目标格式（例如 onnx、torchscript、tensorflow）。
  • imgsz: 模型输入的期望图像大小（例如 640 或 (height, width)）。
  • quantize: 量化精度，例如 8/"int8"、16/"fp16"、32/"fp32"，或者在受支持的格式上的混合权重/激活方案 "w8a16" 和 "w8a32"（LiteRT 动态 INT8）。请参阅量化选项。
  • optimize: 为 DEEPX 导出启用更高的编译器优化。

对于在特定硬件平台上的部署，请考虑使用专门的导出格式，例如用于 NVIDIA GPU 的 TensorRT、用于 Apple 设备的 CoreML 或用于 Google Coral 设备的 Edge TPU。

导出的 YOLO 模型中的输出张量代表什么？#

当你将 YOLO 模型导出为 ONNX 或 TensorRT 等格式时，输出张量结构取决于模型任务。理解这些输出对于自定义推理实现很重要。

对于 YOLO26 检测模型（例如 yolo26n.pt），支持该功能的格式默认启用端到端导出，因此输出形状类似于 (batch_size, max_detections, 6)，并带有 [x1, y1, x2, y2, confidence, class_id] 值。在默认的 max_det=300 下，这通常是 (batch_size, 300, 6)。当不支持端到端算子时，某些受限制的格式会自动回退到传统的输出布局。

对于非端到端检测模型，或使用 end2end=False 导出的 YOLO26 模型，输出通常是形状类似于 (batch_size, 4 + num_classes, num_predictions) 的单个张量，其中通道表示框坐标加上每个类别的得分，而 num_predictions 取决于导出输入分辨率（并且可以是动态的）。

对于分割模型（例如 yolo26n-seg.pt），你通常会得到两个输出：形状类似于 (batch_size, 4 + num_classes + mask_dim, num_predictions) 的第一个张量（包含框、类别得分和掩码系数），以及形状类似于 (batch_size, mask_dim, proto_h, proto_w) 的第二个张量，其中包含与系数配合使用以生成实例掩码的掩码原型。大小取决于导出输入分辨率（并且可以是动态的）。

对于姿态模型（例如 yolo26n-pose.pt），输出张量的形状通常类似于 (batch_size, 4 + num_classes + keypoint_dims, num_predictions)，其中 keypoint_dims 取决于姿态规范（例如关键点数量以及是否包含置信度），而 num_predictions 取决于导出输入分辨率（并且可以是动态的）。

ONNX 推理示例中的示例演示了如何针对每种模型类型处理这些输出。

是否有官方的 Ultralytics C++ 推理 API？#

Ultralytics 目前不提供专为 YOLO 模型设计的 C++ 推理 API。对于 C++ 部署，请将模型 导出为运行时格式，例如 ONNX、TensorRT、 TorchScript 或 MNN，然后使用 该运行时的原生 C++ API 加载导出的构件。

例如，使用 yolo export model=yolo26n.pt format=onnx 导出检测模型并运行 .onnx 文件与 ONNX Runtime C++，或者使用 format=engine 导出并从 TensorRT C++ 应用程序运行 TensorRT 引擎。当你 使用自定义 C++ 后处理时，请匹配你的任务和导出设置的输出张量布局；YOLO26 端到端 检测导出通常返回 (batch, max_det, 6)，而非端到端导出返回需要外部后处理的原始预测张量。

为什么使用 end2end=True 导出量化模型时，output0 仍然是 FP32？#

当使用 quantize=16（FP16）或 quantize=8（INT8）导出时，大多数张量会转换为较低精度以减小模型大小并提高性能。但是，当启用 end2end=True 时，后处理（包括类别索引）将直接嵌入到导出的图中。

output0 张量包含类别索引，它们在内部表示为浮点值。由于尾数精度有限，FP16 无法可靠地表示大于 2048 的整数值。为了避免潜在的精度损失或错误的类别 ID，output0 有意保持为 FP32。

此行为是预期的，也适用于必须保持类索引保真度的低精度或量化导出。

如果需要完整的 FP16 输出，请使用 end2end=False 进行导出并在外部执行后处理。

贡献者
GLglenn-jocher31RAraimbekovm4BUBurhan-Q4AMambitious-octopus3Y-Y-T-G2RIRizwanMunawar2KAKayzwer2OAoaslananka1ONonuralpszr1SHShreyas-S-8091PDpderrenger1JKjk4e1MAMatthewNoyce1

评论