必须显式调用model.eval()并正确配置dynamic_axes、opset_version，导出后须用onnx runtime验证数值一致性；否则模型在跨平台部署时会崩溃或输出错乱。
直接导出 ONNX 不等于能跨平台部署，关键在导出时是否满足可追踪性、静态图约束和接口一致性。跳过 model.eval() 或忽略 dynamic_axes，模型大概率会在 ONNX Runtime 中崩溃或输出错乱。
必须显式调用 model.eval()，不能靠“没训练就默认是 eval”
PyTorch 的 Dropout 和 BatchNorm 在 train 模式下行为与推理完全不一致：前者会随机丢弃神经元，后者使用运行时统计而非固定参数。ONNX Runtime 不模拟训练逻辑，它只按导出时的图执行。
- 即使你从没调用过
model.train()，只要模型实例未显式设为eval，torch.onnx.export仍可能捕获到训练态分支（尤其自定义模块中用了self.training判断） - 常见现象：导出后 ONNX 输出每跑一次都不一样——根源就是
Dropout层没关，被原样保留进图里 - 正确做法：
model.eval()必须出现在torch.onnx.export调用前，且不可被后续代码覆盖（例如误写成model.train()后再 export）
dynamic_axes 不是可选配置，而是部署刚需
绝大多数生产场景需要支持变长 batch 或图像尺寸，但默认导出是静态 shape。若不声明 dynamic_axes，ONNX Runtime 加载后会硬编码输入维度（如 [1, 3, 224, 224]），换 batch_size=4 直接报 InvalidArgument: Input is not a vector 类错误。
python-docx Skill功能概述python-docx Skill是一项面向实际任务的技能，主要用于本Skill提供使用python-docx生成专业Word文档的标准方法和最佳实践；生成安全服务方案文档；核心要点生成技术架构设计文档；生成任何需要专业排版的Word文档；核心库 : python-docx；使用与执行辅助库 : docx.shared , docx.enum , docx.oxml.ns；标准代码模板；1. 文档初始化；2. 字体设置（必须！它将相关步骤、工具调用和结果整理方式集
- 必须写全：不仅
input要标动态维，所有关联输出（如output）也要同步声明，否则下游绑定失败 - 示例：
dynamic_axes={"input": {0: "batch_size"}, "output": {0: "batch_size"}}—— 这里"batch_size"是符号名，不是变量，不能写成batch_size（无引号）或str(batch_size) - 图像尺寸也需处理：若支持多尺度输入（如
[B, 3, H, W]），应写成{"input": {0: "batch", 2: "height", 3: "width"}}
opset_version 选错会导致算子不识别或静默降级
ONNX 算子集版本决定哪些 PyTorch 操作能被准确映射。选太低（如 opset_version=11），torch.where、torch.cat 带空张量等常见操作会 fallback 到不兼容实现；选太高（如 opset_version=17），旧版 ONNX Runtime（v1.15 及之前）直接加载失败。
- 当前安全选择是
opset_version=14或15：覆盖 PyTorch 2.0+ 主流算子，且被 ONNX Runtime v1.16+ 全面支持 - 不要依赖默认值：PyTorch 2.6 默认仍是
14，但早期版本默认为9或11，不显式指定极易踩坑 - 验证方法：导出后用
onnx.load("model.onnx")查看model.opset_import，确认版本与目标平台 runtime 兼容
导出后必须用 ONNX Runtime 做数值一致性验证
导出成功 ≠ 推理可用。常见问题不是报错，而是输出数值漂移（如 softmax 后概率和不为 1、分类 top-1 错位），根源常是 PyTorch 与 ONNX 对算子边界的细微差异。
- 验证输入必须严格对齐：PyTorch 输入是
torch.float32，传给 ONNX Runtime 的 numpy 输入必须是np.float32（不是np.float64），且 shape 完全一致 - 对比方式：
np.allclose(y_pt.detach().numpy(), y_onnx, atol=1e-5)——atol=1e-4太松，会漏掉torch.nn.AdaptiveAvgPool2d等层的量化误差累积 - 最易忽略的坑：
torch.tensor([1, 2, 3])这类字面量张量在 ONNX 中常被常量化，导致与 PyTorch 运行时行为不一致；应改用nn.Parameter或注册为buffer
真正难的不是导出动作本身，而是那些不报错却让结果偏移几个百分点的问题——它们往往藏在自定义层的控制流、非参数张量的生命周期，或 dynamic_axes 没覆盖全的输出节点里。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
