Başlarken
Uygulamanızı bağlayın
Uygulamanız model sağlayıcısı yerine BaseLLM'in OpenAI uyumlu sohbet uç noktasına, proje API anahtarıyla istek atar. Kullanıcı başına limit kullanacaksanız her isteğe X-FFM-User başlığını ekleyin.
Bağlantı mantığı
- İstek POST /api/v1/chat/completions yoluna gider; sunucu adresi kurulumunuza özeldir.
- Kimlik doğrulama proje API anahtarıyla yapılır; anahtarlar sk-ffm önekiyle başlar.
- Anahtar projeyi tanıtır, kişiyi tanıtmaz.
- Sağlayıcı anahtarları uygulamada değil, BaseLLM'de tutulur.
- Politika varsayılan olarak kapalı gelir; limitleri yönetici proje proje açar.
Örnek istek
from openai import OpenAI
client = OpenAI(
base_url="<basellm-uç-noktası>/api/v1",
api_key="sk-ffm-...", # proje API anahtarı
)
resp = client.chat.completions.create(
model="basellm", # BaseLLM bu alanı yok sayar
messages=[{"role": "user", "content": "Merhaba"}],
extra_headers={"X-FFM-User": "u-12345"},
)
Başlıklar ve alanlar
| Ad | Tür | Kural |
|---|---|---|
| X-FFM-User | İstek başlığı | Son kullanıcı kimliği; en çok 128 karakter |
| X-FFM-User-Signature | İstek başlığı | Projede kişi kimliği imzası zorunluysa: t=<unix saniye>,v1=<hex HMAC-SHA256(imza anahtarı, "t.kimlik")>; 5 dakika geçerli |
| user | Gövde alanı | Başlık yerine kullanılabilir; ikisi gelirse başlık geçerli |
| X-FFM-Session | İstek başlığı | Oturum kimliği, 1–128 karakter; oturum hafızası için |
| correlation_id | Kayıt alanı | Audit, kullanım ve log kayıtlarını birbirine bağlar |
| X-FFM-Cache | Cevap başlığı | Yanıt önbelleği: HIT, MISS, SHADOW, BYPASS |
| X-FFM-Memory | Cevap başlığı | Hafızanın işi, ör. session=continued; kept=6 |
X-FFM-User model sağlayıcısına iletilmez; limit, model izni ve raporlama için kullanılır. Kimliği uygulamanız doğrular; BaseLLM gelen değeri olduğu gibi kullanır. Ad-soyad yerine kurum içi kısa bir kod gönderin. Proje anahtarı son kullanıcının elindeyse başka birinin kimliğini yazabilir; bunu önlemek için projede kişi kimliği imzasını zorunlu yapın ve kimliği, imza anahtarı yalnız sunucunuzda duran uygulamanızla imzalayın.
Hata kodları
| Durum | HTTP | Kod | Uygulama ne yapmalı |
|---|---|---|---|
| Dakikalık istek limiti aşıldı | 429 | rate_limited | retryAfterSeconds kadar bekleyip deneyin |
| Günlük ya da aylık token kotası doldu | 429 | quota_exceeded | Yeniden denemeyin; yöneticiye bildirin |
| Girdi izin verilen boyuttan büyük | 400 | context_too_large | Metni kısaltın ya da bölün |
| Kullanıcı limiti açık, kimlik yok | 400 | user_required | Her isteğe kullanıcı kimliği ekleyin |
| Projenin tüm modelleri dolu | 429 | rate_limited / quota_exceeded | Daha sonra deneyin; scope: llm |
| Gizli anahtar tespit edildi | 403 | secret_blocked | Anahtarı metinden çıkarın ve yenileyin |
| Kişisel veri engellendi | 403 | pii_blocked | Kişisel veriyi metinden çıkarın |
| Projede kendi modeli yok, yalnız sağlayıcı bağlantısı var ve model adı verilmedi | 400 | model_required | model alanına izinli bir model adı yazın (GET /api/v1/models) |
| Kişi kimliği imzasız ya da imza geçersiz | 401 | user_signature_invalid | X-FFM-User-Signature'ı güncel zamanla ve doğru anahtarla üretin |
| İstenen model izinli değil, fiyatı yok ya da tavanı aşıyor | 400 | model_not_allowed / model_unpriced / model_over_price_cap | GET /api/v1/models listesinden seçin ya da model alanını auto yapın; scope: api_key ya da user ise kısıt anahtarın ya da kişinindir |
| Proje aylık bütçesi doldu | 429 | budget_exceeded | Yöneticiye bildirin |
Limit hatalarında scope alanı sorunun yerini gösterir: project, api_key, user ya da llm. Maks. çıktı sınırı hata üretmez; istek 200 ile tamamlanır ve cevap kırpılır. Limit dolunca yönlendirmede de 200 döner; cevaptaki model alanı kullanılan modeli gösterir.
Önerilen geçiş
Yeni bir projede limitleri Sadece uyar modunda açın ve bir-iki hafta kayıtları izleyin. “Kullanıcı kimliği yok” kayıtları, kimlik göndermeyen entegrasyonları gösterir. Değerler normal kullanımı kesmiyorsa Engelle moduna geçin.
- Kota istek başında kontrol edilir; eşzamanlı isteklerde birkaç istek kadar aşılabilir.
- Girdi boyutu tahmindir (4 karakter ≈ 1 token); Türkçe metin daha fazla token tutabilir.
- 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.
- Maks. çıktı sınırı yalnızca sohbet isteklerinde uygulanır.