📚 课程目录第3章 ONNX基础

3、ONNX基础：ONNX格式的由来、模型结构（计算图、节点、张量、算子）、如何用Netron查看模型、ONNX的opset版本与兼容性

在TinyML端侧部署的完整链路中，模型训练完成后的格式往往五花八门——PyTorch的.pt、TensorFlow的.pb或.h5、PaddlePaddle的.pdmodel。端侧推理引擎（如TensorFlow Lite Micro、CMSIS-NN、RV1126 NPU工具链）无法直接消费这些训练框架的私有格式。ONNX（Open Neural Network Exchange）正是为解决这一互操作性问题而诞生的中间表示格式。本章将深入剖析ONNX的由来、计算图结构、可视化工具Netron的使用方法，以及opset版本机制对部署兼容性的决定性影响。

上图展示了ONNX在模型转换链路中的核心位置：它作为训练框架与部署引擎之间的“通用语言”，将不同框架的模型统一为一种结构化的计算图描述。下面我们逐一拆解ONNX的格式细节。

3.1 ONNX格式的由来：为什么需要一种“中间表示”？

核心原理：ONNX最初由Facebook和Microsoft于2017年联合推出，其设计目标并非替代训练框架，而是定义一套开放、可扩展的计算图规范。训练框架负责模型精度优化，ONNX负责将训练好的模型“翻译”成与框架无关的中间表示，再由各推理引擎“翻译”成针对特定硬件优化的执行计划。这种“一次导出，多处部署”的理念，极大降低了模型从云端迁移到端侧（MCU、NPU、DSP）的工程成本。

判断方法：在实际项目中，判断是否需要引入ONNX，可参考以下标准：

训练框架与部署工具链不匹配（例如PyTorch训练，但端侧NPU只支持ONNX或TFLite）；
需要对比多个推理引擎（如ONNX Runtime、TensorRT、OpenVINO）的端侧性能；
模型需要跨平台发布（Android/iOS/嵌入式Linux/裸机RTOS）。

经验提醒：ONNX不是“万能转换器”。某些自定义算子（如自定义ROI Pooling变体）可能无法直接映射到ONNX标准算子集，需要额外编写自定义算子或改用“分块导出”策略。

3.2 ONNX模型结构：计算图、节点、张量、算子

核心原理：一个ONNX模型文件（.onnx，使用Protobuf序列化）本质上是一个有向无环图（DAG）。其顶层结构包含以下关键字段：

结构元素	说明	示例
Graph	整个计算图，包含所有节点、初始权重、输入输出	一个完整的MobileNetV2
Node	图中的单个运算单元，包含算子类型、输入/输出张量名、属性	Conv、Relu、Add、Reshape
Tensor	多维数组，包含数据类型（float32/int8）、形状（shape）、原始数据	权重矩阵 [64,3,3,3]
Operator (Op)	定义在opset中的运算逻辑，如Conv、Gemm、BatchNormalization	ai.onnx:Conv
ValueInfo	描述输入/输出张量的名称、类型、形状	input: [1,3,224,224]

操作流程：当Netron打开一个ONNX文件时，它实际上解析了上述结构并渲染为可视化图形。理解图结构的关键在于：

节点（Node）是计算单元，每个节点有唯一的op_type（如"Conv"）和输入/输出张量名；
张量（Tensor）是数据载体，分为初始权重（存储在initializer中）和中间激活值（运行时计算产生）；
算子（Op）的具体行为由opset版本决定，例如Resize算子在opset 10和opset 11中的坐标变换语义不同。

案例拆解：以PyTorch导出的一个简单卷积网络为例，其ONNX图包含约5个节点：Conv → BatchNormalization → Relu → GlobalAveragePool → Flatten → Gemm。每个节点都明确标注了输入张量名（如"input.1"）和输出张量名（如"conv1.output"）。权重张量（如卷积核）存储在initializer中，不占用输入端口。

3.3 使用Netron查看模型：从“黑盒”到“白盒”

核心原理：Netron是一个开源的模型可视化工具，支持ONNX、TFLite、Keras、PyTorch等多种格式。它不仅能展示图结构，还能查看每个节点的详细属性（如卷积的stride、padding、dilation）、张量的形状和数据类型，甚至能直接导出节点列表。

