Self-host LiteLLM Proxy: kunci virtual, kontrol anggaran, serta perbandingan dengan New API dan Magpie

Menaruh kunci API utama dari penyedia model langsung ke setiap aplikasi atau laptop anggota tim membuat Anda tidak bisa membatasi berapa banyak biaya yang dihabiskan satu layanan, dan saat harus merotasi kunci Anda terpaksa mengubah konfigurasi di banyak tempat. LiteLLM adalah salah satu proxy LLM open source paling populer di ekosistem Python dan rekayasa AI: ia menyatukan lebih dari 100 penyedia model di balik satu endpoint yang kompatibel dengan OpenAI, lengkap dengan dashboard admin /ui, kunci virtual (Virtual Keys), batas anggaran (Budgets), serta log pengeluaran per permintaan.

Panduan ini menggunakan template LiteLLM dari Zenavo untuk men-deploy LiteLLM beserta PostgreSQL di server Linux Anda sendiri, sekaligus membandingkannya dengan New API dan Magpie. Server, Zenavo, dan API model upstream ditagih secara terpisah.

1. Deploy LiteLLM dan PostgreSQL

Hubungkan server Linux ke Zenavo (disarankan memori minimal 1 GB), buka template LiteLLM, pilih server Anda, lalu deploy.

Proyek ini langsung menjalankan dua layanan yang saling terhubung melalui jaringan privat proyek:

Layanan / Variabel	Nilai atau fungsi
litellm	Image ghcr.io/berriai/litellm:v1.109.1, port HTTP 4000
postgresql	Image postgres:16, database litellm, volume persisten /var/lib/postgresql/data
LITELLM_MASTER_KEY	Kunci master sk-... yang dibuat otomatis untuk login ke /ui dan memanggil API admin
LITELLM_SALT_KEY	Salt enkripsi otomatis untuk mengenkripsi kunci API penyedia upstream di dalam PostgreSQL
STORE_MODEL_IN_DB	True, sehingga model yang ditambahkan lewat /ui tersimpan secara permanen di PostgreSQL

Jangan pernah mengubah LITELLM_SALT_KEY setelah menyimpan kredensial: LiteLLM memakai LITELLM_SALT_KEY untuk mengenkripsi dan mendekripsi kunci API penyedia di dalam database. Mengubahnya di kemudian hari akan membuat seluruh kunci penyedia yang tersimpan tidak bisa dibaca. Salin LITELLM_MASTER_KEY dan LITELLM_SALT_KEY ke pengelola kata sandi Anda (seperti Vaultwarden self-hosted) segera setelah deploy selesai.

2. Pasang domain dan login ke /ui

1. Di tab Networking pada layanan litellm, pasang domain kustom seperti llm.example.com ke port 4000, lalu tambahkan record DNS A yang mengarah ke server Anda. Lihat Domain & HTTPS.
2. Di tab Variable pada layanan litellm, salin nilai LITELLM_MASTER_KEY.
3. Buka https://llm.example.com/ui dan masuk dengan username admin serta LITELLM_MASTER_KEY.

postgresql hanya diakses oleh litellm melalui jaringan privat dan tidak memerlukan akses publik.

3. Tambahkan model dan terbitkan kunci virtual

Tambahkan model upstream

Karena template sudah mengaktifkan STORE_MODEL_IN_DB="True", Anda tidak perlu mengedit file konfigurasi YAML:

1. Di /ui, buka Models → Add Model.
2. Pilih penyedia (OpenAI, Anthropic, DeepSeek, Gemini, Azure, Bedrock, dll.), masukkan alias model yang akan dipanggil klien (misalnya claude-sonnet atau gpt-4o), lalu tempelkan kunci API upstream.
3. Simpan dan kirim permintaan uji coba di Test Key / Playground untuk memastikan respons berjalan lancar.

Terbitkan Kunci Virtual (Virtual Keys) dengan batas anggaran

Jangan gunakan LITELLM_MASTER_KEY secara langsung di kode aplikasi atau alat harian. Buka Virtual Keys → Create New Key:

• Buat kunci terpisah untuk setiap aplikasi, rekan tim, atau alat (misalnya nextjs-prod, open-webui, claude-code-alex);
• Batasi daftar model yang boleh dipanggil oleh kunci tersebut;
• Tetapkan Max Budget (misalnya $20), periode reset anggaran (harian atau bulanan), serta batas laju permintaan (TPM / RPM).

4. Hubungkan aplikasi, agen coding, dan antarmuka chat

Semua SDK atau klien yang mendukung Base URL OpenAI kustom dapat langsung terhubung ke LiteLLM:

