Arsitektur AI API Gateway: Satu Kunci, Routing Model, dan Failover

Sebuah AI API gateway memberi aplikasi satu endpoint stabil sementara infrastruktur di balik endpoint tersebut dapat menggunakan beberapa model, provider, akun, atau region. Bagian yang berguna bukan sekadar menyembunyikan beberapa API key di balik satu key. Bagian yang berguna adalah menciptakan titik keputusan terkontrol untuk setiap permintaan.

Titik keputusan itu dapat menjawab pertanyaan operasional sebelum lalu lintas mencapai penyedia model:

• Apakah klien ini diizinkan memanggil model yang diminta?
• Upstream mana yang saat ini memenuhi kebutuhan kapabilitas, latensi, dan biaya permintaan?
• Apakah upstream tersebut cukup sehat untuk menerima lebih banyak lalu lintas?
• Apakah permintaan ini bisa dicoba ulang dengan aman?
• Fallback mana yang mempertahankan kontrak respons?
• Bagaimana tim akan menjelaskan rute, biaya, dan kegagalan setelahnya?

Panduan ini memetakan tanggung jawab tersebut ke dalam arsitektur produksi. Panduan ini juga menunjukkan di mana satu API key membantu, di mana tidak, dan bagaimana melakukan migrasi klien yang kompatibel dengan OpenAI tanpa menjadikan gateway sebagai sumber tak terlihat dari kejutan routing.

The reference architecture in one request path

Sebuah permintaan AI gateway yang praktis bergerak melalui lima lapisan:

1. Kontrak klien: aplikasi mengirim permintaan terautentikasi ke satu base URL yang stabil.
2. Kontrol penerimaan: gateway memvalidasi identitas, kuota, izin model, batas payload, dan metadata permintaan.
3. Kebijakan routing: mesin kebijakan mengubah model atau kapabilitas yang diminta menjadi target upstream yang memenuhi syarat.
4. Kontrol eksekusi: aturan health, concurrency, timeout, retry, fallback, dan streaming menentukan bagaimana target yang dipilih dipanggil.
5. Telemetry dan pembebanan biaya: gateway mencatat rute yang dipilih, status respons, latensi, penggunaan token atau media, dan atribusi biaya.

Application / agent
        |
        |  one API key + stable request schema
        v
AI API gateway
  ├─ authentication and tenant policy
  ├─ model alias and capability registry
  ├─ routing policy and budget rules
  ├─ health, timeout, retry, and fallback controls
  └─ logs, traces, usage, and cost attribution
        |
        ├────────> Provider or deployment A
        ├────────> Provider or deployment B
        └────────> Provider or deployment C

Karena itu, gateway adalah sekaligus control plane dan data plane. Control plane menyimpan kebijakan, kredensial, alias, kuota, dan konfigurasi routing. Data plane menangani permintaan langsung, respons streaming, retry, dan telemetry. Memisahkan tanggung jawab tersebut secara konseptual membuat perubahan lebih aman: operator dapat memperbarui kebijakan routing tanpa meminta setiap tim aplikasi untuk mengirim kode klien baru.

Apa arti “satu key” seharusnya

“Satu key” seharusnya berarti satu kontrak kredensial yang dihadapi aplikasi, bukan satu kredensial yang dibagikan ke setiap orang, layanan, dan lingkungan.

Desain yang baik menerbitkan kredensial gateway terpisah untuk production, staging, pengembangan lokal, CI, dan workload independen. Setiap key harus memiliki cakupan yang sempit, pemilik, kuota, dan jalur pencabutan. Gateway kemudian menyimpan kredensial provider di sisi server dan memetakan identitas yang masuk ke kredensial upstream yang diizinkannya untuk digunakan.

Ini menciptakan batas keamanan yang berguna:

Kunci gateway tidak boleh diperlakukan sebagai alasan untuk melonggarkan kebersihan pengelolaan kunci. Simpan di secret manager, jangan pernah di kode browser atau repositori publik, lakukan rotasi, dan pisahkan berdasarkan lingkungan. Untuk daftar periksa operasional yang lebih mendalam, lihat pengelolaan kunci API yang aman untuk produk AI.

