Mengelola Saluran di AI Gateway

「Saluran (Channel)」 adalah konfigurasi titik akses penyedia di AI Gateway—menyimpan alamat penyedia, API Key asli, model yang tersedia, serta informasi penetapan harga dan kuota. AI Gateway menggunakan saluran ini untuk merutekan permintaan dari aplikasi ke penyedia terkait. Artikel ini menjelaskan cara menambah, mengonfigurasi, menguji, dan mengelola saluran.

Prasyarat

• ServBay telah terinstal dan berjalan, serta Anda telah login ke akun ServBay (login diperlukan sebelum menambahkan saluran).
• API Key asli dari penyedia target sudah disiapkan (penyedia lokal seperti Ollama / LM Studio boleh dikosongkan).
• Jika belum memahami arsitektur AI Gateway secara keseluruhan, disarankan membaca Pengenalan AI Gateway.

Menambahkan Saluran

Buka halaman AI Gateway → Saluran (Channels), klik Tambah (Add) untuk membuka wizard. Wizard terdiri dari tiga langkah.

Langkah 1: Pilih penyedia

Penyedia dikelompokkan berdasarkan kategori, klik kartu untuk memilih:

• Utama (Mainstream): OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, OpenRouter.
• Tiongkok (China): DeepSeek, Qwen, Zhipu GLM, Kimi, Doubao·Volcano, ERNIE Bot, Hunyuan, MiniMax, 01.AI, StepFun.
• Lokal (Local): Ollama, LM Studio.
• Kustom (Custom): OpenAI Compatible, Custom.

Setelah memilih penyedia, gateway akan otomatis mengisi Base URL default penyedia tersebut.

Pergantian dua wilayah

Penyedia Tiongkok seperti Qwen, Zhipu GLM, Kimi, Doubao·Volcano, Hunyuan, MiniMax, dan StepFun menyediakan dua set endpoint: domestik dan global. Saat memilih penyedia seperti ini, wizard akan menampilkan pemilih "Wilayah" (🇨🇳 Domestik / 🌐 Global); setelah diganti, Base URL akan otomatis diperbarui ke alamat wilayah yang sesuai.

Langkah 2: Isi konfigurasi

• Nama saluran (wajib) — digunakan untuk mengidentifikasi saluran di daftar, dapat disesuaikan.
• Base URL (wajib) — alamat API penyedia. Sebagian besar penyedia sudah terisi otomatis; Azure OpenAI dan Custom perlu diisi manual.
• API Key (opsional) — kunci asli penyedia. Jika dikosongkan, hanya dapat menguji apakah endpoint dapat dijangkau, tidak dapat memverifikasi validitas kunci; penyedia lokal (Ollama / LM Studio) biasanya tidak perlu diisi.
• Model — ada dua cara, pilih salah satu:
  • Penemuan otomatis: setelah klik temukan, gateway memanggil API daftar model penyedia untuk mengambil model yang tersedia, Anda dapat memilih beberapa sebagai tag (chip).
  • Isi manual: langsung masukkan nama model. Saluran Azure harus diisi dengan nama deployment (Deployment name), bukan nama model.
• Prioritas / bobot — saat beberapa saluran dapat melayani model yang sama, gateway menggunakannya untuk menentukan rute dan distribusi beban.

Perhatian Azure OpenAI

Kolom "Model" pada saluran Azure harus diisi dengan nama deployment (Deployment name) yang Anda buat di portal Azure, bukan nama model yang mendasarinya. Base URL juga harus diisi dengan endpoint sumber daya Azure Anda.

Langkah 3: Konfirmasi dan kirim

Periksa ringkasan konfigurasi lalu kirim. Setelah berhasil dikirim, saluran baru akan muncul di daftar saluran dan menampilkan status kesehatan secara real-time.

Probing Kemampuan dan Kebijakan Perutean

Setelah menambahkan saluran, gateway akan melakukan probing kemampuan (capability probing) terhadap saluran tersebut—ini adalah mekanisme perutean cerdas paling inti di AI Gateway. Hasil probing menentukan apakah alat seperti Claude Code dapat digunakan langsung, apakah perlu membuat pemetaan model, dan bagaimana memilih model target.

