Bu sayfa İngilizce belgenin çevirisidir. Komutlar, tanımlayıcılar ve örnekler aynıdır. Çalışma zamanı 7.24.4 · SDK 2.6.7. İngilizce kaynak

Özel ve ağ geçidi sağlayıcıları

Durum: Etkin Kapsam: güncel durum Son inceleme: 2026-09-06 Sahip: ax-code çalışma zamanı

AX Code modellere standart sağlayıcı protokolleriyle konuşur. OpenAI uyumlu (/v1/chat/completions) veya Anthropic uyumlu (/v1/messages) bir API konuşan herhangi bir uç nokta, baseURL oraya yöneltilerek özel sağlayıcı olarak eklenebilir — kod değişikliği yok ve yerleşik bir hazır ayar beklemek yok.

Bu, LiteLLM, one-api, new-api ve Vercel AI Gateway gibi kendi barındırılan toplayıcıları ve aktarma ağ geçitlerini, ayrıca özel kurumsal vekilleri ve başka uyumlu hizmetleri kapsar. AX Code bunları tek biçimde ele alır: hat protokolünü konuşur, URL ve anahtarı siz verirsiniz.

Sorumluluk notu. Bir ağ geçidi AX Code ile yukarı akış model arasında durur; bu yüzden istemleriniz, kodunuz ve kimlik bilgileriniz ondan geçer. AX Code’u üçüncü taraf veya hesap havuzlayan bir aktarmaya yönelttiğinizde o operatöre verinizle güvenmekten ve yönlendirdiği her yukarı akış sağlayıcının hizmet koşulları içinde kalmaktan siz sorumlusunuz. OpenRouter gibi yerleşik ağ geçidi hazır ayarları aynı standart protokol yolunu kullanır; özel ağ geçidi yapılandırması herhangi bir aktarma operatörünün onaylandığı anlamına gelmez.

Etkileşimli kurulum

Uyumlu bir ağ geçidi için /connect -> API bulut sağlayıcısı -> Özel API sağlayıcısı kullanın veya bir AX Trust ağ geçidi için /connect -> AX Trust -> AX Trust bağla kullanın. Taban URL’sini (AX Trust için /v1 dahil) ve istemci API anahtarını girin. Düzenleyici model kimliklerini ve üst veriyi keşfeder ve kimlik bilgilerini şifreli kimlik deposunda saklar. Keşif yoksa açık model kimliklerini de kabul edebilir. Kayıtlı bir URL’yi yeniden bağlamak, belirteç boş bırakılırsa sağlayıcı kimliğini ve anahtarını korur. AX Trust bağlantıları düzenlemelerden ve model yenilemelerinden sonra kategorilerini korur. AX Code bu bağlantılarda oturum kimliğiyle X-AX-Prompt-Cache-Key gönderir; böylece ağ geçidi bir oturumu uygun bir hesapta tutabilir. Kapatmak için provider.<id>.options.axTrust değerini false yapın. Bu üst bilgi yukarı akışa iletilmez ve bir gövde prompt_cache_key değildir.

Bağlı AX Trust sağlayıcıları başlangıçta model listelerini arka planda yeniler. AX Code, yapılandırılmış uç noktanın GET /models yolunu mevcut kimlik bilgisiyle çağırır ve model adlarını, bağlam/çıktı sınırlarını, akıl yürütmeyi, araç çağırmayı, sıcaklık desteğini ve görüntü desteğini günceller. Görüntü yapabilen modeller, AX Trust görüntü desteğini ilan ettiğinde ağ geçidi takma adları dahil /models içinde görme işaretini gösterir. Keşif bitince TUI güncellenir. Tam birinci taraf DeepSeek model kimlikleri için eksik üst veri paketlenmiş models.dev kataloğundan doldurulur. Açık ağ geçidi yetenek bayrakları ve sınırları önceliklidir; bilinmeyen takma adlar ad benzerliğiyle yetenek devralmaz.

Başarılı bir yenileme çalışma zamanı listesinin yerini alır, ağ geçidinin artık ilan etmediği modelleri kaldırır ve yapılandırılmış izin/engel listelerini yine uygular. Zaman aşımları, hatalar, boş veya geçersiz yanıtlar kayıtlı listeyi korur ve bir keşif başarısızlığı günlüğe yazar. Başlangıç ağı beklemez. Bu yenileme sağlayıcı yapılandırmasını veya kimlik bilgilerini yeniden yazmaz; kayıtlı yapılandırma başlangıç geri dönüşü olarak kalır. Olağan özel API sağlayıcıları el ile yenilemeyi korur.

Bir sağlayıcı nasıl çözülür

Her istek için AX Code bir sağlayıcı girdisinden üç şeye ihtiyaç duyar:

