SSD Nodes Learn Hosting plans →
Panduan Matt ConnorOleh Matt Connor

Cara Host LiteLLM sebagai Gateway LLM Sendiri

Pelajari cara menjalankan LiteLLM di VPS sebagai satu endpoint OpenAI-compatible, lengkap dengan virtual key, anggaran per key, fallback, dan pinned image.

Fungsi gateway LLM yang di-host sendiri

LiteLLM adalah gateway LLM sumber terbuka yang Anda host sendiri: satu endpoint HTTP yang digunakan semua aplikasi Anda, lalu meneruskan setiap permintaan ke provider yang seharusnya menanganinya. LLM berarti large language model. Gateway ini menggunakan OpenAI chat completions API (application programming interface), sehingga library klien yang sudah berkomunikasi dengan OpenAI dapat digunakan melalui gateway ini setelah dua perubahan: base URL dan key.

Lapisan perantara ini adalah inti pendekatannya. Aplikasi Anda tidak lagi menyimpan kredensial provider. Penggantian model cukup dilakukan pada satu baris dalam file konfigurasi di server, bukan dengan mengubah kode pada lima service. Karena setiap panggilan melewati satu proses, Anda memiliki tempat untuk menetapkan anggaran dan mencatat pengeluaran.

Setelah gateway berjalan, Anda memiliki hal-hal berikut:

  • Satu endpoint. Aplikasi mengarah ke https://gateway.example.com/v1 dan meminta nama model yang Anda tentukan sendiri, seperti bulk atau strong.
  • Virtual key. Setiap aplikasi memperoleh key sendiri, dengan allowlist model dan batas pengeluaran masing-masing. Anda dapat mencabut satu key tanpa memengaruhi key lainnya.
  • Fallback. Panggilan yang gagal atau prompt yang terlalu besar akan otomatis dicoba ulang menggunakan model lain.
  • Catatan dalam log. Setiap permintaan menulis satu baris yang memuat biayanya, sehingga pertanyaan "aplikasi mana yang menghabiskan biaya itu" memiliki jawabannya.

Mengapa gateway dijalankan sendiri

Router terkelola memiliki arsitektur yang sama, tetapi proses milik pihak lain berada di antara setiap permintaan. Dengan menjalankannya sendiri, kunci provider dan teks prompt tetap berada pada server yang Anda kendalikan. Biayanya nyata: kini Anda mengoperasikan komponen yang menjadi dependensi setiap aplikasi. Bagian terakhir panduan ini membahas biaya tersebut karena aspek ini sering tidak dibahas dalam panduan lain.

Yang Anda perlukan

  • VPS (virtual private server) yang menjalankan Ubuntu 24.04, dengan Docker dan plugin Compose terpasang.
  • Nama domain yang mengarah ke VPS tersebut jika mesin di luar server akan mengakses gateway melalui TLS (transport layer security).
  • Setidaknya satu kunci API provider.

Gateway tidak menjalankan inference. Gateway meneruskan request dan mengalirkan jawaban kembali, sehingga beban CPU mengikuti volume request, bukan ukuran model. Server dengan 1 vCPU dapat menjalankan beberapa aplikasi internal tanpa masalah. Database yang bertambah besar karena gateway menulis satu baris pengeluaran untuk setiap request.

Tulis config.yaml terlebih dahulu

File konfigurasi menentukan model yang dapat diminta klien. Ada empat bagian tingkat teratas yang 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: 300

model_name adalah nama yang dikirim klien. litellm_params.model adalah model sebenarnya, yang ditulis sebagai provider/model. Beri nama model berdasarkan tugasnya, bukan vendornya. Aplikasi yang meminta bulk akan tetap berfungsi ketika bulan depan Anda memutuskan bahwa bulk harus menggunakan model yang berbeda.

api_key: os.environ/ANTHROPIC_API_KEY memberi tahu LiteLLM agar membaca variabel tersebut saat runtime. Kunci literal tidak pernah muncul dalam file. Hal ini penting karena config.yaml adalah file yang Anda commit.

