yolo-export

导出、量化与部署

最快捷径：在 Platform 中导出

打开已完成模型的 Export 选项卡，选择格式、配置参数，然后点击 Start Export。Platform 会直接运行 CPU 导出；对于需要 GPU 的格式（尤其是 TensorRT），则会要求选择目标 GPU。任务完成后即可下载产物。对于 TensorRT，请选择部署设备的 GPU 系列或 Jetson 目标；如果其 TensorRT/CUDA 版本与设备上的版本不同，请改为在该设备上本地导出。

如果不想在本地安装每种导出工具链，请使用 Platform。需要自定义校准、可重复的自动化、本地硬件构建或立即进行一致性验证时，请使用下方的 Python/CLI 路径。请参阅 Platform 模型导出。

快速入门

from ultralytics import YOLO

model = YOLO("runs/detect/train/weights/best.pt")
path = model.export(format="onnx")  # returns the exported file/dir path

yolo export model=best.pt format=onnx

导出的模型可直接重新载入 YOLO()，用于 predict/val——API 保持不变：

model = YOLO("best.onnx")  # or best.engine, best_openvino_model/, ...

根据目标硬件选择格式

目标	format=	原因
NVIDIA GPU / Jetson	engine（TensorRT）	在 NVIDIA 上速度最快；在部署设备上构建——引擎无法跨 GPU/TRT 版本移植
Intel CPU/iGPU/NPU	openvino	Intel CPU 速度最高可提升 3×
Apple iOS/macOS	coreml	操作系统覆盖面广，支持 Vision/iOS/Flutter
Apple iOS 27+/macOS 27+	coreai	原生 .aimodel；iOS/Flutter SDK 默认使用 coreml；在 Apple 芯片 macOS 26+ 或 x86_64 Linux 上导出
Android	litert（由 tflite 更名而来）或 ncnn	NCNN 在 ARM 上表现出色
Raspberry Pi	ncnn	ARM CPU 延迟最低
PyTorch Edge	executorch
跨平台 / 不确定	onnx	可在任何平台运行；从这里开始，在延迟要求较高时再进行专项优化
NPU（Rockchip/Qualcomm/Hailo/Huawei/Sony/Axelera/DeepX/AMD）	rknn / qnn / hailo / ascend / imx / axelera / deepx / xilinx	name= 用于为 rknn/qnn/hailo/ascend/xilinx 选择具体芯片

包含 22 种目标的完整本地导出矩阵及各格式支持的参数：format-matrix.md（本文件夹）。

关键参数

参数	默认值	说明
imgsz	model	继承自已加载的模型；请显式设置为部署所用的尺寸
quantize	None	精度选项：16/fp16、8/int8/w8a8、w8a16、w8a32 或 32/fp32；支持情况、速度、大小和精度取决于后端 — 参见 format-matrix.md 并在目标设备上进行基准测试
data	None	按需提供具有代表性的校准数据；通常使用 >300 张图像，TensorRT 则使用 500+ 张。若省略，将使用少量任务默认数据，因此请显式传入具有部署代表性的数据
dynamic	False	支持时使用可变输入尺寸/批次；参见 format-matrix.md 并在目标设备上进行基准测试
batch	1	导出时固化的最大批次
simplify	True	简化 ONNX 图
opset	None	未设置时自动选择兼容的 ONNX opset；若使用方运行时报告问题，请指定较低版本
nms	None	None 导出原始输出，供外部 NMS 使用（YOLO26 也如此）；True 在 format-matrix.md 列出 nms 的格式中嵌入 NMS；False 选择 YOLO26/YOLOv10 的无 NMS 检测头，否则输出原始结果
workspace	None	TensorRT 构建器的 GiB 内存；若构建时内存溢出（OOM），请调低
device	None	TensorRT 需要 GPU（未设置时自动设为 device=0）；GPU 也能加速 INT8 校准
fraction	1.0	使用的校准数据比例

导出后验证一致性（务必执行）

yolo val model=best.pt data=data.yaml   # baseline
yolo val model=best.onnx data=data.yaml # compare the same task metric with the baseline

可接受的差异取决于任务、模型、后端、精度和校准数据。若发现意外差距，请统一 imgsz 和预处理/后处理设置；必要时使用具有代表性的校准数据进行排查。另请使用 .pt 对比一次预测结果。

对所有格式进行实测基准测试

yolo benchmark model=best.pt data=data.yaml imgsz=640                                    # all formats at default precision
yolo benchmark model=best.pt data=data.yaml format=engine quantize=16 device=0 imgsz=640 # targeted FP16

在此机器上生成每种可导出格式的任务指标和延迟。对每种受支持的精度重复测试，并在部署硬件上进行基准测试，而不是在开发机上。

在 Python 之外使用导出模型

• 在原生运行环境（C++、移动端、JS）中，预处理（letterbox 调整大小、BGR→RGB、/255）和输出解码都由你负责。
• 检测输出布局遵循 nms：默认的 nms=None 会为所有模型（包括 YOLO26）输出原始 [4+nc, anchors] 检测头（xywh 框 + 类别分数），因此需要运行 NMS（而 imx 始终会内嵌 NMS）。YOLO26/YOLOv10 中的 nms=False 会输出无需 NMS 的 [max_det, 6] 行 [x1,y1,x2,y2,conf,cls]；支持的格式中，nms=True 会内嵌 NMS，并采用相同的行布局；某些格式会回退为原始检测头（format-matrix.md）。分割、姿态和 OBB 还会添加特定任务的输出。请检查导出警告和形状。
• 支持的格式会在导出元数据中附带类别名称；否则，请将 names 映射与模型一同提供。
• 服务部署：Triton 使用 ultralytics.utils.triton.TritonRemoteModel；ultralytics 仓库中的 examples/ 提供 ONNXRuntime C++/Rust/Python 参考示例。

故障排除

症状	解决方法
因缺少软件包导致导出崩溃	大多数后端会在首次导出时自动安装；请重试。在 Linux 上，TensorRT 会自动安装为 tensorrt-cu<torch CUDA major>；其他平台请按照 NVIDIA 文档安装。Hailo（Dataflow Compiler）和 Ascend（CANN atc）需要先安装其供应商 SDK
下游出现 Unsupported ONNX opset	使用较低的 opset= 导出，或升级运行时
TensorRT 构建内存溢出/速度慢	降低 workspace，设置 batch=1、dynamic=False
导出模型的精度明显降低	imgsz 不匹配；校准数据太少或缺乏代表性；自定义预处理/后处理不正确；请使用受支持的更高精度或后端
Engine 在另一台机器上运行失败	TensorRT engine 与设备和版本相关，需在目标设备上重新构建
CoreML 导出在 Windows 上失败	在 macOS 或 Linux 上导出
Core AI 导出不可用	需要 macOS 26+（Apple silicon 或 x86_64 Linux（glibc 2.34+））、torch>=2.8 和 Python 3.11–3.14；如需更广泛的生产环境支持，请使用 CoreML
half/int8/end2end/tflite 出现弃用警告	会自动转发（half→quantize=16、int8→quantize=8、end2end=True→nms=False、end2end=False→nms=None，除非同时传入 nms=True、tflite→litert）——请改用新名称

相关页面

• format-matrix.md — 全部 22 种本地导出目标、生成的产物及支持的参数。使用 onnx/engine/openvino/coreml 以外的格式时请阅读此文件。

如果已安装的版本拒绝某个参数，请以错误文本（格式和量化错误会列出有效值）和 yolo cfg 为准，不要依赖此文件。