Kesalahan Umum LiteLLM: Timeout, Peringatan Anggaran, dan Kegagalan Provider

Kesalahan Umum LiteLLM: Timeout, Peringatan Anggaran, dan Kegagalan Provider

Sejumlah besar Kesalahan Umum LiteLLM pada awalnya terlihat seperti masalah provider: permintaan mengalami timeout, peringatan anggaran tidak pernah tiba, atau model yang sehat tiba-tiba mengembalikan 404 atau 503. Perbaikan tercepat adalah mengidentifikasi lapisan kontrol yang gagal sebelum mengubah retry atau mengganti model.

Gunakan panduan ini untuk membedakan tenggat waktu klien, kebijakan gateway LiteLLM, konfigurasi model, kapasitas provider, dan penegakan pengeluaran. Panduan ini mencakup alur kerja insiden kecil yang dapat Anda ulangi untuk timeout, kontrol anggaran, dan kegagalan provider.

Jawaban singkat: Simpan satu permintaan yang gagal, klasifikasikan kesalahannya, reproduksi dengan panggilan minimal, dan ubah satu kontrol pada satu waktu. Mulailah dengan jenis pengecualian ternormalisasi LiteLLM, metadata permintaan, dan ID panggilan—bukan hanya status HTTP.

LiteLLM memetakan banyak kegagalan provider ke jenis pengecualian yang kompatibel dengan OpenAI serta mengekspos status HTTP, pesan, dan provider asal pada pengecualian tersebut. Hal ini membuat Kesalahan Umum LiteLLM lebih mudah ditelusuri ketika Anda mempertahankan konteks kesalahan asli alih-alih menggantinya dengan 500 generik. Lihat referensi pemetaan pengecualian LiteLLM untuk pemetaan terkini.

Matriks Kesalahan Umum LiteLLM

Tabel ini adalah aset nilai utama dalam panduan Kesalahan Umum LiteLLM ini: tabel ini mengubah kegagalan gateway yang samar menjadi observasi spesifik berikutnya.

Alur triase Kesalahan Umum LiteLLM dalam lima menit

Sebelum mengedit config.yaml, simpan satu kegagalan yang representatif. Samarkan secret dan konten prompt bila diperlukan, tetapi pertahankan field operasionalnya.

1. Catat identitas permintaan. Catat stempel waktu, lingkungan, rute, model yang diminta, status HTTP, jenis pengecualian LiteLLM, pesan kesalahan, nama provider, dan nomor percobaan klien.
2. Catat identitas gateway. Simpan x-litellm-call-id jika tersedia. LiteLLM mendokumentasikan header ini sebagai penanda terbaik untuk mengikuti permintaan melalui sistem logging. Catat juga x-litellm-model-id, x-litellm-model-api-base, dan header versi jika respons Anda mengeksposnya. dokumentasi logging LiteLLM mencantumkan header terkini.
3. Klasifikasikan kegagalan. Apakah ini permintaan tidak valid, masalah autentikasi/izin, batas anggaran/rate, timeout, atau kegagalan layanan upstream? Jangan masukkan semua kesalahan 4xx ke dalam satu kategori retry.
4. Buat satu reproduksi minimal non-produksi. Gunakan virtual key dan model_name publik yang sama dengan yang digunakan aplikasi. Hapus konkurensi khusus aplikasi dan panggilan tool sebelum menguji permintaan dasar.
5. Ubah hanya satu lapisan. Koreksi nama model, perubahan timeout, dan perubahan fallback dalam deployment yang sama membuat hasil akhir tidak mungkin dijelaskan.

Berikut adalah probe minimal generik untuk proxy LiteLLM yang kompatibel dengan OpenAI:

curl -i --request POST "$LITELLM_PROXY_URL/v1/chat/completions" \
  --header "Authorization: Bearer $LITELLM_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "support-chat",
    "messages": [{"role": "user", "content": "Reply with OK."}],
    "max_tokens": 16
  }'

Intinya bukan bahwa support-chat adalah nama model universal. Intinya adalah bahwa pengujian harus menggunakan nama publik yang dikonfigurasi di gateway Anda, lalu mempertahankan header dan body respons untuk dibandingkan dengan permintaan aplikasi yang gagal.

