vLLM 快速上手：从离线批量推理到 OpenAI 兼容在线服务

本指南基于 vLLM 官方 Quickstart 文档整理而成，帮助你在最短时间内跑通两种最核心的使用方式：用 LLM 类进行离线批量推理（一次性生成一批 prompt 的文本），以及用 vllm serve 启动兼容 OpenAI API 的在线服务（供 curl、openai Python SDK 或既有应用直接调用）。读完本文，你将掌握多硬件平台的安装方法、采样参数的核心语义、Chat 模板的处理要点，以及 Attention 后端的手动选择方式，并了解这些能力背后对应的源码入口。

环境前提

vLLM 的官方快速上手要求如下基础环境：

• 操作系统：Linux；
• Python 版本：3.10 — 3.13。

除此之外，vLLM 还可在 Apple Silicon Mac 上通过 vLLM-Metal 获得 Metal GPU 加速；该方案以 MLX 而非 PyTorch 作为计算后端，需要加载 mlx-community 提供的 MLX 优化模型。更完整的逐平台安装说明（包括源码编译与 Docker）可查看 GPU 安装指南 与 安装文档总览。

安装：按硬件平台选择

vLLM 的安装方式因目标加速器而异。下面按官方文档的标签逐一说明。

NVIDIA CUDA

使用 NVIDIA GPU 时可直接通过 pip 安装 vLLM。官方推荐使用 uv（一个非常快的 Python 环境管理器）来创建并管理虚拟环境。安装 uv 后，可依次执行：

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

其中 --torch-backend=auto（或环境变量 UV_TORCH_BACKEND=auto）会让 uv 在运行时检查已安装的 CUDA 驱动版本，自动挑选匹配的 PyTorch 索引；如果你想固定某一后端（例如 cu126），则改为 uv pip install vllm --torch-backend=cu126（或 UV_TORCH_BACKEND=cu126）。

另一种轻量用法是 uv run --with <依赖>，不创建任何常驻环境即可直接执行 vLLM 命令：

uv run --with vllm vllm --help

如果你习惯用 conda 管理环境，也可以把 uv 装进 conda 环境内使用：

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

AMD ROCm

使用 AMD GPU 时同样推荐 uv：它会让额外指定的索引获得比默认索引更高的优先级，从而拉取到对应 ROCm 平台的预编译包。安装命令：

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

两点注意：

• 当前 ROCm 通道支持 Python 3.12、ROCm 7.0 且要求 glibc >= 2.35；
• 此前通过 AMD docker 发布管线发布的 rocm/vllm-dev 镜像正在被 vLLM 自身的 docker 发布管线取代（即逐步弃用）。

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

Intel GPU（XPU）

vLLM 通过 XPU 后端支持 Intel GPU，官方预编译 XPU wheel 即将提供。自 v0.26.0 起，vLLM 发布版本开始包含 Intel GPU 的官方 Docker 镜像，每晚镜像为 vllm/vllm-openai-xpu:nightly。包含源码编译与 Docker 设置的详细步骤见 GPU 安装指南 中的 "Intel XPU" 标签页。

Google TPU

在 Google TPU 上运行 vLLM，需要安装独立的 vllm-tpu 包：

uv pip install vllm-tpu

更完整的 Docker、源码安装与故障排查说明请参阅官方 "vLLM on TPU" 文档。

Ascend NPU

Ascend NPU 用户通过社区维护的硬件插件 vLLM Ascend 运行 vLLM，其安装步骤依赖具体的 NPU 硬件与 CANN 版本，请按其 quick start 文档执行。

Apple Silicon（Mac）

Apple Silicon Mac 可通过 vLLM-Metal 使用 Apple Metal 框架获得 GPU 加速推理，安装步骤见其文档。注意：vLLM-Metal 使用 MLX（而非 PyTorch）作为计算后端，需要加载 Hugging Face 上 mlx-community 组织的 MLX 优化模型。

离线批量推理：LLM + SamplingParams

安装完成后即可对一批输入 prompt 批量生成文本，即离线推理（offline batched inference）。官方示例脚本见 examples/basic/offline_inference/basic.py，该文件在仓库中位于 vllm/ 主包之外，是最小化的完整演示。

示例第一行导入两个核心类：

from vllm import LLM, SamplingParams

在 vllm/init.py 的模块导出映射中可以看到：LLM 实际来自 vllm.entrypoints.llm，SamplingParams 来自 vllm.sampling_params。

• LLM：运行离线推理的主类。其 docstring 说明它内部包含 tokenizer、语言模型（可能跨多张 GPU 分布式部署）以及为中间状态（即 KV cache）分配的 GPU 显存；
• SamplingParams：描述采样过程的参数对象（温度、top-p、最大生成长度等）。

然后定义一批 prompt 与采样参数：

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)

这里 temperature=0.8 控制随机性，top_p=0.95 采用核采样（nucleus sampling）：只从累积概率达到 0.95 的最可能 token 集合中采样。更多采样参数的语义与取值范围参见 docs/api/README.md 的 Inference Parameters 章节。

接着实例化引擎并加载模型：

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

从 LLM.init 的签名可以看到，离线推理同样支持 tokenizer、tensor_parallel_size（张量并行 GPU 数）、dtype（float32/float16/bfloat16，auto 时优先取模型配置 dtype 且 float32 会回退到 float16）、gpu_memory_utilization（默认 0.92，用于模型权重、激活与 KV cache 的显存比例，调高可提升吞吐但过高会 OOM）、enforce_eager（是否禁用 CUDA graph 强制 eager 执行）等工程化参数，与 vllm serve 的 CLI 参数一一对应。默认从 Hugging Face 下载模型；若希望改从 ModelScope 拉取，请在初始化引擎前设置环境变量：

