3. 环境搭建（下）：验证环境——用官方示例跑通第一个AI模型部署流程

好，上一节我们把STM32CubeMX、CubeIDE、X-CUBE-AI扩展包都装好了。说实话，装完只是第一步，真正让人心里踏实的是——能跑通一个完整的例子。

我记得刚接触这套工具链时，自己闷头配了半天，结果生成代码后一编译，报错一堆。后来才发现，是X-CUBE-AI版本和CubeMX没对齐。所以这一节，我带你走一遍官方示例，确保你的环境是真的“能用”。

3.1 选哪个官方示例？

STM32CubeAI提供了好几个示例，分布在不同的开发板下。我个人建议，新手先从Image Classification入手，也就是图像分类。为什么？

• 流程最完整：从模型导入到代码生成，再到板端运行，一步不缺
• 结果直观：LCD上直接显示分类结果，跑没跑对一眼就知道
• 硬件要求低：B-U585I-IOT02A或STM32F746G-DISCO都行，甚至NUCLEO-H743也能跑

你想想看，如果第一个例子就跑语音识别，麦克风、音频解码、FFT预处理……光调试硬件就得折腾半天。图像分类，摄像头一拍，LCD一显示，完事。

3.2 找到并打开示例工程

示例工程藏在X-CUBE-AI的安装目录里。以Windows为例，路径大概是：

C:\Users\你的用户名\STM32Cube\Repository\Packs\STMicroelectronics\X-CUBE-AI\8.1.0\Projects\STM32F746G-DISCO\Applications\AI

进去后你会看到一堆文件夹，比如Image_Classification、Object_Detection、Audio_Classification。我们选Image_Classification。

打开后，里面有个.ioc文件，双击它，CubeMX会自动启动。嗯，这里要注意：不要手动去改.ioc文件，直接用CubeMX打开就好。

3.3 配置模型文件路径

工程打开后，你会看到CubeMX的图形化界面。左侧菜单找到Software Packs -> X-CUBE-AI，点进去。

这里有个关键设置：Model选项卡。官方示例已经预置了一个模型路径，但如果你是自己下载的示例，路径可能不对。我遇到过这种情况——明明选了模型，但编译时提示找不到文件。后来发现是路径里有中文空格。

正确的做法是：点击Browse，找到示例目录下的network文件夹，里面有个.tflite或.h5文件。选中它，确认。

3.4 生成代码

配置完成后，点击右上角的GENERATE CODE按钮。CubeMX会帮你生成完整的STM32CubeIDE工程。

这个过程大概持续30秒到1分钟，取决于你的电脑性能。生成完成后，会弹出一个对话框，问你是否要打开工程。点Open Project。

我个人习惯是：生成后先不急着点Open，而是去工程目录下看一眼。确认Middlewares和X-CUBE-AI文件夹都生成了，里面有个Lib文件夹，放着AI推理的静态库文件。如果这个文件夹是空的，说明生成失败了。

3.5 编译与下载

工程在CubeIDE中打开后，先做一件事：检查编译器版本。在项目上右键 -> Properties -> C/C++ Build -> Settings -> Toolchains。确保你用的ARM GCC版本和CubeIDE自带的匹配。

然后直接点锤子图标（Build All）。第一次编译会慢一些，因为要编译AI库。我试过，大概2-3分钟。

编译成功后，控制台会输出：

Finished building: ../Core/Src/main.c
Finished building: ../X-CUBE-AI/App/app_x-cube-ai.c
Finished building target: AI_Image_Classification.elf

看到这个，说明编译通过了。接下来，用USB线连上开发板，点绿色箭头（Debug或Run）。

3.6 运行与验证

程序下载到板子后，会自动复位运行。如果你用的是STM32F746G-DISCO，LCD上会显示摄像头捕捉的画面，同时左上角会显示推理结果，比如“cat: 0.98”或“dog: 0.95”。

如果LCD没显示，别慌。先检查几个地方：

• 摄像头排线是否插紧——我遇到过好几次，排线松了导致画面全黑
• LCD背光是否亮——有些开发板需要按一下复位键才能点亮背光
• 串口是否有打印——用串口助手看，波特率115200，如果看到“AI inference started”说明程序在跑

3.7 性能数据怎么看？

程序运行后，串口会输出推理性能数据，类似这样：

AI inference time: 45 ms
AI cycles: 11250000
AI memory: 128 KB

这些数据很重要。45ms意味着每秒能跑22帧，对于图像分类来说够用了。如果推理时间超过100ms，说明模型太大或优化不够。

我一般会拿这个数据跟官方文档对比。比如官方说MobileNet V1在STM32F7上推理时间约50ms，你跑出来45ms，说明环境没问题。如果跑出来200ms，那就要检查是不是开启了调试模式（Debug模式会拖慢速度）。

3.8 常见问题与解决

问题	可能原因	解决办法
编译报错：undefined reference to `ai_xxxx`	AI库未正确链接	检查X-CUBE-AI配置，重新生成代码
下载后LCD黑屏	摄像头初始化失败	检查摄像头排线，复位开发板
推理结果全是0	模型输入数据格式不对	检查图像预处理代码，确保RGB顺序正确
串口无输出	串口引脚配置错误	核对CubeMX中UART的TX/RX引脚

说实话，第一次跑通这个示例，你会觉得“原来AI部署就这么回事”。确实，工具链帮我们做了90%的脏活累活。但剩下的10%，比如模型优化、内存管理、性能调优，才是真正考验嵌入式工程师的地方。

好，环境验证这一步走通了。下一节，我们开始讲怎么把自己的模型（比如你训练好的手势识别模型）导入到STM32CubeAI中。那才是真正有意思的部分。