快速入门

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 的身份。

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

登录命令

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

huggingface-cli login

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

或者，您可以使用 notebook 或脚本中的 login() 以编程方式登录

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

您一次只能登录一个账户。登录新账户将自动注销您之前的账户。要确定您当前活动的账户，只需运行 huggingface-cli whoami 命令。

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

本地管理多个令牌

您可以通过使用每个令牌登录 login() 命令，在您的机器上保存多个令牌。如果您需要在本地切换这些令牌，您可以使用 auth switch 命令

huggingface-cli auth switch

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

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

环境变量

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

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

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

方法参数

最后，也可以通过将您的令牌传递给任何接受 token 作为参数的方法来进行身份验证。

from huggingface_hub import whoami

user = whoami(token=...)

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

将令牌作为参数传递时请务必小心。最佳实践始终是从安全库加载令牌，而不是将其硬编码在您的代码库或 notebook 中。如果您不小心共享了您的代码，硬编码的令牌会带来重大的泄露风险。

创建仓库

注册并登录后，使用 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，您必须提供具有写入权限的用户访问令牌。您可以在您的设置页面创建令牌时选择权限。

上传文件

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

要上传的文件的路径。
仓库中文件的路径。
您想要添加文件的仓库 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 上管理您的文件和仓库的更多信息，我们建议您阅读我们的操作指南，了解如何

管理您的仓库.
从 Hub 下载文件。
上传文件到 Hub。
在 Hub 上搜索您所需的模型或数据集。
访问 Inference API 以获得快速推理。

< > 在 GitHub 上更新

Hub Python 库