# 快速入门

[Hugging Face Hub](https://huggingface.co/) 是分享机器学习模型、演示、数据集和指标的必备平台。`huggingface_hub` 库可帮助你在不离开开发环境的情况下与 Hub 进行交互。你可以轻松创建和管理仓库，下载和上传文件，并从 Hub 获取有用的模型和数据集元数据。

## 安装

要开始使用，请安装 `huggingface_hub` 库：

```bash
pip install --upgrade huggingface_hub
```

有关更多详细信息，请参阅[安装](installation)指南。

> [!TIP]
> `huggingface_hub` 还附带了一个 [`hf` CLI](./guides/cli)，允许你直接在终端中与 Hub 进行交互。如果你正在使用 AI 智能体（Claude Code、Codex、Cursor 等），请安装 Skill，以便你的智能体使用该 CLI：
> ```bash
> # works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills`
> hf skills add
> ```
> 有关更多详细信息，请参阅 [面向 AI 智能体的 Hugging Face CLI](https://huggingface.co/docs/hub/agents-cli) 指南。

## 下载文件

Hub 上的仓库采用 git 版本控制，用户可以下载单个文件或整个仓库。您可以使用 [hf_hub_download()](/docs/huggingface_hub/v2.4.0/zh/package_reference/file_download#huggingface_hub.hf_hub_download) 函数来下载文件。该函数会将文件下载并缓存到本地磁盘。下次您需要该文件时，它会直接从缓存中加载，因此无需重新下载。

您需要提供仓库 id 以及要下载的文件名。例如，要下载 [Pegasus](https://huggingface.co/google/pegasus-xsum) 模型的配置文件：

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

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

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

有关更多详细信息和选项，请参阅 [hf_hub_download()](/docs/huggingface_hub/v2.4.0/zh/package_reference/file_download#huggingface_hub.hf_hub_download) 的 API 参考。

 

## 身份验证

在许多情况下，你必须使用 Hugging Face 账户进行身份验证才能与 Hub 交互：下载私有仓库、上传文件、创建 PR 等。如果你还没有账户，请[创建一个账户](https://huggingface.co/join)。

### 登录命令

最简单的身份验证方式是使用 [login()](/docs/huggingface_hub/v2.4.0/zh/package_reference/authentication#huggingface_hub.login) 命令：

```bash
hf auth login
```

如果您已登录，该命令将立即返回。若要强制重新登录，请使用 `hf auth login --force`。如果您尚未登录，系统会提示您通过浏览器登录：打开打印出的 URL，输入短代码，批准请求，随后访问令牌将被获取并保存在您的 `HF_HOME` 目录中（默认为 `~/.cache/huggingface/token`）。令牌会在一段时间后过期，但只要您持续使用它，就会自动刷新。任何与 Hub 交互的脚本或库在发送请求时都会使用此令牌。或者，您也可以粘贴从您的 [Settings page](https://huggingface.co/settings/tokens) 生成的 [User Access Token](https://huggingface.co/docs/hub/security-tokens)。

> [!TIP]
> 用户访问令牌可以具有 `read` 或 `write` 权限。如果您需要创建或编辑仓库，请确保拥有 `write` 访问令牌。否则，建议生成 `read` 令牌，以降低令牌意外泄露带来的风险。

或者，您可以在笔记本或脚本中通过编程方式使用 [login()](/docs/huggingface_hub/v2.4.0/zh/package_reference/authentication#huggingface_hub.login) 进行登录：

```py
>>> from huggingface_hub import login
>>> login()
```

同一时间只能登录一个账户。登录新账户时，系统会自动登出之前的账户。要查看当前处于活动状态的账户，只需运行 `hf auth whoami` 命令即可。

> [!WARNING]
> 登录成功后，所有发往 Hub 的请求——即使某些方法不一定需要身份验证——默认都会使用您的访问令牌。如果您希望禁用令牌的隐式使用，请将 `HF_HUB_DISABLE_IMPLICIT_TOKEN=1` 设置为环境变量（参见 [参考文档](../package_reference/environment_variables#hfhubdisableimplicittoken)）。

### 在本地管理多个令牌

您可以使用 [login()](/docs/huggingface_hub/v2.4.0/zh/package_reference/authentication#huggingface_hub.login) 命令分别登录每个令牌，从而在本地机器上保存多个令牌。如果需要在本地切换这些令牌，可以使用 `auth switch` 命令：

```bash
hf auth switch
```

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

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

### 环境变量

环境变量 `HF_TOKEN` 也可用于身份验证。这在 Space 中尤为有用，因为您可以将 `HF_TOKEN` 设置为 [Space 密钥](https://huggingface.co/docs/hub/spaces-overview#managing-secrets)。

> [!TIP]
> **新功能：**Google Colaboratory 允许您为笔记本定义 [私钥](https://twitter.com/GoogleColab/status/1719798406195867814)。定义 `HF_TOKEN` 密钥即可自动完成身份验证！

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

### 方法参数

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

```
from huggingface_hub import whoami

user = whoami(token=...)
```

通常不建议这样做，除非您不希望永久存储令牌，或者需要同时处理多个令牌。

> [!WARNING]
> 在将令牌作为参数传递时请务必小心。最佳实践始终是从安全保险库中加载令牌，而不是将其硬编码在代码库或笔记本中。如果不小心分享了代码，硬编码的令牌会带来严重的泄露风险。

## 创建仓库

注册并登录后，使用 [create_repo()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.create_repo) 函数创建一个仓库：

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

如果您希望将您的仓库设置为私有，请执行以下操作：

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

私有仓库仅对您自己可见。

> [!TIP]
> 要创建仓库或向 Hub 推送内容，您必须提供一个具有 `write` 权限的用户访问令牌。您可以在 [设置页面](https://huggingface.co/settings/tokens) 中创建令牌时选择相应的权限。

## 上传文件

使用 [upload_file()](/docs/huggingface_hub/v2.4.0/zh/package_reference/hf_api#huggingface_hub.HfApi.upload_file) 函数将文件添加到您新建的仓库中。您需要指定：

1. 要上传的文件的路径。
2. 该文件在仓库中的路径。
3. 要添加文件的仓库 ID。

```py
>>> 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",
... )
```

若要一次上传多个文件，请参阅[Upload](./guides/upload)指南，其中将介绍多种文件上传方法（无论是否使用 git）。

## 后续步骤

`huggingface_hub` 库提供了一种便捷的方式，让用户通过 Python 与 Hub 进行交互。如需了解如何在 Hub 上管理您的文件和仓库，我们建议阅读我们的[操作指南](./guides/overview)：

- [管理您的仓库](./guides/repository)。
- 从 Hub 下载 [Download](./guides/download) 文件。
- 将文件[上传](./guides/upload)到 Hub。
- 在 [Hub](./guides/search) 中搜索您所需的模型或数据集。
- 针对托管在 Hugging Face Hub 上的模型，跨多个服务[运行推理](./guides/inference)。