TorchScript是生产部署的准入门槛，需根据模型结构选择trace（静态路径）或script（动态控制流），注意类型注解、接口对齐、C++加载兼容性及严格验证。
直接结论：不用 Python 解释器跑模型，就能提速、减内存、跨平台——TorchScript 不是“可选优化”，而是生产部署的准入门槛。
torch.jit.trace 为什么一用就出错？
它只记录你给的那一次输入走过的路径，不看代码里写了什么分支。比如模型里有 if x.sum() > 0，但你 trace 时 x.sum() 恰好是正数，那整个 else 分支就彻底消失。上线后遇到负和输入，要么报错，要么输出完全不对。
- 仅适用于结构绝对固定、不含任何
if/for/while的模型（如纯 CNN 骨干） - 输入 shape 必须固定；变长序列、动态 batch size 会直接失败
- trace 后的模型不能调用未 trace 过的 Python 方法（比如自定义后处理函数）
- 验证时别只比一次输出：用多组不同输入（尤其边界值）跑
torch.allclose，否则容易漏掉控制流失效问题
torch.jit.script 怎么写才不被拒？
TorchScript 编译器不是 Python 解释器，它只认自己支持的子集。常见卡点不是语法错，而是类型模糊或运行时依赖。
- 所有参数必须标注类型，例如
def forward(self, x: torch.Tensor) -> torch.Tensor:，不写类型注解会编译失败 - 不能用 Python 原生容器方法：
list.append()、dict.keys()要换成torch.cat()或显式循环 - 避免使用未导出的模块属性：
self.some_list如果是普通 Python list，得改成torch.nn.ParameterList或预分配 tensor - 调试时加
@torch.jit.ignore临时屏蔽可疑代码段，再逐个放开验证
混合转换时 trace 和 script 怎么拼？
现实模型很少非黑即白。骨干网络适合 trace，头部决策逻辑需要 script——关键在于“接口对齐”和“导出声明”。
立即学习“Python免费学习笔记（深入）”；
- 把静态部分单独封装成子模块，用
torch.jit.trace转换后赋值给成员变量（如self.backbone = torch.jit.trace(...)） - 动态部分写成独立函数，加
@torch.jit.export装饰器，并确保输入/输出类型明确 - 主
forward方法里调用这两部分时，传参必须是 tensor，不能穿 Python 对象（比如 dict 或 numpy array） - 保存前务必调用
traced_model.eval()和traced_model.requires_grad_(False)，否则 C++ 加载时可能因训练态行为异常而崩溃
C++ 加载 TorchScript 模型最常卡在哪？
不是模型没保存对，而是环境链断在了隐性依赖上。LibTorch 不报 Python 错，但会静默失败或 segfault。
- Python 端保存必须用
model.save("model.pt")，不能用torch.save——后者存的是 pickle，C++ 根本读不了 - C++ 端加载前要确认 LibTorch 版本和 PyTorch 编译版本严格一致（差一个小版本都可能 ABI 不兼容）
- 输入 tensor 必须和 trace/script 时 dtype、device 完全一致：Python 里用
torch.float32，C++ 就不能传torch::kFloat64 - 首次加载后建议立刻执行一次推理并检查输出 shape，别等请求进来才暴露 tensor 维度不匹配
真正麻烦的从来不是怎么转，而是哪段逻辑该用哪种方式转——模型越接近业务，控制流越复杂，就越得拆开看、分开试、逐层验。漏掉一个 @torch.jit.export 或一个类型注解，线上就可能挂掉，而且错误信息根本不告诉你具体哪行代码坏了。