Kesalahan timeout: temukan batas waktu yang benar-benar terpicu

Timeout termasuk Kesalahan Umum LiteLLM yang paling menyesatkan karena permintaan dapat kedaluwarsa di lebih dari satu lapisan:

• Pemanggil dapat membatalkan lebih dahulu.
• Deployment atau router LiteLLM dapat menerapkan batas waktu yang lebih singkat.
• request_timeout proxy dapat menghentikan panggilan upstream yang berjalan lama.
• Provider, load balancer, atau jalur jaringan dapat menutup permintaan.
• Respons streaming dapat dimulai dengan sukses lalu macet di antara chunk.

Pemetaan exception LiteLLM mendokumentasikan kegagalan timeout sebagai openai.APITimeoutError. Untuk rute native dan pass-through, dokumentasi timeout saat ini menjelaskan urutan prioritas di seluruh pengaturan permintaan, deployment, router, dan proxy. Periksa versi dokumentasi yang sesuai dengan deployment Anda sebelum menerapkan perubahan konfigurasi.

Mulailah dengan anggaran batas waktu, bukan angka yang lebih besar

Pilih total latensi yang dapat ditoleransi oleh alur pengguna Anda, lalu alokasikan secara mundur. Misalnya, pengalaman interaktif mungkin perlu menyediakan waktu untuk antrean, satu kali retry, dan rendering respons, alih-alih membiarkan panggilan upstream menghabiskan seluruh batas waktu yang terlihat oleh pengguna.

# Titik awal ilustratif — sesuaikan dengan beban kerja dan versi LiteLLM Anda.
litellm_settings:
  request_timeout: 60
  set_verbose: false
  json_logs: true

Contoh ini sengaja konservatif: contoh ini memberi proxy mode kegagalan yang dibatasi alih-alih membiarkan koneksi menggantung. Panduan produksi LiteLLM merekomendasikan pengaturan request timeout dan penggunaan logging produksi terstruktur.

Saat timeout terjadi, jawab pertanyaan-pertanyaan ini secara berurutan:

Jangan biarkan retry timeout otomatis berjalan tanpa batas. Retry masuk akal hanya ketika pekerjaan aman untuk diulang dan percobaan alternatif masih dapat selesai dalam batas waktu pemanggil. Jika permintaan memicu tools, menulis data, atau memulai stream yang terlihat oleh pengguna, tentukan idempotensi dan semantik restart terlebih dahulu.

Untuk masalah antrean atau kapasitas yang dipicu 429 dan muncul sebagai latensi panjang, padukan bagian ini dengan panduan RPM, TPM, dan retry dari Flatkey. Timeout dapat menjadi gejala admission control yang kelebihan beban, bukan pengaturan durasi permintaan.

Peringatan anggaran: pisahkan notifikasi dari penegakan

Perilaku anggaran menyebabkan bagian yang tidak proporsional dari Kesalahan Umum LiteLLM karena tim sering menyatukan tiga kontrol berbeda ke dalam kata “peringatan”. Ketiganya tidak dapat saling menggantikan.

Pemeriksaan anggaran pertama: apakah ada database?

Dokumentasi anggaran LiteLLM saat ini menjelaskan secara tegas: anggaran proxynya ditegakkan berdasarkan pengeluaran yang dibaca dari database. Pada deployment tanpa DB, max_budget global yang dikonfigurasi tidak berfungsi sebagai batas pengeluaran yang andal; perilaku anggaran virtual key, tim, dan pengguna juga bergantung pada database.

Hal ini mengarah pada pola kegagalan yang umum: sebuah tim menetapkan max_budget, melihat peringatan startup atau nilai konfigurasi, lalu mengasumsikan traffic produksi akan berhenti pada ambang tersebut. Itu tidak akan menjadi kontrol yang dapat diandalkan tanpa penyiapan pelacakan pengeluaran yang diperlukan.

# Illustrative policy only. Validate with a non-production key before rollout.
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
  fail_closed_budget_enforcement: true

