企业官网建设流程全解析

Ultralytics YOLO26 模型导出实战指南：Export 模式详解与 ONNX / TensorRT / CoreML 等多格式部署

【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics

模型训练的终点是部署。Ultralytics 的Export（导出）模式允许把训练好的 PyTorch 权重一次性转换为 ONNX、TensorRT、CoreML、OpenVINO、LiteRT 等二十余种运行格式，让同一份模型能够跑在不同的硬件与推理框架上。本文以仓库文档 docs/en/modes/export.md 为主体，结合 ultralytics/engine/exporter.py 的源码实现，系统讲解导出参数、量化精度、格式选型与常见问题，帮助你把 YOLO26 模型稳定地送上目标部署环境。

一、什么是 Export 模式：为何需要导出模型

训练产出的best.pt是 PyTorch 原生格式，直接用它推理固然可行，但真实产品往往需要更快的推理速度、更小的模型体积、更强的算子优化或对特定硬件的适配——这就要通过 Export 模式把模型"翻译"成目标运行时能直接加载的中间表示或引擎文件。

在 Ultralytics 中，导出是六大模式（train / val / predict /export/ track / benchmark）之一。核心入口非常简单：

• Python：model.export(format=...)
• CLI：yolo export model=... format=...

导出动作完成后，Ultralytics 会打印该格式的后续使用示例（如yolo predict model=yolo26n.onnx），导出的产物可以直接用于predict或val，例如yolo predict model=yolo26n.onnx。这意味着同一个推理链路上，只要换一个model=路径，就能无缝切换到导出的运行时后端。甚至无需任何本地环境，也可以在 Ultralytics Platform 的浏览器中直接完成导出（参见 docs/en/platform/train/models.md 中的 Export Model 说明）。

选择导出格式的收益

原文档给出的性能指引在仓库与集成文档中保持一致：

• 导出为 ONNX 或 OpenVINO，在CPU上可获得最高约3 倍的推理加速；
• 导出为 TensorRT，在NVIDIA GPU上可获得最高约5 倍的推理加速。

Export 模式的突出能力

• 一键导出：Python / CLI 各一条命令即可切换目标格式；
• 批处理能力：可通过batch参数导出支持批量推理的模型；
• 推理优化：产物针对目标运行时做了算子级优化（如 ONNX 图简化、TensorRT 引擎构建）；
• 广泛兼容：覆盖从云端 GPU 到移动端、NPU、边缘设备的多种软硬件环境。

从源码结构看，ultralytics/engine/exporter.py 中的Exporter类（exporter.py#L508-L558）把「参数校验 → 设备选择 → 模型预处理 → 逐格式导出 → 结果检查」封装成一个完整的流水线，每个目标格式都对应独立的export_xxx()方法，全部通过@try_export装饰器包裹（exporter.py#L485-L505）——导出成功时输出耗时与产物体积，导出失败则抛出明确错误，同时会断言产物文件大于 0.1 MB，防止生成损坏或算子不支持的模型。

二、快速开始：导出你的第一个模型

以官方 YOLO26n 权重或自定义训练权重为例：

=== "Python"

```python from ultralytics import YOLO # 加载模型 model = YOLO("yolo26n.pt") # 加载官方模型 model = YOLO("path/to/best.pt") # 加载自定义训练模型 # 导出模型 model.export(format="onnx") ```

=== "CLI"

```bash yolo export model=yolo26n.pt format=onnx # 导出官方模型 yolo export model=path/to/best.pt format=onnx # 导出自定义训练模型 ```

前置条件：若此前仅安装了基础包，需要补充导出相关依赖，可执行pip install "ultralytics[export]"。这一点也在 exporter.py 顶部的模块 docstring 中有明确标注。

导出到不同格式时，目标产物命名遵循统一规则（以 YOLO26 为例，参考 exporter.py#L146-L277 中export_formats()的Suffix列）：

源码中的格式别名与兼容处理

Exporter.__call__（exporter.py#L572-L603）会自动规范化format参数：tensorrt/trt归一到engine，mlmodel/mlpackage/mlprogram/apple/ios归一到coreml，huawei/cann/om归一到ascend；而历史遗留的tflite/tfjs参数自 8.4.83 起被统一为 Google LiteRT 导出（litert）并输出弃用警告。若传入完全无法识别的格式，源码会尝试用difflib匹配最相近的合法格式，否则直接抛出 "Invalid export format" 错误。此外，format='engine'（TensorRT）必须依赖 GPU，源码在未指定设备时会自动分配device=0。

三、导出参数全解

3.1 参数总表

下列参数控制导出的目标格式、输入尺寸、量化精度与部署行为（继承并展开自 docs/macros/export-args.md，其中多数默认值可在 ultralytics/cfg/default.yaml 的 Export settings 段核对）：

3.2 关键参数背后的源码逻辑