Dua indikator kunci probing

Gateway memprobe dua fakta inti untuk setiap saluran (ketiganya tiga status: true / false / belum diketahui):

Item probing	Arti	true	false	Belum diketahui
Mengenali nama model Claude (accepts_claude_names)	Apakah saluran secara native mengenali nama model claude-opus-* / claude-sonnet-* / claude-haiku-*	Langsung saja, tidak perlu pemetaan	Tidak mengenali, harus membuat pemetaan untuk menerjemahkan nama claude-* menjadi nama model asli di hulu	Probing tidak berjalan atau gagal, tidak dapat menyimpulkan
Membedakan berdasarkan tier (tier_aware)	Apakah hulu sendiri mengembalikan model berbeda berdasarkan tier opus / sonnet / haiku	Hulu sudah membedakan tier, serahkan ke hulu	Tidak membedakan tier (mengembalikan model yang sama untuk semua tier), gateway perlu membuat pemetaan	Tidak dapat diprobe atau belum pernah diprobe

Mengapa probing, bukan menebak

Perilaku antarpenyedia sangat berbeda. OpenAI secara native tidak mengenali nama model claude-*; beberapa penyedia perantara mengenalinya melalui penerusan; sedangkan penyedia paket coding (seperti langganan Claude Pro/Max) mungkin hanya mengenali nama model tertentu yang terikat pada langganan. Gateway tidak menebak berdasarkan jenis saluran, melainkan melakukan probing aktual lalu menentukan kebijakan perutean.

Penentuan rute: lima status

Saat Anda melakukan "pengambilalihan satu klik" untuk Claude Code di AI Gateway → Manajemen Akses → halaman Klien, gateway akan menggabungkan hasil probing semua saluran kandidat dan menghasilkan penentuan rute:

Status saluran kandidat	Penentuan	Arti
Tidak ada saluran kandidat yang tersedia (tidak ada saluran / semua tidak sehat / tidak ada saluran dalam cakupan kunci virtual)	Tidak ada saluran kandidat	Anda perlu menambah atau memperbaiki saluran terlebih dahulu
Nilai probing salah satu saluran kandidat belum diketahui	Belum terdeteksi	Perlu menjalankan probing terlebih dahulu, tidak boleh membuat pemetaan tanpa verifikasi
Semua saluran kandidat mengenali nama model claude	Koneksi langsung	Tidak membuat pemetaan, permintaan diteruskan apa adanya
Semua saluran kandidat tidak mengenali nama model claude	Harus dipetakan	Gateway membuat pemetaan tiga tier, menerjemahkan claude-* menjadi nama model asli di hulu
Ada yang mengenali dan ada yang tidak di antara kandidat	Campuran	Perlu keputusan manual (yang mengenali langsung diteruskan, yang tidak mengenali melalui pemetaan)

Pemetaan model: menerjemahkan claude-* ke model asli di hulu

Saat ditentukan "harus dipetakan", gateway akan membuat tiga aturan pemetaan model untuk Claude Code, masing-masing mencakup tiga tier:

Nama model yang dikirim Claude Code	Aturan pemetaan (wildcard)	Dipetakan ke
claude-opus-*	Mencocokkan semua permintaan tier opus	Model unggulan di saluran kandidat
claude-sonnet-*	Mencocokkan semua permintaan tier sonnet	Model unggulan atau model standar di saluran kandidat
claude-haiku-*	Mencocokkan semua permintaan tier haiku	Model ringan di saluran kandidat

Aturan pemilihan model target (fallback berdasarkan prioritas):

