共享预训练模型

在下面的步骤中，我们将介绍将预训练模型共享到 🤗 Hub 的最简单方法。有可用的工具和实用程序可以简化直接在 Hub 上共享和更新模型，我们将在下面探讨。

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

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

使用 push_to_hub API
使用 huggingface_hub Python 库
使用网页界面

创建仓库后，您可以通过 git 和 git-lfs 将文件上传到其中。我们将在以下部分中指导您创建模型仓库并向其上传文件。

使用 push_to_hub API

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

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

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() 来上传模型的最新版本。它还将生成一个包含所有相关元数据的模型卡，报告使用的超参数和评估结果！以下是您可能会在这样的模型卡中找到的内容示例：

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)

您可以随意使用它们 — 向分词器添加 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 token，也可以将其指定给 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 方法可用于在 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"。

仓库创建后，我们应该向其中添加文件！跳到下一节，查看三种处理方式。

使用网页界面

网页界面提供了直接在 Hub 中管理仓库的工具。使用该界面，您可以轻松创建仓库、添加文件（甚至大型文件！）、探索模型、可视化差异等等。

要创建新仓库，请访问 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 Hub 上的文件管理系统基于 Git 处理常规文件，以及 Git Large File Storage (Git LFS) 处理较大文件。

在下一节中，我们将介绍三种不同的文件上传方式：通过 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 文件作为 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 文档，以了解所有可用方法。

目前，我们有一个模型和一个分词器，我们想将其推送到 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 文件。如果您按照上一节中的说明使用网页界面创建了仓库，该文件夹应该包含一个 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。

✏️ 当从网页界面创建仓库时，*.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

同样，我们可以使用 Git LFS 的 status 命令来确保它正在跟踪正确的文件：

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.

< > 在 GitHub 上更新

LLM 课程