• 参数-格式匹配校验：validate_args（exporter.py#L447-L482）会先取export_formats()中该格式允许的参数集合，再比对实际传入值。若某个参数对该格式无效（如给 PaddlePaddle 传dynamic），导出会直接以ERROR ❌️ argument '...' is not supported for format='...'中止，而不是等导出失败后才暴露问题。这是保证「导出的每一步都可预期」的重要防线。
• 量化前置校验：validate_args同时按第四节精度矩阵拦截不支持的组合，例如quantize=16（FP16）用于不在 FP16 支持集内的格式时会立即报错并提示该格式可用的精度选项。
• 输入形状：self.imgsz = check_imgsz(...)保证输入尺寸对齐模型 stride；随后用torch.zeros(batch, channels, *imgsz)构造虚拟输入做两次 dry-run 前向，拿到真实输出形状output_shape后再进入逐格式导出（exporter.py#L717、L846、L916-L930）。
• 模型预处理：导出前会对模型做deepcopy、冻结参数（requires_grad=False）、切到eval、float并对 Conv-BN 做fuse()（exporter.py#L854-L859）；对 Detect 系列头会按当前imgsz把max_det夹紧到可用 anchor 数量之内，保证 TensorRT 兼容性。
• 硬件目标自动选择：源码为需要name的格式提供默认值——RKNN 默认rk3588并校验RKNN_CHIPS，RV1103/RV1106 等低端芯片强制 INT8；Ascend 默认Ascend310B4（合法值取决于本机安装的 CANN 内核包）；QNN 默认73（Snapdragon 8 Gen 2）并接受v73等别名（exporter.py#L720-L772）。
• 端到端分支自动回退：对不支持 top-k 算子的格式（RKNN、NCNN、ExecuTorch、Paddle、IMX、Edge TPU、QNN），以及 LiteRT INT8 静态量化场景，源码会自动关闭 end2end 分支并警告（exporter.py#L678-L688）；TensorRT < 8.5.0 因缺少 Mod 算子同样会回退。

四、支持的导出格式与各自参数

下表整理了 YOLO26 支持的全部导出格式。任何格式都可以直接作为predict或val的model=输入，例如yolo predict model=yolo26n.onnx；导出成功后在终端会给出对应的用法示例。

上表依据 docs/macros/export-table.md 渲染，并与源码export_formats()（exporter.py#L146-L277）中每个格式注册的Arguments列表一一对应——这正是validate_args校验合法参数的数据来源。几点补充：

• IMX500 格式目前仅支持 YOLOv8n、YOLO11n 模型；
• 大部分格式会携带模型元数据（描述、作者、版本、stride、task、imgsz、names、导出参数等），构建于 exporter.py#L934-L950，后续被写入 ONNX custom metadata、OpenVINOmetadata.yaml或 TFLite 元数据中；
• 表格中"元数据"标记为 ❌ 的 TF GraphDef 格式不做导出期精度转换，也无法保存元数据。

五、量化精度：用quantize精确控制导出精度

quantize参数用于显式请求导出精度。字符串值大小写不敏感，Ultralytics 在导出前会把别名统一规范化：

历史遗留的half=True、int8=True仍然会被接受，但会伴随弃用警告，并分别转发为quantize=16与quantize=8。

5.1 各格式精度支持矩阵

并非每种格式都支持每种精度。显式传入不支持的quantize请求，要么按该格式产生目标精度，要么在导出前直接失败：

5.2 校准数据与源码级约束

对于 INT8 与 W8A16 导出，需要借助data提供代表性校准数据，例如data="coco8.yaml"，除非目标集成文档声明了默认或自动启用行为。LiteRT 的"w8a32"（动态 INT8）方案则无需校准数据。

从源码看，这一整套约束由三处协作实现：

• 支持集常量：FP16_FORMATS、INT8_FORMATS、W8A16_FORMATS、W8A32_FORMATS与FP32_UNSUPPORTED_FORMATS定义了每个精度对应的格式白名单（exporter.py#L400-L444）；
• validate_args校验：逐一分发16/8/"w8a16"/"w8a32"/32分支断言，不符合即报错并列出该格式可用的quantize选项（exporter.py#L464-L478）；
• 自动行为兜底：Edge TPU / IMX / Axelera / DEEPX / QNN / Hailo / Ascend 这类强制量化格式会在未设置时自动启用 INT8（QNN 为 W8A16、Ascend 为 FP16），并对缺失的data回退到任务默认校准集（exporter.py#L624-L634、L831-L835）。

5.3 实操示例：INT8 量化导出

=== "Python"

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

=== "CLI"

```bash yolo export model=yolo26n.pt format=onnx quantize=8 data=coco8.yaml # 导出带 INT8 量化的 ONNX ```

INT8 量化适用于 ONNX、TensorRT、OpenVINO、CoreML、Rockchip RKNN 等格式。为取得最优量化效果，建议用data参数指定一个有代表性的数据集。

六、导出模型的输出张量结构

把 YOLO 导出到 ONNX / TensorRT 等格式后，输出张量结构与任务类型、导出设置强相关。这对自定义推理实现尤为重要（在 exporter.py#L926-L930 中output_shape会被打印出来，便于核对）。

检测模型（如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取决于导出输入分辨率（可动态）。哪些格式保留端到端输出，参见 End-to-End Detection 指南。

分割模型（如yolo26n-seg.pt）

