企业官网建设流程全解析

项目排期表上，"Phase A · Step 3：模型导出 ONNX"只占了一个不起眼的小格子。当时团队预估这是一个顶多两三天的技术活，结果我前后折腾了将近一周才敢说"这个导出是稳的"。后来复盘发现，问题不在于torch.onnx.export这个接口本身有多难，而是整个导出链路里的隐藏依赖、版本矩阵和下游约束，远比大多数人想象的多。

这篇内容我围绕一个具体场景来写：某视觉检测模型，训练基于 PyTorch，目标产物是能在服务端CPU环境稳定运行的ONNX文件，后续推理引擎选用ONNX Runtime。如果你也正处在"模型训练完、准备交付到部署环境"这个阶段，那这篇应该能帮你少踩不少坑。

1. 为什么"导出ONNX"值得单独拆成一个Step

1.1 项目里这条部署链路，ONNX到底卡在哪一环

很多同学第一次接触ONNX，是在某个"快速上手"教程里，跟着代码三五行就把模型转出来了一个 .onnx 文件。于是大家天然觉得：这玩意儿不是有手就行吗？项目排期里为什么要给它单独开一个Step？

实际上，在真实项目里，ONNX导出是"训练"和"部署"之间的交接仪式。训练侧，模型是活的：有动态Batch、有训练状态、有各种中间变量，它还可以继续训练、继续调参。部署侧，模型是死的：输入尺寸固定、计算图固定、运行环境完全独立。ONNX就是这个"由活到死"的转换点。

在这条链路里，ONNX承担的是中间表示（IR）的角色。它本身不负责高效推理，它的价值是让上层训练框架（PyTorch等）和下层推理运行时或硬件编译器解耦。一个 .onnx 文件导出之后，训练框架里的各种花活就彻底与它无关了，下游只认这个静态的描述文件。这样换来两个核心能力：一是同一份模型可以在不同运行时上运行，二是在不依赖深度学习框架环境的前提下完成性能优化。

1.2 不导出的代价：原框架推理的三个现实约束

我自己经历过"先跑通再说"的阶段，当时方案是直接在 PyTorch 环境里加载模型，用原框架做推理服务。这个方案看起来省事，但真正推进到项目后期，会撞上三面墙。

第一，环境锁死。服务器上要装对应版本的 PyTorch、CUDA 库、一堆传递依赖，升级一个系统库都可能让模型服务瘫痪。模型交付出去，基本等于把整套训练环境也交付出去，运维成本直接起飞。

第二，推理效率上不去。训练框架的模型执行方式更关注灵活性，同样的算子，框架内建执行逻辑往往比专门的推理引擎要多一层调度开销。尤其在高并发、小Batch场景下，这个差距会非常明显。

第三，硬件适配能力弱。如果后续业务要上推理加速卡或者边缘设备，这些硬件厂商的编译器通常只吃 ONNX 或自家格式，不支持直接加载 PyTorch 的模型权重。

所以，导出 ONNX 不是"可选项"，而是把模型从训练链路里解放出来、让它进入工程化体系的必经环节。

1.3 ONNX导出前后的责任边界

导出前，你的身份是算法工程师，关注的是模型精度、Loss 曲线、效果指标。导出后，你的身份要切换成"部署交付者"，关注的是算子兼容性、图优化空间、推理延迟。很多人都没意识到，这个身份切换意味着你不能再抱着一颗"算法模型完美就行"的心态。

从项目管理的角度看，单独把"模型导出"拆成一个Step，本质上是强制做一次交付物确认。在排期里明确它，能逼着团队把一些原本含糊的问题提前暴露：模型结构是否确定？算子是否会有兼容性风险？部署环境的 ONNX Runtime 版本是什么？这些问题如果留在部署阶段再发现，排查成本会呈指数上升。

2. 动手导出之前：模型冻结、算清单与版本对齐

2.1 模型处于eval且冻结状态

这是最基础也最容易被忽略的一件事。如果模型里有 BatchNorm 或 Dropout，导出前必须确认已经切换到 eval() 模式。否则，BatchNorm 层在训练模式下会用到当前 batch 的统计数据，而不是训练好的 running_mean 和 running_var，导出后的模型推理结果可能会漂移。

实际操作里，我的习惯是不仅调用 model.eval()，还会顺带看一眼模型里各层的 running_mean 有没有更新。尤其是从检查点恢复的模型，如果中间出现过训练中断、继续训练、再保存这类操作，一旦本地变量和 state_dict 对不上，eval() 也不一定能兜住。

另外，"冻结"不等于"eval"。冻结通常指所有参数 requires_grad=False，这样既能避免误改权重，也能让后续 trace 出的计算图更干净。我见过一些项目导出时忘了关 requires_grad，导是能导出来，但文件里会额外带上梯度相关的节点，白白增加图体积。

