跳到主要内容

速率限制

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

我们针对不同类别的请求设定不同的速率限制，主要区分三个存储桶：

  • Hub API
    • 例如模型或数据集搜索、仓库创建、用户管理等。此存储桶内的全部端点记录在 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

dashboard for rate limits

右侧会看到三个仪表盘，分别对应三类请求。

每个桶都会显示当前（最近 5 分钟）请求次数，以及基于账户或组织计划允许的请求数量。

当过去 5 分钟内超出限制时（界面实时更新），柱状条会变成红色。

提示：你可以使用上下文切换器在个人账户与所属组织之间快速切换。

HTTP 头部​

当你或组织触发速率限制时，会收到 429 Too Many Requests HTTP 错误。

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

其目标是定义标准化 HTTP 头部，供服务器公布配额/速率限制策略，并向客户端告知当前使用情况，帮助客户端避免被限流。

我们具体实现以下头部：

Header目的/含义
RateLimit当前窗口内允许的总请求数。“在该窗口内你可以执行多少此类请求。”
RateLimit-Policy携带速率限制策略本身（例如 “100 requests per 5 minutes”）。这是信息性字段，表明客户端当前受何种策略约束。

示例如下：

Header示例
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 月）根据计划划分的速率限制：

计划APIResolversPages
匿名用户（按 IP 地址计算）500 *3,000 *100 *
免费用户1,000 *5,000 *200 *
PRO 用户2,50012,000400
Team 组织3,00020,000400
Enterprise 组织6,00050,000600
Enterprise Plus 组织6,00050,000600
Enterprise Plus 组织
定义组织 IP 范围后		100,000500,00010,000
Academia Hub 组织2,50012,000400

* 匿名与免费用户的配额会随平台运行状况调整 🤞

备注

所有配额均以 5 分钟固定窗口计算。

提示：对组织而言，速率限制对成员逐一生效，不会在成员间共享。

如果我被限流了怎么办​

首先确保始终传递 HF_TOKEN，并且该令牌会在所有下载 Hub 内容的库或应用之间透传。

这是用户被限速的首要原因，也是最容易修复的问题。

若即便传递了 HF_TOKEN 仍遭限流，可以：

  • 拉长请求间隔，平滑流量
  • 尽可能将 Hub API 调用替换为 Resolver 调用（Resolver 的速率限制更高且优化程度更好）
  • 升级到 PRO、Team 或 Enterprise

更细粒度的用户操作速率限制​

除上述主要类别外，我们还对某些具体用户操作设置限制，例如：

  • 仓库创建
  • 仓库提交
  • 讨论与评论
  • 内容审核操作
  • 等等

我们暂未公开这些具体操作的速率限制，因为它们可能会更频繁调整。如果遇到配额错误，建议升级到 PRO、Team 或 Enterprise。欢迎通过支持团队与我们联系。

最后于 更新