• Backend aplikasi (OpenAI SDK / LangChain / Vercel AI SDK): isi Base URL dengan https://llm.example.com/v1 dan API Key dengan kunci virtual. Jika aplikasi Anda berjalan di proyek Zenavo yang sama (seperti aplikasi Next.js + PostgreSQL), panggil langsung http://litellm.zenavo.internal:4000/v1 lewat jaringan privat.
• Claude Code dan Codex CLI: LiteLLM juga melayani endpoint /v1/messages dan /v1/responses; atur dengan variabel lingkungan yang sama seperti di panduan New API. Jika Anda juga ingin memeriksa log, men-deploy, dan melakukan rollback layanan Zenavo dari Claude Code, lihat Deploy dan debug proyek Zenavo dari Claude Code.
• Antarmuka chat dan asisten pribadi: di Open WebUI, LobeHub, atau OpenClaw self-hosted, arahkan URL proxy OpenAI ke https://llm.example.com/v1 (atau http://litellm.zenavo.internal:4000/v1 bila berada di proyek yang sama).

5. LiteLLM vs New API vs Magpie: pilih gateway yang mana?

Katalog Zenavo menyediakan tiga gateway LLM open source dengan fokus yang berbeda:

Template gateway	Fokus utama	Penyimpanan	Paling cocok untuk
LiteLLM	Proxy OpenAI untuk rekayasa perangkat lunak & SDK dengan kunci virtual, anggaran, guardrails, dan integrasi observabilitas (Langfuse, OpenTelemetry)	PostgreSQL 16	Backend aplikasi AI produksi serta tim engineering yang mengelola anggaran dan log biaya per layanan
New API	Pusat distribusi dan pencatatan kuota multi-pengguna dengan akun pengguna, kuota token, dan penyeimbang beban channel	SQLite (/data) secara bawaan	Membagikan akun atau token per anggota tim untuk dipakai bersama di Open WebUI, LobeHub, Claude Code, dan Codex
Magpie	Gateway multi-protokol satu kontainer yang ringan untuk menerjemahkan antara Anthropic Messages, OpenAI Responses/Chat, dan Gemini, lengkap dengan failover antarkunci dan langganan	Volume /config	Developer individu dan tim kecil pengguna Claude Code & Codex CLI yang membutuhkan routing lintas protokol serta halaman cek kuota mandiri /me

6. Backup dan upgrade

LiteLLM menyimpan seluruh konfigurasi model, kunci virtual, dan catatan pengeluaran di layanan postgresql:

1. Buka tab Backup & Restore pada layanan postgresql untuk membuat dan mengunduh backup database, atau aktifkan jadwal backup otomatis. Lihat Backup & Pemulihan.
2. Selalu simpan salinan LITELLM_SALT_KEY bersama backup database Anda — tanpa LITELLM_SALT_KEY asli, database yang dipulihkan tidak dapat mendekripsi kunci penyedia di dalamnya.
3. Sebelum melakukan upgrade, cadangkan PostgreSQL terlebih dahulu, lalu perbarui tag image (bawaan v1.109.1) di Settings → Source pada layanan litellm.

Pertanyaan umum

Mengapa /ui menampilkan 502 sesaat setelah deploy selesai? Saat mulai berjalan, LiteLLM menunggu PostgreSQL siap lalu menjalankan migrasi database Prisma; template ini menyertakan waktu tenggang health check selama 40 detik (start_period: 40). Tunggu hingga status layanan berubah menjadi Running, atau buka Zenavo Agent bawaan di sisi kanan konsol untuk memeriksa log startup.

Saat menambahkan model di /ui, muncul pesan tidak dapat menyimpan ke database. Pastikan variabel lingkungan STORE_MODEL_IN_DB="True" tetap aktif di layanan litellm dan layanan postgresql berstatus Running.

Klien mendapatkan error BudgetExceededError. Kunci virtual tersebut telah mencapai batas Max Budget yang Anda tetapkan. Buka Virtual Keys di /ui untuk menaikkan anggaran, mereset pemakaian, atau mengatur siklus reset bulanan otomatis.

Bisakah LiteLLM dipakai bersama New API? Bisa. Beberapa tim mengelola kumpulan channel penyedia upstream di New API, lalu menempatkan LiteLLM di depan backend aplikasi untuk pembagian anggaran per microservice serta pelacakan Langfuse, dengan menghubungkan keduanya lewat .zenavo.internal.

Deploy template LiteLLM untuk menyatukan penyedia model Anda di balik proxy berbasis PostgreSQL lengkap dengan kontrol anggaran per kunci dalam hitungan menit.