> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/ai-gateway/routing-resilience.md). # Routing ve dayanıklılık AI Gateway, istenen modeli sıralı bir hedef listesine çözümler, herhangi bir sağlayıcı çağrısından önce consumer politikasını uygular ve uygun hata durumlarında sonraki hedefi dener. ## Hedef seçimi Etkin bir `model_route` kaydında `strategy` alanını ayarlayın. | Strateji | Seçim davranışı | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `ordered` | Hedef dizisindeki sırayı kullanır | | `priority` | Sayısal `priority` değeri en yüksek hedefi önce kullanır; eşit değerlerde dizi sırası korunur | | `weighted` | Durum bilgili ağırlıklı round-robin ilk hedefi belirler, ardından kalan yedek hedef sırasındaki tekrarları kaldırır | | `least_latency` | Önce canlı sağlayıcı/model gecikme EWMA değeri en düşük hedefi; ardından yapılandırılmış gecikme, öncelik ve dizi sırasını kullanır | | `semantic` | Prompt metniyle hedef ipuçları arasındaki hash-vektör benzerliğini kullanır; hiçbir hedef puan almazsa dizi sırasını uygular | `weighted_round_robin`, `weighted_rr`, `latency`, `least_latent`, `semantic_routing` ve `semantic_router` alias'ları da kabul edilir. `latency_ewma_alpha` değeri 0'dan büyük ve en fazla 1 olmalıdır. Çalışma zamanı varsayılan olarak 0,3 kullanır ve canlı değerleri 0,01-1,0 aralığında tutar. {% hint style="info" %} `priority` stratejisinde büyük sayısal değerler önce seçilir. Stratejiyi etkinleştirmeden önce her hedefin değerini gözden geçirin. {% endhint %} Semantik yönlendirme, yapılandırılmış anahtar kelimeler ve ipuçları üzerinde deterministik hash-vektör benzerliği kullanır. Vektör boyutu 8-512 aralığında tutulur. ## Yedek hedefe geçiş kuralları Yerleşik olarak yeniden denenebilir sağlayıcı durum kodları şunlardır: ``` 408, 409, 425, 429, 500, 502, 503, 504 ``` Aktarım hatalarında sonraki hedef denenir. Başarılı durum koduyla gelen fakat nesne olmayan veya geçerli JSON içermeyen gövde `provider_malformed_response` olarak sınıflandırılır ve sonraki hedefe geçilebilir. Geçerli, yeniden denenmeyen bir sağlayıcı hatası kendi durum kodu ve ayrıştırılmış gövdesiyle hemen döndürülür. Her yapılandırılmış hedef, tek bir istekte en fazla bir kez denenir. Hedeflerin tükenmesine aktarım veya hatalı response hataları neden olursa Kangal, güvenli bir özet ve deneme meta verisiyle genellikle `502` gateway hatası döndürür. Son hedef geçerli bir sağlayıcı HTTP hatası döndürürse Kangal bu durum kodunu ve ayrıştırılmış gövdeyi istemciye iletebilir. Hatalı biçimdeki sağlayıcı yanıtlarının gövdeleri istemciye açılmaz. Akışlı yanıtta sağlayıcı bağlantısı kurulurken yedek hedefe geçilebilir. Yanıt header'ları gönderilip veri akışı başladıktan sonraki hata `provider_stream_error` olarak kaydedilir; istemci çıktısının sırasını ve bütünlüğünü korumak için aynı istek kapsamında yeni hedef başlatılmaz. ## Consumer politikası önceliği Politika araması belirli bir sırayla yapılır: 1. Tam `consumer_id` eşleşmesine sahip politika. 2. Consumer'ın kayıtlı grup sırasındaki ilk eşleşen politika. 3. Adı `default` veya `*` olan consumer politikası. 4. Hiçbiri eşleşmezse yapay zekâ politikası uygulanmaz. Örnek varsayılan politika: ```json { "tenant_id": "acme", "kind": "policy", "name": "default", "enabled": true, "config": { "allowed_models": ["support", "gpt-4.1-*"], "denied_models": ["*-preview"], "token_budget": 250000, "rate_limit": 60, "rate_window_seconds": 60 } } ``` Grup politikası için `config` içinde `consumer_group` veya `group` ayarlayın. Belirli bir consumer politikası için `consumer_id` kullanın veya kayıt adını consumer ID'si olarak belirleyin. Model desenleri tam değerleri, `*` değerini ve sonunda `*` bulunan önekleri destekler. ## Bütçe ve rate-limit davranışı * `token_budget`, seçilen politika için tahmini kullanım üst sınırını belirler. * İstek ön kontrolünde yaklaşık olarak her dört prompt karakteri için bir token ile `max_tokens` veya `max_completion_tokens` toplamı kullanılır. * Başarılı yanıtın veya akışın son kullanım olayının ardından sağlayıcının bildirdiği nihai kullanım eklenir. * `rate_limit`, seçilen politika konusu ve istenen model bazında kayan istek penceresinde uygulanır. * Bütçenin veya rate-limit değerinin sıfır olması ilgili kontrolü devre dışı bırakır. ## Tam eşleşmeli ve semantik önbellek Önbellek, akışsız yanıtlarda kullanılır. Tam eşleşme anahtarları varsayılan olarak istek modelini, mesajları, temperature ve top-p değerlerini, maksimum token alanlarını, stop değerlerini ve tenant/consumer kapsamını içerir. Akışlı istekler `X-Kangal-AI-Cache: bypass` döndürür. ```json { "tenant_id": "acme", "kind": "cache", "name": "default", "enabled": true, "config": { "enabled": true, "mode": "hybrid", "ttl_seconds": 300, "similarity_threshold": 0.86, "vary_by_tenant": true, "vary_by_consumer": true, "vector_backend": "mongodb_atlas", "vector_index_name": "ai_gateway_semantic_cache", "vector_path": "embedding", "vector_dimensions": 64, "vector_num_candidates": 100, "search_limit": 50, "embedding_provider": "openai-primary", "embedding_model": "text-embedding-3-small", "embedding_fail_open": true, "allow_scan_fallback": false } } ``` Desteklenen vektör backend alias'ları `memory`, `scan`, `mongo_scan`, `auto`, `atlas`, `mongodb_atlas`, `mongodb_vector` ve `native` değerleridir. Arama limiti 1-100 aralığında, vektör boyutu ise çalışma zamanında 8-512 aralığında tutulur. Admin API pozitif vektör boyutu değerlerini kabul eder. Embedding seçenekleri: * Sağlayıcı yapılandırılmadığında yerleşik deterministik hash vectorizer. * Adlandırılmış bir yapay zekâ sağlayıcısı ve `embedding_model`. * Sağlayıcı adı veya genel HTTPS `base_url` değeriyle birlikte model, yol, credential/referans ve timeout içeren bir nesne. * Azure OpenAI embedding yol dönüşümü. Haricî embedding başarısız olduğunda `embedding_fail_open: true` ise sağlayıcı isteği semantik arama veya yazma yapılmadan devam eder. Değer `false` ise önbellek embedding hatası yapay zekâ isteğini de başarısız kılar. Atlas kullanırken `ai_gateway_semantic_cache` üzerinde uyumlu bir indeks oluşturun. `allow_scan_fallback: false` ayarında vektör aramasının bulunamaması veya uyumsuz olması tarama başlatmak yerine isteği başarısız kılar. ## Dayanıklılık iş akışı 1. Birbirinden bağımsız kimlik doğrulaması yapılan iki sağlayıcı yapılandırın. 2. Genel alias'ı açık upstream modellerine eşleyin. 3. `ordered` stratejisi ve 20-60 saniyelik sağlayıcı timeout değeriyle başlayın. 4. Sağlayıcı sandbox'ında yeniden denenebilir durum kodu, timeout, hatalı yanıt ve tüm hedeflerin başarısız olması senaryolarını çalıştırın. 5. `X-Kangal-AI-Fallback`, yanıt deneme listesi ve telemetriyi doğrulayın. 6. Gerçek trafik temsili EWMA gözlemleri ürettikten sonra `least_latency` stratejisini etkinleştirin. 7. Tenant/consumer kapsamını ve production vektör indeksini doğruladıktan sonra semantik önbelleği etkinleştirin. ## Sorun giderme | Belirti | Neden veya işlem | | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Yedek hedefe geçilmiyor | İlk hata yeniden denenebilir değildir, yalnızca bir hedef vardır veya akış çıktı başladıktan sonra kesilmiştir | | `priority` stratejisinde yanlış sağlayıcı seçiliyor | Büyük sayısal öncelik değerinin önce seçildiğini doğrulayın | | Ağırlıklı trafik dağılımı düzensiz görünüyor | Ağırlık, durumsuz rastgele dağılımı değil dönen ilk denemeyi belirler; daha büyük bir örneklem inceleyin | | `least_latency` yapılandırılmış değerleri kullanmıyor | İlk gözlemden sonra canlı EWMA önceliklidir | | Consumer'lar arasında cache miss oluşuyor | `vary_by_consumer` varsayılan olarak `true` değerindedir | | Embedding sırasında önbellek `502`/`503` döndürüyor | Fail-closed embedding ayarını veya sağlayıcı/indeks yapılandırmasını kontrol edin | | Akış gecikmesi belirgin biçimde artıyor | Yanıt koruma kuralları SSE gövdesinin tamamını göndermeden önce denetler | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/tr/ai-gateway/routing-resilience.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.