Dua entri menggunakan nama strong, dan itu memang disengaja. Jika lebih dari satu deployment memiliki model_name yang sama, router memperlakukannya sebagai deployment yang dapat saling menggantikan dan membagi permintaan untuk nama tersebut di antara semuanya. Dengan cara ini, strong tetap berjalan ketika salah satu provider mengalami masalah sementara: setelah sebuah deployment masuk cooldown (lihat di bawah), permintaan baru untuk strong dialihkan ke deployment lainnya.

num_retries: 2 mencoba kembali error yang dapat diulang hingga dua kali. Percobaan ulang tersebut dapat memilih deployment lain yang tersedia dalam grup model yang sama. Dokumentasi arsitektur LiteLLM, yang diperiksa pada 2026-10-29, menjelaskan bahwa percobaan ulang dalam grup dan fallback lintas grup merupakan langkah yang terpisah. Oleh karena itu, percobaan ulang untuk strong dapat dialihkan ke provider lain tanpa mengaktifkan weighted failover. Fallback hanya dijalankan setelah seluruh percobaan ulang tersebut habis.

allowed_fails dan cooldown_time adalah opsi router, sehingga keduanya ditempatkan di bawah router_settings. Proxy membangun router berdasarkan bagian tersebut. Pada v1.95.0, cooldown_time yang ditulis di bawah litellm_settings tidak pernah diteruskan ke router. Akibatnya, cooldown secara diam-diam tetap menggunakan nilai default 5 detik. cooldown_time: 30 menentukan berapa lama deployment tetap dikeluarkan dari rotasi setelah masuk cooldown. Referensi konfigurasi menjelaskan allowed_fails sebagai jumlah kegagalan yang harus dilampaui deployment dalam periode cooldown_time sebelum masuk cooldown. Dalam source v1.95.0, allowed_fails: 3 adalah nilai default. Dengan nilai default tersebut, router menggunakan pemicu bawaan. Jumlah kegagalan baru digunakan jika Anda menetapkan angka yang berbeda. Pemicu tersebut mencakup cooldown langsung setelah respons 429 untuk grup yang memiliki lebih dari satu deployment, lebih dari 50% kegagalan pada menit berjalan setelah sedikitnya 5 permintaan untuk grup tersebut, serta error yang tidak akan dicoba ulang oleh router, seperti respons 401 akibat key yang salah. Ada pemicu terpisah yang juga memasukkan satu-satunya deployment ke cooldown ketika semua permintaan pada menit berjalan gagal dan trafik mencapai SINGLE_DEPLOYMENT_TRAFFIC_FAILURE_THRESHOLD, yang secara default adalah 1000 permintaan. Jadi, untuk strong yang memiliki dua deployment, provider yang mengembalikan respons 500 secara berturut-turut tidak akan dicoba pada setiap permintaan, sedangkan satu respons 500 setiap beberapa menit tidak pernah memicu cooldown. bulk hanya memiliki satu deployment, sehingga pemicu berdasarkan tingkat kegagalan tidak berlaku untuknya. Rangkaian respons 500 yang tetap berada di bawah 1000 permintaan per menit akan membuatnya tetap berada dalam rotasi. Yang melindungi pemanggilnya adalah num_retries, kemudian fallback ke strong.

fallbacks dan context_window_fallbacks memiliki pemicu yang berbeda. Pemicu kedua sering dilewatkan, padahal berguna.

  • fallbacks dijalankan ketika pemanggilan utama gagal.
  • context_window_fallbacks dijalankan ketika provider menolak permintaan karena panjangnya melebihi context window model tersebut. Dengan demikian, prompt yang terlalu besar dialihkan ke model yang memiliki kapasitas cukup, bukan dikembalikan sebagai error kepada pemanggil.

