vLLM 高效能 LLM 推論框架安裝與使用教學

本文介紹如何在 Ubuntu Linux 中安裝、設定與使用 vLLM 大型語言模型推論框架，安裝各種本地端模型，進行正式環境的效能調校與布署。

vLLM 是一套開放原始碼的 LLM 推理服務引擎框架，使用方式簡單、速度快、吞吐量高、延遲低，適合用於大規模運算的的正式服務環境，可有效利用 GPU 的所有運算能力。

安裝 NVIDIA CUDA Toolkit 套件

參考 NVIDIA 的文件，安裝最新版 NVIDIA CUDA Toolkit。

安裝 uv 套件管理程式

uv 是一種用 Rust 開發的 Python 套件管理工具，比傳統的 pip 還要快十倍至百倍。參考 uv 官方網站的說明進行安裝：

# 安裝 uv 套件管理工具
curl -LsSf https://astral.sh/uv/install.sh | sh

安裝好之後，測試 uv 指令可正常執行：

# 測試 uv 指令可正常執行
uv --version

安裝 vLLM 框架

參考 vLLM 官方的說明文件，安裝 vLLM 框架：

# 在目前目錄下建立 venv 虛擬環境
uv venv vllmenv --python 3.12 --seed

# 載入 .env 虛擬環境
source vllmenv/bin/activate

# 使用 uv 安裝 vLLM
uv pip install vllm --torch-backend=auto

安裝完成後，測試 vllm 指令可正常執行：

# 測試 vllm 指令可正常執行
vllm --version

安裝 Hugging Face CLI 工具

若要使用一些需要特別授權的模型（例如 Llama），就會需要用到 Hugging Face CLI 工具，所以順便一起安裝：

# 安裝 Hugging Face CLI 工具
uv tool install huggingface-hub

安裝完成後，測試 hf 指令可正常執行：

# 測試 hf 指令可正常執行
hf --version

vLLM 模型存放位置

vLLM 預設會把下載的模型放在 Hugging Face 預設的快取目錄 ~/.cache/huggingface/hub/，如果家目錄的磁碟空間不夠大，可以參考 vLLM 環境變數的文件，更改 vLLM 的模型存放位置：

# 大量儲存空間
export LARGE_STORAGE="/mnt/data/gtwang"

# 設定 Hugging Face 資料存放目錄
export HF_HOME="${LARGE_STORAGE}/hf_home"

# 設定 vLLM 的快取目錄
export VLLM_CACHE_ROOT="${LARGE_STORAGE}/vllm_cache"

另一種方式是自行下載模型，在執行 vLLM 的時候，直接指定模型的相對路徑或絕對路徑：

# 自行下載模型
hf download Qwen/Qwen3-8B --local-dir qwen3-8b

# 指定模型的路徑
vllm serve Qwen3-8B

使用 vLLM 布署 LLM 模型

各種 LLM 模型的 vLLM 基本布署方式可以從 Hugging Face 的模型頁面上查看，但是它只提供最基礎的指令，沒有比較詳細的參數組合。

若要查詢更進階的 vLLM 布署方式，可以參考 vLLM Recipes 的資訊，這是一個由社群維護的網站，上面有針對各種模型提供建議的 GPU 卡、模型變體與 vLLM 參數，但我發現它建議的參數不一定是正確的，詳細的參數配置還是要自己看過一次。

以 Qwen/Qwen3.8-27B 來說，使用一張 NVIDIA H100 的 GPU 卡，依它預設的 vLLM 參數下去跑會出現這樣的錯誤訊息：

ValueError: max_num_seqs (1024) exceeds available Mamba cache blocks (393). Each decode sequence requires one Mamba cache block, so CUDA graph capture cannot proceed. Please lower max_num_seqs to at most 393 or increase gpu_memory_utilization.

要把 max_num_seqs 降為 393 以下才能正常執行，例如降到 256：

