4、运行时API概览：STM32Cube AI运行时库的架构、主要API分类、调用流程总览

当神经网络模型经过STM32Cube.AI工具链转换，生成C代码与权重数据后，真正让模型在MCU上“活”起来的，是运行时库（Runtime Library）。运行时库承担着模型推理的调度、内存管理、输入输出数据搬运以及与硬件加速单元的交互。本章将系统梳理STM32Cube AI运行时库的架构分层、API分类与调用流程，帮助开发者建立从“模型文件”到“MCU上可执行推理”的完整认知框架。

上图展示了STM32Cube AI运行时库的四层架构关系。从顶层到底层依次为：应用层（用户业务代码）、运行时API层（对外接口）、核心运行时引擎（内部实现）以及硬件抽象层（平台适配）。理解这个分层结构，是正确使用API、排查推理异常、优化性能的前提。

4.1 运行时库的架构分层与核心设计思想

STM32Cube AI运行时库并非一个简单的函数集合，而是一个面向资源受限MCU的轻量级推理引擎。其架构设计遵循三个核心原则：静态内存优先（避免动态分配）、分层解耦（应用与硬件隔离）、可裁剪性（按需编译）。

4.1.1 四层架构详解

运行时库的API设计遵循“句柄（Handle）”模式。开发者通过ai_network_create()获取一个网络句柄，后续所有操作都围绕该句柄进行。这种设计避免了全局变量污染，也方便在同一MCU上管理多个模型实例。

4.2 主要API分类与功能说明

根据功能职责，运行时API可分为五大类。每类API解决特定问题，开发者需要根据实际场景组合使用。

4.2.1 网络生命周期管理API

这类API负责模型的创建、初始化、销毁，是推理流程的起点和终点。

• ai_network_create()：创建网络实例，返回句柄。该函数会完成权重加载、内存池初始化。
• ai_network_init()：对已创建的网络进行参数初始化，通常在create后自动调用。
• ai_network_destroy()：释放网络占用的资源，重置句柄。
• ai_network_get_info()：获取网络元信息（输入/输出张量数量、形状、数据类型、量化参数等）。

4.2.2 输入输出数据访问API

MCU上的AI推理需要将传感器数据写入输入张量，并从输出张量读取结果。由于运行时库内部使用内存池管理张量，开发者不能直接访问原始数组，必须通过API获取张量指针。

// 获取输入张量指针
ai_float *input_data;
ai_input_data_get(network_handle, 0, (ai_handle*)&input_data, NULL);
// 填充数据（例如从ADC采集的波形数据）
for (int i = 0; i < input_size; i++) {
    input_data[i] = (float)adc_buffer[i] / 4095.0f;
}

对应的输出访问API为ai_output_data_get()，用法与输入一致。需要特别注意的是，输入输出张量的数据类型由模型转换时的量化设置决定，可能是ai_float、ai_i8或ai_u8。

4.2.3 推理执行API

这是最核心的调用，触发一次完整的模型前向计算。

• ai_network_run()：同步执行推理，阻塞直到计算完成。
• ai_network_run_async()：异步执行，配合回调函数使用，适用于RTOS环境。

在STM32H7系列上，ai_network_run()内部会检查是否有可用的硬件加速器（如MCE），若有则自动将算子卸载到加速器执行，否则回退到CPU内核函数。

4.2.4 错误处理与状态查询API

运行时库定义了统一的错误码机制，所有API返回ai_error结构体，包含类型和代码字段。

ai_error err = ai_network_run(network_handle);
if (err.type != AI_ERROR_NONE) {
    printf("推理失败: type=%d code=%d\r\n", err.type, err.code);
}

常见的错误类型包括：AI_ERROR_INVALID_HANDLE（句柄无效）、AI_ERROR_INVALID_SIZE（输入尺寸不匹配）、AI_ERROR_ALLOC_FAIL（内存分配失败）。

4.2.5 工具与调试API

包括ai_network_get_error()（获取详细错误信息）、ai_network_print_info()（打印网络信息到控制台）、ai_network_get_n_batches()（获取批处理数量）等。这些API在开发调试阶段非常有用，但在正式产品中建议关闭以节省Flash空间。

4.3 标准调用流程与代码骨架

一个典型的STM32Cube AI推理任务遵循“五步法”流程。下面以振动信号故障诊断为例，展示完整调用序列。

4.3.1 标准调用流程

