2、版本管理基础：Git在嵌入式AI项目中的基本配置与工作流
说到版本管理，很多做嵌入式的老哥第一反应是：「我一个小单片机项目，要啥Git？」
嗯，我以前也这么想。直到有一次，我花了两周调好的模型量化参数，被同事一个不小心覆盖了。更惨的是，那个版本的模型文件我还没备份。从那以后，Git就成了我每个项目的标配，尤其是STM32CubeAI这种模型和代码深度绑定的项目。
说白了，嵌入式AI项目比纯软件项目更依赖版本管理。为什么？因为你的模型文件、训练脚本、部署代码、CubeMX配置，这些东西环环相扣。任何一个环节出了问题，整个项目都得重来。
2.1 Git在嵌入式AI项目中的特殊配置
先说说基础配置。我个人习惯在项目一开始就配好.gitignore，这东西能救你命。
嵌入式AI项目的.gitignore核心配置：
# 忽略模型中间文件
*.h5
*.ckpt
*.pb
*.tflite
*.onnx
*.uff
# 但保留最终部署模型
!deploy/*.tflite
!deploy/*.onnx
# CubeMX生成的文件
*.ioc
Drivers/
Middlewares/
# 编译产物
build/
Debug/
Release/
*.o
*.elf
*.hex
*.bin
# 个人IDE配置
.idea/
.vscode/
*.swp
这里有个坑，我踩过。你可能会想：「我把所有模型文件都忽略不就行了？」不行。最终部署到STM32上的模型文件（比如.tflite或.onnx）必须进版本库。否则别人拉下来代码，根本跑不起来。
我的经验：在项目根目录建一个deploy/文件夹，专门放最终部署用的模型。这个文件夹里的东西，全部跟踪。其他训练过程中的中间模型，统统忽略。
2.2 嵌入式AI项目的Git工作流选择
嵌入式AI项目的工作流，和纯软件项目不太一样。我试过好几种，最后发现「三分支模型」最适合。
| 分支名称 | 用途 | 谁可以合并 |
|---|---|---|
main |
稳定发布版，模型已部署验证 | 项目负责人 |
develop |
日常开发，模型调优中 | 所有开发者 |
feature/xxx |
单个功能或模型实验 | 个人分支 |
为什么会这样设计？你想想看，嵌入式AI项目最怕什么？最怕模型和代码不匹配。main分支上的模型必须是经过硬件验证的，不能随便改。
我遇到过最惨的一次：一个同事在feature分支上优化了模型，精度提升了2%，但没注意到模型大小增加了30%。合并到main后，STM32的Flash直接爆了。从那以后，我规定所有模型变更必须先在develop分支上做硬件测试。
2.3 模型文件的版本管理策略
模型文件不是代码，不能直接diff。所以管理方式要特殊处理。
我的做法是这样的：
- 每个模型版本配一个README：在deploy/文件夹里，每个模型文件旁边放一个同名.md文件，记录这个模型的输入输出、量化方式、精度指标、测试结果。
- 用Git LFS管理大模型：超过10MB的模型文件，用Git LFS跟踪。不然每次clone项目都像在下载电影。
- 模型命名带版本号：比如
model_v2.1.0_quant_int8.tflite，一看就知道是哪个版本。
注意：千万不要用「最终版」「最终版2」「最终版3」这种命名。我见过一个项目，模型文件叫「最终版_真的不改了.tflite」，结果第二天又改了。版本号才是正道。
2.4 嵌入式AI项目的典型工作流
说一个我常用的工作流，你可以参考一下：
# 1. 从develop分支拉一个新功能分支
git checkout develop
git pull
git checkout -b feature/optimize_model_v2
# 2. 训练新模型，放到deploy/目录
# 训练完成后...
cp best_model.tflite deploy/model_v2.1.0_quant_int8.tflite
# 3. 更新模型说明文档
echo "模型版本: v2.1.0" > deploy/model_v2.1.0_quant_int8.md
echo "量化方式: int8" >> deploy/model_v2.1.0_quant_int8.md
echo "精度: 92.3%" >> deploy/model_v2.1.0_quant_int8.md
# 4. 提交代码
git add deploy/
git commit -m "feat: 优化模型v2.1.0，精度提升1.2%"
# 5. 合并到develop，做硬件测试
git checkout develop
git merge feature/optimize_model_v2
# 在STM32上跑测试...
# 6. 测试通过后，合并到main
git checkout main
git merge develop
git tag v2.1.0
这个流程看起来简单，但实际执行时有个关键点：每次合并前必须做硬件测试。我见过太多人偷懒，觉得模型在PC上跑得好就行。结果一部署到STM32上，推理时间翻倍，或者内存溢出。
2.5 避坑指南：我踩过的那些坑
做嵌入式AI的Git管理，有几个坑我替你们踩过了：
- 坑一：模型文件冲突。两个人同时改了同一个模型文件，Git没法自动合并。解决方案：模型文件专人维护，其他人只读。
- 坑二：CubeMX配置冲突。.ioc文件是二进制格式，冲突了很难解决。我建议每个开发者用自己的.ioc配置，只把关键的配置参数写在文档里。
- 坑三：忘记打Tag。模型版本和代码版本要对应。每次发布，记得打Tag。我习惯用
v模型版本_代码版本的格式，比如v2.1.0_alpha3。 - 坑四：大模型撑爆仓库。有一次我忘了用Git LFS，直接把一个50MB的模型文件push上去了。结果整个团队clone项目花了半小时。从那以后，我强制在CI里检查文件大小。
一个小技巧：在项目的README里放一个「模型版本记录表」，每次更新模型都更新这个表。这样新同事加入项目，一眼就能看到当前用的是哪个模型，历史版本有哪些。
2.6 总结一下
Git在嵌入式AI项目里，说白了就是给模型和代码之间搭一座桥。桥搭好了，团队协作就顺畅；桥没搭好，天天出事故。
我个人觉得，最重要的就三点：模型文件专人管、合并前必须测、版本号要规范。做到这三点，至少能避开80%的坑。
下一章，我会讲模型版本号的具体命名规范和语义化版本控制。到时候咱们再细聊。