分享预训练模型

在以下步骤中，我们将了解将预训练模型分享到 🤗 Hub 的最简单方法。有一些工具和实用程序可用于直接在 Hub 上轻松分享和更新模型，我们将在下面进行探讨。

我们鼓励所有训练模型的用户通过与社区分享来做出贡献 —— 分享模型，即使是在非常特定的数据集上训练的模型，也将帮助他人，节省他们的时间和计算资源，并提供对有用的已训练工件的访问。反过来，您可以从其他人所做的工作中受益！

创建新的模型仓库有三种方法

• 使用 push_to_hub API
• 使用 huggingface_hub Python 库
• 使用 Web 界面

创建仓库后，您可以通过 git 和 git-lfs 将文件上传到其中。在以下章节中，我们将引导您完成创建模型仓库并将文件上传到这些仓库的过程。

使用 push_to_hub API

将文件上传到 Hub 的最简单方法是利用 push_to_hub API。

在继续之前，您需要生成一个身份验证令牌，以便 huggingface_hub API 知道您的身份以及您拥有写入权限的命名空间。确保您处于已安装 transformers 的环境中（请参阅设置）。如果您在笔记本中，可以使用以下函数登录

from huggingface_hub import notebook_login

notebook_login()

在终端中，您可以运行

huggingface-cli login

在这两种情况下，系统都会提示您输入用户名和密码，这与您登录 Hub 时使用的用户名和密码相同。如果您还没有 Hub 个人资料，您应该在此处创建一个。

太棒了！您现在已将身份验证令牌存储在缓存文件夹中。让我们创建一些仓库！

如果您使用过 Trainer API 来训练模型，则将其上传到 Hub 的最简单方法是在定义 TrainingArguments 时设置 push_to_hub=True

from transformers import TrainingArguments

training_args = TrainingArguments(
    "bert-finetuned-mrpc", save_strategy="epoch", push_to_hub=True
)

当您调用 trainer.train() 时，Trainer 会在每次保存模型时（此处为每个 epoch）将其上传到您命名空间中的仓库。该仓库将以您选择的输出目录（此处为 bert-finetuned-mrpc）命名，但您可以使用 hub_model_id = "a_different_name" 选择不同的名称。

要将模型上传到您所属的组织，只需使用 hub_model_id = "my_organization/my_repo_name" 传递它即可。

训练完成后，您应该执行最终的 trainer.push_to_hub() 来上传模型的最新版本。它还将生成一个模型卡片，其中包含所有相关的元数据，报告所使用的超参数和评估结果！以下是您可能在这样的模型卡片中找到的内容示例

在较低级别，可以通过模型、分词器和配置对象的 push_to_hub() 方法直接访问 Model Hub。此方法负责仓库创建和将模型及分词器文件直接推送到仓库。与我们将在下面看到的 API 不同，无需手动处理。

为了了解它的工作原理，我们首先初始化一个模型和一个分词器

from transformers import AutoModelForMaskedLM, AutoTokenizer

checkpoint = "camembert-base"

model = AutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)

您可以随意对它们进行任何操作 —— 向分词器添加 token，训练模型，微调模型。一旦您对生成的模型、权重和分词器感到满意，就可以利用 model 对象上直接可用的 push_to_hub() 方法

model.push_to_hub("dummy-model")

这将在您的个人资料中创建新的仓库 dummy-model，并用您的模型文件填充它。对分词器执行相同的操作，以便所有文件现在都可以在此仓库中使用

tokenizer.push_to_hub("dummy-model")

如果您属于某个组织，只需指定 organization 参数即可上传到该组织的命名空间

tokenizer.push_to_hub("dummy-model", organization="huggingface")

如果您希望使用特定的 Hugging Face 令牌，您可以自由地将其指定给 push_to_hub() 方法

tokenizer.push_to_hub("dummy-model", organization="huggingface", use_auth_token="<TOKEN>")

