vLLM 技术指南：高吞吐 LLM 推理与服务引擎的能力全景与快速上手实践

本文以 vLLM 官方文档首页（docs/README.md）为核心骨架，系统梳理 vLLM 作为"快速、易用、低成本"的 LLM 推理与服务引擎所宣称的完整技术能力清单，并结合仓库中的实际源码（CLI 入口、离线推理类、在线服务子命令、Attention 后端实现等）逐条印证这些能力的落地位置。读完本文后，你将掌握：vLLM 的性能加速手段与灵活服务特性各自对应仓库中的哪些模块、不同角色用户（使用者/开发者/贡献者）的推荐入手路径，以及离线批量推理与在线 OpenAI 兼容服务的可复制启动方式。

一、项目定位：面向 LLM 的高吞吐推理与服务引擎

vLLM 官方文档首页将其定位为一句话："vLLM is a fast and easy-to-use library for LLM inference and serving"（docs/README.md）。项目最初诞生于 UC Berkeley 的 Sky Computing Lab，后发展为由来自数十家学术机构与公司的社区共同维护的开源项目，贡献者超过 2000 人（README.md）。其 Slogan 为 "Easy, fast, and cheap LLM serving for everyone"。

从文档首页给出的信息结构看，vLLM 的技术叙事围绕三条主线展开：

1. 快（fast）——一系列推理引擎层面的性能优化技术；
2. 灵活易用（flexible and easy to use）——面向应用层的 API、并行策略与硬件生态；
3. 模型覆盖面广——支持 Hugging Face 上 200 余种模型架构，涵盖纯解码器 LLM、MoE 模型、混合注意力/状态空间模型、多模态模型、Embedding/检索模型以及奖励/分类模型（docs/README.md）。

文档首页按用户类型给出了三条不同的起步路径（docs/README.md）：

你的目标	推荐起点	对应文档
在 vLLM 上运行开源模型	Quickstart Guide	docs/getting_started/quickstart.md
用 vLLM 构建应用	User Guide	docs/usage/README.md
构建/开发 vLLM 本身	Developer Guide	docs/contributing/README.md

此外，项目还支持通过 docs/models/supported_models.md 查询完整的受支持模型列表。以下章节将围绕文档首页列出的能力清单，逐条给出仓库中的实现落点与实操方式。

二、为什么快：性能能力清单及其在仓库中的落点

文档首页"vLLM is fast with"一节列出了九类加速能力（docs/README.md）。下面按这一清单逐一展开，并标注每条能力在源码中的对应位置。

2.1 PagedAttention：KV Cache 的分页内存管理

PagedAttention 是 vLLM 的核心技术：通过借鉴操作系统虚拟内存分页的思想来高效管理注意力的 Key/Value 显存，减少 KV Cache 的内存碎片与浪费。相关设计文档见 docs/design/paged_attention.md，架构总览见 docs/design/arch_overview.md。从仓库结构看，KV Cache 相关的内核实现位于 csrc/libtorch_stable/（如 cache_kernels.cu、cache_kernels_fused.cu），缓存抽象层位于 vllm/v1/ 目录下。

2.2 持续批处理、分块预填充与前缀缓存

• Continuous batching：对到达的请求做连续批处理，新请求可随时加入/退出批次，是吞吐提升的关键调度机制；
• Chunked prefill：将长提示的预填充阶段分块执行，与解码请求混合调度，改善长文本场景下的时延表现；
• Prefix caching：复用相同前缀的 KV Cache，避免重复计算。

调度与缓存的设计文档分别为 docs/design/hybrid_kv_cache_manager.md 和 docs/features/automatic_prefix_caching.md。前缀缓存的哈希计算与块池机制还有专门的基准脚本可参考：benchmarks/benchmark_prefix_block_hash.py、benchmarks/benchmark_block_pool.py。

2.3 CUDA/HIP Graphs：分段与整图捕获

通过 CUDA Graph（AMD 平台为 HIP Graph）捕获模型执行图，消除 CPU 侧的 kernel 启动开销，且支持分段（piecewise）与整图（full）两种粒度。设计文档为 docs/design/cuda_graphs.md，多模态场景下的整图方案见 docs/design/cuda_graphs_multimodal.md。

2.4 量化：从 FP8 到 INT4 的多精度支持

