vLLM 快速上手：安装与离线推理

vLLM 的上手路径只有两条：离线批量推理和在线服务。前者适合跑数据、做评测这类一次性任务，后者适合给应用提供常驻接口。官方快速上手文档把两条路各走了一遍，这篇把它整理成可以照做的流程 ^[1]。

安装

前置条件是 Linux 和 Python 3.11 到 3.14；macOS 用户可以走 vLLM-Metal 获得 Apple Silicon 的 GPU 加速，它用 MLX 而不是 PyTorch 做计算后端，模型也要选 mlx-community 的 MLX 优化版 ^[1]。

NVIDIA 显卡用 uv 安装，uv 是速度很快的 Python 环境管理器 ^[1]：

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

最后一行值得单独解释：download-kernels 把预编译内核提前装好，否则 vLLM 会在启动时现下载现编译，在 Hopper 及更新的显卡上能多花好几分钟 ^[1]。--torch-backend=auto 让 uv 检查已装的 CUDA 驱动版本后自动选对应的 PyTorch 索引，要锁特定后端比如 cu126 就显式指定 ^[1]。还有个更轻的玩法：uv run --with vllm 可以不建任何常驻环境直接跑 vllm --help，conda 环境里 pip 装 uv 再用也同样可行 ^[1]。

其他硬件各有通道：AMD ROCm 走 uv 加专用 extra index，目前支持 Python 3.12、ROCm 7.0、glibc 2.35 以上，另有 nightly Docker 镜像；Intel GPU 走 XPU 后端，从 v0.26.0 起随版本发布官方镜像；TPU 装 vllm-tpu 包；昇腾 NPU 走社区维护的 vLLM Ascend 插件 ^[1]。

vLLM 的吞吐优势来自显存管理的思路转变：传统方案按请求预留连续显存，碎片化和浪费严重；PagedAttention 把 KV 缓存切成固定大小的块按需分配，显存利用率上去了，能同时塞进引擎的请求数随之倍增。批量任务恰恰是这套机制的舞台——几十条提示词一次性丢进队列，引擎自己调度，总时长远小于逐条处理。评测跑分、合成数据、批量摘要都适用这个模式。

离线批量推理

离线模式的核心是两个类：LLM 负责跑引擎，SamplingParams 负责采样过程 ^[1]：

from vllm import LLM, SamplingParams

示例定义四个提示词，采样温度 0.8、top_p 0.95 ^[1]：

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)

这里有个容易忽略的默认行为：vLLM 会优先读取 Hugging Face 模型仓库里 generation_config.json 的推荐采样参数——不指定 SamplingParams 时通常直接拿到模型作者调好的值；想强制用 vLLM 自己的默认值，建引擎时传 generation_config="vllm" ^[1]。

示例引擎加载 facebook/opt-125m，这个规格小到任何机器都能跑 ^[1]：

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

模型默认从 Hugging Face 拉取，设环境变量 VLLM_USE_MODELSCOPE=True 则改走 ModelScope ^[1]。generate 把提示词加入引擎等待队列并高吞吐执行，返回 RequestOutput 列表 ^[1]：

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

有个关键的坑要记住：generate 不会自动套聊天模板。拿 Instruct 或 Chat 模型跑 generate，提示词必须先过一遍 tokenizer 的模板，或者改用 llm.chat——它的消息格式与 OpenAI SDK 的 chat.completions 完全一致 ^[1]：

# Using tokenizer to apply 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,
)

# Generate outputs
outputs = llm.generate(texts, sampling_params)

# Print the outputs.
for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

# Using chat interface.
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}")

批量任务的选型逻辑由此清晰：纯补全类任务走 generate 直给提示词，对话类任务走 chat 省去模板处理——两条路径共享同一套引擎和采样体系。

部署形态上有两点值得留意：一个服务实例只托管一个模型，多模型场景要起多个实例分配端口，或者前面加一层路由网关做模型分发；鉴权体系虽简单但够用，多密钥轮换覆盖了大多数运维场景，更复杂的配额、限流、计费则交给外层网关。把 vLLM 当作协议兼容的推理后端、把策略和控制留在网关层，是更清晰的分层。

在线服务

服务模式把 vLLM 变成一个实现 OpenAI 协议的服务器，对已在用 OpenAI API 的应用来说可以直接替换接入点 ^[1]。默认监听 http://localhost:8000，--host 和 --port 可改；一次托管一个模型，提供模型列表、chat completion、completion 三类端点 ^[1]。启动命令 ^[1]：

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

服务端同样有两层默认值：聊天模板用 tokenizer 里预定义的那份；采样参数也优先读模型仓库的 generation_config.json，启动时传 --generation-config vllm 可以关掉后者 ^[1]。先列一下模型确认服务活着 ^[1]：

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

要加鉴权，传 --api-key 或环境变量 VLLM_API_KEY，服务就会校验请求头里的密钥；--api-key 后面可以跟多个密钥，命中任意一个即通过，轮换密钥时不用停服务 ^[1]。

completion 端点的调用 ^[1]：

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
    }'

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)

chat 端点支持多轮往复，历史消息存进对话记录，适合需要上下文的任务 ^[1]：

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?"}
        ]
    }'

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)

后端选择一般交给自动模式就好，有两个例外值得手动干预：一是复现论文或对齐基准时，锁定后端能消除环境变量带来的结果抖动；二是升级版本后发现性能回退，先检查自动选择是否换了后端再找别的原因。后端之间的差异主要体现在长上下文和特定模型架构（如 MLA）上，短上下文的普通对话场景差别不大。

注意力后端

vLLM 在不同硬件上有多个注意力计算后端，默认自动选出与系统和模型匹配的最快实现，必要时用 --attention-backend 手动指定 ^[1]。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 ^[1]。FlashInfer 随 vLLM 一起安装，但预编译内核不包含在内——装完或升级 vLLM 后跑一次 vllm download-kernels，启动时就不用现场编译了 ^[1]。

两条路径的分工最后归拢一下：离线模式吃吞吐，生成即结束，不留常驻开销；在线模式吃并发与协议兼容，接入成本趋近于零。多数项目两条都会用——评测和数据处理在离线侧，产品功能在在线侧。

本文改编自 vLLM 官方文档的 Quickstart 一节^[1]，原文以 Apache-2.0 许可证发布。