Halaman ini diterjemahkan dari dokumentasi bahasa Inggris. Perintah, pengenal, dan contoh tidak diubah. Runtime 7.24.4 · SDK 2.6.7. Sumber bahasa Inggris

Penyedia kustom dan gateway

Status: Aktif Cakupan: kondisi terkini Terakhir ditinjau: 2026-09-06 Pemilik: runtime ax-code

AX Code berbicara dengan model melalui protokol penyedia standar. Titik akhir mana pun yang berbicara API kompatibel OpenAI (/v1/chat/completions) atau kompatibel Anthropic (/v1/messages) dapat ditambahkan sebagai penyedia kustom dengan mengarahkan baseURL kepadanya — tanpa perubahan kode dan tanpa menunggu preset bawaan.

Ini mencakup agregator yang di-host sendiri dan gateway relai seperti LiteLLM, one-api, new-api, dan Vercel AI Gateway, serta proksi perusahaan privat dan layanan kompatibel lain. AX Code memperlakukan mereka secara seragam: ia berbicara protokol kawat, Anda memasok URL dan kunci.

Catatan tanggung jawab. Gateway berada di antara AX Code dan model hulu, jadi prompt, kode, dan kredensial Anda melewatinya. Saat Anda mengarahkan AX Code ke relai pihak ketiga atau pengumpul akun, Anda bertanggung jawab untuk memercayai operator itu dengan data Anda dan untuk tetap berada dalam ketentuan layanan setiap penyedia hulu yang ditujunya. Preset gateway bawaan seperti OpenRouter memakai jalur protokol standar yang sama; konfigurasi gateway kustom tidak menyiratkan dukungan terhadap operator relai mana pun.

Penyiapan interaktif

Pakai /connect -> Penyedia cloud API -> Penyedia API kustom untuk gateway yang kompatibel, atau /connect -> AX Trust -> Hubungkan AX Trust untuk gateway AX Trust. Masukkan URL dasarnya (termasuk /v1 untuk AX Trust) dan kunci API klien. Editor menemukan ID model serta metadata dan menyimpan kredensial di penyimpanan autentikasi terenkripsi. Ia juga dapat menerima ID model eksplisit jika penemuan tidak tersedia. Menyambungkan ulang URL tersimpan mempertahankan ID penyedia dan kuncinya bila token dibiarkan kosong. Koneksi AX Trust mempertahankan kategorinya setelah suntingan dan penyegaran model. AX Code mengirim X-AX-Prompt-Cache-Key dengan ID sesi pada koneksi itu agar gateway dapat menahan sesi pada satu akun yang memenuhi syarat; setel provider.<id>.options.axTrust ke false untuk menonaktifkannya. Header ini tidak diteruskan ke hulu dan bukan isi prompt_cache_key.

Penyedia AX Trust yang tersambung menyegarkan daftar model mereka di latar belakang saat mulai. AX Code memanggil GET /models titik akhir yang dikonfigurasi dengan kredensial yang ada dan memperbarui nama model, batas konteks/keluaran, penalaran, pemanggilan alat, dukungan temperatur, dan dukungan gambar. Model yang mampu gambar menampilkan penanda visi di /models, termasuk alias gateway bila AX Trust mengiklankan dukungan gambar mereka. TUI diperbarui saat penemuan selesai. Untuk ID model DeepSeek pihak pertama yang persis, metadata yang hilang diisi dari katalog models.dev terbundel. Bendera kemampuan dan batas gateway yang eksplisit diutamakan; alias yang tidak dikenal tidak mewarisi kemampuan berdasarkan kemiripan nama.

Penyegaran yang berhasil mengganti daftar runtime, menghapus model yang tidak lagi diiklankan gateway, dan tetap menerapkan daftar izinkan/blokir yang dikonfigurasi. Waktu habis, kesalahan, serta respons kosong atau tidak valid mempertahankan daftar tersimpan dan mencatat kegagalan penemuan. Mulai tidak menunggu jaringan. Penyegaran ini tidak menulis ulang konfigurasi atau kredensial penyedia; konfigurasi tersimpan tetap menjadi cadangan saat mulai. Penyedia API kustom biasa mempertahankan penyegaran manual.

Cara penyedia diselesaikan

Untuk setiap permintaan AX Code membutuhkan tiga hal dari entri penyedia:

