Hub Rate limits

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

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

• Hub APIs
  • 예를 들어 모델 또는 데이터셋 검색, 저장소 생성, 사용자 관리 등입니다. 이 범주에 속하는 모든 엔드포인트는 Hub API Endpoints에 문서화되어 있습니다.
• Resolvers
  • 모두 경로에 /resolve/ 세그먼트를 포함하여 Hub에서 사용자 생성 콘텐츠를 서빙하는 URL입니다. 구체적으로, 이러한 URL은 오픈 소스 라이브러리(transformers, datasets, vLLM, llama.cpp, …) 또는 AI 애플리케이션(LM Studio, Jan, ollama, …)이 HF에서 모델/데이터셋 파일을 다운로드하도록 구성하는 URL입니다.
  • 구체적으로, 이는 OpenAPI 스펙에 문서화된 “Resolve a file” 엔드포인트입니다.
  • Resolve 요청은 커뮤니티에서 널리 사용되며, 이를 최대한 효율적으로 처리하기 위해 인프라를 최적화하고 있으므로 Resolver의 속도 제한은 가장 높게 설정되어 있습니다.
• Pages
  • huggingface.co에서 호스팅하는 모든 웹 페이지.
  • 일반적으로 웹 브라우저 요청은 사람이 수행하므로, 위에서 언급한 프로그래매틱 엔드포인트만큼 높은 레이트 리밋이 필요하지 않습니다.

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

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

Billing dashboard

언제든 (본인 또는 조직의) Billing 페이지에서 https://huggingface.co/settings/billing rate limit 상태를 확인할 수 있습니다.

오른쪽에는 Requests의 각 버킷에 해당하는 게이지 3개가 표시됩니다.

각 버킷은 현재(최근 5분) 요청 수와 사용자 계정 또는 조직 플랜에 따라 허용되는 요청 수를 표시합니다.

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

Note: 컨텍스트 스위처를 사용하면 사용자 계정과 조직 사이를 쉽게 전환할 수 있습니다.

HTTP 헤더

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

“RateLimit HTTP header fields for HTTP”라는 제목의 IETF 초안(Version 9)(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

* 익명 및 무료 사용자는 플랫폼의 상태에 따라 시간이 지남에 따라 변경될 수 있습니다 🤞

모든 할당량은 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(버전 1.2.0+)에는 rate limit 오류를 위한 스마트 재시도 처리가 포함되어 있습니다.

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

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

세분화된 사용자 작업 Rate limits

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

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

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

Update on GitHub