1. Preset keluarga: jika nama model kandidat mengandung kata kunci keluarga yang dikenal (seperti glm), langsung ambil versi unggulan keluarga tersebut (seperti glm-5.2) sebagai target tier opus/sonnet, dan versi ringan keluarga tersebut (seperti glm-4.7-flash) sebagai target tier haiku.
2. Pencocokan kata kunci: jika tidak ada preset keluarga, opus/sonnet mengambil model pertama dalam daftar kandidat; haiku mengambil model pertama dalam kandidat yang cocok dengan kata kunci ringan (flash / mini / lite / air / small / turbo / haiku).
3. Fallback: jika masih tidak ada yang cocok, ketiga tier mengambil model pertama dalam daftar kandidat.

Salah konfigurasi tier haiku paling mahal

Claude Code paling banyak memanggil tier haiku (setiap panggilan ringan dalam percakapan menggunakannya). Jika model unggulan salah dimasukkan ke tier haiku, tagihan bisa berlipat ganda. Tabel pencocokan kata kunci gateway mencakup 7 akhiran ringan (flash / mini / lite / air / small / turbo / haiku), memastikan model berat tidak dimasukkan ke tier haiku.

Mekanisme penulisan pemetaan

Setelah pengambilalihan dikonfirmasi, gateway menulis catatan pemetaan melalui API /admin/model-mappings. Setiap catatan pemetaan berisi:

• Protokol sumber (source_protocol): anthropic (permintaan yang dikirim Claude Code berformat Anthropic)
• Pencocokan model sumber (source_model_pattern): wildcard, seperti claude-opus-*
• Protokol target (target_protocol): openai (seragam dikonversi ke format OpenAI untuk dikirim ke hulu)
• Model target (target_model): nama model spesifik yang dipilih dari probing

Penulisan bersifat idempoten—pengambilalihan berulang tidak menghasilkan pemetaan ganda; sebelum menulis, gateway akan mengambil daftar pemetaan yang ada untuk dibandingkan.

Aturan perutean runtime: failover dan degradasi

Selain pemetaan statis yang ditulis pada tahap pengambilalihan, gateway juga mendukung aturan perutean runtime (routing rules), yang mengambil keputusan dinamis saat permintaan melewati gateway:

Kolom aturan	Fungsi
Kondisi pemicu (condition_type)	Kapan degradasi dipicu, misalnya kuota saluran habis (quota_exhausted)
Ambang biaya (cost_threshold_usd)	Opsional: dipicu saat biaya kumulatif saluran melebihi ambang
Aksi (action_type)	Apa yang dilakukan setelah dipicu, misalnya beralih ke saluran cadangan tertentu (switch_to)
Saluran target (target_channel_id)	Saluran cadangan tujuan degradasi
Model target (target_model)	Opsional: sekaligus mengganti model saat degradasi ke saluran cadangan

Dengan menggabungkan beberapa aturan perutean, Anda dapat mewujudkan: saat kuota langganan saluran A habis, otomatis beralih ke endpoint bayar sesuai pemakaian saluran B; saat biaya 24 jam suatu saluran melewati batas, degradasi ke model yang lebih murah.

Load balancing dan prioritas

Saat beberapa saluran sehat dapat melayani model yang sama, gateway memilih berdasarkan strategi berikut:

• Mode prioritas (default): hanya mengambil saluran dengan prioritas tertinggi; di antara saluran dengan prioritas sama, gateway membagi berdasarkan bobot internal.
• Mode round-robin (round_robin): membagi permintaan secara bergiliran di antara semua saluran kandidat yang sehat.

Prioritas diatur dalam konfigurasi saluran (angka lebih besar berarti prioritas lebih tinggi), allowed_channels pada kunci virtual membatasi cakupan saluran yang dapat dipilih.

Uji Konektivitas

Di daftar saluran, Anda dapat menjalankan uji konektivitas untuk satu saluran. Pengujian mencakup dua dimensi:

• Keterjangkauan endpoint (reachable) — memeriksa apakah Base URL dapat terhubung (jaringan dan alamat sudah benar).
• Validitas kunci (authenticated) — benar-benar memanggil API penyedia untuk memverifikasi apakah API Key valid. Hanya diverifikasi jika API Key diisi.

Hasil pengujian akan menampilkan: latensi pulang-pergi (milidetik), lencana status, dan informasi error.

TIP