2.2 输入输出的shape和dtype提前定死

ONNX文件里最核心的元信息就是输入输出的 shape、dtype。虽然 ONNX 支持动态维度，但动态维度并不是"随便填"那么好用，下游推理引擎对动态shape的实现差异很大。

所以导出前，需要确定一件事：这个模型上线后，输入尺寸是固定的，还是需要支持任意大小？

如果业务上输入尺寸固定，比如检测模型统一 Resize 到 640x640 再进网络，那就直接在导出时把输入样例定成 (1, 3, 640, 640)，让 ONNX 导出逻辑把中间所有 shape 全部算死。这样做出来的模型在推理引擎里，图优化空间最大，速度也最稳。

如果确实需要动态，比如第一维 batch 可变，或者 NLP 类的序列长度可变，那就必须明确声明动态轴。这里有个经验：ONNX 的动态轴支持是"选择性动态"，不是"全局动态"。如果你把某个维度标成动态，但图内部有一些算子偷偷假定这个维度是固定值，导出时会报错或者导出的模型行为不正确。因此动态轴不要贪多，能用固定 shape 就用固定 shape。

2.3 opset版本与推理引擎的对应关系

opset（Operator Set）是 ONNX 的算子版本集合。每次 ONNX 规范更新，都会增加新的算子、修正旧算子定义。PyTorch 导出时的 opset 参数决定它用哪个版本的算子定义去序列化计算图。

这个版本号有两端必须对齐：一端是 PyTorch 导出侧能否正常生成，另一端是 ONNX Runtime 或硬件编译器能解析到什么版本。我遇到过最典型的问题：本机 PyTorch 版本较新，随手填了 opset=17，结果目标环境的 ONNX Runtime 只支持到 opset 15，模型加载直接报错。

一个稳妥的做法是：在导出前先确认目标推理引擎支持的 opset 上限，然后导出时的 opset 既不要低于 11（太老会有很多算子缺失），也不要高于目标引擎的上限。比如目标 ONNX Runtime 版本支持 opset 15，那导出就填 15，别为了"新"而去填更高的版本。

3. trace、script还是dynamo：三种导出路径怎么选

3.1 torch.onnx.export默认走trace

PyTorch 里最经典的导出接口是 torch.onnx.export，大多数人知道它内部默认用 tracing 机制：给定一份示例输入，把模型前向过程中实际执行到的算子记录下来，形成一个静态图。

trace 的好处是简单直观，只要前向逻辑是"直来直去"的，几乎一条命令就能搞定。但它的局限性也很明显：只能导出"这次执行走过的路径"。如果你的模型里有一段 if 分支，而示例输入恰好只走了其中一条分支，那另一条分支在导出的模型里压根不存在。后续推理遇到另一条分支的输入，结果就是错的。

我在某个分割模型里就踩过这个坑。模型里有一个针对不同分辨率的判断分支，导出时我用的示例输入是 640 分辨率，成功导出了。结果真跑到 1280 分辨率数据上，模型直接乱输出。排查半天才发现，trace 过程把分辨率判断里的较小分支裁剪掉了。

3.2 script方式适合控制流

为了解决 trace 丢失控制流的问题，可以用 torch.jit.script 先把模型转成 ScriptModule，再导出 ONNX。script 走的是"解析源码"的方式，显式保留 if、for 等控制流结构，图里会生成相应的控制流节点。

但 script 对模型代码有要求：不能随意使用 Python 的动态特性。你写模型时可能觉得"用 .item() 取个数值很方便""列表推导式很 Pythonic"，这些到了 script 阶段全都可能报错。所以如果你的模型并不复杂，也没有明显的动态分支，我一般不建议为了"用 script 而用 script"，改写代码的时间成本可能超过收益。

3.3 dynamo新路径的实际体验

PyTorch 2.x 之后推出了 dynamo 相关能力，torch.onnx.export 也提供了 dynamo=True 的导出选项。我实际试用过几次，最大的感受是它对 Python 代码的兼容性更好，很多原来需要手工改写的代码模式可以原样通过。图结构和 opset 支持也更规范。

但目前来说，dynamo 导出仍然有一些算子覆盖上的坑，尤其是一些自定义的 C++ extension 算子，或者某些用了高阶梯度能力的模型。我的建议是：新项目可以优先尝试 dynamo，但如果测试中出现解释不清的行为差异，就退回传统 trace 再看看。

4. 完整导出脚本与产物级验证

4.1 最小导出脚本

下面这个脚本是我在项目里反复用过的基础模板，参数都标注了用途：

