Transformers 模型分享指南：从 Trainer.push_to_hub 到 Hub 仓库版本管理的完整实践

本文基于 Transformers 官方文档中的模型分享教程（model_sharing），介绍如何将训练或微调完成的模型发布到 Hugging Face Hub 的两种主要方式：通过代码编程式上传，以及通过 Web 界面拖拽上传。读完本文，你将掌握 push_to_hub 的完整用法、TrainingArguments 中全部 Hub 同步参数的含义、跨框架 checkpoint 转换方法，以及模型卡片（model card）的编写规范，并能从源码层面理解 Trainer.push_to_hub 的底层行为。

模型分享的两个入口

Transformers 支持两种把模型送上 Hub 的路径：

1. 编程式上传：直接用代码将模型文件推到 Hub；
2. Web 界面上传：通过 Hugging Face 网页拖拽文件完成上传。

发布模型需要拥有一个 huggingface.co 账号，也可以加入或创建一个组织（organization），以组织名义发布模型。

Hub 仓库特性：基于 Git 与 LFS 的版本管理

Hub 上的每个模型仓库都像一个传统的 Git 仓库：提供版本控制、变更历史，以及版本间差异对比能力。其底层依赖 git 和 git-lfs（Git Large File Storage），因此每个模型都可以被当作一个独立仓库来管理，支持细粒度的访问控制与可扩展性。借助版本控制，你可以按 commit hash、tag（标签）或 branch（分支）来指定模型的某个具体版本。

加载特定版本的模型只需使用 revision 参数：

>>> model = AutoModel.from_pretrained(
...     "julien-c/EsperBERTo-small", revision="4c77982"  # 可以是 tag、branch 或 commit hash
... )

此外，仓库中的文件可以直接修改，并且可以查看文件的历史变更记录与不同版本间的 diff。

准备工作：登录与认证

在把模型发布到 Hub 之前，需要配置 Hugging Face 账号凭证。

命令行环境（假设已在虚拟环境中安装了 Transformers）执行：

hf auth login

该命令会把访问令牌（token）保存到 Hugging Face 的缓存目录（默认是 ~/.cache/）。

Jupyter / Colaboratory 等 Notebook 环境则需先安装 huggingface_hub 库——它提供与 Hub 编程交互的能力：

pip install huggingface_hub

然后用 notebook_login 完成登录（需先在 Hub 的 token 设置页创建访问令牌）：

>>> from huggingface_hub import notebook_login

>>> notebook_login()

让模型兼容多框架：转换 checkpoint

为了让使用不同框架的用户都能顺畅地加载你的模型，官方建议同时上传 PyTorch 与 TensorFlow 两种 checkpoint。如果只上传其中一种，其他框架的用户仍然可以通过 from_pretrained 加载模型，但 Transformers 会在运行时自动转换权重，速度会更慢。

转换 checkpoint 很简单：确认环境中已安装 PyTorch 和 TensorFlow 后，在目标框架下找到对应的模型类，通过 from_tf=True 完成 TensorFlow 到 PyTorch 的转换：

>>> pt_model = DistilBertForSequenceClassification.from_pretrained("path/to/awesome-name-you-picked", from_tf=True)
>>> pt_model.save_pretrained("path/to/awesome-name-you-picked")

训练期间推送模型到 Hub

分享模型只需要在训练配置中加一个参数。回顾训练流程：超参与训练选项都集中在 TrainingArguments 中，而它正好内置了直接推送模型到 Hub 的能力。设置 push_to_hub=True：

>>> training_args = TrainingArguments(output_dir="my-awesome-model", push_to_hub=True)

然后像往常一样把参数传给 Trainer：

>>> trainer = Trainer(
...     model=model,
...     args=training_args,
...     train_dataset=small_train_dataset,
...     eval_dataset=small_eval_dataset,
...     compute_metrics=compute_metrics,
... )

微调完成后，调用 Trainer 提供的 push_to_hub 方法把模型推送到 Hub。Transformers 会自动把训练时使用的超参数、训练结果和各框架版本信息写入模型卡片（model card）。

>>> trainer.push_to_hub()

源码视角：Trainer.push_to_hub 做了什么

查看 src/transformers/trainer.py 中 Trainer.push_to_hub 的实现（第 4058 行起），可以看到完整流程：

• 触发 on_push_begin 回调，允许通过回调机制观察推送过程；
• 若 hub_model_id 未显式设置，则回退到 output_dir 的目录名作为仓库名；
• 调用 save_model 保存模型，且只在 is_world_process_zero()（主进程）上真正执行推送，避免分布式训练时多个节点重复上传；
• 若模型尚未初始化 Hub 仓库（即 push_to_hub 未在构造时开启），会补调 init_hf_repo。