# 使用一張 NVIDIA H100 的 GPU 卡執行 Qwen/Qwen3.8-27B 的建議 vLLM 參數
vllm serve Qwen/Qwen3.8-27B \
  --tensor-parallel-size 1 \
  --reasoning-parser qwen3 \
  --mm-encoder-tp-mode data \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder \
  --max-num-seqs 256

執行之後 vLLM 預設會傾聽 8000 連接埠，提供相容於 OpenAI API 的介面，我們可以透過 curl 指令做一些簡單的測試，例如查詢目前 vLLM 提供的模型：

# 查詢目前 vLLM 提供的模型
curl http://localhost:8000/v1/models

{"object":"list","data":[{"id":"Qwen/Qwen3.8-27B","object":"model","created":1788959822,"owned_by":"vllm","root":"Qwen/Qwen3.8-27B","parent":null,"max_model_len":262144,"permission":[{"id":"modelperm-9f290c253deb989c","object":"model_permission","created":1788959822,"allow_create_engine":false,"allow_sampling":true,"allow_logprobs":true,"allow_search_indices":false,"allow_view":true,"allow_fine_tuning":false,"organization":"*","group":null,"is_blocking":false}]}]}[0.008s]

模型授權與 Access Token

有一些模型會需要特別的授權才能下載，像 Meta 的 Llama 系列模型，都會需要登入 Hugging Face 之後，先在模型頁面填寫申請表，提出申請並獲得授權後，才能下載，若沒有獲得授權，運行 vLLM 時就會出現類似這樣的錯誤訊息：

Access to model meta-llama/Llama-3.2-1B-Instruct is restricted. You must have access to it and be authenticated to access it. Please log in.

在命令列中我們可以使用 Hugging Face CLI 工具登入並取得權杖（token），再下載已獲得授權的模型：

# 登入 Hugging Face 並取得權杖
hf auth login

# 下載並運行已獲得授權的模型
vllm serve meta-llama/Llama-3.2-1B-Instruct

vLLM 運行多個模型

若要使用 vLLM 運行多個不同的模型，就要對每一個模型建立獨立的 vLLM 實體，如果希望使用兩張 GPU 卡，分別運行不同模型，可以使用以下指令：

# 第 1 張 GPU 卡運行 modelA
CUDA_VISIBLE_DEVICES=0 vllm serve --model modelA --gpu-memory-utilization=0.9 --port 8000

# 第 2 張 GPU 卡運行 modelB
CUDA_VISIBLE_DEVICES=1 vllm serve --model modelB --gpu-memory-utilization=0.9 --port 8001

這樣就會有兩個 vLLM 伺服器，分別傾聽 8000 與 8001 連接埠。

關於 vLLM 運行多個模型的議題，可以參考 vLLM 的論壇文章。

Docker 執行 vLLM

vLLM 也可以用 Docker 來執行，以下是一個用 Docker 執行 vLLM 的範例，採用 meta-llama/Llama-3.2-1B-Instruct 模型，而需要的權杖可以在 Hugging Face 網頁上產生後再貼過來：

# Hugging Face 權杖（token）
HF_TOKEN="YOUR_HF_TOKEN"

# 使用 Docker 執行 vLLM
docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model meta-llama/Llama-3.2-1B-Instruct

關於 vLLM 更詳盡的 Docker 使用方式，可以參考 vLLM 官方文件。

常用模型與參數

以下是我個人常用的模型與參數。

NVIDIA H100

使用一張 NVIDIA H100 的 GPU 卡執行 Qwen/Qwen3.8-27B 模型的常用參數組合：

# 使用一張 NVIDIA H100 的 GPU 卡執行 Qwen/Qwen3.8-27B
# 上下文 128K、FP8 KV Cache、允許 4 個請求
vllm serve Qwen/Qwen3.8-27B \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --gpu-memory-utilization=0.98 \
  --max-num-seqs 4 \
  --max-model-len 131072 \
  --kv-cache-dtype fp8 \
  --language-model-only \
  --enable-prefix-caching

