快速入门¶

本指南将帮助您快速上手 vLLM 以执行以下操作：

离线批处理推理
使用兼容 OpenAI 的服务器进行在线服务

先决条件¶

操作系统：Linux
Python: 3.10 -- 3.13

安装¶

NVIDIA CUDAAMD ROCmGoogle TPU

如果您使用的是 NVIDIA GPU，可以直接使用 pip 安装 vLLM。

推荐使用 uv（一个速度极快的 Python 环境管理器）来创建和管理 Python 环境。请遵循官方文档安装 uv。安装 uv 后，您可以使用以下命令创建新的 Python 环境并安装 vLLM：

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

uv 可以通过检查已安装的 CUDA 驱动程序版本，使用 --torch-backend=auto（或 UV_TORCH_BACKEND=auto）在运行时自动选择合适的 PyTorch 索引。若要选择特定后端（例如 cu126），请设置 --torch-backend=cu126（或 UV_TORCH_BACKEND=cu126）。

另一种便捷方法是使用带有 --with [dependency] 选项的 uv run，这允许您在不创建永久环境的情况下运行诸如 vllm serve 之类的命令。

uv run --with vllm vllm --help

您也可以使用 conda 来创建和管理 Python 环境。如果您希望在 conda 环境内管理 uv，可以通过 pip 将其安装到该环境中。

conda create -n myenv python=3.12 -y
conda activate myenv
pip install --upgrade uv
uv pip install vllm --torch-backend=auto

如果您使用的是 AMD GPU，可以使用 uv 安装 vLLM。

建议使用 uv，因为它赋予了额外索引比默认索引更高的优先级。uv 同时也是一个非常快速的 Python 环境管理器，用于创建和管理 Python 环境。请遵循官方文档安装 uv。安装 uv 后，您可以使用以下命令创建新的 Python 环境并安装 vLLM：

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --extra-index-url https://wheels.vllm.ai/rocm/

注意

目前支持 Python 3.12、ROCM 7.0 和 glibc >= 2.35。

注意

请注意，此前 docker 镜像使用 AMD 的 docker 发布流水线发布，位于 rocm/vllm-dev。该方式现正被弃用，转而使用 vLLM 的 docker 发布流水线。

提示

此外，还提供每日构建的 Docker 镜像 vllm/vllm-openai-rocm:nightly，用于测试最新的开发版本。

要在 Google TPU 上运行 vLLM，您需要安装 vllm-tpu 包。

uv pip install vllm-tpu

注意

有关包括 Docker、源码安装及故障排除在内的更多详细说明，请参考 vLLM on TPU 文档。

注意

有关更多详情及非 CUDA 平台的信息，请参考安装指南以获取安装 vLLM 的具体说明。

离线批处理推理¶

安装 vLLM 后，您可以开始为一系列输入提示生成文本（即离线批处理推理）。请参见示例脚本： examples/basic/offline_inference/basic.py

该示例的第一行导入了 LLM 和 SamplingParams 类。

LLM 是使用 vLLM 引擎进行离线推理的主要类。
SamplingParams 用于指定采样过程的参数。

from vllm import LLM, SamplingParams

下一节定义了输入提示列表和文本生成的采样参数。采样温度 (Sampling temperature) 设置为 0.8，核采样概率 (Nucleus sampling probability) 设置为 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 模型。支持的模型列表可以在此处找到。

llm = LLM(model="facebook/opt-125m")

注意

默认情况下，vLLM 从 Hugging Face 下载模型。如果您希望使用来自 ModelScope 的模型，请在初始化引擎之前设置环境变量 VLLM_USE_MODELSCOPE。

export VLLM_USE_MODELSCOPE=True

现在是激动人心的部分！输出是使用 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 model）或聊天模型（Chat model），您应该手动应用相应的聊天模板以确保预期的行为。或者，您可以使用 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 服务器：

vllm serve Qwen/Qwen2.5-1.5B-Instruct

注意

默认情况下，服务器使用存储在分词器（tokenizer）中的预定义聊天模板。您可以在此处了解如何覆盖它。

重要

默认情况下，服务器会应用 Hugging Face 模型仓库中的 generation_config.json（如果存在）。这意味着某些采样参数的默认值可能会被模型创建者推荐的值所覆盖。

若要禁用此行为，请在启动服务器时传递 --generation-config vllm。

该服务器可以使用与 OpenAI API 相同的格式进行查询。例如，列出模型：

curl https://:8000/v1/models

您可以传入 --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/basic/offline_inference/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, TRITON_MLA, ROCM_AITER_MLA 或 ROCM_AITER_TRITON_MLA。

警告

目前没有包含 Flash Infer 的预构建 vllm wheel，因此您必须先在您的环境中安装它。请参考 Flash Infer 官方文档或查看 docker/Dockerfile 获取安装说明。