跳至内容

快速入门

本指南将帮助您快速上手vLLM，用于执行：

先决条件

  • 操作系统: Linux
  • Python: 3.9 -- 3.12

安装

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

另一种便捷的方式是使用uv run配合--with [dependency]选项，这样您就可以运行诸如vllm serve之类的命令，而无需创建任何永久性环境：

uv run --with vllm vllm --help

你也可以使用conda来创建和管理Python环境。如果你想在环境中管理它，可以通过pip将uv安装到conda环境中。

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

注意

如需了解更多详情及非CUDA平台的支持，请参阅此处获取vLLM的具体安装指南。

离线批量推理

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

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

  • LLM 是使用 vLLM 引擎运行离线推理的主类。
  • SamplingParams 指定了采样过程的参数。
from vllm import LLM, SamplingParams

下一部分定义了用于文本生成的输入提示列表和采样参数。采样温度设置为0.8，核心采样概率设置为0.95。您可以在此处找到有关采样参数的更多信息。

重要

默认情况下，如果未指定SamplingParams，vLLM会应用Hugging Face模型仓库中的generation_config.json文件（如果存在），使用模型创建者推荐的采样参数。在大多数情况下，这将为您提供最佳的默认结果。

但如果偏好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对象列表的形式返回，其中包含所有输出令牌。

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的应用程序。默认情况下，它会在http://localhost:8000启动服务器。您可以通过--host和--port参数指定地址。该服务器目前一次托管一个模型，并实现了诸如list models、create chat completion和create completion等端点。

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

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

注意

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

重要

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

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

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

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

你可以传入参数--api-key或环境变量VLLM_API_KEY来让服务器检查请求头中的API密钥。你可以在--api-key后传入多个密钥，服务器会接受其中任意一个密钥，这在密钥轮换时很有用。

使用vLLM的OpenAI Completions 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包：

Code 
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 = "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/online_serving/openai_completion_client.py

基于vLLM的OpenAI聊天补全API

vLLM 旨在同时支持 OpenAI 聊天补全 API。该聊天界面是一种更动态、交互式的模型交流方式，支持存储在聊天历史记录中的多轮对话交换。这对于需要上下文或更详细解释的任务非常有用。

您可以使用create chat completion端点与模型进行交互：

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包：

Code 
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 = "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支持多种后端，可在不同平台和加速器架构上高效计算注意力机制。它会根据您的系统和模型规格自动选择性能最优的兼容后端。

如果需要，您也可以通过配置环境变量VLLM_ATTENTION_BACKEND手动选择后端，可选值为：FLASH_ATTN、FLASHINFER或XFORMERS。

警告

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

优云智算