vLLM快速入门及安装指南

快速入门

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

  • 离线批量推理 (Offline batched inference)
  • 使用 OpenAI 兼容服务器进行在线服务 (Online serving)

前置条件

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

安装

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

推荐使用 uv,一个非常快速的 Python 环境管理器,来创建和管理 Python 环境。请遵循 uv 文档 进行安装。安装 uv 后,您可以使用以下命令创建新的 Python 环境并安装 vLLM:

bash 复制代码
uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

uv 可以通过 --torch-backend=auto(或设置环境变量 UV_TORCH_BACKEND=auto)在运行时通过检查已安装的 CUDA 驱动程序版本来自动选择合适的 PyTorch 索引。要选择特定的后端(例如 cu126),请设置 --torch-backend=cu126(或 UV_TORCH_BACKEND=cu126). 看我另一个文章使用 uv 设成中国的镜象,不然慢到你怀疑人生。

另一种便捷的方式是使用 uv run 加上 --with [dependency] 选项,这允许您运行诸如 vllm serve 之类的命令,而无需创建任何永久性环境:

bash 复制代码
uv run --with vllm vllm --help

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

bash 复制代码
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

此示例的第一行导入了 LLMSamplingParams 类:

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

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

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

但是,如果希望使用 vLLM 的默认采样参数,请在创建 LLM 实例时设置 generation_config="vllm"

python 复制代码
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 模型。支持的模型列表可以在此处找到。

python 复制代码
llm = LLM(model="facebook/opt-125m")

注意

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

如下

bash 复制代码
export VLLM_USE_MODELSCOPE=True

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

python 复制代码
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 的消息格式相同:

python 复制代码
# 使用 llm.chat 的示例 (假设 messages 已按正确格式构造)
# messages = [ ... ]
# outputs = llm.chat(messages, sampling_params)

OpenAI 兼容服务器

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

运行以下命令以启动带有 Qwen2.5-1.5B-Instruct 模型的 vLLM 服务器:

bash 复制代码
vllm serve Qwen/Qwen2.5-1.5B-Instruct

注意

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

重要

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

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

可以按照与 OpenAI API 相同的格式查询此服务器。例如,列出模型:

bash 复制代码
curl http://localhost:8000/v1/models

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

使用 vLLM 的 OpenAI Completions API

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

bash 复制代码
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 包:

python 复制代码
# 使用 openai Python 包的示例
from openai import OpenAI

# 指向本地服务器
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="token-abc123" # 如果设置了 --api-key 或 VLLM_API_KEY,则需要,否则可以是任意值
)

completion = client.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    prompt="San Francisco is a",
    max_tokens=7,
    temperature=0
)
print(completion.choices[0].text)

更详细的客户端示例可以在这里找到:examples/online_serving/openai_completion_client.py

使用 vLLM 的 OpenAI Chat Completions API

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

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

bash 复制代码
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 包:

python 复制代码
# 使用 openai Python 包进行聊天的示例
from openai import OpenAI

# 指向本地服务器
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="token-abc123" # 如果设置了 --api-key 或 VLLM_API_KEY,则需要,否则可以是任意值
)

chat_completion = client.chat.completions.create(
    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?"}
    ]
)
print(chat_completion.choices[0].message.content)

关于注意力后端 (Attention Backends)

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

如果需要,您也可以通过配置环境变量 VLLM_ATTENTION_BACKEND 为以下选项之一来手动设置您选择的后端:FLASH_ATTNFLASHINFERXFORMERS

相关推荐
用户8356290780515 小时前
使用C#轻松提取PDF图片:Spire.PDF for .NET实战教程
后端·c#
凯哥19705 小时前
UV 工具安装与国内镜像源配置指南
后端
用户697244900265 小时前
scala安装和基本使用
后端
该用户已不存在6 小时前
Windows 开发环境这么难配,为什么还有那么多人在用?
前端·windows·后端
二闹6 小时前
告别卡顿!用Python生成器轻松处理海量数据的秘籍
后端·python
zjjuejin6 小时前
Docker 镜像管理完全指南:从拉取到迁移的终极实践
后端·docker
荔枝lizhi6 小时前
mac 忘记mariadb 的密码,重置密码,找回密码
后端
panco681206 小时前
Kratos框架处理未注册路由与引入其他标准http服务
后端
不知道取啥耶6 小时前
基于Springboot和Vue的前后端分离项目
vue.js·spring boot·后端