快速入门

快速入门#

本指南将帮助您快速开始使用 vLLM 来执行

先决条件#

  • 操作系统：Linux

  • Python: 3.9 – 3.12

安装#

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

建议使用 uv，一个非常快速的 Python 环境管理器，来创建和管理 Python 环境。请按照文档安装 uv。安装 uv 后，您可以创建新的 Python 环境并使用以下命令安装 vLLM

uv venv myenv --python 3.12 --seed
source myenv/bin/activate
uv pip install vllm

另一种令人愉快的方式是使用 uv run 和 --with [dependency] 选项，这允许您运行诸如 vllm serve 之类的命令，而无需创建环境

uv run --with vllm vllm --help

您也可以使用 conda 来创建和管理 Python 环境。

conda create -n myenv python=3.12 -y
conda activate myenv
pip install vllm

注意

对于非 CUDA 平台，请参考此处获取有关如何安装 vLLM 的具体说明。

离线批量推理#

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

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

  • LLM 是使用 vLLM 引擎运行离线推理的主要类。

  • SamplingParams 指定了采样过程的参数。

from vllm import LLM, 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 模型。支持的模型列表可以在此处找到。

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

注意

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

现在，有趣的部分来了！输出是使用 llm.generate 生成的。它将输入提示添加到 vLLM 引擎的等待队列中，并执行 vLLM 引擎以高吞吐量生成输出。输出作为 RequestOutput 对象列表返回，其中包含所有输出令牌。

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

OpenAI 兼容服务器#

vLLM 可以部署为实现 OpenAI API 协议的服务器。这使得 vLLM 可以用作使用 OpenAI API 的应用程序的直接替代品。默认情况下，它在 https://127.0.0.1:8000 启动服务器。您可以使用 --host 和 --port 参数指定地址。该服务器目前一次托管一个模型，并实现诸如 列出模型、创建聊天完成和 创建完成 端点。

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

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

注意

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

重要提示

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

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

可以以与 OpenAI API 相同的格式查询此服务器。例如，要列出模型

curl https://127.0.0.1:8000/v1/models

您可以传入参数 --api-key 或环境变量 VLLM_API_KEY，以使服务器能够检查标头中的 API 密钥。

带有 vLLM 的 OpenAI Completions API#

启动服务器后，您可以使用输入提示查询模型

curl https://127.0.0.1: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://127.0.0.1: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/online_serving/openai_completion_client.py

带有 vLLM 的 OpenAI Chat Completions API#

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

您可以使用 创建聊天完成 端点与模型交互

curl https://127.0.0.1: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://127.0.0.1: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 支持多种后端，用于跨不同平台和加速器架构的高效注意力计算。它会自动选择与您的系统和模型规范兼容的最佳性能后端。

如果需要，您还可以通过将环境变量 VLLM_ATTENTION_BACKEND 配置为以下选项之一来手动设置您选择的后端：FLASH_ATTN、FLASHINFER 或 XFORMERS。

注意

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