1. 先说清楚 raw 文件在 CubeAI 流程里的分量1.1 raw 文件到底是什么谁在用它STM32CubeAI Studio 升级到 v1.2 之后不少朋友遇到同一个现象工程编译正常、模型也能在板子上跑起来但去输出目录里翻之前那个熟悉的.raw文件怎么都找不到了。一时间有人以为是自己工程配置被重置有人以为是杀毒软件误删还有人干脆重新生成了一遍工程结果还是一样。先把这个 raw 文件的位置说清楚。在 STM32CubeAI 的典型工作流里你训练好的神经网络模型经过转换之后会得到两部分东西一部分是网络结构的 C 代码包括层定义、前向推理函数、内存池分配这些逻辑另一部分是模型的权重数据也就是成千上万个浮点数或者量化后的整型数。raw 文件就是这份权重数据的纯二进制形式不带文件头、不带格式说明就是一块裸数据。这块裸数据在什么场景下会被用到最常见的有两类第一类是外部存储器部署。STM32 内部 Flash 往往有限一个稍大一点的模型权重动辄几百 KB 甚至上 MB塞进内部 Flash 会非常吃力。这时候常规做法是把 raw 文件烧写到外部 SPI Flash 或者 QSPI Flash 里运行时通过网络接口的权重加载机制直接从外部存储器读取权重。脚本也好、烧录工具也好它们最希望处理的就是这种干净的二进制文件直接按偏移地址写进去就行。第二类是运行时动态加载或者 OTA 升级。设备端固件里不内置权重而是把权重当作独立的数据包管理需要升级模型时只更新 raw 文件即可。这种设计下raw 文件本质上已经成了产品数据包的一部分不生成它整个升级链路就要重新设计。所以这看起来只是少了一个输出文件实际影响的是整个部署方案。这也是为什么这个 Issue 能在社区里引起反响的原因。如果你只是默认生成 C 数组、直接在工程里编译那确实感觉不到什么影响但如果你依赖外部存储或者做模型热更新v1.2 突然不生成 raw 文件就直接打断了你的发布流程。1.2 v1.2 这次更新触动了哪条链路要理解这个问题的根源得稍微看一下 Studio 和底层生成引擎的关系。STM32CubeAI Studio 的图形界面说白了是一个壳真正负责把模型转成代码的是底层的 stm32ai 命令行工具和它依赖的生成引擎。Studio 的每个版本都绑定了一版生成引擎v1.2 这个版本在生成策略上做了一些调整其中就包括输出文件的默认形态。在早期版本里Studio 的图形界面会默认把权重输出成两种形式一种是嵌入 C 源代码的数组形式另一种就是独立的 raw 文件。很多老用户习惯了打开输出目录直接拿走.raw文件去烧片从来没在意过这个选项是怎么配置的。升级之后新版本调整了默认输出逻辑raw 文件不再是一个默认顺手生成的产物而是被挪到了高级选项里甚至在某些配置组合下干脆不生成。这就解释了为什么很多人升级之后什么都没有动raw 文件就是不见了。不是你的工程坏了是工具的默认行为变了。另外一个容易被忽视的细节是Studio 在升级时会尝试保留用户之前的工程配置但保留配置和迁移配置是两回事。如果新版不认识旧版里某个设置项它通常会选择忽略该设置并采用新默认值。也就是说即便你之前在旧版里明确勾选过生成 raw 文件升级后这个勾选状态也可能在迁移过程中被丢弃。还有一类情况是路径和权限问题。新版本在输出文件时会先创建临时文件再重命名如果工程路径里包含中文、空格或者过长的路径某些版本可能在重命名阶段失败临时文件被静默清理看起来就是没有生成。这类问题虽然不如默认行为变更那么普遍但在排查时也值得留意。2. 从行为变化到具体原因为什么 raw 文件会消失2.1 生成选项的改名与收纳是首要嫌疑如果你去翻 v1.2 的 Studio 界面会发现很多选项的位置和旧版不一样了。早期版本里生成选项相对简单基本都是平铺在页面上一项一项列得很清楚。v1.2 对界面做过一轮整理把很多高级但不常用的选项收进了次级菜单同时改了不少选项的名称。这次改名的幅度有多大举个例子旧版里叫Generate weights in external file在外部文件中生成权重或者类似的表述新版可能改成了Export weights as binary将权重导出为二进制或者Data files下的某个子选项。单看名称老用户根本不会把这两个东西联想到一起。更麻烦的是某些选项还从默认开启变成了默认关闭。你升级完打开界面看到的是一个清爽了很多的设置页但正是这种清爽把 raw 文件给优化没了。我的建议是升级后先别急着重新生成工程打开设置页面逐项过一遍选项重点关注和 weights、binary、data、output 相关的条目。如果看到某个选项旁边写着 experimental 或者 advanced也顺手点开看一眼。2.2 模型格式与量化配置的组合影响raw 文件的生成并不是在所有条件下都成立的它和模型的输入格式、量化设置、输出配置都有关系。v1.2 里这个依赖关系变得更严格了。举个例子当你选择输出浮点模型时权重就是一堆 float32 数写进 raw 文件就是一个接一个的 4 字节小端数生成逻辑很直接。但当你选择 int8 量化时权重变成了整型数raw 文件的生成逻辑会引入是否需要额外的缩放因子文件权重排列顺序按通道还是按层是否需要对齐到某个字节边界这些细节。旧版在部分配置组合下会兼容性地输出 raw 文件哪怕格式并不完全符合你的预期新版则倾向于如果格式存在歧义就不生成这条更保守的路线。也就是说不是 v1.2 不能生成 raw 文件而是它要求的生成条件比以前更严格了。如果模型本身的输入格式比较特殊或者量化参数设置得不够规范新版可能直接跳过 raw 文件输出只在日志里留下一行不太起眼的提示。还有一种情况是模型输入了不支持的操作符。Studio 在转换时如果遇到无法映射到 STM32 算子库的层可能会进入降级处理流程。这个流程里某些输出文件的生成会被跳过。这类问题在旧版里可能只是警告新版里会直接影响输出文件列表。2.3 升级残留的缓存和配置碎片工具类软件升级最怕的就是新旧配置混在一起。Studio 在工作过程中会写入不少缓存文件包括工程解析缓存、模型中间表示缓存、生成脚本缓存等等。v1.2 在首次启动时会对旧缓存做兼容处理但如果缓存结构变化太大它可能只是简单地把旧缓存标记为失效并没有彻底清理干净。后果是什么你在界面里改了配置点击生成工具却读了旧缓存里的某些参数结果输出的文件还是旧的逻辑。反过来说旧缓存里记录的某个选项位置已经失效了新代码找不到对应的值就按默认值处理。这两种情况都会导致我明明设置对了生成结果却不对的诡异现象。这类问题最直接的验证方法就是做一次干净生成关闭 Studio删除工程目录下的中间缓存文件夹通常以.stm32ai、*.cache或者类似名称存在重新导入模型重新配置再生成一次。如果这次 raw 文件回来了那基本可以断定是缓存残留引起的。3. 最完整的排查思路从日志到命令行的逐步定位3.1 第一步让日志开口说话遇到这种某个输出文件消失的问题第一反应不应该是反复点生成按钮而是去看日志。Studio 在每次执行模型分析和代码生成时都会记录详细的日志里面包含了它调用了哪些脚本、每一步的输入输出、以及哪些步骤被跳过或失败。日志在哪里看不同版本的 Studio 位置不完全一样但通常可以通过菜单栏的 Help 或者 View 里找到 Logs 入口。界面上看不到的话去用户目录下的工作空间文件夹里翻一翻找名字里带log、trace、report的文件。打开日志之后重点搜索几个关键词raw、weights、binary、skip、not generated、error、warning。大多数情况下你能找到类似这样的提示某个环节需要某个条件才输出 raw 文件而当前配置不满足所以跳过了。看到具体提示之后再回头调整配置就有方向了不再是无头苍蝇。3.2 第二步用命令行工具做隔离验证Studio 界面做了很多封装有时反而掩盖了问题本质。如果你希望确认到底是 Studio 图形界面的问题还是底层生成引擎的问题最直接的办法就是绕开界面直接调用命令行工具。STM32CubeAI 的命令行工具通常叫stm32ai在 STM32CubeMX 安装目录或者 Studio 安装目录下能找到。不同版本具体路径略有差异但基本都在Utilities或者Middlewares目录下。命令行工具支持多种参数组合核心参数包括指定模型文件路径、指定输出目录、指定目标芯片系列、指定内存布局等。这里我用一个示意性的命令来演示排查过程stm32ai generate \ --model /path/to/your_model.onnx \ --output /tmp/cubeai_test \ --name test_network \ --memory external实际参数名以你当前版本的stm32ai --help输出为准。关键在于如果命令行工具在指定了外部存储相关参数之后成功生成了 raw 文件那说明底层生成引擎本身没有问题问题出在 Studio 的界面配置上。如果命令行工具同样不生成 raw 文件那就要考虑生成引擎本身的版本行为或者模型兼容性了。这个隔离测试的价值在于它把界面问题和引擎问题清楚地区分开后续针对性处理会高效得多。3.3 第三步对照实验锁定差异点如果命令行工具能生成 raw 文件但你用 Studio 界面生成不了那就要做对照实验。在 Studio 里新建一个最简单的测试工程随便导入一个小模型用默认配置生成一次看有没有 raw 文件。这个最小化实验有两个作用。第一排除模型本身的干扰。如果你的正式工程里用的是复杂的 ONNX 模型里面可能有一些特殊的算子或动态维度这些都可能影响输出文件列表。换一个最简单的模型就能判断问题到底是所有模型都不生成还是特定模型才不生成。第二排除工程配置的干扰。新建工程从头走一遍流程如果默认配置下能生成 raw 文件那说明问题出在你原来那个工程的具体设置上如果默认配置下也不生成那说明是 Studio 的全局行为问题。这一步做完你基本就能确定问题的属性了是全局默认行为、特定工程配置、还是特定模型引起的。确定属性之后解决思路就清晰了。4. 一套直接可用的解决路径4.1 在界面设置里找回 raw 文件输出先说结论绝大多数情况下v1.2 里 raw 文件并没有被删除只是默认关闭了。你需要在设置里找到对应的开关并打开它。具体路径在不同版本里可能略有差异但我建议你在以下几个位置找工程配置页的 Output 或 Generation Options 部分高级选项里的 Export mode 或 Data output 部分与 weights、binary、data 相关的任何复选框打开设置之后把和权重导出相关的选项设置为同时生成 C 数组和二进制文件或者选择生成独立权重文件然后重新生成代码查看输出目录里是否出现了.raw文件。一种比较实用的做法是在设置界面里把所有可选的语言、输出格式选项都展开看一遍不急着生成先搞清楚每一项的用途。很多人在升级之后根本没有重新审视过这些设置默认值变了也不知道。花五分钟过一遍比你反复试错高效得多。4.2 如果界面实在找不到就主动切到命令行如果你翻遍了设置页面也没有找到 raw 文件相关的选项或者找到了但死活不生效那就不要跟界面死磕了直接回到命令行工具。命令行工具的--memory参数直接决定了内存布局方式。默认情况下是internal权重嵌入内部 Flash改成external之后生成引擎会倾向于输出独立数据文件raw 文件自然就会出现。一个常见的组合是让 C 代码里保留网络结构同时把权重放到外部数据文件里这样代码体积小权重也好单独管理。命令行里可以这样处理先指定--memory external生成权重文件再在工程里手动引用。这种方式虽然比点一下界面麻烦一点但胜在可控性强你能明确看到每个步骤的输出结果。值得注意的是反量化所需的缩放因子等元信息通常会跟随参数文件生成在使用外部 raw 文件时你需要额外留意这些配套文件否则运行时可能会因为缺少元信息而无法正确解析权重。4.3 验证生成的 raw 文件是否真的可用排查到最后raw 文件终于生成出来了先别急着高兴花几分钟验证一下文件完整性。一般 raw 文件的体积可以通过权重参数数量推算。假设一个模型有 100 万个 float32 参数那 raw 文件大小应该在 4MB 左右1000000 × 4 字节。如果文件大小存在数量级的偏差那说明权重数据可能不完整或者格式不对直接烧到板子上肯定跑不出正确结果。可以用简单的命令查看文件大小比如在 Linux 下用ls -l或者stat在 Windows 下右键看属性也可以用xxd或者 hexdump 之类的工具看一眼文件头和文件尾的数据是否合理。权重数据通常呈现一定的统计规律如果文件里面大片都是 0x00 或者 0xFF那就要怀疑生成过程是不是出了问题。还有一个更严谨的验证方法对比 raw 文件和 C 数组版本的权重。在能生成 C 数组配置下把模型权重用const float weights[]的形式编译出固件读取对应地址的数据再用同样的输入跑一次推理对比结果是否一致。虽然这个操作比较繁琐但它是验证 raw 文件内容正确性的金标准。5. 踩过这些坑之后我整理出几条通用建议5.1 升级前备份配置升级后先做最小验证嵌入式工程师的电脑里通常装了不止一版 ST 的工具链升级工具的时候有一个很现实的问题你根本不知道新版本除了界面变化之外还改了哪些生成行为的默认值。所以我的个人习惯是升级之前先把当前工程里所有的生成配置项截个图存档。不要嫌麻烦等出了问题再去回忆旧版本里这个选项是怎么设置的大概率已经记不清了。升级之后先用官方示例或者自己写的一个最小模型跑一遍完整流程确认输出文件列表和升级前一致再把正式工程切过来。这个过程看起来多花了十几分钟但能避免你在正式工程上浪费几个小时排查一个其实很蠢的配置问题。5.2 输出文件对比是最快的问题信号很多人在工程里配置的是相对路径升级之后重新生成代码看到输出目录里有文件就以为一切正常很少会对比这次生成了哪些文件上次生成了哪些文件。这是一个成本极低但极其有效的检查手段。生成完代码之后花十秒钟对比一下文件列表如果多出了文件、少了文件、或者文件大小有显著变化立刻就能发现问题。特别是像 raw 文件这种配套产物它不会影响编译是否通过但会影响你的部署流程。编译通过不代表一切正常把输出文件清单列入验收标准能少踩很多坑。5.3 命令行工具是图形界面的后门最后说一个不一定写在官方文档里的经验图形界面能做的所有事情几乎都能在命令行工具里完成而且命令行工具暴露的参数往往更底层、更完整。当你对图形界面的某个行为不理解、或者怀疑图形界面有 bug 时毫不犹豫地转向命令行。先用--help把所有参数过一遍看看有没有和输出文件类型相关的选项再跑一遍生成观察终端输出的每一步信息。命令行不会给你弹出友好的提示框但它会把真实发生的事情原原本本地告诉你。工具每次大版本更新都值得花点时间把这套界面-命令行对照流程走一遍。这不只是在解决当前问题也是在建立你对这套工具链的掌控感。5.4 学习资源要跟着版本走关于 STM32CubeAI 的用法网上的教程和资料非常多但不少教程对应的都是早期版本。界面截图、菜单名称、生成逻辑都和 v1.2 有差异。你照着旧教程去设置很可能找不到对应的选项甚至被误导。建议以官方 Release Notes 和官方用户手册为准。特别是 Release Notes它不仅仅是修复了几个 bug的列表里面通常隐藏着行为变更这样一句看上去不起眼但实际影响很大描述。做工具升级的时候先花十分钟把 Release Notes 从头到尾看一遍比出了问题再查要值太多。