该用 torch.jit.trace 时仅限结构固定、无输入依赖分支的模型（如 ResNet/VGG）；含控制流必须用 torch.jit.script；保存加载须用 save()/load()，且部署前需用生产环境一致输入验证输出。
直接用 torch.jit.trace 或 torch.jit.script 转，但选错方式会导致线上推理结果错误或崩溃——不是所有模型都适合 trace。
什么时候该用 torch.jit.trace？
只适用于结构完全固定、不依赖输入数据做分支判断的模型。比如 ResNet、VGG 这类经典 CNN，forward 里没有 if、for、while，也没有根据张量值动态跳层的逻辑。
常见错误现象：
- 模型在训练时有
if x.mean() > 0:分支，但 trace 时输入刚好满足条件，导出后模型永远只走这个分支 - 加载
.pt文件后调用时报RuntimeError: The following operation failed in the TorchScript interpreter
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 必须先调用
model.eval()，关闭 Dropout/BatchNorm 更新行为 -
dummy_input的 shape 和 dtype 要和实际推理一致（如 batch=1、RGB 三通道、归一化后范围） - trace 后务必用相同输入跑一次，比对原始模型与 traced 模型输出的
torch.allclose
含控制流的模型必须用 torch.jit.script
只要 forward 函数里出现 Python 控制流（哪怕只是 len(x.shape) == 4 判断），就必须走 script 路径。它通过 AST 解析保留全部语义，不会漏掉任何分支。
使用场景：
Python 环境工具专业版功能概述Python 环境工具专业版是一项面向实际任务的技能。它将相关步骤、工具调用和结果整理方式集中到统一流程中，帮助使用者更快完成目标并减少重复操作。核心要点使用时应结合输入条件选择合适的执行方式，核对必要参数、依赖环境与输出内容，并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景，可作为自动化工作流的一部分，也便于后续检查、调整和扩展。执行完成后建议检查结果是否符合预期，并保留必要记录。使用与执行同时注意输入完整性、执行条件和输出可用性。从功能定位来看，该技能
- 自定义 gate 模块（如
MyDecisionGate） - Transformer 中的 mask 逻辑或动态 padding 处理
- YOLO 类检测头中根据置信度阈值过滤 bbox 的流程
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 优先给模块加
@torch.jit.script装饰器，而不是整模型torch.jit.script(model)（后者可能报 unsupported type 错误） - 避免在脚本化函数里用未标注类型提示的 Python 值，例如
def forward(self, x): threshold = 0.5可以，但threshold = self.confidence_threshold（如果它是 Python float 且未声明为torch.jit.Attribute）会失败 - 若报
Unsupported operation: 'getattr'，说明访问了非 tensor 属性，需显式声明：self.threshold: float = 0.5
保存与加载时容易被忽略的细节
TorchScript 模型不是普通 Python 对象，不能靠 pickle 或 torch.save 存。必须用 save() 方法序列化，且加载后不能当 nn.Module 用。
关键点：
- 保存只能用
traced_model.save("model.pt")或scripted_model.save("model.pt")，不能用torch.save(...) - 加载必须用
torch.jit.load("model.pt")，返回的是torch.jit.ScriptModule，不是nn.Module - 加载后不能调用
.train()或.cuda()—— 必须在 trace/script 前就完成设备迁移，否则会报Expected all tensors to be on the same device - 如果模型里用了自定义算子或第三方库函数（如
cv2.resize），script 会直接失败，得重写为纯 torch ops
部署前必须验证的三件事
很多线上 bug 都源于本地验证不充分。以下检查缺一不可：
- 用和生产一致的输入尺寸、dtype、device（CPU/GPU）跑一遍，确认输出 shape 和数值与原始模型误差
- 在目标环境（如 Docker 容器）里用最小依赖启动：只装
torch，不装torchvision等非必需包，测试能否成功torch.jit.load - 如果服务要支持变长 batch，确保
dynamic_axes参数已用于 ONNX 导出环节（TorchScript 本身不支持动态 batch，这是常见混淆点）
最常被绕开、也最容易出问题的是第三点：TorchScript 模型的输入 shape 是固化死的，想支持 batch=1～32，要么 trace 多个版本，要么改用 ONNX + TensorRT。
