固定Gemma检查点而非跟踪Main分支

跟踪 main 分支时什么会发生变化

Hugging Face 模型仓库本质上是一个 git 仓库，而 main 和其他分支没有任何区别。当 Google 推送一个 commit 时，所有没有指定 revision 就拉取的部署都会在下次冷启动时获取到它。发生变更的文件并非无关紧要：

tokenizer_config.json 保存着聊天模板。模板修正会改变模型收到的确切文本，从而改变其输出。

generation_config.json 保存着停止 token 集合。这里的变更会改变生成结束的时间点，这就是那个重复的 stop-token 页面所讨论的问题。

config.json 保存着包括滑动窗口和位置限制在内的架构值。

safetensors 分片本身在转换修复后也曾被重新上传过，这个家族和其他家族都有过这种情况。

以上这些变化都不会主动告知你。你的评估结果发生了偏移，你的黄金输出不再匹配，而差异却在别人的仓库里。Pinning 把这变成一个由你主动做出的决定。

这种失败有一种独特的特征，值得认识，因为它在不熟悉的情况下会浪费数天时间。一切正常运作好几周，然后某个实例重启，将新的 revision 拉取到冷缓存中，开始表现得与其兄弟节点不同。此时你的集群中有些节点运行的是一个模型，有些运行的是另一个模型，而它们的代码、配置和容器镜像完全相同。所有的调试直觉都指向你自己的部署，却什么都找不到，因为差异在于容器启动时下载的那个目录中。

找到你当前所在的 commit

在 pinning 到一个良好 revision 之前，先确认你当前运行的是哪个版本，这样 pinning 才能保持行为而不是改变它。Gemma 仓库有访问限制，所以需要先认证：在模型页面接受许可协议并登录。

认证，一次性操作，适用于每台机器或 CI runner。

hf auth login          # older CLIs: huggingface-cli login

向 hub 查询 main 当前解析到哪个版本。

from huggingface_hub import model_info

info = model_info("google/gemma-3-4b-it")
print(info.sha)          # full commit hash of main, right now
print(info.lastModified)

如果模型已经在本地缓存中，读取你实际拥有的 hash，而不是上游现在的 hash。两者不同的时候恰恰就是出问题的时候。

from huggingface_hub import scan_cache_dir

for repo in scan_cache_dir().repos:
    if repo.repo_id == "google/gemma-3-4b-it":
        for rev in repo.revisions:
            print(rev.commit_hash, sorted(r for r in rev.refs))

对每个加载器都进行 pin，而不是只 pin 模型

这是通常只做一半的步骤。权重获得了 revision，但 tokenizer 没有，这就产生了你能遇到的最糟糕的组合：pinned 的参数配上浮动的聊天模板。将 revision 传递给每个涉及该仓库的 from_pretrained 调用。

将 hash 放在一处，而不是分散在每个调用点。

MODEL_ID = "google/gemma-3-4b-it"
REVISION = "0f1e2d3c4b5a69788796a5b4c3d2e1f0a9b8c7d6"   # full 40-char sha

在同一 revision 下加载 tokenizer、如果 checkpoint 是多模态的话还要加载 processor，以及模型。

from transformers import AutoTokenizer, AutoProcessor, AutoModelForCausalLM

tok   = AutoTokenizer.from_pretrained(MODEL_ID, revision=REVISION)
proc  = AutoProcessor.from_pretrained(MODEL_ID, revision=REVISION)   # vision sizes only
model = AutoModelForCausalLM.from_pretrained(MODEL_ID, revision=REVISION)

对于容器镜像或气隙部署，在构建时将 revision 作为一个整体下载，并将运行时指向结果目录。

from huggingface_hub import snapshot_download

path = snapshot_download(MODEL_ID, revision=REVISION)
print(path)   # a directory whose contents cannot change under you

让浮动加载变得不可能，而不仅仅是劝阻。在 CI 中，如果任何 from_pretrained 缺少 revision 则让构建失败；一个 grep 就够了，而且能捕获到六个月后某人在此添加的调用点。

使用完整的 commit hash 而不是 tag。Tag 是可移动的引用，会继承你正在解决的问题。一个 40 字符的 sha 是内容寻址的，无法被重新指向。

与模型 pin 同等重要的两个相邻 pin 同样容易被遗忘。第一个是库：Gemma 3 需要足够新的 transformers 版本来识别架构，太旧的栈会在加载时失败，这是好的情况。不好的情况是反过来——一个更新的库改变了 processor 或 attention 实现的默认值，导致你的 pinned 权重运行起来不一样。在 revision 旁边也 pin 库版本。

第二个是下载本身。在容器构建中，在镜像构建时进行下载而不是在容器启动时进行，意味着产物被 baked in，启动时不需要网络 I/O，hub 的中断不会阻止你扩容。这也意味着许可认证发生一次，在可控的地方，而不是在每个节点上。

验证并记录 pin

在启动时断言 pin，以便配置错误的环境大声失败而不是安静地服务于一个不同的模型。

import hashlib, json

tmpl = tok.chat_template or ""
print("template sha256:", hashlib.sha256(tmpl.encode()).hexdigest()[:16])
print("eos ids:", model.generation_config.eos_token_id)
print("window:", model.config.max_position_embeddings)

在每次评估运行时记录这三个值。当分数发生变化时，你会想知道是否是模型发生了变化，而日志中的一个 hash 能在几秒钟内回答这个问题。

也将 revision 记录在你的许可记录旁边。Gemma 的条款附加在你交付的产物上，所以知道那究竟是哪个产物是日后回答许可问题的一部分。

主动移动 pin

Pin 不是永不升级的决定。它是一种将升级变成带有 diff 的事件的决定。升级循环很短：

将你的 pinned hash 与当前 main 进行比较。

from huggingface_hub import model_info
print(model_info(MODEL_ID).sha == REVISION)

阅读仓库在 hub 上的 commit 历史，看看发生了什么变化。模板或 generation-config 的变更值得做完整评估；README 的编辑不值得。

在切换之前，用两个 revision 运行你的评估集，如果 tokenizer 有任何变化则重新测量 token 计数。版本历史列出了最可能发生变化哪些属性。

更新常量，重新部署，并在 commit 消息中保留之前的 hash，这样回滚只是一次编辑而不是一次调查。

合理的节奏是按计划检查上游变化，而不是被动反应。一个每周执行的 job 比较你的 pinned hash 与 main，在它们不同时开一个 issue，把看不见的风险变成一小块例行维护，这意味着你是因为 job 告诉你而不是因为用户抱怨才知道模板修正的消息。

同样的纪律也适用于衍生产物。量化转换、ONNX 导出和微调 adapter 都携带了它们所来源的基础 revision 的隐式依赖，除非你主动记录，否则没有一个会记录它。在构建时将基础 hash 写入产物自己的 metadata 或文件名中。当一个 adapter 在一年后在新基础上有奇怪行为时，这一串字符就是五分钟得出答案和花一下午调查的区别。

这些都不是 Gemma 特有的，这正是关键所在。每个开源模型家族都是从可变仓库提供的，所以同样的纪律适用于所有这些家族；Gemma 只是一个其模板和生成配置都曾在上游被修正过的家族，这让不 pin 的代价从理论变成了具体。如果你从这篇文章中养成一个习惯，就让它变成模块顶部的常量：一个模型 id 和一个完整的 commit hash，放在一处，代码库中每个加载器都读取它。

Hub CLI 命令和辅助函数名称随时间发生了变化；from_pretrained 和 snapshot_download 的 revision 参数是稳定部分。查看当前的 huggingface_hub 文档以了解你的版本使用的 CLI 拼写方式。