# 使用一張 NVIDIA H100 的 GPU 卡執行 Qwen/Qwen3.8-27B
# 上下文 256K、FP8 KV Cache、允許 2 個請求
vllm serve Qwen/Qwen3.8-27B \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --gpu-memory-utilization=0.98 \
  --max-num-seqs 2 \
  --kv-cache-dtype fp8 \
  --language-model-only \
  --enable-prefix-caching

# 使用一張 NVIDIA H100 的 GPU 卡執行 Qwen/Qwen3.8-27B
# 上下文 256K、允許 1 個請求
vllm serve Qwen/Qwen3.8-27B \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --gpu-memory-utilization=0.98 \
  --max-num-seqs 1 \
  --language-model-only \
  --enable-prefix-caching

huihui-ai/Huihui-Qwen3.8-27B-abliterated 與 orcarouter/Qwen3.8-27B-Uncensored 模型是由 Qwen/Qwen3.8-27B 模型所微調出來的，所以參數組合基本上都差不多。

使用一張 NVIDIA H100 的 GPU 卡執行 Llama-3.3-70B-Instruct-AWQ 模型：

# 使用一張 NVIDIA H100 的 GPU 卡執行 Llama-3.3-70B-Instruct-AWQ
vllm serve kosbu/Llama-3.3-70B-Instruct-AWQ \
  --max-num-seqs 1 \
  --max-model-len 110000 \
  --kv-cache-dtype fp8 \
  --gpu-memory-utilization=0.98 \
  --enable-chunked-prefill \
  --max-num-batched-tokens 4096 \
  --enable-auto-tool-choice \
  --tool-call-parser llama3_json \
  --quantization awq

NVIDIA H200

使用一張 NVIDIA H200 的 GPU 卡執行 Qwen/Qwen3.8-27B 模型的常用參數組合：

# 使用一張 NVIDIA H200 的 GPU 卡執行 Qwen/Qwen3.8-27B
# 上下文 128K、FP8 KV Cache、允許 16 個請求
vllm serve Qwen/Qwen3.8-27B \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --gpu-memory-utilization=0.98 \
  --max-num-seqs 16 \
  --max-model-len 131072 \
  --kv-cache-dtype fp8 \
  --language-model-only \
  --enable-prefix-caching

# 使用一張 NVIDIA H200 的 GPU 卡執行 Qwen/Qwen3.8-27B
# 上下文 256K、FP8 KV Cache、允許 8 個請求
vllm serve Qwen/Qwen3.8-27B \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --gpu-memory-utilization=0.98 \
  --max-num-seqs 8 \
  --kv-cache-dtype fp8 \
  --language-model-only \
  --enable-prefix-caching

# 使用一張 NVIDIA H200 的 GPU 卡執行 Qwen/Qwen3.8-27B
# 上下文 256K、允許 4 個請求
vllm serve Qwen/Qwen3.8-27B \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --gpu-memory-utilization=0.98 \
  --max-num-seqs 4 \
  --language-model-only \
  --enable-prefix-caching

八張 NVIDIA H200

🚧 施工中，請減速慢行。

使用八張 NVIDIA H200 的 GPU 卡執行 deepseek-ai/DeepSeek-V4.1-Flash 模型的常用參數組合：

# 使用八張 NVIDIA H200 的 GPU 卡執行 deepseek-ai/DeepSeek-V4.1-Flash（已驗證）
# 上下文 256K、允許 16~24 個請求
VLLM_ENGINE_READY_TIMEOUT_S=3600 \
vllm serve deepseek-ai/DeepSeek-V4.1-Flash \
  --tensor-parallel-size 8 \
  --max-model-len 524288 \
  --gpu-memory-utilization 0.92 \
  --max-num-seqs 24 \
  --enable-prefix-caching \
  --max-num-batched-tokens 16384 \
  --kv-cache-dtype fp8 \
  --engram-config '{"cpu_offload":true}' \
  --tokenizer-mode deepseek_v41 \
  --tool-call-parser deepseek_v41 \
  --enable-auto-tool-choice \
  --reasoning-parser deepseek_v41 \
  --language-model-only \
  --trust-remote-code