现在前往 Model Hub 查找您新上传的模型：https://huggingface.co/user-or-organization/dummy-model。

单击“文件和版本”选项卡，您应该看到以下屏幕截图中可见的文件

如您所见，push_to_hub() 方法接受多个参数，从而可以上传到特定的仓库或组织命名空间，或使用不同的 API 令牌。我们建议您查看 🤗 Transformers 文档中直接提供的方法规范，以了解可能的用途。

push_to_hub() 方法由 huggingface_hub Python 包支持，该包为 Hugging Face Hub 提供了直接的 API。它已集成到 🤗 Transformers 和其他几个机器学习库中，例如 allenlp。尽管在本章中我们重点介绍 🤗 Transformers 集成，但将其集成到您自己的代码或库中也很简单。

跳转到最后一节，了解如何将文件上传到您新创建的仓库！

使用 huggingface_hub Python 库

huggingface_hub Python 库是一个软件包，为模型和数据集 Hub 提供了一组工具。它为常见的任务（例如获取有关 Hub 上仓库的信息和管理这些仓库）提供了简单的方法和类。它提供了在 git 之上工作的简单 API，用于管理这些仓库的内容，并将 Hub 集成到您的项目和库中。

与使用 push_to_hub API 类似，这将要求您将 API 令牌保存在缓存中。为此，您需要使用 CLI 中的 login 命令，如上一节所述（同样，如果运行在 Google Colab 中，请确保在这些命令前加上 ! 字符）

huggingface-cli login

huggingface_hub 包提供了几种对我们的目的有用的方法和类。首先，有一些方法可以管理仓库的创建、删除等

from huggingface_hub import (
    # User management
    login,
    logout,
    whoami,

    # Repository creation and management
    create_repo,
    delete_repo,
    update_repo_visibility,

    # And some methods to retrieve/change information about the content
    list_models,
    list_datasets,
    list_metrics,
    list_repo_files,
    upload_file,
    delete_file,
)

此外，它还提供了非常强大的 Repository 类来管理本地仓库。我们将在接下来的几节中探讨这些方法和该类，以了解如何利用它们。

create_repo 方法可用于在 Hub 上创建新仓库

from huggingface_hub import create_repo

create_repo("dummy-model")

这将在您的命名空间中创建仓库 dummy-model。如果您愿意，可以使用 organization 参数指定仓库应属于哪个组织

from huggingface_hub import create_repo

create_repo("dummy-model", organization="huggingface")

假设您属于该组织，这将在 huggingface 命名空间中创建 dummy-model 仓库。其他可能有用的参数包括

• private，用于指定仓库是否应从其他人处可见。
• token，如果您想用给定的令牌覆盖存储在缓存中的令牌。
• repo_type，如果您想创建 dataset 或 space 而不是模型。接受的值为 "dataset" 和 "space"。

创建仓库后，我们应该向其中添加文件！跳转到下一节，了解处理此问题的三种方法。

使用 Web 界面

Web 界面提供了直接在 Hub 中管理仓库的工具。使用该界面，您可以轻松地创建仓库、添加文件（即使是大型文件！）、浏览模型、可视化差异等等。

要创建新仓库，请访问 huggingface.co/new

首先，指定仓库的所有者：可以是您自己，也可以是您所属的任何组织。如果您选择一个组织，该模型将显示在该组织的页面上，并且该组织的每个成员都将有能力为该仓库做出贡献。

接下来，输入您的模型名称。这也将是仓库的名称。最后，您可以指定您希望模型是公开的还是私有的。私有模型对公众隐藏。

创建模型仓库后，您应该看到类似这样的页面

这是您的模型将托管的位置。要开始填充它，您可以直接从 Web 界面添加 README 文件。

README 文件采用 Markdown 格式 —— 随意使用它！本章的第三部分专门介绍构建模型卡片。这些对于为您的模型带来价值至关重要，因为您可以在其中告诉其他人它可以做什么。

