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

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

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

安裝 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 --python 3.12 --seed

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

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

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

# 測試 vllm 指令可正常執行
vllm --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 的時候，直接指定模型的相對路徑或絕對路徑：

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

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

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

布署 LLM 模型

若要使用 vLLM 布署常見的 LLM 模型，可以參考 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]

運行多個模型

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

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

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

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

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

待處理事項

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

安裝 uv 套件管理程式#

安裝 vLLM 框架#

vLLM 模型存放位置#

布署 LLM 模型#

運行多個模型#

待處理事項#