Ada juga content_policy_fallbacks untuk provider yang menolak permintaan berdasarkan kebijakan konten. Tetapkan opsi ini hanya jika Anda memiliki tujuan yang sesuai untuk mengalihkan permintaan tersebut.

Deploy LiteLLM pada VPS dengan Docker Compose

Buat sebuah direktori yang berisi tiga file: config.yaml, docker-compose.yml, dan .env. Quickstart upstream menggunakan tag latest. Gunakan tag rilis tertentu sebagai gantinya agar upgrade hanya terjadi setelah Anda mengedit file, dan rollback cukup dilakukan dengan mengubah satu baris. Tag saja tidak menjamin isi image tetap identik, karena tag image dapat diubah dan publisher dapat mengarahkannya ke image baru. Jika docker compose up -d bulan depan harus menyediakan gateway yang sama persis seperti hari ini, tambahkan juga image digest dalam format ghcr.io/berriai/litellm:v1.95.0@sha256:<digest>; docker buildx imagetools inspect ghcr.io/berriai/litellm:v1.95.0 menampilkannya.

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. Pertama, untuk mengganti ${POSTGRES_PASSWORD} di dalam file compose itu sendiri. Kedua, melalui env_file untuk meneruskan setiap variabel ke dalam container.

v1.95.0 adalah rilis terbaru pada Agustus 2026. Periksa halaman rilis proyek dan gunakan pin untuk versi yang sedang berlaku saat Anda melakukan deployment. Setiap rilis menerbitkan signature, sehingga Anda dapat memeriksa image sebelum mempercayainya:

cosign verify --key https://raw.githubusercontent.com/BerriAI/litellm/v1.95.0/cosign.pub ghcr.io/berriai/litellm:v1.95.0

Baris port adalah 127.0.0.1:4000:4000, yang hanya memublikasikan port pada interface loopback. Jika Anda menulis 4000:4000, gateway dapat dijangkau dari seluruh Internet karena Docker menambahkan aturannya sendiri ke chain FORWARD pada iptables, dan aturan tersebut dievaluasi sebelum aturan ufw. Akibatnya, ufw deny 4000 tidak dapat menghentikannya. Ini adalah cara paling umum gateway yang di-host sendiri terbuka ke Internet: lihat cara Docker memublikasikan port container langsung melewati ufw. Trafik dari luar masuk melalui reverse proxy.

Simpan kunci provider di luar image

File .env menyimpan semua secret. File ini diberikan sebagai environment saat runtime, sehingga tidak pernah ditanamkan ke dalam image dan tidak pernah di-commit.

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-...

Buat kedua kunci LiteLLM menggunakan sumber keacakan yang kuat, lalu batasi akses ke file tersebut:

printf 'sk-%s\n' "$(openssl rand -hex 32)"
chmod 600 .env

LITELLM_MASTER_KEY adalah kredensial admin. Kredensial ini mengautentikasi management API dan menjadi password untuk Admin UI di /ui. Jangan pernah menyimpan kredensial ini pada aplikasi.

LITELLM_SALT_KEY mengenkripsi kredensial provider yang disimpan dalam database. Tetapkan nilainya sekali dan jangan mengubahnya. Jika nilainya diubah kemudian, kredensial yang sudah tersimpan tidak dapat didekripsi. Akibatnya, gateway berhasil start secara normal, tetapi setiap panggilan ke provider tersebut gagal saat autentikasi.

STORE_MODEL_IN_DB=True memungkinkan Anda menambahkan dan mengedit model dari Admin UI tanpa mengubah config.yaml. Cara ini praktis, tetapi membagi sumber kebenaran menjadi dua. Tentukan sumber yang menjadi acuan dan tuliskan keputusan tersebut di sebelah config.

Alasan untuk menyimpan kunci di luar file config sama dengan alasan untuk menyimpannya di luar tools yang Anda berikan kepada agent. Menyimpan secret provider di luar AI agent membahas pola tersebut, sedangkan file env dan secret dalam Docker Compose membahas penerapannya.

