Release Notes vLLM 0.31: Preload, Model Runner V2, dan Flag yang Rusak Saat Upgrade

Saya membaca halaman release vLLM v0.29.0, v0.30.0 dan v0.31.0 untuk mencari satu jawaban: apa yang berubah bagi orang yang me-restart server vLLM di production. Jawabannya tersebar di tiga release dalam empat minggu. Daemon muncul di 0.30, menjadi command resmi di 0.31, dan runner di bawahnya berganti default di 0.29. Kalau hanya membaca halaman terbaru, dua pertiga ceritanya terlewat.

Sumber saya adalah tiga halaman release GitHub, docs preload dan CLI v0.31.0, docs initialized snapshots, satu checklist upgrade dari pihak ketiga, dan tulisan LMSYS tentang ide yang sama di SGLang. Saya tidak menjalankan apa pun di GPU, jadi tidak ada angka di bawah ini yang hasil ukur saya. Setiap flag, default dan batasan dikutip dari halaman yang saya baca, dan bila sumbernya sekunder atau docs-nya tidak terkunci ke 0.31, saya sebutkan.

Tiga release dalam empat minggu, dan cerita restart menyebar di semuanya

Mulai dari timeline, karena breaking change menumpuk sepanjang itu. Catatan 0.30 menjelaskan weight-cache daemon per GPU yang melayani restart lewat --load-format ipc_cache. Catatan 0.31 menaikkannya menjadi CLI vllm preload dan menambah data parallelism, model draft MTP, endpoint /health dan readiness wait. Kalau Anda upgrade dari sebelum 0.29, Anda mewarisi semua penghapusan di tabel di bawah, bukan hanya daftar di halaman terbaru.

Halaman release menghitung sendiri commit dan contributor, dan saya menyalin angkanya apa adanya. Ini pengingat bahwa ritmenya bukan patch kecil: tiap release berisi ratusan commit, dan tiap release menghapus atau mengganti nama sesuatu yang mungkin ada di systemd unit Anda. Satu batasan jujur: halaman v0.29 tidak mencetak tahun, jadi tahunnya saya simpulkan dari tanggal release di sekitarnya.

Model Runner V2 sudah default, dan V1 kini punya tanggal penghapusan

Catatan 0.29 menyatakan Model Runner V2 kini default untuk semua model. Catatan itu juga menyebut Model Runner V1 deprecated, dengan penghapusan ditargetkan di v0.32, dan proyek tidak akan menerima optimisasi khusus V1 lagi. Saat itu V2 masih belum punya sequence parallelism, dual-batch overlap, elastic expert parallelism, custom logits processor dan beberapa metode speculative decoding, dan vLLM kembali ke V1 bila Anda mengonfigurasi salah satunya.

Celahnya menutup sesuai jadwal. Highlight 0.31 mencantumkan draft-model speculative decoding dan custom logits processor yang kini jalan di Model Runner V2, dan 0.31 juga menolak Model Runner V1 dengan pipeline parallelism di atas 1, async scheduling dan structured output saat startup. Di 0.30, cache mode all untuk Mamba di-deprecate dan jatuh kembali ke V1. Artinya: config yang diam-diam jalan di V1 pada 0.29 kini punya tenggat, dan satu kombinasi tertentu langsung gagal alih-alih tersendat.

Jangan campur dengan biaya startup. Catatan 0.30 menyebut gc freezing di Model Runner V2 memangkas init engine dari 28,9 s menjadi 8,2 s di H200, angka milik proyek untuk setup mereka sendiri. Itu inisialisasi, bukan weight loading, dan merupakan bagian restart yang berbeda dari yang disasar preload. Saya tidak menemukan flag di catatan itu yang melaporkan runner mana yang terpilih, jadi periksa log startup Anda, jangan berasumsi.

Cara kerja weight-cache daemon, dan apa yang dijaganya tetap hidup

vllm preload menjalankan satu daemon per GPU. Setiap daemon memuat shard-nya, menjalankan post-processing quantization, lalu mengekspor tiap parameter dan buffer sebagai CUDA IPC handle lewat Unix domain socket. Engine yang dijalankan dengan --load-format ipc_cache membangun model di meta device, meminta tensor ke daemon di GPU-nya dan memetakannya tanpa copy, sehingga engine yang di-restart tidak pernah membaca checkpoint dari disk. Hanya jalan di CUDA dan ROCm.