另外亦可參考 vLLM Recipes 的 deepseek-ai/DeepSeek-V4.1-Flash 參數組合。類似常用的模型還有 s-zaizen/DeepSeek-V4.1-Flash-Abliterated。

使用八張 NVIDIA H200 的 GPU 卡執行 zai-org/GLM-5.3-Flash 模型的常用參數組合：

# 使用八張 NVIDIA H200 的 GPU 卡執行 zai-org/GLM-5.3-Flash
# 上下文 1M、允許 32 個請求
vllm serve zai-org/GLM-5.3-Flash \
  --tensor-parallel-size 8 \
  --max-model-len 1048576 \
  --gpu-memory-utilization 0.90 \
  --max-num-seqs 32 \
  --enable-prefix-caching \
  --tool-call-parser glm47 \
  --enable-auto-tool-choice \
  --language-model-only \
  --reasoning-parser glm47

另外亦可參考 vLLM Recipes 的 zai-org/GLM-5.3-Flash 參數組合。

使用八張 NVIDIA H200 的 GPU 卡執行 zai-org/GLM-5.3 模型的常用參數組合：

# 使用八張 NVIDIA H200 的 GPU 卡執行 zai-org/GLM-5.3（已驗證）
# 上下文 512K、允許 8 個請求
vllm serve zai-org/GLM-5.3 \
  --tensor-parallel-size 8 \
  --kv-cache-dtype fp8 \
  --max-model-len 524288 \
  --gpu-memory-utilization 0.92 \
  --max-num-seqs 8 \
  --enable-prefix-caching \
  --tool-call-parser glm47 \
  --reasoning-parser glm47 \
  --enable-auto-tool-choice

使用八張 NVIDIA H200 的 GPU 卡執行 Qwen/Qwen3.8-Flash-Next 與 Qwen/Qwen3.8-Flash-Next-FP8 模型的常用參數組合：

# 使用八張 NVIDIA H200 的 GPU 卡執行 Qwen/Qwen3.8-Flash-Next-FP8
# 上下文 256K、FP8 KV Cache、允許 12~16 個請求
vllm serve Qwen/Qwen3.8-Flash-Next-FP8 \
  --tensor-parallel-size 8 \
  --max-model-len 262144 \
  --gpu-memory-utilization 0.95 \
  --max-num-seqs 16 \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --kv-cache-dtype fp8 \
  --language-model-only \
  --enable-prefix-caching

# 使用八張 NVIDIA H200 的 GPU 卡執行 Qwen/Qwen3.8-Flash-Next
# 上下文 256K、FP8 KV Cache、允許 8~12 個請求
vllm serve Qwen/Qwen3.8-Flash-Next \
  --tensor-parallel-size 8 \
  --max-model-len 262144 \
  --gpu-memory-utilization 0.95 \
  --max-num-seqs 12 \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --kv-cache-dtype fp8 \
  --language-model-only \
  --enable-prefix-caching

# 使用八張 NVIDIA H200 的 GPU 卡執行 Qwen/Qwen3.8-Flash-Next
# 上下文 256K、允許 4~6 個請求
vllm serve Qwen/Qwen3.8-Flash-Next \
  --tensor-parallel-size 8 \
  --max-model-len 262144 \
  --gpu-memory-utilization 0.95 \
  --max-num-seqs 6 \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --language-model-only \
  --enable-prefix-caching