1. 创建网络：调用ai_network_create()，传入模型配置结构体。
2. 获取输入输出信息：通过ai_network_get_info()获取张量形状和数据类型。
3. 填充输入数据：获取输入张量指针，将预处理后的数据写入。
4. 执行推理：调用ai_network_run()，等待计算完成。
5. 读取输出结果：获取输出张量指针，解析分类结果或回归值。

// 完整调用示例（伪代码）
ai_handle network_handle;
ai_network_info_t network_info;
ai_float *input_ptr, *output_ptr;

// 1. 创建网络
network_handle = ai_network_create(&network_params, AI_NETWORK_INIT);
if (network_handle == AI_HANDLE_NULL) { error_handler(); }

// 2. 获取网络信息
ai_network_get_info(network_handle, &network_info);
uint32_t input_size = network_info.inputs[0].size;
uint32_t output_size = network_info.outputs[0].size;

// 3. 填充输入
ai_input_data_get(network_handle, 0, (ai_handle*)&input_ptr, NULL);
memcpy(input_ptr, preprocessed_data, input_size * sizeof(float));

// 4. 执行推理
ai_error err = ai_network_run(network_handle);
if (err.type != AI_ERROR_NONE) { error_handler(); }

// 5. 读取输出
ai_output_data_get(network_handle, 0, (ai_handle*)&output_ptr, NULL);
float confidence = output_ptr[0]; // 假设二分类

4.3.2 案例拆解：电机振动故障分类

背景与约束：某工业设备需要实时监测电机振动状态，识别正常、轴承磨损、转子不平衡三类工况。硬件平台为STM32F746（Cortex-M7，216MHz），RAM 320KB，Flash 1MB。模型为1D-CNN，输入128个振动采样点，输出3个类别概率。

初始现象：直接调用ai_network_run()后，系统偶尔进入HardFault，且推理结果不稳定。

分析过程：通过调试发现，问题出在输入数据填充环节。开发者直接使用ai_input_data_get()返回的指针，但在下一次调用前，该指针可能被运行时库内部的内存池管理逻辑重新分配。此外，输入数据未进行归一化，导致量化误差放大。

解决方案：

• 在每次推理前重新获取输入指针，不缓存指针。
• 将输入数据归一化到[0,1]范围，与训练时保持一致。
• 使用ai_network_get_info()确认输入数据类型为ai_float，而非量化后的ai_i8。

结果对比：修复后，推理准确率从91.2%提升至97.8%，且连续运行72小时无异常。

4.4 常见误区与性能优化要点

在实际项目中，开发者常犯以下几类错误，导致推理失败或性能不达标。

4.4.1 误区一：忽略输入数据的布局与对齐

运行时库要求输入张量按特定字节对齐（通常为4字节或8字节）。如果使用#pragma pack(1)压缩结构体，可能导致对齐错误。正确做法是使用memcpy将数据拷贝到张量指针指向的内存，而不是直接强制类型转换。

4.4.2 误区二：混淆量化模型与浮点模型

当模型经过INT8量化后，输入张量类型变为ai_i8或ai_u8。此时如果仍按float类型填充数据，会得到完全错误的推理结果。必须通过ai_network_get_info()查询实际数据类型，并使用对应的量化参数（scale、zero_point）进行转换。

// INT8量化模型的输入填充示例
ai_i8 *input_ptr;
ai_input_data_get(network_handle, 0, (ai_handle*)&input_ptr, NULL);
for (int i = 0; i < input_size; i++) {
    float normalized_val = (float)raw_data[i] / 255.0f;
    input_ptr[i] = (ai_i8)(normalized_val / scale + zero_point);
}

4.4.3 误区三：在中断服务函数中调用推理API

推理过程可能耗时数毫秒至数十毫秒，且涉及内存池操作，不适合在中断上下文中执行。正确做法是将推理任务放入低优先级线程或主循环，通过信号量触发。

4.4.4 性能优化建议

• 内存池复用：避免频繁create/destroy，在系统初始化时创建一次网络，后续重复使用。
• 批量处理：如果模型支持多batch，尽量一次处理多帧数据，减少API调用开销。
• 关闭调试输出：使用编译宏AI_NETWORK_DEBUG_DISABLE关闭调试信息，可减少Flash占用和运行时间。
• 利用硬件加速：在STM32H7系列上，确保启用MCE（Machine Learning Core）或Neural-ART IP，运行时库会自动检测并加速卷积层。