• npm — adaptor AI SDK yang berbicara protokol kawat. Pakai @ai-sdk/openai-compatible untuk titik akhir bergaya OpenAI dan @ai-sdk/anthropic untuk titik akhir bergaya Anthropic. Hanya adaptor @ai-sdk/* yang terbundel/dapat dipasang.
• options.baseURL — URL gateway. Jatuh kembali ke bidang api penyedia, lalu ke api.url milik model sendiri. Mendukung substitusi ${ENV_VAR}.
• Sebuah kredensial — diselesaikan berurutan dari options.apiKey, lalu penyimpanan autentikasi yang menetap, lalu variabel env penyedia.

Konfigurasi manual juga membutuhkan peta models yang eksplisit. Editor interaktif mengisi peta ini dari titik akhir atau dari ID model yang Anda berikan.

Cloud GPU privat khusus adalah penyedia kelas satu di bawah /connect → Cloud GPU privat. Tempel URL dan token yang kompatibel OpenAI (alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti, atau custom-private-gpu); AX Code memanggil GET …/models dan memakai ID model yang di-deploy secara otomatis.

Katalog GPU yang di-host (nebius, fireworks-ai, togetherai, baseten, nvidia, deepinfra) memakai kunci API dan cuplikan model terbundel, pola yang sama dengan yang dipakai OpenCode.

Gateway kompatibel OpenAI

Sebagian besar agregator (LiteLLM, one-api, new-api, gateway gratis/host sendiri) mengekspos permukaan yang kompatibel OpenAI. Tambahkan ini ke ax-code.json Anda (global di ~/.config/ax-code/ax-code.json, atau per proyek di akar repositori):

{
  "$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 },
        },
      },
    },
  },
}

• Kunci "my-gateway" adalah id penyedia yang Anda pilih di /connect dan ax-code models.
• Setiap kunci di bawah models adalah ID pemilihan lokal. Setel id entri ke ID model persis yang diharapkan gateway bila berbeda dari kunci itu; jika tidak, kunci dipakai untuk model yang dinyatakan secara manual tanpa pemetaan katalog yang ada.
• Utamakan ${ENV_VAR} daripada kunci harfiah agar rahasia tetap di luar konfigurasi yang di-commit.

Alias model gateway setelah mengubah titik akhir

Mengubah options.baseURL tidak menerjemahkan ID model yang dikonfigurasi secara manual. Misalnya, titik akhir AX Trust dapat mengiklankan deepseek-flash sementara pemilihan lokal yang ada adalah ax-trust/deepseek-v4-flash. Pertahankan kunci lokal dan setel provider.ax-trust.models.deepseek-v4-flash.id ke deepseek-flash. AX Code kemudian mengirim ID gateway dalam permintaan API.

Lihat contoh konfigurasi AX Trust DeepSeek Flash. Gabungkan bidang penyedia yang relevan ke konfigurasi yang sudah ada, dengan mempertahankan model lain dan pengaturan kemampuannya. Contoh memakai {env:AX_TRUST_API_KEY}; setel variabel lingkungan itu sebelum memulai AX Code, atau pertahankan konfigurasi kredensial yang sudah ada. Mulai ulang AX Code setelah menyunting.

Saat mendiagnosis 403 model is not allowed, bandingkan ID model permintaan dengan respons GET /models terautentikasi dari titik akhir. Permintaan daftar model yang berhasil saja tidak menetapkan izin untuk menjalankan model. Jika ID persis tetap gagal, periksa izin kunci/model gateway.

Gateway kompatibel Anthropic

Relai yang mengekspos /v1/messages (bentuk API Claude) memakai adaptor Anthropic:

{
  "$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 },
        },
      },
    },
  },
}

Beberapa relai berbentuk Anthropic juga menghormati variabel lingkungan Claude secara langsung. Untuk jalankan tanpa interaksi yang cepat tanpa menyunting konfigurasi, Anda dapat menyetel:

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

Entri konfigurasi tetap disarankan bila Anda ingin gateway muncul sebagai penyedia yang dapat dipilih sendiri dengan daftar model yang dikurasi.

Bidang model

Entri model memakai ulang skema registri; untuk titik akhir kustom, bidang yang berguna adalah:

Setel bendera kemampuan agar sesuai dengan yang benar-benar didukung model hulu; AX Code memakainya untuk mengunci panggilan alat, lampiran, dan penganggaran konteks.

Memverifikasi

Setelah menyimpan konfigurasi:

• ax-code models mencantumkan setiap model yang diekspos penyedia Anda.
• /connect di dalam TUI menampilkan penyedia dan memungkinkan Anda mengautentikasi jika Anda memakai kunci env alih-alih options.apiKey.

Jika sebuah model hilang, pastikan id penyedia, kunci model, dan bahwa gateway dapat dijangkau di baseURL.

Pemecahan masalah

• Kesalahan autentikasi — pastikan urutan resolusi kredensial: options.apiKey menang, jika tidak kunci env/penyimpanan autentikasi yang dipakai.
• Aliran yang macet — gateway kadang menahan SSE. Setel options.chunkTimeout (per potongan) dan options.timeout (seluruh permintaan) pada penyedia.
• Panggilan alat ditolak — setel "tool_call": true pada model dan pastikan model hulu di belakang gateway benar-benar mendukung alat.