简单来说,vLLM在启动时一次性申请一组大块的GPU显存作为KV Cache,然后把它切成固定大小的block;Scheduler 会管理“请求使用哪些 block”,Attention kernel则会往对应位置写入和读取 KV。
在EngineCore的初始化函数中,会调用自身的_initialize_kv_caches()方法:
1 | kv_cache_config = self._initialize_kv_caches(vllm_config) |
该函数首先查询每个Worker上哪些层需要KV Cache,调用链是:
1 | EngineCore._initialize_kv_caches() |
KVCacheSpec称为“KV Cache层规格”,表示某一层保存一个block的KV Cache时,要保存多少个token、占多少字节,以及保留多长的上下文。model_executor.get_kv_cache_specs()此时返回的是list[dict[layer_name, KVCacheSpec]]:列表中每个字典对应一个Worker。这一步只是收集,还没有把所有Worker的结果合并成全模型规格。
调用链中的collective_rpc()是model_executor向所有Worker下发同一个方法、再收集所有返回值的入口。
GPUModelRunner.get_kv_cache_spec()首先从已经创建的模型中找出所有需要KV Cache的层:
1 | layer_type = cast(type[Any], AttentionLayerBase) |
这里比较奇怪的是,为什么会需要从vllm_config取Attention层对象。事实上,这是因为模型在初始化时将层注册到了vllm_config.compilation_config的static_forward_context中。注册完成后的static_forward_context类似于:
1 | vllm_config.compilation_config.static_forward_context = { |
在抽取出所有Attention层后,函数会对所有Attention层进行遍历。
如果该层的KV Cache复用其他层的,那么记录复用关系;如果该层需要自己拥有KV Cache,则获取KV Cache的配置并记录到字典内。
1 | if isinstance(attn_module, Attention) and ( |
在Attention层的get_kv_cache_spec函数中,其会根据当前层的类型(普通注意力、SWA、TQA……),使用各项参数构造并返回KV Cache配置。
如果该层复用另一层的KV Cache,这里只记录复用关系,不为它单独创建层规格。如果该层需要自己的KV Cache,就调用它的get_kv_cache_spec();返回None表示它不需要独立KV Cache,否则把返回的层规格记入字典。
以普通注意力层为例,假设一个block保存16个token,有8个存放K/V的头(KV head),每个head的维度是128,K和V都使用16位浮点数(FP16),那么该层为一个block保存KV所需的字节数是:
$$
2\times16\times8\times128\times2=65536\text{ bytes}=64\text{ KiB}.
$$
第一个2表示K和V,最后一个2表示每个FP16元素占2字节。DeepSeek V4的多头潜在注意力(MLA)使用压缩后的自定义布局,不能直接套用这个普通注意力公式;它由MLAAttentionSpec.real_page_size_bytes根据压缩比例和实际存储布局计算。
接下来,_initialize_kv_caches()调用model_executor.determine_available_memory(),让每个Worker计算可以分给KV Cache池的显存。
如果用户显式设置了kv_cache_memory_bytes,GPUWorker仍会运行一次profile_run(),以便按单轮调度最多处理的token数max_num_batched_tokens编译和预热模型,然后直接返回用户指定的字节数。另一个长度配置max_model_len表示单个请求允许的最大模型长度。这个分支不会自动重新估算KV Cache池应该有多大,指定得过大仍可能在后续分配时出现显存不足(OOM)。
如果没有指定,GPUWorker就用一次带虚拟输入的模型前向计算测量模型权重之外的显存峰值。“激活值峰值”是模型前向计算期间PyTorch额外分配的峰值;“非PyTorch显存”是NCCL通信库、自定义内核等没有记在PyTorch显存分配器上的额外显存;“CUDA图显存”是为后续CUDA Graph执行模式预留的估算值。在默认启用CUDA Graph显存估算的CUDA路径中,计算可以简化为:
$$
\text{KV Cache可用显存}
=\text{GPU总显存}\times\text{gpu_memory_utilization}
-\text{模型权重}
-\text{激活值峰值}
-\text{非PyTorch显存}
-\text{CUDA图显存}.
$$
如果没有启用CUDA Graph、关闭了对应的显存估算开关,或者使用ROCm、XPU等不执行这项估算的后端,最后一项按0计算。
例如,某个Worker所在GPU有24GiB显存,用户允许vLLM使用的显存比例gpu_memory_utilization=0.9,模型权重占14GiB,测得激活值峰值、非PyTorch显存和CUDA图显存分别是1.2GiB、0.4GiB和0.5GiB,那么可分给KV Cache池的显存约为:
$$
24\times0.9-14-1.2-0.4-0.5=5.5\text{ GiB}.
$$
max_num_batched_tokens会影响这次forward的激活值峰值,也会影响SWA缓存在一次调度中最多需要接纳多少个新token。它不是直接代入“每层KV Cache池大小”的公式。
此时,EngineCore拿到了两个长度相同的列表:
1 | kv_cache_specs = [ |
因此此时可以调用get_kv_cache_configs()生成各Worker上的KV Cache具体配置:
- 合并所有 Worker 的层规格。
- 根据 PP 切分,确定每个 Worker 实际负责哪些层。
- 计算每个 block 占多少字节。
- 计算每个 Worker 能分配多少个 block。
- 所有 Worker 统一采用最少的 block 数量。
这里出现了block的概念。vLLM是以block为单位管理KV Cache的。一个block的block_size代表这个block存放多少个token的KV Cache,而某一层的一个block存放KV的物理空间称为page,理论所需page的字节数为real_page_size_bytes,而实际上,由于不同层的real_page_size_bytes不尽相同,vLLM会将这些real_page_size_bytes进行分桶对齐,如[84KiB,96KiB,100KiB,192KiB,200KiB]分桶对齐到[100KiB,200KiB],记为page_size_bytes。
现在假设一个简单的模型,其所有自注意力层都是完全相同的全量自注意力层,共$L$层。我们为这个模型每层都分配一些block用于存放KVCache:
1 | Layer 0: block 0, block 1, block 2, …… |
此时我们会发现,在各层申请和释放block时,可以选择完全相同的block。
在系统刚刚启动,没有任何block被占用的情况下,假设某一个请求只需要3个block,那么我们可以为每一层都分配block 03;假设这个请求消亡了,那么我们可以在每一层都同步地释放block 03;只要保证每次申请和释放时都在每层使用相同的block id,那么每层不同block id的block的占用情况就是一样的,我们可以继续每次申请和释放时都在每层使用相同的block id。
vLLM正是发现了这一点,因此会将生命周期相同的注意力层的block分在一个block group中,使用相同的block表,即这些层占用的block的id、空闲的block的id、某个request对应的KV Cache的block完全相同,那么,他们就可以使用统一的全局block编号。
那么,一个全局block的编号就会占用$L * \textit{real_page_size_bytes}$字节的空间;使用总KV Cache可用空间除以这个数,就能得到可用的block ID数。
然而,在DeepSeek V4这样的模型中,注意力机制有多种:C128、C4、SWA、Indexer。这些不同的注意力算子又各自拥有不同的生命周期不同,因此他们不能同时申请和释放同ID的block。
例如,同一个请求已经生成了足够多的token,全量注意力和SWA最初都使用了block 3来保存较早token的KV Cache。此时,SWA的滑动窗口已经越过这些token,不再需要block 3,可以将其释放并复用;但全量注意力后续仍可能关注这些token,所以必须继续保留block 3。两者对block 3的释放时机不同,因而不能共用一张block table并同步申请、释放同一组block id。
vLLM将生命周期相同的一组注意力层分到一个block group中,各自在组内共享block table。那么,难道我们需要为不同group的注意力层分别建立一套block管理系统,分别为他们建立内存池吗?vLLM认为这会导致我们每多一种注意力,就需要增加一个管理系统的实例,还需要协调不同类型注意力的内存占用情况。
vLLM希望,各种不同group的注意力层能够从同一个全局的block池中取block。例如,某个模型有10层全量注意力,5层滑窗注意力,他们分属不同的block group,但是在一次前传中,它们分别从全局block池中取了block 3~22和block 31~35来保存新产生的Cache。如果现在由全量注意力使用block 3~22被释放了,这些block可以既被其他请求的全量注意力或其他请求的滑窗注意力使用。
要实现这一点,理论上每个全局block ID所需的物理空间,是各group中所有层的page_size_bytes之和的最大值。如,10层全量注意力每层的page为32KiB,共320KiB;5层滑窗注意力每层的page为16KiB,共80KiB,取最大值320KiB,那么每个全局block ID只需要预留320KiB。
DeepSeek V4为了让KV Cache拥有规整的Tensor布局,先定义了tuple。tuple不是新的缓存对象,而是物理布局中的一行page槽位。设rank $r$的Full MLA group中,不同的标准page_size_bytes组成集合$\mathcal{P}_r$,那么一个tuple会为$\mathcal{P}_r$中的每一种page size各预留一个page槽。
例如,标准page size为[100KiB, 200KiB],一个tuple的布局就是:
1 | tuple i: |
因此,一个tuple固定预留100KiB + 200KiB = 300KiB。某个槽当前没有对应的层时,它仍然作为padding存在。
接下来确定需要多少个tuple。vLLM先把每个group内的层按照page_size_bytes放入不同的桶。记$n_{r,g,p}$为rank $r$上,group $g$中落入page-size桶$p$的层数,则最终需要的tuple数为:
$$
T_r = \max_{g \in \mathcal{G}_r,\ p \in \mathcal{P}r} n{r,g,p}.
$$
例如,100KiB桶中有10层,200KiB桶中有5层,那么需要$T_r=10$个tuple:
1 | 100KiB槽 200KiB槽 |
在统计最终的$T_r$之前,vLLM会把SWA、C4、C128等非Full-MLA group的page向上对齐到最近的不小于它的Full MLA标准page size;随后使用_approximate_gcd()选择切分宽度,把这些group拆成若干subgroup,并向上补齐tuple数,以尽量减少padding。完成这些对齐和拆分后,_get_kv_cache_config_deepseek_v4()再按照上面的最大桶长度得到最终$T_r$。
知道tuple大小和tuple数量后,就可以计算rank $r$上一个全局block ID需要预留的物理空间:
$$
S_r = T_r \sum_{p \in \mathcal{P}_r} p.
$$
上例中,一个tuple占300KiB,共10个tuple,所以:
$$
S_r = 10\times(100+200)=3000\text{KiB}.
$$
这比不带padding的理论值$10\times100+5\times200=2000\text{KiB}$多出1000KiB。若$M_r$是该rank可用于KV Cache的显存,那么该rank能够建立的block ID数量为:
$$
N_r = \left\lfloor \frac{M_r}{S_r} \right\rfloor.
$$
所有rank最终采用$\min_r N_r$,避免某个rank收到超过自身容量的block ID。
由此,vLLM确定了每个block的规格和内存需求,可以估算并发请求数,并为block申请内存了。
具体申请显存时,vLLM并不会逐个block地分别申请许多小块显存,而是遍历所有(tuple_idx, page_size)组合。对于每一个组合,vLLM一次性申请一个大小为:
$$
\textit{page_size}\times\textit{num_blocks}
$$
的连续Tensor。这个Tensor可以看成沿着block ID方向排列的num_blocks个page:
1 | (tuple 0, 100KiB): [page 0][page 1][page 2] ... [page N-1] |
其中$N=\textit{num_blocks}$。因此,上例有10个tuple、2种page size,实际会申请$10\times2=20$个连续Tensor;每个Tensor内部包含$N$个page,而不是进行$20\times N$次独立的显存申请。
对于Tensor(tuple_idx, page_size),block ID为$b$的page位于:
$$
\left[b\times\textit{page_size},\ (b+1)\times\textit{page_size}\right).
$$
于是,一个全局block ID并不是一块单独且连续的物理内存。它表示在所有(tuple_idx, page_size) Tensor中取出编号相同的page。例如,block ID 3对应每个Tensor中的page 3;这些page分散在不同Tensor中,合起来才是前文计算出的$S_r$字节。
每个注意力层在布局阶段都会被分配到一个确定的(tuple_idx, page_size)组合,并记录在对应Tensor的shared_by中。模型初始化时,该层会绑定到这个Tensor。运行请求时,该层先通过自己所属block group的block table得到block ID,再用这个block ID索引Tensor中的相应page。因此,层决定使用哪个Tensor,block table决定使用该Tensor中的哪个page。
不同block group中的层可能出现在同一个Tensor的shared_by中,这表示它们使用同一套物理page,但是不会同时占用同一个page。所有block group从同一个全局block池申请block ID:只要block ID 3仍被某个group占用,另一个group就不能再独立申请block ID 3;释放后,这个ID以及各Tensor中对应的page 3才可以被其他group重新使用。
由此,我们就获得了kv_cache_configs,该对象中分rank记载了各GPU上的KV Cache Group信息和对应的张量信息。随后,函数向各Worker发送initialize_kv_cache的调用,各Worker即在自己的GPU上申请张量,并绑定到注意力层。
KV Cache张量申请完成后,模型本身并不会决定一个请求需要多少个新block。这个决定由Scheduler在每轮调度时提前完成,调用链如下:
1 | Scheduler.schedule() |
先考虑普通的全量注意力,不使用推测解码。假设请求已经计算了$N_{computed}$个token,本轮Scheduler又安排它计算$N_{scheduled}$个token,那么本轮结束后,需要为下列数量的token准备KV Cache槽位:
$$
N_{need_slot}=N_{computed}+N_{scheduled}.
$$
如果使用推测解码,还要为模型提前生成、等待主模型验证的候选token预留$N_{lookahead}$个槽位:
$$
N_{need_slot}=N_{computed}+N_{scheduled}+N_{lookahead}.
$$
对于block大小为block_size的KV Cache Group,需要的block总数为:
$$
N_{required}=\left\lceil\frac{N_{need_slot}}{\textit{block_size}}\right\rceil.
$$
设请求已经持有$N_{owned}$个block,其中也包括刚刚命中的前缀缓存block,那么本轮需要新申请的block数为:
$$
N_{new}=\max(N_{required}-N_{owned},0).
$$
源码中的计算对应为:
1 | num_required_blocks = cdiv(num_tokens, self.block_size) |
例如,假设block_size=16,某个请求已经计算了30个token,本轮又被调度了4个token,并且已经持有[7, 11]两个block。本轮结束后共有34个token,因此总共需要:
$$
\left\lceil\frac{34}{16}\right\rceil=3
$$
个block。请求已经持有两个,所以只需要从BlockPool申请一个新block。假设得到block 19,请求的block table就从:
1 | [7, 11] |
变成:
1 | [7, 11, 19] |
如果下一轮又调度5个token,请求的token总数将从34增加到39。$\lceil39/16\rceil$仍然等于3,而请求已经持有三个block,因此该轮不需要申请新block。
DeepSeek V4拥有多个KV Cache Group,Scheduler会让每个Group对应的KV Cache管理器分别执行上述计算。不同Group可以拥有不同的block_size和block table。例如,Full MLA Group可能需要新申请一个block,SWA Group也可能需要新申请一个block;KVCacheCoordinator会把各Group所需的新block数量相加,检查全局BlockPool是否有足够的空闲block ID,再让各Group分别从同一个BlockPool中取得block。对于SWA,allocate_slots()还会先释放已经滑出窗口的旧block,因此其block数量不会随着请求的总长度无限增加。
Scheduler为请求分配完block以后,会为每个KV Cache Group维护一张block table。block table按照token在请求中的先后顺序,记录每一段token实际位于哪个物理block。例如:
1 | block_size = 16 |
对于请求中位置为$p$的token,它位于请求的第几个逻辑block以及block内的偏移分别为:
$$
\textit{logical_block_index}=\left\lfloor\frac{p}{\textit{block_size}}\right\rfloor,
$$
$$
\textit{offset_in_block}=p\bmod\textit{block_size}.
$$
再用logical_block_index查询block table,就能得到实际的物理block ID:
1 | physical_block_id = block_table[logical_block_index] |
在通常的block大小与注意力kernel使用的block大小相同,并且一个请求的KV没有被拆分到多张GPU的情况下,该token在KV Cache Tensor中的一维槽位编号为:
$$
\textit{slot}=\textit{physical_block_id}\times\textit{block_size}+\textit{offset_in_block}.
$$
继续使用上面的例子。本轮计算的4个token位于请求的[30,31,32,33]位置,block table是[7,11,19],因此映射过程是:
1 | token 30 -> 第1个逻辑block -> block 11,offset 14 -> slot 190 |
最终得到:
1 | positions = [30, 31, 32, 33] |
因此,token与block的映射分为两个阶段建立。Scheduler先建立“request到block ID列表”的映射,也就是block table;随后,Scheduler通过SchedulerOutput把block ID和num_computed_tokens交给GPUModelRunner。GPUModelRunner根据每个token的position查询block table,生成“本轮每个token到物理槽位”的slot_mapping。DeepSeek V4使用MultiGroupBlockTable,每个KV Cache Group都有自己的block table,也会分别生成自己的slot_mapping。
更新KV Cache时,注意力层根据slot_mapping把当前token的K和V写入对应槽位;计算注意力时,注意力kernel再根据block table找到该请求的历史KV。因此,后文所说的“整理本轮需要计算的token”,并不是重新决定本轮计算哪些token,而是根据Scheduler已经给出的token数量和num_computed_tokens,从各请求中取出对应token,拼成一次模型forward使用的input_ids,同时计算它们的position、请求边界和slot_mapping。
在exexute_model的执行过程中,模型开始推理前,vLLM会为此次前传做一系列的准备工作,大致如下:
1 | GPUModelRunner.execute_model(scheduler_output) |
例如,假设block_size=16,本轮batch中有两个请求。请求A已经计算了31个token,本轮decode 1个token,其block table为[7, 11];请求B已经计算了16个token,本轮继续prefill 4个token,其block table为[4, 9]。vLLM会先把本轮输入排列为:
1 | [A的1个decode token | B的4个prefill token] |
于是,query_start_loc=[0, 1, 5],表示请求A使用第0个输入token,请求B使用第1~4个输入token;本轮计算完成后的seq_lens=[32, 20]。请求A的新token位于block 11的第15个槽位,请求B的4个新token位于block 9的第0~3个槽位,因此:
1 | slot_mapping = [11×16+15, 9×16+0, 9×16+1, 9×16+2, 9×16+3] |
_build_attention_metadata()先把这些序列长度、block table、query_start_loc和slot_mapping装入CommonAttentionMetadata。随后,它会遍历每个KV Cache Group中的attention group;attention group是使用同一种注意力后端和执行方式的一组层。对于使用FlashInfer的attention group,vLLM会调用FlashInferMetadataBuilder.build()。该函数识别出当前batch包含1个decode token和4个prefill token,并把二维block table整理成FlashInfer能够直接读取的page索引,最终生成FlashInferMetadata。
同一个attention group中的注意力层共享这份metadata。set_forward_context()在模型前传前将其保存到当前的ForwardContext中;执行到某个注意力层时,get_attention_context(layer_name)再按照层名取出该层的metadata、KV Cache Tensor和slot_mapping。
更新KV Cache的入口是unified_kv_cache_update()。在该函数内,首先通过get_attention_context()取得当前的注意力上下文:
1 | _, attn_layer, kv_cache, layer_slot_mapping = get_attention_context(layer_name) |
其中,attn_layer是当前层的Attention或MLAAttention实例,用于取得该层的注意力后端并调用其do_kv_cache_update()方法。kv_cache是初始化时绑定到当前注意力层的KV Cache Tensor,用于保存当前层产生的K和V。layer_slot_mapping记录当前batch中每个token应该写入kv_cache的哪个物理槽位,用于确定K和V的具体写入位置。
然后,就可以调用具体attn_layer的do_kv_cache_update方法完成完成KV Cache的更新。对于FlashInfer,会直接调用C语言编写的op完成计算。最后,再调用attn_layer的unified_attention_with_output方法,该方法会调用对应层的attention实现完成具体的注意力计算。
前缀缓存的查询不在GPUModelRunner.execute_model()中,而是在更早的Scheduler调度阶段。调用链如下:
1 | Scheduler.schedule() |
入口位于Scheduler调度等待请求的代码中:
1 | if request.num_computed_tokens == 0: |
前缀缓存是BlockPool维护的一张查询表:
1 | block hash -> 已经保存了对应KV的KVCacheBlock |
查询表是BlockPool.cached_block_hash_to_block。一个请求创建时,vLLM会按照完整block对token分段。假设block_size=16,prompt为[t0,t1,...,t49],那么可以得到三个完整block的hash:
1 | H0 = hash(t0 ... t15) |
最后两个tokent48、t49无法组成完整block,因此不会生成block hash。后一个block的hash包含前一个block的hash,所以它不仅代表当前16个token,还代表从请求开头到当前block为止的整个前缀。如果前面的token不同,即使当前block中的token相同,hash也不会相同。
除了token,hash还会包含可能改变KV计算结果的信息,例如LoRA、多模态输入、cache_salt和prompt embedding。因此,两次请求只有在这些条件也兼容时才能复用对应的KV Cache。
当一个请求计算出新的完整block后,vLLM会调用:
1 | self.coordinator.cache_blocks(request, num_tokens_to_cache) |
最终由BlockPool.cache_full_blocks()给物理block记录hash,并将其加入查询表:
1 | block_hash_with_group_id = make_block_hash_with_group_id( |
例如,某次计算结束后,查询表中可能有:
1 | (H0, Full Attention Group) -> block 7 |
请求结束后,这些block的引用计数会下降。引用计数变为0时,block进入可回收队列,但是其中的KV和hash暂时保留。此时它没有被请求占用,却仍可以被新的请求命中;只有显存不足、该block被重新分配时,旧hash和KV才会被淘汰。因此,前缀缓存不需要单独建立另一套KV Cache池。
新请求第一次进入Scheduler时,KVCacheManager.get_computed_blocks()将request.block_hashes交给:
1 | self.coordinator.find_longest_cache_hit( |
以普通全量注意力为例,查询过程可以简化为:
1 | for block_hash in block_hashes: |
vLLM从第一个block开始连续查询,遇到第一个未命中的block便停止。由于每个block的hash都包含前一个block的hash,所以不存在跳过中间未命中的block、继续复用后续block的情况。
DeepSeek V4拥有多个KV Cache Group。查询表中的key除了block hash,还包含kv_cache_group_id,因此同一段token在不同Group中可以对应不同的物理block:
1 | (H0, Full MLA Group) -> block 7 |
HybridKVCacheCoordinator会分别检查Full MLA、SWA、C4、C128等注意力类型能够命中多长,然后选择所有类型都能正确使用的公共前缀长度。例如:
1 | Full MLA命中48个token |
之所以只能使用前32个token,是因为从第32个token开始,至少有一个KV Cache Group没有可以复用的KV。
假设block_size=16,新请求的prompt共有50个token,前48个token命中缓存,对应的block ID为[7,11,19]。查询返回:
1 | new_computed_blocks = [block7, block11, block19] |
首先,Scheduler调用:
1 | allocate_slots( |
其中的allocate_new_computed_blocks()会增加block 7、11、19的引用计数,并把它们直接加入新请求的block table。这里不会复制KV数据,新请求与旧缓存直接引用相同的物理page。
随后,Scheduler计算本轮仍需执行的token数:
1 | num_computed_tokens = 48 |
因此,Scheduler不会再调度前48个token,只调度t48、t49,并设置:
1 | request.num_computed_tokens = 48 |
构造SchedulerOutput时,NewRequestData会同时携带命中的block ID、新分配的block ID和已计算token数:
1 | NewRequestData( |
GPUModelRunner据此建立请求状态,所以它在开始forward前就知道前48个token已经计算完成,以及这些token的KV位于哪些物理block。
在_prepare_inputs()中,token位置按照下面的公式计算:
1 | positions = num_computed_tokens + query_pos |
因此,本轮真正送入模型的是:
1 | input_ids = [t48, t49] |
而不是重新送入[t0,t1,...,t49]。最终生成的attention metadata中,block table包含:
1 | [7, 11, 19, 新block] |
执行t48、t49的注意力时,它们新产生的K和V被写入新分配的槽位;FlashInfer则根据block table,从block 7、11、19中直接读取前48个token已有的K和V。前48个token不再经过模型计算。
因此,前缀缓存节省计算的效果是:
1 | 没有前缀缓存:forward 50个token |
查询前,vLLM会设置:
1 | max_cache_hit_length = request.num_tokens - 1 |
即使整个prompt的KV都在缓存中,也必须重新计算最后一部分,否则没有token进入模型forward,便无法得到用于生成下一个token的logits。
例如,prompt恰好包含48个token,三个完整block全部存在于缓存中。理论上可以复用48个token的KV,但为了得到下一个token的logits,至少需要重新计算最后一个token。当前的缓存复用又要求num_computed_tokens按照完整block对齐,因此不能只退回一个token,而会退回一个完整block:
1 | 命中前32个token |
前缀缓存的完整使用过程可以总结为:
1 | 请求创建 |