如果您查看“文件和版本”选项卡，您会看到那里还没有很多文件 —— 只有您刚刚创建的 README.md 和跟踪大型文件的 .gitattributes 文件。

接下来，我们将了解如何添加一些新文件。

上传模型文件

Hugging Face Hub 上管理文件的系统基于用于常规文件的 git 和用于较大文件的 git-lfs（即 Git Large File Storage）。

在下一节中，我们将介绍通过 huggingface_hub 和 git 命令上传文件的三种不同方法。

upload_file 方法

使用 upload_file 不需要在您的系统上安装 git 和 git-lfs。它使用 HTTP POST 请求将文件直接推送到 🤗 Hub。这种方法的局限性在于它无法处理大于 5GB 的文件。如果您的文件大于 5GB，请按照下面详述的其他两种方法操作。

API 可以如下方式使用

from huggingface_hub import upload_file

upload_file(
    "<path_to_file>/config.json",
    path_in_repo="config.json",
    repo_id="<namespace>/dummy-model",
)

这将把位于 <path_to_file> 的文件 config.json 上传到 dummy-model 仓库的根目录，并命名为 config.json。其他可能有用的参数包括

• token，如果您想用给定的令牌覆盖存储在缓存中的令牌。
• repo_type，如果您想上传到 dataset 或 space 而不是模型。接受的值为 "dataset" 和 "space"。

Repository 类

Repository 类以类似于 git 的方式管理本地仓库。它抽象化了人们可能遇到的 git 的大多数痛点，以提供我们所需的所有功能。

使用此类需要安装 git 和 git-lfs，因此请确保您已安装 git-lfs（有关安装说明，请参阅此处）并在开始之前进行设置。

为了开始使用我们刚刚创建的仓库，我们可以通过克隆远程仓库来将其初始化到本地文件夹中

from huggingface_hub import Repository

repo = Repository("<path_to_dummy_folder>", clone_from="<namespace>/dummy-model")

这在我们的工作目录中创建了文件夹 <path_to_dummy_folder>。此文件夹仅包含 .gitattributes 文件，因为这是通过 create_repo 实例化仓库时创建的唯一文件。

从现在开始，我们可以利用几种传统的 git 方法

repo.git_pull()
repo.git_add()
repo.git_commit()
repo.git_push()
repo.git_tag()

以及其他方法！我们建议您查看 此处提供的 Repository 文档，以概述所有可用的方法。

目前，我们有一个模型和一个分词器，我们想将它们推送到 Hub。我们已成功克隆仓库，因此可以将文件保存在该仓库中。

我们首先通过拉取最新更改来确保我们的本地克隆是最新的

repo.git_pull()

完成此操作后，我们保存模型和分词器文件

model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")

<path_to_dummy_folder> 现在包含所有模型和分词器文件。我们遵循通常的 git 工作流程，将文件添加到暂存区，提交它们并将它们推送到 Hub

repo.git_add()
repo.git_commit("Add model and tokenizer files")
repo.git_push()

恭喜！您刚刚将您的第一个文件推送到了 Hub。

基于 git 的方法

这是上传文件的非常基本的方法：我们将直接使用 git 和 git-lfs 来完成。大多数困难都已被以前的方法抽象化，但是以下方法有一些注意事项，因此我们将遵循更复杂的使用案例。

使用此类需要安装 git 和 git-lfs，因此请确保您已安装 git-lfs（有关安装说明，请参阅此处）并在开始之前进行设置。

首先启动 git-lfs 初始化

git lfs install

Updated git hooks.
Git LFS initialized.

完成后，第一步是克隆您的模型仓库

git clone https://huggingface.co/<namespace>/<your-model-id>

我的用户名是 lysandre，我使用了模型名称 dummy，因此对​​于我来说，该命令最终看起来像这样

git clone https://huggingface.co/lysandre/dummy

我现在在我的工作目录中有一个名为 dummy 的文件夹。我可以 cd 进入文件夹并查看内容

cd dummy && ls

README.md