import torch model = load_model_from_checkpoint("best.pt") model.eval() # 冻结参数，避免误操作带梯度的节点 for p in model.parameters(): p.requires_grad = False # 输入样例：shape = (batch, channel, height, width) dummy_input = torch.randn(1, 3, 640, 640) torch.onnx.export( model, dummy_input, "model.onnx", opset_version=15, input_names=["input"], output_names=["output"], dynamic_axes={ "input": {0: "batch_size"}, "output": {0: "batch_size"}, }, do_constant_folding=True, )

有几个细节值得展开。

dynamic_axes 里我通常只开放 batch 维。如果你的业务场景里宽高也变化，可以加上 {2: "height", 3: "width"}，但要注意 resizing 类操作对动态尺寸的算子兼容性。do_constant_folding=True 默认开启，它会把一些只依赖常量参数的子图预先计算出来，比如 Conv 层的 bias 加法。开启后模型文件可能更小，推理时也能少跑几个节点，建议保持开启。

4.2 onnx.checker和shape_inference

导出完成后，别急着拿去上服务。第一步先用官方工具做基础体检：

import onnx model = onnx.load("model.onnx") onnx.checker.check_model(model) # 重建图内的shape信息，补全中间张量的维度 model = onnx.shape_inference.infer_shapes(model) onnx.save(model, "model.onnx")

onnx.checker.check_model 检查的是模型的格式合法性，包括节点输入输出是否匹配、属性是否合法、图结构是否完整。这属于"语法检查"，不保证语义正确，但能拦下大量低级问题。

shape_inference 是我每次导出后必跑的一步。很多框架导出的图里，中间张量的 shape 信息是缺失的，推理引擎拿到这种图往往只能按动态思路处理，性能受影响。手动跑一次 shape inference，相当于给图补全了"尺寸标注"，下游引擎的优化空间会大很多。

4.3 用ONNX Runtime做数值一致性验证

格式检查通过只是第一步，真正的考验是数值一致性。我的做法是把原始 PyTorch 模型的输出和 ONNX 模型的输出做逐元素对比：

import numpy as np import onnxruntime as ort import torch # 固定输入，多次采样求最大误差 x = torch.randn(8, 3, 640, 640).numpy() sess = ort.InferenceSession( "model.onnx", providers=["CPUExecutionProvider"], ) outputs_onnx = sess.run(None, {"input": x}) with torch.no_grad(): model.eval() outputs_torch = model(torch.from_numpy(x)).numpy() # 统计最大绝对误差和相对误差 max_diff = np.max(np.abs(outputs_onnx[0] - outputs_torch)) print("max abs diff:", max_diff)

这里要注意，PyTorch 模型和 ONNX Runtime 模型在浮点运算顺序上可能有小差异，比如 Convolution 的 im2col 和矩阵乘的累加顺序不同。所以不要期望二者 diff 为 0，一般观察 1e-4 到 1e-5 量级的最大误差即可。

如果误差到了 1e-2 甚至更大，那就要怀疑导出过程中某个算子被错误降级，或者动态分支被裁掉，需要往具体层去定位。

5. 这步最容易翻车的五个实操坑

5.1 动态轴配了但输入样例写错

这个坑极其隐蔽。某个模型的导出脚本里声明了 height 和 width 是动态轴，但 dummy_input 用的是 (1, 3, 224, 224)。文件导出来一切正常，也能跑，但如果你用 (1, 3, 512, 448) 去测试，中间某个 Resize 节点可能计算出不符合预期的 shape，甚至整个推理崩溃。

原因在于：部分算子对输入尺寸有内部假设，trace 时这个假设被写死在了常量节点里。最典型的例子就是某些 F.interpolate 的 scale_factor 被转成了固定数值，一旦输入尺寸变化，插值目标尺寸就错了。对付这个问题的排查方法是：导出后用多组不同 shape 的输入跑一遍 ONNX Runtime，看输出 shape 是否符合预期，而不只测一组。

5.2 upsample算子被rewrite

语义分割类模型经常会在解码器里用到上采样。PyTorch 里的某些上采样实现，在导出 ONNX 时会被转成一系列自定义节点，例如 Resize 配合 coordinate_transformation_mode 的复杂组合。不同 opset 版本下，这个转换结果差别很大。

我在一个分割模型上遇到过：PyTorch 里用 F.interpolate(mode='bilinear')，导出为 opset 11 时一切正常，换成 opset 15 后，ONNX Runtime 提示 Resize 节点的某个属性不支持。最后没办法，只能强行把导出 opset 降回 11，或者改模型内部的上采样方式，比如换成 PixelShuffle 或卷积堆叠。

这提醒我们：opset 不是越新越好，要结合算子实际转换结果来定。如果某一次切换 opset 版本后出现奇怪报错，先把版本回退对比一下模型输出，很多时候问题就消失了。

5.3 数值对不上

