LLM API Fallback Routing: Buku Panduan Failover Produksi

Fallback routing untuk API LLM terdengar sederhana sampai insiden nyata pertama terjadi: tangkap error, ganti model, lalu coba lagi. Di produksi, aturan itu bisa mengubah satu masalah pada penyedia menjadi panggilan alat duplikat, JSON rusak, output streaming tercampur, lalu lintas retry yang tak terkendali, atau respons yang secara teknis berhasil tetapi tidak lagi memenuhi kontrak produk.

Desain yang lebih aman memperlakukan fallback sebagai state machine terbatas, bukan daftar nama model cadangan. Setiap permintaan bergerak melalui serangkaian keputusan kecil:

1. Apakah kegagalannya layak di-retry?
2. Apakah aman untuk mengulang permintaan ini?
3. Apakah percobaan berikutnya harus menggunakan target yang sama atau yang berbeda?
4. Bisakah fallback mempertahankan kontrak yang diperlukan?
5. Apakah permintaan sudah menghasilkan output atau efek samping?
6. Apakah latensi end-to-end dan anggaran percobaan sudah habis?

Buku panduan ini mengubah pertanyaan-pertanyaan tersebut menjadi matriks error, kebijakan routing, controller TypeScript, rencana pengujian, dan checklist roll out untuk aplikasi LLM multi-pemilik layanan.

Empat tindakan di balik fallback routing API LLM yang andal

Jangan masukkan setiap error ke loop retry yang sama. Router produksi membutuhkan empat tindakan yang berbeda.

Perbedaan antara failover dan fallback itu penting. Failover mempertahankan kontrak model logis dan mengubah infrastruktur. Fallback mengubah model atau tingkat kapabilitas. Failover biasanya merupakan langkah dengan risiko lebih rendah.

Jika Anda memerlukan desain jalur permintaan yang lebih luas seputar alias, health scoring, billing, dan observabilitas, mulai dengan panduan arsitektur AI API gateway. Artikel ini berfokus pada controller yang berjalan setelah target dipilih.

Bangun matriks error-ke-tindakan sebelum menulis kode retry

SDK penyedia mengekspos kelas exception dan body respons yang berbeda-beda, tetapi router harus menormalkannya ke dalam taksonomi internal yang kecil.

Dokumentasi resmi penyedia memperkuat mengapa normalisasi diperlukan. Anthropic mendokumentasikan kesalahan rate-limit, API, dan overload yang berbeda, serta mencatat bahwa permintaan streaming masih bisa gagal setelah respons awal berhasil. OpenAI juga memisahkan permintaan tidak valid, rate limit, dan kegagalan sisi server. Aplikasi Anda harus menerjemahkan sinyal spesifik penyedia menjadi keputusan internal yang stabil, alih-alih menyematkan nama penyedia di seluruh logika bisnis.

Pasang satu retry budget di sekitar seluruh permintaan

Retry sering ada di beberapa tempat sekaligus: HTTP client, provider SDK, gateway, background job, dan application service. Jika tiap lapisan melakukan tiga percobaan, satu tindakan pengguna bisa berlipat menjadi jauh lebih banyak panggilan upstream daripada yang diinginkan tim.

Pola yang lebih aman adalah:

• Pilih satu lapisan untuk mengelola retry dan fallback LLM.
• Tetapkan satu deadline end-to-end untuk permintaan atau job pengguna.
• Tetapkan jumlah maksimum percobaan upstream.
• Cadangkan sebagian deadline untuk target fallback.
• Gunakan exponential backoff dengan jitter untuk kegagalan sementara.
• Berhenti ketika sisa waktu tidak cukup untuk satu percobaan yang bermakna lagi.

Pedoman AWS tentang timeout, retry, backoff, dan jitter menjelaskan bagaimana retry dapat memperbesar overload dan merekomendasikan perilaku yang dibatasi, alih-alih pengulangan instan yang konstan. Prinsip yang sama berlaku untuk API model, di mana provider yang sedang terbebani paling tidak mampu menyerap traffic retry yang tersinkronisasi.

Anggaran interaktif yang praktis dapat dinyatakan sebagai policy, bukan sleep yang di-hardcode:

type RetryBudget = {
  deadlineMs: number;
  maxAttempts: number;
  maxSameTargetAttempts: number;
  reserveForFallbackMs: number;
};

