LLM API gateway adalah control plane antara kode aplikasi dan beberapa penyedia model. Arsitektur yang berguna bukan sekadar URL proxy. Ia harus mengautentikasi caller, memetakan model, menerapkan kebijakan, memilih rute upstream, menegakkan kuota, mencatat penggunaan, menghitung biaya, dan menentukan apa yang terjadi ketika penyedia gagal.
Panduan ini memberikan kepada para platform engineer sebuah diagram arsitektur LLM API gateway yang praktis untuk routing multi-provider dan failover. Panduan ini menggunakan pola gateway publik dari Vercel dan Pydantic sebagai referensi kategori, lalu membatasi klaim spesifik Flatkey pada bukti publik saat ini: satu API key, endpoint router yang kompatibel dengan OpenAI di https://router.flatkey.ai/v1, harga yang jelas, penagihan terpadu, dashboard untuk key, penggunaan, dan routing, switching otomatis, serta load balancing.
Tujuannya adalah membantu Anda meninjau desain sebelum trafik produksi bergantung padanya. Gunakan diagram ini sebagai checklist untuk gateway Anda sendiri, evaluasi vendor, atau pengujian staging Flatkey.
Diagram Arsitektur LLM API Gateway
Diagram ini menunjukkan jalur permintaan dari aplikasi klien ke provider model upstream. Inti dari arsitektur ini adalah LLM API gateway. Di sekelilingnya ada layanan kebijakan yang membuat routing aman dioperasikan: cakupan kunci, pemetaan model, kelas rute, buku besar kuota, penagihan, log, pemeriksaan kesehatan, dan aturan fallback.
| Layer | Tanggung Jawab | Pertanyaan Desain |
|---|---|---|
| Aplikasi klien | Mengirim permintaan chat, respons, gambar, video, agent, atau tool. | SDK dan format endpoint mana yang harus tetap berfungsi? |
| Endpoint gateway | Menerima permintaan melalui base URL dan API key yang stabil. | Apakah aplikasi dapat bermigrasi hanya dengan mengubah kunci, base URL, atau konfigurasi provider? |
| Autentikasi dan cakupan kunci | Mengidentifikasi pemanggil, tim, aplikasi, lingkungan, dan kumpulan model yang diizinkan. | Bisakah traffic staging, produksi, dan pelanggan dipisahkan? |
| Mesin kebijakan | Menerapkan pemetaan model, kelas rute, anggaran, kuota, dan aturan fallback. | Apakah kebijakan menjelaskan mengapa suatu permintaan bisa atau tidak bisa menggunakan sebuah rute? |
| Router | Memilih provider upstream, akun, model, atau jalur cadangan. | Apakah routing didasarkan pada kebijakan yang disetujui, bukan sihir tersembunyi? |
| Kesehatan dan failover | Melacak error provider, timeout, retry, fallback, dan kondisi berhenti. | Failure mana yang harus retry, switch, antre, atau fail closed? |
| Log, kuota, dan penagihan | Mencatat model, rute, status, token atau unit media, biaya, pemilik, dan kunci. | Bisakah engineer dan finance menelusuri permintaan setelah insiden? |
| Provider upstream | Menyajikan model yang dipilih melalui API native provider atau yang kompatibel. | Provider mana yang disetujui untuk setiap kelas traffic? |
Cara Permintaan Bergerak Melalui Gateway
LLM API gateway produksi seharusnya membuat jalur permintaan mudah dijelaskan. Jika tim Anda tidak bisa menggambar jalurnya, kemungkinan besar Anda juga tidak bisa men-debug jalur itu saat outage atau review penagihan.
- Klien mengirim permintaan. Aplikasi memanggil gateway dengan nama model, endpoint, input pesan atau media, dan API key aplikasi.
- Gateway mengautentikasi kunci. Kunci dipetakan ke pemilik, lingkungan, kuota, kumpulan model yang diizinkan, dan kebijakan logging.
- Mesin kebijakan mengklasifikasikan traffic. Permintaan ditandai sebagai chat pelanggan, pekerjaan latar belakang, evaluasi, pembuatan media, traffic tool coding, atau kelas rute lainnya.
- Router memilih rute kandidat. Router memeriksa pemetaan model, ketersediaan provider, akun upstream yang diizinkan, kebijakan biaya, status kuota, serta prioritas atau bobot yang dikonfigurasi.
- Gateway mengirim permintaan upstream. Bergantung pada provider dan endpoint, ini dapat mempertahankan bentuk permintaan yang kompatibel dengan OpenAI atau menggunakan protokol native provider.
- Respons dinormalisasi jika memungkinkan. Gateway mengembalikan bentuk respons, error, streaming, atau referensi job yang diharapkan ke klien.
- Permintaan dicatat. Log menangkap rute, model, status, latensi, unit penggunaan, estimasi biaya, kunci, dan pemilik sehingga tim dapat men-debug dan merekonsiliasi pengeluaran.
Inilah sebabnya langkah migrasi API yang kompatibel dengan OpenAI hanya satu bagian dari arsitektur. Mengubah base URL memang membawa traffic ke gateway. Kesiapan produksi bergantung pada kebijakan, routing, kuota, penagihan, log, dan perilaku fallback setelah itu.
Kebijakan Routing Didahulukan Sebelum Failover
Kesalahan arsitektur yang paling umum adalah memperlakukan failover sebagai sesuatu yang selalu baik. LLM API gateway seharusnya tidak secara buta mengulang setiap permintaan yang gagal ke setiap provider. Gateway harus terlebih dahulu memutuskan apakah jalur cadangan diizinkan untuk kelas traffic tersebut.
Dokumentasi publik gateway menunjukkan mengapa perbedaan ini penting. Pydantic mendokumentasikan grup routing di mana provider dapat memiliki prioritas, bobot, dan status aktif, sehingga memungkinkan failover antar provider yang melayani model yang sama atau load balancing di antara anggota dengan prioritas yang sama. Vercel memposisikan AI Gateway di sekitar routing, penagihan, observabilitas, banyak model, serta routing provider/model dengan fallback. Pola-pola itu berguna sebagai referensi, tetapi kebijakan produksi Anda tetap harus menentukan apa yang dapat diterima untuk beban kerja Anda.
| Kelas Traffic | Aturan Routing Utama | Aturan Failover |
|---|---|---|
| Chat yang menghadap pelanggan | Gunakan hanya keluarga model dan provider yang disetujui. | Beralih hanya ke padanan yang disetujui, atau kembalikan error yang terkendali. |
| Ringkasan latar belakang | Utamakan biaya dan throughput ketika persyaratan kualitas stabil. | Retry, antre, atau gunakan model berbiaya lebih rendah yang disetujui jika kualitas output tetap dapat diterima. |
| Evaluasi dan benchmark | Jaga identitas model tetap stabil. | Fail closed; fallback tersembunyi membuat hasil sulit dibandingkan. |
| Pembuatan media | Hormati bentuk endpoint, siklus hidup job, kebijakan media, dan anggaran. | Fail closed kecuali model alternatif memiliki kontrak output yang sama dan disetujui. |
| Alur kerja agent | Hormati dukungan tool, batas konteks, batas data, dan kebutuhan audit. | Fallback hanya ketika perilaku tool dan penanganan data tetap valid. |
Salinan publik Flatkey menyatakan bahwa produk ini merutekan beberapa akun upstream dengan switching otomatis dan load balancing. Gunakan itu sebagai titik awal produk, lalu tentukan kelas traffic mana yang boleh beralih otomatis dan mana yang harus fail closed.
Failover Membutuhkan Kondisi Berhenti
Setiap desain failover LLM API gateway membutuhkan kondisi berhenti. Tanpa itu, permintaan yang salah format bisa berubah menjadi rangkaian panggilan invalid yang berulang, biaya ganda, log yang membingungkan, dan perilaku pengguna yang tidak konsisten.
Urutan kegagalan yang praktis terlihat seperti ini:
- Tolak sebelum upstream: fail closed untuk auth yang invalid, model yang dilarang, kuota terlampaui, endpoint yang tidak didukung, atau parameter wajib yang hilang.
- Retry rute yang sama: retry hanya ketika error kemungkinan bersifat sementara, seperti network timeout atau 5xx dari upstream yang dipilih.
- Beralih dengan kontrak yang sama: gunakan akun, region, atau jalur provider lain hanya jika melayani kontrak model yang sama dan disetujui.
- Gunakan cadangan yang disetujui: pindah ke model lain hanya ketika pemilik produk, kualitas, kepatuhan, dan anggaran menyetujui cadangannya.
- Antre atau degradasi: tunda pekerjaan yang tidak mendesak ketika fallback segera akan mahal atau berisiko.
- Kembalikan error yang terkendali: berhenti ketika kebijakan menyatakan tidak ada rute aman yang tersisa.
Panduan load balancing dan failover AI API membahas ini lebih rinci. Dalam review arsitektur, pertanyaan pentingnya adalah apakah setiap transisi bersifat eksplisit dan dapat diamati.
Kuota, Penagihan, Dan Log Adalah Bagian Dari Jalur Permintaan
Traffic model tidak ditagih seperti traffic HTTP biasa. Satu LLM API gateway mungkin harus memperhitungkan input token, output token, cached token, reasoning token, unit gambar, durasi video, panggilan tool, retry, dan unit kuota spesifik provider. Jika penagihan dan kuota diperlakukan sebagai laporan malam hari, gateway tidak dapat mencegah penggunaan yang tak terkendali pada saat itu juga.
Tempatkan kuota dan penagihan dekat dengan kebijakan routing:
- Periksa sisa anggaran pemanggil sebelum meneruskan permintaan yang mahal.
- Blokir atau beri peringatan pada rute dengan data harga yang hilang ketika batas pengeluaran penting.
- Catat model yang dipilih, keluarga endpoint, rute upstream, kunci, pemilik, status, dan unit penggunaan.
- Pisahkan panggilan retry dan fallback di log agar satu permintaan pengguna tidak menutupi beberapa percobaan provider.
- Buat kunci staging dan produksi terlihat sebagai cost center yang berbeda.
- Ekspor data yang cukup untuk finance, support, dan review insiden.
Posisi publik Flatkey saat ini mencakup harga yang jelas, penagihan terpadu, visibilitas penggunaan, batas kuota, dan satu dashboard untuk kunci, penggunaan, dan routing. Snapshot API harga pada hari peluncuran menunjukkan 656 baris model dan mendukung metadata endpoint untuk traffic OpenAI-compatible, OpenAI Responses, Anthropic, Gemini, pembuatan gambar, dan pembuatan video. Perlakukan itu sebagai bukti yang bertanggal, lalu verifikasi model dan unit yang tepat pada halaman harga langsung.
Di Mana Flatkey Cocok Dalam Arsitektur Ini
Flatkey dirancang untuk mengurangi penyebaran akun provider di balik satu kunci. Dalam arsitektur LLM API gateway ini, Flatkey memetakan ke endpoint gateway yang di-host, layer akses provider, dashboard, layer penggunaan/penagihan, dan layer routing.
Pengujian staging Flatkey yang cermat seharusnya terlihat seperti ini:
- Buat kunci non-produksi di dashboard Flatkey.
- Arahkan satu klien ke
https://router.flatkey.ai/v1. - Jalankan permintaan yang sudah diketahui baik untuk keluarga endpoint yang Anda perlukan.
- Pastikan permintaan muncul di log penggunaan dengan model, status, unit, dan bukti biaya.
- Tinjau halaman harga live untuk model dan unit penagihan yang dipilih.
- Tentukan kelas traffic mana yang dapat menggunakan switching otomatis atau load balancing.
- Jalankan satu uji kegagalan yang aman, atau dokumentasikan mengapa simulasi kegagalan tidak diizinkan di staging.
Jangan menyimpulkan SLA uptime, jaminan latensi, algoritma routing yang tepat, atau ketersediaan provider yang dijamin dari artikel ini. Arsitektur memberi tahu apa yang harus divalidasi; bukti staging Anda memberi tahu apakah rollout tertentu siap.
Daftar Periksa Implementasi
Sebelum mengirim traffic produksi melalui LLM API gateway, pastikan arsitektur memiliki kontrol berikut:
| Item Daftar Periksa | Kondisi Lulus |
|---|---|
| Migrasi base URL dan SDK | Setidaknya satu permintaan staging berhasil melalui gateway dengan SDK atau klien yang dituju. |
| Pemetaan model dan endpoint | Setiap keluarga endpoint produksi memiliki model, protokol, dan pemilik yang disetujui. |
| Cakupan kunci | Kunci dipisahkan berdasarkan aplikasi, lingkungan, tim, atau pelanggan bila diperlukan. |
| Kebijakan routing | Kelas traffic mendefinisikan rute utama dan rute cadangan yang diizinkan. |
| Kondisi berhenti failover | Gateway tahu kapan harus retry, switch, antre, dan fail closed. |
| Pemeriksaan kuota dan anggaran | Batas dapat menghentikan atau membatasi traffic mahal sebelum mencapai provider upstream. |
| Log dan observabilitas | Bukti permintaan, rute, model, pemilik, status, penggunaan, dan biaya dapat ditinjau setelah kejadian. |
| Rollback | Aplikasi dapat kembali ke konfigurasi provider sebelumnya jika rollout gateway gagal. |
Untuk pandangan kebutuhan yang lebih luas, mulai dengan daftar periksa AI API gateway. Untuk pekerjaan perbandingan platform, panduan alternatif OpenRouter menunjukkan bagaimana tradeoff gateway terkelola berbeda dari marketplace provider dan lapisan routing yang dikelola sendiri.
Pertanyaan yang sering diajukan
Apa itu LLM API gateway?
LLM API gateway adalah layer kontrol di antara aplikasi dan provider model. Gateway ini dapat memusatkan API key, akses model, routing, kuota, penagihan, log, dan kebijakan failover untuk traffic LLM.
Apa saja yang harus ada dalam arsitektur LLM API gateway?
Arsitektur LLM API gateway harus mencakup aplikasi klien, endpoint gateway yang stabil, autentikasi, cakupan kunci, pemeriksaan kebijakan, pemetaan model, routing provider, pemeriksaan kesehatan, aturan failover, kuota, penagihan, log, dan provider upstream.
Apakah failover selalu aman untuk traffic LLM?
Tidak. Failover aman hanya ketika rute cadangan mempertahankan kontrak model yang disetujui, batas data, perilaku endpoint, ekspektasi kualitas, dan kebijakan biaya. Beberapa traffic harus fail closed daripada beralih.
Apa bedanya LLM API gateway dengan API gateway biasa?
API gateway biasa menangani traffic API umum. LLM API gateway menambahkan concern yang sadar-model seperti format provider, penggunaan token dan media, pemetaan model, kebijakan fallback, kontrol pengeluaran, observabilitas prompt/respons, dan routing khusus AI.
Di mana Flatkey cocok dalam diagram?
Flatkey cocok sebagai layer gateway yang di-host, router, akses provider, penggunaan, penagihan, dan dashboard. Salinan publiknya mendukung satu API key, https://router.flatkey.ai/v1, harga yang jelas, penagihan terpadu, visibilitas penggunaan/routing, switching otomatis, dan load balancing.
Inti Akhir
LLM API gateway produksi seharusnya membuat traffic model lebih mudah dikendalikan, bukan lebih sulit dijelaskan. Arsitektur membutuhkan endpoint yang stabil, kunci yang dibatasi cakupannya, pemetaan model, pemeriksaan kebijakan, aturan routing, kontrol kuota dan penagihan, log, dan kondisi berhenti failover.
Flatkey memberi tim satu kunci, endpoint router yang kompatibel dengan OpenAI, dan satu dashboard untuk akses model serta operasi. Untuk menguji arsitektur dengan workload staging Anda sendiri, dapatkan kunci dan verifikasi jalur permintaan sebelum memindahkan traffic produksi.
