共享预训练模型

在下面的步骤中，我们将介绍将预训练模型共享到 🤗 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）将您的模型上传到 Hub，上传到您命名空间中的一个仓库。该仓库将以您选择的输出目录命名（此处为 bert-finetuned-mrpc），但您可以使用 hub_model_id = "a_different_name" 选择不同的名称。

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

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

在更底层的级别上，可以通过模型、分词器和配置对象的 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。

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

正如您所见，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

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

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

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

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

README 文件是 Markdown 格式的 - 请随意使用它！本章的第三部分专门用于构建模型卡片。这些对于为您的模型带来价值至关重要，因为它们是您告诉其他人它能做什么的地方。

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

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

上传模型文件

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

现在，我们可以像使用传统 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:

我们可以看到所有文件都使用 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 允许您浏览模型文件和提交，以及查看每次提交所引入的差异。