机器学习与深度学习 / 系统课时

导出 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 与导出模型输出。模型结构简单时,这条链足够直观,也便于写自动化验收。

TorchScript 从动态图模型到部署文件的导出链路

下面的模型没有数据依赖分支,适合用 trace。示例先固定随机种子,再保存、加载,并用 torch.allclose 做数值验收。

python
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)}")

预期输出:

text
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 视为兼容性方案,而不是新的默认部署格式。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

导出 TorchScript 模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通