机器学习与深度学习 / 系统课时
导出 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。生产项目应把这些信息写进模型发布清单,避免服务端猜测张量契约。

导出并做结构校验
环境需要 torch、onnx、onnxscript 和 onnxruntime。下面把权重设成确定值,因此输出可重复;真实项目只需把 TinyClassifier 替换为你的模型与已加载权重。
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}")预期输出:
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 与数值误差在约定范围内。