Jalankan layanan dan pantau boot pertama:

docker compose up -d
docker compose logs -f litellm

Periksa bahwa layanan benar-benar berjalan

Terdapat dua probe tanpa autentikasi dan satu probe dengan autentikasi. Ketiganya dapat gagal karena alasan yang berbeda.

curl -s http://127.0.0.1:4000/health/liveliness
curl -s http://127.0.0.1:4000/health/readiness

/health/liveliness tidak memerlukan autentikasi dan memberikan respons "I'm alive!" selama proses masih berjalan. /health/readiness juga tidak memerlukan autentikasi. Endpoint ini mengembalikan objek JSON dengan field "status": "healthy" dan field db, atau mengembalikan 503 jika database tidak dapat dijangkau. Arahkan pemantauan ke readiness, karena liveliness tetap berstatus hijau pada gateway yang tidak dapat mencari satu pun kunci virtual.

Pemeriksaan dengan autentikasi adalah pemeriksaan yang berkomunikasi dengan provider:

curl -s http://127.0.0.1:4000/health \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

Pemeriksaan ini memberikan respons berupa array healthy_endpoints dan unhealthy_endpoints. Model yang berada dalam unhealthy_endpoints dan mengalami error autentikasi menunjukkan bahwa provider key dalam .env salah atau belum diatur. Inilah kegagalan yang perlu ditemukan sekarang. Karena background_health_checks: true diatur, proxy menjalankan probe ini sendiri setiap health_check_interval detik dan /health mengembalikan hasil terakhir. Dengan demikian, polling endpoint tersebut tidak mengirimkan test request ke provider setiap kali.

Kunci virtual dan anggaran per kunci

Setiap aplikasi mendapatkan kuncinya sendiri, yang dibuat menggunakan master key.

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 memiliki field key yang diawali dengan sk-. String itu adalah kredensial yang diterima aplikasi, dan hanya itu yang pernah diterima aplikasi.

  • models adalah allowlist untuk permintaan yang boleh dibuat oleh kunci ini. Kunci di atas hanya dapat meminta bulk dan tidak dapat meminta yang lain.
  • max_budget: 5 dengan budget_duration: "30d" adalah lima dolar AS per bulan kalender. LiteLLM mereset anggaran 30d pada tanggal 1 setiap bulan pukul 00.00, dalam UTC kecuali Anda menetapkan timezone di bawah litellm_settings, bukan berdasarkan periode 30 hari berjalan. Jadi, setelah kunci tersebut membelanjakan lima dolar, kunci itu berhenti berfungsi sampai tanggal 1 berikutnya.
  • rpm_limit dan tpm_limit membatasi jumlah permintaan per menit dan token per menit hanya untuk kunci ini.
  • key_alias adalah nama yang akan Anda kenali dalam log pengeluaran enam minggu kemudian. Selalu tetapkan nilai ini.

Saat anggaran habis, panggilan gagal dengan error bertipe budget_exceeded dan pesan dengan bentuk berikut:

Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>

Kode status bergantung pada rilis. Pada v1.95.0 yang dikunci, kodenya adalah HTTP 429. Mulai v1.104.0, nilai defaultnya adalah HTTP 422, dan penetapan budget_exceeded_status_code: 429 di bawah litellm_settings mengembalikan kode sebelumnya. Permintaan yang benar-benar terkena batas rpm_limit dan tpm_limit tetap mengembalikan 429 pada kedua rilis. Periksa kode yang Anda dapatkan setelah setiap upgrade.

Kode status inilah yang menyebabkan kebingungan, karena tidak ada satu pun dari kedua kode tersebut yang menyatakan "anggaran". Library klien melaporkan 429 sebagai rate limit dan mungkin mencoba ulang dengan backoff terhadap anggaran yang tidak akan tersedia kembali sampai reset. Library tersebut melaporkan 422 sebagai permintaan yang tidak dapat diproses. Catat body respons bersama kode status. Jika tidak, kehabisan anggaran akan selalu terlihat seperti masalah lain.

