机器学习与深度学习 / 系统课时
导出 TorchScript 模型
导出 TorchScript 模型
TorchScript 可以把一部分 PyTorch 模型转换为可序列化的 ScriptModule,再通过 torch.jit.save 保存并用 torch.jit.load 重新加载。它适合维护既有 TorchScript 或 LibTorch 部署链路,但当前 PyTorch 已将 TorchScript 标记为弃用,新项目应优先评估 torch.export。
学习目标
- 区分
torch.jit.trace与torch.jit.script的适用边界。 - 将一个
nn.Module导出为 TorchScript 文件并重新加载推理。 - 用输出形状和数值一致性检查导出结果,而不是只检查文件是否存在。
先判断 TorchScript 是否适合项目
TorchScript 文件保存的是可加载的模型程序与参数,不要求部署端重新定义原始 Python 模型类;但它仍需要兼容的 PyTorch Python 运行时或 LibTorch,并不是一个脱离运行时的独立可执行文件。
| 场景 | 选择 |
|---|---|
已有 C++/LibTorch 服务读取 .pt TorchScript |
继续维护 TorchScript,先锁定可用的 PyTorch/LibTorch 版本 |
| 新的 PyTorch 2.x 部署项目 | 优先评估 torch.export,不要把 TorchScript 当成默认新方案 |
forward 主要是固定张量算子路径 |
旧链路中可用 torch.jit.trace |
forward 含依赖输入数据的 Python 分支或循环 |
trace 可能固化示例输入走过的路径;旧项目才考虑 torch.jit.script,同时验证支持的 Python 子集 |
trace 最容易踩的坑是“导出成功但语义不完整”。例如分支条件取决于输入张量数值时,追踪只记录示例输入实际执行的那条路径,换一组输入可能得到错误结果。
导出并重新加载模型
完整链路是 nn.Module.eval() → 示例输入 → torch.jit.trace → torch.jit.save → torch.jit.load → 对比 eager 与导出模型输出。模型结构简单时,这条链足够直观,也便于写自动化验收。

下面的模型没有数据依赖分支,适合用 trace。示例先固定随机种子,再保存、加载,并用 torch.allclose 做数值验收。
from pathlib import Path
import torch
from torch import nn
class TinyClassifier(nn.Module):
def __init__(self) -> None:
super().__init__()
self.net = nn.Sequential(
nn.Linear(4, 8),
nn.ReLU(),
nn.Linear(8, 3),
)
def forward(self, x: torch.Tensor) -> torch.Tensor:
return self.net(x)
torch.manual_seed(0)
model = TinyClassifier().eval()
example = torch.randn(2, 4)
output_path = Path("tiny_classifier_ts.pt")
# trace 会记录 example 实际执行到的张量算子路径。
traced = torch.jit.trace(model, example)
torch.jit.save(traced, output_path.as_posix())
loaded = torch.jit.load(output_path.as_posix(), map_location="cpu")
loaded.eval()
with torch.inference_mode():
eager_output = model(example)
loaded_output = loaded(example)
print(f"saved={output_path.name}")
print(f"shape={tuple(loaded_output.shape)}")
print(f"match={torch.allclose(eager_output, loaded_output, rtol=1e-5, atol=1e-6)}")预期输出:
saved=tiny_classifier_ts.pt
shape=(2, 3)
match=True在较新的 PyTorch 版本中,运行时还可能额外打印 TorchScript 或 torch.jit.trace 的弃用警告;这不改变上面三个 stdout 验收结果。文件存在只证明序列化完成,match=True 才证明这个输入上的 eager 与加载后模型数值一致。
在 trace 与 script 之间做选择
选择方式时,先看 forward 的控制流,而不是看网络名字。卷积、线性层、激活等固定路径通常适合 trace;依赖输入内容决定分支、循环次数或容器操作时,trace 风险明显增加。
一个实用检查是准备至少两组能走不同逻辑的数据:如果模型理论上会根据输入正负、长度或阈值改变路径,就不能只拿一组示例输入做 trace 后宣布完成。旧项目若必须使用 torch.jit.script,还要确认类型标注、容器类型和 Python 语法都在 TorchScript 支持范围内。
验证导出边界
部署前至少做三层验收。第一层是文件:tiny_classifier_ts.pt 存在且大小大于 0。第二层是接口:用真实部署会出现的 batch shape 调用加载后的模型,例如 (1, 4)、(16, 4)。第三层是数值:对固定测试样本比较 eager 与 TorchScript 输出,浮点模型可从 rtol=1e-5、atol=1e-6 起步,再按模型精度策略调整。
还要单独验证设备和运行时版本。若服务端是 CPU,就用 map_location="cpu" 加载并在 CPU 上跑验收;若目标是 C++,应在实际 LibTorch 构建环境加载同一 .pt 文件做冒烟测试。模型含自定义算子、动态容器或特殊第三方扩展时,Python 里成功加载并不能替代目标运行时验收。
对于仍在运行的旧 TorchScript 系统,最稳妥的做法是把“导出 PyTorch 版本、目标 LibTorch 版本、输入 shape、数值容差、模型文件哈希”写进发布清单。对于新系统,则应把 TorchScript 视为兼容性方案,而不是新的默认部署格式。