Alias model memisahkan kontrak klien dari penyedia

Abstraksi routing pertama adalah alias model. Alih-alih meng-hard-code pengenal model spesifik penyedia di seluruh aplikasi, klien meminta nama yang stabil seperti:

support-fast
reasoning-high
code-review-default
image-generation-standard

Registry di balik setiap alias mendefinisikan kontrak kapabilitas. Alias teks mungkin menetapkan pemanggilan alat, output terstruktur, ukuran konteks minimum, dukungan streaming, dan keluarga fallback yang disetujui. Alias gambar atau video memerlukan field yang berbeda, seperti jenis input yang diterima, dimensi output, perilaku job asinkron, dan batasan keamanan.

Alias tidak boleh menjanjikan bahwa setiap model kandidat berperilaku identik. Alias harus mendefinisikan perilaku minimum yang dapat diandalkan oleh aplikasi.

alias: support-fast
contract:
  modality: text
  streaming: true
  tools: optional
  structured_output: required
  maximum_latency_ms: 3500
routes:
  - target: provider-a/model-fast
    priority: 1
  - target: provider-b/model-balanced
    priority: 2

Indireksi inilah yang membuat base URL yang stabil menjadi berharga. Aplikasi berintegrasi dengan kontrak alias; pemilik platform dapat mengubah set target setelah evaluasi, insiden penyedia, perubahan harga, atau kebutuhan regional.

Keputusan routing harus eksplisit

Routing produksi biasanya menggabungkan filter keras dan pemeringkatan lunak.

1. Terapkan filter kelayakan keras

Hapus target apa pun yang tidak dapat memenuhi permintaan. Filter umum meliputi:

• Modality dan jenis input yang diperlukan
• Persyaratan window konteks atau ukuran output
• Dukungan pemanggilan alat atau output terstruktur
• Kedaulatan data atau ketersediaan regional
• Allowlist penyewa atau proyek
• Kebijakan keamanan atau kepatuhan
• Kapasitas, rate limit, atau status konkurensi saat ini
• Kesesuaian streaming

Target yang gagal memenuhi persyaratan keras tidak boleh menang hanya karena lebih murah.

2. Beri peringkat target yang memenuhi syarat

Setelah penyaringan, beri skor pada rute yang tersisa. Kebijakan sederhana bisa lebih mudah dioperasikan daripada pengoptimal yang buram:

route score =
  quality_weight × evaluation_score
  - latency_weight × predicted_latency
  - cost_weight × estimated_cost
  - risk_weight × recent_error_rate

Bobot harus berbeda حسب beban kerja. Chat interaktif mungkin mengutamakan waktu hingga token pertama. Job ekstraksi malam hari mungkin mengutamakan biaya per record terstruktur yang berhasil. Sebuah coding agent mungkin lebih menghargai keandalan tool dan perilaku konteks panjang daripada selisih harga yang kecil.

3. Catat alasannya

Setiap keputusan routing harus menghasilkan metadata yang dapat dibaca mesin seperti:

{
  "requested_alias": "support-fast",
  "selected_target": "provider-a/model-fast",
  "policy_version": "support-fast-2026-07-29.3",
  "selection_reason": "healthy_primary_within_latency_budget",
  "fallback_count": 0
}

Jika sebuah tim tidak dapat merekonstruksi mengapa sebuah route dipilih, mereka tidak dapat men-debug pergeseran biaya, regresi kualitas, atau insiden provider.

Pemeriksaan kesehatan membutuhkan lebih dari HTTP 200

Upstream dapat mengembalikan probe kesehatan yang berhasil sambil gagal pada traffic model nyata. Karena itu, kesehatan AI gateway memerlukan beberapa sinyal:

• Kesehatan transport: kegagalan koneksi, error TLS, error DNS, dan timeout upstream
• Kesehatan API: respons rate-limit, kegagalan autentikasi, error provider, dan respons yang tidak valid
• Kesehatan model: output kosong, output terstruktur yang tidak valid, tool call yang rusak, atau chunk streaming yang tidak kompatibel
• Kesehatan performa: waktu hingga token pertama, latensi total, waktu antre, dan throughput
• Kesehatan kapasitas: permintaan bersamaan, tekanan token per menit, saldo akun, atau kuota deployment

