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.
| Kural | Ne sınırlar | Engelle modunda sonuç |
|---|---|---|
| rate_limit | Dakikadaki istek sayısı | 429 rate_limited |
| daily_token_quota | Günlük toplam token | 429 quota_exceeded |
| monthly_token_quota | Aylık toplam token | 429 quota_exceeded |
| max_input_tokens | Tek istekte modele giden metin | 400 context_too_large |
| max_output_tokens | Tek cevaptaki en çok token | İstek geçer, cevap kırpılır |
| user_required | Kullanıcı limiti açıkken kimliksiz istek | 400 user_required |
| monthly_budget, budget_alert | Proje aylık USD bütçesi ve eşiği | 429 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.
| Durum | Engelle | Sadece uyar |
|---|---|---|
| Dakikalık limit veya kota aşımı | 429 ile reddedilir | İstek geçer, kayda düşer |
| Girdi çok büyük | 400 ile reddedilir | İstek geçer |
| Çıktı sınırı aşılır | max_tokens sınıra indirilir | Kırpılmaz |
| Kimliksiz istek (kullanıcı limiti açık) | 400 user_required | Geçer, kayda düşer |
| Model limiti doldu | Yö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
| Katman | Kapsam | Not |
|---|---|---|
| Proje | Projenin toplam hızı ve tüketimi | Girdi/çıktı sınırı yalnız bu katmanda |
| API anahtarı | Her anahtar kendi sayacıyla | Bir entegrasyon diğerini etkilemez |
| Kullanıcı | Her son kullanıcı kendi sayacıyla | X-FFM-User gerekir |
| Model | Projeye bağlı her model kendi sayacıyla | Dolunca 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
| Durum | HTTP | Kod | Uygulama ne yapmalı |
|---|---|---|---|
| Dakikalık limit aşıldı | 429 | rate_limited | retryAfterSeconds kadar bekleyip denemeli |
| Günlük ya da aylık kota doldu | 429 | quota_exceeded | Tekrar denememeli; yöneticiye bildirmeli |
| Girdi izin verilenden büyük | 400 | context_too_large | Metni kısaltmalı ya da bölmeli |
| Kimliksiz istek | 400 | user_required | Her isteğe kullanıcı kimliği eklemeli |
| Projenin tüm modelleri dolu | 429 | rate_limited / quota_exceeded | Daha sonra denemeli |
| Proje aylık bütçesi doldu | 429 | budget_exceeded | Yöneticiye bildirmeli |
| Çıktı kırpıldı ya da yönlendirildi | 200 | Hata yok | Bir şey yapması gerekmez |
| ACTION | Ekranda | İsteğe ne olur |
|---|---|---|
| blocked | Engellendi | Modele gitmez; uygulama hata alır |
| warned | Uyarı | Geçer; yalnız kayda düşer |
| clamped | Kırpıldı | Geçer; cevap sınıra kısaltılır |
| rerouted | Yönlendirildi | Sı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
| Konu | Davranış |
|---|---|
| Bastırma | Aynı kural için dakikada 1 kayıt + suppressedSinceLast |
| Audit | Her karar Audit Log'a policy.violation olarak da gider |
| Saklama | Varsayılan 90 gün; POLICY_DECISION_RETENTION_DAYS |
| Yansıma | Ayar 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. |
| Redis | Dakikalık sayaç; çok kopyada gerekir (REDIS_URL) |
| Redis erişilemezse | Trafik durmaz; her kopya geçici olarak kendi sayacına döner |