litellm_settings:
  max_budget: 100
  budget_duration: 30d

Perlakukan fail_closed_budget_enforcement sebagai keputusan keandalan, bukan perbaikan salin-tempel. Dokumentasi LiteLLM saat ini menjelaskan bahwa pemeriksaan anggaran yang lebih ketat dapat menolak permintaan saat pengeluaran tidak dapat diverifikasi; uji perilaku kegagalan database dan Redis untuk deployment Anda sebelum mengaktifkannya secara luas.

Uji jalur anggaran, bukan hanya dasbor

Gunakan key atau tim sekali pakai di lingkungan nonproduksi dan verifikasi urutan berikut:

1. Pastikan proxy dapat membaca dan menulis penyimpanan pengeluaran.
2. Buat anggaran keras yang sengaja kecil dalam cakupan yang tepat: key, tim, pengguna, proyek, atau pengguna akhir.
3. Kirim permintaan minimal melalui proxy.
4. Kirim permintaan kedua yang harus melewati ambang batas.
5. Periksa exception yang dikembalikan, catatan pengeluaran, jendela reset, dan saluran peringatan secara terpisah.
6. Pastikan aplikasi menangani pemblokiran anggaran tanpa mencobanya ulang seolah-olah itu adalah kelebihan beban provider yang bersifat sementara.

LiteLLM juga mendokumentasikan jendela anggaran dan kontrol anggaran per model. Pastikan jadwal reset secara presisi: pagar pengaman harian dan batas bulanan menyelesaikan risiko yang berbeda.

Peringatan anggaran Azure dan peringatan anggaran AWS adalah lapisan cadangan, bukan pengganti

Kata kunci sekunder peringatan anggaran Azure dan peringatan anggaran AWS penting karena peringatan penagihan provider cloud mencakup batas yang berbeda. Peringatan tersebut dapat memberi tahu tentang pengeluaran akun provider atau langganan, termasuk trafik yang melewati LiteLLM. Peringatan tersebut tidak menggantikan keputusan di tingkat gateway tentang apakah permintaan, key, tenant, atau model ini harus diizinkan sekarang.

Gunakan kedua lapisan jika sesuai:

• Kebijakan anggaran LiteLLM melindungi rute dan tenant yang dapat diidentifikasi gateway.
• Peringatan anggaran Azure atau peringatan anggaran AWS memantau pengeluaran akun cloud hulu.
• Ledger penggunaan gateway merekonsiliasi keduanya dan mengungkap trafik yang melewati jalur yang dimaksudkan.

Untuk pengeluaran OpenAI, pemeriksaan tingkat penangkapan pengeluaran LiteLLM dapat membandingkan pengeluaran yang dilacak dengan OpenAI Organization Costs API. Fitur ini saat ini memiliki prasyarat khusus provider, jadi bacalah dokumentasi berversi sebelum memperlakukannya sebagai fitur rekonsiliasi universal untuk berbagai provider.

Jika kebutuhan operasional lebih luas daripada satu deployment LiteLLM, lihat panduan evaluasi dasbor penagihan AI terpadu untuk pertanyaan yang perlu diajukan seputar key, anggaran, alokasi, peringatan, dan rekonsiliasi.

Kegagalan provider: verifikasi nama model publik dan deployment hulu secara terpisah

Kegagalan provider adalah Kesalahan Umum LiteLLM yang paling terlihat, tetapi sering kali merupakan kesalahan konfigurasi gateway. Klien biasanya memanggil model_name publik yang Anda ekspos. LiteLLM kemudian me-resolve nama tersebut ke model provider, deployment, endpoint, kredensial, dan parameter khusus provider.

model_list:
  - model_name: support-chat       # The name the client requests
    litellm_params:
      model: azure/<deployment-name>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

model_name dan litellm_params.model sengaja merupakan konsep yang berbeda. Saat klien mendapatkan error model tidak valid, bandingkan nama yang diminta secara persis dengan model_name terlebih dahulu. Dokumentasi manajemen model LiteLLM membedakan nama model publik dari model provider serta menyediakan alur kerja uji koneksi untuk model yang dikonfigurasi.