Nilai yang tepat bergantung pada produk. Antarmuka chat, coding agent, evaluator batch, dan workflow video asinkron tidak boleh berbagi anggaran yang sama.

Gunakan circuit breaker untuk menghentikan routing ke kegagalan yang sudah diketahui

Circuit breaker mencegah setiap request baru menemukan outage yang sama lagi.

Status standar adalah:

• Closed: request mengalir normal sementara router mengukur kegagalan dan latensi.
• Open: target sementara tidak memenuhi syarat karena perilaku terbarunya melewati ambang batas.
• Half-open: sejumlah kecil request probe menguji apakah target sudah pulih.

Pola circuit-breaker Azure menjelaskan siklus closed/open/half-open ini. Untuk routing LLM, kunci breaker harus cukup spesifik untuk mengisolasi permukaan yang gagal. Dimensi yang berguna mencakup provider, model, region, deployment, account, dan capability. Deployment text-completion bisa sehat sementara route tool-calling atau endpoint regional sedang gagal.

Hindari membuka circuit pada setiap client error. Autentikasi yang tidak valid, request yang salah format, context overflow, dan penolakan policy biasanya lebih menunjukkan masalah pada request daripada kesehatan provider. Breaker sebaiknya bereaksi terutama terhadap sinyal infrastruktur sementara seperti kegagalan koneksi, timeout, overload, dan server error.

Pertahankan kontrak kemampuan di seluruh model

Model fallback tidak aman hanya karena menerima request yang kompatibel dengan OpenAI. Definisikan kontrak minimum untuk setiap alias rute.

route: support-agent-v3
requires:
  modalities: [text]
  streaming: true
  tools: true
  parallel_tool_calls: false
  structured_output: json_schema
  context_window_min: 64000
  max_output_tokens_min: 4000
quality_gates:
  task_success_rate_min: 0.94
  schema_valid_rate_min: 0.995
policy:
  same_model_failover_first: true
  cross_model_fallback_allowed: true

Sebelum menambahkan target ke set fallback, uji setidaknya:

• Parameter permintaan yang didukung
• Definisi tool dan perilaku tool-call
• Validitas output terstruktur
• Bentuk event streaming
• Batas konteks dan output
• Perilaku keamanan yang sesuai untuk aplikasi
• Field penghitungan token yang digunakan oleh kontrol biaya
• Latensi dan kualitas pada prompt representatif

Pendekatan berbasis kontrak ini sangat penting untuk alur kerja yang melintasi modality. panduan routing agen multimodal membahas pemeriksaan tambahan untuk rute teks, gambar, audio, dan video.

A TypeScript fallback controller

Contoh berikut sengaja dibuat netral terhadap provider. Contoh ini mengasumsikan adapter hulu menormalisasi error dan respons sebelum lapisan routing melihatnya.

type FailureKind =
  | "connect"
  | "timeout"
  | "rate_limit"
  | "overloaded"
  | "server_error"
  | "invalid_request"
  | "auth"
  | "policy"
  | "context_overflow"
  | "partial_stream"
  | "unknown";

type Target = {
  id: string;
  contractId: string;
  healthy: boolean;
  circuit: "closed" | "open" | "half_open";
};

type RequestState = {
  attempt: number;
  sameTargetAttempts: number;
  deadlineAt: number;
  outputStarted: boolean;
  sideEffectsPossible: boolean;
};

function canReplay(state: RequestState): boolean {
  return !state.outputStarted && !state.sideEffectsPossible;
}

function isTransient(kind: FailureKind): boolean {
  return [
    "connect",
    "timeout",
    "rate_limit",
    "overloaded",
    "server_error",
  ].includes(kind);
}

function chooseNextAction(
  kind: FailureKind,
  state: RequestState,
  current: Target,
  equivalent: Target | undefined,
  fallback: Target | undefined,
) {
  if (!canReplay(state) || kind === "partial_stream") return { type: "stop" };

  if (!isTransient(kind)) return { type: "stop" };

  if (state.attempt >= 3 || Date.now() >= state.deadlineAt) {
    return { type: "stop" };
  }

  if (
    state.sameTargetAttempts < 1 &&
    current.circuit === "closed" &&
    current.healthy
  ) {
    return { type: "retry", target: current };
  }

  if (equivalent?.healthy && equivalent.circuit !== "open") {
    return { type: "failover", target: equivalent };
  }

  if (
    fallback?.healthy &&
    fallback.circuit !== "open" &&
    fallback.contractId === current.contractId
  ) {
    return { type: "fallback", target: fallback };
  }

  return { type: "stop" };
}

