PyTorch模型导出前必须满足：模型调用model.eval()并禁用dropout/BN训练行为，输入张量为固定shape的真实tensor，control flow需可静态化，自定义op需兼容ONNX。
PyTorch模型导出前必须满足哪些条件？
PyTorch模型不能直接调用 torch.onnx.export 就成功导出，核心前提是模型必须处于 eval() 模式，且所有输入张量需固定 shape（尤其是 batch 维度不能为 None 或动态符号）。否则会报错如 RuntimeError: ONNX export failed: Couldn't export operator aten::dropout（因训练模式下 dropout/BN 未冻结）或 Exporting a model to ONNX with dynamic axes is not supported（输入未指定动态维度约束）。
- 确保调用
model.eval()，并手动禁用 dropout 和 BN 的 training 行为（torch.no_grad()包裹推理更稳妥） - 输入示例张量必须是真实 tensor，不能是 dummy placeholder（比如用
torch.randn(1, 3, 224, 224)而非torch.empty） - 若模型含 control flow（如 if/for、
torch.where带标量条件），需确认其在 tracing 时可被静态化；否则得改用torch.jit.script预编译再导出 - 自定义 op 或非标准 torch 函数（如
torch.fft在旧版 ONNX 中不支持）会中断导出，建议先用torch.onnx.export(..., verbose=True)定位卡点
如何正确调用 torch.onnx.export 并设置关键参数？
torch.onnx.export 的参数看似简单，但几个关键项设错会导致 ONNX 模型无法加载或推理结果异常：
-
input_names和output_names建议显式指定，便于后续调试和绑定输入输出（尤其多输入/多输出场景） -
dynamic_axes必须按需声明：例如图像 batch 推理需支持变长 batch，则设{"input": {0: "batch"}, "output": {0: "batch"}}；若忽略，导出模型将硬编码 batch=1，后续 runtime 传入 batch=4 会失败 -
opset_version至少选 12（推荐 14+），低版本（如 11）不支持torch.nn.functional.silu或aten::scaled_dot_product_attention，容易触发Unsupported value kind: None - 不要省略
do_constant_folding=True（默认开启），它能折叠常量子图，减小模型体积并提升兼容性
示例：
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
torch.onnx.export(
model,
args=(dummy_input,),
f="model.onnx",
input_names=["input"],
output_names=["output"],
dynamic_axes={"input": {0: "batch"}, "output": {0: "batch"}},
opset_version=14,
do_constant_folding=True
)
导出后如何快速验证 ONNX 模型是否可用？
导出文件存在 ≠ 模型可用。必须做两层验证：结构可加载 + 数值等价。
- 先用
onnx.load加载并检查图结构：onnx.checker.check_model(model_onnx)，若报ModelProto has no field 'graph'说明导出失败或文件损坏 - 再用 ONNX Runtime 运行一次前向，对比 PyTorch 输出与 ONNX 输出的 max absolute diff（建议阈值
1e-4）：import onnxruntime as ort import numpy as np
sess = ort.InferenceSession("model.onnx") ort_out = sess.run(None, {"input": dummy_input.numpy()})[0] max_diff = np.max(np.abs(torch_out.detach().numpy() - ort_out))
- 注意：ONNX Runtime 默认使用 CPU provider；若模型含 CUDA-specific op（如某些自定义插件），需提前注册 provider 或换用 onnxruntime-gpu
常见错误现象及对应修复点
- 报错
Unsupported node kind: prim::Constant：通常因模型中用了 Python 常量（如 if x > 0.5:），应改用 torch.where 或确保控制流可被 tracing 捕获
- 输出全零或 NaN：检查输入是否归一化（ONNX Runtime 不自动做
torchvision.transforms）、是否漏掉 model.eval() 导致 BN 统计量异常
-
ORT_RUNTIME_EXCEPTION 提示某 op 不支持：查 ONNX operator support matrix，降级 opset_version 或重写对应模块（如把 F.gelu 换成 nn.GELU）
- 动态 batch 推理时报
InvalidArgument: Input shape mismatch：确认 dynamic_axes 在 export 和 runtime 两端一致，且 ONNX Runtime session 创建时未强制固定 shape（如没调用 sess.get_inputs()[0].shape 手动改 shape）
Unsupported node kind: prim::Constant：通常因模型中用了 Python 常量（如 if x > 0.5:），应改用 torch.where 或确保控制流可被 tracing 捕获torchvision.transforms）、是否漏掉 model.eval() 导致 BN 统计量异常ORT_RUNTIME_EXCEPTION 提示某 op 不支持：查 ONNX operator support matrix，降级 opset_version 或重写对应模块（如把 F.gelu 换成 nn.GELU）InvalidArgument: Input shape mismatch：确认 dynamic_axes 在 export 和 runtime 两端一致，且 ONNX Runtime session 创建时未强制固定 shape（如没调用 sess.get_inputs()[0].shape 手动改 shape）PyTorch 到 ONNX 的链路里，最易被忽略的是「导出时的输入张量 dtype 和 device」——必须和实际推理一致（比如模型在 GPU 上训练，但导出时输入在 CPU，某些算子行为会有差异），还有 torch.no_grad() 是否包裹了整个导出流程。这两点不检查，数值误差可能到 1e-2 级别，远超合理范围。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
