Hugging Face Hub 怎样固定模型修订版本

如果同一个模型仓库的 main 分支在两次运行之间发生了更新，配置、权重和 tokenizer 就可能不再来自同一份内容。Hugging Face Hub 的做法是给下载或加载函数显式传入 revision：分支名和标签适合表达可读的版本，完整 commit hash 才适合把一次实验或部署固定在不可变的提交上。

官方地址：https://huggingface.co/

先看 revision 到底固定了什么

先把三个概念分开：repo_id 是仓库身份，例如 openai-community/gpt2；revision 是仓库中的修订定位，可以写分支、标签或 commit hash；真正决定某一组文件内容的，是这个仓库对应的提交版本。只写 main 并不等于永久固定，因为仓库后续提交会改变它指向的内容。

因此可以按使用目的选择定位方式：开发期用分支名跟随更新，发布记录可以使用标签，复现实验或生产部署则记录完整 commit hash。注意 commit hash 只对它所属的仓库有意义，不能把一个仓库解析出来的提交值直接套到另一个仓库。

下载文件或快照时显式传入 revision

单文件下载使用 hf_hub_download()，整仓库下载使用 snapshot_download()。两者都把版本选择放在 revision 参数中；示例中的提交值只是格式示意，实际项目应替换成目标仓库提交历史里已经确认的完整值。

from huggingface_hub import hf_hub_download, snapshot_download

# 用完整提交标识固定本次读取的仓库版本；示例值应替换为目标仓库的真实提交。
MODEL_REVISION = "0123456789abcdef0123456789abcdef01234567"

# 只取配置文件，适合检查或读取单个固定版本的文件。
config_path = hf_hub_download(
    repo_id="openai-community/gpt2",
    filename="config.json",
    revision=MODEL_REVISION,
)

# 需要模型目录时固定同一个 revision，避免目录内容跟随 main 漂移。
snapshot_path = snapshot_download(
    repo_id="openai-community/gpt2",
    revision=MODEL_REVISION,
)

print(config_path)
print(snapshot_path)

命令行也可以传同一个版本定位：

# --revision 接收分支、标签或提交标识；这里使用提交值表达固定版本。
hf download openai-community/gpt2 config.json \
  --revision 0123456789abcdef0123456789abcdef01234567

这里的关键不是把字符串写在代码里，而是让版本值进入配置、部署清单或实验记录，并和 repo_id 成对保存。这样回看日志时，才能知道这个 hash 属于哪个模型仓库。

Transformers 加载模型时固定 revision

使用 Transformers 时，把同一个提交值传给 from_pretrained() 的 revision 参数即可。它约束的是模型仓库中被加载的配置、权重等内容，而不是把模型名称改成某个本地目录。

from transformers import AutoModelForCausalLM, AutoTokenizer

# 模型和 tokenizer 必须共享仓库与版本，避免两次解析落到不同提交。
repo_id = "openai-community/gpt2"
revision = "0123456789abcdef0123456789abcdef01234567"

tokenizer = AutoTokenizer.from_pretrained(
    repo_id,
    revision=revision,
)
model = AutoModelForCausalLM.from_pretrained(
    repo_id,
    revision=revision,
)

print(model.config.model_type)

如果模型依赖仓库中的自定义建模代码，需要额外审慎处理 trust_remote_code=True。当代码和模型内容来自不同仓库或需要分别锁定时，Transformers 还提供 code_revision 这一独立边界；不要把“模型权重版本”和“远程代码版本”混成一个未经说明的字符串。

多个组件要共享同一个提交版本

问题通常出现在更复杂的加载器里：配置、权重、tokenizer、processor 或 adapter 由不同函数分别下载。如果每次都传 revision="main"，仓库在两次请求之间更新时，理论上可能拿到不同提交。Hugging Face Hub 提供 resolve_revision() 先解析一次，再把返回的 ResolvedRevision 传给后续下载。

from huggingface_hub import hf_hub_download, resolve_revision

repo_id = "openai-community/gpt2"

# 先把可读的 main 解析成这个仓库当前对应的提交，后续复用解析结果。
resolved = resolve_revision(repo_id, revision="main")

# 同一个 ResolvedRevision 只回传给原来解析它的仓库。
config_path = hf_hub_download(repo_id, "config.json", revision=resolved)
weights_path = hf_hub_download(repo_id, "model.safetensors", revision=resolved)
tokenizer_path = hf_hub_download(repo_id, "tokenizer.json", revision=resolved)

print(resolved.resolved)
print(config_path, weights_path, tokenizer_path)

ResolvedRevision 仍保留用户最初请求的可读值，同时提供解析后的提交值。对同一个仓库的多个文件复用它，可以把“解析哪一版”和“下载哪些文件”分开。跨仓库下载时，要为另一个 repo_id 重新解析，不能直接复用旧仓库的提交。

用记录清单确认版本真的被固定

复查时先看 repo_id 与提交值是否成对出现，再看所有组件是否使用同一个解析结果。若日志只写了 main，它能说明“当时跟随主分支”，却不能单独证明内容永远不变；若只写 hash 而没有仓库名，也无法判断这个 hash 是否属于当前模型。

常见问题

revision 只能写 commit hash 吗？

不是。官方下载接口支持分支、标签和提交标识。可读名称方便开发，提交值更适合复现实验和部署记录。

为什么配置和权重要共用一个 ResolvedRevision？

因为分开用可变分支名解析时，两次请求可能落在不同提交；先解析一次再复用，可以让同一仓库的多个文件共享一个版本锚点。

不同模型仓库可以复用同一个 commit hash 吗？

不应该。提交值属于具体仓库，跨仓库时需要以目标仓库为对象重新解析。