3. ONNX模型结构解析：计算图与节点、张量与数据类型、模型元数据与版本管理

好，咱们今天来聊聊ONNX模型内部到底长什么样。说实话，我刚开始接触ONNX时，也把它当个黑盒——模型导出来能跑就行。直到有一次线上推理速度死活上不去，我打开模型一看，好家伙，里面多了十几个莫名其妙的Cast节点。从那以后，我养成了一个习惯：拿到任何ONNX模型，先拆开看看。

3.1 计算图与节点：模型的核心骨架

ONNX模型本质上就是一个有向无环图（DAG）。你想想看，神经网络里的每一层计算，在ONNX里都对应一个节点（Node）。节点与节点之间通过张量（Tensor）连接，数据从输入节点一路流到输出节点。

我个人习惯把计算图想象成一张「流水线图纸」。每个节点就是一个工位，干一件具体的事——比如卷积、激活、池化。工位之间用传送带（张量）连起来。嗯，就是这么回事。

节点（Node）的核心属性

每个节点都包含以下几个关键信息：

• op_type：操作类型，比如 Conv、Relu、Gemm。这是节点的「身份证」。
• inputs：输入张量名称列表。一个节点可以有多个输入。
• outputs：输出张量名称列表。一个节点通常只有一个输出。
• attributes：操作参数，比如卷积的 kernel_shape、strides、pads。
• domain：操作所属的域。标准操作是 "ai.onnx"，自定义操作可以自己定义。

计算图的拓扑结构

ONNX的计算图存储在 ModelProto.graph 中。你可以通过以下方式遍历所有节点：

import onnx

model = onnx.load("model.onnx")
graph = model.graph

for node in graph.node:
    print(f"节点名: {node.name}")
    print(f"操作类型: {node.op_type}")
    print(f"输入: {list(node.input)}")
    print(f"输出: {list(node.output)}")
    print("---")

我在项目中遇到过一个问题：模型推理速度比预期慢了一倍。打开模型一看，发现有个Reshape节点被放在了循环里，每次推理都要重新分配内存。说白了，这就是图结构不合理导致的性能瓶颈。

3.2 张量与数据类型：数据的载体

张量（Tensor）是ONNX里传递数据的唯一方式。你可以把它理解成一个多维数组，但比普通的数组多了些「元信息」。

张量的核心属性

属性	说明	示例
name	张量名称，全局唯一	"input_1"
dims	维度信息	[1, 3, 224, 224]
data_type	数据类型	TensorProto.FLOAT
raw_data	原始二进制数据（权重）	bytes

数据类型一览

ONNX支持的数据类型挺多的，但常用的就这几个：

• FLOAT (1)：32位浮点，最常用，模型权重和中间结果基本都是它。
• UINT8 (2) / INT8 (3)：8位整型，量化模型的主力。
• INT64 (7)：64位整型，通常用于shape信息、索引。
• DOUBLE (11)：64位浮点，精度要求高的场景用，但推理速度会慢不少。
• STRING (8)：字符串类型，元数据里偶尔出现。

ValueInfoProto：张量的「身份证」

在ONNX图里，每个张量都有对应的 ValueInfoProto 来描述它。你可以通过 graph.input 和 graph.output 获取输入输出张量的信息：

for input_info in graph.input:
    print(f"输入名称: {input_info.name}")
    print(f"数据类型: {input_info.type.tensor_type.elem_type}")
    print(f"维度: {[dim.dim_value for dim in input_info.type.tensor_type.shape.dim]}")

你想想看，如果输入输出的维度信息都不对，模型怎么可能跑得起来？所以每次导出模型后，我第一件事就是检查输入输出的shape和类型。

3.3 模型元数据与版本管理

元数据就像是模型的「身份证信息」。它记录了模型是谁生成的、用的什么框架、ONNX版本是多少等等。这些信息看似不起眼，但在实际部署中能救命。

模型元数据包含什么

ONNX的 ModelProto 里有个 metadata_props 字段，可以存储任意键值对：

# 查看模型元数据
for prop in model.metadata_props:
    print(f"{prop.key}: {prop.value}")

# 常见的元数据键
# - "model_author": 模型作者
# - "model_version": 模型版本号
# - "converted_from": 从哪个框架转换而来
# - "training_dataset": 训练数据集描述

我个人习惯在导出模型时，把模型的输入输出规范、预处理参数、甚至模型的预期精度都写进元数据里。这样别人拿到模型，一看就知道该怎么用。

版本管理：别让你的模型「失忆」

ONNX有自己的版本号体系，包括：

• IR版本（ir_version）：ONNX中间表示的版本，目前主流是7或8。
• Opset版本（opset_import）：操作集版本，决定了你能用哪些算子。
• 模型版本（model_version）：你自己定义的版本号，用于模型迭代管理。

如何查看和修改版本信息

# 查看版本信息
print(f"IR版本: {model.ir_version}")
print(f"Producer: {model.producer_name} {model.producer_version}")
print(f"Opset: {model.opset_import[0].version}")

# 修改模型版本号（用于模型迭代）
model.model_version = 2
model.metadata_props.append(
    onnx.StringStringEntryProto(key="model_version", value="2.0.0")
)

3.4 实战：手把手解析一个ONNX模型

光说不练假把式。咱们拿一个实际的ONNX模型来拆解一下：

import onnx
import onnx.numpy_helper as np_helper

model = onnx.load("resnet50.onnx")
graph = model.graph

print(f"=== 模型基本信息 ===")
print(f"节点数量: {len(graph.node)}")
print(f"输入数量: {len(graph.input)}")
print(f"输出数量: {len(graph.output)}")
print(f"初始值（权重）数量: {len(graph.initializer)}")

print(f"\n=== 输入输出详情 ===")
for input_info in graph.input:
    shape = [dim.dim_value for dim in input_info.type.tensor_type.shape.dim]
    print(f"输入: {input_info.name}, shape: {shape}")

for output_info in graph.output:
    shape = [dim.dim_value for dim in output_info.type.tensor_type.shape.dim]
    print(f"输出: {output_info.name}, shape: {shape}")

print(f"\n=== 前5个节点 ===")
for i, node in enumerate(graph.node[:5]):
    print(f"节点{i}: {node.op_type}, 输入: {list(node.input)}, 输出: {list(node.output)}")

运行这段代码，你就能看到模型的「骨架」了。嗯，这里要注意：如果节点数量特别多（比如几百个），别一次性全打印出来，否则控制台会刷屏。

3.5 总结与建议

好了，咱们把ONNX模型的结构拆了个遍。说白了，理解计算图、张量和元数据，是调优ONNX推理性能的第一步。我个人建议你养成三个习惯：

1. 拿到模型先看结构：用上面那段代码打印一下节点和输入输出，心里有个底。
2. 记录元数据：把模型的来源、版本、预处理参数都写进去，省得以后自己都忘了。
3. 关注opset版本：不同版本的算子行为可能不同，导出时固定一个版本，别乱升级。

下一章，咱们会深入聊聊如何用Netron可视化工具来「看」模型结构。相信我，可视化比看代码直观多了。