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 LLM Gateway'in Yönlendirme 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ının uç noktası, dağıtım türü ve canlı sağlık durumu; modelin bağlam penceresi, azami çıktı token sayısı ve milyon token başına fiyatları; model kapalıysa bir uyarı) — kimlik bilgisi veya başka bir gizli veri bu panelde hiçbir zaman görünmez.
Karar zincirinin altında, sekmede isteğin tek bir dalına değil her isteğe uygulanan iki grup ayar daha vardır: İstemci "model" alanı kartı ve Bağlantı & İletim Ayarları grubu. Grupta bir Bağlantı kartı (zaman aşımları ve bağlantı havuzu), bir Streaming kartı (Streaming anahtarı, istemci "stream" alanı ve akış sınırları) ile SSL/mTLS, giden proxy ve anonim erişim kartları vardır. Bkz. Bağlantı ve İletim Ayarları. İstemci "model" alanı kartı iki ayarını doğrudan kartın üzerinde taşır — açılacak bir Yapılandır çekmecesi yoktur ve her seçim yapıldığı anda kaydedilir. Proxy üzerinde yalnız okuma yetkisi olan kullanıcı, seçenek kartları yerine iki eksenin seçili değerini özet olarak görür.
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. LLM Gateway liste kartı da aynı kuralı izler: havuz tanımlıysa havuzun ilk üyesini, yoksa tek varsayılan hedefi gösterir.
- 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ıda kapalı olan bir model, çağıran tüketicinin çağırmasına izin verilmeyen bir model veya modalite uyuşmazlığı. 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.
Yönlendirme sekmesini hiçbir hedef olmadan kaydedebilirsiniz: koşullu rota, havuz satırı ve failover satırı yoktur; varsayılan sağlayıcı ve model boştur. Sekmede bir uyarı görünür. Proxy kaydedilir ve deploy edilebilir, ancak siz bir hedef ekleyene kadar her istek HTTP 503 (POLICY_ROUTING_AI_NO_SUITABLE_PROVIDER) hatası alır. Deploy engellenmez.
Bir hedef alanı dolu olduğu halde hedef üretmeyen tanım kayıtta yine reddedilir. Örnek: sağlayıcı seçili, model boş ve listede satır yok.
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 Yönlendirme 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.
Hedef Havuzu Rotaları
Rota penceresinde Hedef tipi alanı iki seçenek sunar: Tek hedef (varsayılan) ve Hedef havuzu (yük dağıtımı). Tek hedef seçeneğinde rota eşleşen istekleri tek bir sağlayıcı · modele gönderir.
Aynı model birden fazla sunucuda çalışıyorsa Hedef havuzu (yük dağıtımı) seçeneğini seçin. Rota, eşleşen istekleri kendi algoritmasıyla hedefleri arasında dağıtır. Sunucuların önüne ikinci bir proxy koymanız gerekmez.
Örnek: qwen3-8b modeli a1, a2 ve a3 sunucularında çalışıyor.
model = qwen3-8bkuralıyla bir rota oluşturun. Hedef havuzu (yük dağıtımı) seçin ve her sunucu için bir hedef ekleyin.model = deepseek-r1kuralıyla ikinci bir rota oluşturun. Hedef havuzu (yük dağıtımı) seçin ve hedeflerini ekleyin.
Her rotanın kendi havuzu ve kendi dağıtım durumu vardır. Bir rotadaki Round Robin sırası diğer rotayı etkilemez.
| Alan | Açıklama |
|---|---|
| Algoritma | Varsayılan Hedef Grubu ile aynı yedi algoritma: Round Robin, Ağırlıklı, En Düşük Gecikme, Rastgele, LRU, En Düşük Maliyet ve Önek Yapışkanlığı. Bkz. Birincil Havuz Seçim Stratejileri. |
| Yapışkanlık Anahtarı Header'ı ve Yük Sınırı Katsayısı | Önek Yapışkanlığı için görünür. Değerler rota başınadır. Varsayılanlar: session_id ve 1.25. |
| Görünen Ad | Hedefin rota listesindeki ve havuz özetindeki adı. |
| LLM Sağlayıcı | Her hedef için zorunludur. |
| Model ID | Her hedef için zorunludur. Hedef, varsayılan hedefin modelini devralmaz. |
| Ağırlık | Yalnız Ağırlıklı algoritmada görünür. Yüksek ağırlık daha fazla trafik alır. |
Satır eklemek için Hedef Ekle düğmesine tıklayın. Bir hedefte sağlayıcı veya model yoksa kayıt reddedilir.
Havuz rotası için rota listesi ve rota özeti Hedef havuzu · algoritma · N hedef bilgisini gösterir. Bu seçenekten önce kaydedilmiş rotalar Tek hedef olarak açılır. Geçiş işlemi gerekmez.
Havuzdaki diğer hedeflerin denenip denenmeyeceğini Hata yolu ayarlarındaki Havuzdaki diğer hedefleri dene seçeneği belirler. Bkz. Havuzdaki Diğer Hedefleri Deneme.
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.
Rota Eşleşme Yöntemleri ve LLM Sınıflandırıcı
Rota penceresinde Eşleşme Yöntemi için üç seçenek vardır: Kural tabanlı, Anlamsal ve Sınıflandırıcı. Anlamsal ve Sınıflandırıcı için Kural koşulları da sağlansın (VE) onay kutusu görünür. Anlamsal veya sınıflandırıcı eşleşmesine ek olarak kural koşullarını da zorunlu kılmak için bu kutuyu işaretleyin.
Rota listesi her rota için bir eşleşme türü rozeti gösterir: KURAL, ANLAMSAL, ANLAMSAL + KURAL, SINIFLANDIRICI veya SINIFLANDIRICI + KURAL.
Hibrit düğmesi artık yoktur. Hibrit olarak kaydedilmiş rota Anlamsal yöntemiyle ve Kural koşulları da sağlansın (VE) işaretli olarak açılır. Kayıtlı yapılandırma değişmez.
Sınıflandırıcı ile Yönlendirme
Sınıflandırıcı ile yönlendirme, hedefi yalnız maliyete göre değil, isteğe uygunluğa göre seçer. Örneğin kodlama istemlerini A modeline, finans istemlerini B modeline, hukuk istemlerini C modeline gönderebilirsiniz.
Sınıflandırıcı adlı küçük bir LLM istemi okur ve tek bir etiketle yanıt verir. Bu etikete sahip rota seçilir. Her sınıflandırıcı rotasının iki alanı vardır:
| Alan | Açıklama |
|---|---|
| Etiket | İstek türü için kısa bir ad. Küçük harf, rakam, _ ve - kullanın. En fazla 64 karakter olabilir. Etiket harf veya rakamla başlar ve biter. none etiketi ayrılmıştır. |
| Açıklama | Zorunludur. En fazla 500 karakter olabilir. Sınıflandırıcı model bu metne göre karar verir. Rotaya ait istek türünü açıklayın. ${env} ortam değişkenleri çözülür; #{...} bağlam değişkenleri çözülmez. |
Birden çok rota aynı etiketi kullanabilir. Bu durumda listede sıradaki ilk ve kural koşulları da sağlanan rota kazanır. Bir etiketi istek boyutuna göre bölmek için bu yöntemi kullanın. Örnek:
- Rota 1:
codeetiketi, Tahmini İstek Token Sayısı 2000'den büyük koşulu. Hedef: büyük model. - Rota 2:
codeetiketi, koşul yok. Hedef: küçük model.
LLM Sınıflandırıcı Ayarları
Koşullu Rotalar çekmecesini açın ve LLM sınıflandırıcı kutusunu yapılandırın. Bu kutuyu proxy'nin tüm sınıflandırıcı rotaları paylaşır.
| Alan | Açıklama |
|---|---|
| Sınıflandırıcı Sağlayıcı | Sınıflandırıcıyı çalıştıran LLM sağlayıcısı. |
| Sınıflandırıcı Model | Bu sağlayıcının modeli. |
| Model davranışı | Standart (varsayılan) veya Reasoning. Bkz. Model Davranışı. Karar modellerinde görünmez. |
| Reasoning bütçesi (token) | Yalnız Reasoning seçiliyse görünür. Aralık 256 ile 8192. Varsayılan 1024. |
| Zaman aşımı (ms) | Sınıflandırıcı için en uzun bekleme süresi. Standart: varsayılan 1000, aralık 100 ile 10000. Reasoning: varsayılan 15000, en çok 60000. |
| En fazla girdi karakteri | Sınıflandırıcıya giden kullanıcı mesajının en büyük uzunluğu. Daha uzun mesaj kısaltılır. Varsayılan 2000. Aralık 200 ile 20000. |
| Ek yönerge (isteğe bağlı) | Sınıflandırıcı için ek metin. Örnek: "Fatura soruları finance etiketidir." ${env} ortam değişkenleri çözülür; #{...} bağlam değişkenleri çözülmez. Kullanıcı istemi hiçbir zaman çözülmez. |
Kutu, sınıflandırıcıya giden etiket listesinin önizlemesini de gösterir.
Hangi Sağlayıcılar Sınıflandırabilir
Sınıflandırıcı Sağlayıcı listesi projedeki tüm sağlayıcıları gösterir. Liste şu gruplara ayrılır:
| Grup | Sağlayıcılar |
|---|---|
| Sohbet modelleri | OpenAI uyumlu sohbet sağlayıcıları ve Anthropic. |
| Karar modelleri | TypeSafe Jev. |
| Rota sınıflandırıcısı olamaz | Listelenen ama seçilemeyen sağlayıcılar. Neden, adın altında yazar. |
Şu sağlayıcılar sınıflandırabilir:
- OpenAI uyumlu sohbet sağlayıcıları: OpenAI, Azure OpenAI, DeepSeek, Moonshot (Kimi), Zhipu, Mistral, Groq, Ollama, vLLM, xAI, Google AI Studio OpenAI uç noktası, Together, Fireworks, Cerebras, Hugging Face, OpenRouter, Perplexity ve NVIDIA NIM. Adapter ailesi
OPENAI_COMPATIBLEveyaVLLMolan özel bir sağlayıcı da sınıflandırabilir. - Anthropic. Apinizer yerel Messages API'sini kullanır.
- TypeSafe Jev. Bkz. TypeSafe Jev Sınıflandırıcı Olarak.
Şu sağlayıcılar sınıflandıramaz: AWS Bedrock, Google Vertex AI, Cohere, yerel Gemini wire formatı, yalnız embedding sağlayıcıları, TEI koruma sınıflandırıcıları ve adapter ailesi olmayan özel sağlayıcılar. Özel sağlayıcıda adapter ailesini ayarlayın.
Sınıflandırıcı çağrısı, sağlayıcıda saklı kimlik bilgisini kullanır. Sağlayıcının kimlik bilgisi kaynağını AI gateway sağlar olarak ayarlayın. İstemci sağlar seçili bir sağlayıcı için sınıflandırıcı çağrısında istemci anahtarı yoktur. Sağlayıcı 401 veya 403 ile yanıt verir.
TypeSafe Jev ve TEI yalnız karar verir. Bunları yönlendirme hedefi, havuz üyesi, failover hedefi veya embedding sağlayıcısı olarak kullanamazsınız. Bu listelerde görünmezler. Apinizer, bunlardan birine başvuran kaydı reddeder.
Model Davranışı: Standart veya Reasoning
Model davranışı, Apinizer'a sınıflandırıcı modelin nasıl yanıt verdiğini bildirir.
| Davranış | Ne için kullanılır | Apinizer ne gönderir |
|---|---|---|
| Standart (varsayılan) | Hemen yanıt veren küçük instruct modeller. | Sıcaklık 0 ve küçük bir çıktı sınırı. Ollama için reasoning_effort: "none". Böylece qwen3 ve deepseek-r1 gibi düşünen modeller doğrudan yanıt verir. |
| Reasoning | Yanıttan önce düşünen modeller: DeepSeek Reasoner, Kimi thinking, Claude extended thinking, OpenAI o-serisi, düşünmesi açık qwen3. | Sıcaklık gönderilmez. Reasoning bütçesi (token), düşünme ve yanıt için ortak çıktı sınırıdır. Ollama için düşünme açık kalır. |
Sizin ayarladığınız değer, davranışın varsayılan değerinden her zaman önceliklidir.
Anthropic için Standart, normal bir Messages çağrısı gönderir. Reasoning, extended thinking'i açar. Yeni modeller uyarlamalı (adaptive) düşünme kullanır. Eski modeller token bütçeli sabit düşünme kullanır. Apinizer bir biçimi dener, sonra sağlayıcı ve model için çalışan biçimi hatırlar.
Bazı modeller yalnız varsayılan sıcaklığı kabul eder. Örnekler: Kimi, OpenAI o-serisi ve gpt-5 modelleri. Apinizer bir kez sıcaklık olmadan yeniden dener ve bunu model için hatırlar.
Model yanıt vermeden önce tüm reasoning bütçesini kullanırsa sonuç TRUNCATED olur ve hiçbir sınıflandırıcı rotası eşleşmez. Reasoning bütçesi (token) değerini artırın veya düşünmeyen bir modelle Standart seçin.
Sınıflandırıcı, bir sınıflandırıcı rotasına ulaşan her istekten önce çalışır. Reasoning modeli bu isteklerin her birine birkaç saniye ve kendi token maliyetini ekler. Yayına almadan önce Yönlendirmeyi test et ile gecikmeyi ve düşünme token'larını görün.
Sağlayıcı güvenlik nedeniyle yanıt vermeyi reddederse sınıflandırıcı bunu eşleşme yok sayar.
TypeSafe Jev Sınıflandırıcı Olarak
TypeSafe Jev yapısal bir karar modelidir. Metin üretmez. Apinizer rota etiketlerini ve açıklamalarını seçenek olarak, "hiçbiri" seçeneğini de ekleyerek gönderir. Kullanıcı istemi durum olarak gider. Jev, 0 ile 1 arasında bir güvenle tek bir seçenek döndürür.
- Model davranışı, Reasoning bütçesi (token) ve çıktı sınırı uygulanmaz. Ekran bunun yerine bir bilgi notu gösterir.
- Yönlendirmeyi test et sonucu Güven değerini gösterir. Yönlendirme izi de bu değeri gösterir.
- Sağlayıcıyı TypeSafe Jev tipiyle oluşturun. Bkz. LLM Sağlayıcıları.
Sınıflandırıcı Modelini Seçme
Küçük ve hızlı bir model kullanın. Sınıflandırıcı tek kelimeyle yanıt vermelidir.
- Küçük instruct modeller. Standart seçin. Ollama örnekleri: qwen2.5:1.5b-instruct, llama3.2:3b ve granite3.3:2b.
- Akıl yürüten ("thinking") modeller. Reasoning seçin. Bir Reasoning bütçesi (token) ve daha uzun bir Zaman aşımı (ms) verin. Bu modeller Standart ile yanıttan önce akıl yürütmelerini kısa yanıt sınırına yazar. Yanıt boş kalır ve sonuç
TRUNCATED(Çıkış sınırına ulaşıldı) olur. Zaman aşımı kısaysa aynı sorunTIMEOUTolarak görünebilir.- Ollama: Standart davranışta Apinizer düşünmeyi sizin için kapatır. Her sınıflandırıcı çağrısıyla
reasoning_effort: "none"gönderir. qwen3 gibi düşünen modeller bu durumda doğrudan yanıt verir. - vLLM ve diğer OpenAI uyumlu sunucular: Standart için modelin düşünmeyen bir sürümünü sunun veya sunucuda düşünmeyi kapatın.
- OpenAI ve Azure OpenAI: Apinizer OpenAI'ye
max_completion_tokensgönderir. Azure OpenAI bu alanıapi-version2024-09-01 ve sonrasında alır. Daha eski sürümdemax_tokensalır.
- Ollama: Standart davranışta Apinizer düşünmeyi sizin için kapatır. Her sınıflandırıcı çağrısıyla
- Zaman aşımı. Sınıflandırıcı gecikmesini görmek için Yönlendirmeyi test et penceresini kullanın. Sonra Zaman aşımı (ms) değerini bu sürenin yaklaşık iki katı yapın. Testlerimizde Ollama üzerindeki yerel 8B–14B modeller, ısındıktan sonra 0,25–0,7 saniyede yanıt verdi. Model yüklendikten sonraki ilk çağrı daha yavaştır.
- Belirsiz istekler. Bir istek türü yanlış rotaya gidiyorsa bu türü Ek yönerge alanında tanımlayın. Örnek: "Vergi beyannamesi, KDV iadesi ve fatura soruları belge veya mevzuattan söz etse de finance etiketidir." Bir yönerge, özellikle küçük modellerde, başka isteklerin yanıtını da değiştirebilir. Yönergeyi değiştirdikten sonra her rota için örnek istemlerle yeniden test edin.
Kabul Edilen Yanıt Biçimi
Sınıflandırıcı yanıtı etiketlerden biri veya none olmalıdır. Apinizer şu farklılıkları kabul eder:
- Büyük/küçük harf farkı, çevreleyen tırnak, ters tırnak, kalın yazı işareti ve sondaki nokta.
category:veyalabel:öneki.- Baştaki
<think>…</think>bloğu. - Tek üyeli bir JSON nesnesi:
labelveyacategory. Örnek:{"label": "code"}. - Yalnız ilk boş olmayan satır okunur.
Apinizer bir cümleden etiket tahmin etmez. "code - kullanıcı Python soruyor" gibi bir yanıt UNKNOWN_LABEL sonucunu verir ve hiçbir sınıflandırıcı rotası eşleşmez.
Rotalar Nasıl Değerlendirilir
- Apinizer rotaları yukarıdan aşağıya değerlendirir.
- Her rota için önce kural koşullarına bakar. Sonra anlamsal veya sınıflandırıcı eşleşmesine bakar. Kural koşulları tanımlıysa ikisi de eşleşmelidir (VE).
- Sınıflandırıcı istek başına en fazla bir kez çağrılır. Yalnız bir sınıflandırıcı rotasına gelindiğinde çağrılır.
- Sınıflandırıcıya yalnız kural koşulu sağlanan sınıflandırıcı rotalarının etiketleri sunulur.
- Sınıflandırıcı son kullanıcı mesajını alır. Mesaj En fazla girdi karakteri değerine kısaltılır. Sınıflandırıcı tek bir etiketle veya
noneile yanıt verir. Standart davranışta sıcaklık 0'dır ve yanıt en fazla 32 çıktı token'ı ile sınırlıdır. Reasoning davranışında sınır, reasoning bütçesidir. - Sınıflandırıcı yalnız yönlendirme aşamasında, kimlik doğrulamadan ve PII maskelemeden sonra çalışır. Maskelenmiş istemi alır. Kimliği doğrulanmamış istek sınıflandırıcı çağrısına neden olmaz.
Sınıflandırıcı başarısız olursa istek reddedilmez. Bu davranış fail-open'dır. Şu durumlarda sınıflandırıcı rotaları eşleşmez:
- Sınıflandırıcı hata verir.
- Sınıflandırıcı zaman aşımına uğrar.
- Model yanıt vermeden önce çıkış sınırına ulaşır (
TRUNCATED). - Sağlayıcı güvenlik nedeniyle yanıt vermeyi reddeder.
- Sınıflandırıcı hiçbir rotanın kullanmadığı bir etiketle yanıt verir.
- Sınıflandırıcı sağlayıcısı tanımlı değildir.
- Sınıflandırıcı modeli sağlayıcıda kapalıdır ya da model kimliği belirsizdir. Apinizer çağrı yapmaz ve sonucu
NO_PROVIDERolarak kaydeder. - Sınıflandırıcı kısa süre önce başarısız olmuştur. Zaman aşımı, hata veya
TRUNCATEDsonucundan sonra Apinizer o proxy için 15 saniye boyunca sınıflandırıcı çağrılarını atlar. SonuçBACKOFFolur. Proxy'yi yeniden yüklemek bekleme süresini sıfırlar.
İstek listede aşağı doğru devam eder. Hiçbir rota eşleşmezse istek Varsayılan Hedef Grubu'na gider.
Token hız sınırının proxy koruma limiti, semantik önbellek araması ve döngü koruması yönlendirme aşamasında çalışır. Bu kurallar, sağlayıcı ve model kesinleştikten ve model erişim listesi çağıranı geçirdikten sonra çalışır. Bir sınıflandırıcı rotası kazanırsa bu kurallar seçilen rotanın modelini kullanır. Hiçbir kural tahmin edilen modelle çalışmaz.
İstek gövdesi boyut sınırı (413) ve stream uyumluluk kontrolleri (400), token limitinden (429) ve önbellek cevabından önce çalışır. Çok uzun bir istem 429 yerine 413 alır.
Kullanıcı, istem metniyle sınıflandırıcının seçimini yönlendirmeyi deneyebilir. Seçim her zaman tanımladığınız rotalarla sınırlıdır. Seçilen rota kotaları ve Limit Planı'nı etkilemez.
Yönlendirme ekranının ilk aşama panelinde iki bilgi mesajı görünür: Sınıflandırıcı: sağlayıcı · model · zaman aşımı ms ve Embedding: sağlayıcı · model.
İstek Boyutuna Göre Yönlendirme
İsteği boyutuna göre yönlendirebilirsiniz. Rotanın kural koşullarında Tahmini İstek Token Sayısı bağlam değerini seçin. Veri tipini Sayısal yapın ve bir işleç seçin. Örnek: büyük.
Değer, istek gövdesindeki token sayısının tahminidir. Apinizer backend'e giden gövdeyi kullanır. Yoksa istemciden gelen gövdeyi kullanır.
Yönlendirmeyi Test Etme
Örnek bir istemin hangi rotayı seçtiğini görmek için Yönlendirmeyi test et düğmesini kullanın. Düğme yalnız Koşullu Rotalar panelinde görünür.
- Yönlendirmeyi test et düğmesine tıklayın.
- Yüklenmiş bir ortam seçin.
- Örnek bir istem girin.
- Testi çalıştır düğmesine tıklayın.
Worker kayıtlı yönlendirmeyi değerlendirir. Hedef model çağrılmaz. Hiçbir şey kaydedilmez.
Test, sınıflandırıcı ve embedding sağlayıcılarını çağırır. Bu çağrıların maliyeti olabilir.
Sonuç ekranı şunları gösterir:
- Tahmini istek token sayısı.
- Sınıflandırıcının etiketi, sonucu, gecikmesi, token sayısı ve maliyeti. Reasoning modelinde token sayısı düşünme token'larını da içerir. Sağlayıcı düşünme token'larını bildirmiyorsa (örneğin Ollama veya vLLM), Apinizer bunları modelin döndürdüğü düşünme metninden tahmin eder. TypeSafe Jev için sonuç ayrıca Güven değerini gösterir.
- Her rota için bir satır içeren tablo: kural, anlamsal skor, sınıflandırıcı yanıtı ve sonuç. Sonuç Seçildi, Eşleşmedi, Hedef kullanılamaz veya Değerlendirilmedi olur. Hedef sağlayıcıyı ve modeli görmek için Seçildi üzerine gelin.
- Havuz rotası için sonuç Seçildi → Hedef havuzu · algoritma · N hedef olur. Hedefi ağ geçidi istek geldiğinde seçer; bu yüzden test havuzdaki bir hedefin adını vermez.
- Hiçbir rota eşleşmezse "Hiçbir rota eşleşmedi — istek Varsayılan Hedef Grubu'na gider" mesajı.
Tahmini İstek Token Sayısı dışındaki kurallar gerçek istek ister. Test bu kuralların eşleştiğini varsayar ve RUNTIME_ONLY olarak gösterir. Gerçek istek olmadan değerlendirilemeyen bir kuralın NOT değeri INDETERMINATE olarak gösterilir.
Test, 15 saniyelik bekleme süresini yok sayar ve sınıflandırıcıyı her zaman çağırır. Embedding başarısız olursa pencere yalnız hata türünü içeren bir uyarı gösterir.
Gözlemlenebilirlik
Trafik logunda sınıflandırıcı için şu seyrek alanlar bulunur:
| Alan | Açıklama |
|---|---|
aircl | Sınıflandırıcının döndürdüğü etiket. |
aircs | Sonuç: MATCHED, NONE, UNKNOWN_LABEL, TIMEOUT, ERROR, TRUNCATED (Çıkış sınırına ulaşıldı olarak gösterilir), BACKOFF (Atlandı (bekleme) olarak gösterilir), NO_PROVIDER veya NO_INPUT. |
aircms | Sınıflandırıcı gecikmesi (milisaniye). |
aircti | Sınıflandırıcının girdi token sayısı. |
aircto | Sınıflandırıcının çıktı token sayısı. |
airccm | Sınıflandırıcı maliyeti (mikro USD). |
AI trafik çekmecesi ile trafik detay penceresi, Yönlendirme Sınıflandırıcısı bloğunda sınıflandırıcı kararını (sonuç ve etiket), milisaniye cinsinden Karar süresi değerini ve Sınıflandırıcı maliyeti değerini gösterir.
İzleme çekmecesi Rota sınıflandırıcı bölümünü gösterir. AI izleme açıksa her rotanın sonucunu içeren Yönlendirme kararı paneli de görünür.
Trafik loglarını bir JDBC veritabanına (Oracle, MySQL, PostgreSQL veya MSSQL) yazıyorsanız yükseltmeden önce veritabanınıza uygun ALTER betiğini çalıştırın. Aksi halde bu veritabanına trafik logu ekleme işlemleri başarısız olur.
Oracle, MySQL, PostgreSQL ve SQL Server için ALTER betikleri 2026.10.0 — Log Tablosu ALTER Scriptleri sayfasındadır. Betikler şu kolonları ekler: ai_route_cls_label, ai_route_cls_outcome, ai_route_cls_latency_ms, ai_route_cls_token_in, ai_route_cls_token_out ve ai_route_cls_cost_micro.
Elasticsearch için işlem gerekmez. Başlangıçtaki bir geçiş trafik indeks şablonunu otomatik günceller ve indeks yeni döneme alınır.
İstemci "model" Alanı
İki bağımsız ayar, istemcinin istek gövdesinde gönderdiği model alanıyla gateway'in ne yapacağını belirler. Bu ayarların sonucunda ortaya çıkan değer, istek için etkin model olur — hız limiti, semantik önbellek, maliyet hesaplaması ve trafik logu, istemcinin gönderdiği değerden bağımsız olarak bu modeli kullanır.
Bu ayarları Yönlendirme sekmesinde, hata yolu (failover) bölümü ile bağlantı ayarları arasındaki İstemci "model" alanı kartında bulursunuz. Bir seçenek seçildiği anda kaydedilir; kayıt başarısız olursa seçim eski değerine döner. Kart, istemcinin kendi model alanını hiç göndermediği A2A agent yönlendirme sekmesinde gösterilmez.
İstekte Model Alanı Zaten Varsa
| Seçenek | Davranış |
|---|---|
| İstemcinin modelini kullan | Gateway istemcinin modelini sağlayıcıya gönderir. Sağlayıcının listesindeki bir model açık olmalıdır. Listede olmayan bir model, sağlayıcıda Yalnız listelenen modeller kapalıysa ve model kimliği düz bir ad ise (aşağıya bakın) yine gönderilir. Aksi halde istek HTTP 400 ile reddedilir. |
| Yönlendirme modeliyle üzerine yaz (varsayılan) | Yönlendirmenin seçtiği model istemcinin değerinin yerine geçer. |
| İsteği reddet | model alanı taşıyan istekler HTTP 400 ile reddedilir. |
Sağlayıcının Listesinde Olmayan Modeller
İstemcinin modelini kullan seçiliyken gateway, sağlayıcının listesinde olmayan bir modeli yalnız iki koşul birlikte doğruysa gönderir:
- Sağlayıcıda Yalnız listelenen modeller anahtarı kapalıdır.
- Model kimliği düz bir addır: harf veya rakamla başlar, yalnız harf, rakam ve
._:@+-karakterlerini içerir, en çok 128 karakterdir ve..içermez.
Bir koşul sağlanmazsa gateway isteği HTTP 400 ile reddeder. Listedeki birden fazla modelle eşleşen bir model kimliği de reddedilir. Listede olmayan modellerin fiyatı ve erişim kontrolü yoktur; bu yüzden USD limitleri bunları ölçmez.
Bu kural yalnız birincil hedef için geçerlidir. Failover bacağı, istemcinin modeli bacağın listesinde yoksa kendi modelini korur. Listede olmayan istemci modelini kendi sağlayıcısına göndermez.
İstekte Model Alanı Yoksa
| Seçenek | Davranış |
|---|---|
| Eklemeden bırak (varsayılan) | Gövde model alanı olmadan iletilir. Modeli URL veya deployment'tan çözen sağlayıcılar bu şekilde çalışır. |
| Yönlendirme modelini ekle | Yönlendirmenin seçtiği model gövdeye eklenir. |
| İsteği reddet | model alanı olmayan istekler HTTP 400 ile reddedilir. |
Boş bırakılan değerler önceki davranışı korur: istemci model gönderiyorsa üzerine yazılır, göndermiyorsa eklenmez. Mevcut bir gateway hiçbir değişiklik yapılmadan öncekiyle birebir aynı şekilde çalışmaya devam eder.
- Gemini, Vertex ve Bedrock modeli URL yolunda taşır — etkin model yine de o yolu belirler. Gemini, Vertex ve Bedrock üzerindeki Anthropic modellerinde native gövdeye
modelalanı hiç yazılmaz. Bedrock'taki diğer modeller (Titan, Llama, Mistral, Nova) OpenAI biçiminde iletilmeye devam eder; onlarda bu ayar, gövde için herhangi bir OpenAI uyumlu sağlayıcıdaki gibi geçerlidir. - Azure OpenAI modeli endpoint'te sabitler:
https://<kaynak>.openai.azure.com/openai/deployments/<deployment>biçimindeki bir deployment endpoint'i yanıtı verecek deployment'ı zaten adlandırdığı için, gövdedekimodelalanı gerçekte çağrılan modeli değiştiremez. Bu nedenle İstemcinin modelini kullan orada uygulanmaz — aşağıya bakın. - Anthropic, istemcinin ne gönderdiğinden bağımsız olarak etkin modeli her zaman native istek gövdesine yazar.
Gemini, Vertex ve Bedrock etkin modeli gateway'den alıp URL'e kendisi yazar; bu nedenle atıf ile isteği gerçekte yanıtlayan model her zaman örtüşür. Azure OpenAI deployment endpoint'i istisnadır: deployment, operatörün yapılandırdığı endpoint'te sabittir; dolayısıyla gövdedeki model alanı hangi modelin yanıt vereceğini değiştiremez — yalnızca atfı değiştirebilirdi; yani hız limitinin, kotanın, semantik önbelleğin, maliyet hesabının ve trafik logunun hangi modele yazılacağını.
Bu atfın istemci tarafından kaydırılabilmesi, çağrıyı gerçekte karşılayan deployment yerine daha ucuz bir modelin fiyatıyla faturalanmaya ve sayılmaya yol açardı. Bu nedenle Apinizer böyle bir sağlayıcıda İstemcinin modelini kullan seçeneğini uygulamaz: etkin model yapılandırılmış yönlendirme modeli olarak kalır ve istemcinin değeri için model denetimi çalıştırılmaz (istemcinin modeli hiç çağrılmadığı için sağlayıcının modelleri arasında olmaması da hata değildir). Apinizer'ın Azure'a gönderdiği istek, tıpkı Yönlendirme modeliyle üzerine yaz seçeneğindeki gibi gövdesinde yapılandırılmış yönlendirme modelini taşır; istemcinin gönderdiği değer yalnızca bir ret gerekçesi olmaktan çıkar. Yönlendirme modeliyle üzerine yaz, İsteği reddet ve "model alanı yoksa" eksenindeki tüm seçenekler yukarıda anlatıldığı gibi çalışmaya devam eder.
Failover Bacakları
Bir failover bacağı, her iki ayarı da kendi sağlayıcısının modellerine göre yeniden değerlendirir. İstemcinin modelini kullan seçiliyken istemcinin modeli o bacağın sağlayıcısında yoksa, bacak isteği reddetmek yerine kendi yapılandırılmış modeline döner — modelin sağlayıcıda bulunmaması yalnızca birincil hedef olduğunda isteği doğrudan reddeder.
Kendi modelini tanımlamayan bir bacak, birincil hedefin bu istek için çözdüğü etkin modeli değil, yapılandırılmış yönlendirme modelini devralır. Bu ayrım İstemcinin modelini kullan seçiliyken önem kazanır: istemcinin modeli bir bacakta ancak o bacağın kendi sağlayıcısının modelleri arasında yer alıyorsa kullanılır; aksi halde bacak, istemcinin seçimini hiç sunmamış bir sağlayıcıya taşımak yerine, sağlayıcının verdiği bilinen bir modele döner.
Context Window Taşması
Context window taşması kartı Yönlendirme sekmesinde, İstemci "model" alanı kartının altında bulunur. Kart, istek yönlendirmenin seçtiği modelin context window değerini aşarsa gateway'in ne yapacağını belirler. Kart A2A agent yönlendirme sekmesinde gösterilmez.
Kontrol model kesinleştikten sonra çalışır. Yalnız chat/completions ve responses istekleri kontrol edilir.
Sınır şöyle hesaplanır: modelin context window değeri, eksi isteğin max_completion_tokens, max_tokens veya max_output_tokens değeri, eksi 512 token güvenlik payı. Sonuç 0 veya daha küçükse (küçük bir context window ya da büyük bir çıktı token değeri), hiçbir istek sığmaz: İsteği reddet ve Konuşmayı kısalt seçenekleri isteği reddeder. Apinizer yalnız metni sayar. Görsel, ses ve dosyalar sayılmaz.
Modelin context window değerini Modeller ekranında modelin ayarlarından girin. Context window değeri olmayan model kontrol edilmez. Kartın Bu proxy'deki modeller tablosu bu model için Değer yok, kontrol yapılmaz gösterir.
| Seçenek | Davranış |
|---|---|
| İsteği reddet (varsayılan) | Gateway isteği HTTP 400 ve ERR-311 hata koduyla reddeder. Sağlayıcıyı çağırmaz. Hiç yapılandırılmamış proxy'ler bu seçeneği kullanır. |
| Konuşmayı kısalt | Gateway, istek sığana kadar en eski konuşma turlarını siler. İstek yine sığmazsa gateway isteği reddeder. |
| Sağlayıcıya bırak | Gateway kontrol yapmaz. Sınırı sağlayıcı uygular. |
Reddetme yanıtının varsayılan gövdesi:
{
"error": {
"code": 400,
"message": "Request exceeds the model's context window",
"type": "context_length_exceeded"
}
}
Bu mesajı Hata Mesajları ekranından değiştirebilirsiniz. Trafik logu isteği BLOCKED olarak kaydeder.
Kısaltma Kuralları
- Gateway istemcinin gönderdiği system mesajlarını, son user mesajını ve ondan sonraki her şeyi her zaman korur. Son user mesajında yapılabilecek tek değişiklik, Son user mesajı ayarının belirlediği kısaltmadır (aşağıya bakın).
- Bir araç çağrısı ve sonucu birlikte silinir.
- Silme en eski turdan başlar. Tur, bir user mesajı ile ondan sonraki assistant ve araç mesajlarıdır.
- Korunacak son tur sayısı, gateway'in hiç silmeyeceği son tur sayısını belirler. Değer 0 ile 50 arasındadır. Varsayılan 0'dır.
- RAG ile eklenen bağlam için iki seçenek vardır. Koru (varsayılan) gateway'in eklediği bağlamı silmez. Sondan kısalt, tur silmek yetmezse bağlamın en az ilgili son parçalarını çıkarır.
- Son user mesajı için iki seçenek vardır. Koru (varsayılan) son user mesajını hiç değiştirmez. Ortadan kısalt, yukarıdaki adımlar yetmezse mesaj metninin ortasını çıkarır.
Gateway adımları şu sırayla uygular:
- En eski konuşma turlarını siler.
- RAG ile eklenen bağlam Sondan kısalt ise RAG bağlamının sonunu keser.
- Son user mesajı Ortadan kısalt ise ve istek hâlâ sığmıyorsa son user mesajının ortasını çıkarır.
Gateway son user mesajını kısalttığında metnin başını ve sonunu korur. Çıkarılan kısmın yerine şu notu koyar: [... N characters removed by the gateway to fit the model context window ...]. Böylece model içeriğin eksik olduğunu görür. Gateway isteği not ile birlikte yeniden ölçer. İstek yine sığmazsa gateway isteği HTTP 400 ile reddeder.
Ortadan kısalt kuralları:
- Son user mesajı birden çok metin parçası içerebilir (örneğin Chat
contentdizisindeki metin parçaları veya Responses girdisindekiinput_textparçaları). Gateway önce en büyük metin parçasını keser. Bu yetmezse sonraki parçaları da keser. - Her metin parçası kendi metninin en fazla yarısını kaybeder. Karakterler Unicode code point olarak sayılır. Böylece her parça başını ve sonunu korur, mesajın tamamı da metninin en fazla yarısını kaybeder. Kesilen her parçaya ayrı bir not konur.
- Daha fazlası gerekirse gateway isteği reddeder.
- Yakınlarda satır sonu varsa kesim satır sonuna kayar.
- Gateway yalnızca metni keser. Görsel, ses, dosya, araç çağrısı ve araç sonucuna hiç dokunmaz.
- Chat Completions
messages[].content(metin ya da metin parçaları) ve Responsesinput(metin ya da user girdi öğeleri) desteklenir. - Koru olarak ayarlı RAG bağlamı hiç kesilmez. Proxy'de birden fazla RAG Injection politikası çalışıyorsa gateway korunan bağlamı mesajda bulamaz. Bu durumda hiçbir şey kesmez ve isteği reddeder.
Tipik kullanım, tek mesaja yapıştırılmış bir dosyadır. Yapıştırılan JSON, XML veya kod çıkarılan kısımda bozulabilir. Yanıt, çıkarılan içeriği dikkate alamaz. Bir belgenin tamamını analiz etmek için istemci içeriği birkaç isteğe bölmelidir.
Kısaltılan isteğin yanıtında X-Apinizer-AI-Truncated header'ı bulunur. Header, silinen mesaj sayısını taşır. Yalnızca son user mesajı kısaltıldıysa değer 0 olur. Trafik logu da isteği işaretler.
Örnekle gör düğmesi yan paneli açar. Panel, kayıtlı kuralları örnek bir konuşmaya uygular. Her mesajda turu ve bir rozet görünür: Her zaman korunur (sistem mesajları ve son tur), Kalır, Korunur (ayar) (Korunacak son tur sayısı nedeniyle), Silinir, Sondan kısaltılır (RAG bağlamı) veya Ortadan kısaltılır (son user mesajı). Metindeki işaret token'ların nereden kesildiğini, token sayısı ise önce → sonra değerini gösterir.
Failover ve Bilinen Sınırlar
- Yönlendirmenin seçtiği model belirleyicidir. Failover sırasında gateway, context window değeri isteği almayan yedek modeli atlar.
- A2A proxy'lerine giden istekler kontrol edilmez.
- Token Rate Limit politikası daha ucuz bir modele geçerse gateway isteği yeniden kontrol etmez.
Token Rate Limit politikasının istek başına token sınırı için bkz. Token Rate Limit.
Bağlantı ve İletim Ayarları
Bu kartlar, LLM Gateway'in ilettiği her isteğe uygulanır; yönlendirme kararının bir dalına değil. Her değerin hangi istek türüne uygulandığı grup başlığında yazar: Tüm istekler, Tek seferlik istekler veya Streaming istekleri. Her kartın kendi Yapılandır çekmecesi vardır: Bağlantı çekmecesi zaman aşımlarını, tekrar deneme sayısını ve bağlantı havuzunu; Streaming çekmecesi akış sınırlarını içerir. Bir değer yalnız bir yerde düzenlenir.
Bağlantı Kartı
| Alan | Uygulandığı istekler | Açıklama |
|---|---|---|
| Bağlantı Zaman Aşımı (saniye) | Tüm istekler | LLM sağlayıcısına bağlantı kurma (TCP ve TLS) için beklenen en uzun süre. Aralık 1 ile 300. Varsayılan 10. |
| Yanıt Zaman Aşımı (saniye) | Tek seferlik istekler | Streaming olmayan istekte sağlayıcının yanıtı için beklenen en uzun süre. Aralık 1 ile 3600. Varsayılan 60. Alanı boş bırakırsanız gateway varsayılan 60 saniyeyi kullanır. Boş bir alanı kaydettikten hemen sonra kart 60 (varsayılan) gösterir. |
| Tekrar Deneme Sayısı | Tek seferlik istekler | Geçici bir bağlantı hatasından sonra isteğin kaç kez tekrar deneneceği. Aralık 0 ile 10. Varsayılan 0. Streaming istekleri tekrar denenmez. |
Bağlantı zaman aşımı eskiden yalnız streaming bağlantısını sınırlıyordu; tek seferlik isteğin bağlantısı yanıt zaman aşımına bağlıydı. Şimdi bağlantı zaman aşımı iki istek türünün bağlantısını da sınırlar, yanıt zaman aşımı ise yalnız yanıtın beklenmesini sınırlar.
Bağlantı Havuzu
Aynı karttaki Bağlantı havuzu grubu, gateway'in LLM sağlayıcısına açtığı bağlantıları nasıl yeniden kullanacağını belirler. Gateway havuzu LLM Gateway'i deploy ettiğinizde oluşturur. Havuz streaming isteklerine uygulanır.
| Seçenek | Davranış |
|---|---|
| Genel (varsayılan) | LLM Gateway kendi havuzunu kullanır. Havuzun boyutu ve boşta kalma süresi AI Ayarları'ndaki varsayılanlardan gelir. |
| Özel | LLM Gateway kendi havuzunu, Provider başına açık tutulan bağlantı (aralık 1 ile 1000, varsayılan 8) ve Kullanılmayan bağlantıyı kapatma süresi (saniye) (aralık 1 ile 3600, varsayılan 4) alanlarına girdiğiniz değerlerle kullanır. |
| Yok | Havuz kullanılmaz. Her istek yeni bir bağlantı açar ve bağlantı istek bitince kapanır. Bir provider girişinde provider'a özel havuz ayarı varsa bu kural o provider için geçerli olmaz. |
- Provider başına açık tutulan bağlantı, gateway'in her LLM sağlayıcısına ayrı uygulanır. Yoğun bir sağlayıcı, başka bir sağlayıcının (örneğin failover sağlayıcısının) hazır bağlantılarını bellekten çıkarmaz.
- Boyut yalnız yeniden kullanım için açık tutulan boşta bağlantıları sınırlar. Eşzamanlı istek sayısını sınırlamaz ve istek bağlantı beklemez.
- Kullanılmayan bağlantıyı kapatma süresi (saniye) değerini sağlayıcının kendi boşta kapatma süresinden kısa tutun. Örneğin vLLM ve diğer uvicorn sunucuları boşta bağlantıyı 5 saniye sonra kapatır. Gateway bağlantıyı daha uzun tutarsa isteği sağlayıcının zaten kapattığı bir bağlantıya gönderebilir. Bu durumda streaming isteği 502 hatasıyla biter. Gateway streaming isteğini yalnız şu durumda yeniden gönderir: istek yeniden kullanılan havuz bağlantısında gönderilirken yazma veya flush hatası oluştu. Yazma zaman aşımı ve kesinti (interrupt) gönderim hatası sayılmaz; bu durumlarda istek yeniden gönderilmez. İstek gönderildiyse ve hata yanıt okunurken oluştuysa (yanıt başlığı gelmeden önce olsa bile) gateway isteği yeniden göndermez. Sağlayıcı isteği çalıştırıyor olabilir; istemci 502 alır.
- Bilinen sınırlar: HTTP/2'de bağlantı aynı anda koparsa son çerçeve gittikten sonra da flush hatası bildirilebilir. HTTPS'te nadir bir TLS durumu da (veri sokete verildikten sonra TLS KeyUpdate) veri gittikten sonra gönderim hatası bildirebilir. Bu nadir durumlarda istek sağlayıcıya iki kez ulaşabilir.
- Seçenek Genel olduğunda Yönlendirme sekmesindeki Bağlantı kartı boyut ve süre için AI Ayarları varsayılanı yazısını gösterir.
Genel varsayılanları Sistem Ayarları ve Limitler ekranında, AI Gateway sekmesindeki Bağlantı Havuzu Varsayılanları bölümünde bulursunuz. Lisansınız AI Gateway'i içeriyorsa sekme görünür. Yalnız sistem yöneticisi kaydedebilir.
| Alan | Aralık | Varsayılan |
|---|---|---|
| Provider Başına Boşta Bağlantı | 1 ile 1000 | 64 |
| Boşta Bağlantı Zaman Aşımı (sn) | 1 ile 3600 | 4 |
AI Ayarları'ndaki bir değişiklik, LLM Gateway'e bir sonraki deploy'unda ulaşır. Genel seçeneğini kullanan gateway'in havuzu o zaman yeniden kurulur. Özel seçeneğini kullanan gateway kendi değerlerini korur.
Provider'a Özel Havuz Ayarı
Primary (havuz üyesi), Failover zinciri ve Koşullu rota pencerelerinde Bu provider için bağlantı havuzu (isteğe bağlı) paneli bulunur. Panel, seçtiğiniz provider için havuz değerlerini ayrı belirler.
| Alan | Aralık |
|---|---|
| Provider başına açık tutulan bağlantı | 1 ile 1000 |
| Kullanılmayan bağlantıyı kapatma süresi (saniye) | 1 ile 3600 |
- Alan boşsa routing düzeyindeki ayar geçerlidir.
- Gateway her provider için tek havuz tutar. Aynı provider birden çok girişte farklı değerle ayarlıysa her alan için en büyük değer kullanılır. Pencerede bu durumda uyarı simgesi görünür.
- Routing düzeyinde Yok seçili olsa bile bir giriş bu alanlardan birini doldurursa gateway o provider için havuz açar. Alanı boş bırakılan diğer değer önce routing düzeyinde kayıtlı değeri alır (özel havuz boyutu veya boşta bağlantı süresi). Routing düzeyinde değer yoksa AI Ayarları varsayılanını alır. Ekran Yok seçildiğinde routing düzeyindeki değerleri temizler; bu yüzden ekrandan kaydedilen routing için sonuç AI Ayarları varsayılanıdır. APIops ile yazılan bir routing Yok altında da routing düzeyinde değer taşıyabilir. O zaman bu değerler kullanılır.
- Panel yalnız streaming isteklerine uygulanır.
Streaming Kartı
| Alan | Uygulandığı istekler | Açıklama |
|---|---|---|
| Streaming (SSE) anahtarı | Streaming istekleri | Gateway için streaming'i açar. İstemcinin stream alanıyla nasıl birleştiği aşağ ıdaki İstemci "stream" alanı ayarına bağlıdır. |
| Akış Boşta Kalma Zaman Aşımı (saniye) | Streaming istekleri | Sağlayıcı bu süre boyunca yeni parça göndermezse gateway akışı kapatır. Aralık 1 ile 3600. Varsayılan 120. |
| Maks. Yanıt Bayt | Streaming istekleri | Yanıt bu boyuta ulaşınca gateway akışı keser. 0 sınırsız demektir. |
| Maks. Parça Sayısı | Streaming istekleri | Bu sayıda parçadan sonra gateway akışı kapatır. 0 sınırsız demektir. |
İstemci "stream" Alanı
Bu ayar, istemcinin istek gövdesinde gönderdiği stream değeriyle gateway'in ne yapacağını belirler. Streaming kartındadır. Bir seçenek seçildiği anda kaydedilir; kayıt başarısız olursa seçim eski değerine döner. Yalnız okuma yetkisi olan kullanıcı seçili değeri özet olarak görür. Kart, A2A agent yönlendirme sekmesinde gösterilmez.
| Seçenek | Davranış |
|---|---|
| İstemcinin değerini kullan | stream: true streaming yanıt açar, stream: false tek seferlik yanıt döner. stream alanı olmayan istek Streaming (SSE) anahtarını izler. |
| Proxy ayarıyla üzerine yaz | Her istekte Streaming (SSE) anahtarı belirler. İstemcinin değeri değiştirilir. Anahtar kapalıyken stream: true gönderen istek de tek seferlik yanıt alır. |
- Yeni bir LLM Gateway İstemcinin değerini kullan seçeneğiyle başlar. Kayıtlı değeri olmayan mevcut bir LLM Gateway öncekiyle birebir aynı şekilde Proxy ayarıyla üzerine yaz gibi çalışır.
- Ayar sohbet tamamlama ve Responses isteklerine uygulanır. Embedding, ses ve görsel istekleri proxy ayarını korur.
- İstemci streaming'i yalnız LLM Gateway'de yalnızca tek seferlik yanıtta çalışan bir politika yoksa açabilir. Böyle bir politika varsa ve istemci
stream: truegönderirse proxy ayarı uygulanır ve istemci tek seferlik yanıt alır. Bu politikalar şunlardır: Dayanaklılık Koruyucu; yanıt yönündeki MCP Çağrısı (LLM) ve A2A Çağrısı (LLM); maskelenen değerleri satır içinde geri yükleyen veya yanıt yönünde kodlanmış içeriği çözen PII Maskeleme; ikisi de arabellek kipinde olan Konu Koruyucu ve DLP Koruyucu; yanıt yönünde harici guardrail motoru kullanan DLP Koruyucu, Konu Koruyucu veya PII Maskeleme. İstemci streaming'i her zaman kapatabilir. - İstemcinin değerini kullan seçiliyken semantik önbellek, streaming ve tek seferlik istekler için ayrı kayıt tutar.
Bir LLM Gateway'in tek seferlik yanıtı istemciye Content-Type başlığıyla ulaşır. Önceki sürümler yanıtı bu başlık olmadan gönderebiliyordu. Bu, semantik önbellekten gelen yanıt için de geçerlidir. Yalnız sağlayıcının kullandığı başlıklar iletilmez.
LLM Sağlayıcısı İçin Sertifika Güveni
Ağ geçidi, LLM sağlayıcısının sertifikasını Apinizer sertifika deposundaki sertifikalarla doğrular. Bu, akışsız ve akışlı (streaming) isteklerin ikisi için geçerlidir. Yönlendirme mTLS kullanmıyorsa ve SSL Doğrulamayı Atla kapalıysa uygulanır. Ağ geçidi, Yönetim → Gizlilik Yönetimi → Sertifikalar ekranında LLM Gateway'in ortamına atadığınız sertifikaları kullanır.
- Eklediğiniz veya kaldırdığınız sertifika yeni bağlantılara hemen uygulanır. LLM Gateway'i yeniden deploy etmeniz gerekmez. API proxy yönlendirmesinde de davranış aynıdır.
- Yönlendirme mTLS kullanıyorsa mTLS yapılandırmasının güven ayarları geçerlidir.
- Ana makine adı (hostname) doğrulaması değişmemiştir.
Bu hata, sağlayıcının sertifika zincirinin güvenilir olmadığını gösterir. Sertifikayı veren sertifika otoritesini (veya sertifikanın kendisini) LLM Gateway'in ortamı için sertifika deposuna ekleyin. Bkz. SSL/TLS Sertifika Sorunları.
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.
Tüm Hedefler Başarısız Olunca Yanıt Header'ları
Birincil ve tüm yedek hedefler başarısız olunca istemci bir hata yanıtı alır. Yanıtın durum kodu ve gövdesi Hata Mesajı ayarlarınızı izler. Apinizer ayrıca şu yanıt header'larını ekler:
| Header | Değer | Ne zaman gönderilir |
|---|---|---|
X-Apinizer-AI-Exhausted | true | Akışsız (non-streaming) bir istek için zincir tükendiğinde. |
X-Apinizer-AI-Exhausted-Reason | Bir neden kodu (aşağıya bakın) | X-Apinizer-AI-Exhausted ile birlikte, Apinizer son başarısız denemeyi sınıflandırabildiğinde. Sınıflandıramazsa yalnız X-Apinizer-AI-Exhausted gönderilir. |
Neden kodu yalnız son başarısız denemeyi anlatır:
| Neden kodu | Anlamı |
|---|---|
connect_timeout | Sağlayıcıyla bağlantı zamanında açılmadı. |
read_timeout | Sağlayıcı zamanında yanıt vermedi. |
dns_error | Sağlayıcı ana makine adı çözülemedi. |
tls_error | Sağlayıcıyla TLS el sıkışması başarısız oldu. |
connection_refused | Sağlayıcı bağlantıyı reddetti. |
transport_error | Başka bir ağ hatası. |
upstream_status | Sağlayıcı hata durum koduyla yanıt verdi. |
Header'lar sağlayıcı mesajı, adresi veya gövdesi taşımaz. İstemcinin aldığı hata gövdesi ve durum kodu değişmez. Apinizer bu iki header'ı akışlı (streaming) istekte göndermez.
Sağlayıcıya yapılan tüm denemeler (birincil, tekrar denemeleri ve failover) TLS hatasıyla biterse trafik kaydı POLICY_ROUTING_SSLHANDSHAKE hata türünü yazar. Tüm denemeler sertifikanın süresi dolduğu veya henüz geçerli olmadığı için başarısız olduysa POLICY_ROUTING_SSLEXPIRED yazar. El sıkışma sırasında kesilen TLS bağlantısı SSL hatası olarak kaydedilmez. Hatalar karışıksa (örneğin TLS ve zaman aşımı) hata türü POLICY_ROUTING_AI_PROVIDER_EXHAUSTED olarak kalır. İstemci yanıtı, tls_error neden header'ı dahil, değişmez.
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: Yönlendirme 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.
Varsayılan Hedef Grubu çekmecesini ekrandan kaydettiğinizde ekran, proxy düzeyindeki eski tek varsayılan sağlayıcıyı ve modeli (Tek varsayılan rozetiyle görünen hedef) temizler. Böylece havuz tek varsayılan hedef olur; son üyeyi kaldırırsanız grup boş kalır ve yönlendirme failover zincirine gider. Koşullu rota, havuz üyesi veya failover satırında sağlayıcı ya da model boşsa ve temizlenen tek varsayılan hedefi kullanıyorsa kayıt reddedilir: o rotaya ya da satıra kendi modelini verin. APIops ile yazılan bir routing tek varsayılan hedefi taşımaya devam edebilir. O zaman yukarıda anlatıldığı gibi kullanılır.
| 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 modelin 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. En düşük maliyet ve En düşük gecikme stratejileri yalnızca havuzda 2 veya daha fazla üye varken devreye girer; daha azıysa havuz sessizce Sıralı (round-robin) dağıtımı kullanır (bu durum geçerliyken yönlendirme ekranında bir uyarı gösterilir).
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.
Havuzdaki Diğer Hedefleri Deneme
Havuzdaki diğer hedefleri dene anahtarı Hata yolu (Failover) panelindedir. Seçilen havuz hedefi başarısız olunca ne olacağını belirler. Varsayılan Hedef Grubu'na ve tüm koşullu rota havuzlarına uygulanır.
| Ayar | Deneme sırası |
|---|---|
| Açık (varsayılan) | Seçilen hedef, ardından aynı hedefte tekrar deneme (varsa), ardından havuzdaki diğer hedefler, ardından Failover zinciri. |
| Kapalı | Seçilen hedef, ardından aynı hedefte tekrar deneme (varsa), ardından doğrudan Failover zinciri. Zincir boşsa istek hata döner. |
Anahtar hiç kaydedilmediyse açık kabul edilir.
Apinizer şu durumlarda sonraki adıma geçer: bağlantı hatası, zaman aşımı, failover durum kodu veya varsayılan olarak 5xx, 408 ve 429 yanıtı. Bu liste değişmedi. Model erişim reddi ve 4xx istemci hatası sonraki adıma geçirmez. Bu sıra streaming olmayan isteklerde uygulanır. Streaming istekte hata olunca başka hedefe geçilmez; istemci hatayı alır.
Aynı hedefte tekrar deneme ayrı bir ayardır.
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ı modelde tanımlı olmayan bir hedefin maliyet sınırı kontrolü yapılamaz; bu durumda hedef atlanmadan denenmeye devam eder.
Limit Planı ya da Token Rate Limit politikası bir limit dolduğunda Yedeğe geç aşım aksiyonunu seçebilirsiniz. İstek yedek hedefe gider. Yönlendirmede yedek sağlayıcı yoksa istek 429 ile reddedilir; bütçesi dolan birincil hedefe gönderilmez. Ucuz Modele Düş aksiyonu isteği daha düşük maliyetli bir modele yönlendirir. Ayrıntı için bkz. Token Rate Limit Politikası ve Limit Planları.
Failover Zincirinin Alanları
Failover zinciri (sağlayıcı/model listesi, strateji, maliyet ve durum kodu ayarları), LLM Gateway'in Yönlendirme sekmesinde satır satır (inline) tanımlanır ve şu bilgileri içerir:
| Alan | Açıklama |
|---|---|
| Yedekleme Stratejisi | Zincirin nasıl işleneceği — aşağıdaki tablo |
| Failover Kayıtları | Sırayla denenecek tanımlar. Ekranda her kayıt için LLM sağlayıcı ve model seçersiniz; isterseniz zaman aşımı, maksimum maliyet ve (Round Robin için) ağırlık da girebilirsiniz |
| Tetikleyici durum kodları | Failover'ı tetikleyecek HTTP durum kodları (boş bırakılırsa varsayılan olarak 5xx / 408 / 429 kullanılır) |
| Adım başına deneme | Her failover kaydında yapılan deneme sayısı (varsayılan 1) |
| Koşullu Gecikme Eşiği (ms) | Yalnızca Koşullu stratejide okunur |
Yedekleme Stratejisi 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 (gecikme/hata) | Durum kodu tetikleyicilerine ek olarak, başarılı bir yanıt gecikme eşiğinden yavaşsa da failover devreye girer. Daha hızlı yanıt veren başka kayıt çıkmazsa yavaş yanıt döndürülür |
| Katı Öncelik | Bir üst kayda ulaşılamıyorsa (bağlantı hatası ya da açık devre) alt kayda geçilir; kayıt bir hata yanıtı verdiyse alt kayda geçilmez ve yanıt olduğu gibi döner (örn. veri yerleşimi zorunluluğu olan senaryolar) |
| Round Robin (yük dağıtımı) | Failover denemeleri kayıtlar arasında, kayıtların ağırlığına göre sırayla 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
LLM Gateway'in Yönlendirme 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.
Bu maliyet/kota uyarısı hem bu panelde hem de açılan Test Console diyaloğunda gösterilir.
LLM Gateway'in Geliştir sekmesinde de aynı kısayol vardır. Bu sekmedeki adres listesi her ortam için bir satır gösterir; proxy'nin deploy edildiği her ortamın adresinin yanında Endpoint'i Test Et düğmesi bulunur. Düğme, aynı önceden doldurulmuş isteği Uç Noktayı Test Et penceresinde açar ve test çalıştırma yetkisi olan kullanıcılara görünür. Pencerede aynı uyarı gösterilir: çağrı gerçek LLM sağlayıcısına gider ve maliyet/kota doğurur; düşük tutmak için minimal bir istek (max_tokens: 16) önceden doldurulur.
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.
Yanıt yönünde bir Politika Grubu içine konan MCP veya A2A Çağrı politikası, doğrudan proxy'ye konan politika gibi döngüye katılır. Apinizer, grup etkinse ve koşulu sağlanıyorsa gruba girer. Araç sonuçları proxy'deki Kişisel Veri Maskeleme kurallarıyla maskelenir; bkz. Araç Çağırma Döngüsünde Araç Sonu çları.