vLLM 深度解析：以 PagedAttention 与内核生态构建高吞吐 LLM 推理引擎

本文基于 vLLM 仓库根目录的 README.md 及其关联的设计文档与源码，系统梳理 vLLM 的核心技术主张：PagedAttention 显存管理、连续批处理与 CUDA Graph 执行优化、量化与注意力/GEMM 内核生态、投机解码与分离式（disaggregated）推理，以及多硬件平台支持与 OpenAI 兼容服务体系。读完后，你将能够理解 vLLM 各性能特性的底层实现位置，并掌握从安装到离线推理、在线服务落地的完整路径。

一、vLLM 是什么

vLLM 官方定位为"一个用于 LLM 推理与服务的高吞吐、显存高效的推理引擎"（该描述同时出现在包模块 docstring 中，见 vllm/init.py）。项目最初由 UC Berkeley 的 Sky Computing Lab 开发，如今由来自众多学术机构和公司的社区共同维护，README 中提到的论文引用为：

@inproceedings{kwon2023efficient,
  title={Efficient Memory Management for Large Language Model Serving with PagedAttention},
  author={Woosuk Kwon and Zhuohan Li and Siyuan Zhuang and Ying Sheng and Lianmin Zheng and Cody Hao Yu and Joseph E. Gonzalez and Hao Zhang and Ion Stoica},
  booktitle={Proceedings of the ACM SIGOPS 29th Symposium on Operating Systems Principles},
  year={2023}
}

从仓库结构看，vLLM 由几部分构成：

• 纯 Python 核心包 vllm/：引擎、调度、模型执行、API 入口等；
• C++/CUDA 内核 csrc/：注意力、量化、MoE、采样等算子的底层实现，通过 CMake（CMakeLists.txt）构建；
• 设计文档 docs/design/：架构总览、PagedAttention、CUDA Graph、混合 KV Cache 等原理说明；
• 功能与部署文档 docs/features/、docs/serving/：特性兼容矩阵、推理服务接口、部署方案；
• 示例与基准测试 examples/、benchmarks/：可运行的离线/在线示例及各类内核、端到端基准。

二、性能支柱：README 宣称的"快"从何而来

README 的 "vLLM is fast with" 一节列出了 10 项核心加速手段，下面逐项对照仓库实现展开。

2.1 PagedAttention：KV Cache 的分页管理

PagedAttention 是 vLLM 的标志性设计：借鉴操作系统虚拟内存分页思想，将注意力 KV Cache 切分为固定大小的 block，按需分配而非按序列最大长度预留连续显存，从而显著降低碎片并提高批处理并发能力。仓库中保留了该机制的原理文档 docs/design/paged_attention.md，其中给出了内核级细节：

• 每个 block 存储固定 BLOCK_SIZE 个 token 在单个 head 上的 KV 数据（例如 block size 16、head size 128 时，单 block 单 head 存 2048 个元素）；
• 内核以 k_cache[vllm_paged_attention_block, num_kv_heads, head_size/x, block_size, x] 的布局存储 Key，Value 布局为 [num_blocks, num_kv_heads, head_size, block_size]；
• 通过 thread group、warp、thread block 的三级协作完成 QK 点积、softmax 归一化和 LV 累加，并依赖内存合并（coalescing）提升访存效率。

需要注意：该文档自述是基于原始论文的历史文档，"不再描述当前 vLLM 使用的代码"；今天 vLLM 的注意力后端已扩展为可插拔体系（见下文 2.5），但分页 KV 管理的核心思想依然贯穿 docs/design/paged_attention.md 所描述的 block 分配模型，并在 docs/design/hybrid_kv_cache_manager.md 等文档中继续演进。

2.2 连续批处理、Chunked Prefill 与 Prefix Caching

README 列出"continuous batching of incoming requests, chunked prefill, prefix caching"三项调度层优化：