export VLLM_USE_MODELSCOPE=True

该开关在 vllm/envs.py 中定义，值为 "1"/"true"（不区分大小写）即视为开启。

然后调用 llm.generate 生成输出：

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 的实现可知：该方法会把 prompts 加入 vLLM 引擎的等待队列，再由引擎以高吞吐方式批量执行，返回与输入 prompt 同序的 RequestOutput 对象列表。RequestOutput 定义于 vllm/outputs.py，包含 prompt、完整输出 token、token id、logprobs 等信息；sampling_params 既可以传单个对象（作用于所有 prompt），也可以传与 prompts 等长的列表按序一一配对。若想观察批处理进度，可通过 use_tqdm 参数控制进度条。

关于默认采样参数：模型作者推荐值

一个容易忽略的要点是：默认情况下，如果模型仓库中存在 generation_config.json，vLLM 会采用模型作者推荐的采样参数（未显式指定 SamplingParams 时通常能带来最佳效果）。如果希望强制使用 vLLM 自身的默认采样参数，则在创建 LLM 实例时传 generation_config="vllm"。

至于 vLLM 的默认值，见 vllm/sampling_params.py 的数据类定义：temperature=1.0（0 表示贪心解码）、top_p=1.0、top_k=0（0 或 -1 表示考虑全部 token）、max_tokens=16、min_tokens=0、n=1（每 prompt 返回序列数，上限由环境变量 VLLM_MAX_N_SEQUENCES 控制，默认 16384）等。此外还支持 stop/stop_token_ids 停止串、presence_penalty/frequency_penalty/repetition_penalty 三类惩罚项、logprobs/prompt_logprobs 概率返回等。

Chat 模型必须正确应用模板

llm.generate 不会自动为输入 prompt 套用模型的 chat template。因此使用 Instruct/Chat 模型时，应手动应用对应聊天模板，或直接改用 llm.chat 方法并传入与 OpenAI client.chat.completions 相同格式的 messages。官方示例给出了三种写法：

# 方式一：用 tokenizer 套用 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,
)

# 生成
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}")

llm.chat 同样支持批量：传入 messages 列表组成的列表即可一次处理多轮对话。仓库中的 examples/basic/offline_inference/chat.py 演示了 llm.chat 的完整用法，包括可选的自定义 chat template、批量并发以及通过 --chat-template-path 传入模板文件；不传时模型会使用其自带的默认 chat template。

在线服务：兼容 OpenAI API 的服务器

vLLM 可以部署为一个实现 OpenAI API 协议的服务器，从而作为 OpenAI API 应用的即插即用替代品。默认监听 http://localhost:8000，可用 --host 与 --port 指定地址。服务器一次托管一个模型，实现了 list models、create chat completion、create completion 等端点。

用 Qwen2.5-1.5B-Instruct 启动服务器：

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

两个默认行为需要留意：

• 服务器默认使用 tokenizer 中预置的 chat template，需要覆盖时参见在线服务文档的 Chat template 章节；
• 与离线推理一致，服务器默认也会应用 Hugging Face 仓库中的 generation_config.json（模型作者推荐的采样参数会被采用）。想禁用该行为，启动时加 --generation-config vllm。

启动后可查询当前模型列表：

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

若需鉴权，可传 --api-key 参数或设置环境变量 VLLM_API_KEY；--api-key 支持传多个 key，服务器会接受其中任意一个，便于做 key 轮换。该参数在 vllm/entrypoints/cli/openai.py 中定义，且从 vllm/entrypoints/serve/middleware/register.py 的实现看，CLI 传入的 --api-key 优先于环境变量 VLLM_API_KEY。

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 Python 包查询（仅需把 API base 指向 vLLM 服务器）：

from openai import OpenAI

# 将 OpenAI 的 API key 与 API base 改为 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/basic/offline_inference/basic.py。

Chat Completions 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 key 与 API base 指向 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)

Attention 后端：自动选择与手动覆盖

vLLM 当前支持多种 Attention 计算后端，以适配不同平台与加速器架构，并会依据你的系统与模型规格自动挑选性能最优的后端。从源码看，Attention 相关的配置与选择逻辑集中在 vllm/config/attention.py，包括按 KV cache group 粒度的后端覆盖（backend_per_kind）以及 MLA prefill 后端等高级选项。

如确有需要，可用 --attention-backend 参数手动指定：

# 在线服务
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；
• Intel XPU：FLASH_ATTN、TRITON_ATTN、TRITON_MLA、XPU_MLA_SPARSE、TORCH_SDPA、TURBOQUANT。

特别提醒：预编译的 vLLM wheel 中不包含 FlashInfer，若选择 FLASHINFER 后端必须自行预先安装（参见 FlashInfer 官方文档，或参考仓库 docker/Dockerfile 中的安装方式）。

更深入一步

• 支持的模型列表见 docs/models/supported_models.md，初始化 LLM 或 vllm serve 前可先确认模型架构是否受支持；
• 完整离线推理示例： basic.py、generate.py、chat.py；
• 采样参数的全部字段与校验规则见 vllm/sampling_params.py，LLM 类的全部构造参数见 vllm/entrypoints/llm.py；
• 在线服务更完整的功能（鉴权、多模型、工具调用、结构化输出、指标监控等）可继续阅读 docs/serving 与 docs/features 下的对应文档。