Periksa dan sesuaikan kunci melalui management API 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}'

Anggaran yang diberlakukan di gateway tetap berlaku meskipun masalahnya berasal dari agent itu sendiri. Karena itu, anggaran ini menjadi fondasi pengendalian biaya untuk agent AI pada VPS.

Kirim pekerjaan massal ke model murah

Arahkan client ke gateway. Base URL, key, dan 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."}]
  }'

Semua library client OpenAI bekerja dengan cara yang sama, meskipun nama opsinya berbeda menurut bahasa pemrograman. Pada client Python, atur base_url ke https://gateway.example.com/v1 dan api_key ke virtual key. Pemanggilan client JavaScript dan TypeScript menggunakan dua opsi yang sama, yaitu baseURL dan apiKey.

Kebijakan routing dari config.yaml kini berlaku tanpa perlu diketahui pemanggil. Permintaan untuk bulk diarahkan ke model murah. Jika pemanggilan tersebut gagal setelah seluruh percobaan ulang, permintaan dicoba kembali menggunakan strong. Jika prompt terlalu panjang untuk bulk, context_window_fallbacks mengirimkannya ke strong alih-alih mengembalikan error. Pekerjaan massal seperti proses klasifikasi atau backlog peringkasan berjalan menggunakan model murah secara default. Hanya permintaan yang sulit yang dikenai biaya lebih tinggi.

Di sinilah gateway juga memberikan manfaat untuk agent yang menggunakan tool. Server MCP (protokol konteks model) pada VPS yang sama dan agent yang mengendalikannya dapat diarahkan ke satu endpoint. Dengan demikian, model di balik keduanya dapat diubah tanpa men-deploy ulang salah satunya.

Bagaimana cara mengetahui bahwa fallback terjadi?

Ini adalah mode kegagalan yang menimbulkan biaya, karena tidak ada yang terlihat rusak. Fallback yang berhasil mengembalikan HTTP 200 dengan body respons biasa. Model murah Anda dapat tidak tersedia selama sehari, setiap panggilan diam-diam dilayani oleh model mahal, dan bukti pertama muncul pada invoice.

Buktinya ada di response header. Minta 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-group adalah nama model yang digunakan untuk merutekan request, misalnya bulk. x-litellm-model-id adalah ID deployment yang memberikan respons. Anda dapat mencarinya dengan /v1/model/info?litellm_model_id=.... Jika ID tersebut bukan salah satu deployment bulk milik Anda, berarti fallback terjadi.
  • x-litellm-attempted-fallbacks dan x-litellm-attempted-retries menghitung jumlahnya. Pada panggilan yang normal, tidak satu pun menampilkan jumlah di atas 0.
  • x-litellm-response-cost adalah biaya panggilan tersebut dalam dolar AS.
  • x-litellm-call-id adalah identifier yang digunakan untuk menemukan panggilan yang sama di log.

Catat x-litellm-attempted-fallbacks pada setiap request dan buat alert setiap kali nilainya di atas 0. Angka tersebut membedakan routing policy yang berfungsi dari routing policy yang diam-diam berubah menjadi "selalu gunakan model mahal".

Versi lengkapnya adalah tracing, dan fitur ini memerlukan setup tersendiri: Langfuse self-hosted untuk tracing panggilan agent. LiteLLM menyediakan callback tersebut, sehingga konfigurasinya hanya memerlukan dua baris dan kredensial.

litellm_settings:
  success_callback: ["langfuse"]
  failure_callback: ["langfuse"]
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://langfuse.example.com

Untuk Langfuse v3 dan versi yang lebih baru, halaman Langfuse LiteLLM kini merekomendasikan preset langfuse_otel; callback langfuse di atas masih didokumentasikan. Tetapkan failure_callback dan success_callback. Jika dilewati, satu-satunya trace yang disimpan adalah trace ketika tidak ada yang bermasalah. Terlepas dari semua ini, LiteLLM menulis satu baris spend untuk setiap request ke Postgres, dan Admin UI pada /ui membaca tabel tersebut. Tabel ini bertambah seiring traffic, jadi pantau penggunaannya jika disk berukuran kecil.

