vLLM 解决的所有问题，根源都在 Transformer 自回归推理的两个物理事实：生成是逐 token 的，以及历史计算结果（KV cache）必须留在显存里。本章把这两件事从公式到硬件彻底讲透——后面五章的每个设计决策都会回指到这里。

1.1自回归生成：prefill 与 decode

LLM 生成文本的过程是：把整段 prompt 算一遍得到第一个新 token，再把这个新 token 喂回去得到下一个……直到遇到停止符。这个循环天然分成两个性质完全不同的阶段：

• Prefill（预填充）：prompt 的所有 token 一次性并行通过模型。计算量大、并行度高，通常是 compute-bound（算力受限），决定了首 token 延迟 TTFT。
• Decode（解码）：每一步只处理 1 个新 token，但要读取全部模型权重和整段 KV cache。计算量小、访存量大，是 memory-bound（带宽受限），决定了 token 间延迟 ITL。

1.1.1为什么 prefill 能并行、decode 不能

回忆 attention 的计算：每个位置的输出是 softmax(QKᵀ/√d)·V，配合因果掩码（causal mask）——位置 t 只能看见 ≤ t 的 token。关键在于：prompt 里每个 token 要看的内容都已经在手上，所以整段 prompt 的 Q、K、V 可以拼成大矩阵一次算完，矩阵乘的形状是 [T×d] @ [d×T]，GPU 吃得很饱。而生成阶段，第 t+1 个 token 依赖第 t 个 token 的采样结果——数据依赖是串行的，每一步只能做 [1×d] 的矩阵-向量乘（GEMV），GPU 的并行度用不上。

这条「串行依赖」正是第 4 章投机解码要攻击的目标：既然依赖链断不开，那就先猜出几个 token，再用一次并行前向去验证。

1.1.2decode 为什么是 memory-bound：一笔粗账

生成 1 个 token，需要把全部权重从显存搬进计算单元（8B 模型 FP16 权重约 16 GB），而这个 token 引发的浮点运算约为 2 × 参数量 = 16 GFLOPs（每个参数一次乘一次加）。H100 每秒能做约 990 TFLOPS、搬 3.35 TB——也就是每搬 1 字节能做约 295 次运算，而 batch=1 的 decode 每搬 1 字节只做约 1 次运算。时间全花在「搬数据」上，算力闲置 99% 以上。

1.2KV cache：由来、大小与 GQA/MLA 演进

1.2.1为什么必须缓存 K 和 V

attention 要求每个新 token 与之前所有 token 的 Key/Value 做运算。如果不缓存，生成第 t 个 token 就要把前 t-1 个 token 全部重算一遍，整段生成的总计算量是 O(T²) 次完整前向——完全不可行。于是引擎把每层算出的 K、V 张量存下来复用，代价从「重算」变成「存储」：KV cache 是拿显存换计算的经典 trade-off。注意只缓存 K、V 而不缓存 Q——因为历史 token 的 Q 之后再也用不到（未来的 token 用自己的 Q 来查历史的 K/V）。

1.2.2大小公式与计算器

以 Llama-3.1-8B（32 层、8 个 KV head、head_dim 128、FP16）为例：2 × 32 × 8 × 128 × 2 = 128 KB/token。一条 8K 上下文的请求就要 1 GB。KV cache 是推理服务的第二大显存开销，且随并发线性增长——它就是并发能力的天花板。

1.2.3模型侧的自救：MHA → MQA → GQA → MLA

KV cache 太贵，模型结构本身也在进化以缩小它。这条演进线值得记住，因为它解释了为什么现代模型的 num_kv_heads 远小于 num_heads，也解释了 DeepSeek 系列为什么能把超长上下文做便宜：

1.3GPU 体系结构速成

读 vLLM 的日志、文档和 kernel 代码，绕不开这些硬件概念。不需要会写 CUDA，但每个词都要能对上一个物理位置——先看一张地图：

1.3.1芯片鸟瞰：SM、显存与互联

执行模型三层楼：CPU 发射一个 kernel → kernel 由成千上万个线程组成，按 block（线程块）为单位分派到各 SM → 每个 block 内的线程按 32 个一组（warp）在 SIMT 模式下同步执行——同一 warp 的 32 个线程每拍执行同一条指令，只是操作不同数据。写 GPU 程序的本质就是把问题切成「几千个可以并行的小块」；矩阵乘天然适配（每个输出 tile 一个 block），而 decode 的逐 token 循环不适配——这就是 1.1 节「并行度用不上」的硬件语言版本。

1.3.2显存层级与合并访问

图右下的速度阶梯是所有 kernel 优化的地形图：寄存器 → shared memory → L2 → HBM，每下一级带宽掉几倍、延迟涨几倍。两个推理相关的直接推论：

• 数据复用是第一美德：一个数从 HBM 搬上来，能用几次就用几次再丢。矩阵乘的 tile 化、FlashAttention 的分块（4.3 节）都是在最大化「每字节复用次数」——这正是 roofline 横轴的物理含义。
• 合并访问（coalescing）：HBM 按 128 字节的事务读写。一个 warp 的 32 个线程若访问连续地址，硬件合并成几次大事务；若地址零散，同样的数据量要拆成几十次事务，有效带宽掉一个量级。这解释了为什么 KV cache 的 block 内布局要精心设计（token 连续、head 连续），也解释了 PagedAttention「按块寻址」为什么能做到几乎不损性能——块内仍是连续的。

1.3.3Tensor Core：算力的附加条件

H100 的 990 TFLOPS 几乎全部来自 Tensor Core——它每拍完成一个小矩阵乘累加（MMA，如 16×8×16 的 tile），而普通 CUDA core 一拍只做一次乘加，两者算力差约 15 倍。但 Tensor Core 有附加条件：输入必须组织成矩阵 tile。prefill 的大矩阵乘完美适配；batch=1 的 decode 是矩阵-向量乘（GEMV），凑不满 tile 的行维，Tensor Core 大量空转——所以「decode 吃不满算力」在硬件层面是双重的：既缺带宽，又缺可用的矩阵形状。batch 增大同时缓解这两件事。另外 Tensor Core 对低精度有硬件倍率：FP8 吞吐是 BF16 的 2 倍（Blackwell 的 FP4 再翻倍）——4.2 节激活量化的加速收益直接来自这里。

1.3.4延迟隐藏与 kernel 发射