• 连续批处理（continuous batching）：调度器在每一步（而非每批）决定哪些请求参与执行，使 decode 阶段的新 token 可以立刻加入下一批，提升 GPU 利用率；
• Chunked prefill：将长 prompt 的 prefill 切块，与 decode 请求混合执行，避免长 prompt 独占一步导致延迟尖峰。优化参数说明见 docs/configuration/optimization.md；
• Prefix caching（APC，自动前缀缓存）：跨请求复用相同前缀（如 system prompt、few-shot 示例）已计算的 KV Cache。用法见 docs/features/automatic_prefix_caching.md。

这些特性之间的兼容性可用 docs/features/README.md 中的"特性 × 特性"与"特性 × 硬件"兼容矩阵核对，例如该矩阵标明了 chunked prefill、APC、LoRA、投机解码、CUDA graph 在各 GPU 架构（Volta 到 Hopper、CPU、AMD、Intel GPU）上的支持情况。

2.3 CUDA/HIP Graph：分段与全图执行

README 提到"piecewise and full CUDA/HIP graphs"。源码层面，图捕获相关实现集中在 vllm/compilation/ 目录：

• cuda_graph.py 与 piecewise_backend.py：分别对应全图（full graph）与分段图（piecewise graph）执行模式；
• backends.py 作为 torch.compile 的后端实现，将图分区规则（partition_rules.py）作用于模型编译；
• docs/design/cuda_graphs.md 与 docs/design/torch_compile.md 解释了两者的关系与取舍。

从源码结构看，vLLM 用分段图的方式把不可捕获的动态算子（如 shape 变化的注意力）从图中切出，其余部分捕获为静态图，从而兼顾动态 shape 与低启动开销。

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

README 宣称"Automatic kernel generation and graph-level transformations using torch.compile"。编译子系统 vllm/compilation/ 中还包含 codegen.py（代码生成）、caching.py（编译缓存）、monitor.py（JIT 监控）等模块，docs/contributing/jit_kernel_warmup.md 则说明了 JIT 内核预热问题——这也是 torch.compile 路线需要处理的关键工程点。

2.5 优化后的注意力与 GEMM/MoE 内核

README 点名的内核生态：

• 注意力：FlashAttention、FlashInfer、TRTLLM-GEN、FlashMLA、Triton。CMake 层通过 cmake/external_projects/vllm_flash_attn.cmake、cmake/external_projects/flashmla.cmake、cmake/external_projects/fmha_sm100.cmake 等拉取对应内核仓库；
• GEMM/MoE：CUTLASS、TRTLLM-GEN、CuTeDSL，构建配置见 cmake/external_projects/ 及 csrc/cutlass_extensions/；DeepGEMM 等外部项目的接入脚本在 tools/build_deepgemm_C.py。

对应地，基准脚本 benchmarks/kernels/ 提供了 benchmark_fp8_gemm.py、benchmark_grouped_gemm_cutlass.py、benchmark_moe.py 等大量内核级 benchmark，可用于验证不同精度/硬件下的算子表现。

三、量化：README 清单与仓库实现的对应关系

README 列出的量化清单为：FP8、MXFP8/MXFP4、NVFP4、INT8、INT4、GPTQ/AWQ、GGUF、compressed-tensors、ModelOpt、TorchAO 及更多。功能文档 docs/features/quantization/README.md 及同目录下各格式专页给出了每种格式的使用方式，例如：

• docs/features/quantization/gguf.md、docs/features/quantization/auto_awq.md、docs/features/quantization/gptqmodel.md
• docs/features/quantization/modelopt.md、docs/features/quantization/torchao.md、docs/features/quantization/b12x.md（compressed-tensors）
• docs/features/quantization/quantized_kvcache.md：KV Cache 本身也可量化以降低显存占用
• docs/features/quantization/online.md：在线量化

