1、课程导论：为什么需要模型版本管理？STM32CubeAI项目中的痛点分析。

大家好，我是你们的老朋友。今天咱们开始聊一个看似不起眼、但实际能让你少掉不少头发的话题——模型版本管理。

说实话，我刚开始用STM32CubeAI那会儿，根本没想过版本管理这回事。觉得不就是训练个模型，转成c代码，烧进去就完事了嘛。结果呢？项目一多，模型一改，各种混乱就来了。嗯，今天咱们就来好好掰扯掰扯，为什么这东西这么重要。

1.1 一个真实的“翻车”现场

先讲个我自己的经历。去年有个项目，做的是工业异常检测。我花了两周时间，调了一个MobileNetV2的量化模型，在开发板上跑得挺好，准确率92%。

结果过了三天，客户说想试试另一个场景。我就顺手改了改训练脚本，重新训练了一版。当时没留任何记录，也没保存旧模型。一周后客户说“还是第一版效果好”，让我切回去。

你猜怎么着？我翻遍了硬盘，根本找不到第一版的模型文件了。训练日志？没有。超参数记录？也没有。最后只能凭记忆重新调参，又花了一周才勉强复现。那感觉，真叫一个憋屈。

从那以后，我养成了一个习惯：每个模型版本，必须打标签、写日志、存快照。哪怕只是改了一个学习率，也得记下来。

1.2 STM32CubeAI项目中的典型痛点

咱们做嵌入式AI的，跟纯软件AI还不一样。软件那边，模型版本管理已经很成熟了，有MLflow、DVC这些工具。但到了STM32CubeAI这边，情况就复杂多了。

我总结了几个最常见的痛点，你看看你中了几条：

• 痛点一：模型文件与工程文件脱节
  你训练好的.tflite或.onnx模型，跟CubeMX生成的C代码、MDK/IAR工程文件，往往是分开存放的。时间一长，根本对不上号。
• 痛点二：量化参数丢失
  STM32CubeAI的量化过程，涉及到输入输出缩放因子、零点偏移等参数。我见过有人把量化后的模型拷给别人，结果忘了带校准数据集。对方一跑，输出全是乱码。
• 痛点三：硬件适配版本混乱
  同一个模型，在STM32F4上跑一个版本，在STM32H7上跑另一个版本。两个板子的RAM、Flash大小不同，模型裁剪策略也不同。没有版本管理，你根本不知道哪个模型对应哪个板子。
• 痛点四：迭代记录缺失
  “这个模型比上个版本准确率高了2%，但推理慢了5ms。”——这种关键信息，如果不记录下来，过两周你自己都忘了当初为什么这么改。

1.3 为什么软件AI的版本管理方法不适用？

你可能会问：那我把MLflow那一套搬过来不就行了？

我试过。说实话，不太行。原因有三：

1. 嵌入式模型更小，但更“脆弱”
   软件AI的模型动辄几百MB，版本管理主要管的是模型文件本身。但嵌入式模型往往只有几百KB，真正要管的是整个部署链路——包括量化参数、硬件配置、编译器版本、CubeAI版本。这些东西MLflow管不了。
2. 硬件依赖性强
   同一个模型，在STM32F4上量化后是1.2MB，在STM32H7上量化后是2.1MB。因为硬件资源不同，模型裁剪和量化策略也不同。版本管理必须把硬件型号作为一个维度。
3. 工具链版本敏感
   STM32CubeAI从1.7.0升级到1.8.0，量化算法变了。同样的模型，两个版本生成的c代码可能不一样。我遇到过因为CubeAI版本不一致，导致模型在板子上跑飞的情况。所以，工具链版本也必须纳入管理。

1.4 版本管理到底能解决什么问题？

说白了，版本管理就干三件事：

能力	解决的问题	具体表现
可追溯	知道每个模型从哪来、到哪去	能查到训练脚本、数据集、超参数、量化配置
可复现	任何时候都能回到某个历史状态	一键恢复某个版本的模型+工程+配置
可对比	清楚不同版本之间的差异	准确率、推理时间、内存占用一目了然

举个例子。有一次客户反馈说，某个模型在量产板上偶尔会死机。我通过版本管理查到，这个模型用的是CubeAI 1.7.0生成的代码。而1.7.0有个已知bug，在特定条件下会触发内存越界。我立刻切回1.8.0重新生成，问题解决。如果没有版本管理，我可能得排查好几天。

1.5 本课程能给你什么？

这门课一共10章，咱们会从最基础的文件命名规范讲起，到Git LFS管理大模型文件，再到自动化版本记录脚本，最后还会聊团队协作中的版本冲突解决。

每一章我都会结合自己在STM32CubeAI项目中的实际踩坑经历，给你一套拿来就能用的方法。

好了，导论就聊到这儿。下一章咱们会手把手搭建一个最小可行的版本管理方案，保证你学完就能用上。

记住一句话：版本管理不是束缚，而是给你自由。自由地尝试、自由地回退、自由地迭代。

咱们下章见。