GPU 不靠缓存命中来掩盖 HBM 的 ~500 周期延迟，而是靠超额并发：每个 SM 上驻留几十个 warp，谁的数据到了就执行谁（图中的 warp scheduler 每拍挑选），访存延迟被计算「织」进去。这要求 kernel 有足够的并行度（occupancy）——又一次指向「batch 要大」。最后一个数字：CPU 发射一个 kernel 约 5~10 微秒，一个 decode step 要发几百个 kernel；当 batch 小、每个 kernel 只算几十微秒时，CPU 发射速度追不上 GPU 消化速度，GPU 反过来等 CPU——这是第三种瓶颈（launch-bound），第 4 章的 CUDA Graph 专治它。

1.4Roofline 模型与每 token 的性能账

把 1.1 的粗账正式化。任何一段计算都有一个操作强度（arithmetic intensity）：每从显存搬 1 字节能做多少次浮点运算。把它画在横轴、把实际性能画在纵轴，就是 roofline 模型——性能要么撞上斜线（带宽顶）、要么撞上平线（算力顶）：

1.4.1为什么增大 batch「几乎不伤」延迟

decode 时权重搬运是固定成本：batch=1 和 batch=32 都要把 16 GB 权重完整读一遍。batch 增大后同一次搬运摊到更多请求头上——吞吐近似线性上涨，而单步时间在带宽吃满前几乎不变，每个用户感受到的 ITL 只轻微上升。推理服务的核心游戏：在显存装得下的前提下，把 batch 推到尽可能大。显存里最有弹性的正是 KV cache，于是「如何高效管理 KV cache」成了主战场——这就是第 3 章的 PagedAttention。

1.5需要的工程底子与练习

• Python 工程能力：能读中大型项目；了解 asyncio、多进程、类型标注、dataclass。vLLM 的调度器和引擎层是纯 Python。
• PyTorch 基础：tensor 操作、nn.Module、CUDA tensor；知道什么是 kernel launch、什么是 stream。
• Transformer 结构：能画出 decoder-only 模型的一层——Attention（RoPE、GQA）+ FFN（SwiGLU）+ RMSNorm，知道残差连接在哪里。推荐动手实现过一次 nanoGPT 级别的小模型；视频课首推 Karpathy 的 Let's build GPT。

这一章的目标是可量化的手感：跑通两种使用方式、把主要功能都摸一遍、做一次像样的压测。每个实验都记下「改了什么 → 吞吐 / 显存 / 延迟怎么变」，这份笔记在第 3、4 章会反复用来印证原理。

2.1安装与硬件前提

shell · 推荐用 uv 建独立环境

# uv 是 vLLM 官方文档推荐的安装方式，秒级解析依赖
uv venv --python 3.12 && source .venv/bin/activate
uv pip install vllm

# 或者用官方 Docker 镜像（生产环境推荐，CUDA 依赖全部打包）
docker run --gpus all -p 8000:8000 vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-7B-Instruct

2.2离线推理 API 与 SamplingParams 详解

vLLM 有两种形态：离线批量推理（LLM 类，适合评测、数据合成、RL rollout）和在线服务（vllm serve）。先从离线开始：

python · offline_infer.py

from vllm import LLM, SamplingParams

# 首次运行自动下载权重；0.5B 模型 CPU 也能勉强跑通
llm = LLM(model="Qwen/Qwen2.5-0.5B-Instruct")

params = SamplingParams(temperature=0.7, top_p=0.9, max_tokens=256)

# generate() 走原始补全；chat() 自动套用模型的 chat template
outs = llm.chat([{"role": "user", "content": "用一句话解释 KV cache"}], params)
print(outs[0].outputs[0].text)

值得留意的第一个现象：启动日志里有一行 GPU KV cache size: ... tokens——vLLM 在加载完权重后做了一次显存测量（profiling run），把剩余显存全部预分配为 KV cache 的 block 池。这个「先量出能装多少 token」的数字决定了并发能力，第 3 章的一切都发生在这个池子里。

2.2.1SamplingParams：每个字段都在控制什么

2.3OpenAI 兼容 server 全功能

shell · 服务端

vllm serve Qwen/Qwen2.5-7B-Instruct \
  --max-model-len 8192 \
  --gpu-memory-utilization 0.90