Kode produksi juga memerlukan delay dengan jitter, propagasi pembatalan, request ID, pembaruan circuit breaker, telemetri, dan parsing error khusus adapter. Properti pentingnya adalah keamanan replay dan kompatibilitas kontrak diperiksa sebelum target lain dipilih.

Anggap fallback streaming sebagai protokol terpisah

Streaming menciptakan batas yang tegas: begitu konten mencapai klien, gateway tidak lagi bisa berpura-pura bahwa percobaan itu tidak pernah terjadi.

Jika upstream gagal sebelum event pertama diteruskan, retry atau fallback masih bisa berjalan transparan. Setelah token pertama, delta tool, event gambar, atau chunk audio dikirim, pergantian model otomatis berisiko menggabungkan dua respons yang tidak kompatibel.

Gunakan salah satu strategi eksplisit berikut:

1. Gagalkan stream dengan jelas. Kembalikan event error yang stabil dengan request ID dan biarkan client menawarkan retry.
2. Buffer sebelum dilepas. Untuk respons terstruktur yang pendek, validasi hasil lengkap sebelum mengirimkannya ke downstream. Ini mengorbankan time-to-first-token.
3. Implementasikan resume di level aplikasi. Mulai turn baru dengan konteks eksplisit bahwa respons sebelumnya terputus. Perlakukan itu sebagai generasi model baru, bukan kelanjutan dari stream byte yang sama.

Jangan menggabungkan output dari dua model secara diam-diam.

Pisahkan reliabilitas tool-call dari reliabilitas model-call

Permintaan LLM mungkin bisa diulang, sementara tool yang dipilih tidak. Pembayaran, email, deployment, penulisan database, atau pembuatan tiket dapat berhasil bahkan jika koneksi model gagal sebelum aplikasi mencatat hasilnya.

Amankan tool sisi tulis dengan:

• Idempotency key yang diturunkan dari operasi pengguna, bukan percobaan provider
• Catatan eksekusi tool yang tahan lama
• Deduplication di batas tool
• Pembedaan yang jelas antara planned, started, succeeded, dan unknown
• Review manusia untuk side effect berisiko tinggi yang tidak pasti

Jika side effect mungkin terjadi dan hasilnya tidak diketahui, hentikan fallback otomatis. Pertama, rekonsiliasikan state tool.

Amati fallback sebagai hasil produk

Tingkat error provider yang rendah tidak membuktikan bahwa fallback berjalan. Lacak hasil rute secara penuh.

Catat alasan rute untuk setiap percobaan: target yang dipilih, error yang dinormalisasi, jeda retry, status circuit, alasan fallback, sisa tenggat request, dan hasil akhir. Hindari mencatat prompt atau output sensitif kecuali kebijakan data produk secara eksplisit mengizinkannya.

Uji jalur kegagalan sebelum mengaktifkan fallback otomatis

Jalankan failure injection di lingkungan staging lalu canary kebijakan tersebut di produksi.

Pengujian transport dan provider

• Putuskan koneksi sebelum header respons.
• Kembalikan pembatasan laju berulang dengan dan tanpa panduan retry.
• Simulasikan overload dan error server.
• Tunda primary hingga tenggat permintaan hampir habis.
• Buka circuit target dan verifikasi trafik berpindah ke rute yang memenuhi syarat.
• Pulihkan target dan verifikasi probe half-open tidak mengembalikan trafik penuh terlalu cepat.

Contract tests

• Hapus tool yang diperlukan dari fallback adapter.
• Kembalikan output terstruktur yang tidak valid.
• Ubah bentuk event streaming.
• Lampaui batas konteks atau output.
• Bandingkan kualitas fallback pada set evaluasi tetap.

Replay-safety tests

• Gagal sebelum dan sesudah event streaming pertama.
• Gagal setelah tool sisi tulis dimulai.
• Ulangi idempotency key yang sama.
• Batalkan permintaan klien saat percobaan fallback masih tertunda.

