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

导出 TorchScript 与 ONNX

导出 TorchScript 与 ONNX

本课把一个可运行的 PyTorch 分类模型分别导出为 TorchScript 和 ONNX,并用重新加载与跨运行时推理验证结果一致,同时说明动态批次、控制流和算子兼容的处理边界。

学习目标

  • 根据部署运行时选择 TorchScript 或 ONNX
  • 为 ONNX 输入声明动态批次并完成结果校验
  • 定位控制流、输入形状和不支持算子导致的导出失败

选择导出格式

TorchScript 将模型转换为可保存、可由 PyTorch JIT 或 LibTorch 加载的程序,适合维护已有的 PyTorch 原生部署链路。ONNX 强调框架无关的计算图,通常交给 ONNX Runtime、TensorRT 等后端执行。

维度 TorchScript ONNX
主要运行时 PyTorch JIT、LibTorch ONNX Runtime、TensorRT 等
Python 依赖 可脱离 Python,由 C++ 加载 通常可脱离 PyTorch
动态能力 取决于 trace 或 script 的捕获方式 需显式声明动态形状与后端支持
适合场景 既有 PyTorch 部署链路 跨框架、跨语言或推理引擎优化

PyTorch 模型的两条导出链路

导出并验证两个模型

下面的主示例使用纯张量运算且没有数据相关分支,因此可以安全地用 torch.jit.trace。ONNX 导出使用 dynamo=True,并把 features 的第 0 维声明为 1~32 的动态批次。

python
from pathlib import Path

import numpy as np
import onnxruntime as ort
import torch
from torch import nn

class TinyClassifier(nn.Module):
    def __init__(self) -> None:
        super().__init__()
        self.network = nn.Sequential(
            nn.Linear(8, 16),
            nn.ReLU(),
            nn.Linear(16, 3),
        )

    def forward(self, features: torch.Tensor) -> torch.Tensor:
        return self.network(features)

def main() -> None:
    torch.manual_seed(7)
    output_dir = Path("artifacts")
    output_dir.mkdir(exist_ok=True)

    model = TinyClassifier().eval()
    example = torch.randn(2, 8)

    with torch.inference_mode():
        eager_output = model(example)

    # trace 只记录示例输入实际经过的张量运算路径。
    traced = torch.jit.trace(model, example, check_trace=True)
    torch.jit.save(traced, output_dir / "tiny_classifier.ts")

    loaded_ts = torch.jit.load(output_dir / "tiny_classifier.ts").eval()
    with torch.inference_mode():
        ts_output = loaded_ts(example)
    torch.testing.assert_close(eager_output, ts_output)

    # 仅让批次维动态,特征维仍固定为 8。
    batch = torch.export.Dim("batch", min=1, max=32)
    torch.onnx.export(
        model,
        (example,),
        output_dir / "tiny_classifier.onnx",
        input_names=["features"],
        output_names=["logits"],
        dynamic_shapes={"features": {0: batch}},
        opset_version=18,
        dynamo=True,
    )

    session = ort.InferenceSession(
        str(output_dir / "tiny_classifier.onnx"),
        providers=["CPUExecutionProvider"],
    )
    ort_output = session.run(
        ["logits"],
        {"features": example.numpy()},
    )[0]
    np.testing.assert_allclose(
        eager_output.detach().numpy(),
        ort_output,
        rtol=1e-4,
        atol=1e-5,
    )

    print("TorchScript verification: passed")
    print("ONNX Runtime verification: passed")
    print("Artifacts: artifacts/tiny_classifier.ts, artifacts/tiny_classifier.onnx")

if __name__ == "__main__":
    main()

预期结果:脚本在 artifacts 目录生成两个模型文件,并在断言通过后打印稳定的验证信息。运行环境需提前安装 torch、onnx、onnxscript、onnxruntime 和 numpy。

bash
python export_models.py

预期输出如下;导出器可能在这些关键行之前输出额外诊断日志。

text
TorchScript verification: passed
ONNX Runtime verification: passed
Artifacts: artifacts/tiny_classifier.ts, artifacts/tiny_classifier.onnx

理解动态批次的边界

动态批次不等于任意形状。示例只把第 0 维设为动态,因此 (1, 8)、(8, 8) 可以复用同一模型,而 (2, 10) 仍会失败,因为网络第一层固定接收 8 个特征。

采用较新的 ONNX 导出路径时优先使用 dynamic_shapes。维护旧的 dynamo=False 导出代码时可能看到 dynamic_axes,二者不要在未理解导出路径的情况下混用。动态范围也应贴近服务真实上限,避免后端为不可能出现的超大形状准备资源。

处理控制流与算子兼容

torch.jit.trace 不会理解普通 Python 分支的语义,只会记录示例输入走过的路径。模型包含由输入值决定的分支或循环时,应改写为可导出的张量控制流,或评估 torch.jit.script、torch.export 等更合适的方案。

ONNX 导出成功也不代表目标后端一定能执行。定位问题时按“最小输入复现、查看具体算子、确认 opset 与运行时支持、替换或分解不支持算子、再次做数值对比”的顺序处理。生产交付前还应使用多组正常输入和边界批次验证,而不是只验证导出时的单个样本。

本课总结

  • TorchScript 更贴近 PyTorch 原生运行时,ONNX 更适合跨运行时部署
  • 动态批次必须显式声明,并保留固定特征维等真实约束
  • 导出完成后必须重新加载模型,用目标运行时做数值一致性验证

下一课预告

下一课将把已初始化的模型封装为批量推理服务,加入请求校验、短窗口合批、错误返回和统一响应结构。

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

目录与阅读设置

阅读设置

17

记录一个想法

导出 TorchScript 与 ONNX

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

登录哪都通