vLLM Docker: Arsitektur, Performa, dan Panduan Deployment Cloud

vLLM Docker: Arsitektur, Performa, dan Panduan Deployment Cloud

Docker adalah cara paling langsung untuk menempatkan vLLM di balik endpoint yang kompatibel dengan OpenAI pada GPU yang Anda kendalikan. Namun, deployment vLLM Docker yang baik bukan sekadar perintah docker run: deployment ini memerlukan runtime GPU yang kompatibel, rencana memori dan konkurensi yang dibatasi, autentikasi di edge, serta cara yang dapat diulang untuk menguji performa sebelum trafik masuk.

Panduan ini membahas arsitektur, deployment awal yang aman, pengaturan yang benar-benar mengubah kapasitas, serta jalur dari satu GPU ke armada GPU cloud.

Gunakan vLLM Docker ketika Anda membutuhkan kontrol atas bobot model, lokasi deployment, pengaturan runtime, atau workload yang di-host sendiri secara stabil. Jika biaya operasional melebihi nilai kontrol tersebut, API model terkelola atau gateway terpadu sering kali menjadi batas yang lebih baik.

Apa yang diberikan vLLM Docker

vLLM menerbitkan image Docker resmi vllm/vllm-openai yang menjalankan server kompatibel OpenAI. Hal ini menjadikan vLLM Docker jembatan yang berguna antara repositori model dan aplikasi yang sudah menggunakan format klien OpenAI: daftar model, chat completions, completions, embeddings, serta endpoint kompatibel terkait bergantung pada model dan versi server yang Anda deploy. Dokumentasi Docker vLLM menyediakan contoh image dan runtime terkini.

Implikasi praktisnya sederhana: aplikasi Anda seharusnya tidak memerlukan klien server model khusus hanya karena Anda memindahkan workload ke GPU sendiri. Aplikasi tetap memerlukan nama model yang eksplisit, kunci API, timeout, dan perilaku retry yang sesuai dengan target ketersediaan Anda.

Cara kerja arsitektur vLLM Docker

Pada tingkat tinggi, vLLM Docker memiliki lima lapisan:

1. Klien Anda mengirimkan permintaan terautentikasi ke endpoint yang kompatibel dengan OpenAI.
2. Server API memvalidasi dan melakukan tokenisasi permintaan, lalu meneruskannya ke engine vLLM.
3. Scheduler mengelompokkan pekerjaan yang kompatibel dan mendistribusikannya ke satu atau beberapa worker GPU.
4. Worker GPU menyimpan bobot model dan cache key-value (KV) sambil menghasilkan token.
5. Respons dialirkan kembali melalui server API ke klien.

Gagasan utama di balik performa adalah PagedAttention. Alih-alih mencadangkan satu wilayah cache KV besar yang kontigu untuk panjang maksimum yang mungkin dari sebuah permintaan, vLLM mengelola status KV dalam blok-blok. Hal ini membuat workload dengan panjang bervariasi lebih mudah ditempatkan ke dalam memori yang tersedia dan memungkinkan permintaan yang selesai melepaskan blok untuk pekerjaan berikutnya. Makalah PagedAttention asli menjelaskan scheduler, worker GPU, blok KV logis-ke-fisik, serta pertukaran antara utilisasi cache dan batching.

Arsitektur tersebut memiliki konsekuensi operasional penting: VRAM bukan hanya “ukuran model”. VRAM dibagi antara bobot model, overhead runtime, aktivasi, dan cache KV yang kebutuhannya bertambah seiring panjang konteks dan permintaan konkuren. Perlakukan konteks, konkurensi, dan utilisasi memori sebagai satu keputusan—bukan tiga tugas tuning terpisah.

Sebelum menjalankan vLLM Docker pada GPU cloud

Mulailah dengan empat pemeriksaan:

1. Pilih tag image yang telah diuji. Sematkan tag rilis vLLM di produksi alih-alih terus mengikuti latest secara buta. Baca dokumentasi yang sesuai dengan tag tersebut sebelum mengandalkan sebuah flag atau nilai default.
2. Gunakan model yang diizinkan untuk Anda unduh dan layani. Beberapa repositori memerlukan token Hugging Face atau persetujuan lisensi model. Sematkan revisi model setelah Anda memvalidasinya.
3. Verifikasi akses GPU di luar container model. Instal driver NVIDIA pada host dan NVIDIA Container Toolkit, lalu validasi container yang mendukung GPU dengan nvidia-smi. Panduan instalasi NVIDIA mencakup prasyarat sisi host dan konfigurasi runtime.
4. Jaga port tetap privat pada awalnya. Bind ke loopback untuk proof of concept pada satu host, atau tempatkan layanan di subnet privat di belakang TLS, autentikasi, serta reverse proxy/load balancer. Jangan menganggap server model tanpa pelindung sebagai batas keamanan yang menghadap internet.

