快速入門¶
本指南將幫助您快速開始使用 vLLM 來執行
先決條件¶
- 作業系統：Linux
- Python: 3.10 -- 3.13
安裝¶
如果您使用的是 NVIDIA GPU，可以直接使用 pip 安裝 vLLM。
建議使用 uv，一個非常快的 Python 環境管理器，來建立和管理 Python 環境。請按照 文件 安裝 uv。安裝 uv 後，您可以使用以下命令建立一個新的 Python 環境並安裝 vLLM：
uv 可以透過 --torch-backend=auto (或 UV_TORCH_BACKEND=auto) 來檢查安裝的 CUDA 驅動版本，從而 在執行時自動選擇合適的 PyTorch 索引。要選擇特定的後端 (例如 cu126)，請設定 --torch-backend=cu126 (或 UV_TORCH_BACKEND=cu126)。
另一種愉快的方式是使用 uv run 和 --with [dependency] 選項，這允許您在不建立任何永久環境的情況下執行 vllm serve 等命令。
您也可以使用 conda 來建立和管理 Python 環境。如果您想在 conda 環境中管理 uv，可以透過 pip 將其安裝到 conda 環境中。
使用 Docker Hub 提供的預構建 Docker 映象。公共穩定映象為 rocm/vllm:latest。還有一個開發映象位於 rocm/vllm-dev。
下面的 docker run 命令中的 -v 標誌會將本地目錄掛載到容器中。將 <path/to/your/models> 替換為主機上包含模型的目錄路徑。然後，模型將在容器內的 /app/models 處可用。
命令
docker pull rocm/vllm-dev:nightly # to get the latest image
docker run -it --rm \
--network=host \
--group-add=video \
--ipc=host \
--cap-add=SYS_PTRACE \
--security-opt seccomp=unconfined \
--device /dev/kfd \
--device /dev/dri \
-v <path/to/your/models>:/app/models \
-e HF_HOME="/app/models" \
rocm/vllm-dev:nightly
要在 Google TPU 上執行 vLLM，您需要安裝 vllm-tpu 包。
注意
有關更詳細的說明，包括 Docker、從原始碼安裝和故障排除，請參閱 vLLM on TPU 文件。
注意
有關更多詳細資訊和非 CUDA 平臺，請參閱 此處 獲取安裝 vLLM 的具體說明。
離線批處理推理¶
安裝 vLLM 後，您可以開始為一系列輸入提示生成文字（即離線批處理推理）。請參閱示例指令碼： examples/offline_inference/basic/basic.py
此示例的第一行匯入了 LLM 和 SamplingParams 類。
- LLM 是使用 vLLM 引擎執行離線推理的主要類。
- SamplingParams 指定了取樣過程的引數。
下一部分定義了一系列用於文字生成的輸入提示和取樣引數。 取樣溫度設定為 0.8，核取樣機率設定為 0.95。有關取樣引數的更多資訊，您可以在 此處 找到。
重要
預設情況下，vLLM 將使用模型建立者推薦的取樣引數，透過應用 Hugging Face 模型儲存庫中的 generation_config.json (如果存在)。在大多數情況下，如果您未指定 SamplingParams，這將為您提供最佳的預設結果。
但是，如果您偏好 vLLM 的預設取樣引數，請在建立 LLM 例項時設定 generation_config="vllm"。
prompts = [
"Hello, my name is",
"The president of the United States is",
"The capital of France is",
"The future of AI is",
]
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)
LLM 類初始化 vLLM 引擎和 OPT-125M 模型 以進行離線推理。支援的模型列表可以在 此處 找到。
注意
預設情況下，vLLM 從 Hugging Face 下載模型。如果您想使用 ModelScope 中的模型，請在初始化引擎之前設定環境變數 VLLM_USE_MODELSCOPE。
現在，激動人心的部分來了！輸出是使用 llm.generate 生成的。它將輸入提示新增到 vLLM 引擎的等待佇列中，並執行 vLLM 引擎以高吞吐量生成輸出。輸出將作為 RequestOutput 物件列表返回，其中包含所有輸出的 token。
outputs = llm.generate(prompts, sampling_params)
for output in outputs:
prompt = output.prompt
generated_text = output.outputs[0].text
print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")
注意
llm.generate 方法不會自動將模型的聊天模板應用於輸入提示。因此，如果您使用的是 Instruct 模型或 Chat 模型，則應手動應用相應的聊天模板以確保預期的行為。或者，您可以使用 llm.chat 方法並傳遞與傳遞給 OpenAI 的 client.chat.completions 格式相同的訊息列表。
程式碼
# Using tokenizer to apply chat template
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("/path/to/chat_model")
messages_list = [
[{"role": "user", "content": prompt}]
for prompt in prompts
]
texts = tokenizer.apply_chat_template(
messages_list,
tokenize=False,
add_generation_prompt=True,
)
# Generate outputs
outputs = llm.generate(texts, sampling_params)
# Print the outputs.
for output in outputs:
prompt = output.prompt
generated_text = output.outputs[0].text
print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")
# Using chat interface.
outputs = llm.chat(messages_list, sampling_params)
for idx, output in enumerate(outputs):
prompt = prompts[idx]
generated_text = output.outputs[0].text
print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")
相容 OpenAI 的伺服器¶
vLLM 可以部署為一個實現 OpenAI API 協議的伺服器。這使得 vLLM 能夠作為應用程式使用 OpenAI API 的即插即用替代品。預設情況下，伺服器將在 https://:8000 啟動。您可以使用 --host 和 --port 引數指定地址。該伺服器目前一次只能託管一個模型，並實現了 列出模型、建立聊天補全 和 建立補全 等端點。
執行以下命令，使用 Qwen2.5-1.5B-Instruct 模型啟動 vLLM 伺服器。
注意
預設情況下，伺服器使用儲存在 tokenizer 中的預定義聊天模板。您可以在 此處 瞭解如何覆蓋它。
重要
預設情況下，伺服器會應用 Hugging Face 模型儲存庫中的 generation_config.json。這意味著某些取樣引數的預設值可能會被模型建立者推薦的值覆蓋。
要停用此行為，請在啟動伺服器時傳遞 --generation-config vllm。
可以透過與 OpenAI API 相同的格式查詢此伺服器。例如，列出模型
您可以傳遞 --api-key 引數或設定環境變數 VLLM_API_KEY 來啟用伺服器在請求頭中檢查 API 金鑰。您可以為 --api-key 傳遞多個金鑰，伺服器將接受其中任何一個金鑰，這對於金鑰輪換很有用。
vLLM 的 OpenAI Completions API¶
伺服器啟動後，您可以用輸入提示查詢模型
curl https://:8000/v1/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen2.5-1.5B-Instruct",
"prompt": "San Francisco is a",
"max_tokens": 7,
"temperature": 0
}'
由於該伺服器相容 OpenAI API，因此您可以將其作為任何使用 OpenAI API 的應用程式的即插即用替代品。例如，另一種查詢伺服器的方式是透過 openai Python 包。
程式碼
from openai import OpenAI
# Modify OpenAI's API key and API base to use vLLM's API server.
openai_api_key = "EMPTY"
openai_api_base = "https://:8000/v1"
client = OpenAI(
api_key=openai_api_key,
base_url=openai_api_base,
)
completion = client.completions.create(
model="Qwen/Qwen2.5-1.5B-Instruct",
prompt="San Francisco is a",
)
print("Completion result:", completion)
更詳細的客戶端示例可以在這裡找到： examples/offline_inference/basic/basic.py
vLLM 的 OpenAI Chat Completions API¶
vLLM 還支援 OpenAI Chat Completions API。聊天介面是一種更動態、更具互動性的與模型溝通的方式，允許進行可以儲存在聊天曆史記錄中的來回交流。這對於需要上下文或更詳細解釋的任務非常有用。
您可以使用 建立聊天補全 端點與模型進行互動。
curl https://:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "Qwen/Qwen2.5-1.5B-Instruct",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Who won the world series in 2020?"}
]
}'
或者，您也可以使用 openai Python 包。
程式碼
from openai import OpenAI
# Set OpenAI's API key and API base to use vLLM's API server.
openai_api_key = "EMPTY"
openai_api_base = "https://:8000/v1"
client = OpenAI(
api_key=openai_api_key,
base_url=openai_api_base,
)
chat_response = client.chat.completions.create(
model="Qwen/Qwen2.5-1.5B-Instruct",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Tell me a joke."},
],
)
print("Chat response:", chat_response)
關於 Attention 後端¶
目前，vLLM 支援多種後端，以便在不同的平臺和加速器架構上高效地進行 Attention 計算。它會自動選擇與您的系統和模型規格相容的最優後端。
如果需要，您也可以使用 --attention-backend CLI 引數手動設定您選擇的後端。
# For online serving
vllm serve Qwen/Qwen2.5-1.5B-Instruct --attention-backend FLASH_ATTN
# For offline inference
python script.py --attention-backend FLASHINFER
一些可用的後端選項包括：
- 在 NVIDIA CUDA 上：
FLASH_ATTN或FLASHINFER。 - 在 AMD ROCm 上：
TRITON_ATTN,ROCM_ATTN,ROCM_AITER_FA或ROCM_AITER_UNIFIED_ATTN。
對於 AMD ROCm，您還可以使用以下選項進一步控制特定的 Attention 實現：
- Triton Unified Attention：設定環境變數
VLLM_ROCM_USE_AITER=0 VLLM_ROCM_USE_AITER_MHA=0並將--attention-config.use_prefill_decode_attention=false作為 CLI 引數傳遞。 - AITER Unified Attention：設定環境變數
VLLM_ROCM_USE_AITER=1 VLLM_USE_AITER_UNIFIED_ATTENTION=1 VLLM_ROCM_USE_AITER_MHA=0並將--attention-config.use_prefill_decode_attention=false作為 CLI 引數傳遞。 - Triton Prefill-Decode Attention：設定環境變數
VLLM_ROCM_USE_AITER=1 VLLM_ROCM_USE_AITER_MHA=0並將--attention-config.use_prefill_decode_attention=true作為 CLI 引數傳遞。 - AITER Multi-head Attention：設定環境變數
VLLM_ROCM_USE_AITER=1 VLLM_ROCM_USE_AITER_MHA=1並將--attention-config.use_prefill_decode_attention=false作為 CLI 引數傳遞。
警告
沒有包含 Flash Infer 的預構建 vllm wheel，因此您必須先在環境中安裝它。請參閱 Flash Infer 官方文件 或檢視 docker/Dockerfile 以獲取安裝說明。