企业官网建设流程全解析

Transformers 模型共享指南：将训练完成的模型发布到 Hugging Face Hub 的完整实战

【免费下载链接】transformers🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers

在完成模型的微调训练之后，下一个关键步骤就是将成果分享给社区。本文基于 Hugging Face Transformers 仓库中的官方共享指南（docs/source/it/model_sharing.md，英文原版见 docs/source/en/model_sharing.md），系统讲解把训练好或微调好的模型上传到 Model Hub 的两种主流方式——编程式共享（通过Trainer或push_to_hub方法）与网页拖拽上传，并结合仓库源码剖析底层实现。读完本文，你将掌握从登录认证、跨框架转换、训练中自动推送，到撰写 Model Card 的完整发布链路。

一、为什么要把模型分享到 Hub

Hugging Face 的核心理念是共享知识与资源，让 AI 对所有人民主化。将训练好的模型发布到 Model Hub，能帮助其他开发者省去重复训练的时间与算力成本。在 Transformers 生态中，模型分享有两个关键途径：

• 编程式共享：通过 Python 代码把文件推送到 Hub，适合与训练流程深度集成；
• 界面拖拽共享：通过 Hub 的网页图形界面无代码上传，适合快速发布。

无论哪种方式，最终模型都能被全世界任何开发者通过一行from_pretrained加载使用。

二、发布前的环境配置

1. 注册账号与获取凭据

要与社区共享模型，首先需要一个 huggingface.co 账号。你也可以加入现有组织或创建新组织，以便以组织名义发布模型。接下来需要生成一个**用户访问令牌（User Access Token）**用于身份认证。

2. 命令行登录：hf auth login

如果你有终端环境，在安装了 Transformers 的虚拟环境中执行以下命令登录。该命令会把访问令牌保存在 Hugging Face 的缓存目录中（默认是~/.cache/）：

hf auth login

登录后令牌默认存放在缓存目录中，后续所有需要认证的推送操作都会自动读取它。这一机制在源码中也有体现：PushToHubMixin.push_to_hub的token参数文档明确指出，默认会使用执行hf auth login时生成并存储在~/.huggingface中的令牌（见 hub.py）。

3. 笔记本环境登录：notebook_login

如果使用 Jupyter 或 Colaboratory 这类笔记本环境，需要先安装huggingface_hub库——它是与 Hub 进行编程式交互的基础依赖：

pip install huggingface_hub

然后通过notebook_login登录，它会生成一个链接引导你在浏览器中完成令牌授权：

>>> from huggingface_hub import notebook_login >>> notebook_login()

三、Model Hub 仓库的核心特性

1. 基于 Git 与 Git LFS 的版本管理

Model Hub 上的每个模型仓库都像一个典型的 GitHub 仓库，提供**版本管理、提交历史（commit history）与差异可视化（diff）**功能。版本管理的底层基于 Git 和 Git Large File Storage (Git LFS)，因此可以把模型当作一个真正的代码仓库来对待，获得更精细的访问控制与更强的可扩展性——这正是大模型权重这类超大文件得以高效托管的关键。

2. 用revision固定模型版本

版本管理衍生出 **revisions（修订版本）**机制：你可以用提交哈希（commit hash）、标签（tag）或分支（branch）来固定模型的某个特定版本，实现可复现的加载。在from_pretrained中传入revision参数即可：

>>> model = AutoModel.from_pretrained( ... "julien-c/EsperBERTo-small", revision="4c77982" # 标签名、分支名或提交哈希 ... )

这一参数背后对应仓库源码中的下载逻辑：get_checkpoint_shard_files等函数会把revision透传给 Hub API，用于拉取对应版本的权重文件（见 hub.py）。同理，在推送时你也可以通过revision指定推送到的目标分支。

3. 仓库的访问控制与交互能力

除了版本管理，模型仓库还支持门控（gating）机制来控制谁能访问模型——这在研究模型公开发布前，只允许特定群体预览时非常实用。仓库还内嵌推理 Widget，让访问者在网页上直接与模型交互试玩。

四、跨框架转换：让模型适配所有生态

为了让使用不同深度学习框架的开发者都能直接使用你的模型，官方强烈建议同时上传 PyTorch 和 TensorFlow 两种格式的 checkpoint。虽然 Transformers 也能从异构框架加载模型，但如果跳过转换步骤，加载时会因为需要现场转换 checkpoint 而明显变慢。

转换过程非常简单：确保本地同时安装了 PyTorch 和 TensorFlow（安装说明见 安装指南），然后在目标框架中找到对应任务的模型类。例如要把 TensorFlow checkpoint 转换为 PyTorch，指定from_tf=True：

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

执行完save_pretrained后，本地目录就同时拥有了两份权重，随后便可将它们一起推送到 Hub（见后文push_to_hub小节）。

五、训练期间自动共享：Trainer 的一键推送

把模型分享到 Hub 简单到只需要添加一个额外参数或一个回调。还记得微调教程（docs/source/en/training.md）中的TrainingArguments吗？它就是指定超参数和训练选项的地方，其中就包含直接向 Hub 推送模型的开关。

1. 开启push_to_hub并训练

在TrainingArguments中设置push_to_hub=True：

>>> from transformers import TrainingArguments, Trainer >>> 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, ... )