C++ 侧的量化算子实现位于 csrc/quantization/ 与 csrc/libtorch_stable/quantization/（后者包含数十个 .cu/.cuh 文件，覆盖 W8A8、GPTQ、AWQ、FP8/NVFP4 等路径），其中 csrc/quantization/w8a8/ 专门放置 W8A8 整数量化内核。基准工具 benchmarks/benchmark_quant.py 与 tests/quantization/（36 个测试文件）则构成量化正确性与性能的验证层。

四、投机解码与分离式推理

4.1 投机解码方法族

README 提到"Speculative decoding including n-gram, suffix, EAGLE, DFlash"。docs/features/speculative_decoding/README.md 给出了更完整的方法清单与选型表：EAGLE、Multi-Token Prediction（MTP）、Draft Model、Parallel Draft Model（PARD）、MLP speculator、N-Gram、Suffix Decoding、Custom Proposer（实验性）、Dynamic Speculative Decoding、Adaptive Verification。文档以 QPS 为维度给出定性选型表：低 QPS 关注延迟时 EAGLE/MTP/草稿模型收益最高，高 QPS 关注吞吐时 n-gram/suffix 等轻量方法不会在峰值流量下增加额外草稿开销。

各方法均有独立专页：eagle.md、mtp.md、n_gram.md、suffix.md、dynamic_speculative_decoding.md（README 中提到的 DFlash 即在此动态投机解码文档中作为动态方法出现）。CLI 侧通过 --speculative-config 传 JSON 配置，且支持 method = "custom_class" 挂载自定义 proposer 类（需接受 VllmConfig 并实现 propose 方法）。可复现实验脚本见 examples/features/speculative_decoding/spec_decode_offline.py。

4.2 分离式 prefill / decode / encode

README 提到"Disaggregated prefill, decode, and encode"。仓库中的用户指南是 docs/features/disagg_prefill.md（PD 分离）与 docs/features/disagg_encoder.md（编码器分离），示例脚本位于 examples/disaggregated/disaggregated_serving/ 与 examples/disaggregated/disaggregated_encoder/，并集成 Mooncake、NIXL、LMCache 等 KV 传输方案（如 docs/features/mooncake_connector_usage.md、docs/features/nixl_connector_usage.md）。

五、模型支持：200+ 架构与双建模后端

README 声称"vLLM seamlessly supports 200+ model architectures on Hugging Face"，覆盖五类模型：

类别	代表模型
纯解码器 LLM	Llama、Qwen、Gemma
MoE LLM	Mixtral、DeepSeek-V3、Qwen-MoE、GPT-OSS
混合注意力/状态空间模型	Mamba、Qwen3.5
多模态模型	LLaVA、Qwen-VL、Pixtral
嵌入/检索与奖励/分类模型	E5-Mistral、GTE、ColBERT、Qwen-Math

docs/models/supported_models.md 提供了按任务划分的完整架构清单。仓库支持两种建模后端：

1. vLLM 原生实现：位于 vllm/model_executor/models/，该目录包含 700+ Python 实现文件与 570+ 模型配置 JSON；
2. Transformers modeling backend：直接复用 Hugging Face Transformers 的建模代码，文档称其性能"应与专用 vLLM 实现一致"，且兼容 vLLM 全特性矩阵以及 DP/TP/EP/PP 任意组合的并行方案。用户可通过离线推理 model_impl="transformers" 或在线服务 --model-impl transformers 强制切换到该后端。

所有模型构造函数统一为 __init__(self, *, vllm_config: VllmConfig, prefix: str = "") 的关键字参数签名，这一设计出自 docs/design/arch_overview.md 的类层次设计章节：统一构造签名让模型运行器无需感知具体模型类型即可实例化模型，也便于视觉-语言模型的组合；而张量并行切分与量化在初始化阶段（而非加载后）完成，避免"整卡加载 810GB 权重再切分"的显存浪费。

六、硬件平台与分布式并行

README 声明支持"NVIDIA GPUs, AMD GPUs, Intel GPUs, and x86/ARM/PowerPC CPUs"，并列举 TPU、Intel Gaudi、IBM Spyre、华为 Ascend、Rebellions NPU、Apple Silicon、MetaX GPU 等硬件插件。仓库内 vllm/platforms/ 目录体现了内置平台的划分：

• cuda.py：NVIDIA CUDA 平台
• rocm.py：AMD ROCm 平台
• xpu.py：Intel GPU（XPU）平台
• tpu.py：Google TPU 平台
• cpu.py 与 zen_cpu.py：x86/ARM CPU 及 AMD Zen CPU 路径
• interface.py：平台抽象接口

C++ 侧则对应 csrc/cpu/（含 AMX/NEON/RVV/VSX 等多 ISA 的 CPU 注意力实现与 sgl-kernels）与 csrc/rocm/（AMD RDNA 系列量化 GEMM 内核）。Docker 镜像矩阵在 docker/ 下按平台拆分（Dockerfile、Dockerfile.rocm、Dockerfile.tpu、Dockerfile.xpu、Dockerfile.cpu、Dockerfile.ppc64le 等），版本清单见 docker/versions.json。

分布式推理方面，README 列出 Tensor、Pipeline、Data、Expert、Context 五种并行。仓库文档对应 docs/serving/parallelism_scaling.md（TP/PP 扩展）、docs/serving/data_parallel_deployment.md（DP）、docs/serving/expert_parallel_deployment.md（EP，面向 MoE）与 docs/serving/context_parallel_deployment.md（CP）。通信算子实现在 vllm/distributed/（150+ 文件）及 csrc/custom_all_reduce.cu、csrc/custom_all_gather_reduce_scatter.cu 等自研集合通信内核中，其基准工具为 benchmarks/kernels/benchmark_device_communicators.py。

七、服务化能力：从 OpenAI 兼容 API 到结构化输出

README 的功能清单中服务相关条目包括：多种解码算法（parallel sampling、beam search）、流式输出、xgrammar/guidance 结构化输出、tool calling 与 reasoning 解析器、OpenAI 兼容 API + Anthropic Messages API + gRPC、多 LoRA 支持。对照仓库文档：

• 在线服务接口全集：docs/serving/online_serving/README.md 列出 OpenAI 系 API（/v1/completions、/v1/chat/completions、/v1/chat/completions/batch、/v1/responses、/v1/embeddings、音频 /v1/audio/transcriptions|translations）、Anthropic Messages API（/v1/messages）、Cohere Embed/Rerank API、以及 Pooling/Classification/Score 等自定义 API；
• 结构化输出：docs/features/structured_outputs.md，基准见 benchmarks/benchmark_serving_structured_output.py；
• 工具调用与推理解析：vllm/tool_parsers/（50+ 解析器实现）与 vllm/reasoning/（30+ 推理解析器实现），功能文档见 docs/features/tool_calling.md 与 docs/features/reasoning_outputs.md；
• 多 LoRA：docs/features/lora.md，实现在 vllm/lora/（40+ 文件，覆盖 dense 与 MoE 层），基准 benchmarks/kernels/benchmark_lora.py；
• 离线推理：docs/serving/offline_inference.md，示例 examples/basic/offline_inference/。

API 服务端的进程架构见 docs/design/arch_overview.md：V1 采用多进程模型，默认 1 个 API Server 进程（数据并行时随 DP 数扩展，可用 --api-server-count 配置）+ 每个 DP rank 1 个 Engine Core 进程 + 每 GPU 1 个 Worker 进程 +（DP>1 时）1 个 DP Coordinator，进程间通过 ZMQ 通信。该文档还给出进程数公式：A + DP + N（DP>1 时再加 1），例如 4 卡 vllm serve -tp=4 共 6 个进程，8 卡 -tp=2 -dp=4 共 17 个进程——这是做 CPU 资源规划的直接依据。

八、快速上手：安装、离线推理与在线服务

8.1 安装

README 给出的最小安装命令为：

uv pip install vllm

