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.
Hedef Nasıl Seçilir
Ağ geçidi her istek için hedefi kademeli çözer ve kullanılabilir bir sağlayıcı+model veren ilk kademede durur:
- Koşullu rotalar — sırayla değerlendirilir, ilk eşleşen kazanır.
- Varsayılan hedef grubu — hiçbir rota eşleşmediğinde devreye girer: yük dağıtımı havuzu tanımlıysa algoritması aktif üyeyi seçer, havuz yoksa tek varsayılan sağlayıcı ve model kullanılır.
- Failover zinciri (hata yolu) — varsayılan hedef grubu boş ya da kullanılamaz olduğunda devreye girer: zincirin ilk kullanılabilir satırı o istek için birincil hedefe terfi eder, zincirin kalanı arkasında failover olarak durur.
- Uygun sağlayıcı yok — hiçbir kademe hedef vermezse istek HTTP 503 ve "No suitable LLM provider found for this request" mesajıyla reddedilir.
Bu, her kademenin tek başına eksiksiz bir yapılandırma olduğu anlamına gelir. Yalnızca koşullu rotalardan oluşan bir ağ geçidi çalışır; yalnızca havuzdan ya da yalnızca failover zincirinden oluşan da öyle. Varsayılan sağlayıcı ve modeli yalnızca hiçbir rotanın eşleşmediği istekler için bir düşüş noktası istiyorsanız — ya da rotalarınız/havuz satırlarınız bilerek boş bırakıp devralacaksa — tanımlamanız gerekir.
Bir aday şu durumlarda atlanır ve bir sonraki kademe denenir: sağlayıcısı silinmiş ya da pasif, veya ne satırın kendisi ne de proxy düzeyindeki varsayılan bir model veriyor. Eşleşen ama hedefi kullanılamayan bir koşullu rota da atlanır ve değerlendirme sonraki rotayla sürer.
Atlanmayanlar: sağlayıcının izin vermediği bir model, kimlik bilgisinin (credential) çağırmasına izin verilmeyen bir model, modalite uyuşmazlığı veya emekliye ayrılmış (sunset) bir model. Bunlar sessizce başka bir hedefe yönlendirilmez, seçilen hedef üzerinde hata döner — görmeniz gereken yapılandırma/yetki sorunlarıdır, etrafından dolaşılacak durumlar değil.
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.
Bir rotaya örnek cümle eklendiyse, proxy düzeyinde bir semantik embedding sağlayıcısı da seçilmiş olmalıdır; aksi halde kayıt "Bir koşullu rota anlamsal ifade (semantic utterance) kullanıyor; bu nedenle AI Routing sekmesinde bir embedding sağlayıcısı da seçilmelidir" hatasıyla reddedilir. Önceki sürümlerde böyle bir proxy sorunsuz kaydediliyor, ardından tüm semantik rotalar ekranda hiçbir uyarı olmadan yalnızca kural koşuluyla değerlendiriliyordu. Sağlayıcı seçildikten sonraki istek anındaki davranış değişmedi ve bilinçli olarak fail-open'dır (yukarıdaki uyarı).
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:
Her havuz satırında bir sağlayıcı seçilmiş olmalıdır. Satırın modeli isteğe bağlıdır; boş bırakılırsa varsayılan hedefin modeli devralınır — aynı kural failover zinciri satırları için de geçerlidir ve devralınacak bir varsayılan model yoksa kendi modeli olmayan satır reddedilir. Sağlayıcısı olmayan bir satır istek anında ağ geçidi tarafından atlanır; bu nedenle hiç çalışmayacak bir yapılandırma olarak ekranda bırakılmak yerine kaydedilirken reddedilir.
Bu denetimler, yönlendirme yapılandırmasının kendisini kaydettiğinizde çalışır: AI Routing sekmesi, APIops ai-routing ucu, promosyon ya da içe aktarma. Aynı proxy üzerindeki ilgisiz işlemler (deploy etmek, politika eklemek, yetki düzenlemek) bu denetimleri yeniden çalıştırmaz; böylece bir kuraldan önce kaydedilmiş bir proxy hiçbir zaman açılıp düzeltilemez hale gelmez.
Bir havuz üyesi sağlayıcısı silinmiş/pasif olduğunda ya da çözülebilir bir modeli olmadığında atlanır — havuz kalan üyeler arasında dağıtıma devam eder. Hiç üye kalmazsa yönlendirme tek varsayılan hedefe, o da yoksa failover zincirine düşer.
| 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.
Uç Noktalar ve Hızlı Test
AI Gateway'in AI Routing sekmesindeki Uç Noktalar paneli, sistemde tanımlı her ortam için gerçekte çağrılacak data-plane adresini listeler; adresin yanındaki kopyala ikonuyla panoya alabilirsiniz.
Bu panel, proxy'nin o ortama deploy edilip edilmediğine bakmaksızın kurulumda tanımlı tüm ortamları listeler. Proxy'nin henüz deploy edilmediği bir ortamın satırında Test düğmesi çalıştırılırsa, çağrı gateway'de başarısız olur (proxy o ortamda bulunmaz).
Her satırda bir Test düğmesi bulunur: bu düğme, o satırın adresi + /v1/chat/completions
yolunu ve minimal, önceden doldurulmuş bir istek gövdesini (yönlendirmedeki model, messages
alanında tek bir "ping" mesajı, max_tokens: 16) taşıyan Test Console'u açar.
Bu Test düğmesi, yapılandırılmış gerçek LLM sağlayıcısına bir istek gönderir ve maliyet/kota
doğurur — bu yüzden istek gövdesindeki max_tokens değeri kasıtlı olarak düşük (16) tutulmuştur.
Panel, proxy A2A ile gömülü modda çalışırken hiç görünmez; Test düğmesi ise yönetim (proxy düzenleme) yetkiniz yoksa pasif kalır.
Bu panel akış (streaming) yanıtının test edilmesini, test çağrısı için token/maliyet özetini ve embedding, ses veya görüntü istekleri için hazır şablonları kapsamaz — bunlar için tam bir API istemcisi kullanın.
Güvenilir Tekrar Denemeler ve Faturalama
Failover tekrar denemeleri doğru şekilde faturalandırılır: bir bağlantıya yapılan başarısız bir deneme, kullanım veya bütçenize hiçbir zaman yansımaz — yalnızca yanıtı fiilen veren bağlantı faturalandırılır ve loglanır.
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.