Letakkan gateway di belakang reverse proxy

Tidak boleh ada koneksi dari luar server ke port 4000. Hentikan TLS di nginx atau Caddy, lalu teruskan koneksi 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 diabaikan. proxy_buffering off penting karena completion streaming terdiri atas serangkaian server-sent events. Jika buffering aktif, nginx mengumpulkan chunk dalam buffer sebelum meneruskannya sehingga pengiriman ke klien tertunda. proxy_read_timeout 600s penting karena default nginx sebesar 60 detik adalah waktu tunggu maksimum antara dua pembacaan dari gateway, bukan batas untuk seluruh respons. Completion yang tidak menggunakan streaming tidak mengirim apa pun sampai proses pembuatan selesai. Karena itu, proses yang lama dapat melewati 60 detik tanpa satu byte pun diterima, lalu klien mendapatkan 504 sementara error log mencatat upstream timed out (110: Connection timed out) while reading response header from upstream. Completion streaming yang terus mengirim chunk dapat berjalan jauh lebih lama dari 60 detik. Timeout hanya terjadi jika model tidak mengirim data selama itu.

Untuk sertifikat, Certbot dengan Let's Encrypt pada nginx adalah cara paling singkat. Jika server sudah melayani beberapa container, Traefik di depan beberapa aplikasi Compose menangani routing dan sertifikat dari satu tempat.

Gateway kini menjadi satu-satunya titik kegagalan

Pahami risiko dari arsitektur yang telah Anda bangun. Semua aplikasi yang Anda kelola kini bergantung pada satu container di satu VPS. Saat container tersebut tidak aktif, tidak ada aplikasi yang dapat memanggil model apa pun, termasuk provider yang sebenarnya tetap sehat. Ada empat konsekuensi.

  • Konfigurasi yang buruk dapat menghentikan semuanya sekaligus. restart: unless-stopped me-restart container yang mengalami crash, termasuk container yang tidak dapat mem-parsing config.yaml, berulang kali. Baca docker compose logs litellm setiap kali selesai mengubah konfigurasi, dan lakukan perubahan saat Anda memiliki waktu untuk memantaunya.
  • Postgres berada dalam jalur request saat cache miss. Pencarian virtual key menggunakannya ketika key tidak berada di cache; pencatatan penggunaan berlangsung secara asynchronous setelah response dikirim. /health/readiness yang mengembalikan 503 menunjukkan bahwa gateway masih berjalan, tetapi tidak dapat melakukan kedua hal tersebut.
  • Gunakan core terlebih dahulu, lalu tambahkan instance. Panduan produksi proyek yang menetapkan satu worker per instance (--num_workers 1) ditujukan untuk Kubernetes atau autoscaler pod lain yang menambahkan instance secara otomatis. Untuk satu VM atau bare container seperti ini, panduannya justru berlawanan: tetapkan jumlah worker sesuai jumlah vCPU mesin. Pada mesin 1 vCPU di atas, nilainya tetap --num_workers 1; pada mesin yang lebih besar, naikkan nilainya dan ingat bahwa setiap worker menggunakan memorinya sendiri. Gateway kedua di belakang load balancer menghilangkan ketergantungan pada satu container. Namun, database tetap menjadi ketergantungan.
  • Cadangkan data yang tidak dapat dibuat ulang. Data tersebut adalah config.yaml dan .env, bersama pg_dump database. Kehilangan LITELLM_SALT_KEY membuat kredensial provider terenkripsi di dalam dump tersebut tidak berguna. Karena itu, env file dan dump harus dicadangkan dalam job backup yang sama: backup restic ke penyimpanan di luar server.