操作流程：

下载Netron（桌面版或浏览器版 netron.app）；
打开你的.onnx文件；
点击任意节点，右侧面板显示该节点的算子类型、输入/输出张量、属性字典；
点击张量名称，可查看其形状、数据类型和存储值（若为初始权重）。

实战场景：在TinyML部署中，Netron常用于以下排查：

检查输入输出形状：确认模型输入是否为[N,C,H,W]布局，输出是否为分类概率向量；
定位不支持的算子：例如端侧NPU不支持Gather或NonMaxSuppression，通过Netron快速搜索节点类型；
验证权重是否被正确折叠：例如BatchNormalization在导出时是否已融合到Conv中（减少端侧计算量）。

风险提示：Netron显示的“形状”是静态推导值。如果模型包含动态维度（如动态batch size），Netron会显示None或symbolic。端侧部署通常要求静态形状，需在导出时固定输入尺寸。

3.4 ONNX的opset版本与兼容性：部署失败的“隐形杀手”

核心原理：opset（Operator Set）是ONNX算子版本的集合。每个算子（如Conv、Resize）在不同opset版本中可能有不同的行为定义或新增属性。模型文件中的opset_import字段声明了该模型依赖的算子集版本。推理引擎必须支持该版本（或更高版本）才能正确执行。

判断方法：当端侧推理引擎加载ONNX失败时，优先检查以下兼容性矩阵：

opset版本	关键变化	端侧引擎常见支持情况
9	基础算子稳定，支持大多数CNN	广泛支持（TFLite转换器、ONNX Runtime）
10	新增`Resize`坐标变换模式、`ThresholdedRelu`	部分NPU工具链可能滞后
11	引入`DynamicQuantizeLinear`，`Resize`语义调整	需确认工具链是否适配
13	新增`ReduceL1/L2`等，`Softmax`支持axis属性	较新工具链支持
15+	支持`BFloat16`、`Optional`类型	端侧MCU通常不支持

操作流程：在PyTorch导出时，可通过opset_version参数控制：

import torch
model = torch.load('model.pth')
dummy_input = torch.randn(1, 3, 224, 224)
torch.onnx.export(model, dummy_input, 'model.onnx',
                  opset_version=11,  # 显式指定
                  input_names=['input'], output_names=['output'])

案例拆解：某团队在将YOLOv5s部署到瑞芯微RK3588 NPU时，初始导出使用opset 17，导致NPU工具链报错“Unsupported op: Resize”。分析过程：Netron显示Resize节点使用了coordinate_transformation_mode="half_pixel"，该模式在opset 11中才被完整定义，而工具链仅支持到opset 12。解决步骤：重新导出时设置opset_version=12，并手动将Resize替换为Upsample（旧版算子），最终NPU编译通过，推理速度提升15%。

经验总结：对于TinyML端侧部署，建议优先使用opset 11或12。这两个版本覆盖了绝大多数CNN算子，且兼容性最广。若必须使用高版本opset，务必先在目标推理引擎上做“冒烟测试”——加载一个最小模型（如单层Conv）验证兼容性。

3.5 常见误区与复盘

误区1：认为ONNX是“可执行文件”。实际上ONNX只是计算图描述，不包含推理逻辑，需要由推理引擎解释执行。
误区2：忽略opset_import字段。两个模型即使算子相同，若opset版本不同，行为可能不同（如Split在opset 13中新增了num_outputs属性）。
误区3：在Netron中看到“绿色节点”就认为算子被支持。Netron只负责可视化，不负责验证目标硬件的兼容性。
误区4：导出时使用默认opset版本。PyTorch默认opset随版本升级（当前为17+），直接导出可能导致端侧工具链无法解析。

复盘建议：在项目启动阶段，应建立“模型转换兼容性检查清单”：① 确认端侧推理引擎支持的opset范围；② 导出时固定opset版本；③ 用Netron检查关键节点类型；④ 在目标硬件上运行一个最小验证模型（如输入为全1张量）确认链路畅通。这四步能避免80%的部署兼容性问题。