Hub 레이트 리밋

Hub 레이트 리밋 (Hub Rate limits)

플랫폼의 무결성을 보호하고 최대한 많은 AI 커뮤니티 멤버에게 가용성을 보장하기 위해 Hugging Face Hub에 대한 모든 요청에 레이트 리밋을 적용합니다. 요청 등급에 따라 서로 다른 레이트 리밋을 정의하며, 크게 세 가지 버킷으로 구분합니다: Hub API, Resolvers, Pages.

출처: 문서

본문

플랫폼의 무결성을 보호하고 최대한 많은 AI 커뮤니티 멤버에게 가용성을 보장하기 위해 우리는 Hugging Face Hub에 대한 모든 요청에 레이트 리밋을 적용합니다.

요청 등급에 따라 서로 다른 레이트 리밋을 정의합니다. 세 가지 주요 버킷을 구분해요:

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 요청은 커뮤니티에서 많이 사용되며, 우리는 이를 최대 효율로 제공하도록 인프라를 최적화하므로 Resolvers의 레이트 리밋이 가장 높습니다.
Pages
- huggingface.co에서 호스팅하는 모든 웹 페이지.
- 보통 웹 브라우징 요청은 사람이 하므로 레이트 리밋이 위의 프로그램적 엔드포인트만큼 높을 필요는 없어요.

[!TIP] 모든 값은 5분 창으로 정의되며, 애플리케이션·개발자 관점에서 어느 정도의 "버스트성"을 허용합니다.

당신, 조직, 또는 애플리케이션에 더 높은 레이트 리밋이 필요하면 PRO, Team, Enterprise 계정으로 업그레이드하는 것을 권장합니다. 우리는 PRO, Team, Enterprise 고객의 지원 요청을 우선 처리합니다 — 내장 리밋은 Rate limit Tiers를 참고하세요.

청구 대시보드 (Billing dashboard)

언제든지 (당신 또는 조직의) Billing 페이지에서 레이트 리밋 상태를 확인할 수 있어요: https://huggingface.co/settings/billing

dashboard for rate limits

오른쪽에는 Requests의 각 버킷에 대한 게이지 3개가 보입니다.

각 버킷은 현재(지난 5분) 요청 수와 사용자 계정·조직 플랜에 기반한 허용 요청 수를 표시합니다.

지난 5분 동안 리밋을 초과할 때마다(뷰는 실시간 업데이트) 막대가 빨간색으로 변합니다.

참고: 컨텍스트 스위처로 사용자 계정과 조직 사이를 쉽게 전환할 수 있어요.

HTTP 헤더 (HTTP Headers)

당신이나 조직이 레이트 리밋에 도달할 때마다 429 Too Many Requests HTTP 오류를 받게 됩니다.

우리는 IETF draft (Version 9)에 나오는 "RateLimit HTTP header fields for HTTP"(일명 draft-ietf-httpapi-ratelimit-headers)의 메커니즘을 구현합니다.

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

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

Header	Purpose / Meaning
`RateLimit`	현재 창의 총 허용 레이트 리밋. "이 유형의 요청을 (몇 개) 수행할 수 있는지."
`RateLimit-Policy`	레이트 리밋 정책 자체를 담음(예: "5분당 100개 요청"). 정책이 무엇인지 보여주는 정보성 헤더.

예시:

Header	Example
`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]`

레이트 리밋 티어 (Rate limit Tiers)

플랜에 따른 현재 레이트 리밋('25년 9월 기준)은 다음과 같습니다:

Plan	API	Resolvers	Pages
Anonymous user (per IP address)	500 *	3,000 *	100 *
Free user	1,000 *	5,000 *	200 *
PRO user	2,500	12,000	400
Team organization	3,000	20,000	400
Enterprise organization	6,000	50,000	600
Enterprise Plus organization	10,000	100,000	1,000
Enterprise Plus organization ("Higher Hub Rate Limits" 활성화)	100,000	500,000	10,000
Academia Hub organization	3,000	20,000	400

* Anonymous와 Free 사용자는 플랫폼 상태에 따라 시간이 지나며 변경될 수 있습니다 🤞

[!NOTE] 모든 쿼터는 5분 고정 창으로 계산됩니다.

참고: 조직의 경우 레이트 리밋은 멤버 간 공유가 아니라 각 멤버에게 개별적으로 적용됩니다.

레이트 리밋에 걸리면 (What if I get rate-limited)

먼저 항상 HF_TOKEN을 전달하고, 그것이 Hub에서 stuff 를 다운로드하는 모든 라이브러리·애플리케이션에 전달되도록 하세요.

이것이 사용자가 레이트 리밋에 걸리는 첫 번째 이유이며 아주 쉬운 수정입니다.

HF_TOKEN을 전달해도 여전히 레이트 리밋에 걸린다면 다음을 할 수 있어요:

요청을 더 긴 시간에 걸쳐 분산
가능하면 Hub API 호출을 Resolver 호출로 대체(Resolver 레이트 리밋이 훨씬 높고 더 최적화됨)
PRO, Team, Enterprise로 업그레이드

`huggingface_hub`를 통한 스마트 레이트 리밋 처리 (Smart rate limit handling with `huggingface_hub`)

Hub Python 라이브러리 huggingface_hub(버전 1.2.0+)에는 레이트 리밋 오류에 대한 스마트 재시도 처리 기능이 포함되어 있습니다.

429 오류가 발생하면 SDK가 자동으로 RateLimit 헤더를 파싱해 레이트 리밋이 초기화될 때까지의 정확한 초 수를 추출한 다음, 정확히 그 시간을 기다렸다가 재시도합니다. 이는 파일 다운로드(즉 Resolvers)와 페이지네이션된 Hub API 호출(모델·데이터셋·spaces 목록 등)에 적용됩니다.

Hub에 대한 모든 프로그래밍 접근에 huggingface_hub을 강력히 권장합니다. 이 최적화된 재시도 동작의 이점을 얻고 커스텀 레이트 리밋 처리를 피할 수 있기 때문입니다.

세분화된 사용자 액션 레이트 리밋 (Granular user action Rate limits)

이 주요 레이트 리밋 등급 외에도 특정 종류의 사용자 액션에 리밋을 적용합니다:

리포지토리 생성
리포지토리 커밋
discussions과 댓글
중재 액션
등

이 특정 액션의 레이트 리밋은 시간이 지나며 더 자주 변하는 경향이 있어 현재 문서화하지 않습니다. 쿼터 오류가 발생하면 PRO, Team, Enterprise 계정으로 업그레이드하는 것을 권장합니다. 지원팀을 통해 저희에게 연락해도 좋아요.

더 알아보기 (Learn more)

레이트 리밋은 RateLimit/RateLimit-Policy 헤더로 실시간 잔여량을 확인할 수 있고, Billing 페이지에서도 게이지를 볼 수 있어요. 항상 HF_TOKEN을 전달하고, 가능하면 Resolver 호출을 쓰며, huggingface_hub(1.2.0+)의 스마트 재시도를 활용하면 429를 피할 수 있습니다. 더 높은 리밋이 필요하면 PRO/Team/Enterprise 업그레이드를 고려하세요.

Hub 레이트 리밋