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

导出 ONNX 模型

导出 ONNX 模型

把训练好的 PyTorch 模型交给 ONNX Runtime、TensorRT 或其他推理框架前,不能只确认“文件导出了”。本课用一个可运行模型完成导出、ONNX 结构检查和跨运行时数值比对,最终得到可验证的 tiny_classifier.onnx。

学习目标

  • 使用当前 PyTorch 的 Dynamo ONNX exporter 导出模型
  • 用 onnx.checker 与 ONNX Runtime 验证模型可加载、可推理
  • 用数值误差阈值判断 PyTorch 与 ONNX 输出是否一致

固定模型状态与导出契约

示例面向 PyTorch 2.6+ 的 Dynamo ONNX exporter。导出前调用 model.eval(),避免 Dropout、BatchNorm 等训练态行为改变结果;同时固定输入形状 (2, 4)、输入名 features、输出名 logits 和 opset 18。生产项目应把这些信息写进模型发布清单,避免服务端猜测张量契约。

PyTorch 模型导出 ONNX 并验证的一致性链路

导出并做结构校验

环境需要 torch、onnx、onnxscript 和 onnxruntime。下面把权重设成确定值,因此输出可重复;真实项目只需把 TinyClassifier 替换为你的模型与已加载权重。

python
import numpy as np
import onnx
import onnxruntime as ort
import torch
from torch import nn
class TinyClassifier(nn.Module):
    # 固定权重让跨运行时比对结果可重复。
    def __init__(self):
        super().__init__()
        self.fc = nn.Linear(4, 3)
        with torch.no_grad():
            self.fc.weight.copy_(torch.tensor([
                [1.0, 0.0, 0.0, 0.0],
                [0.0, 1.0, 0.0, 0.0],
                [0.0, 0.0, 1.0, 0.0],
            ]))
            self.fc.bias.copy_(torch.tensor([0.1, 0.2, 0.3]))
    def forward(self, x):
        return self.fc(x)
model = TinyClassifier().eval()
x = torch.tensor([[1.0, 2.0, 3.0, 4.0], [4.0, 3.0, 2.0, 1.0]])
with torch.inference_mode():
    torch_out = model(x).numpy()
# 导出契约固定输入输出名称与 opset。
torch.onnx.export(
    model,
    (x,),
    "tiny_classifier.onnx",
    input_names=["features"],
    output_names=["logits"],
    opset_version=18,
    dynamo=True,
)
onnx_model = onnx.load("tiny_classifier.onnx")
onnx.checker.check_model(onnx_model)
# 用目标运行时执行同一输入,避免只验证文件结构。
session = ort.InferenceSession(
    "tiny_classifier.onnx",
    providers=["CPUExecutionProvider"],
)
onnx_out = session.run(["logits"], {"features": x.numpy()})[0]
consistent = np.allclose(torch_out, onnx_out, rtol=1e-5, atol=1e-5)
print("onnx_check=ok")
print(f"torch_shape={torch_out.shape}")
print(f"onnx_shape={onnx_out.shape}")
print(f"consistent={consistent}")

预期输出:

text
onnx_check=ok
torch_shape=(2, 3)
onnx_shape=(2, 3)
consistent=True

验证数值而不只验证文件

onnx.checker.check_model 主要检查 ONNX 图是否符合格式和算子约束,不能证明语义与 PyTorch 完全一致。真正的交付门槛应包含同一批输入的输出比对,例如分类 logits 常用 rtol=1e-5, atol=1e-5 起步;如果模型含低精度算子或后端融合,应根据误差分布再放宽阈值,而不是直接忽略差异。

固定形状导出的本例只接受 (2, 4)。如果线上请求的 batch 大小会变化,应在导出阶段显式声明动态 shape,并在服务启动时读取 session.get_inputs() 校验名称、dtype 与维度。输入名、dtype 或预处理顺序不一致,通常比 ONNX 文件本身损坏更常见。

常见失败与定位顺序

遇到 UnsupportedOperatorError 时,先确认算子是否被目标 opset 和当前 exporter 支持,再考虑改写模型算子;不要先盲目提高 opset。若 ONNX Runtime 报输入维度错误,先打印会话输入元数据并与实际数组 shape 对照。若结构检查通过但 consistent=False,优先检查 eval()、随机算子、预处理和 dtype,再定位到具体中间节点。

一个可交付的 ONNX 模型至少要同时满足:ONNX checker 通过、目标 Runtime 能创建会话、真实代表性输入能推理、输出 shape 与数值误差在约定范围内。

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

目录与阅读设置

阅读设置

17

记录一个想法

导出 ONNX 模型

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

登录哪都通