如果您只是使用 Hugging Face Hub 的 create_repo 方法创建了仓库，则此文件夹应仅包含一个隐藏的 .gitattributes 文件。如果您按照上一节中的说明使用 Web 界面创建了仓库，则该文件夹应包含一个 README.md 文件以及隐藏的 .gitattributes 文件，如此处所示。

添加常规大小的文件（例如配置文件、词汇表文件或基本上任何小于几兆字节的文件）的步骤与在任何基于 git 的系统中执行的操作完全相同。但是，较大的文件必须通过 git-lfs 注册才能将它们推送到 huggingface.co。

让我们回到 Python 一会儿，以生成我们想要提交到虚拟仓库的模型和分词器

from transformers import AutoModelForMaskedLM, AutoTokenizer

checkpoint = "camembert-base"

model = AutoModelForMaskedLM.from_pretrained(checkpoint)
tokenizer = AutoTokenizer.from_pretrained(checkpoint)

# Do whatever with the model, train it, fine-tune it...

model.save_pretrained("<path_to_dummy_folder>")
tokenizer.save_pretrained("<path_to_dummy_folder>")

现在我们已经保存了一些模型和分词器工件，让我们再次查看 dummy 文件夹

ls

config.json  pytorch_model.bin  README.md  sentencepiece.bpe.model  special_tokens_map.json tokenizer_config.json  tokenizer.json

如果您查看文件大小（例如，使用 ls -lh），您应该看到模型状态字典文件 (pytorch_model.bin) 是唯一的异常值，超过 400 MB。

我们现在可以继续进行，就像我们通常对传统 Git 仓库所做的那样。我们可以使用 git add 命令将所有文件添加到 Git 的暂存环境

git add .

然后，我们可以查看当前暂存的文件

git status

On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
  modified:   .gitattributes
	new file:   config.json
	new file:   pytorch_model.bin
	new file:   sentencepiece.bpe.model
	new file:   special_tokens_map.json
	new file:   tokenizer.json
	new file:   tokenizer_config.json

同样，我们可以通过使用 git-lfs 的 status 命令来确保 git-lfs 正在跟踪正确的文件

git lfs status

On branch main
Objects to be pushed to origin/main:


Objects to be committed:

	config.json (Git: bc20ff2)
	pytorch_model.bin (LFS: 35686c2)
	sentencepiece.bpe.model (LFS: 988bc5a)
	special_tokens_map.json (Git: cb23931)
	tokenizer.json (Git: 851ff3e)
	tokenizer_config.json (Git: f0f7783)

Objects not staged for commit:

我们可以看到，除了 pytorch_model.bin 和 sentencepiece.bpe.model 之外，所有文件都将 Git 作为处理程序，而 pytorch_model.bin 和 sentencepiece.bpe.model 将 LFS 作为处理程序。太棒了！

让我们继续执行最后步骤，提交并推送到 huggingface.co 远程仓库

git commit -m "First model version"

[main b08aab1] First model version
 7 files changed, 29027 insertions(+)
  6 files changed, 36 insertions(+)
 create mode 100644 config.json
 create mode 100644 pytorch_model.bin
 create mode 100644 sentencepiece.bpe.model
 create mode 100644 special_tokens_map.json
 create mode 100644 tokenizer.json
 create mode 100644 tokenizer_config.json

推送可能需要一段时间，具体取决于您的互联网连接速度和文件大小

git push

Uploading LFS objects: 100% (1/1), 433 MB | 1.3 MB/s, done.
Enumerating objects: 11, done.
Counting objects: 100% (11/11), done.
Delta compression using up to 12 threads
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 288.27 KiB | 6.27 MiB/s, done.
Total 9 (delta 1), reused 0 (delta 0), pack-reused 0
To https://huggingface.co/lysandre/dummy
   891b41d..b08aab1  main -> main

如果我们完成此操作后查看模型仓库，我们可以看到所有最近添加的文件

UI 允许您浏览模型文件和提交，并查看每个提交引入的差异