Gunakan jendela bergulir, bukan satu kegagalan. Circuit breaker dapat sementara menghapus target setelah ambang kegagalan atau latensinya terlampaui, lalu mengizinkan probe terbatas sebelum memulihkan traffic penuh. Deteksi outlier juga dapat mengeluarkan satu deployment yang tidak sehat sambil tetap membiarkan deployment sehat dari provider yang sama tersedia.

Prinsip ini sudah mapan dalam infrastruktur gateway dan service mesh: retry, circuit breaking, dan deteksi outlier adalah kontrol yang terpisah, dan masing-masing memerlukan kebijakan yang terbatas. Envoy mendokumentasikan mekanisme ini secara terpisah dalam panduan HTTP retry, circuit breaking, dan deteksi outlier.

Retry hanya saat request aman

Retry hanya meningkatkan keandalan ketika tidak melipatgandakan pekerjaan atau menciptakan efek samping duplikat.

Untuk text completion non-streaming yang gagal sebelum byte respons apa pun tiba, satu retry ke target yang sama mungkin masuk akal. Untuk request yang memicu tool, memulai job gambar atau video, menagih akun eksternal, atau sudah men-stream output parsial, retry sembarangan dapat menciptakan duplikat atau merusak pengalaman pengguna.

Definisikan kelayakan retry menggunakan tiga pertanyaan:

1. Apakah permintaan diterima di upstream? Kegagalan koneksi sebelum penerimaan berbeda dari timeout setelah penyedia mulai bekerja.
2. Apakah ada output yang sudah mencapai klien? Setelah streaming dimulai, beralih penyedia dapat menghasilkan jawaban yang terputus-putus.
3. Apakah ada kunci idempotency atau catatan deduplikasi? Alur kerja media dan agen yang berjalan lama memerlukan identitas operasi yang stabil.

Matriks retry yang konservatif terlihat seperti ini:

Gunakan satu deadline end-to-end. Jika klien memberi waktu delapan detik, gateway tidak bisa menghabiskan tujuh detik pada primary lalu memberi fallback delapan detik lagi. Setiap percobaan mengonsumsi budget permintaan yang sama.

Fallback harus mempertahankan kontrak

Fallback bukan sekadar “coba model lain.” Ini adalah kesepakatan tentang apa yang boleh berubah ketika rute utama gagal.

Tentukan fallback pada tiga level:

1. Model yang sama, deployment atau akun berbeda: risiko perilaku paling rendah; berguna untuk kegagalan kuota atau regional.
2. Keluarga model yang setara: risiko sedang; memerlukan regresi test untuk skema, tools, keamanan, dan gaya output.
3. Kemampuan yang diturunkan: risiko tertinggi; dapat menonaktifkan tools, mengurangi konteks, atau mengembalikan respons antrean вместо respons live.

Untuk setiap alias, dokumentasikan:

• Kelas kegagalan mana yang memicu fallback
• Target mana yang kompatibel dengan kontrak
• Apakah klien diberi tahu bahwa fallback terjadi
• Jumlah maksimum percobaan dan total deadline
• Cara perubahan kualitas dan biaya diukur
• Apakah respons boleh dicache atau diputar ulang

Akses penyedia regional menambahkan dimensi lain. Sebuah penyedia atau model mungkin tersedia di satu geografi, jenis akun, atau pengaturan komersial dan tidak tersedia di yang lain. Routing penyedia LLM regional menjelaskan pemeriksaan akses, kebijakan, dan failover terpisah yang diperlukan untuk rute tersebut.

Streaming adalah bagian dari kontrak gateway

Bentuk permintaan yang kompatibel dengan OpenAI dapat menyederhanakan migrasi klien, tetapi kompatibilitas streaming memerlukan translasi yang disengaja. Gateway harus mempertahankan urutan event, alasan selesai, metadata penggunaan, fragmen tool-call, sinyal error, dan pembatalan koneksi.

