将您的库与 Hub 集成

Hugging Face Hub 旨在促进机器学习模型、检查点和工件的共享。这一工作包括将 Hub 集成到社区中许多出色的第三方库中。目前已集成的库包括 spaCy、Sentence Transformers、OpenCLIP 和 timm 等。集成意味着用户可以直接从您的库中下载和上传文件到 Hub。我们希望您能将您的库进行集成，与我们一起推动人工智能的普及，让每个人都能受益。

将 Hub 集成到您的库中可带来诸多好处，包括：

• 为您和您的用户提供免费的模型托管服务。
• 内置文件版本控制——即使是超大文件也能轻松实现——由 Git-Xet 提供支持。
• 社区功能（讨论、拉取请求、点赞）。
• 使用您库运行的所有模型的用量指标。

本教程将帮助您将 Hub 集成到您的库中，以便您的用户能够充分利用 Hub 提供的各项功能。

在开始之前，我们建议您创建一个 Hugging Face 账户，以便管理您的仓库和文件。

如果您在集成过程中需要帮助，请随时提交一个issue，我们非常乐意为您提供协助。

实现

实现库与 Hub 的集成，通常意味着提供内置方法来从 Hub 加载模型，并允许用户将新模型推送到 Hub。本节将介绍如何使用 huggingface_hub 库完成这些操作的基本方法。如需更深入的指导，请参阅 此指南。

安装

要将您的库与 Hub 集成，您需要将 huggingface_hub 库添加为依赖项：

pip install huggingface_hub

有关 huggingface_hub 安装的更多详细信息，请参阅 此指南。

在本指南中，我们将重点关注 Python 库。如果您使用 JavaScript 实现了您的库，可以改用 @huggingface/hub。其余逻辑（即托管文件、代码示例等）与代码语言无关。

已复制

npm add @huggingface/hub

成功安装 huggingface_hub 库后，用户需要进行身份验证。最简单的验证方式是将令牌保存在机器上。用户可以在终端中使用 login() 命令来完成此操作：

hf auth login

该命令会告知用户是否已登录，并提示其输入令牌。随后，令牌将被验证并保存在其 HF_HOME 目录中（默认为 ~/.cache/huggingface/token）。任何与 Hub 交互的脚本或库在发送请求时都会使用此令牌。

或者，用户可以在笔记本或脚本中通过编程方式使用 login() 进行登录：

from huggingface_hub import login
login()

从 Hub 上的公共仓库下载文件时，身份验证是可选的。

从 Hub 下载文件

集成允许用户从 Hub 下载模型，并直接从您的库中实例化它。这通常是通过提供一个特定于您库的方法（通常称为 from_pretrained 或 load_from_hf）来实现的。要从 Hub 实例化模型，您的库必须：

• 从 Hub 下载文件。这正是我们现在要讨论的内容。
• 从这些文件中实例化 Python 模型。

使用 hf_hub_download 方法从 Hub 上的仓库下载文件。下载的文件会存储在缓存目录 ~/.cache/huggingface/hub 中。下次使用时，用户无需重新下载该文件，这对于大文件而言能节省大量时间。此外，如果仓库更新了文件的新版本，huggingface_hub 会自动下载最新版本并将其存入缓存。用户无需手动更新文件。

例如，从 lysandre/arxiv-nlp 仓库下载 config.json 文件：

>>> from huggingface_hub import hf_hub_download
>>> config_path = hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json")
>>> config_path
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json'

config_path 现在包含已下载文件的路径。可以确保该文件存在且为最新版本。

如果你的库需要下载整个仓库，请使用 snapshot_download。它会自动并行下载所有文件。返回值是包含已下载文件的目录路径。

>>> from huggingface_hub import snapshot_download
>>> snapshot_download(repo_id="lysandre/arxiv-nlp")
'/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade'

有许多选项可用于从特定修订版本下载文件、筛选要下载的文件、提供自定义缓存目录、下载到本地目录等。有关更多详细信息，请参阅下载指南。

将文件上传到 Hub

您可能还想提供一个方法，以便用户可以将自己的模型推送到 Hub。这允许社区构建一个与您的库兼容的模型生态系统。huggingface_hub 库提供了创建仓库和上传文件的方法：

• create_repo 在 Hub 上创建一个仓库。
• upload_file 和 upload_folder 用于将文件上传到 Hub 上的仓库。

create_repo 方法用于在 Hub 上创建一个仓库。使用 repo_id 参数为你的仓库指定一个名称：

>>> from huggingface_hub import create_repo
>>> create_repo(repo_id="test-model")
'https://huggingface.co/lysandre/test-model'

