Hugging Face 的 LOGO

Hub Python 库文档

快速入门

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

快速入门

Hugging Face Hub 是共享机器学习模型、演示、数据集和指标的首选平台。`huggingface_hub` 库可帮助您在不离开开发环境的情况下与 Hub 交互。您可以轻松创建和管理仓库、下载和上传文件，以及从 Hub 获取有用的模型和数据集元数据。

安装

首先，安装 `huggingface_hub` 库

pip install --upgrade huggingface_hub

欲了解更多详情，请查看安装指南。

下载文件

Hub 上的仓库受 Git 版本控制，用户可以下载单个文件或整个仓库。您可以使用 hf_hub_download() 函数下载文件。此函数会将文件下载并缓存到本地磁盘。下次您需要该文件时，它将从缓存中加载，因此您无需重新下载。

您将需要仓库 ID 和要下载的文件名。例如，要下载 Pegasus 模型配置文件

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json")

要下载特定版本的文件，请使用 `revision` 参数指定分支名称、标签或提交哈希。如果您选择使用提交哈希，它必须是完整的哈希，而不是较短的 7 字符提交哈希

>>> from huggingface_hub import hf_hub_download
>>> hf_hub_download(
...     repo_id="google/pegasus-xsum",
...     filename="config.json",
...     revision="4d33b01d79672f27f001f6abade33f22d993b151"
... )

有关更多详细信息和选项，请参阅 hf_hub_download() 的 API 参考。

身份验证

在很多情况下，您必须通过 Hugging Face 帐户进行身份验证才能与 Hub 交互：下载私有仓库、上传文件、创建 PR 等。创建帐户（如果您还没有），然后登录以从您的设置页面获取您的用户访问令牌。用户访问令牌用于向 Hub 验证您的身份。

令牌可以具有 `read` 或 `write` 权限。如果您想创建或编辑仓库，请确保拥有 `write` 访问令牌。否则，最好生成 `read` 令牌以降低令牌意外泄露的风险。

登录命令

最简单的身份验证方法是将令牌保存在您的机器上。您可以通过终端使用 login() 命令来完成此操作

hf auth login

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

或者，您可以在笔记本或脚本中通过 login() 以编程方式登录

>>> from huggingface_hub import login
>>> login()

您一次只能登录一个帐户。登录新帐户将自动注销上一个帐户。要确定您当前活动的帐户，只需运行 `hf auth whoami` 命令。

登录后，对 Hub 的所有请求（即使是不一定需要身份验证的方法）默认都会使用您的访问令牌。如果您想禁用隐式使用令牌，应将 `HF_HUB_DISABLE_IMPLICIT_TOKEN=1` 设置为环境变量（参见参考）。

在本地管理多个令牌

您可以通过简单地使用每个令牌运行 login() 命令来在您的机器上保存多个令牌。如果您需要在这些令牌之间进行本地切换，可以使用 `auth switch` 命令

hf auth switch

此命令将提示您从保存的令牌列表中按名称选择一个令牌。选择后，所选令牌将成为*活动*令牌，并将用于所有与 Hub 的交互。

您可以使用 `hf auth list` 列出您机器上所有可用的访问令牌。

环境变量

环境变量 `HF_TOKEN` 也可以用于验证您的身份。这在 Space 中特别有用，您可以在其中将 `HF_TOKEN` 设置为Space 机密。

新功能： Google Colaboratory 允许您为笔记本定义私钥。定义一个 `HF_TOKEN` 密钥即可自动进行身份验证！

通过环境变量或机密进行身份验证优先于存储在您机器上的令牌。

方法参数

最后，也可以通过将令牌作为参数传递给任何接受 `token` 参数的方法来认证。

from huggingface_hub import whoami

user = whoami(token=...)

通常不建议这样做，除非在您不想永久存储令牌的环境中，或者如果您需要同时处理多个令牌。

传递令牌作为参数时请务必小心。始终最好从安全保管库加载令牌，而不是在您的代码库或笔记本中硬编码。如果您不小心共享了您的代码，硬编码的令牌会带来主要的泄露风险。

创建仓库

注册并登录后，使用 create_repo() 函数创建一个仓库

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model")

如果您希望您的仓库是私有的，那么

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.create_repo(repo_id="super-cool-model", private=True)

私人仓库除了您自己之外，其他人将无法看到。

要创建仓库或将内容推送到 Hub，您必须提供具有 `write` 权限的用户访问令牌。您可以在设置页面创建令牌时选择权限。

上传文件

使用 upload_file() 函数将文件添加到您新创建的仓库。您需要指定

  1. 要上传文件的路径。
  2. 文件在仓库中的路径。
  3. 要添加文件的仓库 ID。
>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/home/lysandre/dummy-test/README.md",
...     path_in_repo="README.md",
...     repo_id="lysandre/test-model",
... )

要一次上传多个文件，请查看 上传 指南，该指南将向您介绍几种上传文件的方法（带或不带 git）。

下一步

`huggingface_hub` 库为用户提供了一种使用 Python 与 Hub 交互的简单方法。要了解如何管理 Hub 上的文件和仓库，我们建议阅读我们的操作指南，以

< > 在 GitHub 上更新

←主页 安装→