Hub 文档
将你的库与 Hub 集成
并获得增强的文档体验
开始使用
将你的库与 Hub 集成
Hugging Face Hub 旨在促进机器学习模型、检查点和工件的共享。这项工作包括将 Hub 集成到社区中许多优秀的第三方库中。一些已经集成的库包括 spaCy、Sentence Transformers、OpenCLIP 和 timm 等等。集成意味着用户可以直接从你的库下载和上传文件到 Hub。我们希望你能够集成你的库,并加入我们,一起为所有人普及人工智能。
将 Hub 与你的库集成提供了许多好处,包括
- 为你和你的用户提供免费的模型托管。
- 内置文件版本控制 - 甚至对于大型文件 - 由 Git-LFS 实现。
- 社区功能(讨论、pull requests、点赞)。
- 使用你的库运行的所有模型的使用指标。
本教程将帮助你将 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()
命令来执行此操作
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 here
- 库 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 添加到了文档中。
< > 在 GitHub 上更新