Dukungan GGUF vLLM tersedia, tetapi penyiapan yang tepat bergantung pada rilis vLLM Anda, checkpoint GGUF, dan tokenizernya. Dokumentasi stabil saat ini mengarahkan pengguna ke vllm-gguf-plugin terpisah; tutorial lama menjelaskan pemuat bawaan. Mulailah dengan mengidentifikasi stack yang terinstal, lalu validasi satu model kecil sebelum memindahkan beban kerja produksi.
Panduan ini berfokus pada cara membuat checkpoint GGUF dimuat dan dilayani dengan benar. Untuk memilih antara GGUF, AWQ, GPTQ, dan FP8, gunakan panduan kuantisasi vLLM kami yang lebih luas.
Arti dukungan GGUF vLLM saat ini
GGUF adalah format file model. Nama file yang berakhiran .gguf tidak membuktikan bahwa runtime mendukung setiap arsitektur, jenis kuantisasi, atau komponen tambahan di dalamnya. Anggap kompatibilitas sebagai gabungan dari runtime + plugin + arsitektur model + kuantisasi + tokenizer + perangkat keras.
Dokumentasi GGUF vLLM saat ini menjelaskan jalur eksperimental dengan keterbatasan performa dan fitur. Dokumentasi tersebut mencantumkan selector Hugging Face repo_id:quant_type serta file lokal, dan merekomendasikan penggunaan tokenizer model asli. Ini berbeda dari instruksi v0.8.4, yang menjelaskan alur kerja file lokal yang lebih lama. Cocokkan dokumentasi dengan versi yang benar-benar Anda jalankan.
| Apa yang Anda temukan | Apa yang perlu diperiksa selanjutnya |
|---|---|
| Instalasi stabil terbaru | Apakah plugin GGUF diinstal dalam lingkungan Python yang sama dengan vLLM |
| Container lama atau rilis yang dipatok | Dokumentasi sesuai versinya; hindari mencampurkan pemuat lama dengan flag saat ini |
| GGUF yang berfungsi di runtime lain | Arsitektur, pemetaan tensor, tokenizer, dan fitur yang diperlukan dalam stack vLLM Anda |
Contoh yang menggunakan --omni |
Apakah Anda menggunakan vLLM-Omni, bukan jalur penyajian teks dalam panduan ini |
Panduan GGUF vLLM-Omni mencakup konfigurasi multimodal terpisah dan adapter khusus model. Contoh difusinya bukan perintah siap pakai untuk server vLLM khusus teks.
1. Catat lingkungan sebelum menginstal apa pun
Gunakan lingkungan pengujian yang bersih pada mesin GPU target Anda. Pertama, konfirmasikan bahwa instalasi dasar vLLM sesuai dengan mesin tersebut menggunakan instruksi instalasi GPU resmi. Instalasi paket Python yang berhasil saja tidak memastikan kompatibilitas driver atau perangkat.
Catat versi paket tanpa mengimpor model:
from importlib.metadata import version, PackageNotFoundError
for package in ("vllm", "vllm-gguf-plugin", "torch", "transformers"):
try:
print(package, version(package))
except PackageNotFoundError:
print(package, "not installed")
Pada host NVIDIA, catat juga nvidia-smi, model GPU, memori yang tersedia, serta tag image container atau lockfile lingkungan. Simpan catatan ini bersama revisi repositori model dan nama kuantisasi. Jika peningkatan di masa mendatang gagal, detail ini memungkinkan Anda membandingkan dua lingkungan yang diketahui alih-alih menebak dependensi mana yang berubah.
2. Instal plugin GGUF di lingkungan penyajian
Dengan lingkungan vLLM yang kompatibel sudah disiapkan, dokumentasi stabil saat ini memberikan perintah instalasi paket berikut:
uv pip install vllm-gguf-plugin
Pastikan uv beroperasi pada lingkungan yang berisi executable vllm. Menginstal plugin ke satu lingkungan virtual dan menjalankan server dari lingkungan lain tidak akan membuat plugin tersedia bagi server tersebut.
Untuk build dari sumber, ikuti instruksi instalasi repositori plugin. Instruksi tersebut memerlukan toolkit CUDA atau ROCm dan melakukan build terhadap instalasi PyTorch yang digunakan oleh vLLM; instalasi editable yang didokumentasikan menonaktifkan isolasi build karena alasan tersebut. Gunakan instruksi repositori untuk revisi yang Anda pilih, alih-alih menambahkan flag compiler yang tidak terkait hingga build berhasil.
Repositori plugin juga mencantumkan keluarga model dan kuantisasi yang telah diuji untuk generasi. Gunakan pengujian tersebut sebagai titik awal untuk canary pertama. Pengujian itu bukan bukti bahwa setiap konversi GGUF dari setiap model dapat berfungsi.
3. Muat checkpoint kecil dengan tokenizer eksplisit
Perintah berikut menggunakan contoh Qwen kecil yang didokumentasikan oleh proyek plugin, menambahkan listener khusus lokal, dan memberikan API nama model yang dapat diprediksi:
vllm serve Qwen/Qwen3-0.6B-GGUF:Q8_0 \
--tokenizer Qwen/Qwen3-0.6B \
--served-model-name gguf-canary \
--host 127.0.0.1 \
--port 8000
Ini adalah uji asap kompatibilitas, bukan benchmark performa. Perintah ini mengunduh aset model dan memerlukan runtime serta perangkat yang didukung. Jangan menafsirkan pilihan checkpoint kecil sebagai model yang direkomendasikan untuk aplikasi Anda.
Untuk file lokal, ganti pemilih model dengan jalur GGUF Anda yang sebenarnya dan pertahankan tokenizer model dasar yang sesuai. Pastikan file tersebut lengkap dan penanganan file terpisah apa pun didukung oleh versi yang Anda instal sebelum menyajikannya. Mengganti nama checkpoint sembarang tidak mengonversi formatnya.
Jika metadata konfigurasi tidak dapat diuraikan, dokumentasi saat ini menawarkan --hf-config-path sebagai masukan konfigurasi eksplisit. Gunakan konfigurasi yang benar-benar milik arsitektur dasar checkpoint tersebut. Konfigurasi yang praktis tetapi tidak terkait dapat mengubah kegagalan pemuatan yang jelas menjadi kesalahan tensor atau output yang lebih sulit didiagnosis.
4. Pisahkan pemeriksaan pemuatan, API, dan output
Setelah server melaporkan bahwa server siap, kueri daftar modelnya dari terminal kedua:
curl --fail --silent --show-error http://127.0.0.1:8000/v1/models
Kemudian kirim completion kecil ke nama yang disajikan secara eksplisit:
curl --fail --silent --show-error \
http://127.0.0.1:8000/v1/completions \
-H 'Content-Type: application/json' \
-d '{"model":"gguf-canary","prompt":"The capital of France is","max_tokens":16,"temperature":0}'
Dokumentasi server yang kompatibel dengan OpenAI menjelaskan endpoint yang didukung dan perilaku permintaan. Completion biasa menjaga pemeriksaan pertama tetap independen dari konfigurasi template chat. Setelah pemeriksaan tersebut lolos, uji template chat aktual Anda, persyaratan output terstruktur, streaming, dan fitur aplikasi lainnya secara terpisah.
Simpan tiga hasil terpisah dalam catatan deployment Anda:
- Muat: bobot dan tokenizer diinisialisasi tanpa kesalahan lapisan yang tidak didukung atau tensor.
- Sajikan: endpoint yang diperlukan mengembalikan respons valid untuk nama model yang disajikan.
- Gunakan: output memenuhi serangkaian kecil kriteria kebenaran khusus aplikasi.
Respons dengan HTTP 200 hanya meloloskan bagian API. Teks kosong, token berulang, pemformatan yang salah, atau jawaban tugas yang gagal masih perlu diselidiki. Pertahankan server awal terikat ke localhost; tambahkan autentikasi dan kontrol jaringan normal Anda sebelum mengeksposnya kepada klien lain.
Pemecahan masalah berdasarkan tahap pertama yang gagal
| Gejala | Periksa terlebih dahulu | Perubahan terkontrol berikutnya |
|---|---|---|
| Plugin atau metode kuantisasi tidak dikenali | Lingkungan Python aktif dan versi paket yang terinstal | Reproduksi di lingkungan yang bersih dan kompatibel |
| Impor gagal dengan kesalahan biner atau simbol | Keselarasan build PyTorch, CUDA/ROCm, dan plugin | Bangun ulang menggunakan prosedur terdokumentasi milik plugin |
| Pemilih model atau kuantisasi tidak dapat ditemukan | Ejaan repositori, kuantisasi yang dipilih, izin, kelengkapan unduhan | Coba checkpoint kecil yang didokumentasikan oleh proyek |
| Nama atau bentuk tensor tidak cocok | Arsitektur model, asal konversi, konfigurasi | Gunakan konversi yang didukung dari model dasar yang sama |
| Pemuatan berhenti di sekitar tokenizer | Identitas dan revisi tokenizer | Berikan tokenizer model dasar yang sesuai secara eksplisit |
| Completion berfungsi tetapi chat gagal | Template chat dan format permintaan aplikasi | Uji permintaan chat minimal sebelum menambahkan fitur tambahan |
| Model dimuat tetapi kehabisan memori saat ada trafik | Panjang konteks, permintaan aktif, memori runtime, cache KV | Kurangi satu dimensi beban kerja dan ulangi pengujian yang sama |
Simpan kesalahan bermakna pertama dan perintah yang tepat. Mengubah model, tokenizer, driver, dan konkurensi secara bersamaan dapat menghilangkan kesalahan sambil menyembunyikan penyebabnya.
Tentukan apakah akan tetap menggunakan GGUF setelah kompatibilitas lolos
File yang lebih kecil berguna ketika penyimpanan bobot atau memori menjadi batasan Anda. Hal itu tidak membuktikan keunggulan latensi. Bandingkan model dasar dan rangkaian tugas yang sama dengan checkpoint alternatif yang didukung sebelum memilih format penyajian.
Gunakan panjang input, panjang output, dan tingkat permintaan bersamaan yang Anda harapkan. Catat keberhasilan tugas, waktu hingga token pertama, latensi ekor, throughput, dan memori puncak. CLI benchmark penyajian resmi dapat menghasilkan trafik terkontrol; opsi dan datasetnya harus disesuaikan dengan versi yang Anda instal. Pengujian stres sintetis dan uji penerimaan aplikasi menjawab pertanyaan yang berbeda, jadi simpan kedua hasil tersebut secara terpisah.
Jika fitur atau output yang diperlukan GGUF gagal, tanyakan terlebih dahulu apakah Anda memerlukan checkpoint persis ini. Ketika format lain memenuhi beban kerja dengan ketidakpastian operasional yang lebih rendah, konversi atau distribusi lain yang didukung mungkin merupakan pilihan yang lebih sederhana. Jadikan perbandingan format kami sebagai panduan keputusan yang lebih luas alih-alih mengulang survei kuantisasi lengkap di sini.
Rencanakan kapasitas GPU cloud berdasarkan beban kerja yang diterima
Setelah model lolos pemeriksaan di atas, tentukan ukuran lingkungan GPU untuk kebutuhan memori dan konkurensi yang telah diuji. Cloud GPU Compute dari Flatkey menawarkan opsi penyewaan GPU NVIDIA. Konfirmasikan konfigurasi, wilayah, kapasitas, detail akses, dan ketentuan sewa yang tersedia untuk pengujian yang dimaksud. Panduan ini tidak menyatakan bahwa contoh tersebut dibenchmark pada sewaan Flatkey atau bahwa kartu tertentu selalu tersedia.
Sertakan ringkasan singkat: revisi model, kuantisasi, versi perangkat lunak, perkiraan kebutuhan disk, batas konteks, konkurensi target, dan ambang penerimaan. Hal itu membuat diskusi infrastruktur menjadi konkret dan mencegah masalah kompatibilitas perangkat lunak disalahartikan sebagai kebutuhan untuk menyewa GPU yang lebih besar.
Pertanyaan yang sering diajukan
Apakah vLLM mendukung setiap model GGUF?
Tidak. Validasi arsitektur, kuantisasi, tokenizer, perangkat keras, dan fitur secara bersama-sama. Dukungan untuk format file bukan berarti dukungan universal untuk setiap model yang disimpan dalam format tersebut.
Mengapa panduan lama menyarankan untuk meneruskan file lokal?
Panduan tersebut mungkin menjelaskan rilis yang lebih lama. Dokumentasi vLLM berversi dan panduan plugin terkini dapat menjelaskan jalur pemuatan yang berbeda. Gunakan instruksi yang sesuai dengan stack yang Anda instal.
Dapatkah saya menggunakan kembali tokenizer dari model lain?
Gunakan tokenizer yang dimiliki oleh model dasar checkpoint, kecuali penerbitnya secara eksplisit mendokumentasikan pilihan kompatibel lainnya. Server yang dimulai dengan tokenizer yang tidak terkait tetap dapat menghasilkan hasil yang salah.
Apakah pemuatan yang berhasil sudah cukup untuk produksi?
Tidak. Selesaikan pemeriksaan endpoint, kualitas tugas, fitur, dan beban realistis. Jawaban praktis untuk dukungan GGUF vLLM adalah konfigurasi yang dapat direproduksi dan lulus pengujian, bukan sekadar instalasi paket yang berhasil.