docs/getting_started/quickstart.md 给出了完整前置条件与分平台命令。前置条件为 Linux + Python 3.10–3.13（Apple Silicon 可经 vLLM-Metal 项目在 macOS 运行）。NVIDIA CUDA 平台推荐流程：

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

其中 --torch-backend=auto 让 uv 依据已安装 CUDA 驱动版本自动选择 PyTorch index（也可显式指定 cu126 等）。无需常驻环境时可 uv run --with vllm vllm --help 直接执行。AMD ROCm、Intel XPU、Google TPU 平台分别有独立的安装分支（ROCm 需额外 wheel index 与 glibc ≥ 2.35 等前提；XPU 提供官方 Docker 镜像；TPU 安装 vllm-tpu 包），细节见同一 quickstart 文档。开发场景可 从源码构建，仓库构建体系为 CMake（CMakeLists.txt）+ setuptools（setup.py）+ Rust 组件（rust/）。

8.2 离线批处理推理

docs/design/arch_overview.md 中给出的标准用法（可直接运行）：

from vllm import LLM, SamplingParams

prompts = [
    "Hello, my name is",
    "The capital of France is",
    "The largest ocean 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}")

从源码结构看，LLM、SamplingParams、EngineArgs 等公开 API 在 vllm/init.py 中通过 MODULE_ATTRS 映射做惰性导入（如 LLM 实际解析到 vllm.entrypoints.llm），LLM 类实现即 vllm/entrypoints/llm.py。

8.3 在线服务

启动一条命令：

vllm serve <model>

CLI 入口在 vllm/entrypoints/cli/main.py。启动后可直接调用第 7 节列出的 /v1/chat/completions 等端点；完整参数说明见 docs/serving/online_serving/openai_compatible_server.md，生产部署可参考 docs/serving/nginx.md、docs/serving/k8s.md 以及 examples/deployment/chart-helm/ 下的 Helm Chart。

九、工程验证：测试与基准体系

README 中每一项宣称在仓库中都有对应的验证资产，这也是判断 vLLM 能力边界的可靠方式：

• 内核级：tests/kernels/（270 个测试）与 benchmarks/kernels/（60+ benchmark 脚本）逐一对应 csrc 内核；
• 端到端：tests/v1/（400+ 测试文件）覆盖 V1 引擎、调度、KV Cache、入口点；
• 模型正确性：tests/models/（230 个文件）逐模型验证；
• 分布式：tests/distributed/（58 个文件）验证 TP/PP/DP 语义一致性；
• 基准入口：benchmarks/benchmark_latency.py、benchmark_throughput.py、benchmark_serving.py 三大标准脚本，CLI 用法见 docs/benchmarking/cli.md。

十、贡献与引用

README 指向的贡献文档为 docs/contributing/（含 CI 说明、开发 Dockerfile、模型添加指南等），代码贡献规范见 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md；仓库另设有 AGENTS.md 为 AI 辅助开发提供约定。联系方式方面，README 建议：技术问答与功能请求走 GitHub Issues，用户交流用 vLLM 官方论坛，贡献协调用官方 Slack，安全漏洞走 GitHub Security Advisories，合作事宜联系官方协作邮箱。若将 vLLM 用于研究，请引用上文第二节给出的 SOSP 2023 论文 bibtex。

小结

vLLM 的技术轮廓可以概括为三层：显存层用 PagedAttention 分页 KV Cache 释放批处理上限；执行层用连续批处理 + chunked prefill + prefix caching 的调度策略，叠加 CUDA/HIP graph 与 torch.compile 图变换，以及 FlashAttention/FlashInfer/CUTLASS 等成熟内核生态；服务层提供 OpenAI 兼容 + Anthropic Messages + gRPC 的多协议 API、结构化输出、工具调用解析与多 LoRA，并通过 TP/PP/DP/EP/CP 与 PD/Encoder 分离在异构硬件上水平扩展。仓库中每一层主张都能在 vllm/、csrc/、docs/design/、benchmarks/ 中找到对应源码与验证脚本，便于读者按本文路径继续深入。