Upgrade dilakukan dengan mengubah image tag dan menjalankan docker compose up -d. Secara default, LiteLLM menjalankan prisma migrate deploy saat startup, sehingga container baru memigrasikan schema database pada boot pertamanya. Buat dump sebelum mengubah tag, karena mengembalikan image lama tidak membatalkan migration yang sudah dijalankan.

Baca release notes untuk setiap versi yang Anda lewati, bukan hanya versi yang Anda gunakan. Perpindahan dari v1.95.0 ke v1.104.0 atau versi yang lebih baru melewati beberapa perubahan yang dapat menyebabkan inkompatibilitas: status code budget di atas, proxy yang menolak start jika master key tidak disetel, kosong, atau sudah diketahui publik, serta proxy yang keluar saat setup database gagal pada startup. Dengan restart: unless-stopped, kondisi terakhir tersebut muncul sebagai loop restart. Jika berasal dari v1.102.x atau versi yang lebih lama, catatan v1.104.0 juga meminta Anda membuat sendiri dua index LiteLLM_SpendLogs.

FAQ

Apakah LiteLLM menambahkan latensi yang terasa pada setiap panggilan?

Proyek ini mencantumkan 8 ms pada persentil ke-95 dengan 1000 request per detik, sebagaimana dinyatakan dalam README-nya pada November 2026. Anggap angka tersebut sebagai angka dari vendor. Faktor yang benar-benar memengaruhi latensi Anda adalah jarak jaringan antara aplikasi dan gateway, karena Anda menambahkan satu round trip pada setiap panggilan. Jalankan gateway di region yang sama dengan aplikasi yang memanggilnya, lalu ukur overhead Anda sendiri menggunakan header x-litellm-overhead-duration-ms pada response nyata.

Mengapa streaming berhenti berfungsi setelah saya menempatkan nginx di depannya?

Karena nginx secara default melakukan buffering pada response upstream, sedangkan completion streaming terdiri atas rangkaian server-sent events. Saat proxy_buffering aktif, nginx mengumpulkan chunk dalam buffer sebelum meneruskannya, sehingga pengiriman ke client tertunda. Tetapkan proxy_buffering off; pada location block. Naikkan proxy_read_timeout pada block yang sama. Secara default, nginx berhenti menunggu setelah 60 detik tanpa data dari gateway. Generasi non-streaming yang panjang dapat dengan mudah mencapai batas ini, sehingga client menerima 504.

Apa yang terjadi ketika virtual key kehabisan anggaran?

Panggilan gagal dengan error bertipe budget_exceeded dan pesan dalam bentuk Budget has been exceeded! Key=<key> Current cost: <spend>, Max budget: <max_budget>. Pada v1.95.0 yang dipatok, statusnya adalah HTTP 429; mulai v1.104.0, default-nya adalah HTTP 422. Tidak satu pun dari kedua kode tersebut menyebut anggaran. Di sinilah jebakannya: library client melaporkan 429 sebagai rate limit dan mungkin melakukan retry, sehingga orang mulai mencari penyebab throttling alih-alih membaca pesannya. Catat response body bersama status code. Konfirmasikan posisi sebenarnya dari key dengan /key/info?key=sk-... menggunakan master key, lalu naikkan batasnya dengan /key/update jika anggarannya terlalu rendah.

Dapatkah gateway merutekan ke model lokal selain model yang di-host?

Ya, dan model tersebut menjadi satu entri tambahan dalam model_list. Gunakan prefix ollama_chat/ dengan api_base, misalnya model: ollama_chat/llama3.1 bersama api_base: http://ollama:11434. Pada networking default Compose, localhost di dalam container berarti container tersebut, jadi gunakan nama service Compose atau alamat host pada jaringan Docker, bukan 127.0.0.1. Host networking, ketika container menggunakan network stack host secara bersama, merupakan pengecualian. Menjalankan model lokal adalah tugas terpisah. Lihat self-hosting LLM dengan Ollama pada VPS.

Apakah artikel ini bermanfaat?