# Step 1: one daemon per GPU. It loads each shard from disk ONCE, runs the
# quantization post-processing, and exports every tensor as a CUDA IPC handle.
# The command reports ready only when every rank is serving; if a rank dies at
# startup the others are terminated and the exit code is that rank's.
vllm preload --model meta-llama/Llama-3.1-8B-Instruct --tensor-parallel-size 4

# Step 2: engines map the daemon's tensors instead of reading the checkpoint.
# TP size, dtype, quantization, revision and the vLLM version must match the
# daemon's, or the engine quietly loads from disk (fallback defaults to true).
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --tensor-parallel-size 4 \
  --load-format ipc_cache

# Stop the daemon with SIGINT or SIGTERM: it removes its sockets and frees GPU
# memory. In the default zero_copy mode the engines must be gone first.

Sebelum melayani, engine dan daemon membandingkan fingerprint yang mencakup isi checkpoint (di-hash dari metadata safetensors), arsitektur, ukuran dan rank TP serta DP, dtype, quantization, model revision dan versi vLLM. Engine juga memeriksa bahwa GPU UUID milik daemon sama dengan device-nya, sehingga socket usang tidak bisa menyerahkan GPU yang salah. Bila daemon tidak ada atau salah satu fingerprint berbeda, engine memuat dari disk, dan itu perilaku default.

Idenya bukan baru di vLLM. LMSYS menerbitkan desain yang sama untuk SGLang pada Agustus 2026: satu daemon per GPU yang mengekspor CUDA IPC handle. Pada Ling-2.6-1T FP8 di delapan GPU H20-3e mereka melaporkan weight loading turun dari sekitar 495 s menjadi sekitar 0,63 s, dan menyebut loading dari disk memakan 93,2 persen waktu startup. Tulisan mereka sendiri tidak konsisten soal angka disk dan menyebut nilai lain di bagian lain, jadi baca sebagai orde besaran. Itu engine dan model yang berbeda, bukan hasil ukur vLLM, dan tulisan itu mencatat start pertama daemon tetap membaca dari disk.

Config loader: dua mode, satu fallback, dan timeout-nya

Loader diatur lewat --model-loader-extra-config di engine. Mode menentukan siapa yang memegang weight: di zero_copy engine memetakan alokasi milik daemon dan daemon harus hidup lebih lama darinya, dengan satu salinan per GPU; di copy engine mengkloning tiap tensor ke memorinya sendiri dan daemon melepas cache-nya, yang membebaskan memori GPU tetapi memakan satu salinan penuh tiap restart. Di zero_copy, sleep mode weight offloading tidak boleh dipakai bersama loader ini.

Scale-out mengikuti node. IPC handle bersifat lokal per node, jadi tensor parallelism multi-node butuh satu launcher per node, masing-masing hanya melayani GPU lokalnya, dengan --weight-cache-master-port dipatok dan berbeda dari --master-port milik engine. Dengan data parallelism, GPU lokal i melayani DP rank start_rank ditambah hasil bagi bulat i dengan tp_size, dan TP rank i modulo tp_size. Untuk MTP, EAGLE dan EAGLE3, grup draft daemon terpisah menyimpan model draft dengan nama socket dan rendezvous port sendiri.

# Strict engine config for rollout tests: fail instead of falling back to disk.
# connect_timeout_s and state_timeout_s are shown at their documented defaults.
vllm serve meta-llama/Llama-3.1-8B-Instruct --tensor-parallel-size 4 \
  --load-format ipc_cache \
  --model-loader-extra-config '{"mode": "zero_copy", "fallback": false, "connect_timeout_s": 5.0, "state_timeout_s": 300.0}'

# Multi-node TP: one launcher per node, each serving only its local GPUs.
# The daemon's rendezvous port must differ from the engine's --master-port
# and match across nodes.
vllm preload --model /path/to/model --tensor-parallel-size 16 \
  --nnodes 2 --node-rank 0 --master-addr 10.0.0.1 \
  --weight-cache-master-port 29600
