Cara Hos Sendiri LiteLLM sebagai Gateway LLM
Jalankan satu endpoint serasi OpenAI untuk semua penyedia dengan LiteLLM pada VPS, termasuk kunci maya, bajet setiap kunci, fallback dan imej yang dipinkan.
Fungsi gateway LLM yang dihoskan sendiri
LiteLLM ialah gateway LLM sumber terbuka yang anda hoskan sendiri: satu endpoint HTTP yang dipanggil oleh semua aplikasi anda, yang kemudiannya memajukan setiap permintaan kepada penyedia yang sepatutnya menjawab permintaan tersebut. LLM bermaksud large language model. Gateway ini menggunakan API (application programming interface) chat completions OpenAI, jadi mana-mana pustaka klien yang sudah berhubung dengan OpenAI boleh berfungsi dengannya selepas dua perubahan: base URL dan kunci.
Satu lapisan indirection itulah tujuannya. Aplikasi anda tidak lagi menyimpan kelayakan penyedia. Menukar model hanya menjadi satu baris dalam fail konfigurasi pada pelayan dan bukannya perubahan kod dalam lima servis. Oleh sebab setiap panggilan melalui satu proses, anda mempunyai tempat untuk menetapkan bajet dan tempat untuk menyimpan rekod perbelanjaan.
Berikut adalah apa yang anda miliki sebaik sahaja ia berjalan:
- Satu endpoint. Aplikasi menyasarkan
https://gateway.example.com/v1dan meminta nama model yang anda cipta, sepertibulkataustrong. - Kunci maya. Setiap aplikasi mendapat kuncinya sendiri dengan senarai kebenaran model dan had perbelanjaan tersendiri. Anda boleh membatalkan satu kunci tanpa menjejaskan kunci yang lain.
- Fallback. Panggilan yang gagal atau prompt yang terlalu besar akan dicuba semula secara automatik menggunakan model yang berbeza.
- Rekod log. Setiap permintaan menulis satu baris yang mengandungi kosnya, jadi persoalan "aplikasi mana yang membelanjakannya" mempunyai jawapan.
Mengapa mengendalikan gateway sendiri
Router terurus mempunyai bentuk yang sama dengan proses pihak lain yang berada di tengah-tengah setiap permintaan. Mengendalikannya sendiri memastikan kunci pembekal dan teks prompt anda kekal pada kotak yang anda kawal. Kosnya adalah nyata: anda kini mengendalikan komponen yang bergantung kepada setiap aplikasi. Bahagian terakhir panduan ini adalah mengenai kos tersebut, kerana ia merupakan bahagian yang sering ditinggalkan oleh kebanyakan penulisan.
Keperluan anda
- Sebuah VPS (virtual private server) yang menjalankan Ubuntu 24.04, dengan Docker dan pemalam Compose dipasang.
- Nama domain yang menghala ke pelayan tersebut, jika mesin di luar kotak akan mencapai gateway melalui TLS (transport layer security).
- Sekurang-kurangnya satu kunci API pembekal.
Gateway ini tidak menjalankan inferens. Ia memajukan permintaan dan menstrim jawapan kembali, jadi beban CPU-nya mengikut volum permintaan dan bukannya saiz model. Kotak 1 vCPU mampu menampung beberapa aplikasi dalaman tanpa masalah. Perkara yang akan berkembang ialah pangkalan data, kerana gateway menulis satu baris perbelanjaan bagi setiap permintaan.
Tulis config.yaml terlebih dahulu
Fail konfigurasi menentukan model yang boleh diminta oleh klien. Empat bahagian peringkat atas adalah penting: model_list, litellm_settings, router_settings dan general_settings.
model_list:
- model_name: bulk
litellm_params:
model: anthropic/claude-haiku-4-5
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: strong
litellm_params:
model: anthropic/claude-sonnet-5
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: strong
litellm_params:
model: openai/gpt-5.5
api_key: os.environ/OPENAI_API_KEY
litellm_settings:
num_retries: 2
request_timeout: 120
json_logs: true
set_verbose: false
router_settings:
allowed_fails: 3
cooldown_time: 30
fallbacks: [{"bulk": ["strong"]}]
context_window_fallbacks: [{"bulk": ["strong"]}]
general_settings:
background_health_checks: true
health_check_interval: 300model_name ialah nama yang dihantar oleh klien anda. litellm_params.model ialah model sebenar, ditulis sebagai provider/model. Namakan model anda berdasarkan tugasan dan bukannya berdasarkan vendor. Aplikasi yang meminta bulk akan terus berfungsi apabila anda memutuskan pada bulan hadapan bahawa bulk sepatutnya menjadi model yang berbeza.
api_key: os.environ/ANTHROPIC_API_KEY memberitahu LiteLLM untuk membaca pemboleh ubah tersebut semasa runtime. Kunci literal tidak akan muncul dalam fail, yang penting kerana config.yaml ialah fail yang anda commit.
Dua entri berkongsi nama strong, secara sengaja. Apabila lebih daripada satu deployment membawa model_name yang sama, router menganggapnya sebagai boleh tukar ganti dan mengagihkan permintaan untuk nama tersebut merentasinya. Begitulah cara strong bertahan apabila satu penyedia mengalami masalah: sebaik sahaja deployment berada dalam cooldown (di bawah), permintaan baharu untuk strong akan pergi ke deployment yang satu lagi.
num_retries: 2 mencuba semula ralat yang boleh dicuba semula sehingga dua kali. Percubaan semula tersebut boleh memilih deployment lain yang tersedia dalam kumpulan model yang sama: dokumentasi seni bina LiteLLM, yang disemak pada 2026-10-29, menerangkan percubaan semula dalam kumpulan dan fallback merentas kumpulan sebagai langkah yang berasingan. Oleh itu, percubaan semula untuk strong boleh mendarat pada penyedia lain tanpa mendayakan weighted failover. Fallback hanya akan dicetuskan selepas percubaan semula tersebut habis digunakan.
allowed_fails dan cooldown_time adalah pilihan router, jadi ia diletakkan di bawah router_settings. Proksi membina router daripada bahagian tersebut, dan pada v1.95.0, cooldown_time yang ditulis di bawah litellm_settings tidak akan sampai kepadanya, jadi cooldown akan kekal pada nilai lalai 5 saat secara senyap. cooldown_time: 30 menetapkan tempoh masa deployment kekal di luar putaran sebaik sahaja ia disejukkan (cooled down). Rujukan konfigurasi menerangkan allowed_fails sebagai kiraan kegagalan yang mesti dilampaui oleh deployment dalam tempoh cooldown_time sebelum ia disejukkan. Dalam kod sumber v1.95.0, allowed_fails: 3 ialah nilai lalai, dan pada nilai lalai tersebut, router mematuhi pencetus terbina dalam; kiraan kegagalan hanya akan mengambil alih apabila anda menetapkan nombor yang berbeza. Pencetus tersebut termasuk cooldown serta-merta pada respons 429 untuk kumpulan yang mempunyai lebih daripada satu deployment, lebih daripada 50% kegagalan dalam minit semasa selepas sekurang-kurangnya 5 permintaan untuk kumpulan tersebut, dan ralat yang tidak akan dicuba semula oleh router, seperti 401 daripada kunci yang salah. Pencetus berasingan juga menyejukkan satu deployment apabila semua permintaan dalam minit semasa gagal dan trafik mencapai SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD, yang secara lalainya ialah 1000 permintaan. Jadi untuk strong, yang mempunyai dua deployment, penyedia yang mengembalikan ralat 500 secara bertubi-tubi akan berhenti dicuba pada setiap permintaan, manakala ralat 500 yang terpencil setiap beberapa minit tidak akan mencetuskan cooldown. bulk hanya mempunyai satu deployment, jadi pencetus kadar kegagalan tidak terpakai kepadanya: ralat 500 yang bertubi-tubi tetapi kekal di bawah 1000 permintaan seminit akan membiarkannya dalam putaran, dan apa yang melindungi pemanggilnya ialah num_retries diikuti dengan fallback ke strong.
fallbacks dan context_window_fallbacks mempunyai pencetus yang berbeza, dan yang kedua adalah yang berguna yang sering diabaikan oleh orang ramai.
fallbacksdicetuskan apabila panggilan utama gagal.context_window_fallbacksdicetuskan apabila penyedia menolak permintaan kerana ia lebih panjang daripada context window model tersebut, jadi prompt yang terlalu besar akan dihantar ke model yang mempunyai ruang untuknya dan bukannya mengembalikan ralat kepada pemanggil.
Terdapat juga content_policy_fallbacks, untuk penyedia yang menolak atas alasan polisi kandungan. Tetapkannya hanya jika anda mempunyai tempat yang munasabah untuk menghantar panggilan tersebut.
Melancarkan LiteLLM pada VPS dengan Docker Compose
Cipta direktori yang mengandungi tiga fail: config.yaml, docker-compose.yml dan .env. Panduan permulaan pantas huluan menarik tag latest. Sebaliknya, tetapkan tag keluaran supaya naik taraf hanya berlaku apabila anda menyunting fail tersebut, dan supaya rollback boleh dilakukan dengan satu baris arahan. Tag sahaja tidak menjamin kandungan yang sama, kerana tag imej boleh diubah dan penerbit boleh menghalakannya ke imej baharu. Jika docker compose up -d bulan depan mesti memberikan anda gateway yang sama seperti hari ini, lampirkan juga digest imej dalam bentuk ghcr.io/berriai/litellm:v1.95.0@sha256:<digest>; docker buildx imagetools inspect ghcr.io/berriai/litellm:v1.95.0 akan mencetaknya.
services:
litellm:
image: ghcr.io/berriai/litellm:v1.95.0
restart: unless-stopped
command: ["--config", "/app/config.yaml", "--num_workers", "1"]
ports:
- "127.0.0.1:4000:4000"
volumes:
- ./config.yaml:/app/config.yaml:ro
env_file: .env
depends_on:
db:
condition: service_healthy
db:
image: postgres:16
restart: unless-stopped
environment:
POSTGRES_USER: litellm
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
POSTGRES_DB: litellm
healthcheck:
test: ["CMD-SHELL", "pg_isready -U litellm"]
interval: 5s
timeout: 5s
retries: 10
volumes:
- postgres_data:/var/lib/postgresql/data
volumes:
postgres_data:Compose membaca .env dua kali di sini. Sekali untuk menggantikan ${POSTGRES_PASSWORD} di dalam fail compose itu sendiri, dan sekali melalui env_file untuk menghantar setiap pemboleh ubah ke dalam kontena.
v1.95.0 merupakan keluaran semasa pada Ogos 2026. Semak halaman keluaran projek dan tetapkan versi yang terkini semasa anda melakukan deployment. Setiap keluaran menerbitkan tandatangan, jadi anda boleh menyemak imej tersebut sebelum mempercayainya:
cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0Baris port ialah 127.0.0.1:4000:4000, yang menerbitkan port pada antara muka loopback sahaja. Tulis 4000:4000 sebaliknya dan gateway anda boleh dicapai dari seluruh internet, kerana Docker menambah peraturannya sendiri dalam rantaian iptables FORWARD dan peraturan tersebut dinilai sebelum peraturan ufw, jadi ufw deny 4000 tidak akan menghalangnya. Ini adalah cara paling lazim gateway yang dihoskan sendiri terdedah kepada umum: lihat bagaimana Docker menerbitkan port kontena melepasi ufw. Trafik dari luar sebaliknya tiba melalui reverse proxy.
Pastikan kunci penyedia tidak dimasukkan ke dalam imej
Fail .env menyimpan setiap rahsia. Ia dihantar sebagai persekitaran semasa masa jalan (run time), jadi ia tidak pernah dibakar ke dalam imej dan tidak pernah dikomitkan.
LITELLM_MASTER_KEY=sk-REPLACE_ME
LITELLM_SALT_KEY=sk-REPLACE_ME_TOO
POSTGRES_PASSWORD=REPLACE_ME_AS_WELL
DATABASE_URL=postgresql://litellm:REPLACE_ME_AS_WELL@db:5432/litellm
STORE_MODEL_IN_DB=True
LITELLM_MODE=PRODUCTION
LITELLM_LOG=ERROR
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...Jana dua kunci LiteLLM dengan rawak sebenar, kemudian kunci fail tersebut:
printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .envLITELLM_MASTER_KEY ialah kelayakan pentadbir. Ia mengesahkan API pengurusan dan merupakan kata laluan untuk UI Pentadbir di /ui. Tiada aplikasi yang sepatutnya menyimpan kelayakan ini.
LITELLM_SALT_KEY menyulitkan kelayakan penyedia yang disimpan dalam pangkalan data. Tetapkan sekali dan biarkan ia begitu. Jika anda menukarnya kemudian, kelayakan yang telah disimpan tidak dapat dinyahsulit, jadi gateway akan bermula seperti biasa tetapi setiap panggilan kepada penyedia tersebut akan gagal semasa pengesahan.
STORE_MODEL_IN_DB=True membolehkan anda menambah dan mengedit model daripada UI Pentadbir tanpa menyentuh config.yaml. Ini memudahkan, tetapi ia memecahkan sumber kebenaran (source of truth) anda kepada dua bahagian. Tentukan yang mana satu adalah autoritatif dan catatkan keputusan tersebut bersebelahan dengan konfigurasi.
Sebab yang memastikan kunci tidak dimasukkan ke dalam fail konfigurasi adalah sama dengan sebab yang memastikan kunci tidak dimasukkan ke dalam alatan yang anda berikan kepada ejen. Memastikan rahsia penyedia tidak diberikan kepada ejen AI merangkumi corak tersebut, dan fail env dan rahsia dalam Docker Compose merangkumi mekanismenya.
Jalankan ia dan perhatikan but pertama:
docker compose up -d
docker compose logs -f litellmSemak sama ada ia benar-benar berfungsi
Terdapat dua ujian tanpa pengesahan dan satu ujian dengan pengesahan, dan kesemuanya gagal atas sebab yang berbeza.
curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness/health/liveliness tidak memerlukan pengesahan dan menjawab "I'm alive!" semasa proses sedang berjalan. /health/readiness juga tidak memerlukan pengesahan. Ia mengembalikan objek JSON dengan "status": "healthy" dan medan db, atau ralat 503 apabila pangkalan data tidak dapat dicapai. Halakan pemantauan anda kepada readiness, kerana liveliness kekal hijau pada gateway yang tidak dapat mencari kunci maya tunggal.
Ujian dengan pengesahan ialah ujian yang berhubung dengan penyedia:
curl -s http://127.0.0.1:4000/health \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"Ia menjawab dengan tatasusunan healthy_endpoints dan unhealthy_endpoints. Model yang berada dalam unhealthy_endpoints dengan ralat pengesahan bermakna kunci penyedia dalam .env adalah salah atau tiada, iaitu kegagalan yang ingin anda cari sekarang. Kerana background_health_checks: true ditetapkan, proksi menjalankan ujian ini setiap health_check_interval saat secara automatik dan /health mengembalikan hasil terakhir, jadi melakukan polling tidak menghantar permintaan ujian kepada penyedia anda setiap kali.
Kunci maya dan bajet bagi setiap kunci
Setiap aplikasi mendapat kuncinya sendiri, yang dijana berdasarkan kunci induk.
curl -s http://127.0.0.1:4000/key/generate \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H 'Content-Type: application/json' \
-d '{
"key_alias": "nightly-summariser",
"models": ["bulk"],
"max_budget": 5,
"budget_duration": "30d",
"rpm_limit": 60,
"tpm_limit": 200000
}'Respons tersebut membawa medan key yang bermula dengan sk-. Rentetan tersebut ialah perkara yang diterima oleh aplikasi, dan ia merupakan satu-satunya perkara yang akan diperoleh oleh aplikasi tersebut.
modelsialah senarai benarkan (allowlist) bagi perkara yang boleh diminta oleh kunci ini. Kunci di atas hanya boleh memintabulkdan tiada yang lain.max_budget: 5denganbudget_duration: "30d"adalah lima dolar AS bagi setiap bulan kalendar. LiteLLM menetapkan semula bajet30dpada hari pertama setiap bulan tepat tengah malam, dalam waktu UTC melainkan anda menetapkantimezonedi bawahlitellm_settings, bukannya sepanjang 30 hari berturut-turut. Oleh itu, sebaik sahaja kunci tersebut telah membelanjakan lima dolar, ia akan berhenti berfungsi sehingga hari pertama bulan berikutnya.rpm_limitdantpm_limitmengehadkan permintaan seminit dan token seminit khusus untuk kunci ini sahaja.key_aliasialah perkara yang akan anda kenali dalam log perbelanjaan enam minggu kemudian. Sentiasa tetapkannya.
Apabila bajet habis, panggilan tersebut gagal dengan ralat jenis budget_exceeded dan mesej dalam bentuk ini:
Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>Kod status bergantung pada keluaran (release). Pada versi terkunci v1.95.0, ia adalah HTTP 429. Bermula dari v1.104.0, lalai (default) adalah HTTP 422, dan menetapkan budget_exceeded_status_code: 429 di bawah litellm_settings akan mengembalikan kod yang terdahulu. Serangan rpm_limit dan tpm_limit yang sebenar masih mengembalikan 429 pada mana-mana keluaran. Semak kod yang anda peroleh selepas setiap naik taraf.
Kod status inilah yang menjadikannya mengelirukan, kerana tiada satu pun kod tersebut menyatakan "bajet". Pustaka klien melaporkan 429 sebagai had kadar (rate limit) dan mungkin mencuba semula dengan backoff terhadap bajet yang tidak akan kembali sehingga waktu penetapan semula, dan ia melaporkan 422 sebagai permintaan yang tidak dapat diproses. Log badan respons di sebelah kod status, jika tidak, kehabisan bajet akan kelihatan seperti masalah lain setiap kali ia berlaku.
Periksa dan laraskan kunci melalui API pengurusan yang sama:
curl -s "http://127.0.0.1:4000/key/info?key=sk-..." \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"
curl -s -X POST http://127.0.0.1:4000/key/update \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H 'Content-Type: application/json' \
-d '{"key": "sk-...", "max_budget": 25}'Bajet yang dikuatkuasakan di pintu masuk (gateway) tetap berkesan walaupun perkara yang tidak kena adalah ejen itu sendiri, itulah sebabnya ia menjadi tulang belakang kepada kawalan kos untuk ejen AI pada VPS.
Menghantar tugasan pukal ke model murah
Halakan klien ke gateway. URL asas, kunci, nama model:
curl -s http://127.0.0.1:4000/v1/chat/completions \
-H "Authorization: Bearer sk-<the virtual key>" \
-H 'Content-Type: application/json' \
-d '{
"model": "bulk",
"messages": [{"role": "user", "content": "Say hello in five words."}]
}'Mana-mana pustaka klien OpenAI berfungsi dengan cara yang sama, walaupun nama pilihan berbeza mengikut bahasa. Dalam klien Python, tetapkan base_url kepada https://gateway.example.com/v1 dan api_key kepada kunci maya. Klien JavaScript dan TypeScript memanggil dua pilihan yang sama sebagai baseURL dan apiKey.
Polisi penghalaan daripada config.yaml kini terpakai tanpa pengetahuan pemanggil. Permintaan untuk bulk akan pergi ke model murah. Jika panggilan itu gagal selepas percubaan semula, permintaan tersebut akan dicuba semula terhadap strong. Jika prompt terlalu panjang untuk bulk, context_window_fallbacks akan menghantarnya ke strong dan bukannya mengembalikan ralat. Tugasan pukal seperti proses klasifikasi atau tunggakan ringkasan dijalankan secara murah secara lalai, dan hanya permintaan sukar yang menelan kos lebih tinggi.
Di sinilah gateway membuktikan nilainya dengan ejen yang menggunakan alatan. Sebuah pelayan MCP (model context protocol) pada VPS yang sama dan ejen yang menggerakkannya boleh menghala ke satu endpoint yang sama, supaya model di sebaliknya boleh ditukar tanpa perlu menggunakan semula (redeploy) mana-mana komponen.
Bagaimanakah anda tahu fallback telah berlaku?
Ini ialah mod kegagalan yang menelan kos, kerana tiada apa-apa yang kelihatan rosak. Fallback yang berjaya akan mengembalikan HTTP 200 dengan badan respons biasa. Model murah anda boleh terhenti selama sehari, dengan setiap panggilan diservis secara senyap oleh model yang mahal, dan bukti pertama yang anda perolehi ialah invois.
Bukti tersebut wujud dalam header respons. Dapatkan header tersebut:
curl -s -D - -o /dev/null http://127.0.0.1:4000/v1/chat/completions \
-H "Authorization: Bearer sk-<the virtual key>" \
-H 'Content-Type: application/json' \
-d '{"model":"bulk","messages":[{"role":"user","content":"ping"}]}' \
| grep -i '^x-litellm'x-litellm-model-groupialah nama model yang digunakan untuk menghalakan permintaan, contohnyabulk.x-litellm-model-idialah ID deployment yang menjawab, yang boleh anda semak dengan/v1/model/info?litellm_model_id=.... Apabila ID tersebut bukan salah satu daripada deploymentbulkanda, maka fallback telah berlaku.x-litellm-attempted-fallbacksdanx-litellm-attempted-retriesmengira kejadian tersebut. Pada panggilan yang sihat, kedua-duanya tidak menunjukkan angka melebihi 0.x-litellm-response-costialah kos bagi satu panggilan tersebut dalam dolar AS.x-litellm-call-idialah pengecam yang anda gunakan untuk mencari panggilan yang sama dalam log anda.
Rekod x-litellm-attempted-fallbacks pada setiap permintaan dan berikan amaran apabila nilainya melebihi 0. Satu nombor itu adalah perbezaan antara polisi penghalaan yang berfungsi dengan polisi penghalaan yang telah berubah secara senyap menjadi "sentiasa gunakan model yang mahal".
Versi penuh bagi perkara ini ialah tracing, dan ia memerlukan persediaan tersendiri: Langfuse yang dihoskan sendiri untuk tracing panggilan ejen. LiteLLM menyediakan callback tersebut, jadi penyambungannya hanya memerlukan dua baris kod berserta kelayakan.
litellm_settings:
success_callback: ["langfuse"]
failure_callback: ["langfuse"]LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.comUntuk Langfuse v3 dan seterusnya, halaman Langfuse LiteLLM kini mengesyorkan pratetap langfuse_otel; callback langfuse di atas masih didokumentasikan. Tetapkan failure_callback serta success_callback. Jika dilangkau, satu-satunya trace yang anda simpan hanyalah trace di mana tiada apa-apa yang tidak kena. Secara berasingan daripada semua ini, LiteLLM menulis baris perbelanjaan bagi setiap permintaan ke dalam Postgres dan Admin UI di /ui membaca jadual tersebut. Ia akan membesar mengikut trafik, jadi pantau saiznya pada cakera yang kecil.
Letakkan gateway di belakang reverse proxy
Tiada apa-apa dari luar pelayan boleh mencapai port 4000. Tamatkan TLS dalam nginx atau Caddy dan hantarkan permintaan ke alamat loopback.
location / {
proxy_pass http://127.0.0.1:4000;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
proxy_read_timeout 600s;
}Dua baris tersebut sering ditinggalkan. proxy_buffering off penting kerana completion penstriman ialah siri server-sent events. Apabila buffering diaktifkan, nginx mengumpulkan chunk dalam buffer sebelum menghantarnya, lalu melambatkan penghantaran kepada klien. proxy_read_timeout 600s penting kerana nilai lalai nginx, iaitu 60 saat, ialah tempoh maksimum nginx menunggu antara dua bacaan daripada gateway, bukan had untuk keseluruhan respons. Completion tanpa penstriman tidak menghantar apa-apa sehingga penjanaan selesai. Oleh itu, completion yang panjang boleh melebihi 60 saat tanpa satu bait pun tiba, lalu klien menerima 504 dan log ralat merekodkan upstream timed out (110: Connection timed out) while reading response header from upstream. Completion berpenstriman yang terus menghantar chunk boleh berjalan jauh lebih lama daripada 60 saat. Timeout hanya berlaku jika model tidak menghantar data selama tempoh tersebut.
Untuk sijil, Certbot dengan Let's Encrypt pada nginx ialah cara paling ringkas. Jika pelayan tersebut sudah menyediakan beberapa container, Traefik di hadapan beberapa aplikasi Compose mengurus penghalaan dan sijil di satu tempat.
Gateway itu kini menjadi satu titik kegagalan
Nyatakan dengan jelas perkara yang telah anda bina. Setiap aplikasi yang anda uruskan kini bergantung pada satu container dalam satu VPS. Apabila container itu tidak berfungsi, tiada apa-apa yang dapat memanggil mana-mana model, termasuk provider yang berfungsi dengan baik. Empat perkara berikut perlu diberi perhatian.
- Konfigurasi yang salah akan menghentikan semuanya serentak.
restart: unless-stoppedmemulakan semula proses yang crash, termasuk container yang tidak dapat menghuraikan config.yaml, berulang kali. Bacadocker compose logs litellmselepas setiap perubahan konfigurasi, dan buat perubahan konfigurasi apabila anda mempunyai masa untuk memantaunya. - Postgres berada dalam laluan permintaan apabila cache miss berlaku. Carian virtual key menggunakan Postgres apabila key itu tiada dalam cache; rekod penggunaan dijalankan secara tak segerak selepas respons dihantar.
/health/readinessyang mengembalikan 503 ialah amaran bahawa gateway sedang berjalan tetapi tidak dapat melakukan kedua-dua operasi tersebut. - Gunakan core terlebih dahulu, kemudian tambah instance. Panduan produksi projek yang menetapkan satu worker bagi setiap instance (
--num_workers 1) adalah untuk Kubernetes atau autoscaler pod yang lain, yang menambah instance untuk anda. Untuk satu VM atau container kendiri seperti ini, panduan itu membawa maksud yang sebaliknya: tetapkan bilangan worker mengikut bilangan vCPU mesin. Pada mesin 1 vCPU di atas, nilainya masih--num_workers 1; pada mesin yang lebih besar, naikkan nilai itu dan ingat bahawa setiap worker menggunakan memorinya sendiri. Gateway kedua di belakang load balancer menghapuskan kebergantungan pada satu container sahaja. Namun, database masih menjadi kebergantungan. - Sandarkan perkara yang tidak boleh dijana semula. Perkara itu ialah
config.yamldan.env, bersama-samapg_dumpdatabase. KehilanganLITELLM_SALT_KEYmenyebabkan credential provider yang disulitkan di dalam dump itu tidak boleh digunakan. Oleh itu, fail env dan dump perlu dimasukkan dalam kerja backup yang sama: backup restic ke storan di luar pelayan.
Proses upgrade hanya memerlukan anda mengedit image tag dan menjalankan docker compose up -d. Secara lalai, LiteLLM menjalankan prisma migrate deploy semasa startup, jadi container baharu akan memigrasikan skema database pada boot pertamanya. Ambil dump sebelum menukar tag, kerana menggunakan semula image lama tidak akan membatalkan migration yang telah dijalankan.
Baca release notes bagi setiap versi yang anda langkau, bukan hanya versi yang anda pasang. Peralihan daripada v1.95.0 kepada v1.104.0 atau versi yang lebih baharu merentasi beberapa perubahan yang tidak serasi: status code budget di atas, proxy yang enggan bermula apabila master key tidak ditetapkan, kosong atau diketahui umum, serta proxy yang keluar apabila setup database gagal semasa startup. Di bawah restart: unless-stopped, keadaan ini muncul sebagai restart loop. Jika anda datang daripada v1.102.x atau versi yang lebih awal, nota v1.104.0 juga meminta anda membina sendiri dua index LiteLLM_SpendLogs.
FAQ
Adakah LiteLLM menambah latensi yang ketara pada setiap panggilan?
Projek ini mencatatkan 8 ms pada persentil ke-95 pada 1000 permintaan sesaat, seperti yang dinyatakan dalam README-nya pada November 2026. Anggap itu sebagai angka daripada vendor. Angka yang sebenarnya mempengaruhi latensi anda ialah jarak rangkaian antara aplikasi anda dan gateway, kerana anda telah menambah satu perjalanan pergi-balik (round trip) pada setiap panggilan. Jalankan gateway di rantau yang sama dengan aplikasi yang memanggilnya, kemudian ukur overhead anda sendiri dengan header x-litellm-overhead-duration-ms pada respons sebenar.
Mengapa penstriman berhenti berfungsi selepas saya meletakkan nginx di hadapan?
Ini kerana nginx menimbal (buffer) respons upstream secara lalai dan penyiapan penstriman adalah satu siri peristiwa yang dihantar oleh pelayan (server-sent events). Dengan proxy_buffering diaktifkan, nginx mengumpul cebisan data dalam penimbal sebelum menghantarnya, yang melambatkan penghantaran kepada klien. Tetapkan proxy_buffering off; dalam blok location. Tingkatkan juga proxy_read_timeout dalam blok yang sama. Secara lalai, nginx akan berhenti selepas 60 saat tanpa data daripada gateway, yang mudah dicapai oleh penjanaan bukan penstriman yang panjang, dan klien akan menerima ralat 504.
Apa yang berlaku apabila kunci maya (virtual key) kehabisan bajet?
Panggilan akan gagal dengan ralat jenis budget_exceeded dan mesej dalam bentuk Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>. Pada versi v1.95.0 yang disematkan, statusnya ialah HTTP 429; bermula dari v1.104.0, lalai yang digunakan ialah HTTP 422. Tiada satu pun kod tersebut menyatakan tentang bajet, dan itulah perangkapnya: pustaka klien melaporkan 429 sebagai had kadar (rate limit) dan mungkin mencuba semula, jadi pengguna mula mengejar isu pendikitan (throttling) dan bukannya membaca mesej tersebut. Log badan respons bersama-sama dengan kod status. Sahkan kedudukan sebenar kunci tersebut dengan /key/info?key=sk-... berbanding kunci induk, dan tingkatkan had dengan /key/update jika bajet ditetapkan terlalu rendah.
Bolehkah gateway menghalakan trafik ke model tempatan selain model yang dihoskan?
Ya, dan ia merupakan satu lagi entri dalam model_list. Gunakan awalan ollama_chat/ dengan api_base, contohnya model: ollama_chat/llama3.1 bersama-sama api_base: http://ollama:11434. Pada rangkaian lalai Compose, localhost di dalam kontena bermaksud kontena itu sendiri, jadi gunakan nama servis Compose atau alamat hos pada rangkaian Docker, jangan sekali-kali menggunakan 127.0.0.1. Rangkaian hos (host networking), di mana kontena berkongsi tindanan rangkaian hos, adalah pengecualian. Menyediakan model tempatan adalah tugas yang berasingan: lihat self-hosting an LLM with Ollama on a VPS.