Self-Host LLM dengan vLLM: Server OpenAI-Compatible Production-Grade

Kamu nggak butuh OpenAI buat jalanin LLM serius. Kamu juga nggak harus bayar per token. Dengan satu box GPU dan vLLM, kamu bisa host Llama, Qwen, Mistral, atau 200+ model open-source lain di belakang API yang speak protokol OpenAI. Tempel di tool apa pun yang udah panggil /v1/chat/completions, langsung jalan.

Angka dari benchmark awal tim vLLM bukan kaleng-kaleng. Di LLaMA-7B di A10G dan LLaMA-13B di A100 40GB, sampling dari distribusi ShareGPT, vLLM capai 14 sampai 24 kali throughput lebih tinggi dari HuggingFace Transformers dan 2.2 sampai 3.5 kali dari HuggingFace Text Generation Inference (TGI). Di LMSYS, pindahin Chatbot Arena ke vLLM motong penggunaan GPU jadi setengahnya sambil handle 30 ribu request per hari di peak.

Kuncinya PagedAttention. KV cache buat satu sequence LLaMA-13B sampai 1.7GB. Sistem yang ada buang 60 sampai 80% memori itu karena fragmentasi dan over-reservation karena mereka anggap KV cache kayak satu tensor besar yang contiguous. vLLM partisi jadi blok ukuran tetap, sama kayak OS partisi memori jadi page, dan waste turun ke bawah 4%. Lebih banyak memori berarti lebih banyak request concurrent dalam satu batch, yang berarti throughput per dollar lebih tinggi.

Guide ini ngebawa kamu dari nol ke server production yang bisa dipanggil pake SDK openai Python atau curl.

Prerequisites

• Linux (Ubuntu 22.04+ atau setara)
• Python 3.10 sampai 3.13
• NVIDIA GPU minimal 24GB VRAM buat model 7B di FP16 (atau 16GB buat INT4/INT8)
• Driver CUDA 12.x
• Minimal 50GB disk kosong buat bobot model
• uv terinstall (pip install uv) — direkomendasiin tapi opsional

Halaman vllm di PyPI daftar versi CUDA yang didukung per release. Pastikan driver kamu match sama wheel-nya.

Step 1: Install vLLM

Path paling cepet pake uv, yang otomatis milih index PyTorch yang sesuai sama versi CUDA kamu:

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

Kalau prefer pip biasa:

python -m venv .venv
source .venv/bin/activate
pip install vllm

Smoke test:

python -c "import vllm; print(vllm.__version__)"

Import pertama trigger beberapa kompilasi kernel kecil. Import berikutnya udah cepet.

Step 2: Start Server OpenAI-Compatible

Satu perintah nge-start server di port 8000 dengan endpoint OpenAI-compatible /v1/chat/completions:

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --port 8000 \
  --host 0.0.0.0 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.90

Di run pertama, vLLM download model dari HuggingFace (default ~16GB buat 8B di FP16) dan compile beberapa CUDA graph. Itu makan 1 sampai 5 menit. Setelah itu, startup di bawah 30 detik.

Kamu juga bisa pake entrypoint lama kalau script kamu pin ke sana:

python -m vllm.entrypoints.openai.api_server --model meta-llama/Llama-3.1-8B-Instruct

Dua-duanya didokumentasiin di referensi vllm serve.

Step 3: Panggil Kayak OpenAI

Intinya, kode existing kamu nggak perlu berubah. SDK openai kerja ke vLLM cuma dengan ganti base URL:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed",  # vLLM nggak butuh auth secara default
)

resp = client.chat.completions.create(
    model="meta-llama/Llama-3.1-8B-Instruct",
    messages=[{"role": "user", "content": "Jelasin PagedAttention dalam 3 kalimat."}],
    temperature=0.7,
    max_tokens=200,
)
print(resp.choices[0].message.content)

Atau pake curl:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "messages": [{"role": "user", "content": "Halo"}],
    "max_tokens": 50
  }'

Streaming jalan sama. Set stream=True di SDK atau kirim "stream": true di body curl. Server kirim Server-Sent Events di path /v1/chat/completions yang sama kayak OpenAI.

Step 4: Tune Buat Workload Kamu

Default-nya udah masuk akal. Beberapa flag nutup 90% tuning production:

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --port 8000 \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.92 \
  --max-num-seqs 256 \
  --max-num-batched-tokens 16384 \
  --enable-prefix-caching \
  --enable-chunked-prefill

Fungsi masing-masing:

• --max-model-len 8192 — batas context window. Nilai lebih kecil ninggalin lebih banyak memori buat KV cache. Pilih window terkecil yang emang dibutuhin app kamu.
• --gpu-memory-utilization 0.92 — fraksi VRAM yang boleh dipake vLLM. Default 0.9. Naikin ke 0.95 kalau vLLM jalan sendiri di box.
• --max-num-seqs 256 — max request concurrent. Turunin kalau context panjang atau GPU kecil; naikin kalau request pendek.
• --max-num-batched-tokens 16384 — total token per batched step. Dokumentasi optimization rekomendasiin 8192+ buat model kecil di GPU gede. Lebih tinggi naikin throughput tapi nambahin TTFT.
• --enable-prefix-caching — reuse KV cache antar request yang share prefix. Hemat gede buat app chat yang tiap message mulai dari system prompt. Default on di V1.
• --enable-chunked-prefill — pecah prefill panjang jadi chunk kecil dan selang-seling sama decode step. Ngurangin variansi TTFT. Default on di V1.

