002、代码管理基石：Git与GitHub/GitLab在大模型项目中的高级实践

---

上周团队里一个实习生跑来找我，说他的大模型微调实验代码“回不去了”。他手头有三个版本的模型参数文件，每个都超过10GB，混在代码目录里一起提交到了Git。现在仓库膨胀到快50GB，clone一次要半小时，想清理历史记录却无从下手。我看着他满屏的git push失败提示，叹了口气——这场景太典型了。

大模型项目的代码管理，远不止是git add和git commit那么简单。当你面对动辄几十GB的权重文件、数百个实验分支、复杂的预处理流水线时，传统的Git工作流会迅速崩溃。今天我们就聊聊怎么让Git在这样极端的环境下，依然能成为可靠的基石。

权重文件：别让它们进版本库

这是第一条血泪教训：永远不要把模型权重文件（.bin、.pth、.h5等）直接提交到Git仓库。Git本质上是个文件版本系统，每次提交都会保存文件的完整快照。一个20GB的权重文件，你稍微改几行代码重新提交一次，仓库体积就可能变成40GB。不出一个月，你的仓库就会臃肿到无法操作。

正确的做法是用.gitignore彻底屏蔽：

# 模型权重和检查点
*.bin
*.pth
*.h5
*.safetensors
checkpoints/
experiments/*/weights/
# 数据集缓存文件
*.arrow
*.lock
data/cache/

那权重文件怎么管理？两种务实方案：

1. 用Git LFS（大文件存储）：适合团队内部分享的中小型模型（比如10GB以内）。先在仓库里初始化git lfs install，然后追踪大文件类型：

git lfs track "*.bin" "*.pth"
git add .gitattributes

这样实际文件会存储在LFS服务器，Git仓库里只保留指针。但注意，GitHub的LFS有配额限制，私有仓库容易超量。

2. 外挂存储+版本清单：更适合生产环境。权重文件扔到对象存储（S3、OSS、公司NAS），然后在代码库维护一个model_versions.json：

{
  "llama2-7b-finetuned-v3": {
    "url": "s3://our-bucket/models/v3/weights.bin",
    "md5": "a1b2c3...",
    "created": "2024-06-15",
    "note": "在医疗语料上微调了3个epoch"
  }
}

代码里写个简单的加载器，根据版本名自动下载。这个方案虽然要多写几行工具代码，但扩展性极好，还能和模型注册中心对接。

实验分支的生存法则

大模型实验最烧钱的就是GPU机时。经常要同时跑好几组超参实验，每个实验可能持续几天。如果所有实验都挤在main分支上做，很快就会变成一团乱麻。

我习惯用“实验沙盒”模式：

• main分支永远保持可运行状态，只合并经过验证的代码
• 每个实验独立开分支，分支名带实验目的和日期：exp/lora-rank8-0615、exp/attention-mask-0616
• 实验分支里，代码可以随便改，但提交要频繁——不是让你提交权重，是提交实验配置和日志

关键在这里：每个实验分支必须包含一个experiment_log.md文件，记录：

## 实验：LoRA rank=8
- 数据集：medical_corpus_v2
- 基础模型：Llama2-7b-hf
- 超参：lr=2e-4, rank=8, alpha=16
- 启动命令：python train.py --config configs/lora.yaml
- 关键结果：在eval集上loss从1.23降至0.89
- 问题：第3个epoch出现过拟合迹象

这个文件随着实验进展不断更新。等实验结束，哪怕分支被删除，所有关键信息都已经沉淀下来。

配置文件的版本控制艺术

大模型的训练配置项可能有上百个：模型结构、优化器参数、数据路径、回调设置……很多人图省事，写个config.yaml一提交就完事。结果就是：两周后根本不知道哪个配置对应哪个实验结果。

我的做法是“配置即代码”：

# configs/train_base.py
class TrainConfig:
    model_name = "llama2-7b"
    batch_size = 16
    gradient_accumulation = 4
    
    # 这里踩过坑：绝对路径在别人机器上会报错
    # data_path = "/home/me/data/train.jsonl"  # 别这样写！
    data_path = "${DATA_DIR}/train.jsonl"  # 用环境变量替换
    
    def to_dict(self):
        return {k: v for k, v in self.__dict__.items() 
                if not k.startswith('_')}

然后在训练脚本里：

from configs.train_base import TrainConfig

class ExperimentA(TrainConfig):
    lr = 2e-4
    use_lora = True
    lora_rank = 8

config = ExperimentA()
print(config.to_dict())

这样每个实验的配置都是一个Python类，可以继承、覆盖、做类型检查。更重要的是，配置和代码一起被Git管理，完全可追溯。配合上面的实验日志，任何时候都能复现实验环境。

预处理流水线的缓存策略

数据预处理是大模型训练最耗时的环节之一。原始语料→分词→分桶→缓存，一套流程下来可能要好几个小时。如果每次跑实验都重新预处理，等于是把GPU服务器当CPU用。

我在项目里会强制约定缓存目录结构：

data/
├── raw/          # 原始数据，手动管理
├── processed/    # 处理后的数据，.gitignore忽略
│   ├── v1_tokenized/  # 第一次处理的缓存
│   │   ├── dataset_info.json  # 这个要提交！
│   │   └── *.arrow
│   └── v2_shuffled/
└── datasets.py   # 数据加载逻辑

dataset_info.json记录预处理的关键参数：分词器版本、最大长度、是否截断等。代码里会先检查缓存目录是否存在，且参数匹配，如果匹配就直接加载缓存。

这里有个细节：缓存文件本身不进Git，但dataset_info.json一定要进。这样新同事clone代码后，运行预处理脚本会自动生成缓存，而不是直接使用可能过期的缓存文件。

合并请求的“模型报告”文化

在GitLab/GitHub上提交Merge Request时，我要求团队必须附上“模型报告”——不是学术论文，而是一页纸的总结：

1. 改动范围：改了哪些文件，为什么改
2. 性能影响：在验证集上的指标变化（哪怕只是训练loss曲线）
3. 副作用检查：推理速度是否下降、内存占用是否增加
4. 回滚方案：如果出问题，怎么快速回退

这个习惯最初是为了应付老板的提问，后来发现它极大提升了代码合并的质量。强迫开发者用一两句话说清楚“这个PR为什么值得合并”，能过滤掉很多不必要的提交。

个人工具箱里的私货

最后分享几个我每天在用的命令和配置，有些文档里不太容易找到：

1. 查看仓库大小，找出罪魁祸首：

git count-objects -vH  # 查看本地仓库体积
git lfs ls-files       # 查看LFS文件详情

2. 清理历史中的大文件（慎用！）：

# 找出前5个大文件
git rev-list --objects --all | grep "$(git verify-pack -v .git/objects/pack/*.idx | sort -k 3 -n | tail -5 | awk '{print$1}')"
# 用BFG工具删除（比git filter-branch友好）
bfg --delete-files "*.pth" --no-blob-protection .

3. 我的全局Git配置片段：

[core]
    # 大模型项目文件多，提高压缩率
    compression = 9
[merge]
    # 合并冲突时创建备份文件
    keepBackup = false
[diff]
    # 忽略空格变更，看diff更清晰
    ignoreAllSpace = true
[alias]
    # 自定义别名
    tree = log --graph --oneline --all
    cleanup = "!git branch --merged main | grep -v '^\\*\\|main' | xargs -n 1 git branch -d"

4. 提交信息模板（.gitmessage）：

## 变更类型
[ ] 模型架构
[ ] 训练脚本
[ ] 数据预处理
[ ] 配置/工具

## 影响范围
- 训练流程：是/否
- 推理服务：是/否
- 向后兼容：是/否

## 测试情况
- [ ] 本地训练通过
- [ ] 验证集指标
- [ ] 内存/速度基准

写在最后

在大模型项目里用Git，核心思想就一个：版本控制的是“知识”，不是“数据”。代码、配置、实验记录、评估报告——这些是知识，必须严格版本化。权重文件、预处理缓存、日志文件——这些是数据，应该用专门的系统管理。

刚开始做LLM项目时，我也曾试图把一切都塞进Git，结果就是仓库变成无法移动的巨石。后来才明白，好的版本控制系统不是仓库越大越好，而是能在需要的时候，快速找到三个月前某个实验的确切环境和配置。Git做不到存储几百GB的模型文件，但它能完美记录你如何得到那个模型。

下次提交前，不妨问自己一句：如果这个提交半年后要用来复现实验，我还缺什么信息？把答案放进commit message里，未来的你会感谢现在的细心。