Tabel keputusan kegagalan provider

Jenis pengecualian harus menentukan tindakan berikutnya. referensi pengecualian LiteLLM memetakan kondisi 401, 402, 403, 404, 408, 429, 500, dan 503 ke dalam kelas yang dinormalisasi; referensi ini juga mengekspos field khusus provider untuk investigasi lebih mendalam.

Percobaan ulang, fallback, dan cooldown: pulih tanpa menyembunyikan insiden

Percobaan ulang dan fallback dapat mengurangi kegagalan yang terlihat, tetapi juga dapat mengubah kesalahan konfigurasi menjadi latensi, biaya, atau pekerjaan duplikat. Penanganan Kesalahan Umum LiteLLM yang baik menggunakan kebijakan berbeda untuk konfigurasi yang tidak valid dan gangguan provider singkat.

LiteLLM mendokumentasikan pembagian yang berguna:

• Percobaan ulang berupaya pulih dalam grup model saat ini.
• Fallback berpindah ke grup model lain setelah percobaan ulang yang dikonfigurasi.
• Cooldown mengisolasi deployment yang gagal sementara alternatif yang sehat tetap tersedia.

Berikut adalah konfigurasi ilustratif kecil berdasarkan panduan failover provider LiteLLM:

model_list:
  - model_name: primary-chat
    litellm_params:
      model: openai/<primary-model>
      api_key: os.environ/PRIMARY_PROVIDER_KEY

  - model_name: backup-chat
    litellm_params:
      model: azure/<backup-deployment>
      api_base: os.environ/AZURE_API_BASE
      api_key: os.environ/AZURE_API_KEY
      api_version: os.environ/AZURE_API_VERSION

litellm_settings:
  num_retries: 1
  request_timeout: 30
  fallbacks: [{"primary-chat": ["backup-chat"]}]
  allowed_fails: 3
  cooldown_time: 30

Validasikan ini hanya dengan kesalahan provider non-produksi yang disengaja. Dokumentasi LiteLLM memperingatkan bahwa flag fallback mock lama tidak menguji request proxy; kegagalan nyata yang terkontrol adalah jalur validasi proxy yang tepat.

Jauhkan kondisi 404, autentikasi, izin, skema, dan kebijakan konten dari loop percobaan ulang umum kecuali Anda telah secara eksplisit merancang respons terpisah. Dokumentasi routing LiteLLM mendukung kebijakan percobaan ulang khusus per kesalahan, termasuk nol percobaan ulang untuk NotFoundError; hal itu mencegah nama model yang tidak valid menjadi insiden yang lambat.

Sebelum mengaktifkan fallback lintas-provider, validasikan kontrak produk:

• Perilaku context window dan semantik tool call
• Dukungan output terstruktur dan format respons
• Persyaratan residensi data, retensi, dan kebijakan pelanggan
• Perilaku keamanan dan ekspektasi kebijakan konten
• Batas latensi dan biaya
• Idempotensi efek samping downstream

Fallback harus dapat diamati setelah request, bukan diam-diam. LiteLLM mendokumentasikan field seperti fallback yang dicoba dan grup model asli dalam metadata spend-log. Pantau tingkat fallback, tingkat keberhasilan akhir, latensi yang ditambahkan oleh percobaan ulang/fallback, dan biaya rute yang benar-benar melayani request.

Untuk desain routing yang lebih luas, lihat playbook routing fallback Flatkey. Aturan yang sama berlaku: lakukan routing hanya jika alternatif tersebut tetap memenuhi kontrak workflow.

Checklist siap-insiden untuk masalah LiteLLM

Jalankan checklist ini sebelum menutup insiden atau menyatakan salah satu Kesalahan Umum LiteLLM telah diperbaiki.

Kapan menyederhanakan permukaan routing

Beberapa tim menginginkan LiteLLM karena memusatkan konfigurasi model, penggunaan, dan kebijakan keandalan. Tim lain menginginkan lebih sedikit infrastruktur gateway untuk dioperasikan. Jawaban yang tepat bergantung pada siapa yang memiliki kebijakan routing, kredensial provider, penegakan anggaran, dan siklus respons insiden.