Optimization Level

vLLM punya 4 level compile: -O0 sampai -O3. -O2 default dan yang kamu mau buat production. -O0 skip graph capture buat startup paling cepet (cocok buat CI). -O3 enable semua optimasi termasuk yang eksperimental dan saat ini sama kayak -O2. Set pake VLLM_COMPILE_CONFIG=... atau --compilation-config.

Perhatiin Preemption

Kalau kamu liat warning kayak Sequence group 0 is preempted by PreemptionMode.RECOMPUTE mode, scheduler-nya kehabisan KV cache di tengah batch dan ngitung ulang beberapa sequence. Itu behavior yang bener, bukan bug, tapi ngaruh ke latency. Fix-nya salah satu dari: naikin --gpu-memory-utilization, turunin --max-num-seqs, turunin --max-num-batched-tokens, atau shard model-nya pake --tensor-parallel-size 2 ke dua GPU.

Halaman optimization bahas setiap flag secara detail.

Step 5: Tambah API Key (Production)

vLLM nggak enforce auth secara default. Buat apa pun yang reachable dari jaringan, set key dan validasi di edge:

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --port 8000 \
  --api-key "$MY_SECRET_KEY" \
  --allow-credentials

Kirim key yang sama sebagai parameter api_key SDK OpenAI. Buat production beneran, terminate TLS di reverse proxy (Caddy, nginx, Traefik) dan taruh key-nya di check Authorization: Bearer ... di sana. vLLM tetep di jaringan private.

Step 6: Jalan di Belakang Reverse Proxy

Caddyfile yang terminate TLS dan forward ke vLLM:

llm.example.com {
  reverse_proxy localhost:8000 {
    header_up X-Real-IP {remote_host}
  }
}

Restart Caddy. Sekarang https://llm.example.com/v1/chat/completions jalan dan SDK kamu cuma butuh base_url yang beda.

Jalanin Banyak Model

vllm serve load satu model per proses. Kalau kamu mau serve beberapa model dari box GPU yang sama, jalanin satu proses vLLM per model di port berbeda, atau pake router di depan. llm-router sama LiteLLM dua-duanya jalan. Buat setup high-traffic, jalanin tiap model di GPU sendiri dengan satu instance vLLM per GPU.

Kalau model nggak muat di satu GPU, vLLM support tensor parallelism:

vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --tensor-parallel-size 4

Ini nge-shard model ke 4 GPU. vLLM juga support pipeline parallelism (--pipeline-parallel-size) dan campuran keduanya. Bagian parallelism strategies di dokumentasi optimization punya matriks lengkapnya.

Kapan Pake vLLM vs Alternatif

Pilih vLLM kalau:

• Kamu mau throughput maksimum per GPU di hardware NVIDIA
• Kamu butuh drop-in OpenAI-compatible buat kode client yang udah ada
• Kamu nyervin model dense atau MoE kelas 7B-70B

Pilih yang lain kalau:

• Ollama atau LM Studio kalau kamu cuma mau chat sama model lokal di laptop. Mereka ngebungkus llama.cpp dengan UX yang lebih ramah tapi mentok jauh di bawah throughput vLLM.
• llama.cpp kalau kamu butuh CPU-only atau Apple Silicon inference plus fleksibilitas quantization maksimum. vLLM punya dukungan Apple Silicon lewat vllm-metal tapi masih tahap pematangan.
• TensorRT-LLM kalau kamu all-in di NVIDIA dan butuh latency paling rendah. vLLM deket di belakang dan jauh lebih gampang di-deploy.
• TGI kalau kamu prefer server resmi HuggingFace. vLLM opsi yang lebih cepet dan lebih populer sekarang.
• Hosted API (OpenAI, Anthropic) kalau kamu nggak punya kapasitas GPU atau belum yakin workload-nya nyata. Mereka tagih per token dan ngilangin overhead ops.

Jebakan yang Sering Kejadian

Out of memory saat startup. Turunin --max-model-len dulu. Context 4096 pake KV cache jauh lebih sedikit dari 32768. Kalau masih kurang, turunin --gpu-memory-utilization ke 0.85 dan cek nggak ada proses lain yang pake GPU (nvidia-smi).

Request pertama lambat. Panggilan pertama setelah startup kena CUDA graph yang baru di-JIT-compile. Setiap request setelahnya cepet. Warm up dengan satu panggilan dummy sebelum ngukur latency di benchmark.

Download model nge-block startup. vLLM narik dari HuggingFace secara default. Di environment air-gapped, pre-download pake huggingface-cli download dan arahin --model ke path lokal.

Long-tail latency dari preemption. Lihat bagian "Perhatiin Preemption" di atas. Default gpu_memory_utilization=0.9 itu konservatif. Naikin cuma setelah kamu ukur.

Bingung antara OpenAI client vs raw API. /v1/chat/completions vLLM match schema OpenAI, tapi /v1/responses (endpoint Assistants-style yang baru) belum didukung. Pake /v1/chat/completions atau /v1/completions.

Mau Lanjut ke Mana

• Referensi CLI vllm serve — penjelasan tiap flag
• Optimization and tuning — parallelism, batching, compilation level
• Blog vLLM: PagedAttention — hasil paper SOSP 2023 original dan trik memory-sharing yang muncul dari situ
• Speculative decoding di vLLM — EAGLE dan setup draft-model lain yang naikin 2-3x token/detik tanpa ngorbanin kualitas