分享预训练模型

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

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

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

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

创建存储库后，您可以通过 git 和 git-lfs 将文件上传到其中。我们将在以下部分引导您完成创建模型存储库和将文件上传到其中的过程。

使用 push_to_hub API

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

在继续之前，您需要生成一个身份验证令牌，以便 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）将其上传到 Hub，存储在您命名空间中的存储库中。该存储库将以您选择的输出目录（此处为 bert-finetuned-mrpc）命名，但您可以使用 hub_model_id = "a_different_name" 选择其他名称。

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

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

An example of an auto-generated model card.

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

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

from transformers import AutoModelForMaskedLM, AutoTokenizer

checkpoint = "camembert-base"

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

您可以随意使用它们——向分词器添加标记，训练模型，对其进行微调。一旦您对生成的模型、权重和分词器感到满意，就可以直接利用 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>")

现在转到模型中心以查找您新上传的模型：https://huggingface.co/user-or-organization/dummy-model。

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

Dummy model containing both the tokenizer and model files.

✏️ **试一试！** 获取与 bert-base-cased 检查点关联的模型和分词器，并使用 push_to_hub() 方法将它们上传到您命名空间中的存储库。在删除它之前，请仔细检查存储库是否已正确显示在您的页面上。

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

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

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

使用 huggingface_hub Python 库

huggingface_hub Python 库是一个提供模型和数据集中心工具集的软件包。它提供了一些简单的方法和类，用于执行常见任务，例如获取有关中心上存储库的信息以及管理它们。它提供基于 Git 的简单 API，用于管理这些存储库的内容，并将中心集成到您的项目和库中。

类似于使用 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 方法可用于在中心上创建一个新的存储库。

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"。

创建存储库后，我们应该向其中添加文件！请跳到下一节查看处理此问题的三种方法。

使用网页界面

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

要创建新的存储库，请访问 huggingface.co/new

Page showcasing the model used for the creation of a new model repository.

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

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

创建模型存储库后，您应该会看到如下页面

An empty model page after creating a new repository.

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

The README file showing the Markdown capabilities.

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

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

The 'Files and versions' tab only shows the .gitattributes and README.md files.

我们将在接下来看看如何添加一些新文件。

上传模型文件

Hugging Face 中心上管理文件的系统基于 Git 处理常规文件，并使用 Git LFS（代表 Git 大型文件存储）处理较大的文件。

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

`upload_file` 方法

使用 upload_file 不需要在您的系统上安装 Git 和 Git LFS。它使用 HTTP POST 请求将文件直接推送到 🤗 中心。这种方法的限制是它无法处理大小超过 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 作为 config.json 上传到存储库的根目录，到 dummy-model 存储库。其他可能有用的参数包括：

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 文档，以概述所有可用方法。

目前，我们有一个模型和一个标记器，我们希望将其推送到中心。我们已成功克隆了存储库，因此可以将文件保存在该存储库中。

我们首先确保我们的本地克隆是最新的，方法是拉取最新的更改：

repo.git_pull()

完成后，我们保存模型和标记器文件：

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

<path_to_dummy_folder> 现在包含所有模型和标记器文件。我们按照通常的 Git 工作流程，将文件添加到暂存区，提交它们并将其推送到中心：

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

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

基于 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 中心的 create_repo 方法创建了存储库，则此文件夹应该只包含一个隐藏的 .gitattributes 文件。如果您按照上一节中的说明使用网页界面创建了存储库，则该文件夹应该包含一个 README.md 文件以及隐藏的 .gitattributes 文件，如下所示。

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

让我们回到 Python，生成一个模型和标记器，我们希望将其提交到我们的 dummy 存储库中：

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。

✏️ 当从 Web 界面创建存储库时，*.gitattributes* 文件会自动设置为考虑具有某些扩展名的文件（例如 *.bin* 和 *.h5*）作为大文件，并且 git-lfs 会跟踪它们，而无需您进行任何设置。

现在我们可以继续像往常一样处理传统的 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

类似地，我们可以使用其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:

我们可以看到所有文件都具有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

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

The 'Files and versions' tab now contains all the recently uploaded files.

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

The diff introduced by the recent commit.

NLP 课程