快速入门¶

本指南将帮助您快速上手使用 vLLM 执行以下任务：

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

先决条件¶

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

安装¶

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

uv run --with vllm vllm --help

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

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

uv pip install vllm-tpu

离线批量推理¶

安装 vLLM 后，您可以开始对输入提示列表生成文本（即离线批量推理）。参考示例脚本： examples/offline_inference/basic/basic.py

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

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

from vllm import LLM, SamplingParams

下一部分定义了输入提示列表和文本生成的采样参数。采样温度 设为 0.8，核采样概率 设为 0.95。关于采样参数的更多信息，请参见此处。

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")

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}")

# 使用 tokenizer 应用对话模板
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,
)

# 生成输出
outputs = llm.generate(texts, 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}")

# 使用 chat 接口
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 的应用程序的即插即用替代方案。

默认情况下，服务端启动地址为 http://localhost:8000。您可以通过 --host 和 --port 参数指定地址。服务端目前一次只能托管一个模型，并实现了诸如列出模型、创建聊天补全和创建补全等端点。

运行以下命令以使用 Qwen2.5-1.5B-Instruct 模型启动 vLLM 服务端：

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

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

curl http://localhost:8000/v1/models

您可以传递 --api-key 参数或设置环境变量 VLLM_API_KEY 以启用服务端检查请求头中的 API 密钥。 您可以在 --api-key 后传递多个密钥，服务端将接受任何传递的密钥，这对于密钥轮换非常有用。

使用 vLLM 的 OpenAI 补全 API¶

一旦您的服务端启动，您可以使用输入提示查询模型：

curl http://localhost: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

# 修改 OpenAI 的 API 密钥和 API 基础 URL 以使用 vLLM 的 API 服务端。
openai_api_key = "EMPTY"
openai_api_base = "http://localhost: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 聊天补全 API¶

vLLM 也设计为支持 OpenAI 聊天补全 API。聊天界面是一种更动态、交互式的与模型通信的方式，允许来回交流并可以存储在聊天历史中。这对于需要上下文或更详细解释的任务非常有用。

您可以使用创建聊天补全端点与模型交互：

curl http://localhost: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
# 设置 OpenAI 的 API 密钥和 API 基础 URL 以使用 vLLM 的 API 服务端。
openai_api_key = "EMPTY"
openai_api_base = "http://localhost: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)

关于注意力后端¶

目前，vLLM 支持多个后端，以便在不同的平台和加速器架构上进行高效的注意力计算。它会自动选择与您的系统和模型规格兼容的性能最佳的后端。

如果需要，您也可以使用 --attention-backend CLI 参数手动设置您选择的后端：

# 用于在线服务
vllm serve Qwen/Qwen2.5-1.5B-Instruct --attention-backend FLASH_ATTN

# 用于离线推理
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。