PyTorch模型导出ONNX需满足可追踪性、显式调用model.eval()、正确配置input_names/output_names和dynamic_axes、选用兼容opset_version，并用ONNX Runtime验证数值一致性。
能导出，但“高效”不等于“快”，而是指导出后 ONNX 模型在目标平台能跑通、数值对得上、结构没被拆碎——关键在 torch.onnx.export 的参数组合和前置准备，不是换更快的命令。
必须先调用 model.eval() 再导出
PyTorch 的 Dropout 和 BatchNorm 在训练/评估模式下行为完全不同。导出时若模型仍处于训练模式，ONNX 会把训练专用分支（比如随机丢弃逻辑）也固化进去，导致推理结果漂移甚至崩溃。
- 务必在导出前执行
model.eval()，且不能只写在函数里、忘了实际调用 - 如果模型里手动写了
if self.training:分支，导出前要确认该分支是否被禁用——eval()不会自动跳过你手写的条件逻辑 - 导出后建议用
onnx.checker.check_model()验证基础结构，但这个检查不捕获数值偏差
dynamic_axes 不是可选项，是精度对齐的必要开关
导出时模型不报错，但 ONNX Runtime 推理结果和 PyTorch 对不上？90% 是 dynamic_axes 没设对。PyTorch 默认把所有 shape 当固定值处理，而 ONNX Runtime 会严格按导出时声明的 shape 分配内存和计算路径。
- batch 维度（通常是第 0 维）几乎必须标：
{"input": {0: "batch"}} - 输入名必须和
input_names完全一致：写了input_names=["sensor_input"]，就只能写{"sensor_input": {0: "batch"}}，不能写{"x": ...}或大小写不匹配 - 输出 tensor 若 shape 依赖输入（如 padding 后长度变化），对应维度也要同步标，否则 ONNX Runtime 可能截断或填充错误
- 不确定输出名？加
verbose=True运行一次，日志里会打印出实际使用的 symbol 名
选对 opset_version 和 dynamo 开关，避免算子不支持
ONNX 算子集是版本化的。opset_version=11 兼容老设备（如 STM32Cube.AI），但不支持 torch.where 的某些用法；opset_version=17 支持更广，但部分边缘推理引擎还没跟上。
立即学习“Python免费学习笔记（深入）”；
- 目标平台明确时，优先查其文档支持的最高 opset，而不是无脑用最新版
-
dynamo=True是 PyTorch 2.0+ 推荐方式，能更好处理 control flow（如 for 循环、if 判断），但要求模型 forward 中不含 CUDA-only 操作（如torch.tensor(..., device="cuda")） -
dynamo=False（默认）更稳定，尤其适合轻量 CNN、RNN 等静态图结构；若导出报 “Unsupported value type”，大概率是用了 dynamo 不识别的 Python 原生类型（如 list of tensors） - 无论开不开 dynamo，
do_constant_folding=True都应开启——它能把可静态计算的子图（如nn.ReLU+ 常量 bias）提前折叠，减小 ONNX 文件体积并提升推理速度
导出后必须做数值一致性验证，不能只看文件生成成功
生成 .onnx 文件只是第一步。ONNX Runtime 加载后跑出来的结果，和原始 PyTorch 模型在相同输入下的输出，最大绝对误差应小于 1e-5（FP32 场景）。差得多，说明导出过程已引入隐式修改。
- 验证代码必须用 CPU 输入：PyTorch 输出转
.cpu().numpy()，ONNX Runtime 输入用dummy.cpu().numpy()，避免 device 不一致引入误差 - 不要只比对 softmax 后概率——比对模型最后一层 raw logits，因为 softmax 本身对微小差异敏感
- 如果验证失败，优先检查
dynamic_axes是否漏标、input_names是否与 forward 参数名一致、是否有未处理的torch.no_grad()外部上下文影响梯度状态