Gunakan perintah contoh NVIDIA sebelum men-debug vLLM itu sendiri:

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Jika perintah tersebut tidak dapat melihat GPU yang diharapkan, berhenti di sana. Log server model tidak akan memperbaiki driver yang tidak ada, runtime container yang belum dikonfigurasi, atau GPU yang tidak pernah ditetapkan ke VM cloud.

Jalankan server vLLM Docker dengan satu GPU

Berikut ini adalah titik awal yang sengaja dibuat sederhana. Ini mengikuti pola image resmi, tetapi menambahkan kunci API dan mengikat port yang dipublikasikan ke loopback. Ganti placeholder dengan model dan tag image yang telah Anda uji.

export HF_TOKEN="your_hugging_face_token"
export VLLM_API_KEY="replace-with-a-long-random-secret"
export VLLM_IMAGE="vllm/vllm-openai:<tested-version>"
export MODEL="Qwen/Qwen3-0.6B"

docker run -d \
  --name vllm-api \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --dtype auto \
  --api-key "$VLLM_API_KEY"

Pengaturan memori bersama dan mount cache Hugging Face mengikuti contoh resmi vLLM Docker. Mount cache mencegah pengunduhan ulang bobot model yang sama saat container dibuat ulang. Kunci API adalah kontrol aplikasi, bukan pengganti untuk isolasi jaringan, TLS, batas laju, atau secret manager.

Pastikan server menyajikan model yang diharapkan sebelum menghubungkan aplikasi:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

Kemudian kirim satu permintaan kecil dengan identifier model yang sama seperti yang dikembalikan oleh /v1/models:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 16
  }'

Jika model Anda tidak menyertakan chat template yang dapat digunakan, permintaan chat-completion dapat gagal meskipun container telah berjalan. vLLM mendokumentasikan cara menyediakan --chat-template untuk model yang konfigurasi tokenizernya tidak memilikinya; uji ini sebelum penerapan aplikasi. Lihat panduan chat-template.

Tetapkan batas performa sebelum mengubah flag

Tidak ada perintah vLLM Docker yang benar secara universal. Konfigurasi yang tepat bergantung pada arsitektur model, jenis dan memori GPU, distribusi panjang input/output, konkurensi, dan sasaran latensi. Buat baseline dengan beban kerja yang representatif, lalu ubah satu variabel setiap kali.

Catat setidaknya pengukuran berikut:

• Tingkat keberhasilan/kesalahan permintaan serta peristiwa restart/OOM.
• Waktu hingga token pertama (TTFT) dan waktu per token output (TPOT), yang dikelompokkan berdasarkan panjang prompt.
• Latensi end-to-end pada p50 dan p95/p99 di bawah konkurensi yang diharapkan.
• Token input, token output, waktu antrean, permintaan aktif, dan penggunaan memori GPU.
• Throughput hanya bersama sasaran latensi dan kualitas yang dipenuhinya.

Flag vLLM Docker yang secara signifikan mengubah kapasitas

Default dan perilaku opsi yang tepat bergantung pada versi. Referensi argumen engine vLLM saat ini mendefinisikan kontrol scheduler, cache, paralelisme, dan antrean; referensi konfigurasi cache-nya menjelaskan pengaturan pemanfaatan memori dan prefix-cache.

Urutan tuning yang praktis

1. Tetapkan --max-model-len yang realistis berdasarkan batas aplikasi.
2. Mulailah secara konservatif dengan utilisasi memori dan sisakan ruang untuk overhead driver/runtime.
3. Lakukan load test pada --max-num-seqs dan --max-num-batched-tokens menggunakan panjang prompt dan completion yang nyata.
4. Tambahkan paralelisme tensor hanya ketika satu GPU tidak dapat memuat model atau memenuhi target model tersebut.
5. Tambahkan replika di belakang load balancer ketika kebutuhan ketersediaan atau trafik agregat memerlukan domain kegagalan yang independen.

Urutan ini mencegah kesalahan umum: menambahkan GPU atau meningkatkan konkurensi sebelum Anda mengetahui apakah beban kerja sebenarnya dibatasi oleh konteks, antrean, memori, atau komputasi.

Menskalakan vLLM Docker di beberapa GPU

Untuk satu model yang membutuhkan beberapa GPU, vLLM mendukung penyajian paralel tensor dan pipeline. Pada satu host, ekspos GPU ke container dan tetapkan ukuran paralel tensor ke jumlah GPU yang sengaja Anda alokasikan untuk server model tersebut:

docker run -d \
  --name vllm-tp \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --tensor-parallel-size 4 \
  --api-key "$VLLM_API_KEY"

