STM32CubeMX 部署 AI 模型全流程指南

当时钟以及串口等相关基础配置设置完成后即可进行 AI 模型的部署，在图形化界面中选择 Software Packs，并在弹出的选项框中选择 Select Components，或者直接按下键盘上的 Alt+O 快捷键

![图片：Software Packs 选择]

在弹出的新窗口中进行相应模型功能的使能和添加工作，在对应的选项框中打勾，并选择对应的模式

![图片：组件选择界面]

选择 X-CUBE-AI 折叠选项中的 Core 之后即可激活对应的 AI 功能，随后下面的选项框中就是在选择不同的模式，三种模式的应用场景各不相同

• SystemPerformance 模式主要用于评估在 STM32 硬件上的实时性能指标（如推理时间、CPU 负载等），主要应用于模型部署前的性能分析
• Validation 模式主要用于验证模型转换后的准确性，该模式可以在桌面环境和 MCU 中进行验证，主要应用于模型转换后的可靠性检查，防止压缩以及量化导致的精度损失
• Application Template 模式主要目的为提供 AI 模型的框架，便于用户添加对应的业务逻辑，相应的功能需要用户自行扩展，例如传感器数据采集等等，此模式应用于实际的落地项目中

根据我们目前的需求来说，我们不需要进行 AI 模型的可靠性检测，因为别人已经完成了这一部分操作，因此我们只需要进行模型的部署，以及模型的调用工作即可，在此我们选择 Application Template 模式
选择成功后在左侧的侧边栏中选择最底部的折叠选项卡，在随后弹出的新选项中选择 X-CUBE-AI，并在侧边栏右侧的新窗口中点击 Add network 选项为当前项目中添加新的 AI 神经网络模型

![图片：Add Network 选项]

接下来我们就可以在弹出的新窗口中进行 AI 模型的相关配置

![图片：模型配置界面]

当前界面中的选项作用依次如下：

• network 所在栏代表的是当前 AI 模型的名称，支持用户自定义
• Keras 所在栏代表 AI 模型文件的格式，当前 CubeMX 支持三种 AI 模型的格式，分别是 Keras(对应 AI 模型文件后缀为.h5)、TFLite(对应 AI 模型文件后缀为.tflite) 以及 ONNX（对应 AI 模型后缀为.onnx)，我们在使用这些 AI 模型的时候只需要注意选择合适的文件类型以及相应对应的文件格式即可
• Compression 代表压缩等级，当当前 AI 模型体积较大无法完整写入 MCU 时可以使用当前选项，对 AI 模型进行适当的压缩，以减少资源消耗
• Optimization 代表优化等级，即会对当前 AI 模型进行空间优化以及推理时间优化等
• Validation inputs 作用为提供验证数据源，当选则 Random numbers 时代表使用随机生成的数据进行验证，当然我们也可以使用自己提前准备好的数据进行验证
• Validation outputs 控制验证输出结果的处理方式，这个选项使用到的频率较低
• 下面的 Complexity、Used Flash 以及 Used Ram 在没有选择 AI 模型时展示了当前的 MCU 的硬件资源，即当前真展示的当前使用的 MCU 有着 1MB 的 Flash 以及 512kb 的 Ram，用电脑的概念来类推就是当前 MCU 有 1MB 的磁盘和 512KB 的内存
• Analyze 选项的作用为验证当前 AI 模型能否在 MCU 上正常运行，例如倘若 AI 模型的体积较大时便会出现警告
• validate on desktop 以及 validate on target 就是分别在 PC 端的 MCU 端进行模型的可靠性验证

了解了 AI 模型配置面板的基本功能后选择合适的 AI 模型类型，本次我们使用的 AI 模型类型文件的后缀为.tflite，依次需要选择 TFLite 类型的 AI，选择完成后点击 Browse 选项，随后在对应的文件夹中找到下载好的 AI 模型

![图片：模型文件选择]

随后点击 Analyze 选项，当结果不报错时即代表模型可以正确烧录到 MCU 中

![图片：模型分析结果]

从分析界面中可以查看到 AI 模型占用的 AI 资源，Flash 和 Ram 等

![图片：资源占用显示]

如果 AI 模型占用的资源超过了当前选型的芯片则可以尝试使用 Compression 选项对模型进行压缩，随后我们点击进入项目配置界面填写相应的工程名称以及使用的 IDE（本次使用 MDK_ARM)

![图片：工程配置界面]

随后点击对应的 Code Generator 栏目并进行相应改进

![图片：代码生成器设置]

最后即可点击右上角的 Generator CODE 即可一键生成对应的工程

模型使用

生成文件介绍