而"自动写入超参数与训练结果"这一承诺，来自同文件第 3984 行起的 create_model_card 方法：它基于 TrainingSummary.from_trainer 汇总训练信息，生成模型卡草稿并写入 output_dir/README.md，且保留了 README 中已有的 tags 等元数据，兼容 PEFT 场景。

TrainingArguments 中的完整 Hub 参数组

除文档示例中的 push_to_hub 外，src/transformers/training_args.py 第 1190 行起的 "Hub Integration" 字段块还定义了以下配套参数，可按需组合：

参数	默认值	说明
push_to_hub	False	每次保存模型时是否同步推送到 Hub
hub_token	None	推送用的 token，默认取 hf auth login 缓存的 token
hub_private_repo	None	仓库是否私有；None 表示公开（除非组织默认私有），仓库已存在时忽略
hub_model_id	None	与本地 output_dir 保持同步的仓库名
hub_strategy	"every_save"	推送时机："end" / "every_save" / "checkpoint" / "all_checkpoints"
hub_always_push	False	为 True 时，即使上一次推送未完成也会继续推送新内容
hub_revision	None	推送目标 revision，可以是分支名、tag 或 commit hash

此外，TrainingArguments.set_push_to_hub 方法把上述参数聚合为一个链式调用入口，例如 args.set_push_to_hub("me/awesome-model") 会一次性设置 push_to_hub=True、hub_model_id 和推送策略。四种 hub_strategy 的语义（见该方法 docstring）值得注意：

• "end"：仅在训练结束调用 save_model 时推送一次模型、配置、tokenizer 和模型卡草稿；
• "every_save"：每次保存时异步推送（不阻塞训练，上一次推送未完成则跳过新推送），训练结束再推最终模型；
• "checkpoint"：在 every_save 基础上把最新 checkpoint 推到 last-checkpoint 子文件夹，可用 trainer.train(resume_from_checkpoint="last-checkpoint") 断点续训；
• "all_checkpoints"：把 output_dir 中出现的所有 checkpoint 目录完整推送到仓库。

直接调用 push_to_hub

除了走 Trainer 流程，也可以直接在模型对象上调用 push_to_hub 上传到 Hub。指定模型名即可：

>>> pt_model.push_to_hub("my-awesome-model")

这会在你的用户名下创建名为 my-awesome-model 的仓库，其他用户现在就能这样加载它：

>>> from transformers import AutoModel

>>> model = AutoModel.from_pretrained("your_username/my-awesome-model")

如果属于某个组织，想把模型发布在组织名下，只需在 repo_id 中加上组织前缀：

>>> pt_model.push_to_hub("my-awesome-org/my-awesome-model")

push_to_hub 同样适用于向模型仓库添加其他文件。例如把 tokenizer 加入同一仓库：

>>> tokenizer.push_to_hub("my-awesome-model")

或者把同一模型的 TensorFlow 版本追加进去：

>>> tf_model.push_to_hub("my-awesome-model")

从源码看，src/transformers/modeling_utils.py 第 3650 行的 PreTrainedModel.push_to_hub 是一个轻量包装：它先把模型的 model_tags 与调用方传入的 tags 参数合并（去重），再委托给底层（huggingface_hub）的同名方法执行实际上传。这也解释了为什么多次对同一仓库 push_to_hub 不同对象（模型、tokenizer、TF 版本）时能自然地汇聚到同一个仓库中。

完成推送后，登录你的 Hugging Face 个人资料页即可看到新建的模型仓库；点击 Files 标签页会列出所有已上传的文件。

通过 Web 界面上传

偏好无代码操作的用户可以直接用 Hub 的 Web 界面上传模型。访问 huggingface.co/new 创建新仓库，并填写：

• 所有者（Owner）：可以是自己，也可以是所属的任何组织；
• 模型名称：即仓库名；
• 可见性：选择公开（public）或私有（private）；
• 许可证（License）：为模型指定使用许可。

然后进入 Files 标签页，点击 Add file 按钮，拖入文件并填写提交信息（commit message）即可完成上传。

添加模型卡片（Model Card）

为了让使用者理解模型的能力边界、局限性、潜在偏差和伦理注意事项，官方强烈建议为仓库添加模型卡片。模型卡片就是仓库中的 README.md 文件，有两种添加方式：

• 手动创建 README.md 文件并上传；
• 在模型仓库页面点击 Edit model card 按钮在线编辑。

模型卡片应涵盖的信息类型可参考 DistilBERT 的官方仓库卡片。除基本介绍外，README.md 还支持声明碳足迹、嵌入可运行的示例代码等富内容选项。值得注意的是，若走 Trainer 流程，create_model_card（src/transformers/trainer.py）已经会自动生成包含训练超参的卡片草稿，你只需在其基础上补充任务说明与使用示例即可。