> 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/providers-models.md). # Provider ve model AI Gateway çalışma zamanı yapılandırması, doğrulanmış tek bir `tenant_id + gateway_id` kapsamında kayıtlar hâlinde tutulur. Her kayıt şu ortak alanlara sahiptir: | Alan | Kurallar | | ------------- | ------------------------------------------------------------------------------------- | | `tenant_id` | Oluşturma sırasında zorunludur; tenant dışı değerler reddedilir | | `kind` | `provider`, `model_route`, `policy`, `pricing`, `guardrail`, `redaction` veya `cache` | | `name` | Zorunludur, 1-120 karakter olmalıdır; tür ve kapsam içinde benzersizdir | | `enabled` | Varsayılan değeri `true` değeridir | | `config` | Türe özel JSON nesnesidir | | `description` | İsteğe bağlı operatör açıklamasıdır | | `labels` | İsteğe bağlı JSON meta verisidir; belgelenmedikçe yorumlanmaz | ## Sağlayıcı alanları Bağımsız kimlik doğrulaması yapılan her upstream için bir `provider` kaydı oluşturun. | `config` alanı | Davranış | | --------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `base_url` | Zorunludur. Çalışma zamanı genel bir HTTPS hedefi gerektirir ve yönlendirmeleri reddeder | | `provider_type` veya `type` | `openai`, `openai_compatible`, `azure_openai` veya `anthropic` | | `models` | Açık bir model rotası eşleşmediğinde kullanılan, isteğe bağlı tam eşleşme veya sonu `*` ile biten üyelik desenleri | | `api_key` | Düz metin girdi kabul edilir, saklanırken şifrelenir ve okumalarda redakte edilir | | `api_key_ref` | Önerilen `vault://...` referansı; `secret_ref` ve `vault_ref` de aynı amaçla kullanılabilir | | `api_key_env` | Ortam değişkeni adı; çalışma zamanında açıkça izin verilmesi gerekir | | `headers` | Ek upstream header'larıdır. Değerler gizli bilgi içerebilen alanlar olarak işlenir | | `chat_completions_path` | Varsayılan değeri `/chat/completions` yoludur | | `embeddings_path` | Varsayılan değeri `/embeddings` yoludur; haricî önbellek embedding'lerinde kullanılır | | `timeout_seconds` | Negatif olmayan istek timeout değeri; varsayılan 60 saniyedir | | `prompt_cost_per_1k` | Negatif olmayan girdi token fiyatıdır | | `completion_cost_per_1k` | Negatif olmayan çıktı token fiyatıdır | | `api_version` | Azure OpenAI `api-version` sorgu değeridir | | `anthropic_version` | Anthropic header'ıdır; varsayılan değeri `2023-06-01` değeridir | Örnek: ```bash curl -sS -X POST \ "$KANGAL_ADMIN_URL/admin/gateways/$GATEWAY_ID/ai-gateway/configs" \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H 'Content-Type: application/json' \ -d "{ \"tenant_id\": \"$TENANT_ID\", \"kind\": \"provider\", \"name\": \"openai-primary\", \"enabled\": true, \"description\": \"Primary public OpenAI endpoint\", \"config\": { \"provider_type\": \"openai\", \"base_url\": \"https://api.openai.com/v1\", \"models\": [\"gpt-4.1*\"], \"api_key_ref\": \"vault://ai/openai#api_key\", \"timeout_seconds\": 45 } }" ``` ## Sağlayıcı davranışı | Tür | Dönüştürme ve kimlik doğrulama | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `openai` / `openai_compatible` | OpenAI biçimindeki payload'ı `Authorization: Bearer ...` ile `{base_url}/{chat_completions_path}` adresine gönderir | | `azure_openai` | `/openai/deployments/{deployment}/chat/completions` yolunu kullanır, hedef modeli deployment yoluna yerleştirir, gövdeden `model` alanını kaldırır ve `api-key` gönderir | | `anthropic` | Varsayılan olarak `/v1/messages` yolunu kullanır; system/user/assistant mesajlarını sağlayıcı için dönüştürür ve `x-api-key` gönderir | Anthropic streaming sağlayıcıya özgü biçimi korur. Yalnızca streaming olmayan Anthropic payload'ları OpenAI sohbet tamamlama response biçimine normalize edilir. Azure için `base_url` değerini kaynak origin'i olarak ayarlayın; örneğin `https://example.openai.azure.com`. Rota hedefindeki `model` alanını deployment adıyla doldurun. OpenAI uyumlu bir serviste endpoint'in OpenAI sohbet tamamlama biçimini ve bearer kimlik doğrulamasını kabul ettiğini doğrulayın. Sağlayıcı ve embedding hedefleri genel HTTPS kullanmalıdır; localhost, özel, link-local, metadata, düz HTTP ve yönlendirme yapan hedefler reddedilir. ## Model rotaları Bir `model_route`, istemcinin istediği modeli bir veya daha fazla sağlayıcı hedefine eşler. `config.model` atlanırsa varsayılan değer kayıt adının son bölümüdür. ```json { "tenant_id": "acme", "kind": "model_route", "name": "chat:support", "enabled": true, "config": { "model": "support", "strategy": "ordered", "targets": [ {"provider": "openai-primary", "model": "gpt-4.1-mini", "priority": 20, "weight": 80}, {"provider": "anthropic-fallback", "model": "claude-3-5-haiku-latest", "priority": 10, "weight": 20} ] } } ``` Hedef alanları: | Alan | Anlamı | | ------------------------------------------------------------ | ------------------------------------------------------------------------------------- | | `provider` veya `name` | Zorunlu yapılandırılmış sağlayıcı adıdır | | `model` veya `upstream_model` | İsteğe bağlı model/deployment yeniden yazımıdır; istenen modeli korumak için atlayın | | `priority` | Tam sayıdır. `priority` stratejisinde büyük değerler önce seçilir | | `weight` | Ağırlıklı rotasyon için 1 veya daha büyük tam sayıdır | | `latency_ms` | Canlı EWMA oluşana kadar kullanılan, isteğe bağlı negatif olmayan başlangıç değeridir | | `semantic_text`, `description` veya `prompt_hint` | Semantik hedef sıralamasında kullanılan metindir | | `semantic_keywords`, `keywords`, `tags` veya `semantic_tags` | Ek semantik ipuçlarıdır | İstenen model rotalarında tam adlar ve `gpt-4.1-*` gibi sonu joker karakterle biten desenler desteklenir. Her isteği bilerek tek bir sabit upstream modeline yönlendirmiyorsanız joker karakterli rotada hedef düzeyindeki `model` alanını atlayın. ## Fiyatlandırma kayıtları Fiyatlandırma bir sağlayıcıya gömülebilir veya ayrı bir `pricing` kaydı olarak tanımlanabilir: ```json { "tenant_id": "acme", "kind": "pricing", "name": "openai-primary:support", "config": { "provider": "openai-primary", "model": "support", "currency": "USD", "input_per_1k": 0.00015, "output_per_1k": 0.0006 } } ``` Maliyet tahmini, yapılandırılmış sağlayıcı adına göre fiyat seçer ve sonucu USD cinsinden bildirir. Aynı upstream üzerindeki modellerin fiyatları farklıysa her rotanın doğru fiyatlara ulaşması için ayrı sağlayıcı kayıtları kullanın. Sonucu tahmin olarak değerlendirin ve sağlayıcı faturasıyla mutabakat yapın. ## Güvenli güncelleme `PATCH`, gönderilen `config` nesnesini değiştirir; atlanan anahtarları derin birleştirmez. Kaydı okuyun, gerekli alanları koruyun ve yeni yapılandırmanın tamamını gönderin. Dönen `[redacted]` işareti, saklanan şifreli değeri korumak için yeniden gönderilebilir. ```bash curl -sS -X PATCH \ "$KANGAL_ADMIN_URL/admin/gateways/$GATEWAY_ID/ai-gateway/configs/$CONFIG_ID" \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H 'Content-Type: application/json' \ -d '{ "enabled": true, "config": { "provider_type": "openai", "base_url": "https://api.openai.com/v1", "api_key_ref": "[redacted]", "timeout_seconds": 30 } }' ``` ## Sorun giderme | Belirti | Kontrol | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | `422 Invalid AI Gateway config` | Türe özgü zorunlu alanı, liste öğesini, sayısal alt sınırı, strateji adını veya regex söz dizimini kontrol edin | | `503 AI provider outbound URL was rejected` | Genel HTTPS kullanımını, DNS sonucunu, yönlendirme olmadığını ve hedefin özel/link-local/metadata adresi olmadığını doğrulayın | | `503 AI provider credential is unavailable` | Vault tenant kapsamını, secret fragment'ını, sağlayıcı erişimini ve ortam referansı politikasını kontrol edin | | `503 No AI provider configured for model` | Etkin sağlayıcıyı, rota desenini, hedef adını, sağlayıcının model üyeliğini ve varsayılan sağlayıcıyı kontrol edin | | Azure yolu `openai/deployments` bölümünü iki kez içeriyor | `base_url` olarak Azure kaynak origin'ini kullanın | | OpenAI uyumlu sağlayıcı kimlik doğrulama veya payload hatası döndürüyor | Bearer kimlik doğrulamasını, sohbet tamamlama yolunu ve OpenAI istek/yanıt uyumluluğunu doğrulayın | --- # 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/providers-models.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.