快速入门

The 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 交互的脚本或库在发送请求时都将使用此令牌。

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

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

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

本地管理多个令牌

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

huggingface-cli auth switch

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

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

环境变量

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

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

方法参数

最后，还可以通过将令牌传递给任何接受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)

私有仓库将对除您自己以外的任何人不可见。

上传文件

使用 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 上管理文件和仓库的更多信息，我们建议您阅读我们的操作指南，以

• 管理您的仓库.
• 从 Hub下载文件。
• 将文件上传到 Hub。
• 在 Hub 中搜索 您想要的模型或数据集。
• 访问推理 API 以进行快速推理。