2、ONNX与ONNX Runtime基础：ONNX模型格式、计算图、算子、模型文件结构、ONNX Runtime架构与C API概览

在深度学习部署领域，训练框架（如PyTorch、TensorFlow）与推理引擎（如ONNX Runtime、TensorRT）之间的“语言鸿沟”一直是工程落地的核心痛点。ONNX（Open Neural Network Exchange）作为中间表示层，将模型从训练框架中解耦；而ONNX Runtime（简称ORT）则作为高性能推理引擎，直接消费ONNX模型。理解这两者的底层结构，是使用C API进行嵌入式或服务端部署的前提。本章将从模型文件内部的字节布局出发，逐步拆解计算图与算子的语义，再深入到ONNX Runtime的会话（Session）与内核（Kernel）架构，最后给出C API的整体调用脉络。

上图展示了ONNX模型文件与ONNX Runtime执行栈之间的映射关系。左侧是静态的模型描述，右侧是动态的推理引擎。理解这条链路，是后续编写C API代码时正确设置选项、分配内存、解读错误码的基础。

2.1 ONNX模型格式：从protobuf到计算图

核心原理：ONNX模型本质上是一个使用Google Protobuf序列化的二进制文件。其顶层消息为ModelProto，内部包含GraphProto、OperatorSetIdProto（算子集版本）、ProducerName等字段。计算图（Graph）是模型的核心，它由节点（Node）、输入/输出张量（ValueInfo）、初始化器（Initializer）三部分构成。节点描述“计算操作”，初始化器存放权重和常量，而张量定义则声明了数据的名称、数据类型和维度信息。

判断方法：在工程中，我们通常不直接解析二进制，而是通过Python API或onnx库来检查模型结构。但C API开发者需要理解，OrtSessionOptionsAppendExecutionProvider等函数内部实际是在操作这些protobuf字段。例如，当模型包含Sequence或Map类型时，C API需要显式调用OrtCreateValueWithSequence等函数，因为标准张量API无法处理非张量类型。

2.2 算子（Operator）与图优化

核心原理：算子是计算图的最小执行单元。每个算子由OpType（如Conv、Gemm、LayerNormalization）和属性（Attribute）组成。ONNX Runtime在加载模型后，会执行图优化（Graph Optimization），包括常量折叠、算子融合（如Conv+ReLU融合为FusedConv）、冗余节点消除。这些优化在C API中通过OrtSessionOptionsSetGraphOptimizationLevel控制，分为ORT_DISABLE_ALL、ORT_ENABLE_BASIC、ORT_ENABLE_EXTENDED和ORT_ENABLE_ALL四个级别。

操作流程：在C代码中，优化级别的设置直接影响推理性能。例如，对于Transformer模型，开启ORT_ENABLE_ALL后，ORT会自动将多个Attention相关的算子融合为一个自定义算子，减少内核启动开销。但代价是首次加载时间变长（因为需要执行优化pass）。

// C代码示例：设置图优化级别
OrtSessionOptions* session_options;
OrtCreateSessionOptions(&session_options);
OrtSessionOptionsSetGraphOptimizationLevel(session_options, ORT_ENABLE_ALL);
// 加载模型
OrtSession* session;
OrtCreateSession(env, L"model.onnx", session_options, &session);

2.3 ONNX Runtime架构：会话、执行提供程序与内核

核心原理：ONNX Runtime采用分层架构。最上层是语言绑定（C/C++/C#/Python），中间是核心引擎（负责图优化、内存规划、执行调度），底层是执行提供程序（EP）。EP抽象了不同硬件后端：CPUExecutionProvider（默认）、CUDAExecutionProvider、TensorRTExecutionProvider等。每个EP内部维护一个算子内核注册表（Kernel Registry），将ONNX算子映射到具体硬件实现。

案例拆解：假设我们有一个包含Conv和Relu的模型，在CPU上运行时，ORT会调用mlas库的卷积实现；若切换到CUDA EP，则会调用cuDNN的卷积API。C API中通过OrtSessionOptionsAppendExecutionProvider_CUDA来添加EP。但需要注意，EP的优先级由添加顺序决定，第一个添加的EP优先级最高。

2.4 C API概览：核心对象与生命周期

核心原理：ONNX Runtime C API围绕几个不透明指针（Opaque Pointer）展开：OrtEnv（环境）、OrtSessionOptions（会话配置）、OrtSession（会话）、OrtValue（张量/值）、OrtMemoryInfo（内存描述）。所有API函数通过全局的OrtApi结构体访问，该结构体由OrtGetApiBase()->GetApi(ORT_API_VERSION)获取。

操作流程：典型的C API调用序列如下：

1. 初始化OrtEnv（全局唯一，线程安全）。
2. 创建OrtSessionOptions，设置优化级别、EP、日志等级。
3. 创建OrtSession，传入模型路径和选项。
4. 获取输入/输出名称、形状、类型。
5. 创建OrtValue，绑定输入数据指针。
6. 调用OrtRun执行推理。
7. 读取输出OrtValue，释放资源。

// 最小C API推理流程（伪代码）
const OrtApi* api = OrtGetApiBase()->GetApi(ORT_API_VERSION);
OrtEnv* env;
api->CreateEnv(ORT_LOGGING_LEVEL_WARNING, "test", &env);
OrtSessionOptions* opt;
api->CreateSessionOptions(&opt);
api->SetSessionGraphOptimizationLevel(opt, ORT_ENABLE_EXTENDED);
OrtSession* session;
api->CreateSession(env, L"model.onnx", opt, &session);
// ... 创建输入Tensor，执行Run，释放资源

2.5 模型文件结构深度解析与排障

核心原理：一个标准的ONNX文件包含以下关键段：ir_version（IR版本）、producer_name、graph（包含节点、初始化器、输入输出）。在C API中，我们通常不直接读取这些字段，但理解它们有助于诊断加载失败问题。例如，当模型使用ir_version=8而ORT仅支持到ir_version=7时，会报“Model IR version is too new”错误。

案例拆解：某次部署中，模型在Python下正常，但C程序加载失败。通过onnx库检查发现，模型包含一个Constant节点，其值为float64类型。而ORT的CPU内核默认不支持float64的某些算子。解决方案有两种：一是用onnx库将常量转换为float32；二是在C API中设置OrtSessionOptionsAddSessionConfigEntry，启用session.use_ort_model_bytes_directly=1（仅限ORT 1.14+），但根本解法是统一数据类型。