Dalam wizard penambahan, jika endpoint tidak dapat dijangkau, Anda akan dicegah melanjut ke langkah berikutnya; jika endpoint dapat dijangkau tetapi kunci tidak valid, hanya akan muncul peringatan, Anda tetap dapat melanjutkan (misalnya Anda berencana menambahkan kunci nanti).

Konfigurasi Lanjutan

Saat menambah atau mengedit saluran, Anda dapat membuka konfigurasi lanjutan untuk perhitungan biaya dan kontrol kuota:

• Pengali tarif (Rate Multiplier) — mengalikan harga resmi penyedia dengan suatu faktor, memudahkan perhitungan berdasarkan biaya riil atau harga jual Anda, default 1.0.
• Struktur penagihan — menjelaskan metode penagihan saluran, seperti bayar sesuai pemakaian (pay as you go), langganan (subscription), paket (package).
• Saldo — sumber saldo dapat berupa nilai tetap, tagihan OSS, atau pemeliharaan manual; saat memilih tagihan OSS, Anda juga dapat menentukan jenis tagihan. Saldo dan waktu pembaruan ditampilkan hanya-baca di detail saluran.
• Waktu kedaluwarsa langganan — saluran jenis langganan / paket dapat mencatat waktu kedaluwarsa.
• Batas kuota — dapat menetapkan batas atas berdasarkan jumlah Token, jumlah permintaan, atau jumlah uang, dan memilih periode (harian / mingguan / bulanan / kustom). Setelah kuota habis, saluran akan otomatis dikeluarkan dari pemilihan rute, ini adalah katup pengaman untuk mencegah pembengkakan biaya tak terduga.

Edit dan Hapus Saluran

• Edit — buka saluran tertentu di daftar saluran untuk mengubah nama, Base URL, API Key, model, dan konfigurasi lanjutan.
• Hapus — setelah menghapus saluran, kunci virtual yang bergantung padanya tidak akan dapat merutekan ke saluran tersebut lagi, harap berhati-hati.

Status Kesehatan

Daftar saluran dan halaman Ikhtisar akan menampilkan status kesehatan setiap saluran secara real-time (normal / degradasi / tidak tersedia), membantu Anda cepat menemukan konfigurasi penyedia yang tidak berfungsi.

Pertanyaan Umum (FAQ)

• T: Saat menambahkan saluran muncul permintaan login?
  • J: AI Gateway adalah fitur nilai tambah ServBay, sebelum menambahkan saluran / kunci Anda perlu login ke akun ServBay, ikuti panduan antarmuka untuk login.
• T: Muncul pesan jumlah saluran sudah mencapai batas?
  • J: Jumlah saluran yang dapat dibuat terkait dengan paket akun; saat mencapai batas, Anda dapat menghapus saluran yang tidak terpakai atau meningkatkan paket.
• T: Penemuan model otomatis tidak dapat mengambil daftar?
  • J: Pastikan Base URL benar dan API Key valid (dapat diverifikasi dengan "Validitas kunci" pada uji konektivitas), sebagian penyedia memerlukan kunci valid untuk mengembalikan daftar model; Anda juga dapat beralih ke pengisian nama model secara manual.
• T: Apakah perlu mengisi Key untuk mengintegrasikan Ollama / LM Studio lokal?
  • J: Biasanya tidak perlu. Pastikan layanan lokal terkait sudah berjalan dan mendengarkan port default (Ollama 11434, LM Studio 1234).

Ringkasan

Saluran adalah dasar AI Gateway dalam merutekan permintaan. Melalui wizard tiga langkah, Anda dapat dengan cepat mengintegrasikan hampir 20 penyedia, dengan dukungan pergantian dua wilayah, penemuan model otomatis, dan uji konektivitas dua dimensi untuk memastikan konfigurasi benar, lalu mengelola biaya secara terperinci dengan konfigurasi lanjutan seperti penetapan harga dan kuota. Setelah saluran dikonfigurasi, Anda dapat membuat Kunci Virtual untuk digunakan oleh aplikasi dan alat.