项目生成后我们用 Keil MDK 打开项目后发现当前项目于先前的项目不同的地方在于多了一个新的文件夹，文件夹中的文件都为与 AI 模型相关的文件

![图片：新增 AI 文件目录]

因此我们只需要了解新增文件中的内容就可以轻松实现 AI 模型的调用
新增文件中有 4 个.c 文件，每个 C 文件又对应一个头文件，因此相当于新增了 8 个与 AI 模型有关的新文件，但是这并不意味着我们需要详细了解每一个文件中的内容，这几个文件的作用各不相同：

• network.c/network.h 文件：这两个文件的名称与我们在添加 AI 模型时自定义的 AI 模型名称相同，因此不难推出这两个文件中存储了 AI 模型的相关信息，其中 C 文件中存储了模型的结构、接口函数的实现代码，头文件中声明了模型的接口函数、宏定义等；
• network_data.c/network_data.h 文件：这两个文件同样与模型本体信息有关，其中存放的是存储模型的权重 (Weights) 和偏置 (Bias) 等参数，这些通常是常量数据，存储在 Flash 中
• network_data_params.c/network_data_params.h：该文件是连接您训练好的 AI 模型和 STM32 嵌入式硬件的桥梁，当前文件相当于 AI 模型的数据仓库，AI 依赖此文件中的内容才能够正常进行推理工作

上述文件在开发时有一个共同的特点就是我们不需要也不能够修改文件中的内容，我们只需要大致了解文件中的内容即可，具体的 AI 运行逻辑函数的编写大多在 app_x-cube-ai.c 文件中编写，其中为我们提供了空的模板函数，我们可以在其中完善自己需要的业务逻辑，如果觉得麻烦也可以直接在 main.c 文件中直接编写对应的函数

代码编写流程

由于 CUBEMX 的 AI 模型库并不开源，因此如果我们想要进行 AI 模型初始化以及 AI 推理等函数功能的实现就必须要调用官方提供的 API 函数，上述文件中我们提到 AI 模型的函数接口都在 network.h 中进行了对应声明，因此我们可以在该头文件中查找对应的 API 函数，在这里简单介绍一下常用的 API 函数以及其对应的功能

• ai_network_create：创建模型实例，分配 AI 模型的基础内存
• ai_network_init：初始化模型，设置权重和激活内存
• ai_network_run：执行一次推理，并获取输出
• ai_network_inputs_get：获取输入缓冲区的指针
• ai_network_outputs_get：获取输出缓冲区的指针，用于获取输出
• ai_network_get_error：在 API 调用失败后，获取并清除最近的错误码

至于如何使用官方提供的 API 函数这里推荐大家可以去看看意法半导体官方提供的操作案例

https://wiki.stmicroelectronics.cn/stm32mcu/wiki/AI:FP-AI-MONITOR1_how_to_integrate_a_different_AI_Model_for_Human_Activity_Recognition_(HAR)

当你看完这些文章后应该就对 AI 初始化函数和 AI 模型运行过程的函数有了大致的了解，接下来就让我们尝试着手编写这些函数
接下来的函数的声明和定义都在 main.c 文件中完成，主要是为了减少操作流程

重写 fputc 函数

本次程序中将会调用 AI 模型来实现将对应的角度的正弦值通过串口输出到 PC 端，由于不同的 MCU 对应的串口引脚不同为了减少复刻难度我们可以将串口输出统一通过 printf 函数来实现：

1. 由于 printf 函数的底层实现依赖的是 fputc 函数，因此我们只需要重写 fputc 函数即可，在此之前你需要先使能一个可以与 PC 端进行数据收发的串口，确保可以正常向 PC 进行数据发送后才开始进行下一步的操作
2. 重写部分代码如下，将 huart1 更改为自己程序中对应的且已经使能成功的串口即可

int fputc(int ch, FILE *f){HAL_UART_Transmit(&huart1,(uint8_t*)&ch,1, HAL_MAX_DELAY);return ch;}

在 Keil MDK 主界面中点击设置后在随后弹出的界面中选择 Use MicroLIB 即可

AI 初始化函数

在初始化函数中我们需要实现获取模型对应参数、模型创建、初始化模型以及获取输入输出缓冲区指针操作，这些操作要想实现看起来无从下手，但是还记得之前提到的 network.c 文件官方提供的 API 函数吗，我们接下来要进行的操作官方都已经生成了对应的 API 函数，我们只需要调用它们就可以了，具体的代码实现如下

