# Hub 速率限制

为了保护平台的完整性并确保尽可能多的 AI 社区成员能够使用，我们对所有发往 Hugging Face Hub 的请求实施速率限制。

我们为不同类型的请求定义了不同的速率限制。我们区分了三个主要类别：

- **Hub API**
  - 例如模型或数据集搜索、仓库创建、用户管理等。属于此类别的所有端点均在[Hub API 端点](./api)中有文档说明。
- **解析器**
  - 它们都是路径中包含 `/resolve/` 段的 URL，用于从 Hub 提供用户生成的内容。具体来说，这些 URL 由开源库（transformers、datasets、vLLM、llama.cpp、……）或 AI 应用（LM Studio、Jan、ollama、……）构造，用于从 HF 下载模型/数据集文件。
  - 具体来说，这是我们在 OpenAPI 规范中记录的 [“Resolve a file”](https://huggingface-openapi.hf.space/#tag/models/get/apiresolve-cachemodelsnamespacereporevpath) 端点。
  - Resolve 请求在社区中被大量使用，由于我们优化了基础设施以最高效地处理这些请求，因此 Resolver 的速率限制是最高的。
- **页面**
  - 我们在 huggingface.co 上托管的所有网页。
  - 通常，网页浏览请求由人类发起，因此速率限制无需像上述程序化端点那样高。

> [!TIP]
> 所有值均基于 5 分钟窗口定义，这从应用程序或开发者的角度来看，允许一定程度的“突发”行为。

如果您、您的组织或您的应用需要更高的速率限制，我们建议您将账户升级为 PRO、Team 或 Enterprise。我们会优先处理来自 PRO、Team 和 Enterprise 客户的支持请求 – 有关内置限制，请参阅 [速率限制层级](#rate-limit-tiers)。

## 账单仪表板

在任何时候，你都可以在（你或你所在组织的）Billing 页面上查看你的速率限制状态：https://huggingface.co/settings/billing

![dashboard for rate limits](https://cdn-uploads.huggingface.co/production/uploads/5dd96eb166059660ed1ee413/0pzQQyuVG3c9tWjCqrX9Y.png)

在右侧，您会看到三个仪表盘，分别对应 Requests 的每个桶。

每个桶显示当前（最近 5 分钟）的请求数，以及基于您的用户账户或组织套餐所允许的请求数。

每当您在过去 5 分钟内超出限制（该视图会实时更新）时，进度条将变为红色。

注意：您可以使用上下文切换器轻松地在您的用户账户和组织之间切换。

## HTTP 标头

每当您或您的组织达到速率限制时，您将收到 **429** `Too Many Requests` HTTP 错误。

我们实现了名为“RateLimit HTTP header fields for HTTP”（也称为 `draft-ietf-httpapi-ratelimit-headers`）的 [IETF 草案（第 9 版）](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) 中描述的机制。

其目标是定义标准化的 HTTP 头，以便服务器能够公布配额/速率限制策略，并向客户端传达当前的使用情况/限制，从而帮助客户端避免被限流。

具体而言，我们实现了以下标头：

| 页眉                 | 目的 / 含义                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **`RateLimit`**        | 当前时间窗口内允许的总速率限制。“您被允许执行（此类型）的请求数量。”                      |
| **`RateLimit-Policy`** | 承载速率限制策略本身（例如“每 5 分钟 100 次请求”）。它提供信息性说明，展示客户端所适用的策略。 |

示例如下：

| 页眉                 | 示例                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| **`RateLimit`**        | `"api\|pages\|resolvers";r=[remaining];t=[seconds remaining until reset]`                             |
| **`RateLimit-Policy`** | `"fixed window";"api\|\pages\|resolvers";q=[total allowed for window];w=[window duration in seconds]` |

## 速率限制层级

以下是基于您的套餐的当前速率限制（2025 年 9 月）：

| 计划                                                                      | API      | 解析器 | 页面  |
| ------------------------------------------------------------------------- | -------- | --------- | ------ |
| 匿名用户（按 IP 地址）                                           | 500 \*   | 3,000 \*  | 100 \* |
| 免费用户                                                                 | 1,000 \* | 5,000 \*  | 200 \* |
| PRO 用户                                                                  | 2,500    | 12,000    | 400    |
| 团队组织                                                         | 3,000    | 20,000    | 400    |
| 企业组织                                                   | 6,000    | 50,000    | 600    |
| Enterprise Plus 组织                                              | 10,000   | 100,000   | 1,000  |
| 启用了“更高的 Hub 速率限制”的 Enterprise Plus 组织   | 100,000  | 500,000   | 10,000 |
| Academia Hub 组织                                                 | 3,000    | 20,000    | 400    |

\* 匿名和免费用户可能会根据平台健康状况随时发生变化 🤞

> [!NOTE]
> 所有配额均基于 5 分钟的固定时间窗口进行计算。

注意：对于组织，速率限制会单独应用于每个成员，而不是在成员之间共享。

## 如果我被限流了怎么办

首先，请确保始终传入 `HF_TOKEN`，并将其向下游传递给所有从 Hub 下载 _内容_ 的库或应用程序。

这是用户被限流的首要原因，而且非常容易解决。

即使已传入 `HF_TOKEN`，如果您仍然受到速率限制，您可以：

- 将您的请求分散到更长的时间段内
- 尽可能将 Hub API 调用替换为 Resolver 调用（Resolver 的速率限制更高，且优化程度更好）。
- 升级到 PRO、Team 或 Enterprise。

## 使用 `huggingface_hub` 实现智能速率限制处理

Hub Python 库 [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/index)（版本 **1.2.0+**）包含针对速率限制错误的智能重试处理。

当发生 429 错误时，SDK 会自动解析 `RateLimit` 标头，以提取速率限制重置前的确切秒数，然后精确等待该时长后再进行重试。此机制适用于文件下载（即 Resolvers）以及分页的 Hub API 调用（例如列出模型、数据集、空间等）。

**我们强烈建议对所有对 Hub 的程序化访问使用 `huggingface_hub`**，以受益于这种优化的重试行为，并避免自行实现速率限制处理。

## 细粒度用户操作速率限制

除了上述主要的速率限制类别外，我们还会对某些特定类型的用户操作实施限制，例如：

- 创建仓库
- 仓库提交
- 讨论和评论
- moderation actions
- 等等。

我们目前未记录这些特定操作的速率限制，因为它们往往会随时间更频繁地发生变化。如果您遇到配额错误，我们建议您将账户升级为 PRO、Team 或 Enterprise。请随时通过支持团队与我们联系。

