Kontrol

Policy Engine

Policy Engine, her isteği model çağrılmadan önce proje, API anahtarı, kullanıcı ve model limitlerine göre değerlendirir. Reddedilen istek için sağlayıcıda maliyet oluşmaz; her karar kayda geçer.

Kurallar

Politika varsayılan olarak kapalı gelir; yönetici proje proje açar. Her proje kendi limitlerini taşır, bir projenin taşması diğerini etkilemez. Boş bırakılan limit "sınırsız" demektir.

KuralNe sınırlarEngelle modunda sonuç
rate_limitDakikadaki istek sayısı429 rate_limited
daily_token_quotaGünlük toplam token429 quota_exceeded
monthly_token_quotaAylık toplam token429 quota_exceeded
max_input_tokensTek istekte modele giden metin400 context_too_large
max_output_tokensTek cevaptaki en çok tokenİstek geçer, cevap kırpılır
user_requiredKullanıcı limiti açıkken kimliksiz istek400 user_required
monthly_budget, budget_alertProje aylık USD bütçesi ve eşiği429 budget_exceeded

Bütçe kuralları Bütçe ve maliyet sayfasında ayrıntılı anlatılır.

Pencere mantığı ve modlar

  • Dakikalık limit kayan pencereyle sayılır: her istekte son 60 saniyeye bakılır.
  • Limit projenin bütün API anahtarlarının toplamına uygulanır.
  • Reddedilen istekte retryAfterSeconds ne zaman tekrar denenebileceğini söyler.
  • Kota, sağlayıcının bildirdiği girdi + çıktı token toplamıyla hesaplanır.
  • Gün ve ay başı USAGE_QUOTA_TIMEZONE ayarına göredir (Europe/Istanbul).
  • Girdi boyutu gönderilmeden tahmin edilir: yaklaşık 4 karakter = 1 token.
DurumEngelleSadece uyar
Dakikalık limit veya kota aşımı429 ile reddedilirİstek geçer, kayda düşer
Girdi çok büyük400 ile reddedilirİstek geçer
Çıktı sınırı aşılırmax_tokens sınıra indirilirKırpılmaz
Kimliksiz istek (kullanıcı limiti açık)400 user_requiredGeçer, kayda düşer
Model limiti dolduYönlendirilir ya da 429İstek ilk modele gider

İhlal modu projenin bütün katmanlarına uygulanır. Önerilen geçiş: limitleri önce "Sadece uyar" ile açıp bir-iki hafta izlemek, sonra "Engelle"ye geçmektir. Kota istek başında kontrol edildiği için eşzamanlı isteklerde birkaç istek kadar aşılabilir.

Limit katmanları ve kullanıcı kimliği

KatmanKapsamNot
ProjeProjenin toplam hızı ve tüketimiGirdi/çıktı sınırı yalnız bu katmanda
API anahtarıHer anahtar kendi sayacıylaBir entegrasyon diğerini etkilemez
KullanıcıHer son kullanıcı kendi sayacıylaX-FFM-User gerekir
ModelProjeye bağlı her model kendi sayacıylaDolunca engelle ya da sıradakine geç
  • Her katmanda dakikalık istek, günlük ve aylık token kuralı vardır.
  • Kimlik X-FFM-User başlığıyla ya da sohbet gövdesindeki user alanıyla gelir.
  • İkisi birlikte gelirse başlık geçerlidir; kimlik en çok 128 karakterdir.
  • Kimlik model sağlayıcısına iletilmez; yalnız limit ve raporlama içindir.
  • Kimliği uygulamanız doğrular; BaseLLM gelen değeri kullanır.
  • Anahtar ve kullanıcı için varsayılan limit ve istisna (özel limit) girilir.

Model limiti dolunca varsayılan davranış "İsteği engelle"dir; istenirse öncelik sırasındaki sonraki modele yönlendirilir. Hiçbir modelde yer yoksa istek 429 ile reddedilir (rate_limited ya da quota_exceeded, scope: llm). Dolu olduğu için atlanan model, o isteği kendi sayacına eklemez.

Hata kodları ve sonuç türleri

DurumHTTPKodUygulama ne yapmalı
Dakikalık limit aşıldı429rate_limitedretryAfterSeconds kadar bekleyip denemeli
Günlük ya da aylık kota doldu429quota_exceededTekrar denememeli; yöneticiye bildirmeli
Girdi izin verilenden büyük400context_too_largeMetni kısaltmalı ya da bölmeli
Kimliksiz istek400user_requiredHer isteğe kullanıcı kimliği eklemeli
Projenin tüm modelleri dolu429rate_limited / quota_exceededDaha sonra denemeli
Proje aylık bütçesi doldu429budget_exceededYöneticiye bildirmeli
Çıktı kırpıldı ya da yönlendirildi200Hata yokBir şey yapması gerekmez
ACTIONEkrandaİsteğe ne olur
blockedEngellendiModele gitmez; uygulama hata alır
warnedUyarıGeçer; yalnız kayda düşer
clampedKırpıldıGeçer; cevap sınıra kısaltılır
reroutedYönlendirildiSıradaki modele gider; hata yok
failed—Sağlayıcı hatasında yedek model de kalmadı

Limit hatalarındaki scope alanı sorunun yerini söyler: project, api_key, user ya da llm. Akışlı isteklerde hata, akış başlamadan düzgün bir HTTP hatası olarak döner.

Kayıt ve çok sunucu

KonuDavranış
BastırmaAynı kural için dakikada 1 kayıt + suppressedSinceLast
AuditHer karar Audit Log'a policy.violation olarak da gider
SaklamaVarsayılan 90 gün; POLICY_DECISION_RETENTION_DAYS
YansımaAyar değişikliği hemen yansır; birden fazla sunucuda diğerlerine Redis üzerinden iletilir (Redis yoksa en geç 5 sn). Kullanım ve bütçe sayaçları en geç 10 sn gecikmeyle güncellenir.
RedisDakikalık sayaç; çok kopyada gerekir (REDIS_URL)
Redis erişilemezseTrafik durmaz; her kopya geçici olarak kendi sayacına döner