Hub Hız sınırları

Platform bütünlüğümüzü korumak ve mümkün olan en geniş yapay zeka topluluğu üyesi kitlesine erişilebilirlik sağlamak için, Hugging Face Hub'a yapılan tüm isteklerde hız sınırlamaları uyguluyoruz.

Farklı istek sınıfları için farklı hız sınırları tanımlıyoruz. Üç ana kategori ayırıyoruz:

• Hub APIs
  • ör. model veya veri seti arama, depo oluşturma, kullanıcı yönetimi vb. Bu kapsamda yer alan tüm uç noktalar Hub API Endpoints belgelerinde yer alır.
• Resolvers
  • Hepsi, yollarında /resolve/ segmenti içeren ve Hub’dan kullanıcı tarafından oluşturulan içeriği sunan URL’lerdir. Somut olarak, bunlar HF’den model/veri seti dosyalarını indirmek için açık kaynaklı kütüphaneler (transformers, datasets, vLLM, llama.cpp, …) veya yapay zeka uygulamaları (LM Studio, Jan, ollama, …) tarafından oluşturulan URL’lerdir.
  • Özellikle bu, OpenAPI spesifikasyonumuzda belgelenen “Bir dosyayı çöz” uç noktasıdır.
  • Resolve istekleri topluluk tarafından yoğun bir şekilde kullanılmaktadır ve altyapımızı bunları en yüksek verimlilikle karşılayacak şekilde optimize ettiğimiz için Resolver'lar için hız sınırları en yüksektir.
• Pages
  • huggingface.co üzerinde barındırdığımız tüm Web sayfaları.
  • Genellikle Web gezinme istekleri insanlar tarafından yapılır, bu nedenle hız sınırlarının yukarıda bahsedilen programatik uç noktalar kadar yüksek olması gerekmez.

Tüm değerler 5 dakikalık pencereler üzerinde tanımlanır; bu da uygulama veya geliştirici açısından belirli bir düzeyde “ani yoğunluk”a (burstiness) izin verir.

Siz, organizasyonunuz veya uygulamanız daha yüksek hız sınırlarına ihtiyaç duyuyorsa, hesabınızı PRO, Team veya Enterprise olarak yükseltmenizi öneririz. PRO, Team ve Enterprise müşterilerinden gelen destek isteklerine öncelik veriyoruz – yerleşik sınırlar için Hız sınırı kademeleri bölümüne bakın.

Faturalama paneli

Herhangi bir anda, (kendi veya kuruluşunuzun) Faturalama sayfasında hız limit durumu kontrol edebilirsiniz: https://huggingface.co/settings/billing

Sağ tarafta, Requests'in her bir sepeti için olmak üzere üç gösterge göreceksiniz.

Her sepet, son 5 dakikadaki mevcut istek sayısını ve kullanıcı hesabınıza veya kuruluş planınıza dayalı olarak izin verilen istek sayısını gösterir.

Son 5 dakika içinde sınırı aştığınızda (görünüm gerçek zamanlı olarak güncellenir), çubuk kırmızıya döner.

Not: Kullanıcı hesabınız ve kuruluşlarınız arasında kolayca geçiş yapmak için bağlam değiştiriciyi kullanabilirsiniz.

HTTP Başlıkları

Siz veya organizasyonunuz bir hız sınırına takıldığında, 429 Too Many Requests HTTP hatasını alırsınız.

“RateLimit HTTP header fields for HTTP” başlıklı IETF taslağında (Sürüm 9) (aynı zamanda draft-ietf-httpapi-ratelimit-headers olarak da bilinir) açıklanan mekanizmayı uygularız.

Amaç, sunucuların kota / hız sınırı politikalarını duyurmak ve istemcilerin boğulmayı (throttling) önleyebilmeleri için mevcut kullanım / sınırları iletmek amacıyla kullanabilecekleri standartlaştırılmış HTTP başlıklarını tanımlamaktır.

Tam olarak, aşağıdaki başlıkları uyguluyoruz:

