Hub 速率限制

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

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

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

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

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

账单仪表板

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

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

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

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

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

HTTP 标头

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

我们实现了名为“RateLimit HTTP header fields for HTTP”（也称为 draft-ietf-httpapi-ratelimit-headers）的 IETF 草案（第 9 版） 中描述的机制。

其目标是定义标准化的 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
Enterprise Plus 组织 已启用“更高的 Hub 速率限制”	100,000	500,000	10,000
Academia Hub 组织	3,000	20,000	400

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

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

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

如果我被限流了怎么办

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

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

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

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

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

Hub Python 库 huggingface_hub（版本 1.2.0+）包含针对速率限制错误的智能重试处理。

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

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

细粒度用户操作速率限制

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

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

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

Update on GitHub