# node 1: the same command with --node-rank 1

Preload, snapshot, sleep mode: alat restart mana yang cocok

0.31 memberi dua cara baru menghindari cold start, dan keduanya tidak bisa saling menggantikan. vllm snapshot create dan vllm snapshot restore memakai CRIU untuk memulihkan engine TP1 yang sudah terinisialisasi penuh, sehingga menyasar inisialisasi engine, walau docs menyebut restore tetap memuat ulang file model dan KV cache sebelum mengikat HTTP. Harganya kotak yang jauh lebih sempit: Linux x86-64, satu GPU NVIDIA, root atau sudo tanpa password, io_uring dinonaktifkan, model revision 40 karakter yang dipatok, dan server HTTP plaintext tanpa autentikasi. Saya membaca halaman snapshot di URL latest, karena URL versi 0.31.0 mengembalikan 404, jadi anggap batasannya docs terkini, bukan terkunci ke 0.31.

Aturan praktis saya dari tabel, dan ini penilaian, bukan rekomendasi resmi docs: coba preload dulu, karena syaratnya lingkungan yang sudah dipenuhi kebanyakan host GPU dan ia mencakup tensor, expert dan data parallelism. Snapshot cocok untuk layanan satu GPU satu model di mana waktu init mendominasi dan Anda bisa menerima root, container privileged, dan listener plaintext di dalam batas yang tepercaya. Restore gagal alih-alih kembali ke start normal, jadi ia butuh jalur recovery sendiri.

Breaking change, dalam urutan yang akan menabrak deploy Anda

Kebanyakan gagal dengan suara keras, yang merupakan kasus baik. Yang perlu dibaca dua kali adalah gerbang multimodal kwargs, perubahan keamanan yang tampil sebagai flag, serta baris GPTQ dan YaRN yang mengubah perilaku alih-alih menolak start.

Script di bawah meng-grep repository deploy untuk string-string itu, ditambah tiga env var yang dihapus catatan release (VLLM_PREFIX_CACHE_RETENTION_INTERVAL, VLLM_MM_HASHER_ALGORITHM dan VLLM_PLE_CPU_OFFLOAD). Dua knob baru perlu diketahui sekalian: --max-num-active-seqs membatasi admisi RUNNING terpisah dari max_num_seqs (0.31), dan --max-num-queued-reqs serta --max-num-queued-tokens menambah admission control pada waiting queue (0.29).

# Run from the repo that holds your launch scripts, unit files and compose files.
# Each pattern is something the 0.29 to 0.31 notes removed, renamed or gated.
# A hit is a place to read, not proof of a bug: the quantization pattern also
# matches a deliberately spelled fp8 that now redirects to fp8_per_tensor.
grep -rnE \
  -e 'tokenizer[_-]mode[= ]+"?slow' \
  -e 'quantization[= ]+"?fp8"?( |$)' \
  -e 'enable-mamba-fine-grained-prefix-cache' \
  -e 'collect-detailed-traces[= ][^ ]*,' \
  -e 'VLLM_ENABLE_SCALE_OUT_ENDPOINTS' \
  -e 'VLLM_PREFIX_CACHE_RETENTION_INTERVAL' \
  -e 'VLLM_MM_HASHER_ALGORITHM' \
  -e 'VLLM_PLE_CPU_OFFLOAD' \
  -e 'vllm\.entrypoints\.openai\.api_server' \
  -e 'mm_processor_kwargs|media_io_kwargs' \
  --include='*.sh' --include='*.service' --include='*.yml' \
  --include='*.yaml' --include='*.py' .

Di mana ia bisa salah: start yang berhasil bukan berarti cache hit

Kegagalan yang perlu dinamai adalah fallback senyap. fallback default-nya true, jadi daemon yang hilang, di socket yang salah, atau punya fingerprint untuk versi vLLM berbeda menghasilkan engine yang start, lulus health check dan memuat dari disk dengan kecepatan lama. Checklist upgrade pihak ketiga menyatakannya lugas: start yang berhasil saja tidak membuktikan cache hit. Tidak ada yang saya baca yang menyediakan metrik hit versus fallback, jadi buktinya adalah menjalankan engine sekali dengan fallback false dan melihat ia bisa start.