从源码看，push_to_hub的完整语义是"每次保存模型时都推送到 Hub"（见 training_args.py）。开启后，output_dir会成为一个与 Hub 仓库同步的 git 目录，每次触发保存（由save_strategy决定）都会执行推送，调用Trainer.save_model也会触发推送。

2. 训练结束后手动推送

微调完成后，调用Trainer.push_to_hub上传训练好的模型：

>>> trainer.push_to_hub()

Trainer.push_to_hub默认的提交消息是"End of training"，并支持blocking（是否等待 git push 完成）、token、revision等参数。Transformers 还会自动把训练超参数、训练结果和框架版本写入你的 Model Card，无需手动整理。

从实现细节看（见 trainer.py），push_to_hub会依次执行：初始化 Hub 仓库（如果尚未创建）、调用save_model保存模型、调用create_model_card生成模型卡片、最后通过hf_api().upload_folder把output_dir整体上传，并自动忽略_*临时文件与checkpoint-*检查点目录。

3. 训练过程中的推送策略：hub_strategy

如果希望训练过程中就持续推送中间结果（而不仅是训练结束），可以配置hub_strategy参数（见 training_args.py）。它有四种取值：

与之配合的参数还包括：

• hub_model_id：指定要同步的仓库名。可以是简单的模型 ID（推送到你的命名空间下），也可以是"user_name/model"或"organization_name/model"形式的完整仓库名；默认值为user_name/output_dir 名称；
• hub_token：推送使用的令牌，默认取hf auth login缓存的令牌；
• hub_private_repo：是否创建私有仓库。为None（默认）时仓库公开，除非组织默认私有；仓库已存在时该参数被忽略；
• hub_always_push：为True时，即使上一次推送尚未完成也会继续推送，否则会跳过本次推送；
• hub_revision：推送目标分支，可以是分支名、标签或提交哈希。

Trainer内部的_push_from_checkpoint（见 trainer.py）会从 checkpoint 目录中挑选配置文件、权重文件、分片索引与分片文件，连同 tokenizer 和训练参数一起上传，并以"Training in progress, step N / epoch N"作为提交消息。整个上传过程是异步的，避免阻塞训练循环。

六、直接调用push_to_hub函数上传模型

除了Trainer，你还可以直接在模型对象上调用push_to_hub上传。它的底层是PushToHubMixin——一个为模型、tokenizer 等对象提供 Hub 推送能力的混入类（Mixin）。

1. 基础用法

指定模型名称即可创建仓库并上传：

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

这会在你的用户名下创建一个名为my-awesome-model的仓库。现在任何人都可以用from_pretrained加载你的模型：

>>> from transformers import AutoModel >>> model = AutoModel.from_pretrained("your-username/my-awesome-model")

2. 推送到组织

如果你属于某个组织，想以组织名义发布模型，push_to_hub接受organization参数（这是文档中的经典写法）：

>>> pt_model.push_to_hub("my-awesome-model", organization="my-awesome-org")

注：从当前仓库源码看，新版PushToHubMixin.push_to_hub已不再单列organization参数，推荐直接使用"组织名/模型名"形式的repo_id——例如pt_model.push_to_hub("my-awesome-org/my-awesome-model")（见 hub.py 中的 docstring 示例）。旧式organization写法在早期版本仍可工作。

3. 向同一仓库追加其他文件

push_to_hub不仅能上传模型权重，还能把 tokenizer、TensorFlow 版本权重等文件追加到同一个仓库。例如把 tokenizer 加入模型仓库：

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

