使用 Ultralytics YOLO 导出模型#

使用 Ultralytics 将 YOLO26 模型导出为 ONNX 格式非常简单。你可以通过 Python 或 CLI 导出模型。

from ultralytics import YOLO

# 加载模型
model = YOLO("yolo26n.pt")  # 加载官方模型
model = YOLO("path/to/best.pt")  # 加载自定义训练的模型

# 导出模型
model.export(format="onnx")

如需了解有关此流程的更多详情，包括处理不同输入尺寸等高级选项，请参阅 ONNX 集成指南。

使用 TensorRT 导出模型可以显著提升性能。导出为 TensorRT 的 YOLO26 模型可实现最高 5 倍的 GPU 加速，因此非常适合实时推理应用。

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

如需详细了解如何集成 TensorRT，请参阅 TensorRT 集成指南。

INT8 量化是压缩模型并加快推理速度的好方法，尤其适用于边缘设备。启用 INT8 量化的方法如下：

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # 加载模型
model.export(format="onnx", quantize=8, data="coco8.yaml")

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

动态输入尺寸使导出的模型能够处理不同的图像尺寸，从而提升灵活性，并针对不同用例优化处理效率。导出为 ONNX 或 TensorRT 等格式时，启用动态输入尺寸可确保模型能够无缝适配不同的输入形状。

导出时使用 dynamic=True 标志即可启用此功能：

from ultralytics import YOLO

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

动态输入尺寸特别适用于输入尺寸可能变化的应用，例如视频处理，或处理来自不同来源的图像。

PyTorch 模型和动态导出默认使用最小矩形填充，而静态导出会填充到完整的 imgsz，因此置信度阈值附近的检测结果可能不同。若要匹配静态导出，请使用 rect=False 进行原生推理；也可以在支持的情况下使用 dynamic=True 导出。

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

• format: 导出模型的目标格式（例如 onnx、torchscript、saved_model）。
• imgsz: 模型输入所需的图像尺寸（例如 640 或 (height, width)）。
• quantize: 量化精度，例如 8/"int8"、16/"fp16"、32/"fp32"，或支持格式中的混合权重/激活值方案 "w8a16" 和 "w8a32"（LiteRT 动态 INT8）。请参阅量化选项。
• dynamic: 在支持动态形状的格式（如 ONNX、OpenVINO 和 TensorRT）中接受可变输入尺寸。
• nms: 用于选择原始输出（外部 NMS，None）、内嵌 NMS（True）或无 NMS 检测头（False）。
• device: 导出期间用于追踪模型的设备，例如用于第一块 CUDA GPU 的 cpu 或 0；FP16 TorchScript 需要 GPU。

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

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

对于使用 nms=False 导出的 YOLO26 检测模型（例如 yolo26n.pt），受支持的格式会生成无 NMS 输出，其形状类似 (batch_size, max_detections, 6)，包含 [x1, y1, x2, y2, confidence, class_id] 个值。使用默认的 max_det=300 时，这通常是 (batch_size, 300, 6)。某些受限格式在不支持端到端算子时，会自动回退到传统输出布局。

默认情况下（nms=None），包括 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 目前不为 YOLO 模型提供专用的 C++ 推理 API。对于 C++ 部署，请将模型导出为 ONNX、TensorRT、TorchScript 或 MNN 等运行时格式，然后使用相应运行时的原生 C++ API 加载导出的模型文件。

例如，使用 yolo export model=yolo26n.pt format=onnx 导出检测模型，然后通过 ONNX Runtime C++ 运行 .onnx 文件；或者使用 format=engine 导出，再从 TensorRT C++ 应用运行 TensorRT 引擎。使用自定义 C++ 后处理时，请确保输出张量布局与你的任务和导出设置相匹配；默认的 YOLO26 检测导出会返回需要外部 NMS 处理的原始预测张量。使用 nms=False 导出无 NMS 检测结果，其形状为 (batch, max_det, 6)；或者使用 nms=True 在受支持的格式中嵌入 NMS。

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

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

如果需要完整的 FP16 输出，请在 GPU 上使用 nms=None 导出，并在外部执行后处理。无论如何，CPU 上的 FP16 ONNX 导出都会保留 FP32 输入和输出，仅转换内部计算图。