Batas laju Hub

Untuk menjaga integritas platform kami dan memastikan ketersediaan bagi sebanyak mungkin anggota komunitas AI, kami menerapkan batas laju (rate limits) pada semua permintaan yang dibuat ke Hugging Face Hub.

Kami menetapkan batas laju yang berbeda untuk kelas permintaan yang berbeda. Kami membedakan tiga kategori utama:

• Hub APIs
  • misalnya pencarian model atau dataset, pembuatan repo, manajemen pengguna, dan sebagainya. Semua endpoint yang termasuk dalam kategori ini didokumentasikan di Hub API Endpoints.
• Resolvers
  • Semuanya adalah URL yang mengandung segmen /resolve/ di path-nya, yang menyajikan konten yang dibuat pengguna dari Hub. Secara konkret, URL tersebut dibangun oleh pustaka open source (transformers, datasets, vLLM, llama.cpp, …) atau aplikasi AI (LM Studio, Jan, ollama, …) untuk mengunduh file model/dataset dari HF.
  • Secara spesifik, ini adalah endpoint “Resolve a file” yang didokumentasikan dalam spesifikasi OpenAPI kami.
  • Resolve requests sangat banyak digunakan oleh komunitas, dan karena kami mengoptimalkan infrastruktur kami untuk melayaninya dengan efisiensi maksimal, batas laju untuk Resolvers adalah yang tertinggi.
• Pages
  • Semua halaman Web yang kami host di huggingface.co.
  • Biasanya, permintaan penelusuran web dilakukan oleh manusia, sehingga batas laju tidak perlu setinggi endpoint programatik yang disebutkan di atas.

Semua nilai didefinisikan dalam jendela 5 menit, yang memungkinkan tingkat "burstiness" tertentu dari sudut pandang aplikasi atau pengembang.

Jika Anda, organisasi Anda, atau aplikasi Anda memerlukan batas laju yang lebih tinggi, kami mendorong Anda untuk meningkatkan akun Anda ke PRO, Team, atau Enterprise. Kami memprioritaskan permintaan dukungan dari pelanggan PRO, Team, dan Enterprise – lihat batas bawaan di Tier batas laju.

Dasbor penagihan

Kapan pun, Anda dapat memeriksa status batas laju Anda di halaman Billing (Anda atau organisasi Anda): https://huggingface.co/settings/billing

Di sisi kanan, Anda akan melihat tiga gauge, masing-masing untuk setiap bucket dari Requests.

Setiap bucket menampilkan jumlah permintaan saat ini (5 menit terakhir) dan jumlah permintaan yang diizinkan berdasarkan paket akun pengguna atau organisasi Anda.

Setiap kali Anda melampaui batas dalam 5 menit terakhir (tampilan diperbarui secara real-time), bar akan berubah menjadi merah.

Catatan: Anda dapat menggunakan context switcher untuk beralih dengan mudah antara akun pengguna Anda dan organisasi Anda.

Header HTTP

Setiap kali Anda atau organisasi Anda mencapai batas laju, Anda akan menerima error HTTP 429 Too Many Requests.

Kami mengimplementasikan mekanisme yang dijelaskan dalam draf IETF (Versi 9) berjudul “RateLimit HTTP header fields for HTTP” (juga dikenal sebagai draft-ietf-httpapi-ratelimit-headers).

Tujuannya adalah untuk mendefinisikan header HTTP yang distandarkan yang dapat digunakan server untuk mengiklankan kebijakan kuota / pembatasan laju dan mengomunikasikan penggunaan / batas saat ini kepada klien agar mereka dapat menghindari pengebatasan.

Secara spesifik, kami mengimplementasikan header berikut:

Header	Tujuan / Makna
RateLimit	Batas laju total yang diizinkan untuk jendela saat ini. “Berapa banyak permintaan (dari jenis ini) yang boleh Anda lakukan.”
RateLimit-Policy	Menyimpan kebijakan batas laju itu sendiri (misalnya “100 permintaan per 5 menit”). Bersifat informatif; menunjukkan kebijakan yang berlaku untuk klien.

Beberapa contoh adalah sebagai berikut:

Header	Contoh
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]

Tingkat batas laju

Berikut adalah batas laju saat ini (pada September '25) berdasarkan paket Anda:

Rencana	API	Resolvers	Halaman
Pengguna anonim (per alamat IP)	500 *	3,000 *	100 *
Pengguna gratis	1,000 *	5,000 *	200 *
Pengguna PRO	2,500	12,000	400
Organisasi tim	3,000	20,000	400
Organisasi Enterprise	6,000	50,000	600
Organisasi Enterprise Plus	10,000	100,000	1,000
Organisasi Enterprise Plus Dengan “Higher Hub Rate Limits” diaktifkan	100,000	500,000	10,000
Organisasi Academia Hub	3,000	20,000	400

* Pengguna Anonymous dan Free dapat berubah seiring waktu tergantung pada kesehatan platform 🤞

Semua kuota dihitung dalam jendela tetap 5 menit.

Catatan: Untuk organisasi, batas laju diterapkan secara individual untuk setiap anggota, bukan dibagikan di antara anggota.

Bagaimana jika saya terkena pembatasan laju

Pertama, pastikan Anda selalu meneruskan HF_TOKEN, dan token tersebut diteruskan ke semua pustaka atau aplikasi yang mengunduh berbagai hal dari Hub.

Ini adalah alasan utama pengguna terkena pembatasan laju dan sangat mudah diperbaiki.

Meskipun Anda telah meneruskan HF_TOKEN, jika Anda masih dibatasi laju (rate limited), Anda dapat:

• sebar permintaan Anda di sepanjang periode waktu yang lebih lama
• ganti panggilan API Hub dengan panggilan Resolver, setiap kali memungkinkan (batas laju Resolver jauh lebih tinggi dan jauh lebih dioptimalkan).
• upgrade ke PRO, Team, atau Enterprise.

Penanganan batas laju cerdas dengan huggingface_hub

Library Python Hub huggingface_hub (versi 1.2.0+) mencakup penanganan retry cerdas untuk error batas laju.

Ketika error 429 terjadi, SDK secara otomatis memarsing header RateLimit untuk mengekstrak jumlah detik yang tepat hingga batas laju direset, lalu menunggu durasi tersebut secara presisi sebelum mencoba lagi. Hal ini berlaku untuk unduhan file (yaitu Resolvers) dan panggilan API Hub yang dipaginasi (daftar model, dataset, spaces, dll.).

Kami sangat merekomendasikan penggunaan huggingface_hub untuk semua akses programatik ke Hub agar Anda dapat memanfaatkan perilaku retry yang dioptimalkan ini dan menghindari implementasi penanganan batas laju (rate limit) yang kustom.

Batas laju tindakan pengguna yang terperinci

Selain kelas utama batas laju tersebut, kami juga menerapkan batas pada jenis-jenis tindakan pengguna tertentu, seperti:

• pembuatan repo
• commit repo
• diskusi dan komentar
• tindakan moderasi
• dst.

Saat ini, kami tidak mendokumentasikan batas laju (rate limits) untuk tindakan spesifik tersebut, mengingat batas tersebut cenderung berubah lebih sering seiring waktu. Jika Anda mengalami kesalahan kuota, kami menyarankan Anda untuk meningkatkan akun Anda ke PRO, Team, atau Enterprise. Silakan hubungi kami melalui tim dukungan.

Update on GitHub