Başlık	Amaç / Anlam
RateLimit	Mevcut pencere için izin verilen toplam hız sınırı. “(Bu türden) kaç istek yapmanıza izin veriliyor.”
RateLimit-Policy	Kendisi hız sınırı politikasını taşır (ör. “5 dakikada 100 istek”). Bilgilendirici niteliktedir; istemcinin hangi politikaya tabi olduğunu gösterir.

Örnek bir küme aşağıdaki gibidir:

Başlık	Örnek
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]

Hız sınırı kademeleri

Planınıza göre geçerli olan mevcut hız sınırları (Eylül 2025) aşağıdaki gibidir:

Plan	API	Çözücüler	Sayfalar
Anonim kullanıcı (IP adresi başına)	500 *	3,000 *	100 *
Ücretsiz kullanıcı	1,000 *	5,000 *	200 *
PRO kullanıcısı	2,500	12,000	400
Ekip organizasyonu	3,000	20,000	400
Kurumsal organizasyon	6,000	50,000	600
Enterprise Plus kuruluşu	10,000	100,000	1,000
Enterprise Plus kuruluşu “Higher Hub Rate Limits” etkinleştirildi	100,000	500,000	10,000
Academia Hub kuruluşu	3,000	20,000	400

* Anonim ve Ücretsiz kullanıcılar, platform sağlığına bağlı olarak zamanla değişiklik gösterebilir 🤞

Tüm kota hesaplamaları 5 dakikalık sabit pencereler üzerinden yapılır.

Not: Kuruluşlar için hız sınırları, üyeler arasında paylaşılmaz; her üyeye ayrı ayrı uygulanır.

Hız sınırlamasına takılırsam ne olur

Öncelikle, her zaman bir HF_TOKEN geçirdiğinizden ve Hub'dan veri indiren tüm kütüphanelere veya uygulamalara aşağı akışta iletildiğinden emin olun.

Kullanıcıların hız sınırına takılmasının bir numaralı nedeni budur ve çok kolay bir düzeltmesi vardır.

HF_TOKEN değerini ilettiğiniz halde hâlâ hız sınırına takılıyorsanız, şunları yapabilirsiniz:

• isteklerinizi daha uzun zaman dilimlerine yayın
• Mümkün olduğunca Hub API çağrılarını Resolver çağrılarıyla değiştirin (Resolver hız sınırları çok daha yüksektir ve çok daha optimize edilmiştir).
• PRO, Team veya Enterprise'e yükseltin.

huggingface_hub ile akıllı hız sınırı yönetimi

Hub Python Kütüphanesi huggingface_hub (1.2.0+ sürümü), hız sınırı hataları için akıllı yeniden deneme işleme özelliği içerir.

429 hatası oluştuğunda SDK, RateLimit başlığını otomatik olarak ayrıştırarak hız sınırının sıfırlanmasına kalan tam saniye sayısını çıkarır ve ardından yeniden denemeden önce tam olarak bu süreyi bekler. Bu durum dosya indirmelerine (yani Resolver'lara) ve sayfalı Hub API çağrılarına (modelleri, veri setlerini, uzayları listeleme vb.) uygulanır.

Bu optimize edilmiş yeniden deneme davranışından yararlanmak ve özel hız sınırı işleme uygulamak zorunda kalmamak için, Hub'a tüm programatik erişimlerde huggingface_hub kullanmanızı şiddetle öneririz.

İnce tanecikli kullanıcı eylemi Hız sınırları

Bu ana hız sınırı sınıflarının yanı sıra, aşağıdakiler gibi belirli kullanıcı eylemleri üzerinde de sınırlar uygularız:

• repo oluşturma
• repo commit'leri
• tartışmalar ve yorumlar
• moderasyon eylemleri
• vb.

Belirtilen bu özel eylemlerin hız sınırlamalarını şu anda belgelemiyoruz, çünkü bu sınırlar zamanla daha sık değişme eğilimindedir. Kota hataları alırsanız, hesabınızı PRO, Team veya Enterprise seviyesine yükseltmenizi öneririz. Destek ekibi aracılığıyla bizimle iletişime geçmekten çekinmeyin.

Update on GitHub