或者把你 PyTorch 模型的 TensorFlow 版本也推上去：

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

现在浏览你的 Hugging Face 个人主页，就能看到新建的模型仓库；点击Files标签页可以看到全部已上传文件。

4.push_to_hub的完整参数

结合 hub.py 的实现，PushToHubMixin.push_to_hub支持的参数非常丰富：

从执行流程看（hub.py），push_to_hub的完整调用链是：先用hf_api().create_repo创建仓库（已存在则复用）→ 生成/更新 Model Card 并打标签 → 在临时目录中调用save_pretrained保存全部文件 → 把 Model Card 写入README.md→ 最后通过_upload_modified_files把临时目录中的文件以一次 commit 推送到远端。其中_upload_modified_files（hub.py）会基于文件的修改时间戳智能识别需要上传的文件，并在指定revision时自动创建对应分支。

5. 使用save_pretrained的注意点

需要特别说明：PushToHubMixin依赖对象自身实现save_pretrained方法。mixin 中的save_pretrained只是显式抛出不实现的约定（见 hub.py），模型、tokenizer 等具体类必须自己实现序列化逻辑，push_to_hub才能正常工作。这也解释了为什么它能统一适用于模型、tokenizer、feature extractor 和 processor 等各种对象。

七、无代码方案：使用网页界面上传

偏好零代码工作流的开发者，可以直接通过 Hub 网页界面上传模型。

1. 创建仓库

访问 huggingface.co/new 创建新仓库，然后填写模型信息：

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

2. 上传文件

点击Files标签页，再点击Add file按钮，把文件拖拽进上传区域，填写提交消息（commit message）后提交，文件即进入仓库。

3. 网页方式与代码方式的取舍

网页方式适合快速发布、非技术成员协作等场景；代码方式（Trainer/push_to_hub）则能融入自动化训练流水线，实现"训练完即发布"，并自动生成带训练元数据的 Model Card。实际项目中常两者结合：用代码推送权重，再用网页补充说明文档。

八、添加 Model Card：让模型可被理解与信任

为了确保任何使用你模型的人都能了解它的能力、局限性、潜在偏见与伦理考量，官方强烈建议为仓库添加一张Model Card（模型卡）。Model Card 就是仓库根目录下的README.md文件，可以通过两种方式添加：

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

1. Trainer 自动生成 Model Card

使用Trainer.push_to_hub时，Transformers 会自动生成 Model Card。Trainer.create_model_card（见 trainer.py）会把TrainingSummary汇总的训练信息写入output_dir/README.md。它还支持通过参数补充卡片元数据：

• language：模型适用的语言；
• license：模型许可证，默认继承原始预训练模型仓库的许可证；
• tags：卡片元数据标签；
• model_name：模型名称；
• finetuned_from：微调所基于的基座模型（默认取传入Trainer的原始模型仓库名）；
• tasks：任务标识符；
• dataset_tags/dataset/dataset_args：训练数据集信息。

如果输出目录中已有README.md，create_model_card还会自动合并已有标签，避免覆盖手工维护的卡片内容。

2. 手动补充更多元数据

除了上述字段，Model Card 的README.md还可以通过 YAML front-matter 声明碳足迹（carbon emissions）、论文链接、许可证、示例 Widget 等更多元数据，让模型信息更完整。一个好的 Model Card 应涵盖：模型用途与能力、训练数据与过程、评估指标与结果、已知限制与偏见、伦理考量以及使用示例。

九、发布后的验证与最佳实践

1. 验证模型可被加载

发布后，建议在一个全新的环境中用from_pretrained验证加载是否成功：

>>> from transformers import AutoModel >>> model = AutoModel.from_pretrained("your-username/my-awesome-model")

2. 组合技巧速查

3. 几点提醒

• 上传大模型时会自动分片（max_shard_size默认"50GB"），无需手动处理；
• 若仓库已存在，private参数会被忽略，可见性以仓库当前状态为准；
• 分布式训练时，Trainer会保证只在主进程执行推送（is_world_process_zero判断），避免重复上传（见 trainer.py）。

至此，从登录认证、跨框架转换、训练中一键推送、手动push_to_hub、网页上传到 Model Card 撰写，你已经掌握了完整的模型发布链路。把模型共享出去，让开源 AI 的成果惠及更多人。

【免费下载链接】transformers🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers