# Hub Rate limits

플랫폼의 무결성을 보호하고 가능한 한 많은 AI 커뮤니티 구성원에게 서비스를 제공하기 위해, Hugging Face Hub로 전송되는 모든 요청에 대해 속도 제한을 적용합니다.

요청의 서로 다른 클래스에 대해 서로 다른 속도 제한을 정의합니다. 세 가지 주요 버킷을 구분합니다:

- **Hub API**
  - 예를 들어 모델 또는 데이터셋 검색, 저장소 생성, 사용자 관리 등입니다. 이 범주에 속하는 모든 엔드포인트는 [Hub API Endpoints](./api)에 문서화되어 있습니다.
- **리졸버**
  - 모두 경로에 `/resolve/` 세그먼트를 포함하여 Hub에서 사용자 생성 콘텐츠를 서빙하는 URL입니다. 구체적으로, 이는 오픈 소스 라이브러리(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에서 호스팅하는 모든 웹 페이지.
  - 일반적으로 웹 브라우저 요청은 사람이 수행하므로, 위에서 언급한 프로그래매틱 엔드포인트만큼 높은 레이트 리밋이 필요하지 않습니다.

> [!TIP]
> 모든 값은 5분 윈도우에 걸쳐 정의되며, 이는 애플리케이션 또는 개발자의 관점에서 일정 수준의 "버스티니스(burstiness)"를 허용합니다.

사용자, 조직 또는 애플리케이션에 더 높은 rate limit이 필요한 경우, PRO, Team 또는 Enterprise 계정으로 업그레이드하는 것을 권장합니다. PRO, Team 및 Enterprise 고객의 지원 요청을 우선 처리하며, [Rate limit Tiers](#rate-limit-tiers)에서 내장된 한도를 확인하세요.

## Billing dashboard

언제든 (본인 또는 조직의) Billing 페이지에서 rate limit 상태를 확인할 수 있습니다: 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 헤더

사용자 또는 조직이 rate limit에 도달하면 **429** `Too Many Requests` HTTP 오류가 반환됩니다.

“RateLimit HTTP header fields for HTTP”라는 제목의 [IETF 초안(Version 9)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/)(`draft-ietf-httpapi-ratelimit-headers`으로도 알려짐)에 설명된 메커니즘을 구현했습니다.

목표는 서버가 쿼터/레이트 리밋 정책을 광고하고 현재 사용량/한도를 클라이언트에 전달하여 클라이언트가 스로틀링을 피할 수 있도록 하는 표준화된 HTTP 헤더를 정의하는 것입니다.

정확히 말해, 우리는 다음 헤더를 구현합니다:

| 헤더                 | 목적 / 의미                                                                                                                       |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **`RateLimit`**        | 현재 윈도우에 대해 허용되는 총 레이트 리밋. “(이 유형의) 요청을 수행할 수 있는 횟수.”                      |
| **`RateLimit-Policy`** | rate limit 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 사용자는 플랫폼 상태에 따라 시간이 지남에 따라 변경될 수 있습니다 🤞

> [!NOTE]
> 모든 할당량은 5분 고정 윈도우 기준으로 계산됩니다.

Note: 조직의 경우, 속도 제한은 멤버 간에 공유되지 않고 각 멤버별로 개별적으로 적용됩니다.

## What if I get rate-limited

먼저, `HF_TOKEN`를 항상 전달하고, Hub에서 _콘텐츠_를 다운로드하는 모든 하위 라이브러리나 애플리케이션으로 전달되도록 확인하세요.

이것은 사용자가 rate limit에 걸리는 가장 흔한 이유이며, 매우 쉽게 해결할 수 있습니다.

`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+**)에는 rate limit 오류를 위한 스마트 재시도 처리가 포함되어 있습니다.

429 오류가 발생하면 SDK는 `RateLimit` 헤더를 자동으로 파싱하여 속도 제한이 재설정되기까지의 정확한 초를 추출한 후, 해당 시간만큼 정확히 대기한 뒤 재시도합니다. 이는 파일 다운로드(즉, Resolvers) 및 페이지네이션된 Hub API 호출(모델, 데이터셋, 스페이스 목록 등)에 적용됩니다.

이 최적화된 재시도 동작의 이점을 누리고 사용자 정의 속도 제한 처리를 구현하지 않도록, Hub에 대한 모든 프로그래매틱 액세스에는 **`huggingface_hub` 사용을 강력히 권장합니다**.

## 세분화된 사용자 작업 Rate limits

이러한 주요 레이트 리밋 클래스 외에도, 다음과 같은 특정 유형의 사용자 작업에 대해 제한을 적용합니다:

- 리포지토리 생성
- repo 커밋
- 토론 및 댓글
- 모더레이션 조치
- 등

해당 특정 작업의 속도 제한은 시간이 지남에 따라 자주 변경되는 경향이 있어 현재 문서화되어 있지 않습니다. 할당량(quota) 오류가 발생하면 PRO, Team 또는 Enterprise 계정으로 업그레이드하시기를 권장합니다. 지원 팀을 통해 언제든지 문의해 주세요.