• npm — hat protokolünü konuşan AI SDK bağdaştırıcısı. OpenAI tarzı uç noktalar için @ai-sdk/openai-compatible, Anthropic tarzı uç noktalar için @ai-sdk/anthropic kullanın. Yalnızca @ai-sdk/* bağdaştırıcıları paketlenir/kurulabilir.
• options.baseURL — ağ geçidi URL’si. Sağlayıcı api alanına, sonra modelin kendi api.url değerine düşer. ${ENV_VAR} yerine koymayı destekler.
• Bir kimlik bilgisi — sırayla options.apiKey, sonra kalıcı kimlik deposu, sonra sağlayıcının env değişkenlerinden çözülür.

El ile yapılandırma ayrıca açık bir models haritası ister. Etkileşimli düzenleyici bu haritayı uç noktadan veya verdiğiniz model kimliklerinden doldurur.

Ayrılmış özel GPU bulutları /connect → Özel GPU bulutu altında birinci sınıf sağlayıcılardır. OpenAI uyumlu URL ve belirteci yapıştırın (alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti veya custom-private-gpu); AX Code GET …/models çağırır ve dağıtılan model kimliklerini otomatik kullanır.

Barındırılan GPU katalogları (nebius, fireworks-ai, togetherai, baseten, nvidia, deepinfra) bir API anahtarı ve paketlenmiş model anlık görüntüsünü kullanır; OpenCode’un kullandığı aynı desendir.

OpenAI uyumlu ağ geçidi

Çoğu toplayıcı (LiteLLM, one-api, new-api, ücretsiz/kendi barındırılan ağ geçitleri) OpenAI uyumlu bir yüzey sunar. Bunu ax-code.json dosyanıza ekleyin (genel olarak ~/.config/ax-code/ax-code.json veya depo kökünde proje başına):

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-gateway": {
      "name": "My Gateway",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o (via gateway)",
          "tool_call": true,
          "reasoning": false,
          "attachment": true,
          "limit": { "context": 128000, "output": 16384 },
        },
      },
    },
  },
}

• "my-gateway" anahtarı, /connect ve ax-code models içinde seçtiğiniz sağlayıcı kimliğidir.
• models altındaki her anahtar yerel seçim kimliğidir. Anahtardan farklıysa girdinin id değerini ağ geçidinin beklediği tam model kimliğine ayarlayın; aksi halde anahtar, mevcut katalog eşlemesi olmayan el ile bildirilmiş modeller için kullanılır.
• Gizli, işlenmiş yapılandırmanın dışında kalsın diye düz bir anahtar yerine ${ENV_VAR} yeğleyin.

Uç nokta değiştikten sonra ağ geçidi model takma adları

options.baseURL değiştirmek el ile yapılandırılmış model kimliklerini çevirmez. Örneğin bir AX Trust uç noktası deepseek-flash ilan ederken mevcut yerel seçim ax-trust/deepseek-v4-flash olabilir. Yerel anahtarı tutun ve provider.ax-trust.models.deepseek-v4-flash.id değerini deepseek-flash yapın. AX Code ardından API isteklerinde ağ geçidi kimliğini gönderir.

AX Trust DeepSeek Flash yapılandırma örneğine bakın. İlgili sağlayıcı alanlarını mevcut yapılandırmanıza birleştirin; diğer modelleri ve yetenek ayarlarını koruyun. Örnek {env:AX_TRUST_API_KEY} kullanır; AX Code’u başlatmadan önce bu ortam değişkenini ayarlayın veya mevcut kimlik bilgisi yapılandırmanızı koruyun. Düzenledikten sonra AX Code’u yeniden başlatın.

403 model is not allowed tanısı koyarken isteğin model kimliğini uç noktanın kimliği doğrulanmış GET /models yanıtıyla karşılaştırın. Başarılı bir model listesi isteği tek başına bir modeli çalıştırma izni oluşturmaz. Tam kimlik yine başarısız olursa ağ geçidinin anahtar/model izinlerini denetleyin.

Anthropic uyumlu ağ geçidi

/v1/messages sunan aktarmalar (Claude API biçimi) Anthropic bağdaştırıcısını kullanır:

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-claude-gateway": {
      "name": "My Claude Gateway",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://gateway.example.com",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet (via gateway)",
          "tool_call": true,
          "reasoning": true,
          "attachment": true,
          "limit": { "context": 200000, "output": 64000 },
        },
      },
    },
  },
}

Bazı Anthropic biçimli aktarmalar Claude ortam değişkenlerini doğrudan da onurlandırır. Yapılandırmayı düzenlemeden hızlı bir başsız çalıştırma için şunları ayarlayabilirsiniz:

export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."

Ağ geçidinin küratörlü bir model listesiyle kendi seçilebilir sağlayıcısı olarak görünmesini istiyorsanız bir yapılandırma girdisi yine önerilir.

Model alanları

Model girdileri kayıt şemasını yeniden kullanır; özel bir uç nokta için yararlı alanlar şunlardır:

Yetenek bayraklarını yukarı akış modelin gerçekten desteklediğiyle eşleştirin; AX Code bunları araç çağrılarını, ekleri ve bağlam bütçelemesini kapılamak için kullanır.

Doğrulama

Yapılandırmayı kaydettikten sonra:

• ax-code models sağlayıcınızın sunduğu her modeli listeler.
• TUI içindeki /connect sağlayıcıyı gösterir ve bir env anahtarı kullandıysanız, options.apiKey yerine, kimlik doğrulamanızı sağlar.

Bir model eksikse sağlayıcı kimliğini, model anahtarını ve ağ geçidinin baseURL adresinde erişilebilir olduğunu doğrulayın.

Sorun giderme

• Kimlik doğrulama hataları — kimlik bilgisi çözüm sırasını doğrulayın: options.apiKey kazanır, aksi halde bir env/kimlik deposu anahtarı kullanılır.
• Takılan akışlar — ağ geçitleri bazen SSE tamponlar. Sağlayıcıda options.chunkTimeout (parça başına) ve options.timeout (tüm istek) ayarlayın.
• Reddedilen araç çağrıları — modelde "tool_call": true ayarlayın ve ağ geçidinin arkasındaki yukarı akış modelin araçları gerçekten desteklediğini doğrulayın.