通常返回两个输出：第一个张量形状为(batch_size, 4 + num_classes + mask_dim, num_predictions)（框、类别分数与 mask 系数），第二个张量形状为(batch_size, mask_dim, proto_h, proto_w)（mask 原型，配合系数生成实例 mask）。尺寸取决于导出输入分辨率（可动态）。

姿态模型（如yolo26n-pose.pt）

输出张量形状通常为(batch_size, 4 + num_classes + keypoint_dims, num_predictions)，其中keypoint_dims取决于姿态规格（关键点数量、是否包含置信度），num_predictions同样取决于导出输入分辨率（可动态）。

若需要处理这些输出的逐语言示例，仓库的 examples 目录（examples）与各集成文档提供了多语言实现供参考。

七、常见问题（FAQ）

7.1 如何把 YOLO26 导出为 ONNX？

直接使用 Python 或 CLI 即可：

=== "Python"

```python from ultralytics import YOLO # 加载模型 model = YOLO("yolo26n.pt") # 加载官方模型 model = YOLO("path/to/best.pt") # 加载自定义训练模型 # 导出模型 model.export(format="onnx") ```

=== "CLI"

```bash yolo export model=yolo26n.pt format=onnx # 导出官方模型 yolo export model=path/to/best.pt format=onnx # 导出自定义训练模型 ```

涉及不同输入尺寸等进阶选项时，参考 ONNX 集成指南。

7.2 使用 TensorRT 导出有哪些收益？

导出为 TensorRT 能带来显著的性能提升：YOLO26 导出到 TensorRT 可获得最高约 5 倍的 GPU 推理加速，适合实时推理应用。

• 硬件针对性：为特定 NVIDIA 硬件定制优化；
• 速度：借助深度算子优化获得更快推理；
• 兼容性：与 NVIDIA 生态无缝集成。

具体集成方式参见 TensorRT 集成指南。

7.3 端到端模型（end2end）导出说明

YOLO26 与 YOLOv10 支持无 NMS 的端到端推理。默认情况下，在支持的格式中端到端导出自动启用。如果需要兼容传统的 NMS 后处理管线，可显式传入end2end=False；而 RKNN / NCNN / ExecuTorch / Paddle / IMX / Edge TPU / QNN 等不支持 top-k 算子的格式会强制回退为非端到端，LiteRT 的 INT8 静态量化同样会关闭端到端分支。详见 docs/en/guides/end2end-detection.md。

7.4 动态输入尺寸为何重要？如何开启？

动态输入尺寸允许导出模型处理任意分辨率的图像，在视频流处理、多来源图像等输入维度不固定的场景尤为有用。对 ONNX、TensorRT、CoreML、OpenVINO、TorchScript 等格式，使用dynamic=True即可：

=== "Python"

```python from ultralytics import YOLO model = YOLO("yolo26n.pt") model.export(format="onnx", dynamic=True) ```

=== "CLI"

```bash yolo export model=yolo26n.pt format=onnx dynamic=True ```

注意结合第三节表格约束：例如 CoreML 的dynamic=True与nms=True互斥、不支持分类与 RT-DETR 模型；MNN 不支持dynamic=True与nms=True同时开启；CoreMLbatch>1也要求开启dynamic。这些互斥约束均在源码 exporter.py#L789-L813 中有显式断言。

7.5 官方是否有 C++ 推理 API？

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++ 应用中加载引擎文件。使用自定义 C++ 后处理时，必须匹配任务与导出设置对应的输出布局：YOLO26 端到端检测导出通常返回(batch, max_det, 6)，而非端到端导出返回需要外部后处理的原始预测张量。

7.6 量化模型开启end2end=True后为何output0仍是 FP32？

当quantize=16（FP16）或quantize=8（INT8）时，绝大多数张量会被降为低精度以减小体积、提升性能。但end2end=True会把后处理（包括类别索引）直接嵌入导出计算图，而output0中的类别索引在内部以浮点表示——FP16 因尾数精度有限无法可靠表示 2048 以上的整数值。为避免精度损失或类别 ID 出错，output0会被刻意保留为 FP32。这是预期行为，同样适用于其它低精度/量化导出。若确需全 FP16 输出，请以end2end=False导出并在外部完成后处理。

八、部署的下一步

导出只是部署的第一步。找到目标运行时的集成文档（ONNX、TensorRT、CoreML 等，完整列表见 integrations 索引），即可按其中的加载与推理示例把导出产物跑起来。仓库内针对各导出格式的冒烟测试集中在 tests/test_exports.py，是查阅「某个格式参数组合是否被 CI 覆盖」的第一手材料；Exporter类的完整字段与逐格式导出方法清单可继续阅读 ultralytics/engine/exporter.py。

一句话总结选型策略：CPU 部署优先考虑 ONNX/OpenVINO，NVIDIA GPU 实时应用优先 TensorRT，Apple 生态用 CoreML，移动/嵌入式端看 NCNN/LiteRT，NPU 与专用加速卡（RKNN、QNN、Ascend、Hailo、Edge TPU、Axelera、DEEPX、IMX500）再按硬件逐一匹配——所有选项都只是同一个model.export(format=...)参数的不同取值而已。

【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics