# 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 API'leri**
  - ö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](./api) belgelerinde yer alır.
- **Çözücüler**
  - 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](https://huggingface-openapi.hf.space/#tag/models/get/apiresolve-cachemodelsnamespacereporevpath).
  - 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.
- **Sayfalar**
  - huggingface.co üzerinde barındırdığımız tüm Web sayfaları.
  - Genellikle Web'de 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.

> [!TIP]
> 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" (burstiness) olanağı sağlar.

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](#rate-limit-tiers) 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

![dashboard for rate limits](/static-proxy?url=https%3A%2F%2Fcdn-uploads.huggingface.co%2Fproduction%2Fuploads%2F5dd96eb166059660ed1ee413%2F0pzQQyuVG3c9tWjCqrX9Y.png)

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)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/) (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 '25) 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 🤞

> [!NOTE]
> 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`](https://huggingface.co/docs/huggingface_hub/index) (**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.

Bu belirli 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.