void AI_Model_Init(void){ ai_error err; ai_network_params params;printf("Initializing AI Model...\r\n");//调用参数获取 API 函数获取 AI 模型参数if(!ai_network_data_params_get(&params)){printf("Failed to get network params\r\n");Error_Handler();}//调用创建模型 API 函数创建模型实例 err =ai_network_create(&network, AI_NETWORK_DATA_CONFIG);if(err.type != AI_ERROR_NONE){printf("AI Model Creation Failed\r\n");Error_Handler();}//调用初始化 API 函数初始化模型if(!ai_network_init(network,&params)){printf("AI Model Initialization Failed\r\n"); err =ai_network_get_error(network);printf("Initialization Error\r\n");Error_Handler();}//调用对应 API 函数获取输入输出缓冲区指针 ai_input =ai_network_inputs_get(network,NULL); ai_output =ai_network_outputs_get(network,NULL);printf("AI Model Initialized Successfully.\r\n");}

AI 推理函数

AI 推理函数主要作用为处理输入的角度并尝试求取它们的正弦值，函数执行逻辑大致为：

• 对输出数据进行量化处理，确保所有输入的角度都在有效范围内
• 将数据进行量化后传递给 AI 模型进行计算
• 从输出缓冲区中读取相应数据并进行反量化处理

具体代码实现如下

/** * @brief 运行 AI 模型进行推理 * @param angle_deg: 输入的角度值（0-360 度） * @retval 模型推理出的正弦值（反量化后的 float 值） */float AI_Model_Run(int angle_deg){ ai_i32 batch;float real_output;//角度预处理：将 0-360 度映射到 0-255 范围 // 计算：normalized_angle = (angle % 360) × 255 ÷ 360uint8_t normalized_angle =(uint8_t)((angle_deg %360)*255/360);//量化处理：将 0-255 范围转换到 int8_t 的标准范围 (-128 到 127) // 计算：quantized_input = normalized_angle - 128 int8_t quantized_input =(int8_t)(normalized_angle -128);// 将预处理后的数据写入模型输入缓冲区*((int8_t*)(ai_input[0].data))= quantized_input;// 执行模型推理 batch =ai_network_run(network, ai_input, ai_output);if(batch !=1){printf("AI Model Run Failed. Batch: %ld\r\n", batch);Error_Handler();}// 从模型输出缓冲区读取量化结果int8_t quantized_output =*((int8_t*)(ai_output[0].data));//反量化处理：将量化输出转换为真实的正弦值/* 使用 network.c 中定义的量化参数： * scale = 0.008472006767988205f * zero_point = 4 * 计算：real_output = (quantized_output - zero_point) × scale */ real_output =(quantized_output -4)*0.008472006767988205f;return real_output;}

main 函数调用

完成上述函数的内容后即可在主函数中进行函数的调用
首先调用模型初始化函数

//初始化 AI 模型AI_Model_Init();printf("Starting AI Mode");

随后在主循环中调用 AI 推理函数，主循环中实现了从 0 度开始每隔 10 度输出一次对应角度的正弦值，主要执行逻辑如下：

1. 内部循环每隔 10 度进行一次计算
2. 调用 AI 推理函数计算对应的角度正弦值
3. 调用数学库中的正弦函数计算角度对应的准确正弦值
4. 计算两种正弦值的无差别
5. 输出结果

代码内容如下

while(1){/* USER CODE END WHILE *//* USER CODE BEGIN 3 */// 遍历 0-360 度，步长为 10 度，进行正弦值推理验证for(int angle_deg =0; angle_deg <=360; angle_deg +=10){//调用 AI 模型推理当前角度的正弦值float sine_value =AI_Model_Run(angle_deg);// 计算真实的正弦值用于对比验证（使用数学库 sinf 函数）float real_sine =sinf(angle_deg *3.14159265f/180.0f);// 计算模型输出与真实值的绝对误差float error =fabsf(sine_value - real_sine);//输出结果printf("Angle: %3d deg -> AI Output: %7.4f, Real: %7.4f, Error: %6.4f\r\n", angle_deg, sine_value, real_sine, error);HAL_Delay(100);}printf("\r\nCycle complete. Starting again...\r\n\r\n");HAL_Delay(2000);}

观察输出结果

完成上述代码编写操作之后点击编译运行即可将程序烧录到单片机中，此时打开串口调试工具，连接对应端口，即可查看输出

![图片：串口输出结果]

至此程序的编写就全部完成了

总结

综合模型获取以及模型嵌入的全过程我们发现模型的使用并不困难，CUBEAI 已经为我们生成了便捷可靠的 API 函数，在本阶段我们只需要多进行几次模型下载和使用的操作，熟悉了总体的流程后在后续的学习过程中就可以加速我们的开发流程了