Pengujian hanya lulus ketika router memilih tindakan yang diharapkan dan mencatat alasannya.

Where Flatkey fits

Flatkey menyediakan satu API key dan base URL yang kompatibel dengan OpenAI untuk model yang didukung, dengan penggunaan dan penagihan terpusat. Hal ini menciptakan batas integrasi yang stabil untuk akses dan routing multi-model.

Tim aplikasi tetap harus memiliki kontrak rute yang dijelaskan dalam playbook ini: error mana yang boleh retry, target mana yang setara, apakah fallback lintas model diizinkan, bagaimana tool dideduplikasi, dan ambang kualitas apa yang harus dipenuhi respons yang dipulihkan.

Untuk jalur integrasi tercepat, gunakan Flatkey integration starter. Jika Anda sedang memigrasikan klien yang sudah ada, OpenAI-compatible API gateway checklist mencakup base URL, parameter, streaming, dan verifikasi bentuk error.

Production rollout checklist

• Normalisasikan error penyedia ke dalam taksonomi internal yang stabil.
• Definisikan retry, equivalent failover, cross-model fallback, dan tindakan stop.
• Tetapkan satu komponen untuk memiliki anggaran retry.
• Tegakkan satu deadline end-to-end dan jumlah percobaan maksimum.
• Tambahkan exponential backoff dengan jitter untuk kegagalan sementara.
• Kunci circuit breaker berdasarkan domain kegagalan terkecil yang berguna.
• Definisikan kontrak kapabilitas berversi untuk setiap alias rute.
• Blokir peralihan otomatis setelah output parsial dimulai.
• Tambahkan idempotency dan rekonsiliasi untuk tool sisi tulis.
• Rekam alasan rute dan hasil akhir tugas.
• Suntikkan kegagalan transport, overload, kontrak, streaming, dan side-effect.
• Lakukan canary untuk equivalent failover sebelum mengaktifkan cross-model fallback.
• Tambahkan kill switch untuk setiap target dan kebijakan fallback.

FAQ

Apa itu fallback routing untuk API LLM?

Fallback routing untuk API LLM adalah kebijakan keandalan yang memilih model atau penyedia lain yang memenuhi syarat ketika rute yang dipilih tidak dapat menyelesaikan permintaan. Fallback yang aman memeriksa keamanan replay, kompatibilitas kapabilitas, kesehatan circuit, anggaran latensi, dan status output sebelum beralih.

Apa perbedaan antara retry LLM dan fallback?

Retry mengulangi request ke target yang sama. Failover berpindah ke infrastruktur yang setara sambil mempertahankan kontrak model logis. Fallback lintas model mengubah model dan karena itu memerlukan pengujian kompatibilitas dan kualitas yang lebih kuat.

Should an LLM API retry every 429 or 5xx error?

Tidak. Retry harus dibatasi oleh deadline end-to-end, batas percobaan, kebijakan backoff, status circuit, dan pemeriksaan replay-safety. Failover yang setara mungkin lebih baik daripada memanggil target yang tidak sehat berulang kali.

Can an LLM router switch models during a stream?

Tidak secara transparan setelah output mencapai klien. Default yang aman adalah menghentikan stream dengan jelas atau memulai turn baru di tingkat aplikasi. Menggabungkan output parsial dari model yang berbeda dapat merusak kontrak respons.

When should cross-model fallback be disabled?

Nonaktifkan ketika model alternatif tidak dapat mempertahankan tools yang diperlukan, output terstruktur, batas konteks, perilaku keamanan, ambang kualitas, atau jaminan efek samping. Juga nonaktifkan replay otomatis setelah output parsial atau eksekusi tool yang tidak pasti.

How many fallback attempts should an LLM request make?

Tidak ada jumlah universal. Gunakan jumlah percobaan terbatas paling kecil yang sesuai dengan anggaran latensi produk dan bukti pengujian. Router harus berhenti ketika deadline yang tersisa tidak dapat mendukung satu percobaan lain yang berguna.

Fallback yang andal tidak berarti “coba semuanya.” Artinya membuat tindakan berikutnya eksplisit, kompatibel, aman untuk replay, dapat diamati, dan mudah dihentikan.