Sebelum merutekan dua model di balik satu alias streaming, uji:

• Waktu hingga event pertama dan perilaku heartbeat
• Format delta teks inkremental
• Perakitan argumen tool-call
• Pelaporan penggunaan pada event akhir
• Propagasi pembatalan oleh klien
• Perilaku timeout sebelum dan sesudah event pertama
• Format error setelah header sudah dikirim

Jangan menyembunyikan restart stream di dalam satu respons kecuali protokol secara eksplisit mendukung resumsi. Pada sebagian besar klien, mencampur jawaban parsial dari satu model dengan jawaban kedua dari model lain lebih buruk daripada memberikan error yang jelas.

Observability menghubungkan routing ke hasil

Dashboard gateway memang berguna, tetapi diagnosis produksi memerlukan telemetry terstruktur yang dapat menghubungkan permintaan model dengan trace aplikasi di sekitarnya.

Setidaknya, tangkap:

Hindari logging prompt dan output mentah secara default. Rekam konten hanya ketika kasus penggunaan, kebijakan retensi, dan ekspektasi pengguna mengizinkannya. Proyek OpenTelemetry mempertahankan konvensi semantik yang terus berkembang untuk sistem AI generatif yang dapat membantu tim menggunakan nama span dan metrik yang konsisten alih-alih menciptakan skema terpisah untuk setiap provider.

Kontrol biaya harus ditempatkan sebelum panggilan upstream

Laporan pengeluaran setelah kejadian tidak dapat mencegah insiden. Kebijakan admission dan routing harus mengevaluasi biaya sebelum mengirim traffic.

Kontrol yang berguna mencakup:

• Kuota keras per key dan per project
• Alert anggaran lunak
• Unit input atau output maksimum
• Allowlist model per environment
• Routing sadar biaya untuk workload yang fleksibel
• Kebijakan cache untuk permintaan yang dapat diulang
• Batas konkurensi untuk job media yang mahal
• Kill switch untuk model, provider, tenant, atau route

Mesin routing membutuhkan tabel harga yang berversi dan lapisan normalisasi penggunaan yang konsisten. Jika tidak, kebijakan “model termurah” mungkin membandingkan unit yang tidak kompatibel atau harga yang sudah usang. Untuk framework yang memisahkan tarif provider, biaya platform, dan kontrol operasional, lihat harga AI gateway.

Migrasi minimal yang kompatibel dengan OpenAI

Perubahan klien paling kecil biasanya hanya berupa API key baru, base URL, dan nama model. Dengan gateway yang kompatibel dengan OpenAI, kode aplikasi dapat mempertahankan library klien yang sama:

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url="https://router.flatkey.ai/v1",
)

response = client.chat.completions.create(
    model="your-model-or-alias",
    messages=[
        {"role": "user", "content": "Ringkas laporan insiden ini."}
    ],
)

Perubahan kode itu adalah bagian yang mudah. Migrasi yang aman memiliki empat tahap:

1. Inventarisasi kontrak saat ini. Catat model, parameter, perilaku streaming, tools, skema, timeout, dan penanganan error.
2. Jalankan evaluasi shadow atau offline. Bandingkan kualitas output, validitas skema, latensi, dan biaya pada permintaan yang representatif.
3. Lakukan canary pada satu workload. Mulai dengan persentase traffic yang terbatas dan jalur rollback yang langsung tersedia.
4. Aktifkan fitur routing secara terpisah. Pertama ubah endpoint, lalu tambahkan alias, lalu failover berbasis kesehatan, lalu optimasi biaya atau kualitas.

Memisahkan perubahan-perubahan tersebut membuat insiden lebih mudah didiagnosis. Jika migrasi endpoint, penggantian model, kebijakan retry, dan optimizer biaya semuanya diluncurkan sekaligus, tim tidak akan tahu variabel mana yang menyebabkan regresi. Flatkey integration starter membahas pola migrasi base URL lebih rinci.

Daftar periksa kesiapan produksi

Gunakan daftar periksa ini sebelum memperlakukan gateway sebagai infrastruktur bersama.

Kontrak klien

