1. 模型导出 ONNX 的整体思路与方案选型1.1 为什么要在 Phase A 的第三步做 ONNX 导出做过模型部署的人都有一个共识训练框架和推理框架之间天然存在一道鸿沟。你在 PyTorch 里训练出来的权重直接拿到生产环境去跑往往会遇到依赖臃肿、启动慢、跨平台困难等一系列问题。ONNXOpen Neural Network Exchange就是为解决这个问题而生的中间表示格式它把模型的计算图用一套与框架无关的标准描述出来让下游的推理引擎、硬件加速器都能读懂。在 Phase A 的流程里Step 3 被安排成“模型导出 ONNX”这个位置是有讲究的。Step 1 通常是环境搭建和依赖安装Step 2 是模型训练或权重准备到了 Step 3模型已经具备了可用的权重接下来就要为部署做准备。ONNX 导出是承上启下的关键一步往上它承接训练产出的.pt权重往下它可以继续转成 ATC 需要的格式、量化成 int8、或者转成 kmodel 部署到边缘设备。所以这一步做得好不好直接决定了后面整条部署链路顺不顺。我个人的经验是ONNX 导出看起来只是调一个export函数但真正踩坑的地方非常多——opset 版本选错、动态轴没设对、输出节点名字对不上、算子不支持等等。这篇文章就把这些细节全部拆开讲清楚。1.2 导出方案的核心考量opset、动态轴与简化导出 ONNX 时有三个参数是必须想清楚的它们直接决定了导出的模型能不能用、好不好用。第一是 opset 版本。opset 是 ONNX 算子集的版本号不同版本支持的算子不一样。选低了某些新算子表达不出来选高了下游推理引擎可能还不支持。以 Ultralytics 的 YOLO 系列为例官方默认用的是 opset 12 到 17 之间的版本实测下来 opset 12 兼容性最好绝大多数推理引擎都能吃。如果你要用一些较新的算子比如某些注意力机制里的操作可能得往上提到 16 或 17。我的建议是先按官方默认值导出跑通了再根据下游需求调整不要一上来就追求最新版本。第二是动态轴dynamic axes。这个参数决定了导出的模型能不能接受可变尺寸的输入。如果你固定了 batch size 和图像尺寸导出的模型就只能跑那一种输入换个分辨率就报错。实际部署中输入尺寸经常是变化的所以一般会把 batch 维度和空间维度都设成动态。但要注意动态轴设多了会拖慢推理速度因为推理引擎没法做针对性的图优化。所以这里有个权衡如果确定输入尺寸固定就别开动态轴性能更好。第三是模型简化simplify。PyTorch 导出的 ONNX 图里经常有一些冗余节点比如多余的 Transpose、Reshape、Cast 等这些节点不影响结果但会增加推理开销。用onnx-simplifier工具可以把这些冗余节点合并掉导出的模型更干净、推理更快。这一步不是必须的但强烈建议做尤其是要部署到算力有限的边缘设备时。1.3 不同模型类型的导出差异虽然标题说的是通用的“模型导出 ONNX”但不同类型的模型导出时关注点完全不同这里简单分个类。目标检测模型比如 YOLO 系列导出时最需要注意的是输出节点的结构。YOLO 的输出通常是多个尺度的特征图导出后要确认输出张量的形状和顺序跟推理代码里的解析逻辑对得上。另外NMS非极大值抑制是在模型内做还是模型外做也要提前决定——放在模型内会让 ONNX 图变复杂放在模型外则推理代码要多写一点。TTS语音合成模型导出时难点在于模型往往包含动态控制流比如根据输入长度决定循环次数。这类模型导出 ONNX 时容易遇到算子不支持的问题可能需要改写模型结构或者用自定义算子。Sherpa ONNX 这类项目就是专门为 TTS 模型提供 ONNX 推理支持的它内部对模型结构有特定要求。量化模型int8导出时通常不是直接导出 int8 的 ONNX而是先导出 fp32 的 ONNX再用量化工具做训练后量化PTQ。量化过程中需要校准数据集校准集的质量直接影响量化后的精度损失。2. 核心细节解析与实操要点2.1 环境准备Ultralytics 安装与依赖确认导出 ONNX 之前环境必须干净且版本匹配。以 Ultralytics 为例安装本身不复杂但版本冲突是高频问题。pip install ultralytics onnx onnxruntime onnxsim这行命令看起来简单但实际执行时经常遇到could not find a version that satisfies the requirement ultralytics这类报错。原因通常是 Python 版本太老或者 pip 源里没有对应版本的包。解决办法是先确认 Python 版本在 3.8 以上然后换个源重试pip install ultralytics -i https://pypi.tuna.tsinghua.edu.cn/simple安装完成后务必验证一下关键库的版本import torch import ultralytics import onnx import onnxruntime print(torch:, torch.__version__) print(ultralytics:, ultralytics.__version__) print(onnx:, onnx.__version__) print(onnxruntime:, onnxruntime.__version__)这里有个经验onnx和onnxruntime的版本要匹配否则加载模型时可能报Unsupported model IR version之类的错误。一般来说onnxruntime 的版本要大于等于 onnx 的版本。如果发现不匹配优先升级 onnxruntime。注意不要在一个环境里同时装多个深度学习框架的 GPU 版本CUDA 版本冲突会让你排查到怀疑人生。导出 ONNX 其实用 CPU 就够了不需要 GPU。2.2 导出参数详解从 imgsz 到 dynamicUltralytics 的导出接口设计得很简洁一个export方法搞定但里面的参数每一个都有讲究。下面这张表是我实际使用中总结的关键参数说明参数含义推荐值注意事项format导出格式onnx也可以是 torchscript、openvino 等imgsz输入图像尺寸640必须是 32 的倍数否则某些算子会报错opset算子集版本12兼容性最好需要新算子时再往上调dynamic是否动态轴False输入尺寸固定时设 False性能更好simplify是否简化True强烈建议开启减少冗余节点half是否半精度False导出 fp16 需要 GPU 支持CPU 推理可能不支持batchbatch size1部署时通常 batch1训练时才用大 batch导出命令可以写成一行from ultralytics import YOLO model YOLO(yolo11n.pt) model.export(formatonnx, imgsz640, opset12, simplifyTrue, dynamicFalse)执行后会在权重文件同目录下生成一个.onnx文件。如果开了simplifyTrue还会额外生成一个-simplified.onnx文件部署时用简化版。这里重点说一下imgsz为什么必须是 32 的倍数。YOLO 的主干网络里有多次下采样每次下采样把特征图缩小一半总共下采样 5 次就是 32 倍。如果输入尺寸不是 32 的倍数最后一层特征图的尺寸会出现小数导致 Reshape 或 Concat 操作失败。640 是 32 的 20 倍所以是安全的。同理如果你要用 416、320 这些尺寸也都能被 32 整除。2.3 动态轴设置的实际影响dynamic参数设成 True 时导出的 ONNX 模型在 batch 维度和空间维度上都是动态的。这意味着你可以用同一个模型处理不同尺寸的输入灵活性大大提高。但代价是什么呢首先是推理速度。动态轴会让推理引擎无法预先分配内存、无法做针对性的图优化实测下来推理耗时会增加 10% 到 30%。其次是某些推理引擎对动态轴的支持不完善比如一些嵌入式 NPU 的编译器就要求所有维度固定。所以我的建议是如果部署环境确定输入尺寸固定就老老实实设dynamicFalse如果确实需要变尺寸输入再开动态轴并且做好性能测试。如果只想让 batch 维度动态、空间维度固定可以手动指定model.export( formatonnx, imgsz640, opset12, dynamic{batch: True, height: False, width: False} )这样导出的模型可以接受任意 batch size但图像尺寸必须固定为 640。这种配置在实际部署中很常见因为服务端经常需要批量处理请求。2.4 导出后的模型校验导出完成不代表万事大吉必须做校验。校验分两步结构校验和数值校验。结构校验用onnx.checkerimport onnx model onnx.load(yolo11n.onnx) onnx.checker.check_model(model) print(模型结构校验通过)数值校验是拿同一份输入分别用 PyTorch 和 ONNX Runtime 跑一遍对比输出差异import numpy as np import onnxruntime as ort import torch # PyTorch 推理 dummy torch.randn(1, 3, 640, 640) torch_out model.model(dummy) # ONNX Runtime 推理 sess ort.InferenceSession(yolo11n.onnx) onnx_out sess.run(None, {images: dummy.numpy()}) # 对比 diff np.abs(torch_out.detach().numpy() - onnx_out[0]).max() print(最大误差:, diff)正常情况下最大误差应该在 1e-4 到 1e-5 量级。如果误差超过 1e-3说明导出过程中有问题可能是 opset 版本不对或者某些算子被错误转换了。这时候要回去检查导出日志看看有没有 warning。提示数值校验时输入要用随机数不要用全零或全一的输入因为某些算子在特殊输入下会走不同的分支掩盖问题。3. 实操过程与核心环节实现3.1 完整导出流程从权重到 ONNX下面把整个导出流程串一遍你可以直接照着做。第一步准备权重文件。假设你已经训练好了模型得到了best.pt放在runs/detect/train/weights/目录下。第二步写导出脚本。新建一个export_onnx.pyfrom ultralytics import YOLO import onnx import onnxruntime as ort import numpy as np import torch # 加载权重 model YOLO(runs/detect/train/weights/best.pt) # 导出 ONNX export_path model.export( formatonnx, imgsz640, opset12, simplifyTrue, dynamicFalse, halfFalse ) print(导出路径:, export_path) # 结构校验 onnx_model onnx.load(export_path) onnx.checker.check_model(onnx_model) print(结构校验通过) # 数值校验 dummy torch.randn(1, 3, 640, 640) with torch.no_grad(): torch_out model.model(dummy) sess ort.InferenceSession(export_path) onnx_out sess.run(None, {images: dummy.numpy()}) diff np.abs(torch_out[0].numpy() - onnx_out[0]).max() print(最大误差:, diff)第三步运行脚本。如果一切正常你会看到导出路径、结构校验通过、最大误差在 1e-5 量级。第四步检查输出节点。用 Netron 打开 ONNX 文件看看输入节点名字是不是images输出节点名字是什么。Ultralytics 导出的模型输出节点通常叫output0推理代码里要对应上。3.2 参数计算imgsz 与 batch 的取舍imgsz的选择不是拍脑袋决定的它跟你的应用场景直接相关。假设你要做一个实时检测系统摄像头输入是 1080p1920x1080你不可能直接把 1080p 喂给模型那样计算量太大。通常的做法是缩放到一个较小的尺寸。缩放尺寸怎么选先看你的硬件算力。如果是在服务器 GPU 上跑640 甚至 1280 都没问题如果是在边缘设备上跑320 或 416 更现实。再看你的检测目标大小。如果目标在图像中占比很小比如远处的行人那输入尺寸太小会导致目标特征丢失检测精度下降。这时候要么提高输入尺寸要么用滑动窗口切图检测。batch的选择也类似。训练时用大 batch 是为了梯度稳定推理时 batch 大小取决于你的吞吐需求。如果是一次处理一张图batch1如果是服务端批量处理batch 可以设成 4、8、16。但要注意batch 越大显存占用越高而且不是线性增长的。实测下来batch 从 1 增加到 8显存占用可能增加 6 到 7 倍。3.3 导出日志解读warning 里藏着关键信息导出过程中终端会打印一堆日志很多人直接忽略其实里面藏着重要信息。下面是我实际导出时的一段日志PyTorch: starting from best.pt with input shape (1, 3, 640, 640) BCHW and output shape(s) (1, 84, 8400) ONNX: starting export with onnx 1.15.0 opset 12... ONNX: simplifying with onnxsim 0.4.36... ONNX: export success, saved as best.onnx (12.3 MB)这里有几个关键信息输入形状是(1, 3, 640, 640)输出形状是(1, 84, 8400)。84 是 4 个边界框坐标加上 80 个类别概率8400 是所有预测框的数量。如果你训练的是自定义数据集类别数不是 80那 84 这个数字会变推理代码里的解析逻辑也要跟着改。如果日志里出现Warning: Unsupported operator或者Warning: Constant folding failed就要警惕了。前者说明某个算子没被正确转换后者说明某些常量折叠优化没生效。这些 warning 不一定导致导出失败但可能影响推理结果或性能需要逐一确认。3.4 从 ONNX 到下游格式的衔接ONNX 导出完成后通常还要继续转换。比如转成 ATC 格式给昇腾芯片用或者转成 kmodel 给 K210 用。这些转换工具对 ONNX 模型有额外要求。以 ATC 为例它要求 ONNX 模型的输入节点名字必须是input或者通过参数指定输出节点也要明确。如果 Ultralytics 导出的模型输入节点叫images那 ATC 命令里就要加--input_shapeimages:1,3,640,640。另外 ATC 对 opset 版本也有要求通常支持到 opset 11 或 12太新的版本可能不认。转 kmodel 时通常要先经过 NNCase 编译器。NNCase 对 ONNX 算子的支持有限某些算子需要替换或重写。这时候前面做的simplify就派上用场了简化后的模型算子更少转换成功率更高。注意每次转换格式后都要重新做数值校验因为不同工具对算子的实现可能有细微差异累积误差可能超出预期。4. 常见问题与排查技巧实录4.1 导出报错速查表下面这张表是我踩坑多年总结出来的覆盖了 90% 以上的导出报错报错信息原因解决办法Unsupported ONNX opset versionopset 版本过高降低 opset 到 12 或 11Could not find a version that satisfies the requirement ultralyticspip 源问题或 Python 版本过低换源升级 Python 到 3.8RuntimeError: Expected all tensors to be on the same device模型和数据在不同设备统一用 CPU 或统一用 GPUONNX export failed: Couldnt export operator算子不支持改写模型结构或换 opsetInvalid model IR versiononnx 和 onnxruntime 版本不匹配升级 onnxruntimeInput size must be multiple of 32imgsz 不是 32 的倍数改成 320、416、640 等4.2 数值误差过大的排查思路数值校验时如果发现误差超过 1e-3按下面的顺序排查。先确认输入是否一致。PyTorch 的输入是 NCHW 格式ONNX 的输入也是 NCHW但有些模型导出后会变成 NHWC这时候输入就要转置。检查方法是看 ONNX 模型的输入节点形状如果是(1, 640, 640, 3)那就是 NHWC输入要转置。再确认是否开了half。如果 PyTorch 用 fp32 推理ONNX 用 fp16 推理误差自然会大。统一精度后再对比。然后检查是否有随机性操作。有些模型里包含 Dropout 或随机数据增强导出时如果没设成 eval 模式每次推理结果都不一样。导出前务必调用model.eval()。最后检查算子实现差异。某些算子在 PyTorch 和 ONNX Runtime 里的实现细节不同比如插值算子的对齐方式、池化算子的取整方式等。这种误差通常较小但如果累积起来也可能超标。解决办法是尽量用简单算子避免复杂的自定义算子。4.3 实操心得三个容易被忽略的细节第一个细节是导出时的设备。很多人习惯在 GPU 上训练导出时也默认用 GPU。但 ONNX 导出其实在 CPU 上更稳定因为 GPU 上的一些算子实现可能跟 ONNX 不兼容。我的做法是导出前把模型移到 CPUmodel.to(cpu)导出完成后再移回去。第二个细节是文件路径。Ultralytics 默认把 ONNX 文件导出到权重文件同目录下但如果你用的是相对路径可能导出到你意想不到的地方。建议用绝对路径或者在导出后打印export_path确认。第三个细节是模型名字。导出后的 ONNX 文件名字默认跟权重文件一样只是后缀变成.onnx。如果你同时导出多个版本比如不同 opset文件会互相覆盖。建议在导出后手动重命名加上 opset 和日期的标识比如yolo11n_opset12_20250101.onnx。4.4 量化导出 int8 的注意事项如果下游需要 int8 量化模型不要直接导出 int8 的 ONNX而是先导出 fp32再做训练后量化。量化流程大致是准备校准数据集通常 100 到 500 张代表性图片用onnxruntime.quantization.quantize_static做静态量化最后校验量化后的精度损失。校准集的选择很关键。如果校准集不能代表实际数据分布量化后的精度会大幅下降。我的经验是校准集要从真实场景里采样覆盖各种光照、角度、遮挡情况。量化后如果精度下降超过 2%就要考虑用量化感知训练QAT而不是训练后量化。提示int8 量化对某些层特别敏感比如第一层卷积和最后一层全连接。如果精度损失主要来自这些层可以在量化时把它们排除保持 fp16 精度。4.5 跨框架导出的兼容性问题有时候你拿到的不是 PyTorch 权重而是其他框架的模型比如 TensorFlow 或 PaddlePaddle。这些框架导出 ONNX 的流程不同但核心思路一致先转成 ONNX 标准格式再校验。TensorFlow 转 ONNX 用tf2onnx工具PaddlePaddle 用paddle2onnx。转换时同样要注意 opset 版本和动态轴设置。跨框架转换的误差通常比同框架导出大因为不同框架的算子语义可能有细微差异。校验时如果误差在 1e-3 以内一般可以接受超过 1e-2 就要仔细排查了。我在实际项目里遇到过一次 TensorFlow 转 ONNX 后精度暴跌的情况最后发现是 BatchNormalization 层的 epsilon 参数在转换时被改了默认值。这种问题很隐蔽只能靠逐层对比输出定位。所以跨框架转换后逐层校验比整体校验更可靠。4.6 导出后的模型优化空间ONNX 导出不是终点导出后的模型还有优化空间。除了前面说的simplify还可以做算子融合、常量折叠、死代码消除等优化。ONNX Runtime 提供了一些优化工具可以在加载模型时自动做图优化。另外如果目标硬件有专门的推理引擎比如 TensorRT、OpenVINO可以把 ONNX 再转成这些引擎的格式通常能获得额外的性能提升。TensorRT 对 ONNX 的支持很好转换后推理速度能提升 2 到 5 倍。OpenVINO 在 Intel CPU 上的优化也很到位。不过要注意每次转换格式都可能引入精度损失所以每转一次都要校验一次。我的原则是能用 ONNX 直接推理就用 ONNX除非性能瓶颈明显否则不轻易引入额外的转换环节。