# Hub のレート制限

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

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

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

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

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

## 請求ダッシュボード

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

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

右側には、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）](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  |
| Enterprise Plus組織「Higher Hub Rate Limits」を有効化   | 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 Library [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/index)（バージョン **1.2.0+**）には、レート制限エラーに対するスマートなリトライ処理が含まれています。

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

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

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

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

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

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