Hub のレート制限

プラットフォームの健全性を保護し、できるだけ多くのAIコミュニティのメンバーに利用可能にするため、Hugging Face Hubへのすべてのリクエストに対してレート制限を適用しています。

リクエストの種類ごとに異なるレート制限を定義しています。主に3つのカテゴリを区別します。

• Hub APIs
  • モデルやデータセットの検索、リポジトリの作成、ユーザー管理などです。このカテゴリに属するすべてのエンドポイントは、Hub API Endpointsにドキュメント化されています。
• Resolvers
  • これらはすべて、パスに/resolve/セグメントを含むURLであり、Hubからユーザー生成コンテンツを提供します。具体的には、オープンソースライブラリ（transformers、datasets、vLLM、llama.cpp、…）やAIアプリケーション（LM Studio、Jan、ollama、…）が、HFからモデル/データセットファイルをダウンロードするために構築するURLです。
  • 具体的には、これはOpenAPI仕様で文書化されている「Resolve a file」エンドポイントです。
  • Resolve リクエストはコミュニティで広く利用されており、当社はこれらを最大限の効率で提供するためにインフラストラクチャを最適化しているため、Resolver のレート制限は最も緩やかです。
• Pages
  • huggingface.co でホストしているすべての Web ページ。
  • 通常、Webブラウジングのリクエストは人間によって行われるため、上記のプログラムによるエンドポイントほど高いレート制限は必要ありません。

すべての値は5分間のウィンドウで定義されており、アプリケーションや開発者の視点から見て、ある程度の「バースト性」を許容します。

あなた、あなたの組織、またはあなたのアプリケーションがより高いレート制限を必要とする場合、アカウントをPRO、Team、またはEnterpriseにアップグレードすることをお勧めします。PRO、Team、Enterpriseのお客様からのサポートリクエストを優先的に処理します。組み込みの制限については、Rate limit Tiersを参照してください。

請求ダッシュボード

いつでも、あなた（またはあなたの組織）の Billing ページでレート制限の状況を確認できます: https://huggingface.co/settings/billing

右側には、Requests の各バケットに対応する3つのゲージが表示されます。

各バケットには、現在のリクエスト数（直近5分間）と、ユーザーアカウントまたは組織のプランに基づいて許可されるリクエスト数が表示されます。

過去5分間の制限を超えた場合（ビューはリアルタイムで更新されます）、バーは赤色に変わります。

Note: コンテキストスイッチャーを使用すると、ユーザーアカウントと組織の間を簡単に切り替えることができます。

HTTP ヘッダー

あなたまたはあなたの組織がレート制限に達すると、429 Too Many Requests HTTPエラーが返されます。

「RateLimit HTTP header fields for HTTP」（draft-ietf-httpapi-ratelimit-headersとしても知られています）というタイトルのIETFドラフト（Version 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組織 「Higher Hub Rate Limits」が有効化されている場合	100,000	500,000	10,000
Academia Hub組織	3,000	20,000	400

* AnonymousおよびFreeユーザーは、プラットフォームの健全性に応じて、時間とともに変更される場合があります 🤞

すべてのクォータは、5分間の固定ウィンドウで計算されます。

注: 組織の場合、レート制限はメンバー間で共有されるのではなく、各メンバーに個別に適用されます。

レート制限に引っかかった場合はどうすればよいですか

まず、HF_TOKENを常に渡すようにしてください。また、Hubからデータをダウンロードするすべてのライブラリやアプリケーションに、下流で渡されるようにしてください。

ユーザーがレート制限に引っかかる最も一般的な理由であり、非常に簡単に修正できます。

HF_TOKEN を渡してもレート制限が解除されない場合は、以下の方法があります:

• リクエストをより長い期間に分散してください
• 可能な限り、Hub APIの呼び出しをResolverの呼び出しに置き換えてください（Resolverのレート制限ははるかに高く、はるかに最適化されています）。
• PRO、Team、またはEnterpriseにアップグレードしてください。

huggingface_hubによるスマートなレート制限の処理

Hub Python Library huggingface_hub（バージョン 1.2.0+）には、レート制限エラーに対するスマートなリトライ処理が含まれています。

429エラーが発生すると、SDKはRateLimitヘッダーを自動的に解析してレートリミットがリセットされるまでの正確な秒数を抽出し、その時間だけ待ってからリトライします。これはファイルのダウンロード（つまりResolver）およびページネーション付きのHub API呼び出し（モデル、データセット、スペースのリスト表示など）に適用されます。

この最適化されたリトライ動作の恩恵を受け、カスタムのレート制限処理を実装することを避けるため、Hubへのすべてのプログラムによるアクセスにはhuggingface_hubの使用を強く推奨します。

ユーザーアクションごとのレート制限

これらの主要なレートリミットの種類に加えて、特定のユーザーアクションに対して制限を適用しています。例えば、以下のようなものです：

• リポジトリの作成
• リポジトリのコミット
• ディスカッションとコメント
• モデレーションアクション
• など

これらの特定のアクションのレート制限については、頻繁に変更される傾向があるため、現在ドキュメント化していません。クォータエラーが発生した場合は、アカウントを PRO、Team、または Enterprise にアップグレードすることをお勧めします。 サポートチームを通じてお気軽にお問い合わせください。

Update on GitHub