4、Git LFS实战：解决大模型文件（>100MB）的版本管理问题

模型文件动辄上百兆，甚至几个G。你想想看，一个训练好的CNN权重文件，随便就是200MB+。用普通Git管理？等着爆仓吧。

我最早踩过这个坑。那时候刚接触STM32Cube AI，把训练好的模型直接往Git仓库里一丢，结果团队拉代码时，每个人都要下载几百兆的二进制文件。更崩溃的是，每次模型迭代，Git就把整个文件重新存一份。仓库体积膨胀得飞快，最后连clone都超时。

后来我学乖了。对付大文件，得用Git LFS（Large File Storage）。说白了，它就是把大文件替换成指针文件，真正的数据存到远端服务器。本地只保留你需要的版本。

4.1 为什么普通Git搞不定大模型文件？

先看一组数据，你就明白了。

场景	普通Git	Git LFS
首次提交200MB模型	仓库增加200MB	仓库增加约1KB（指针文件）
修改后再次提交	再增加200MB（全量存储）	仅存储差异部分
clone仓库	下载全部历史版本	只下载当前版本
切换分支	可能触发大文件传输	按需拉取

普通Git存二进制文件，每次修改都是全量副本。你迭代10次模型，仓库里就躺着10个完整的大文件。Git LFS只存指针，真正的文件按版本管理，按需下载。

4.2 安装与初始化Git LFS

步骤很简单，但有几个坑要注意。

1. 安装Git LFS客户端

   # Ubuntu / Debian
   sudo apt install git-lfs
   
   # macOS
   brew install git-lfs
   
   # Windows
   # 下载安装包：https://git-lfs.github.com/

2. 初始化Git LFS

   git lfs install

   这条命令会在全局配置里注册LFS钩子。我建议你每个项目都跑一次，确保环境干净。

3. 指定要追踪的文件类型

   git lfs track "*.tflite"
   git lfs track "*.h5"
   git lfs track "*.onnx"
   git lfs track "*.bin"

   这会生成一个.gitattributes文件。记得把它提交到仓库里。

4.3 实战：管理STM32Cube AI模型文件

假设你有一个STM32Cube AI项目，目录结构大概是这样：

my_stm32_ai_project/
├── models/
│   ├── v1.0/
│   │   ├── model.tflite        (2.3 MB)
│   │   └── model_quant.tflite  (580 KB)
│   ├── v1.1/
│   │   ├── model.tflite        (2.5 MB)
│   │   └── model_quant.tflite  (600 KB)
│   └── v2.0/
│       ├── model.tflite        (4.1 MB)
│       └── model_quant.tflite  (1.2 MB)
├── src/
├── inc/
└── .gitattributes

嗯，这里要注意。虽然单个模型文件可能没超过100MB，但多个版本加起来就大了。我习惯把所有模型文件都纳入LFS管理，不管大小。

具体操作：

# 1. 追踪所有模型文件
git lfs track "models/**/*.tflite"

# 2. 查看追踪状态
git lfs status

# 3. 正常提交
git add .
git commit -m "feat: add model v2.0 with quantized version"

# 4. 推送（LFS文件会自动上传到LFS服务器）
git push origin main

4.4 查看与迁移已有的大文件

如果你已经用普通Git提交了大文件，别慌。可以迁移到LFS。

# 查看当前仓库里的大文件
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  awk '/^blob/ {print $3, $4}' | \
  sort -rn | head -10

这条命令会列出仓库里最大的10个文件。我一般用它来确认哪些文件需要迁移。

迁移步骤：

1. 安装并初始化Git LFS
2. 设置追踪规则
3. 使用git lfs migrate命令重写历史

   # 将指定类型的文件迁移到LFS
   git lfs migrate import --include="*.tflite,*.h5" --everything
   
   # 清理本地缓存
   git reflog expire --expire=now --all
   git gc --prune=now

4. 强制推送（注意：这会重写历史）

   git push --force origin main

4.5 LFS的存储与带宽限制

GitHub免费版给每个仓库提供1GB的LFS存储，每月1GB的带宽。超出就要付费。GitLab免费版是5GB。我个人建议，如果团队模型文件多，可以考虑自建LFS服务器，或者用阿里云OSS、AWS S3做后端存储。

平台	免费存储	免费带宽/月	超出费用
GitHub	1 GB	1 GB	$5/50GB
GitLab	5 GB	10 GB	$60/100GB
Bitbucket	5 GB	5 GB	$10/100GB

你想想看，一个模型迭代10次，每次200MB，光存储就2GB了。免费额度根本不够用。所以我的建议是：

• 只存最终版本：中间训练过程的检查点（checkpoint）不要进LFS，用本地存储或NAS
• 量化模型优先：STM32Cube AI最终部署用的是量化模型，通常只有几百KB。原始浮点模型可以单独归档
• 定期清理旧版本：用git lfs prune删除本地不需要的旧版本缓存

4.6 团队协作中的LFS最佳实践

我总结了几条经验，分享给你：

1. 统一追踪规则：.gitattributes必须进版本库，所有人用同一套规则
2. 拉取时指定LFS：

   git lfs pull
   # 或者 clone 时直接拉取 LFS 文件
   git lfs clone https://github.com/your/repo.git

3. 锁定大文件：防止多人同时修改同一个模型文件

   git lfs lock models/v2.0/model.tflite

4. CI/CD中处理LFS：在流水线里加上git lfs pull，否则构建环境拿不到真正的模型文件

4.7 一张图看懂Git LFS工作流程

下面这张图展示了Git LFS的核心逻辑。你看完就明白它怎么省空间了。

说白了，Git LFS就是给大文件开了个「外挂」。Git仓库只存个「索引卡」，真正的文件存在专门的存储服务器上。你需要哪个版本，就去服务器上取哪个版本。这样仓库永远轻量，历史永远干净。