Circuit breaker LLM API gateway menghentikan aplikasi agar tidak berulang kali mengirim trafik ke rute yang sudah gagal. Tanpa pagar pengaman itu, timeout dapat memicu retry, retry dapat memicu percobaan fallback, percobaan fallback dapat memicu lebih banyak error provider, dan aplikasi bisa mengubah satu insiden upstream menjadi loop kegagalan provider.
Tujuannya bukan menggantikan retry atau fallback model. Tujuannya adalah menentukan kapan sebuah rute sudah cukup tidak sehat sehingga gateway harus berhenti mencobanya untuk sementara, mengirim probe terkontrol nanti, dan memilih hasil yang lebih aman saat breaker terbuka: fallback, antre, degradasi, atau fail closed.
Flatkey relevan karena flatkey.ai secara publik memposisikan produknya di sekitar satu API key, OpenAI-compatible base URL di https://router.flatkey.ai/v1, routing, penagihan terpadu, analitik penggunaan, kontrol dashboard, switching otomatis, load balancing, dan batas kuota. Itu adalah titik pusat yang berguna untuk pekerjaan reliabilitas. Namun hal-hal tersebut tidak menghilangkan kebutuhan untuk mendefinisikan kebijakan circuit breaker LLM API gateway yang jelas untuk alur kerja aplikasi Anda sendiri.
Jawaban Cepat: Apa yang Harus Dilakukan Circuit Breaker LLM API Gateway
Circuit breaker LLM API gateway yang praktis memiliki tiga state rute dan satu jalur fail-closed. Jaga kebijakannya tetap sederhana agar engineer on-call dapat menjelaskannya saat terjadi insiden.
| State | Perilaku Gateway | Apa yang Mengubahnya | Bukti yang Perlu Dicatat |
|---|---|---|---|
| Closed | Trafik dapat menggunakan provider, model, family endpoint, akun, atau grup rute. | Rasio error, rasio timeout, latensi, respons overload, atau health probe yang gagal melewati ambang batas. | ID kebijakan rute, model yang dipilih, provider, family endpoint, latensi, status code, jumlah retry, dan biaya. |
| Open | Gateway berhenti mengirim trafik normal ke rute yang tidak sehat selama jendela cooldown. | Cooldown berakhir, atau operator secara manual mengizinkan sebuah probe. | Alasan breaker, waktu dibuka, jumlah percobaan yang diblokir, rute fallback, keputusan antre, atau alasan fail-closed. |
| Half-open | Gateway mengizinkan sejumlah terbatas request probe sebelum memulihkan trafik. | Probe yang berhasil menutup breaker; probe yang gagal membukanya lagi. | Ukuran sampel probe, workflow probe, hasil probe, latensi, penggunaan, dan persetujuan pemilik rute. |
| Fail closed | Gateway menolak merutekan request karena masalahnya bukan isu kesehatan provider. | Risiko auth, kebijakan, kuota, safety, batas data, request tidak valid, atau side effect dari tool. | Alasan penghentian, pemilik, pesan yang terlihat oleh pengguna, dan jalur remediasi. |
Mengapa Retry Menciptakan Loop Kegagalan Provider
Retry berguna ketika sebuah request gagal karena alasan yang bersifat sementara. Retry menjadi berbahaya ketika setiap request pengguna menciptakan beberapa panggilan upstream tambahan, terutama selama outage provider atau jendela overload. Loop retry dapat menghabiskan rate limit, menghabiskan kuota, meningkatkan latensi, dan menyembunyikan kegagalan awal di balik error akhir.
Circuit breaker mengubah pertanyaan tentang retry. Alih-alih bertanya, "Apakah request tunggal ini harus di-retry lagi?", gateway bertanya, "Apakah rute ini cukup sehat untuk menerima lebih banyak trafik saat ini?" Pandangan di level rute ini penting untuk workload LLM karena setiap request bisa mahal, berjalan lama, streaming, menggunakan tool, dan terlihat oleh pelanggan.
Pola desain cloud Microsoft untuk circuit breaker menjelaskan ide inti yang sama untuk layanan remote: setelah kegagalan berulang, circuit terbuka sehingga aplikasi tidak terus mencoba operasi yang kemungkinan besar akan gagal. Untuk rute AI, pola yang sama memerlukan batasan spesifik LLM: perilaku model, family endpoint, token spend, state streaming, side effect tool, kelas data, dan persetujuan fallback.
Klasifikasikan Error Sebelum Mencapai Breaker
Cara tercepat untuk membangun AI API circuit breaker yang buruk adalah dengan menganggap setiap kegagalan sebagai kesehatan provider. Itu menciptakan false positive. Itu juga bisa menyembunyikan masalah yang harus diperbaiki oleh pemilik aplikasi.
| Error Atau Peristiwa | Keputusan Breaker | Alasan | Hasil Default |
|---|---|---|---|
| Provider 500, 503, overload, unavailable, connection failure, repeated upstream timeout | Dihitung terhadap kesehatan route. | Ini adalah sinyal kesehatan provider, route, kapasitas, atau jaringan yang masuk akal. | Coba ulang dalam batas anggaran yang ketat, lalu buka route breaker jika ambang batas terlampaui. |
| 429 request-rate limit | Klasifikasikan dengan hati-hati. | Sinyal overload di seluruh provider dan lonjakan yang dibuat aplikasi memerlukan penanganan yang berbeda. | Throttle, lakukan back off, atau buka hanya route ter-scope yang benar-benar jenuh. |
| 429 monthly quota, exhausted credits, or spend limit | Jangan dihitung sebagai kesehatan provider. | Ini adalah kondisi anggaran atau pemilik akun. | Fail closed, kirim peringatan ke pemilik anggaran, atau route hanya jika ada anggaran yang sudah disetujui sebelumnya. |
| 401 auth, incorrect key, organization membership, IP allowlist, unsupported region | Jangan dihitung sebagai kesehatan provider. | Permintaan tidak diizinkan menggunakan route tersebut. | Fail closed dan perbaiki kredensial, akun, IP, atau kebijakan region. |
| Invalid request, unsupported parameter, unsupported model, malformed schema | Jangan dihitung sebagai kesehatan provider. | Aplikasi mengirim bentuk permintaan yang tidak dapat dilayani route tersebut. | Perbaiki permintaan atau pilih model yang kompatibel sebelum routing. |
| Safety, moderation, DLP, compliance, or unapproved data-class block | Jangan pernah melewati dengan fallback. | Routing ke model lain dapat melanggar batas kebijakan. | Fail closed dan catat keputusan kebijakan. |
| Tool already executed, partial stream already shown, user cancelled request | Jangan memutar ulang secara diam-diam. | Aplikasi dapat membuat efek samping duplikat atau menggabungkan dua output model. | Tandai sebagai tidak lengkap, minta retry eksplisit dari pengguna, atau gunakan jalur pemulihan idempotent. |
Panduan kode error OpenAI adalah contoh berguna mengapa taksonomi ini penting: panduan tersebut memisahkan masalah autentikasi dan IP allowlist, masalah unsupported-region, rate limit, kehabisan kuota, error server, overload, dan perlambatan mendadak pada request-rate. Dokumentasi Anthropic dan Google Gemini membuat perbedaan serupa antara rate limit, kondisi overload/unavailable, invalid request, serta masalah izin atau kuota. LLM API gateway circuit breaker Anda harus memisahkan kelas-kelas tersebut sebelum membuka route.
Scope The Breaker To The Smallest Route That Explains The Failure
Breaker yang terlalu luas menyebabkan downtime yang tidak perlu. Breaker yang terlalu sempit membiarkan loop kegagalan provider yang sama terus berlanjut melalui jalur di sekitarnya. Beri scope breaker ke dimensi route terkecil yang menjelaskan insiden tersebut.
| Scope | Gunakan Saat | Risiko Jika Scope Salah |
|---|---|---|
| Provider | Beberapa model dari provider yang sama tidak tersedia atau mengalami overload. | Terlalu luas jika hanya satu model, akun, atau keluarga endpoint yang gagal. |
| Model | Satu keluarga model mengalami 5xx berulang, timeout, atau error unsupported-route. | Terlalu sempit jika akun upstream atau provider sedang jenuh. |
| Keluarga endpoint | Chat berfungsi tetapi Responses, image, video, Anthropic Messages, atau route Gemini berperilaku berbeda. | Menggabungkan keluarga endpoint dapat menyembunyikan kegagalan spesifik protokol. |
| Akun, grup, region, atau path vendor | Hanya satu akun upstream, grup routing, region, atau path vendor yang gagal. | Gagal mengisolasi dapat menghabiskan kapasitas sehat di tempat lain. |
| Workflow | Tool calls, streaming, batch jobs, atau chat yang berhadapan dengan pelanggan memiliki aturan safety dan replay yang berbeda. | Route yang aman untuk batch enrichment mungkin tidak aman untuk stream pengguna langsung. |
Bagi pengguna Flatkey, ini berarti Anda harus melakukan pengujian dari workflow dan route yang benar-benar akan Anda gunakan. Snapshot API harga Flatkey saat ini untuk artikel ini mengembalikan 638 baris model, 23 vendor, dan keluarga endpoint untuk OpenAI chat completions, OpenAI Responses, Anthropic messages, Gemini generateContent, image generation, dan OpenAI video. Perlakukan itu sebagai bukti yang sudah kedaluwarsa dari 18 Juni 2026, bukan sebagai kontrak route permanen.
Set Thresholds That Match LLM Traffic
LLM API gateway circuit breaker seharusnya tidak terbuka karena satu kegagalan yang terisolasi. Ia juga tidak seharusnya menunggu sampai setiap permintaan pelanggan gagal. Gunakan threshold yang menggabungkan volume trafik minimum, rasio kegagalan, latensi, dan cooldown.
| Ambang Batas | Titik Awal Praktis | Mengapa Ini Penting |
|---|---|---|
| Ukuran sampel minimum | Buka hanya setelah cukup banyak permintaan atau probe telah diamati. | Mencegah satu completion yang mahal membuka rute global. |
| Rasio kegagalan | Lacak kegagalan upstream yang bisa di-retry secara terpisah dari kegagalan milik aplikasi. | Mencegah error auth, kuota, dan permintaan yang tidak valid merusak kesehatan rute. |
| Ambang latensi atau timeout | Gunakan anggaran timeout khusus endpoint untuk jalur chat, streaming, gambar, dan video. | Ambang yang baik untuk chat bisa saja salah untuk video atau pembuatan batch. |
| Cooldown saat terbuka | Tahan rute tetap terbuka cukup lama untuk menghentikan badai retry, lalu lakukan probe. | Melindungi baik provider maupun antrean permintaan Anda sendiri. |
| Batas probe half-open | Izinkan sejumlah kecil permintaan uji yang terkontrol sebelum menutup. | Mencegah lonjakan trafik penuh ketika provider baru pulih sebagian. |
| Plafon biaya | Tetapkan estimasi pengeluaran maksimum untuk retry, fallback, dan probe. | Mencegah pemulihan reliabilitas berubah menjadi insiden penagihan. |
Batas laju adalah bagian dari pembahasan ambang batas. Panduan batas laju OpenAI menjelaskan bahwa batas laju melindungi dari penyalahgunaan, memastikan akses yang adil, dan membantu mengelola beban agregat. Jika aplikasi Anda terus retry ke rute yang dibatasi laju, pola trafik Anda sendiri bisa menjadi insiden. LLM API gateway circuit breaker harus bekerja bersama pacing di sisi klien, antrean, dan kontrol kuota, bukan melawannya.
Tentukan Apa yang Terjadi Saat Breaker Terbuka
Membuka breaker hanya berguna jika gateway memiliki aksi berikutnya yang jelas. Jangan biarkan setiap rute yang terbuka otomatis fallback ke model apa pun yang tersedia.
| Aksi Saat Status Open | Gunakan Saat | Guardrail yang Diperlukan |
|---|---|---|
| Rute fallback | Model atau provider cadangan sudah disetujui untuk workflow tersebut. | Jalankan evaluasi, skema, alat, batas data, dan pemeriksaan biaya yang sama sebelum produksi. |
| Antrekan | Job bersifat asinkron atau pengalaman pengguna masih dapat menoleransi penundaan. | Pertahankan metadata owner, customer, model, biaya, dan retry. |
| Degrade | Hasil parsial dengan risiko lebih rendah dapat diterima, seperti respons cache atau fitur yang dikurangi. | Buat status degraded terlihat oleh aplikasi dan log. |
| Fail closed | Permintaan memiliki risiko kebijakan, anggaran, keamanan, auth, wilayah, atau efek samping. | Kembalikan error yang jelas dan beri tahu owner yang tepat alih-alih mencoba model lain. |
Dokumentasi publik Vercel AI Gateway menjelaskan fallback model sebagai pola gateway dengan model cadangan berurutan. Gunakan itu hanya sebagai bukti kategori. Dalam stack Anda sendiri, fallback adalah keputusan persetujuan yang terpisah. Breaker menentukan apakah suatu rute saat ini sehat; fallback menentukan apakah rute lain diizinkan untuk melayani permintaan yang sama.
Streaming Dan Tool Calls Memerlukan Penghentian Tambahan
Streaming membuat loop kegagalan provider lebih mudah disembunyikan. Jika aplikasi diam-diam memulai ulang permintaan setelah output parsial, pengguna bisa melihat jawaban gabungan dari dua percobaan. Tool calls menambah masalah kedua: retry atau fallback dapat menggandakan refund, pembaruan tiket, email, penulisan database, atau tindakan eksternal.
Gunakan aturan berikut dalam kebijakan LLM API gateway circuit breaker:
- Sebelum output pertama: retry atau fallback dapat diizinkan jika rute disetujui dan breaker tertutup atau half-open.
- Setelah output pertama: tandai stream sebagai tidak lengkap dan minta retry eksplisit dari pengguna alih-alih fallback diam-diam.
- Setelah eksekusi tool: jangan ulangi kecuali tool bersifat idempotent dan operasi memiliki replay key.
- Setelah pemblokiran kebijakan: fail closed. Jangan arahkan ke model lain untuk melewati blok.
Ini selaras dengan panduan strategi retry AI API, daftar periksa evaluasi fallback model, dan load balancing dan failover AI API. Breaker harus berbagi taksonomi kegagalan yang sama seperti playbook tersebut.
Field Observabilitas Untuk Review Circuit Breaker
Jika sebuah permintaan berhasil hanya karena gateway diam-diam melewati rute yang rusak, insiden itu tetap harus terlihat. Dokumentasi Cloudflare AI Gateway memberikan contoh publik pola observabilitas AI gateway: log permintaan dapat mencakup provider, status, token, biaya, dan durasi, dan metadata kustom dapat menandai permintaan untuk penyaringan di kemudian hari. Log gateway Anda harus memberikan tingkat bukti rute yang sama untuk keputusan breaker.
| Field | Mengapa Operator Membutuhkannya |
|---|---|
| ID dan versi kebijakan breaker | Menunjukkan aturan mana yang membuka, menutup, atau melewati rute. |
| Status breaker pada waktu keputusan | Menjelaskan apakah rute dalam keadaan tertutup, terbuka, setengah terbuka, atau fail-closed. |
| Model yang diminta, model yang dipilih, provider, akun, grup, dan keluarga endpoint | Memisahkan intent pengguna dari keputusan rute gateway. |
| Kelas error per percobaan | Membedakan kegagalan upstream dari auth, kuota, request tidak valid, kebijakan, dan error tool. |
| Latensi, timeout, jumlah retry, dan hasil probe | Menunjukkan apakah rute gagal secara lambat, gagal cepat, atau pulih selama probing half-open. |
| Flag output parsial dan status side effect tool | Mencegah insiden output campuran tersembunyi atau aksi duplikat. |
| Usage, biaya, pemilik kuota, dan disposisi akhir | Menghubungkan pemulihan keandalan dengan pengeluaran, anggaran, dan akuntabilitas. |
Artikel pendamping log observabilitas AI API membahas lebih dalam tentang logging insiden. Untuk circuit breaker, prioritaskan status rute dan alasan spesifik mengapa sebuah request diblokir, diprobe, diarahkan, dikantrekan, atau gagal closed.
Rencana Rollout Flatkey untuk Kebijakan Circuit Breaker
Gunakan pendekatan bertahap ini sebelum mengandalkan LLM API gateway circuit breaker untuk traffic pelanggan melalui Flatkey atau gateway yang kompatibel dengan OpenAI apa pun.
- Buat staging key: pisahkan pengujian breaker dari traffic pelanggan production.
- Konfirmasi route dasar: arahkan klien yang kompatibel dengan OpenAI ke
https://router.flatkey.ai/v1dan verifikasi model, keluarga endpoint, baris usage, serta visibilitas dashboard. - Snapshot katalog route: simpan halaman pricing Flatkey dan respons API pricing pada tanggal rollout agar asumsi route dan harga dapat diaudit.
- Definisikan taksonomi error: tentukan error mana yang dihitung terhadap health rute dan mana yang fail closed sebelum breaker melihatnya.
- Mulai dengan satu workflow: terapkan breaker pada satu route model, satu keluarga endpoint, dan satu kelas traffic sebelum memperluas.
- Paksa pengujian kegagalan: simulasi timeout provider, 500, 503, request-rate 429, kuota habis, kegagalan auth, request tidak terformat, partial stream, dan side effect tool.
- Verifikasi perilaku open-state: pastikan tindakan fallback, queue, degrade, atau fail-closed sesuai dengan matriks persetujuan.
- Tinjau log dan billing: pastikan status breaker, route terpilih, usage, biaya, dan pemilik kuota terlihat setelah setiap pengujian.
- Tetapkan rollback: nonaktifkan kebijakan jika terlalu luas membuka, menyembunyikan error milik aplikasi, atau memicu pengeluaran yang tidak terduga.
Template Kebijakan Circuit Breaker
Template ini bukan kontrak API Flatkey. Perlakukan ini sebagai artefak review untuk pemilik engineering, product, finance, dan security.
{
"policy_id": "support-chat-provider-breaker-v1",
"workflow": "customer-support-chat",
"environment": "production",
"route_scope": {
"provider": "primary-provider",
"model": "primary-approved-model",
"endpoint_family": "openai-chat-completions",
"traffic_class": "customer-visible-stream"
},
"count_toward_breaker": [
"upstream_5xx",
"provider_overloaded",
"provider_unavailable",
"upstream_timeout",
"connection_reset"
],
"fail_closed_before_breaker": [
"auth_error",
"ip_allowlist_error",
"unsupported_region",
"quota_exhausted",
"invalid_request",
"schema_incompatible",
"safety_or_policy_block",
"unapproved_data_class",
"tool_side_effect_already_committed"
],
"thresholds": {
"window_seconds": 60,
"minimum_requests": 20,
"failure_ratio_to_open": 0.5,
"timeout_ratio_to_open": 0.4,
"open_cooldown_seconds": 90,
"half_open_probe_requests": 3,
"max_total_attempts_per_request": 2
},
"open_state_action": {
"default": "fail_closed",
"allowed_fallback_policy_ids": [
"support-chat-fallback-v1"
],
"allow_after_partial_output": false,
"allow_after_tool_side_effect": false
},
"logging": {
"record_breaker_state": true,
"record_route_scope": true,
"record_error_class_per_attempt": true,
"record_probe_results": true,
"record_usage_cost_and_quota_owner": true
}
}FAQ
Apa itu circuit breaker pada LLM API gateway?
LLM API gateway circuit breaker adalah kebijakan health rute yang menghentikan traffic normal agar tidak mengenai model, provider, akun, atau keluarga endpoint yang tidak sehat setelah kegagalan retryable berulang. Kebijakan ini membuka untuk jendela cooldown, mengizinkan probe half-open terbatas, dan hanya menutup setelah rute terlihat sehat lagi.
Error LLM API mana yang harus membuka circuit breaker?
Error 5xx di sisi provider, overload, respons unavailable, kegagalan koneksi, dan timeout upstream yang berulang adalah kandidat umum. Error auth, kegagalan IP allowlist, region yang tidak didukung, kuota habis, request yang salah format, blokir kebijakan, dan side effect tool biasanya harus fail closed, bukan membuka breaker kesehatan provider.
Apa perbedaan circuit breaker dengan retry atau fallback?
Retry menentukan apakah satu request perlu dicoba lagi. Fallback menentukan apakah route lain yang disetujui dapat melayani request. Circuit breaker menentukan apakah suatu route boleh menerima traffic normal sama sekali ketika terlihat tidak sehat.
Haruskah circuit breaker diterapkan pada respons streaming LLM?
Ya, tetapi dengan batas yang lebih ketat. Sebuah breaker dapat melindungi rute sebelum token yang terlihat pertama kali muncul. Setelah output parsial atau efek samping tool, aplikasi tidak boleh diam-diam mengulang atau melakukan fallback kecuali alur kerja tersebut secara eksplisit dirancang untuk pemulihan yang idempoten.
Pemeriksaan Akhir Sebelum Anda Mengaktifkan Breaker
Sebelum Anda mengaktifkan circuit breaker gateway API LLM, ajukan satu pertanyaan: jika rute ini terbuka saat terjadi insiden pada provider, apakah tim dapat menjelaskan apa yang gagal, mengapa traffic normal berhenti, ke mana traffic dialihkan selanjutnya, berapa biayanya, dan bagaimana menutup atau memutar balik kebijakan tersebut?
Jika jawabannya tidak, tetap biarkan breaker di staging. Jika jawabannya ya, gunakan akses model terpusat Flatkey, routing, visibilitas penggunaan, penagihan, dan kontrol kuota sebagai bagian dari loop peninjauan. Saat Anda siap memvalidasi rute di belakang satu gateway yang kompatibel dengan OpenAI, dapatkan key dan mulai dengan satu workflow, satu rute model, dan satu kebijakan breaker.