python · 客户端 — 任何 OpenAI SDK 直接对接

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="EMPTY")
stream = client.chat.completions.create(
    model="Qwen/Qwen2.5-7B-Instruct",
    messages=[{"role": "user", "content": "解释一下 PagedAttention"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

浏览器打开 http://localhost:8000/docs 能看到完整 API 面：/v1/chat/completions、/v1/completions、/v1/embeddings（embedding 模型）、/v1/models、/metrics 等。以下四个能力在生产里最常用，建议逐个跑通：

2.3.1Chat template 与多轮对话

chat 接口收到 messages 数组后，server 会套用模型自带的 chat template（Jinja 模板，在 tokenizer 配置里）把对话拼成一段带特殊 token 的文本。理解这一点很重要：多轮对话就是把历史重新发一遍——所以第 3 章的 prefix caching 对多轮场景收益巨大（历史部分的 KV 全部命中）。用 --chat-template 可以覆盖模板，调试时用 /tokenize 端点检查最终 token 序列。

2.3.2结构化输出（structured outputs）

约束模型只能输出符合 JSON Schema / 正则 / 语法的内容。vLLM V1 的实现方式是语法约束解码：后端（默认 xgrammar，也支持 guidance 等）把 schema 编译成自动机，每个 decode step 生成一个 bitmask 把不合法的 token 置为 -inf——保证输出 100% 合法，而且几乎零开销。在 API 里用 response_format={"type": "json_schema", ...} 或 vLLM 扩展参数 guided_json / guided_regex / guided_choice。

2.3.3Tool calling 与推理模型

传 tools=[...] 即可用 OpenAI 风格的函数调用；server 端需要 --enable-auto-tool-choice 和对应模型的 --tool-call-parser（如 hermes、llama3_json）——因为每家模型的工具调用格式不同，parser 负责把模型输出解析回结构化的 tool_calls。同理，DeepSeek-R1 / Qwen3 这类推理模型需要 --reasoning-parser 把 <think> 段拆到响应的 reasoning_content 字段。

2.3.4多模态与 multi-LoRA

• 多模态：Qwen2.5-VL 等模型直接 serve，chat 消息里传 image_url 即可。V1 对多模态做了专门设计：图片经 vision encoder 的结果有独立缓存（encoder cache），且图片内容参与 prefix cache 的哈希——同一张图的重复请求不会重复过 encoder。
• Multi-LoRA：--enable-lora --lora-modules name=path 可同时挂多个 LoRA adapter，请求里按 model 名选用；底层用 Punica 风格的分组 kernel（SGMV）让不同 adapter 的请求同 batch 执行——「一个 base 模型 + 百个定制头」的多租户场景就是这么做的。

2.4关键参数逐个讲

每个参数改一次、压测一次，观察吞吐 / 显存 / 延迟的变化，比读十篇文章都有用：

2.5压测方法学：四个指标与延迟-吞吐曲线

shell · vllm bench — 内置压测三件套

# 在线压测：向已启动的 server 发 200 条请求、每秒 8 条的泊松流量
vllm bench serve --model Qwen/Qwen2.5-7B-Instruct \
  --num-prompts 200 --request-rate 8

# 另外两个模式：离线极限吞吐 / 单请求延迟
vllm bench throughput --model ... --input-len 1024 --output-len 256
vllm bench latency --model ... --batch-size 1

读结果需要四个词，整个学习过程都会围绕它们：

方法学要点：吞吐和延迟是一对根本矛盾——batch 越大吞吐越高、每个请求等得越久，所有调度参数本质上都在这条曲线上选位置。规范做法：固定模型与数据集（用 ShareGPT 或贴近业务的真实分布），扫 --request-rate 从低到高，对每个点记录 P50/P99 的 TTFT 与 ITL，画出「负载-延迟」曲线；曲线的拐点（延迟开始飙升处）就是这套配置的容量。报告 P99 而不只是均值——长尾才是用户体验。

2.6可观测性：读懂 vLLM 在想什么

/metrics 端点暴露 Prometheus 指标，生产部署配 Grafana 看板（官方有现成模板）。学习期最值得盯的几个：

日志侧：VLLM_LOGGING_LEVEL=DEBUG 可看到调度细节；启动时打印的配置快照（选中的 attention backend、编译模式、KV cache 容量）值得逐行读一遍——每一行都对应后面章节的一个机制。

朴素的推理服务浪费在两个地方：显存被碎片吃掉（装不下更大的 batch），以及 GPU 在等待中空转（batch 没被填满）。vLLM 的两大支柱分别对付它们：PagedAttention 治显存，continuous batching 治空转。本章每个机制都配动画——先玩动画，再读文字，最后读折叠块里的实现细节。

3.1问题定量化：显存都浪费在哪

KV cache 的麻烦在于长度不可预知：请求进来时没人知道它会生成 10 个还是 1000 个 token。vLLM 之前的系统（FasterTransformer、早期 Orca）按「可能的最大长度」为每个请求预留一段连续显存，产生三种浪费：

• 内部碎片：预留 2048 格实际用 300 格，剩下 1748 格锁死。这是最大头。
• 外部碎片：请求完成后留下大小不一的空洞，总空闲不少，却凑不出连续段给新请求。
• 无法共享：并行采样（n>1）、beam search、共享 system prompt 的场景里，相同内容在显存里存多份。

PagedAttention 论文（SOSP 2023）实测：这些系统里 KV cache 显存的实际利用率只有 20%~40%。也就是说，一多半显存在「站着茅坑」。由第 1 章的结论——吞吐近似正比于 batch 大小——把利用率从 30% 提到 95%，吞吐直接翻 2~4 倍。这就是 vLLM 一战成名的全部秘密：不是算得更快，而是装得更多。

把浪费算一笔具体的账。设 max_model_len=2048，真实流量的平均长度（prompt+输出）为 400 token。连续预分配下每条请求锁定 2048 格：内部碎片 = (2048−400)/2048 ≈ 80%，这还没算外部碎片和「为还没生成的部分提前留位」的预留浪费。论文把预分配方案的浪费拆成三类统计：已预留但尚未用到（reserved）、为最大长度多留的（internal fragmentation）、空洞（external fragmentation）——在 ShareGPT 负载上三者合计吃掉 60%~80% 的 KV 显存。而分页方案的浪费只剩「每条序列最后一个没写满的块」，期望值是半个块（8 个 token 位），400 token 的请求浪费率 = 8/400 = 2%。80% vs 2%，就是那 2~4 倍吞吐的全部来源。

3.2PagedAttention：机制、页表与代价

解法直接借自操作系统的虚拟内存分页：把 KV cache 切成固定大小的 block（默认 16 个 token 一块），请求按需一块一块地拿，块与块在物理显存上无需连续，由一张 block table（页表）记录逻辑块 → 物理块的映射，attention kernel 读 KV 时按表寻址。

3.2.1页表长什么样

3.2.2分页免费送的两个能力：共享与写时复制

一旦 KV 的所有权从「请求」变成「页表指向」，两个高级能力就自然出现了：

• 共享（sharing）：多个请求的页表可以指向同一物理块，配合引用计数管理生命周期——这是 3.6 节 prefix caching 的基础。
• 写时复制（copy-on-write）：并行采样 n=4 时，4 个候选序列共享 prompt 的所有块；当某个候选要往「共享的最后一块」写新 token 时，先复制这一块再写（ref_cnt>1 触发 CoW）。beam search 的序列分叉同理。论文里这两项让并行采样场景额外省 30%~55% 显存。

for blk_idx in range(seq_len[s] // BLOCK_SIZE + 1):
    phys = block_tables[s][blk_idx]          # 查页表：逻辑块号 → 物理页号
    K_tile = K_pool[phys]                    # [16, kv_heads, head_dim]，页内连续读
    scores[blk_idx*16 : ...] = Q[s] @ K_tile.T   # 与该页的 16 个 K 做点积
# 之后对 scores 做（online）softmax，再按同样方式逐页读 V 加权求和

3.3Continuous batching：iteration 级调度

解决了「装得下」，还要解决「随时上车」。传统静态 batching 以整个 batch 为单位调度：一批请求一起进、等最慢的那条生成完才全体退场，期间完成的请求占着座位空转。而 LLM 请求的输出长度天差地别——短的几十 token、长的几千——静态 batch 的 GPU 利用率惨不忍睹。

Continuous batching（Orca, OSDI 2022 提出，原文叫 iteration-level scheduling）把调度粒度细化到每个 decode step：每步结束都重新组班——完成的立刻离开、等待的立刻补位，GPU 面前永远是尽可能满的 batch。

量化这笔收益：设输出长度服从重尾分布（LLM 流量的常态，均值 300、P99 可到 2000+）。静态 batch 的完成时间由 batch 内最长的请求决定——batch 越大，抽中长尾的概率越高，平均空转率随 batch 规模上升，形成「batch 越大越浪费」的反常识现象；iteration 级调度把这个相关性直接消灭，槽位利用率与长度分布解耦。工程上还有一个隐藏收益：新请求不再需要「凑批」等待窗口（静态方案常见的 batching timeout），TTFT 的排队分量也随之消失。两大支柱到这里合成一句话：PagedAttention 让显存装下更多请求，continuous batching 让这些请求无缝挤满每一个 GPU 时钟周期。

3.4V1 统一调度器：token 预算与抢占

朴素 continuous batching 还有一根刺：新请求插进来要先做 prefill，一段长 prompt 会独占 GPU 几百毫秒，正在 decode 的所有请求集体卡一拍（ITL 尖刺）。vLLM V1 的调度器把解法（chunked prefill，见 3.5）推到了极致，形成一个非常优雅的抽象，也是读源码前必须建立的心智模型：

调度顺序与策略：先服务 running 队列（保证已有请求不断流），预算有余再从 waiting 队列收新请求；策略默认 FCFS（先来先服务），也支持 priority（请求带优先级，配合抢占实现分级 SLO）。

抢占（preemption）：block 池耗尽时，调度器把最低优先级的 running 请求整个踢回 waiting——释放它的全部 block，之后重新调度时靠重算 prefill 恢复（prefix cache 命中的部分免算，所以代价可控）。压测日志里的 WARNING ... preempted 就来自这里：偶发无妨，频繁出现说明 KV cache 太小，该加卡、调小 max_model_len 或开 KV 量化了。抢占的受害者选择规则：FCFS 策略下踢最晚到达的（保护排队久的），priority 策略下踢优先级最低的——这保证系统过载时牺牲的总是「最不重要」的请求，而不是随机抖动。

请求在引擎里的状态机很简单：WAITING → RUNNING →（抢占时退回 WAITING）→ FINISHED。但每步调度不只分配 token 数，还要同步推进一串「随行状态」：结构化输出的语法自动机走到哪个节点（决定下一步的 logits mask）、投机解码的草稿 token 是否计入预算、多模态的 encoder 预算是否够用、KV connector 是否有外部缓存可查——这些都是 schedule() 真实代码比 5.4 节伪代码长的原因，主干逻辑不变。

3.5Chunked prefill：把大石头敲碎

思想源自 Sarathi-Serve 论文：把长 prompt 的 prefill 切成固定大小的 chunk，每个 step 只算一块，与其他请求的 decode 混在同一 batch。这样每个 step 的计算量被「预算」封顶，decode 请求的 ITL 保持平稳；而 decode 请求们也顺便「搭了 prefill 的车」——prefill 是 compute-bound、decode 是 memory-bound，混合执行让算力和带宽同时被利用（论文称之为 piggybacking）。

算一个具体例子感受量级。H100 上 8B 模型，decode batch 每步约 15ms；一条 8000 token 的 prompt 若整段 prefill 约需 150ms。不分块：混在批里的所有 decode 请求这一步 ITL 从 15ms 跳到 150ms——用户可感的卡顿。按预算 2048 分块：prompt 切成 4 刀，每步只多花 ~35ms，ITL 峰值 50ms 上下，而 TTFT 只多了三步的排队（几十 ms）。分块把一次 10 倍的尖刺换成四次 1.3 倍的微扰——这就是它成为默认行为的原因。Sarathi 论文进一步指出最优 chunk 大小应贴着「刚好吃满算力」的临界点选：太小浪费算力（每 chunk 有固定开销），太大重新引入尖刺。

两个实现细节值得知道：① 只有 prompt 的最后一个 chunk 需要产出 logits 并采样（前面的 chunk 只为填充 KV cache），所以中间 chunk 连 LM head 的计算都省了；② 长 prompt 请求可能连续多步占据大额预算、饿着排队的短请求，V1 用 long_prefill_token_threshold 限制单个请求每步的份额，保证公平性。

3.6Prefix caching：哈希链与逐出策略

生产流量里大量请求共享前缀：同一段 system prompt、多轮对话的历史、RAG 的公共模板。分页让复用变得自然——给每个写满的 block 建索引，新请求逐块查表，命中就直接把页表指过去，prefill 从第一个未命中的块算起。

3.6.1哈希链：命中判定的精确语义

关键设计是 block 的哈希不是只看块内 token，而是前缀累积哈希：

父哈希的链式传递保证：两个块哈希相等 ⟺ 从序列开头到这个块的全部内容都相同——所以命中判定是严格的前缀匹配，第 1 个 token 不同则全线失配。「额外键」包括多模态输入的内容哈希、LoRA adapter id、cache salt 等——保证「同 token 不同图」或「同 prompt 不同 adapter」不会错误命中。工程含义直白：把稳定的内容放 prompt 开头，把会变的（时间戳、用户名、随机 id）放末尾，这是部署 vLLM 最重要的一条 prompt 结构纪律。

3.6.2逐出与「零开销」设计

请求结束后它的块不立即清空，而是保留哈希、进入空闲队列尾部；池子紧张时从空闲队列头部拿块——天然形成 LRU 逐出（最久未用的缓存块最先被覆盖）。V1 把这套机制做到「零开销」：即使 0 命中，额外成本也只是每块一次哈希计算，所以默认开启、生产环境没有理由关掉。多轮对话场景的 TTFT 提升常达一个数量级；观测指标是 2.6 节的 prefix_cache_hit_rate。第 5 章会在 block_pool.py 里看到这套「空闲队列 + 哈希索引」的具体数据结构。

3.6.3边界情况：安全、滑动窗口与跨实例

• 多租户安全：缓存共享引入了一个微妙的侧信道——攻击者可以用「探测 prompt + 观测 TTFT」推断缓存里有没有某段前缀（命中则明显更快），从而探知其他租户的 prompt 内容。vLLM 的对策是 cache_salt：请求携带盐值参与块哈希，不同租户盐值不同则永不互相命中。默认哈希也可切换为 SHA-256 以防哈希碰撞攻击。
• 滑动窗口与混合模型：滑动窗口 attention（Mistral 类）只看最近 W 个 token——窗口外的 KV 理论上可丢弃，但「前缀命中」的语义也变了（不再是任意长前缀可复用）。Gemma、混合 Mamba 类模型每层的 KV 需求还不一样。V1 为此把 KV cache 组织成分组（不同 attention 类型一组一套页池与管理逻辑），是 kv_cache_manager 里为数不多的复杂度来源，读源码时可以先跳过、知道为什么存在即可。
• 跨实例共享：单机的 prefix cache 只在本实例有效；多副本部署时要么用前缀感知路由把同前缀请求送到同一实例（6.4 节），要么用 LMCache 这类外部 KV 池做集群级共享（6.3 节）——本节的哈希链设计是这两者共同的地基。

第 3 章的显存与调度决定了「装多少、排多满」，本章的四类技术则各自攻击一段具体的物理成本：投机解码攻击 decode 的串行依赖，量化攻击访存字节数，attention kernel 攻击 HBM 往返，CUDA Graph 与编译攻击 CPU 开销。理解每项技术「偷的是哪段时间」，选型就不会凭感觉。

4.1投机解码：原理、谱系与 vLLM 的选择

4.1.1原理：起草-验证，快了但没变笨

第 1 章说过 decode 的两个事实：① token 之间是串行依赖，一步只能出一个；② 一步前向的时间被搬权重主导，多算几个 token 几乎免费。投机解码（speculative decoding）把它们拼成一个漂亮的杠杆：用便宜的「起草者」快速猜出 k 个候选 token，再让大模型一次前向并行验证这 k 个位置——验证通过几个就收下几个。

正确性靠拒绝采样保证：设起草分布为 q、目标分布为 p，对每个候选 token x 以概率 min(1, p(x)/q(x)) 接受；一旦拒绝，从修正分布 (p−q)₊ 归一化后重新采样一个 token 并终止本轮。Leviathan et al. 2022 与 Chen et al. 2023（DeepMind，同期独立提出）证明了这个过程的输出分布与直接从大模型采样严格相同——快了，但数学上没变笨。若单 token 接受率为 α，每轮期望产出 (1−α^{k+1})/(1−α) 个 token；α≈0.8、k=4 时约 3.3 个/轮，对应 2~3 倍的延迟改善。

4.1.2谱系：起草者的五个流派

投机解码的研究全部围绕一个问题展开：去哪找一个又快又准的起草者？五个流派按时间线依次登场：

4.1.3vLLM 用的是哪种

vLLM V1 走的是「不依赖独立 draft 模型」的路线，当前支持 ngram、eagle / eagle3、medusa、以及 DeepSeek 系的 mtp（V0 时代的独立小模型起草未在 V1 延续，因为调度两个模型的复杂度高、收益不如 EAGLE）。配置通过 --speculative-config 传 JSON：

# n-gram：零成本，先拿它验证你的业务是否「有草可偷」
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --speculative-config '{"method": "ngram", "num_speculative_tokens": 4,
                         "prompt_lookup_max": 3}'

# EAGLE-3：接受率最高的通用方案，社区为主流模型都训好了头
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --speculative-config '{"method": "eagle3",
                         "model": "yuhuili/EAGLE3-LLaMA3.1-Instruct-8B",
                         "num_speculative_tokens": 4}'

运行时日志会周期性打印 acceptance rate / mean acceptance length——这是投机解码唯一重要的健康指标：平均接受长度 2.5~3 以上收益明显，接近 1 说明起草全被拒、纯赔本。（字段名随版本可能微调，以 官方文档 为准。）

4.2量化：格式、kernel 与选型

4.2.1先分清三个对象

「量化」在推理里其实是三件独立的事，收益机制不同，可以叠加：

• 权重量化（W）：16-bit → 8/4-bit，权重体积÷2~4。因为 decode 被搬权重主导，搬得少 = 单步更快，小 batch 下 W4 模型 decode 常快近一倍；同时省下的显存变成 KV cache。
• 激活量化（A）：矩阵乘的输入也降精度，才能用上 FP8/INT8 tensor core 的双倍算力——这是大 batch / prefill（compute-bound 区域）提速的关键。难点是激活里的 outlier。
• KV cache 量化：--kv-cache-dtype fp8，容量翻倍 → 并发翻倍，长上下文场景还直接减半 attention 的访存（1.4 节深入块算过这笔账）。

4.2.2主流格式各自的招

工作流：用 vLLM 官方的 llm-compressor 做量化（或直接下载 HuggingFace 上现成的量化 checkpoint，如 RedHatAI/NM 出品的 FP8 系列），vLLM 加载时自动识别 checkpoint 里的量化配置并选择对应 kernel——W4A16 的矩阵乘由 Marlin / Machete 这类混合精度 GEMM kernel 执行，它们把「反量化」融合进矩阵乘流水线，这是 4-bit 能真跑出加速的关键。

4.2.3选型直觉与验收

• 单卡装不下模型 / 追求低延迟 → AWQ / GPTQ（W4A16）；
• Hopper+ 卡上追求吞吐与精度平衡 → FP8（已是服务部署的事实标准）；
• 长上下文高并发 → 叠加 KV cache FP8；
• 验收别只看困惑度：用 lm-eval 跑任务指标 + 抽真实业务样本人工对比，重点看格式遵循与长输出稳定性——量化伤的往往是这些，榜单看不出来。

4.3Attention kernel 生态

4.3.1FlashAttention：不落地的 softmax

朴素 attention 要把 T×T 的分数矩阵 S = QKᵀ 完整写进 HBM、读回来做 softmax、再写读一轮乘 V——长序列下这个中间矩阵的搬运量是 O(T²)，远超 Q/K/V 本身。FlashAttention 的解法：把 Q/K/V 切成小块装进片上 SRAM，用 online softmax（边扫边维护运行中的最大值与归一化和）在片上一次算完，T×T 矩阵从头到尾不存在。这是「IO 感知算法设计」的教科书案例——不减少 FLOPs，只减少 HBM 往返，恰好打中 1.4 节 roofline 的要害。FA2 改进了并行切分与非矩阵开销；FA3 面向 Hopper 用上 warp 专业化、TMA 异步拷贝与 FP8。

# 每个 Q tile 常驻 SRAM；K/V 分块流过
for (K_j, V_j) in 分块序列:
    S = Q_tile @ K_j.T                # 小块分数，只存在于 SRAM
    m_new = max(m, rowmax(S))
    P = exp(S - m_new)                # 本块的未归一化概率
    O = O * exp(m - m_new) + P @ V_j  # 旧输出「改口」+ 新块贡献
    l = l * exp(m - m_new) + rowsum(P); m = m_new
O = O / l                             # 最后一次性归一化

4.3.2vLLM 的 backend 选择

vLLM 把「哪个 kernel 算 attention」抽象为可插拔的 attention backend，按硬件与模型自动选择，也可用 VLLM_ATTENTION_BACKEND 强制指定：

• FlashAttention 2/3：NVIDIA 卡默认，原生支持 paged KV 与变长 batch；
• FlashInfer：面向服务场景特化的 kernel 库——分页 KV、GQA 分组、投机解码的树状验证等场景常更快，部分新特性（如某些采样融合）首发在这里；
• Triton 实现：用 OpenAI Triton 写的后备实现，保证 ROCm 等非 CUDA 平台可用；
• FlashMLA 等专用 kernel：MLA（1.2.3 节）的 latent 结构与标准 attention 不同，DeepSeek 开源了专用实现。

学习建议：不必读 kernel 源码，但要会做一个实验——同一负载切换 backend 压测一次，你会对「kernel 也是变量」建立体感；第 5 章会看它们在 v1/attention/backends/ 里怎么接进执行流。

4.4CUDA Graph 与 torch.compile

4.4.1CPU 开销：被忽视的第三种瓶颈

一个 decode step 要发射几百个 kernel，每个 launch 有 5~10 微秒 CPU 开销；小 batch 时 GPU 每个 kernel 只算几十微秒——CPU 发射速度追不上 GPU 消化速度，GPU 在等指令而不是等数据。这就是第三种瓶颈：launch-bound。CUDA Graph 的解法是把一整步的 kernel 序列「录制」成图，之后每步一次性「重放」，CPU 开销从几百次 launch 变成一次 graph launch。

V1 默认用 piecewise CUDA Graph：attention 前后的稠密计算段录成图，attention 本身留在图外灵活执行（因为分页寻址、变长 batch 让它的输入形状难以固化）；对形状规整的纯 decode batch 也支持整图模式。启动时那串 Capturing CUDA graphs 日志就是在预录不同 batch 尺寸的图；--enforce-eager 关掉它，对比 ITL 你能直接量出 CPU 开销有多大。

4.4.2torch.compile：定制 kernel 的量产线

V1 的模型执行默认经过 torch.compile（Inductor 后端）：自动做算子融合（RMSNorm+量化、SiLU+mul 等）、为当前硬件生成特化 kernel——过去要手写 CUDA 的优化现在由编译器量产。启动时的「编译中」等待就是它，产物缓存在 ~/.cache/vllm，二次启动跳过。编译等级用 -O0~-O3 控制；调试崩溃或数值问题时先降到 -O0 / --enforce-eager 排除编译因素——这是实战里最常用的排障开关。vLLM 团队博客有一篇 torch.compile 集成详解 值得读。

读 vLLM 源码最有效的方式不是按目录顺序读文件，而是自顶向下跟踪一个请求的完整生命周期，再对两个核心类（Scheduler、KVCacheManager）做伪代码级精读。前面三章的所有概念，在这里都会落到具体的类和函数上。

5.1准备：能跳转、能断点的代码

git clone https://github.com/vllm-project/vllm.git && cd vllm
# editable 安装 + 复用预编译的 CUDA kernel（不用等半小时编译）
VLLM_USE_PRECOMPILED=1 uv pip install -e .

Python 部分改完即生效。两个让 debugger 好用的开关：VLLM_ENABLE_V1_MULTIPROCESSING=0 让引擎回到单进程内运行（断点直接命中，不用 attach 子进程）；--enforce-eager 关掉编译与 CUDA Graph（栈干净、行号准）。再备一个 2 条 prompt 的最小离线脚本当「探针」。

5.2骨架：两个进程，一条消息队列

V1 最重要的架构决策是把引擎拆成两个进程，用 ZeroMQ 连接。CPU 重活（HTTP、tokenize、detokenize）与 GPU 调度循环彻底隔离：EngineCore 忙循环里每一毫秒都很贵，不能被 Python 字符串处理拖住——detokenize 一条长输出可能花几毫秒，若与调度同进程，所有请求的 decode 都会被它卡一拍。

几个架构细节，读代码时能少走弯路：① API 侧通过 EngineCoreClient 抽象与引擎对话——同一套接口有单进程内联（调试用，VLLM_ENABLE_V1_MULTIPROCESSING=0 就是切到它）、多进程 ZMQ、多引擎数据并行三种实现，这就是「断点能不能直接命中」的开关原理；② 跨进程消息用 msgpack 序列化（比 pickle 快且安全），大的张量类数据（多模态 embedding）走共享内存旁路；③ LLM 离线类和 vllm serve 共用同一个 EngineCore——离线只是把 AsyncLLM 换成同步壳，所以你在离线脚本里调试的调度行为与线上完全一致；④ 高 QPS 下单个 API 进程的 tokenize/detokenize 会成瓶颈，V1 支持多 API 进程共享一个引擎（--api-server-count），这是「两侧独立伸缩」的具体形态。

5.3主线：请求的一生（七站）

下面是一条 chat 请求走过的每一站。把它当作阅读顺序：每站打开对应文件、找到入口函数、用 debugger 停一次，观察括号里的关键数据结构：

路径以 v0.2x 为准，小版本间可能微调；对不上时用 git grep 类名 定位。

5.4精读 Scheduler.schedule()

全项目最值得逐行读的函数。先带着这份伪代码框架去读，真实代码就只是它加上边界处理（投机解码的草稿 token、结构化输出的语法状态、encoder 预算等）：

def schedule() -> SchedulerOutput:
    budget = max_num_batched_tokens          # 本步 token 总预算

    # ── 第一优先级：running 队列（已在跑的请求不断流）──
    for req in running:
        n = min(req.未算的token数, budget)   # decode 时 n=1；prompt 没算完时是下一个 chunk
        while not kv.allocate_slots(req, n): # 块不够 → 抢占别人
            victim = running.pop_lowest_priority()
            kv.free(victim); victim → waiting 队头   # 释放全部块，回头重算
            if victim is req: break            # 自己被踢，本步作罢
        schedule req 算 n 个 token; budget -= n

    # ── 第二优先级：waiting 队列（预算有余才收新人）──
    for req in waiting:                       # FCFS 或 priority 顺序
        if len(running) == max_num_seqs or budget == 0: break
        cached = kv.get_computed_blocks(req)  # prefix cache 命中的部分免算
        n = min(req.prompt长度 - cached, budget)
        if not kv.allocate_slots(req, n): break
        req → running; schedule req 算 n 个 token; budget -= n

    return SchedulerOutput({req_id: n, ...}, block_table增量, ...)

对照第 3 章验证你的理解：统一 token 预算（3.4）、chunked prefill 是「prompt 没算完的请求每步领一个 chunk」（3.5）、抢占是 allocate 失败时的连锁反应（3.4）、prefix cache 在新请求入场时查表（3.6）。读完的检验标准：给你一个 running/waiting 队列快照和预算数字，你能手推出这一步的分配表。配套测试 tests/v1/core/test_scheduler.py 里就是一堆这样的场景，直接拿来自测。

对着真实代码读时的几个锚点：调度结果的核心载体是 num_scheduled_tokens: dict[str, int]（就是 3.4 那张分配表的本体）；新入场请求与继续运行的请求在 SchedulerOutput 里分开描述（前者要带完整 prompt 与采样参数，后者只带增量），这是为了让跨进程消息尽量小；update_from_output() 是 schedule() 的「下半场」——模型跑完后回填每个请求的新 token、推进结构化输出的自动机、判定完成与否，一进一出合起来才是调度器的完整职责。投机解码启用时，上一步被接受的草稿 token 也会出现在预算里（验证 k 个草稿意味着本步要为该请求调度 k+1 个 token）——读到 spec_token_ids 相关分支时对照 4.1 节即可。

5.5精读 KVCacheManager 与 BlockPool

三个数据结构撑起整个分页系统（v1/core/block_pool.py、kv_cache_utils.py）：

• KVCacheBlock：物理块的元数据——block_id、ref_cnt（几个请求在用）、block_hash（3.6 的前缀累积哈希，未满的块为 None）、双向链表前后指针。
• 空闲队列（free_block_queue）：双向链表串起所有 ref_cnt==0 的块。头部 = 最久未用。妙处在于：空闲块仍保留哈希，还能被命中「复活」——所以它同时是 free list 和 LRU 缓存。
• 哈希索引（cached_block_hash_to_block）：hash → 块的字典，prefix cache 查表就是查它。

两个核心操作的逻辑：

def get_computed_blocks(req):          # 入场时查前缀命中
    for 每个满块的hash in req 的哈希链:
        if hash in 哈希索引: 命中块.ref_cnt += 1   # 在空闲队列里则先摘出（复活）
        else: break                     # 链式哈希：断一环则后面全断
    return 命中的块列表

def allocate_slots(req, n_tokens):     # 为新 token 领块
    需要的新块数 = 按 n_tokens 折算
    if 空闲队列长度不够: return False  # → 触发调度器的抢占逻辑
    从队列头 pop 块（最久未用优先）:
        if 块还带着旧哈希: 从哈希索引删除   # ← LRU 逐出就发生在这一刻
        块.ref_cnt = 1; 写进 req 的 block table
    新写满的块: 计算哈希、登记进索引     # ← 缓存的产生

逐出不是后台任务，而是分配的副作用——这个设计让 prefix caching 做到「零开销」（3.6.2）。读完可以自答：为什么请求结束时块要从队列尾部入队？（答：刚用过的最「热」，应最晚被逐出。）

再记三个读码锚点：① BlockHash 的构成与 3.6.1 的公式一一对应——父哈希 + 块内 token 元组 + extra keys（多模态哈希、LoRA id、cache_salt），在 kv_cache_utils.py 里能找到打包函数；② 池里有一个特殊的 null_block（0 号块）用来占位——比如滑动窗口把窗口外的位置指向它，省得页表里出现空洞判断；③ 每个请求持有的块列表由 KVCacheManager 按请求 id 记账，请求结束统一 free()（引用计数减一、归还队尾）——顺着一个 request_id grep 这三处，分配-使用-归还的闭环就完整了。混合模型（滑动窗口/Mamba 层）会把这套结构复制成多个「KV cache group」各管一类层（3.6.3），首次阅读建议直接读单组路径。

5.6执行层：ModelRunner 与 Sampler

gpu_model_runner.py 把 SchedulerOutput 变成 GPU 上的一次前向。三个值得专门观察的机制：

• 扁平化输入：本步所有请求要算的 token 拼成一条一维序列（3.3 深入块讲的 selective batching）——R1 的 320 个 + R2 的 1 个 + ……attention 元数据记录各自边界与 block table，交给变长 kernel。
• Persistent batch：batch 的张量状态（token id、位置、采样参数）常驻 GPU，每步只做增量修改（新增/移除请求），避免每步全量重建输入张量的 CPU 开销。
• Sampler：logits → 重复惩罚 → temperature → top-k/p → 采样。不同请求参数不同，用张量化技巧按行批处理；结构化输出的 grammar bitmask 也在此生效（2.3.2）。

观察方法：在 execute_model() 入口断点，打印 scheduler_output 与输入张量形状，对照 5.4 手推的分配表——三章理论在这一刻闭环。

5.7模型定义、TP 层与阅读方法论

打开 model_executor/models/llama.py 对照 HuggingFace 版本读，vLLM 重写模型只为三件事：

• 并行层替换：nn.Linear 换成 QKVParallelLinear（QKV 合并 + 按列切）、MergedColumnParallelLinear（gate/up 合并）、RowParallelLinear（按行切，出口处 allreduce）。TP 的通信结构就藏在类名里——第 6 章展开这笔通信账。
• 算子融合：RMSNorm、RoPE、SiLU-mul 用融合 kernel；attention 接到第 4 章的 backend 上。
• 权重加载映射：load_weights() 把 HF checkpoint 的张量名映射并切分到并行层——给 vLLM 添加新模型 80% 的工作量在这里（官方新模型指南）。

走到这里，你已经「读得懂、改得动」。本章把视野从单卡扩展到集群：先学会量化性能（不量化就没有优化），再理解四种并行各自的通信账，然后是 2025 年以来最活跃的方向——PD 分离与大规模编排。最后，把学到的还给社区。

6.1性能剖析实战

• 先量化再动手：设 VLLM_TORCH_PROFILER_DIR=/tmp/traces 启动，压测工具带 --profile 开关抓 torch profiler trace，在 Perfetto 里看时间线：每个 step 里 CPU 在忙什么、GPU 空隙在哪、哪个 kernel 最长。更底层用 Nsight Systems（nsys profile）。
• 诊断三分法：GPU 空隙大 → launch-bound（查 CUDA Graph 是否生效、CPU 是否被 tokenize 拖住）；GEMM kernel 占主导且 batch 小 → memory-bound（上量化、投机解码）；attention kernel 占主导 → 长上下文效应（KV 量化、换 backend）。第 1 章的 roofline 是分诊台。
• 调度层调优：拿真实流量分布，在 TTFT SLO 约束下扫 max_num_batched_tokens 与 max_num_seqs 最大化 goodput——生产环境最常见也最体现理解深度的实战。

nsys profile -t cuda,nvtx --duration=20 -o vllm_trace \
  --attach-pid $(pgrep -f "EngineCore")
# 或者用 torch profiler：启动前设 VLLM_TORCH_PROFILER_DIR=/tmp/traces，
# 压测端 vllm bench serve ... --profile，产物拖进 ui.perfetto.dev

6.2并行全景：TP / PP / EP / DP 的通信账

所有并行策略都在回答同一个问题：模型 / 数据怎么切，通信代价放在哪。先看最常用的 TP 在一层 Transformer 里的通信结构：

实践组合：单机内 TP、跨机 PP 是经典搭配（-tp 8 -pp 2）；MoE 大模型主流是 attention 走 DP + FFN 专家走大规模 EP（DeepSeek 公开架构即此形态）。多机由 Ray 或 multiprocessing 编排。深入阅读：官方并行文档 与 vllm/distributed/。

6.3PD 分离：prefill 与 decode 分家

第 1 章讲过：prefill 是 compute-bound、decode 是 memory-bound——两种负载抢同一块 GPU 注定互相干扰，chunked prefill 只是缓解。Prefill-Decode disaggregation 干脆把它们放到不同 GPU 组：prefill 集群算完 prompt，把 KV cache 经 RDMA / NVLink 传给 decode 集群继续生成（思想源自 DistServe、Splitwise；Kimi 的 Mooncake 给出了超大规模的工程实录）。

vLLM 侧的抽象是 KV connector：把「KV cache 从哪来 / 到哪去」插件化——NIXL 走 RDMA 点对点传输，LMCache 提供 GPU/CPU/磁盘三级 KV 缓存池（跨实例复用前缀）。编排层交给 Kubernetes 生态：llm-d、vLLM production-stack、NVIDIA Dynamo 都以 vLLM 为引擎实现 PD 分离 + 前缀感知路由。什么时候值得上：流量大、prompt 长（KV 传输摊得开）、SLO 严；小规模部署里 chunked prefill 混跑往往更划算——别为了架构而架构。

6.4生产部署：路由、扩缩容与多实例

• 前缀感知路由：多实例时把同一会话 / 同一 system prompt 的请求路由到同一实例，prefix cache 命中率决定成败——随机轮询会把命中率打掉一半以上。
• 扩缩容信号：用 2.6 的 num_requests_waiting 与 KV 使用率做 HPA 指标，比 GPU 利用率灵敏得多（GPU util 常年 100% 不代表没容量）。
• 发布与容错：模型加载要几分钟，滚动升级须配合就绪探针（/health）；长请求 drain 策略、抢占告警、OOM 自动重启都要提前演练。
• 睡眠模式与弹性：vLLM 支持 sleep/wake（权重下卸到 CPU 释放显存），配合弹性调度应对潮汐流量。

6.5生态对比：vLLM 之外的世界

对比阅读的价值：同一个问题（如 prefix 复用）看两家解法，才能理解设计空间的取舍，而不是把 vLLM 的选择当唯一答案。SGLang 的 RadixAttention 论文 建议精读。

6.6参与社区：从 issue 到 PR

• 从 good first issue 入手；复现并修复一个 bug 是深入代码库的最快路径。
• 经典第一个实质性 PR：给新模型添加支持——5.7 的知识刚好够用，跟着 官方指南 走。
• 加入 vLLM Slack，蹲双周 office hours；关注 官方博客 与 release notes 跟进版本节奏。
• 提 PR 的软技能：小步提交、benchmark 数据说话、CI 全绿再请 review——vLLM 的 reviewer 吞吐有限，让 PR「好审」是被合并的最大加分项。

论文

官方文档与代码

• docs.vllm.ai —— 总入口。重点：Design Documents（架构与各子系统设计）、Features（spec decode / structured outputs / LoRA）、Serving（并行与部署）、Contributing（新模型指南）。★★★
• blog.vllm.ai —— 每个大特性的动机与实测。必读三篇：V1 架构发布、torch.compile 集成、各版本性能回顾。★★★
• github.com/vllm-project/vllm —— 源码、issue、[RFC] 设计讨论、release notes。★★★

动手与工具

• nanoGPT + Let's build GPT —— 补 Transformer 基础（第 1 章）。
• nano-vllm —— 约 1200 行的迷你 vLLM（分页 KV + 调度器），读正式源码前的最佳热身（第 5 章）。
• llm-compressor —— 官方量化工具链（第 4 章）；lm-eval —— 量化验收评测。
• LMCache / llm-d / production-stack —— KV 缓存池与 K8s 编排（第 6 章）。
• Perfetto / Nsight Systems —— trace 分析（第 6 章）。

术语表

正文里带虚线下划线的词都可以悬停查看解释；这里是全部术语的汇总，供集中查阅。

中文社区

• 知乎搜「vLLM 源码解析」有大量系列文章——注意分辨 V0/V1：凡是讲 LLMEngine.step()、swap in/out、BlockSpaceManager 的都是 V0 旧架构，概念可参考、路径已失效；认准 EngineCore、kv_cache_manager、统一调度等 V1 关键词。
• vLLM 官方公众号、vllm-ascend（昇腾）等中文活跃子项目的文档，质量高且更新及时。