Panduan paralelisme dan penskalaan vLLM mendokumentasikan paralelisme tensor, paralelisme pipeline, serta pilihan eksekusi single-node versus multi-node. Jangan menyalin 4 dari contoh ke node dua-GPU: sesuaikan flag dengan GPU yang dialokasikan ke server ini dan validasi topologi komunikasi, keseimbangan memori, serta perilaku kegagalan.

Untuk detail implementasi, pemeriksaan topologi, dan keputusan antara paralelisme tensor dan pipeline, lihat panduan inferensi multi-GPU vLLM dari Flatkey. Untuk keputusan runtime penyajian alih-alih keputusan deployment Docker, lihat vLLM vs. SGLang.

Bentuk deployment cloud produksi

Deployment vLLM Docker produksi biasanya memisahkan edge publik dari eksekusi GPU:

Tempatkan cache Hugging Face pada penyimpanan yang tahan lama atau sengaja dipanaskan agar restart biasa tidak berubah menjadi unduhan model yang mengejutkan. Simpan lisensi dan kontrol akses model dalam catatan deployment Anda. Mem-pin tag image saja tidak cukup jika repositori model mengarah ke branch yang berubah-ubah.

Untuk latar belakang tentang pemilihan GPU, perencanaan memori berbasis konteks, dan kapan infrastruktur cloud merupakan pilihan yang tepat, tautkan runbook ini ke panduan kebutuhan memori GPU LLM, panduan cloud GPU, dan cloud GPU vs. framework API model dari Flatkey.

Memecahkan masalah vLLM Docker tanpa menebak

Ketika server berjalan tetapi perilaku aplikasi masih berbeda dari API yang di-host, konfirmasikan kompatibilitas endpoint dan parameter secara eksplisit. Panduan server inferensi yang kompatibel dengan OpenAI dari Flatkey membahas migrasi sisi klien dan cakupan pengujian kompatibilitas.

Kapan sebaiknya tidak mengoperasikan vLLM Docker sendiri

Self-hosting adalah komitmen infrastruktur. Anda bertanggung jawab atas pembaruan image, asal-usul model, kapasitas GPU, kegagalan node, kontrol akses, validasi latensi, dan jalur on-call. Ini dapat menjadi pilihan yang tepat ketika kontrol runtime merupakan kebutuhan.

Untuk workload yang mengutamakan pilihan model, ketersediaan penyedia, atau kesederhanaan operasional dibandingkan kontrol GPU langsung, pertahankan jalur API terkelola dalam arsitektur. Flatkey dirancang untuk alur kerja yang saling melengkapi: satu integrasi yang kompatibel dengan OpenAI untuk mengakses model dari berbagai penyedia dengan penagihan terpusat, sementara endpoint vLLM yang di-host sendiri tetap menjadi opsi untuk workload yang benar-benar membutuhkannya.

Langkah berikutnya yang tepat bukanlah memaksimalkan benchmark secara terpisah. Sebelum menempatkan vLLM Docker di balik traffic produksi, tetapkan versi image dan model, buktikan runtime GPU, tetapkan kebijakan konteks dan antrean yang eksplisit, uji dengan permintaan yang menyerupai produksi, dan dokumentasikan jalur kegagalan.

Pertanyaan yang sering diajukan

Apakah vLLM Docker sama dengan API LLM terkelola?

Tidak. vLLM Docker memberi Anda runtime penyajian model pada GPU yang Anda operasikan. API terkelola mengabstraksikan hosting model dan operasi GPU. Keduanya dapat mengekspos antarmuka klien yang kompatibel dengan OpenAI, tetapi tanggung jawab operasionalnya berbeda.

Apakah vLLM Docker memerlukan NVIDIA Container Toolkit?

Untuk container GPU NVIDIA, host memerlukan driver NVIDIA yang kompatibel dan runtime container GPU yang dikonfigurasi. NVIDIA Container Toolkit adalah jalur standar yang didokumentasikan oleh NVIDIA untuk menyediakan GPU bagi container Docker.

Flag vLLM Docker mana yang harus saya sesuaikan terlebih dahulu?

Tetapkan panjang konteks maksimum yang realistis terlebih dahulu, lalu uji utilisasi memori, konkurensi, dan batas token batch dengan campuran permintaan yang representatif. Mengubah flag tanpa baseline workload sebagian besar hanya menghasilkan hasil yang tidak dapat diulang.

Bisakah vLLM Docker menjalankan model di beberapa GPU?

Ya. vLLM mendukung penyajian tensor parallel dan pipeline parallel. Mulailah dengan satu host dan validasikan jumlah GPU, topologi, serta perilaku komunikasi yang tepat sebelum memperluas desain.

Sumber dan bacaan lanjutan

• vLLM: Menggunakan Docker
• vLLM: Paralelisme dan Penskalaan
• vLLM: Argumen Engine
• Panduan instalasi NVIDIA Container Toolkit
• Efficient Memory Management for Large Language Model Serving with PagedAttention