快速入门¶
本指南将帮助您快速开始使用 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 以获取安装说明。