检查你的 Hugging Face 账户时，你应该能在你的命名空间下看到一个 test-model 仓库。

upload_file 方法用于将文件上传到 Hub。此方法需要满足以下条件：

• 要上传的文件的路径。
• 仓库中的最终路径。
• 您希望推送文件到的仓库。

例如：

>>> from huggingface_hub import upload_file
>>> upload_file(
...    path_or_fileobj="/home/lysandre/dummy-test/README.md", 
...    path_in_repo="README.md", 
...    repo_id="lysandre/test-model"
... )
'https://huggingface.co/lysandre/test-model/blob/main/README.md'

检查你的 Hugging Face 账户，你应该能在你的仓库中看到该文件。

通常，库会将模型序列化到本地目录，然后一次性将整个文件夹上传到 Hub。可以使用 upload_folder 来完成此操作：

>>> from huggingface_hub import upload_folder
>>> upload_folder(
...     folder_path="/home/lysandre/dummy-test",
...     repo_id="lysandre/test-model",
... )

有关如何上传文件的更多详细信息，请参阅上传指南。

模型卡片

模型卡是随模型提供的文件，包含实用信息。在底层，模型卡是带有额外元数据的简单 Markdown 文件。模型卡对于可发现性、可复现性和共享至关重要！您可以在任何模型仓库中将其作为 README.md 文件找到。有关如何创建良好模型卡的更多详细信息，请参阅 模型卡指南。

如果您的库支持将模型推送到 Hub，建议生成一个包含预填元数据（通常为 library_name、pipeline_tag 或 tags）以及模型训练方式说明的最小化模型卡片。这有助于为使用您的库构建的所有模型提供标准化的描述。

注册你的库

干得漂亮！现在你应该已经拥有一个可以从 Hub 加载模型并最终推送新模型的库了。下一步是确保你在 Hub 上的模型文档完善，并与平台良好集成。为此，可以将库注册到 Hub，这将为使用者带来一些好处：

• 在模型页面上可以显示一个更美观的标签（例如，显示为 KerasNLP 而不是 keras-nlp）
• 每个模型页面都会添加一个指向您的库仓库和文档的链接
• 可以定义自定义的下载量规则
• 可以生成代码片段，展示如何使用您的库加载模型

要注册一个新库，请按照以下说明在此处提交 Pull Request：

• 库 ID 应使用小写字母并以连字符分隔（例如："adapter-transformers"）。在提交 PR 时，请确保保持字母顺序。
• 将 repoName 和 prettyLabel 设置为用户友好的大小写格式（例如：DeepForest）。
• 将 repoUrl 设置为指向库源代码的链接（通常是 GitHub 仓库）。
• （可选）将 docsUrl 设置为指向该库文档的链接。如果文档位于上述 GitHub 仓库中，则无需重复设置。
• 将 filter 设置为 false。
• （可选）通过设置 countDownload 来定义如何统计下载量。下载量可以按文件扩展名或文件名进行跟踪。请务必避免重复计数。例如，如果加载一个模型需要 3 个文件，则下载计数规则必须仅针对这 3 个文件中的 1 个进行计数。否则，下载量将被高估。注意：如果该库使用了其中一个默认配置文件（config.json、config.yaml、hyperparams.yaml、params.json 和 meta.yaml，参见此处），则无需手动定义下载计数规则。
• （可选）定义 snippets，以便让用户了解如何快速实例化模型。更多详情见下文。

在提交 PR 之前，请确保至少有一个模型在 https://huggingface.co/models?other=my-library-name 中被引用。如果没有，则必须使用 library_name: my-library-name 更新相关模型的模型卡元数据（参见 示例）。如果您不是 Hub 上这些模型的所有者，请提交 PR（参见 示例）。

下面是一个为 VFIMamba 添加集成的最小示例。

代码片段

我们建议添加一段代码片段，以说明如何在您的下游库中使用模型。

要添加代码片段，您应在 model-libraries-snippets.ts 文件中更新有关您的模型的说明。例如，Asteroid 集成包含一个简短的代码片段，演示如何加载和使用 Asteroid 模型：

const asteroid = (model: ModelData) =>
`from asteroid.models import BaseModel
  
model = BaseModel.from_pretrained("${model.id}")`;

这样做还会为您的模型添加一个标签，以便用户快速识别来自您库中的模型。

将您的代码片段添加到 model-libraries-snippets.ts 后，即可按照上述说明在 model-libraries.ts 中引用它。

记录你的库

最后，您可以将您的库添加到 Hub 的文档中。例如，可以参考将 SetFit 添加到文档中的 Setfit PR。