Fallback LiteLLM: retry dan pindah model

Di LiteLLM, daftarkan deployment utama di bawah satu model_name, daftarkan kelompok cadangan dengan nama lain, lalu hubungkan keduanya melalui fallbacks. Atur retry dan timeout secara terpisah. Alur permintaan LiteLLM menempatkan retry di dalam kelompok model yang gagal, sementara fallback membawa permintaan ke kelompok model berikutnya.

Untuk aplikasi, perbedaan itu menentukan berapa banyak percobaan yang mungkin terjadi sebelum pengguna menerima jawaban atau galat. Deployment tambahan dengan model_name yang sama memberi Router jalur lain dalam kelompok utama; kelompok cadangan baru dicoba setelah jalur utama yang diizinkan tidak berhasil. Batas waktu satu panggilan karena itu perlu dipertimbangkan bersama retry dan tenggat total aplikasi.

Urutan keputusan ketika deployment gagal

Alur contoh ini adalah: permintaan ke kelompok utama → deployment pada prioritas pertama → retry sesuai batas → deployment pada prioritas berikutnya → kelompok cadangan jika kelompok utama tetap gagal. Panah menunjukkan keputusan Router, bukan janji bahwa setiap tahap selalu menghasilkan panggilan ke penyedia. Deployment yang sedang cooldown dapat dikeluarkan sementara dari pilihan.

Referensi Router LiteLLM menjelaskan bahwa nilai order yang lebih kecil mendapat prioritas lebih tinggi dan setiap tingkat prioritas memiliki kesempatan retry sebelum Router naik ke tingkat berikutnya. Jika beberapa deployment memiliki order yang sama, strategi routing memilih di antaranya. Itulah letak load balancing: memilih deployment untuk trafik dalam satu kelompok, sedangkan fallback menentukan kelompok model tujuan setelah kelompok sebelumnya gagal.

Contoh konfigurasi kelompok utama dan cadangan

Dua deployment dalam kelompok model utama LiteLLM; saat deployment prioritas pertama gagal, jalur beralih ke deployment kedua.

Contoh bersyarat berikut memakai dua kredensial OpenAI untuk kelompok utama dan satu deployment Anthropic untuk kelompok cadangan. Nama model, hak akses, dan kredensial harus sesuai dengan yang tersedia pada akun Anda. Contoh konfigurasi fallback LiteLLM menempatkan deployment dalam model_list dan memetakan satu nama kelompok ke kelompok lain melalui fallbacks.

Masukkan tiga entri tingkat atas berikut ke berkas konfigurasi YAML. Notasi kurung kurawal adalah bentuk ringkas YAML; setiap deployment dalam model_list tetap merupakan entri tersendiri:

model_list: [{model_name: utama, litellm_params: {model: openai/gpt-5.6, api_key: os.environ/OPENAI_KEY_A, order: 1}}, {model_name: utama, litellm_params: {model: openai/gpt-5.6, api_key: os.environ/OPENAI_KEY_B, order: 2}}, {model_name: cadangan, litellm_params: {model: anthropic/claude-sonnet-5, api_key: os.environ/ANTHROPIC_API_KEY}}]

litellm_settings: {num_retries: 1, request_timeout: 10}

router_settings: {fallbacks: [{utama: [cadangan]}], allowed_fails: 1, cooldown_time: 30}

Angka retry, timeout, dan cooldown tersebut hanya pilihan untuk contoh, bukan ukuran yang sudah terbukti cocok bagi aplikasi tertentu. Aplikasi meminta model bernama utama; Router lebih dulu memakai deployment dengan order terendah, kemudian dapat mencoba tingkat berikutnya bila tingkat pertama gagal. Jika keduanya tidak berhasil, aturan fallbacks menunjuk cadangan. Dua kunci OpenAI tidak memberi perlindungan terhadap gangguan yang meliputi seluruh penyedia OpenAI; deployment Anthropic menyediakan jalur lintas penyedia dalam contoh ini.

Memilih retry, fallback, dan cooldown