文档首页列出的量化方案包括：FP8、MXFP8/MXFP4、NVFP4、INT8、INT4、GPTQ/AWQ、GGUF、compressed-tensors、ModelOpt、TorchAO 等。各量化方案的文档位于 docs/features/quantization/ 目录（18 篇量化特性文档）；对应的量化内核实现分布在 csrc/libtorch_stable/quantization/ 与 csrc/libtorch_stable/moe/ 中，可按目录中的 *.cu/*.cuh 文件核对具体算子。

2.5 优化过的 Attention 内核与后端自动选择

文档首页指出 vLLM 提供 FlashAttention、FlashInfer、TRTLLM-GEN、FlashMLA、Triton 等多种优化 Attention 内核，并且会自动选择与当前系统和模型规格兼容的最高性能后端。从源码结构看，这一"后端注册 + 自动选择"机制的落点是 vllm/v1/attention/backends/ 目录：

• flash_attn.py、flashinfer.py：NVIDIA CUDA 上的主力后端；
• triton_attn.py、triton_attn_diffkv.py：跨平台的 Triton 实现；
• rocm_attn.py、rocm_aiter_fa.py、rocm_aiter_unified_attn.py：AMD ROCm 后端；
• mla/ 子目录：MLA（Multi-head Latent Attention）类模型专用后端；
• mamba1_attn.py、mamba2_attn.py、linear_attn.py、gdn_attn.py 等：面向状态空间与线性注意力模型的专用后端；
• b12x.py、xpu 相关后端与 turboquant_attn.py：Intel XPU 平台选项；
• cpu_attn.py、flex_attention.py：CPU 与 PyTorch FlexAttention 路径。

用户也可通过 --attention-backend 参数手动指定后端（详见 5.3 节）。相关的设计说明见 docs/design/attention_backends.md，Attention 基准测试配置在 benchmarks/attention_benchmarks/。

2.6 GEMM/MoE 内核：CUTLASS、TRTLLM-GEN 与 CuTeDSL

不同精度下的矩阵乘与 MoE 计算使用了 CUTLASS、TRTLLM-GEN、CuTeDSL 等工具链优化的内核。仓库中对应的基础设施包括：

• csrc/cutlass_extensions/ 与 cmake/external_projects/（如 qutlass.cmake、deepgemm.cmake、flashmla.cmake），用于在构建期集成这些第三方计算库；
• MoE 内核的基准脚本，如 benchmarks/kernels/benchmark_moe.py、benchmarks/kernels/benchmark_block_fp8_gemm.py、benchmarks/kernels/benchmark_nvfp4_gemm.py，可用来核对各精度 GEMM/MoE 的实际调用方式；
• 模块化 MoE 内核设计文档见 docs/design/fused_moe_modular_kernel.md。

2.7 投机解码：n-gram、suffix、EAGLE、DFlash

vLLM 支持多种投机解码（speculative decoding）策略以降低解码时延。特性文档位于 docs/features/speculative_decoding/（13 篇专题文档），对应的示例脚本在 examples/features/speculative_decoding/，示例代码中可看到各方案的启动参数写法。

2.8 torch.compile：自动内核生成与图级变换

通过 PyTorch 的 torch.compile 机制实现自动内核生成与图级变换优化。设计文档为 docs/design/torch_compile.md，调试相关说明见 docs/design/debug_vllm_compile.md，编译行为的功能验证集中在 tests/compile/（65 个测试文件）。

2.9 分离式（Disaggregated）预填充、解码与编码

将 prefill、decode、encode 阶段部署到不同的实例上执行，以隔离计算特性、提升资源利用率。特性文档为 docs/features/disagg_prefill.md 与 docs/features/disagg_encoder.md；KV Cache 在节点间传输依赖各类 connector（NIXL、Mooncake、LMCache 等），对应文档见 docs/features/nixl_connector_usage.md、docs/features/mooncake_connector_usage.md，可运行的示例脚本位于 examples/disaggregated/ 目录（含 lmcache/、mooncake_connector/、example_connector/ 等子目录）。

三、灵活易用：服务层能力清单及其源码落点

文档首页"vLLM is flexible and easy to use with"一节列出九类能力（docs/README.md），逐条对应如下：

3.1 Hugging Face 模型无缝集成与 200+ 模型架构

模型实现集中在 vllm/models/（264 个 Python 文件），覆盖文档首页列举的各类架构：纯解码器 LLM（Llama、Qwen、Gemma 等）、MoE LLM（Mixtral、DeepSeek-V3、Qwen-MoE、GPT-OSS 等）、混合注意力与状态空间模型（Mamba、Qwen3.5 等）、多模态模型（LLaVA、Qwen-VL、Pixtral 等）、Embedding/检索模型（E5-Mistral、GTE、ColBERT 等）、奖励与分类模型（Qwen-Math 等）。HF 集成的机制说明见 docs/design/huggingface_integration.md。

3.2 多种解码算法与流式输出

除默认采样外，支持并行采样（parallel sampling）、beam search 等多种解码算法，以及流式输出。beam search 的离线入口是 LLM 类混入的 BeamSearchOfflineMixin（见 vllm/entrypoints/llm.py）；采样参数（temperature、top_p、top_k 等）的完整定义见 vllm/sampling_params.py。

3.3 张量/流水线/数据/专家/上下文并行

支持 tensor、pipeline、data、expert、context 多种并行策略用于分布式推理。部署指南分别位于 docs/serving/data_parallel_deployment.md、docs/serving/expert_parallel_deployment.md、docs/serving/context_parallel_deployment.md，并行与扩展的总览见 docs/serving/parallelism_scaling.md。在线服务侧对这些并行模式的进程编排逻辑（如数据并行下的多 API server 数量默认值）可在 vllm/entrypoints/cli/serve.py 中核对。

3.4 结构化输出：xgrammar 与 guidance

支持使用 xgrammar 或 guidance 生成约束格式的结构化输出。特性文档为 docs/features/structured_outputs.md，示例与 schema 位于 examples/features/structured_outputs/，离线与在线两条路径的演示脚本均可直接复制使用。

3.5 工具调用与推理（Reasoning）解析器

内置 tool calling 与 reasoning 解析器：

• 工具调用解析器实现位于 vllm/tool_parsers/（52 个解析器文件），示例脚本见 examples/tool_calling/ 与 examples/features/structured_outputs/；
• 推理内容（thinking/reasoning 块）的解析实现位于 vllm/reasoning/，对应测试在 tests/reasoning/ 与 tests/parser/。

3.6 OpenAI 兼容 API、Anthropic Messages API 与 gRPC

API 服务入口的源码布局清晰地体现了这三条协议路径：

• OpenAI 兼容服务：vllm/entrypoints/openai/，含 completions、chat completions 等路由；
• Anthropic Messages API：vllm/entrypoints/anthropic/serving.py 与 vllm/entrypoints/anthropic/api_router.py；
• gRPC 服务：vllm/entrypoints/grpc_server.py，由 vllm serve --grpc 触发（见 vllm/entrypoints/cli/serve.py）。

在线服务的完整使用文档在 docs/serving/ 目录，包括离线推理（docs/serving/offline_inference.md）与在线服务（docs/serving/online_serving/）。

3.7 高效多 LoRA 支持

支持在稠密层与 MoE 层上同时挂载多个 LoRA 适配器。实现位于 vllm/lora/（43 个文件），特性文档为 docs/features/lora.md，离线与在线 LoRA 示例见 examples/features/lora/。

3.8 硬件支持：NVIDIA/AMD GPU、CPU 与硬件插件

文档首页声明支持 NVIDIA GPU、AMD GPU 以及 x86/ARM/PowerPC CPU，另有 Google TPU、Intel Gaudi、IBM Spyre、Huawei Ascend、Rebellions NPU、Apple Silicon、MetaX GPU 等硬件插件生态。从源码结构看，平台抽象层位于 vllm/platforms/，包含 cuda.py、rocm.py、cpu.py、xpu.py、tpu.py、zen_cpu.py 等平台实现，统一接口为 interface.py。安装路径按硬件区分：NVIDIA/AMD/XPU/TPU/Ascend/Apple Silicon 的具体安装命令见 docs/getting_started/quickstart.md 的安装章节，各平台 Docker 镜像定义在 docker/ 目录（Dockerfile、Dockerfile.rocm、Dockerfile.xpu、Dockerfile.tpu 等），CI 使用的版本矩阵见 docker/versions.json。

四、快速上手：离线批量推理

文档首页推荐"运行开源模型"的用户从 Quickstart 入手（docs/getting_started/quickstart.md）。前置条件为 Linux 系统与 Python 3.10–3.13；NVIDIA GPU 环境推荐用 uv 安装：

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

离线推理的核心是 LLM 与 SamplingParams 两个类（vllm/entrypoints/llm.py）。从 LLM 类的 docstring 可以看到，它"包含一个 tokenizer、一个语言模型（可分布在多张 GPU 上）、以及为中间状态（即 KV cache）预留的 GPU 显存"，这正是 PagedAttention 与持续批处理机制的类级入口。完整示例脚本为 examples/basic/offline_inference/basic.py：

from vllm import LLM, SamplingParams

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 = LLM(model="facebook/opt-125m")
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}")

使用上有三个容易踩坑的细节，Quickstart 文档均明确提示（docs/getting_started/quickstart.md）：

1. 默认采样参数来自模型仓库：若 Hugging Face 模型仓库中存在 generation_config.json，vLLM 默认采用模型作者推荐的采样参数；若想强制使用 vLLM 自身默认值，创建实例时设置 generation_config="vllm"。
2. generate 不会自动套 chat template：对 Instruct/Chat 模型，需手动用 AutoTokenizer.apply_chat_template 渲染对话模板，或直接改用 llm.chat(messages_list, sampling_params)，其消息格式与 OpenAI client.chat.completions 的 messages 相同。
3. 模型来源：默认从 Hugging Face 下载；如需从 ModelScope 下载，在初始化引擎前设置环境变量 VLLM_USE_MODELSCOPE=True。环境变量的全集可在 docs/configuration/env_vars.md 与 vllm/envs.py 中查询。

LLM 类还通过混入（mixin）扩展了 beam search、pooling（嵌入/分类/打分）等离线能力，见 vllm/entrypoints/llm.py 的类定义；pooling 模型的示例脚本在 examples/pooling/（embed/、score/、classify/、reward/ 等子目录）。

五、快速上手：在线 OpenAI 兼容服务

5.1 启动服务

一行命令即可启动默认监听 http://localhost:8000 的 API 服务器：

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

可用 --host 与 --port 修改监听地址；传入 --api-key（支持多个，便于轮换）或环境变量 VLLM_API_KEY 后，服务器会校验请求头中的 API key。

从源码看，serve 是 vllm CLI 的一个子命令，CLI 顶层命令由 vllm/entrypoints/cli/main.py 注册，包括 openai（serve 的别名）、serve、launch、benchmark、collect_env、run_batch。serve 子命令的核心处理逻辑在 vllm/entrypoints/cli/serve.py：它会解析 --grpc（切换到 gRPC 服务）、--headless（无 API server 模式）、--api-server-count（多 API server 进程，配合数据并行/负载均衡模式）等选项，最终通过 run_server/run_multi_api_server/run_headless 三条路径拉起引擎与前端进程。vllm serve 的完整参数分组可用 vllm serve --help=<ConfigGroup>（如 --help=ModelConfig）或 --help=all 查看，这一提示就写在子命令的 DESCRIPTION 中（vllm/entrypoints/cli/serve.py）。

另一个与离线侧一致的行为值得注意：服务器默认也会应用 Hugging Face 模型仓库中的 generation_config.json；如需禁用，启动时传 --generation-config vllm。

5.2 调用三个核心端点

列出模型：

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

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

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 API 协议，任何使用 OpenAI SDK 的应用只需改 base_url 即可切换到 vLLM：

from openai import OpenAI

client = OpenAI(
    api_key="EMPTY",
    base_url="http://localhost:8000/v1",
)
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(response)

更细粒度的端点行为（流式、n、logprobs、chat template 覆盖等）可查 docs/serving/online_serving/ 目录下的专题文档，服务端的协议实现位于 vllm/entrypoints/openai/。

5.3 手动选择 Attention 后端

默认情况下引擎自动选择兼容且高性能的后端；如需手动指定，使用 --attention-backend（在线服务参数或离线脚本参数均可），Quickstart 文档给出的部分可用选项（docs/getting_started/quickstart.md）：

# 在线服务
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/v1/attention/backends/ 目录下的后端模块一一对应。文档同时警告：预编译的 vLLM wheel 不包含 Flash Infer，需先自行安装（安装方式可参考 docker/Dockerfile）。

六、延伸路径：文档、测试与基准测试的组织方式

以 docs/README.md 为起点，仓库中各能力均有对应的"文档 + 源码 + 测试/基准"三件套，建议按主题追踪：

• 配置与调优：docs/configuration/（引擎参数、内存节省、环境变量、优化）；
• 设计文档：docs/design/（架构总览、PagedAttention、CUDA graphs、torch.compile、MoE 内核等 30 余篇）；
• 特性文档：docs/features/（前缀缓存、结构化输出、LoRA、投机解码、分离式推理等）；
• 基准测试：根目录 benchmarks/（benchmark_throughput.py、benchmark_latency.py、benchmark_serving.py 等）与内核级 benchmarks/kernels/（近 80 个内核基准脚本）；
• 功能测试：tests/（含 tests/kernels/、tests/v1/ 共四百余个测试文件）。

社区与开发流程方面，贡献指南在 docs/contributing/，治理与协作规范在 docs/governance/，社区活动信息在 docs/community/meetups.md。

适用前提与限制：本文所有结论均基于当前仓库（vLLM main 分支快照）中的文档与源码；各硬件平台的预编译 wheel 支持范围（如 ROCm 版当前支持 Python 3.12、ROCm 7.0、glibc >= 2.35）以 docs/getting_started/quickstart.md 安装章节的当前标注为准，具体版本的兼容性请以实际发行说明核对。