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 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 的 GPU 卡執行 Qwen/Qwen3.8-27B 模型：

# 使用一張 NVIDIA H100 的 GPU 卡執行 Qwen/Qwen3.8-27B
vllm serve Qwen/Qwen3.8-27B \
  --reasoning-parser qwen3 \
  --enable-auto-tool-choice \
  --tool-call-parser qwen3_xml \
  --max-num-seqs 16

使用一張 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 16 \
  --gpu-memory-utilization=0.98 \
  --max-model-len 120000 \
  --enable-auto-tool-choice \
  --tool-call-parser llama3_json \
  --quantization awq

待處理事項

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

安裝 uv 套件管理程式#

安裝 vLLM 框架#

安裝 Hugging Face CLI 工具#

vLLM 模型存放位置#

使用 vLLM 布署 LLM 模型#

模型授權與 Access Token#

vLLM 運行多個模型#

Docker 執行 vLLM#

常用模型與參數#

待處理事項#