数值对不上的原因很多，最常见的是预处理不对齐。ONNX Runtime 输入是裸 Tensor，它不关心你在 PyTorch 里是怎么做归一化的。如果你在模型内部做了 Normalize 然后用均值和方差做了减法，那 OK；但如果 Normalize 在模型外部用 PIL 或 OpenCV 做的，部署时也得复刻同样的顺序、同样的通道格式、同样的缩放。

我遇到过团队里前后端联调大半天，最后发现是 HWC 和 CHW 的通道顺序问题。PyTorch 模型内部是 CHW，预处理端输出的是 HWC 且忘记 transpose，结果推理结果的准确率断崖下跌。

5.4 图优化选项导致显存爆炸

ONNX Runtime 里有一个 graph optimization level 配置，常见的有 ORT_DISABLE_ALL、ORT_ENABLE_BASIC、ORT_ENABLE_EXTENDED、ORT_ENABLE_ALL。这个配置能自动融合算子、重排节点、消除冗余，理论上推理性能会更好。

但你调高优化级别后要重新做一轮精度验证。我遇到过把优化级别调到 EXTENDED 之后，某层被融合成了新的算子组合，浮点误差变大，最终线上效果出现可见的劣化。还有一个极端情况是开启闭环优化后，某些大模型推理时内存占用反而上升。

所以我的建议是：性能调优时，优化级别从 BASIC 开始往上试，每提升一档都回归一次精度和延迟。不要图省事直接拉满 ALL。

5.5 opset太高导致推理引擎不支持

这算是版本问题里最高发的。通常是开发环境用的 PyTorch 很新，导出默认 opset 也高，代码一写就导出成功。等到部署环境加载时报类似"Model opset version X is not supported"的错误。

这种问题的排查链路很简单：先看报错信息里要求的 opset 上限，再看导出脚本里的 opset_version，改了之后重新导出。关键是不要在本地换 PyTorch 版本，因为升级或降级 PyTorch 可能影响模型权重加载行为，正确做法是固定 PyTorch，改 opset。

6. 导出完成之后：接入运行时和后续迭代流程

6.1 session.options里值得调整的参数

ONNX Runtime 跑起来之后，有几个参数值得认真调一下。首先是 intra_op_num_threads 和 inter_op_num_threads，分别控制单个算子内部的线程数和不同算子间的并行线程数。CPU 推理场景下，这两个值不是越大越好，设得比物理核数还多是常见性能杀手。

其次是 execution_mode，默认是 ORT_SEQUENTIAL，如果模型里没有明显的并行分支，我建议保持默认。并行模式在有分支结构的模型上有收益，但也会引入额外的线程调度开销，小模型反而变慢。

另一个容易被忽略的是 session 的 graph_optimization_level。我上面提过优化级别会影响精度，正式部署前应该把这一项固定下来，并写进配置文档，避免不同环境加载同一份模型时行为不一致。

6.2 把"导出-验证-提交"固化到pipeline里

模型迭代不是一次性的，项目到了中后期可能一天要导出好几次新版本模型。如果每次都靠手动执行脚本，很容易在不同的环境里导出结果不一致。

我在项目里做了一件事：把导出脚本、shape inference、数值一致性验证、样例输出检查打包成一个自动化脚本。每次训练出新的权重文件，只要执行一条命令，就能得到一个确认可交付的 ONNX 文件加上一份校验报告。

这个流程里印象最深刻的一点是：校验环节里除了数值比对，还固定了几组真实业务输入，用来确认模型在常见输入下的输出是否合理。数值比对只能保证"和 PyTorch 一致"，但不保证"符合业务预期"，尤其当 PyTorch 模型本身就有点问题的时候，容易把错误一套搬到 ONNX。所以我建议在自动化流程里加一个"业务回归检查"步骤，比如固定几张图，输出指标高于某个阈值才算通过。

6.3 下次迭代时的注意点

模型结构一旦有变化，ONNX 导出不是简单重跑一遍就行。要特别关注新增的模块是否引入了不支持导出的操作。我的经验是，在模型编码阶段就提前审查每个新算子的可导出性，比导出时再发现要省力得多。

另外，模型文件在多次导出的过程中可能会积累一些旧版本残留图节点。如果导出的模型体积比预期大出不少，可以用 onnxsim 这类工具做一次简化。它能把常量折叠掉、移除冗余节点，把图整理得更清爽。但用完 onnxsim 之后，也要重新做一遍精度验证，确保简化过程没有引入语义变化。

回头看这个 Step，我的直观感受是：真正难的不是那一行导出代码，而是围绕导出建立起一套可重复、可验证、可追溯的流程。当模型从训练环境迈向生产环境的那一刻，"它能跑"是不够的，你得确保它能稳定地、和预期一致地跑很久。这一步做扎实了，后面接入推理服务、性能调优都会顺很多。