Yönlendirme ve Failover
Genel Bakış
Bir API proxy'sinde bir modele istek gönderildiğinde, Apinizer AI Gateway isteği önce birincil hedefe yönlendirir. Birincil hedef başarısız olursa (hata, zaman aşımı, kota aşımı vb.), istek önceden tanımlanan yedek hedeflere sırayla denenir.
Bir AI Gateway'in AI Routing sekmesi, bir isteğin modele ulaşana kadar geçtiği kararları üç adımlı bir karar zinciri olarak gösterir: Koşullu Kapı (varsa koşullu/semantik rotalar) → Hedef Seçimi (birincil hedef veya yük dengelemeli havuz) → sağlayıcıya iletim. Zincirin üstündeki özet bandındaki her adım tıklanabilir ve sayfayı ilgili bölüme kaydırır; Failover, ana akışın bir parçası değil, hedef başarısız olduğunda devreye giren ayrı bir hata yolu olarak gösterilir. Her adımda seçilen sağlayıcı/model için aynı standart model bilgi paneli açılır (sağlayıcı adı, model kimliği, bağlam penceresi, katalog fiyatı) — kimlik bilgisi veya başka bir gizli veri bu panelde hiçbir zaman görünmez.
Koşullu Yönlendirme ve Semantik Rotalar
Birincil hedefe geçmeden önce, isteğe bağlı olarak bir veya daha fazla koşullu rota değerlendirilir. Her koşullu rotanın bir Route Adı, bir hedefi (sağlayıcı/model) ve rotanın ne zaman devreye gireceğini belirleyen bir veya iki eşleşme mekanizması vardır:
- Kural tabanlı koşul — istek içeriğine göre değerlendirilen klasik koşul ifadesi
- Semantik eşleşme — isteğin, rota için tanımlanan örnek cümlelere (utterances) anlamsal olarak ne kadar yakın olduğuna bakan embedding-tabanlı eşleşme
Semantik Eşleşme
Bir rotaya örnek cümleler ve bir benzerlik eşiği (varsayılan 0.75) tanımlarsınız. İstek geldiğinde isteğin ilk mesajları tek seferde embedding'e çevrilir — bu embedding istek başına yalnızca bir kez hesaplanır ve o istekte değerlendirilen tüm semantik rotalar arasında paylaşılır. Elde edilen vektör her rotanın örnek cümle embedding'leriyle karşılaştırılır (kosinüs benzerliği); en yüksek benzerlik skoru rotanın eşiğini karşılıyorsa rota eşleşmiş sayılır. Embedding sağlayıcısı ve modeli, koşullu rotalar için proxy düzeyinde bir kez seçilir.
Bir rotada hem kural hem semantik eşleşme tanımlıysa, rota yalnızca ikisi birden sağlandığında devreye girer. Yalnızca semantik eşleşme tanımlıysa (kural yok), tek başına semantik sonuç yeterlidir.
Embedding sağlayıcısına ulaşılamıyorsa veya bir hata oluşursa, ilgili rota basitçe "eşleşmedi" sayılır — istek reddedilmez, sıradaki koşullu rotaya, orada da eşleşme yoksa birincil hedef seçimine devam eder. Semantik eşleşme bir güvenlik koruması değil bir yönlendirme mekanizmasıdır; bu nedenle bir hata durumunda isteği durdurmak yerine akışı kesintisiz sürdürür.
Hiçbir koşullu rota eşleşmezse istek doğrudan aşağıdaki Birincil Havuz Seçim Stratejileri bölümünde açıklanan hedef seçimine geçer.
Yönlendirme Metninde Ortam Değişkenleri
Semantik eşleşmeyi besleyen örnek ifadeler ve yakınlık (affinity) stratejilerinin anahtarını okuduğu başlık adı, ${DEGISKEN_ADI} biçiminde ortam değişkeni referansı kabul eder; böylece tek bir yönlendirme yapılandırması ortama özel ifade veya başlık adı taşıyabilir.
Örnek ifadelerin çözümlenmesi her istekte değil, rotanın vektörleri ilk kez oluşturulup önbelleğe alınırken bir kez yapılır. Burada yalnızca ${...} ortam değişkenlerinin kabul edilip #{...} bağlam değişkenlerinin kabul edilmemesinin nedeni budur: her istekte değişen bir değer ilk istekte vektörlenir ve aynı vektörler sonraki tüm isteklere servis edilirdi.
Failover Zinciri
Bir yönlendirme planı, öncelik sırasına göre bir veya daha fazla yedek hedef içerebilir:
- Birincil hedef — varsayılan olarak isteğin gönderildiği sağlayıcı/model
- Yedek hedef(ler) — birincil başarısız olduğunda sırayla denenen alternatif sağlayıcı/model tanımları
Bir yedek hedefe geçiş, orijinal isteği aynı içerikle yeniden dener; istemci tarafında ek bir işlem gerekmez.
Birincil Havuz Seçim Stratejileri
Aynı öncelik seviyesinde birden fazla birincil hedef tanımlıysa, hangisinin seçileceğini belirleyen bir strateji seçebilirsiniz:
| Strateji | Açıklama |
|---|---|
| Sıralı (round-robin) | Hedefler arasında sırayla dağıtım yapar |
| Ağırlıklı | Her hedefe atanan ağırlığa göre orantılı dağıtım yapar |
| Rastgele | Hedef rastgele seçilir |
| En-az-kullanılan | Son zamanda en az kullanılan hedef seçilir |
| En düşük maliyet | Hedeflerin katalog birim fiyatına göre en ucuz olanı seçilir; karşılaştırma girdi fiyatına çıktı fiyatının bir kısmını (varsayılan ağırlık: %25) ekleyerek yapılır — yalnızca girdi hacmine bakan düz toplamın aksine, çıktı ağırlıklı gerçek iş yüklerinde daha doğru sıralar |
| En düşük gecikme | Öncelik sırasıyla seçilir: önce gerçek trafikten ölçülen ortalama yanıt hızı, o yoksa periyodik sağlık kontrolü ölçümü kullanılır |
| Sabit önek yakınlığı | Aynı konuşmanın her zaman aynı havuz üyesine gitmesini sağlar — anahtar olarak önce session_id header'ı (özelleştirilebilir), o yoksa isteğin sistem ve ilk kullanıcı mesajının öneki kullanılır |
En düşük maliyet, en düşük gecikme ve sabit önek yakınlığı stratejileri, ilgili sinyal (fiyat, gecikme ölçümü veya yakınlık anahtarı) üretilemeyen hedeflerde otomatik olarak sıralı dağıtıma düşer.
Akış (streaming) isteklerinde en düşük gecikme stratejisi ilk-token süresini esas alır; akış kullanılmayan isteklerde ilk-token anı ölçülemediğinden toplam yanıt süresi kullanılır.
Havuz üyeleriniz zaten kendi önbellek-farkında yönlendirme kararını veren bir katmanın (ör. KV-cache-farkında bir çıkarım ağ geçidi) arkasındaysa sabit önek yakınlığı stratejisini seçmeyin — iki katman birbirinden habersiz aynı kararı vermeye çalışır ve bu çakışma önbellek isabet oranını iyileştirmek yerine düşürebilir. Bir üyenin yükü havuz ortalamasının belirli bir katını (varsayılan 1,25) aşarsa istek otomatik olarak bir sonraki üyeye kaydırılır; tek bir üye aşırı yüklenmez.
Maliyet Sınırlı Failover
Her failover adımı için isteğe bağlı bir maliyet sınırı (USD) tanımlanabilir. Bir yedek hedefin, girdi ve beklenen çıktı token'larına göre tahmini maliyeti bu sınırı aşıyorsa, o hedef atlanır ve sıradaki denenir.
Fiyatı katalogda tanımlı olmayan bir hedefin maliyet sınırı kontrolü yapılamaz; bu durumda hedef atlanmadan denenmeye devam eder.
Kota veya bütçe sınırına yaklaşıldığında, isteğin otomatik olarak daha düşük maliyetli bir modele yönlendirilmesini sağlayan bir seçenek de mevcuttur — detaylar için Token Kotaları ve Hız Sınırlaması sayfasına bakın.
Failover Zincirinin Alanları
Failover zinciri (sağlayıcı/model listesi, strateji, maliyet ve durum kodu ayarları), AI Gateway'in AI Routing sekmesinde satır satır (inline) tanımlanır ve şu bilgileri içerir:
| Alan | Açıklama |
|---|---|
| Strateji | Zincirin nasıl işleneceği — aşağıdaki tablo |
| Failover Kayıtları | Sırayla denenecek tanımlar: etiket, LLM sağlayıcı, model, kimlik bilgisi, zaman aşımı, maks. maliyet (USD), ağırlık |
| Geçerli Durum Kodları | Failover'ı tetikleyecek HTTP durum kodları (boş bırakılırsa varsayılan olarak 5xx / 408 / 429 kullanılır) |
| Tekrar Sayısı | Kayıt başına deneme sayısı (varsayılan 1) |
| Gecikme Eşiği (ms) | Yalnızca Koşullu stratejide okunur |
Strateji alanı, failover zincirinin nasıl işleneceğini belirler:
| Strateji | Açıklama |
|---|---|
| Sıralı | Kayıtlar sırayla denenir, ilk başarılı yanıt döner |
| Koşullu | Failover yalnızca tanımlı bir tetikleyici (gecikme eşiğinin aşılması gibi) gerçekleştiğinde devreye girer |
| Öncelik Sıkı | Bir üst kayıt tamamen kullanılamaz hale gelmediği sürece alt kayda geçilmez (örn. veri yerleşimi zorunluluğu olan senaryolar) |
| Round Robin | Hata olmasa da istekler kayıtlar arasında dağıtılır |
Bu dört strateji, Birincil Havuz Seçim Stratejileri bölümündeki yedi stratejiden farklı bir mekanizmadır: oradaki tablo eş-öncelikli birden fazla birincil hedef arasından seçim yapar, buradaki strateji ise failover zincirinin adımları arasında sırayla ilerleyiş biçimini belirler.
Failover zinciri proxy'nin kendi yapılandırmasının bir parçası olduğundan, proxy dışa aktarıldığında/içe aktarıldığında onunla birlikte taşınır; ayrıca APIops REST API ile de yönetilebilir — bkz. API Referansı: AI Gateway.
Araç Çağırma Döngüsü (Agentic Loop)
Model bir isteğe yanıt verirken kendi araçlarını çağırmayı seçtiğinde, Apinizer AI Gateway bu araç çağırma turlarını takip eder ve yapılandırılabilir bir üst sınıra kadar model ile araç sonuçları arasındaki döngüyü yönetir. Her tur, kullanım ve maliyet açısından ayrı ayrı ölçümlenir.