Flatkey berguna ketika aplikasi memerlukan antarmuka integrasi yang kompatibel dengan OpenAI di seluruh rute model yang didukung sambil menjaga routing, peninjauan penggunaan, dan penagihan tetap lebih terintegrasi. Flatkey tidak menghilangkan kebutuhan untuk mengklasifikasikan timeout, pemblokiran anggaran, atau error provider; Flatkey mengurangi jumlah integrasi klien khusus provider yang harus dipelihara aplikasi Anda. Mulailah dengan satu API key untuk beberapa model AI atau panduan cepat API Flatkey saat Anda ingin mengevaluasi model operasional tersebut.

Untuk panduan penyiapan lengkap dan contoh konfigurasi, lihat panduan proxy LiteLLM kami.

FAQ

Apakah semua Kesalahan Umum LiteLLM aman untuk dicoba ulang?

Tidak. Kegagalan autentikasi, izin, model tidak valid, parameter tidak didukung, anggaran, dan sebagian besar penagihan memerlukan perbaikan konfigurasi atau akun. Coba ulang hanya kondisi yang jelas bersifat sementara, dengan jumlah percobaan dan anggaran waktu yang kecil, serta hanya ketika operasi aman untuk diulangi.

Mengapa max_budget tidak menghentikan pengeluaran di proxy LiteLLM saya?

Pertama, verifikasi bahwa proxy memiliki pelacakan pengeluaran berbasis database yang diperlukan untuk penegakan anggaran. Kemudian konfirmasikan bahwa traffic mencapai LiteLLM alih-alih memanggil provider secara langsung, serta bahwa key, tim, pengguna, atau proyek yang dikonfigurasi adalah cakupan yang benar-benar membuat permintaan. dokumentasi anggaran LiteLLM menjelaskan persyaratan database dan perilaku cakupan.

Apakah peringatan anggaran Azure atau peringatan anggaran AWS cukup untuk mencegah pembengkakan penggunaan aplikasi?

Keduanya berguna sebagai pengaman di tingkat akun provider, tetapi tidak menentukan apakah permintaan gateway tertentu harus diizinkan. Pertahankan peringatan penagihan provider, lalu tambahkan anggaran gateway yang telah diuji dan batas produk di tingkat aplikasi tempat konteks permintaan diketahui.

Apa yang harus saya simpan dari panggilan LiteLLM yang gagal?

Simpan badan error yang telah disanitasi, kelas exception yang dinormalisasi, status HTTP, nama provider, model yang diminta, stempel waktu, environment, nomor percobaan klien, dan x-litellm-call-id jika tersedia. Hindari mencatat API key serta konten prompt/response yang sensitif.

Dapatkah fallback menyembunyikan konfigurasi yang buruk?

Ya. Fallback dapat membuat permintaan pelanggan berhasil sementara rute utama terus gagal. Karena itu, tingkat fallback, error khusus rute, grup model akhir, latensi, dan biaya memerlukan peringatan atau dashboard. Perlakukan peningkatan tingkat fallback sebagai sinyal operasional, bukan perbaikan yang telah selesai.

Kesimpulan akhir

Perbaikan yang tahan lama untuk Kesalahan Umum LiteLLM bukanlah jumlah percobaan ulang universal atau timeout yang lebih besar. Perbaikan tersebut adalah siklus operasional yang dapat diulang: tangkap kegagalan yang sebenarnya, identifikasi lapisan kebijakan, validasi perubahan aman terkecil, dan buktikan jalur pemulihan dengan pengujian terkontrol. Hal ini menjaga timeout tetap terbatas, peringatan anggaran tetap bermakna, dan kegagalan provider cukup terlihat untuk diperbaiki.

Sumber

• Pemetaan exception LiteLLM
• Anggaran dan batas laju LiteLLM
• Failover dan fallback provider LiteLLM
• Routing, percobaan ulang, cooldown, dan konkurensi LiteLLM
• Praktik terbaik produksi LiteLLM
• Logging LiteLLM
• Pemeriksaan spend-capture-rate LiteLLM