将您的库与 Hub 集成

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

将 Hub 与您的库集成可带来许多好处，包括

• 为您和您的用户提供免费的模型托管。
• 内置文件版本控制（即使对于大型文件），由 Git-LFS 提供支持。
• 社区功能（讨论、拉取请求、点赞）。
• 使用您库运行的所有模型的使用情况指标。

本教程将帮助您将 Hub 集成到您的库中，以便您的用户能够从 Hub 提供的所有功能中受益。

在开始之前，我们建议您创建一个 Hugging Face 帐户，您可以在其中管理您的存储库和文件。

如果您需要帮助进行集成，请随时打开一个 问题，我们将很乐意为您提供帮助。

实施

实现库与 Hub 的集成通常意味着提供内置方法来从 Hub 加载模型，并允许用户将新模型推送到 Hub。 本节将介绍如何使用 huggingface_hub 库执行此操作的基础知识。 有关更深入的指导，请查看 本指南。

安装

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

pip install huggingface_hub

有关 huggingface_hub 安装的更多详细信息，请查看 本指南。

npm add @huggingface/hub

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

huggingface-cli 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 和 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 PR，它将 SetFit 添加到文档中。