# 使用八張 NVIDIA H200 的 GPU 卡執行 Qwen/Qwen3.8-Flash-Next-FP8（已驗證）
# 上下文 512K、允許 24 個請求（可嘗試 40）
VLLM_ALLOW_LONG_MAX_MODEL_LEN=1 \
VLLM_PLE_CPU_OFFLOAD=1 \
vllm serve Qwen/Qwen3.8-Flash-Next-FP8 \
  --tensor-parallel-size 8 \
  --enable-expert-parallel \
  --moe-backend triton \
  --max-model-len 524288 \
  --hf-overrides '{"rope_parameters":{"rope_type":"yarn","factor":2.0,"original_max_position_embeddings":262144}}' \
  --gpu-memory-utilization 0.90 \
  --max-num-seqs 24 \
  --enable-prefix-caching \
  --no-enable-flashinfer-autotune \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --reasoning-parser qwen3

另外亦可參考 vLLM Recipes 的 Qwen/Qwen3.8-Flash-Next 參數組合。類似常用的模型還有 huihui-ai/Huihui-Qwen3.8-Flash-Next-abliterated 與 orcarouter/Qwen3.8-Flash-Next-Uncensored。

# openai/gpt-oss-120b（已驗證，但 context 可能有問題）
VLLM_ALLOW_LONG_MAX_MODEL_LEN=1 \
vllm serve openai/gpt-oss-120b \
  --tensor-parallel-size 8 \
  --max-model-len 524288 \
  --hf-overrides '{"rope_parameters":{"rope_type":"yarn","rope_theta":150000,"factor":128.0,"original_max_position_embeddings":4096,"beta_fast":32.0,"beta_slow":1.0,"truncate":false}}' \
  --gpu-memory-utilization 0.90 \
  --max-num-seqs 32 \
  --max-num-batched-tokens 16384 \
  --no-enable-prefix-caching \
  --tool-call-parser openai \
  --enable-auto-tool-choice \
  --reasoning-parser openai_gptoss

# meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8
VLLM_DISABLE_COMPILE_CACHE=1 \
vllm serve meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8 \
  --tensor-parallel-size 8 \
  --max-model-len 524288 \
  --override-generation-config '{"attn_temperature_tuning": true}' \
  --gpu-memory-utilization 0.90 \
  --max-num-seqs 32 \
  --enable-prefix-caching \
  --tool-call-parser llama4_pythonic \
  --enable-auto-tool-choice \
  --language-model-only

# RedHatAI/NVIDIA-Nemotron-3-Ultra-550B-A55B-FP8-dynamic
vllm serve RedHatAI/NVIDIA-Nemotron-3-Ultra-550B-A55B-FP8-dynamic \
  --host 0.0.0.0 --port 8000 \
  --trust-remote-code \
  --tensor-parallel-size 8 \
  --max-model-len 262144 \
  --max-num-seqs 16 \
  --gpu-memory-utilization 0.90 \
  --kv-cache-dtype fp8 \
  --async-scheduling \
  --reasoning-parser nemotron_v3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_coder \
  --speculative-config '{"method": "nemotron_h_mtp", "num_speculative_tokens": 5}'

# 使用八張 NVIDIA H200 的 GPU 卡執行 Qwen/Qwen3.8-27B（已驗證）
vllm serve Qwen/Qwen3.8-27B \
  --tensor-parallel-size 2 \
  --data-parallel-size 4 \
  --max-model-len 262144 \
  --max-num-batched-tokens 16384 \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --gpu-memory-utilization 0.90 \
  --max-num-seqs 64 \
  --language-model-only \
  --enable-prefix-caching

參考資料

myyang19770915/vllm-model-serve

待處理事項

vLLM 細部參數說明。
vLLM 最佳化與效能測試報告。
常用 vLLM 模型布署方案與參數組合。

安裝 NVIDIA CUDA Toolkit 套件#

安裝 uv 套件管理程式#

安裝 vLLM 框架#

安裝 Hugging Face CLI 工具#

vLLM 模型存放位置#

使用 vLLM 布署 LLM 模型#

模型授權與 Access Token#

vLLM 運行多個模型#

Docker 執行 vLLM#

常用模型與參數#

NVIDIA H100#

NVIDIA H200#

八張 NVIDIA H200#

參考資料#

待處理事項#