3. ONNX 模型详解：从标准到实战验证

ONNX 这个词，做模型部署的应该都不陌生。说白了，它就是深度学习模型的“通用语言”。

我最早接触 ONNX 是在一个嵌入式项目里，训练好的 PyTorch 模型死活跑不到目标芯片上。后来发现，只要转成 ONNX，大部分推理引擎都能认。嗯，从那时起我就养成了习惯——不管最终部署到哪，中间一定会过一道 ONNX。

3.1 ONNX 标准：为什么需要它？

ONNX（Open Neural Network Exchange）是微软和 Facebook 在 2017 年联合推出的开放标准。它的核心目标就一个：让模型在不同框架之间自由流动。

ONNX 的架构其实很清晰，就三层：

层级	作用	我常用的场景
IR（中间表示）	定义模型的计算图结构	查看网络拓扑、检查算子连接
算子集（Opset）	定义每个操作的标准接口	确认目标设备支持哪些算子
数据类型	定义张量的精度和形状	检查输入输出是否对齐

我个人习惯，拿到一个 ONNX 模型后，第一件事就是看它的 opset_version。为什么？因为不同版本的算子集，支持的算子种类和参数都不一样。版本太低，新算子没有；版本太高，老设备不支持。

3.2 ONNX 算子集：你的模型能跑吗？

ONNX 算子集（Opset）是定义好的标准操作库。从 Relu、Conv 到 LayerNorm，每个算子都有固定的输入输出和属性。

我在项目中遇到过最头疼的问题：模型转 ONNX 成功了，但上板推理时报错“Unsupported Op”。查了半天，发现是用了 opset 15 才有的 LayerNormalization，而 NPU 只支持到 opset 11。

常用的算子集版本对应关系：

Opset 版本	PyTorch 对应版本	新增关键算子
11	1.5 - 1.7	ScatterND, GatherND
13	1.8 - 1.10	Softmax, ReduceSum 改进
15	1.11 - 1.13	LayerNormalization, GroupNormalization
17	1.14+	DFT, STFT 等信号处理算子

你想想看，如果你的模型里用了 GroupNorm，但目标设备只支持 opset 11，那就得手动拆成多个基础算子。这就是为什么我建议：转换时尽量选低版本 opset，兼容性更好。

3.3 使用 ONNX Runtime 验证模型

转完 ONNX 后，千万别直接扔到板子上跑。先用 ONNX Runtime 在 PC 上验证一遍，这是最稳妥的做法。

我一般会写一个简单的验证脚本：

import onnxruntime as ort
import numpy as np

# 加载模型
session = ort.InferenceSession("model.onnx")

# 获取输入输出信息
input_name = session.get_inputs()[0].name
output_name = session.get_outputs()[0].name
input_shape = session.get_inputs()[0].shape

# 构造随机输入
dummy_input = np.random.randn(*input_shape).astype(np.float32)

# 推理
outputs = session.run([output_name], {input_name: dummy_input})

print("推理结果 shape:", outputs[0].shape)
print("推理结果前 5 个值:", outputs[0].flatten()[:5])

ONNX Runtime 还支持 性能 profiling。你可以用 session.run() 的 profiling 参数，看看每个算子的耗时。这在排查性能瓶颈时特别有用。

3.4 ONNX 模型可视化：一眼看清网络结构

模型可视化，说白了就是把计算图画出来。我常用的工具有两个：Netron 和 ONNX GraphSurgeon。

Netron 是图形化工具，拖进去就能看。我最喜欢它的节点搜索功能——想找某个算子，直接 Ctrl+F，秒定位。

ONNX GraphSurgeon 是代码工具，适合批量处理。比如我想把模型里所有的 Relu 替换成 LeakyRelu，用 GraphSurgeon 几行代码搞定。

下面是我用 GraphSurgeon 做可视化的一个例子：

import onnx_graphsurgeon as gs
import onnx

# 加载模型
graph = gs.import_onnx(onnx.load("model.onnx"))

# 打印所有节点
for node in graph.nodes:
    print(f"Op: {node.op}, Name: {node.name}, Inputs: {[i.name for i in node.inputs]}, Outputs: {[o.name for o in node.outputs]}")

# 统计算子类型
op_counts = {}
for node in graph.nodes:
    op_counts[node.op] = op_counts.get(node.op, 0) + 1
print("算子统计:", op_counts)

你想想看，如果模型有 200 个节点，手动找某个算子得翻到什么时候？用代码统计，一秒出结果。

3.5 ONNX 模型结构全景图

为了让你更直观地理解 ONNX 模型的完整结构，我画了一张图：

这张图把 ONNX 模型的四层结构都画出来了。从上到下依次是：元信息、计算图、张量数据、序列化格式。你想想看，一个 .onnx 文件里其实就装了这些东西。

3.6 实战：完整验证流程

最后，我分享一下我在项目中常用的 ONNX 验证流程：

1. 转换：用 torch.onnx.export() 导出模型，指定 opset 版本
2. 检查：用 onnx.checker.check_model() 检查模型合法性
3. 可视化：用 Netron 或 GraphSurgeon 查看网络结构
4. 推理验证：用 ONNX Runtime 跑一遍，对比原始框架的输出
5. 精度对比：计算输出差异，确保 max_diff < 1e-5

嗯，ONNX 这部分就讲到这里。记住一句话：ONNX 是模型部署的“通用语言”，掌握它，你就能在任意推理引擎之间自由穿梭。