Trade-off kedua adalah versi termasuk dalam fingerprint. Docs menyatakan daemon dan engine harus memakai versi vLLM yang sama, dan checklist menyebut daemon 0.30 bukan warm cache untuk engine 0.31. Kesimpulan saya, bukan prosedur resmi: upgrade tetap cold start, karena daemon baru harus membaca checkpoint dari disk sekali sebelum restart menjadi cepat. Preload mempercepat restart build yang sama, bukan upgrade.

Batasan lain lebih sederhana. Di mode zero_copy daemon harus hidup selama engine hidup, dan menghentikannya dengan SIGINT atau SIGTERM menghapus socket dan membebaskan memori GPU. Metode quantization yang tidak bisa menyediakan weight pra-proses memunculkan error, pipeline parallelism ditolak saat launch, dan aturan node sama dan user sama berarti batas pod Kubernetes bisa memisahkan daemon dari engine-nya. Versi SGLang dari LMSYS membatasi diri pada unquantized dan FP8 block-wise, jadi cocokkan metode quantization Anda dengan docs vLLM, jangan menganggap sama.

Yang dikerjakan hari Senin

Perlakukan upgrade dan cached restart sebagai dua perubahan terpisah, dan rilis satu per satu. Urutan yang akan saya pakai:

1. Jalankan grep audit di atas pada setiap repository yang meluncurkan vLLM, dan perbaiki tiap temuan di versi lama selama ejaan barunya sudah berfungsi.
2. Upgrade tanpa preload dan periksa log startup untuk runner yang terpilih; jika config jatuh ke Model Runner V1, jadwalkan pekerjaannya sebelum v0.32.
3. Audit client multimodal untuk mm_processor_kwargs dan media_io_kwargs per request sebelum memutuskan apakah --trust-request-mm-kwargs memang dibutuhkan.
4. Jalankan preload daemon di satu canary host dan nyalakan engine dengan fallback false, agar ketidakcocokan gagal dengan keras.
5. Ukur cold start, restart lewat daemon, dan ketidakcocokan yang disengaja pada model dan GPU Anda sendiri. Catat angkanya sendiri; tidak ada sumber yang saya baca yang memberi angka Anda.
6. Baru setelah itu kembalikan fallback ke true untuk production, dan simpan image container serta launch config sebelumnya untuk rollback.

#!/usr/bin/env bash
# Canary rollout of the weight-cache daemon. Defaults for socket locations on purpose.
set -euo pipefail
MODEL=meta-llama/Llama-3.1-8B-Instruct
TP=4

# Daemon first. /health is off unless a port is given; bind it to loopback.
vllm preload --model "$MODEL" --tensor-parallel-size "$TP" \
  --weight-cache-health-port 8100 --weight-cache-health-host 127.0.0.1 &

# The parent answers once the daemon is up. It does not prove the engine will
# hit the cache, and it runs no inference.
until curl -fs http://127.0.0.1:8100/health > /dev/null; do sleep 2; done

# Wrong: a plain engine start. It succeeds on a cache miss too, so a version
# or dtype mismatch is invisible.
#   vllm serve "$MODEL" --tensor-parallel-size "$TP" --load-format ipc_cache
# Right for the canary: fallback false turns a mismatch into a startup failure.
vllm serve "$MODEL" --tensor-parallel-size "$TP" \
  --load-format ipc_cache \
  --model-loader-extra-config '{"fallback": false}'

Script rollout di atas sengaja memakai default lokasi socket. Docs menurunkan direktori privat per user dan nama socket per GPU, dan menimpanya adalah keputusan terpisah yang hanya perlu Anda ambil bila launcher dan engine memang berjalan di path yang berbeda.

Aturan yang akan saya bawa dari tiga release ini: restart yang lebih cepat adalah fitur sekaligus mode kegagalan baru, karena jalur cepat dan jalur lambat sama-sama berakhir di server yang berjalan. Buat jalur cepat membuktikan dirinya dengan fallback mati, cek flag yang dihapus sebelum kode, dan ukur di hardware Anda sendiri, karena satu-satunya angka vLLM di halaman release adalah milik orang lain.