2、ONNX基础：ONNX格式简介、模型结构（图、节点、张量）、常用工具（Netron、onnxruntime）与基本操作

ONNX（Open Neural Network Exchange）是深度学习模型互操作的核心标准。在部署排查场景中，理解ONNX的底层结构——尤其是输入输出命名规则如何与图（Graph）、节点（Node）、张量（Tensor）关联——是定位“输入名不匹配”“维度错误”“动态轴失效”等问题的前提。本章从格式定义出发，拆解模型内部的三层结构，并演示Netron与ONNX Runtime两大工具的实际操作流程，帮助学员建立从“黑盒模型”到“结构化计算图”的认知框架。

上图展示了ONNX模型从文件到工具操作的完整链路。左侧是物理存储层，中间是逻辑结构层，右侧是工程工具层。在实际部署中，我们通常从右侧工具入手，但排查问题的根源往往需要回溯到中间层的定义细节。下面逐一展开。

2.1 ONNX格式简介：为什么需要中间表示

核心原理：ONNX是一种基于Protobuf序列化的开放格式，用于定义深度学习模型的计算图。它不绑定任何特定框架，而是提供一套中立的算子集（Opset）和数据类型系统。PyTorch模型可通过torch.onnx.export导出，TensorFlow模型可通过tf2onnx转换，导出的ONNX文件可被任何支持ONNX的推理引擎（如ONNX Runtime、TensorRT、OpenVINO）加载。

ONNX文件的核心是ModelProto，它包含以下关键字段：

• ir_version：ONNX中间表示版本，影响语法解析规则。
• opset_import：算子集版本，决定可用算子种类和属性定义。
• graph：计算图主体，包含节点、张量、初始化器。
• metadata_props：可选键值对，常存放模型作者、转换工具信息。

判断方法：当部署环境报“unsupported operator”或“opset version mismatch”时，首先检查opset_import是否在推理引擎支持范围内。例如ONNX Runtime 1.15默认支持Opset 18，若模型导出时指定Opset 21，则需升级运行时或重新导出。

2.2 模型结构：图、节点、张量的层次关系

核心原理：ONNX的计算图（Graph）由三个核心元素组成：

1. 节点（Node）：表示一个算子操作，如Conv、Relu、MatMul。每个节点有op_type（算子类型）、input（输入张量名列表）、output（输出张量名列表）、attribute（算子属性，如卷积的kernel_shape）。
2. 张量（Tensor）：表示数据流，分为三类——图输入（用户需提供的数据）、图输出（模型推理结果）、中间张量（节点间传递的临时数据）。每个张量有名称、数据类型（float32/int64等）、形状（shape）。
3. 初始化器（Initializer）：存放权重和偏置等常量张量，它们不暴露为图输入，而是直接嵌入模型文件。

命名规则的关键点：在ONNX中，张量名称是全局唯一的字符串。节点通过名称引用输入输出张量，因此输入输出命名直接决定了API调用时的参数名。例如PyTorch导出时若未指定input_names，默认名称为“input.1”“input.2”等，部署时就必须使用这些名称。

操作流程：使用Python检查模型结构：

import onnx
model = onnx.load("model.onnx")
graph = model.graph
# 查看输入
for inp in graph.input:
    print(f"输入名: {inp.name}, 类型: {inp.type.tensor_type.elem_type}, 形状: {[d.dim_value for d in inp.type.tensor_type.shape.dim]}")
# 查看输出
for out in graph.output:
    print(f"输出名: {out.name}, 类型: {out.type.tensor_type.elem_type}")
# 查看节点数量
print(f"节点数: {len(graph.node)}")
# 查看初始化器数量
print(f"权重数: {len(graph.initializer)}")

案例拆解：某团队部署一个图像分类模型，导出时未指定输入输出名称。使用Netron打开后发现输入名为“input.1”，输出名为“output.1”。在ONNX Runtime中调用时，必须使用这两个字符串作为feed和fetch的参数名。若团队内部约定使用“image”和“logits”，则需在导出时显式指定：

torch.onnx.export(model, dummy_input, "model.onnx",
                  input_names=["image"], output_names=["logits"],
                  dynamic_axes={"image": {0: "batch"}, "logits": {0: "batch"}})