• URL dasar yang stabil dan skema permintaan yang diberi versi
• Alias bernama dengan kemampuan minimum yang didokumentasikan
• Envelope error yang konsisten dan ID permintaan
• Streaming, pemanggilan tools, dan output terstruktur yang telah diuji

Identitas dan keamanan

• Kunci terpisah per layanan dan lingkungan
• Kredensial penyedia di sisi server
• Scope kunci, kuota, rotasi, dan pencabutan
• Logging prompt dan respons dinonaktifkan atau diatur secara eksplisit

Routing dan keandalan

• Filter kelayakan keras sebelum pemeringkatan biaya
• Kebijakan routing dan data harga yang diberi versi
• Kesehatan berdasarkan perilaku permintaan nyata
• Retry terbatas dengan satu batas waktu end-to-end
• Target fallback yang kompatibel dengan kontrak
• Circuit breaker dan probe pemulihan

Operasional

• Alasan rute, error penyedia, latensi, dan telemetri penggunaan
• Peringatan untuk tingkat fallback, tingkat error, drift biaya, dan tekanan kuota
• Kill switch per model dan per rute
• Runbook untuk gangguan penyedia dan gangguan gateway
• Jalur darurat langsung atau alternatif untuk workload kritis

Cara Flatkey sesuai dengan arsitektur ini

Flatkey menyediakan satu API key, satu base URL yang kompatibel dengan OpenAI, dan satu dashboard untuk akses model yang didukung, penggunaan, dan penagihan. Router-nya dirancang untuk mengurangi akun penyedia terpisah dan jalur integrasi yang terfragmentasi sambil mendukung perpindahan upstream dan load balancing.

Bagi tim aplikasi, manfaat arsitekturalnya adalah batas klien yang stabil: arahkan klien yang kompatibel dengan OpenAI ke https://router.flatkey.ai/v1, pilih model yang didukung, dan pertahankan akses model di balik endpoint gateway yang sama. Tim tetap harus mendefinisikan kontrak tingkat aplikasi mereka sendiri, ambang evaluasi, cakupan kunci, anggaran kegagalan, dan ekspektasi fallback.

Arsitektur gateway terbaik tidak membuat routing menjadi tak terlihat. Arsitektur tersebut membuat routing menjadi dapat diubah, terbatas, dan dapat dijelaskan.

FAQ

Apa itu AI API gateway?

AI API gateway adalah perantara antara aplikasi dan penyedia model. Ia memusatkan autentikasi, akses model, routing, kontrol keandalan, pelacakan penggunaan, dan kebijakan sambil mengekspos API yang stabil bagi klien.

Apakah satu API key berarti setiap layanan berbagi kunci yang sama?

Tidak. Artinya aplikasi menggunakan kredensial yang diterbitkan gateway, alih-alih menangani setiap kredensial penyedia secara langsung. Layanan produksi, lingkungan, dan tim tetap harus menerima kunci terpisah dengan cakupan yang sesuai.

Apa itu model routing?

Model routing adalah proses menyaring model atau deployment yang memenuhi syarat dan memilih target berdasarkan kemampuan, kebijakan, kesehatan, latensi, kualitas, biaya, wilayah, atau kapasitas.

Apa strategi fallback yang paling aman?

Mulailah dengan model yang sama pada deployment atau akun lain yang sehat. Fallback lintas model sebaiknya dilakukan hanya setelah pengujian menunjukkan bahwa target alternatif mempertahankan skema, tool, streaming, keamanan, dan kontrak kualitas aplikasi.

Bisakah gateway mencoba ulang respons streaming ke model lain?

Biasanya tidak setelah output mencapai klien. Beralih di tengah streaming dapat menggabungkan respons parsial yang tidak kompatibel. Gunakan error stream yang jelas kecuali klien dan gateway menerapkan protokol resume yang eksplisit.

Apakah API yang kompatibel dengan OpenAI cukup untuk migrasi tanpa perubahan?

Itu mengurangi perubahan pada SDK dan bentuk permintaan, tetapi tim tetap perlu memverifikasi parameter yang didukung, error, event streaming, panggilan tool, output terstruktur, akuntansi token, dan perilaku model.