Retry sesuai untuk kegagalan yang masih mungkin pulih dalam kelompok utama, seperti gangguan sementara pada satu deployment. Fallback sesuai ketika kelompok itu tidak dapat melayani permintaan dan aplikasi menerima model cadangan. Pada rate limit, retry dapat melibatkan jeda dengan backoff eksponensial; cooldown mengeluarkan deployment yang bermasalah sementara waktu, sehingga permintaan lain dapat memakai deployment yang masih tersedia.

Timeout: batasi lamanya satu panggilan yang menggantung. Bila setiap percobaan dibiarkan terlalu lama, tingkat prioritas berikutnya dan fallback baru mendapat giliran setelah pengguna menunggu.
Rate limit: beri Router kesempatan mencoba jalur lain tanpa membuat aplikasi pemanggil langsung mengulang seluruh permintaan. Periksa pula apakah pembatasan berlaku pada satu kunci atau pada seluruh akun penyedia.
Penyedia tidak tersedia: jalur dalam kelompok utama mungkin gagal bersama. Fallback ke kelompok penyedia lain berguna hanya jika model cadangan dapat menjalankan tugas aplikasi tersebut.

Nilai num_retries mengatur percobaan ulang LiteLLM; tingkat prioritas dan fallback masih dapat menambah rangkaian panggilan. Retry di aplikasi pemanggil akan memulai rangkaian baru, sehingga batas retry di kedua sisi perlu dihitung bersama. request_timeout pada contoh membatasi panggilan model, bukan otomatis menjadi tenggat untuk seluruh perjalanan permintaan. Tetapkan tenggat aplikasi berdasarkan lama respons yang masih dapat diterima pengguna.

Biaya dan izin model cadangan

Fallback yang menghasilkan respons tetap dapat mengubah biaya maupun perilaku aplikasi. Sebelum mengaktifkannya, cocokkan kemampuan model cadangan dengan tugas yang diminta, termasuk ukuran konteks, format keluaran, dan pemanggilan alat. Bandingkan pula tarif model dan perkiraan trafik yang dapat berpindah saat jalur utama bermasalah; jumlah permintaan masuk ke gateway saja tidak menunjukkan berapa kali penyedia dipanggil.

LiteLLM memeriksa kembali akses model dan anggaran kunci atau pengguna sebelum mencoba tujuan fallback. Tujuan yang tidak diizinkan atau melampaui anggaran dilewati; bila tidak ada tujuan yang layak, pemanggil menerima galat dari model utama. Karena itu, izin untuk memanggil utama saja belum cukup bila aplikasi diharapkan memakai cadangan. Untuk proxy dengan beberapa instans, Redis dapat dipakai untuk berbagi pelacakan cooldown dan penggunaan antarinstans.

Uji timeout, rate limit, dan penyedia yang tidak tersedia

Pengujian LiteLLM menunjukkan permintaan melewati deployment yang sedang cooldown dan memakai jalur yang masih tersedia.

Uji konfigurasi di lingkungan terpisah dengan kegagalan yang sengaja dipicu. Catat deployment yang menerima tiap percobaan, lama respons, dan apakah kelompok cadangan dipakai. Bandingkan hasilnya dengan tenggat aplikasi serta izin dan anggaran kunci pengujian; konfigurasi yang benar secara sintaks belum menunjukkan bagaimana seluruh rantai merespons gangguan.

Timeout: buat deployment prioritas pertama merespons melewati batas panggilan. Amati apakah tingkat berikutnya atau cadangan dicoba dan apakah aplikasi masih memenuhi tenggat totalnya.
Rate limit: picu pembatasan pada deployment utama. Amati jeda retry, perpindahan tujuan, dan apakah permintaan berikutnya menghindari deployment yang sedang cooldown.
Penyedia tidak tersedia: buat seluruh deployment utama gagal. Periksa respons dari cadangan dengan kunci yang berhak memanggilnya, lalu ulangi dengan akses atau anggaran cadangan dibatasi untuk melihat galat yang diterima aplikasi.

Jika satu permintaan memicu terlalu banyak panggilan atau menunggu terlalu lama, kurangi retry, pendekkan batas panggilan, atau sederhanakan tingkat prioritas. Pertahankan fallback hanya untuk tujuan yang kemampuan, izin, dan biayanya sesuai dengan tugas aplikasi.