常见误区：初学者常混淆“张量名称”与“变量名”。ONNX中的名称是纯字符串标识，与Python变量无关。修改名称需通过onnx.utils或重新导出，不能直接编辑二进制文件。

2.3 常用工具：Netron可视化与ONNX Runtime推理

核心原理：Netron是一个轻量级模型可视化工具，支持ONNX、TensorFlow、PyTorch等格式。它解析模型文件后，以节点图形式展示计算流，点击节点可查看详细属性（算子类型、输入输出张量形状、属性值）。ONNX Runtime是微软开源的跨平台推理引擎，提供Python/C++/C#等接口，支持CPU、GPU、NPU多种执行提供程序。

操作流程：

1. Netron使用：直接打开model.onnx文件，左侧为节点列表，右侧为属性面板。排查输入输出命名时，点击最左侧的“输入”节点，即可看到完整的输入张量名、数据类型、形状（含动态轴标注）。
2. ONNX Runtime推理：

import onnxruntime as ort
import numpy as np

sess = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])
# 获取输入输出信息
input_info = sess.get_inputs()
output_info = sess.get_outputs()
print(f"输入: {[(i.name, i.shape, i.type) for i in input_info]}")
print(f"输出: {[(o.name, o.shape, o.type) for o in output_info]}")

# 构造输入数据（注意名称和形状）
input_data = np.random.randn(1, 3, 224, 224).astype(np.float32)
result = sess.run([output_info[0].name], {input_info[0].name: input_data})
print(f"输出形状: {result[0].shape}")

案例拆解：某推荐系统团队部署一个排序模型，使用ONNX Runtime在CPU上推理。初始现象是推理速度慢（单次50ms），且偶发报错“input name mismatch”。分析过程：

• 使用Netron查看模型，发现输入名为“float_input:0”，而代码中feed的是“input”，导致运行时错误。
• 修正名称后，进一步分析性能瓶颈。通过sess.get_profiling()启用性能分析，发现Transpose算子耗时占比30%。
• 优化方案：在导出时调整维度顺序，避免推理时Transpose；同时将执行提供程序改为“CPUExecutionProvider”并开启graph_optimization_level=ort.GraphOptimizationLevel.ORT_ENABLE_ALL。
• 结果对比：优化后单次推理降至18ms，吞吐量提升2.7倍。

复盘经验：部署排查应遵循“先结构后性能”的顺序。先通过Netron确认输入输出名称、形状、数据类型完全匹配，再考虑性能优化。很多性能问题源于模型结构不合理（如多余的Transpose、Reshape），而非推理引擎配置。

2.4 基本操作：加载、校验、修改与转换

核心原理：ONNX的Python API提供完整的模型操作能力。加载模型使用onnx.load，保存使用onnx.save。校验模型完整性使用onnx.checker.check_model，它会检查图结构是否合法、算子属性是否完整、张量形状是否一致。修改模型通常涉及重命名张量、修改维度、删除节点等操作。

操作流程：重命名输入输出张量：

import onnx
from onnx import helper, TensorProto

model = onnx.load("model.onnx")
# 修改输入名称
for inp in model.graph.input:
    if inp.name == "old_input_name":
        inp.name = "new_input_name"
# 同步修改所有引用该名称的节点输入
for node in model.graph.node:
    for i, name in enumerate(node.input):
        if name == "old_input_name":
            node.input[i] = "new_input_name"
# 保存
onnx.save(model, "model_renamed.onnx")

案例拆解：某自动驾驶团队需要将感知模型从PyTorch导出为ONNX，并部署到TensorRT。初始现象：TensorRT转换失败，报错“scale is zero”。分析过程：

• 使用Netron检查模型，发现BatchNorm层在导出时被折叠为Conv+Scale，但Scale的scale参数在推理时出现0值。
• 进一步检查训练代码，发现模型处于训练模式时BatchNorm的running_var未更新，导致导出时scale计算异常。
• 解决方案：在导出前调用model.eval()，并确保BatchNorm层已冻结（running_mean/var固定）。
• 结果对比：重新导出后TensorRT转换成功，推理精度与PyTorch一致。

常见误区：修改模型时只改graph.input的名称，却忘记更新节点引用，导致图结构断裂。正确做法是遍历所有节点，同步更新输入输出名称。此外，修改形状时需注意动态轴与静态轴的兼容性，动态轴在dim_param字段中定义，修改时需保持一致性。