手写 vLLM 分页 KV Cache(三):引用计数、写时复制(CoW)与前缀缓存
系列导读(全系列收官篇):本系列采用 Top-Down(自顶向下) 的顺序拆解 vLLM 核心机制。在第一篇《Continuous Batching 调度器》中,我们从全局视角看清了请求如何准入、抢占与并发调度;在第二篇《物理块分配与地址映射》中,我们把 KV Cache 切成了固定大小的物理块,并做出了
block_table页表;本篇作为系列收官之作,正式补齐最后一块拼图——物理块如何被多条序列零拷贝共享、共享块写入时如何通过写时复制(CoW)隔离修改,以及前缀缓存(Prefix Cache)如何实现跨请求匹配与惰性失效。全文代码来自我的学习仓库 learn-vllm-paged-kvcache:纯 C++17、零第三方依赖、无需 GPU,
cmake --build之后ctest就能把本文每一项结论跑一遍(61 个单测 + 2 个压力测试,覆盖 Linux/GCC、Windows/MSVC、ThreadSanitizer 三套 CI)。 注:本项目为个人学习复现,与 vLLM 官方项目无关,不含其任何源代码。
0. 承接上文:ref_count > 1 带来的核心挑战
第二篇结尾我们留下了一个关键伏笔。在 BlockAllocator 的视角里,每个物理块只处于三种引用状态之一:
ref_count = 0 → 空闲状态,躺在 free_list_ 中等待分配
ref_count = 1 → 独占状态,仅被单条序列持有
ref_count > 1 → 共享状态,被多条序列同时指向
前两种状态处理起来非常直观;但只要系统里出现了第三种状态(ref_count > 1),所有“往物理块里追加写入新 token”的路径都必须先回答一个问题:直接写下去,会不会把其他序列的历史 KV 数据改坏?
本文围绕这个问题拆解为上下两个半场:
| 上半场:共享与隔离 | 下半场:检索与淘汰 |
|---|---|
| 共享是怎么发生的(三种业务入口) | 共享靠什么自动发现(链式前缀缓存) |
| 共享之后怎么安全写(写时复制 CoW) | 缓存条目怎么高效失效(双字段惰性验证) |
1. 显存共享的三个入口
先看清楚“共享”是从哪里产生的,这是理解整个引用计数生命周期的前提。
入口一:前缀缓存命中(多个请求复用同一段 Prompt)
这是线上推理最高频的场景:同一个 System Prompt 加上几千字的 Few-Shot 模板,几十个并发用户请求的前缀 token 完全一致。
// prefill() 内部复用路径
auto matched = manager.match_prefix(prompt_tokens); // 查询可复用的完整物理块
for(auto id : matched.cached_blocks)
{
allocator->inc_ref(id); // 引用计数 +1,零新块分配
request.block_table.push_back(id);
}
注意这里没有任何 allocate() 调用。多个请求的 block_table 前缀部分直接指向同一批 block_id,对应物理块的 ref_count 随之递增。
入口二:fork_sequence()(Beam Search / Parallel Sampling)
在束搜索(Beam Search)或同 prompt 多路并行采样(n > 1)时,一条父序列在某个时间点需要分叉出多条候选子序列。分叉瞬间,父子序列的历史 KV 完全一致,根本不需要拷贝显存:
Request fork_sequence(Request& father_request, BlockAllocator& allocator)
{
Request son = father_request; // 值拷贝:block_table / all_tokens / seq_len 全部带过来
son.slot_mapping.clear(); // 子序列尚无本步写入槽位,必须清空
for(auto& id : son.block_table) allocator.inc_ref(id); // 每个共享物理块引用计数 +1
return son;
}
由于 Request 采用值语义设计(内部持有 std::vector<int>),Request son = father_request 会深拷贝一份独立的 block_table 列表——父子各自拥有一张页表,后续追加新块互不干扰,但两张页表里登记的物理块号完全重合。
同时注意 son.slot_mapping.clear():正如第二篇强调的,slot_mapping 是仅限当前步的写入地址,父序列上一轮的写入槽位对子序列没有任何意义。
来看仓库 ./build/kvcache_demo 中 fork 前后的实时状态输出:
[2] r2 prefill same prompt: ok=1, hit blocks=2, free=12
r2 block_table=[0(ref=2) 1(ref=2) 3(ref=1)]
[3] fork_sequence(r2) -> ref_count +1 for every block, free still 12
son block_table=[0(ref=3) 1(ref=3) 3(ref=2)]
执行 fork_sequence 后,池子里的空闲块数依然是 12,实现了真正的空间零开销派生。
入口三:空闲块“原地复活”——最微妙的跨波次共享
假设请求 A 占用 2 个物理块跑完生成,调用 release() 将引用计数降为 0,这两个块回到了 free_list_。但此时显存里的 KV 数据和物理块上的哈希元信息并没有被擦除。
几毫秒后,请求 B 带着完全相同的前缀到达,match_prefix() 依然能在哈希表中命中这两个块。此时 prefill() 调用 inc_ref() 把它们“捞回来”:
void BlockAllocator::inc_ref(int block_id)
{
std::lock_guard<std::mutex> lock(alloc_mutex_);
auto& block = blocks_[block_id];
if(block.ref_count == 0) // 关键:块正躺在 free_list_ 里等待分配
{
free_list_.remove(block_id); // 必须先将其从空闲链表摘除,再复活!
}
block.ref_count += 1;
}
如果没有这行 free_list_.remove(block_id),这两个块就会同时处于“已被 B 占用”和“仍在空闲链表中”的分裂状态——下一次 allocate() 会把它们再次分配给请求 C,导致 B 和 C 静默踩踏同一块显存。
单测 test_prefix_hit_after_owner_released 专门锁定了这条路径:A 释放后 B 命中,B 拿到的 block_table[0] 必须严格等于 A 曾经持有的物理块号,且整个过程不消耗新的空闲块。正如我们在第二篇 3.5 节对比过的,这一步在教学仓库里为了代码简洁采用了 的 std::list::remove,而在 vLLM v1 中则演进为了 的侵入式双向链表。
2. 引用计数完整状态机
把上述三条入口与释放路径合在一起,每个物理块的生命周期遵循严格的状态机流转:
stateDiagram-v2
direction LR
[*] --> Free: 初始化(ref=0,挂入 free_list_)
Free --> Allocated: allocate()<br/>ref 0→1,has_hash=false
Free --> Allocated: inc_ref()(缓存复活)<br/>先从 free_list_ 摘除
Allocated --> Shared: inc_ref()<br/>前缀命中 / fork_sequence
Shared --> Allocated: dec_ref()<br/>其他共享者退出,剩最后 1 人
Shared --> Shared: inc_ref()<br/>第 3、4 个共享者加入
Allocated --> Free: dec_ref()<br/>ref→0,归还至 free_list_
Shared --> Free: dec_ref() 逐次归零
整套状态机只遵守两条铁律:
allocate()与inc_ref()都会使引用计数 :区别在于前者从空闲链表头部取走空白块,后者针对已知block_id增加引用(若其引用原为 则顺带摘出空闲链表);dec_ref()绝不清空块内容:仅在ref_count归零时把block_id放回free_list_尾部。
“归零不擦内容”是刻意为之的性能设计:擦除一块显存需要耗费 的带宽,而保留历史内容配合第 4.5 节的惰性失效机制,就能让后续到来的相似请求直接命中复活,零成本白捡计算结果。
3. 共享之后怎么写:为什么只有“尾块”需要 CoW?
上半场的核心问题:当一个物理块的 ref_count > 1 时,其中一条序列在 decode 阶段要往里写入新生成的 token,该如何安全隔离?
3.1 关键论证:已写满的前缀块永远不可变(Immutable)
先看清一个结构性事实:一条序列的 block_table 中,只有最后一个物理块(尾块)处于可写状态。
所有排在尾块之前的物理块,都已经填满了 16 个 token:
- 一旦写满,
append_token()会立刻将其注册进前缀哈希表; - 注册之后,它在任何执行路径下都只读不写,直到所有引用者释放它为止。
因此,共享任意数量的“非尾块”是绝对安全的,永远不会发生写冲突。整个写时复制(Copy-on-Write)机制只需要盯住 block_table.back() 这一个尾块。
对比传统的连续显存分配:一旦两条序列分叉,复制整段历史 KV 的时间复杂度是 ;而在分页机制下,无论序列已经生成了十万个 token,尾块里最多只有 15 个有效 token,CoW 的拷贝代价被严格封死在了 常数级。这是 PagedAttention 在工程上最被低估的红利之一。
3.2 append_slot() 的三个执行分支
int append_slot(BlockManager& manager, Request& request)
{
auto allocator = manager.get_allocator();
int N = request.sequence_length;
int offset = N % BLOCK_SIZE;
int tail_block_logical_id = N / BLOCK_SIZE;
int slot_id = -1;
if(offset == 0)
{
// 分支 A:块边界(上一个块刚好写满),直接申请全新物理块,与共享无关
int new_block_id = allocator->allocate();
if(new_block_id < 0) return -1;
request.block_table.push_back(new_block_id);
slot_id = new_block_id * BLOCK_SIZE + offset;
}
else
{
int tail_id = request.block_table[tail_block_logical_id];
PhysicalBlock& tail = allocator->get_block(tail_id);
if(tail.ref_count == 1)
{
// 分支 B:尾块独占,直接原地追加写入,零额外开销
slot_id = tail_id * BLOCK_SIZE + offset;
}
else
{
// 分支 C:尾块共享(ref_count > 1),触发写时复制(CoW)
int new_block_id = allocator->allocate();
if(new_block_id < 0) return -1;
request.block_table[tail_block_logical_id] = new_block_id;
printf("copy valid tokens to new block\n"); // 真实引擎中调用 copy_blocks 拷贝 [0, offset)
allocator->dec_ref(tail_id); // 必须在替换页表并拷贝完成后再 dec_ref!
slot_id = new_block_id * BLOCK_SIZE + offset;
}
}
request.slot_mapping.clear(); // 契约:每步重建,仅包含本步新写入的物理槽位
request.slot_mapping.push_back(slot_id);
return slot_id;
}
这里有三个极易写错的细节必须点透:
- 分支 A(
offset == 0)必须优先于ref_count判断:当序列长度恰好是 16 的整数倍时,前一个尾块已经彻底写满,新 token 落在下一个全新的逻辑块上,直接allocate()即可,绝对不能对已经写满的旧尾块触发 CoW。 - 分支 C 中
dec_ref(tail_id)必须放在替换与拷贝之后:如果先调dec_ref再拷贝,万一tail_id的引用计数恰好从 降到 甚至归零被回收,后续一旦有并发分配把tail_id领走覆写,拷贝出来的就是别人的脏数据。 - 只拷贝 区间:尾块中
offset之后的槽位尚未写入任何有效 token,无需搬运。真实 vLLM 会通过一个轻量级的copy_blocksGPU Kernel 批量完成这一小段显存的块内拷贝。
3.3 成本分摊规律: 个共享者共支付 次拷贝
这是一个常被误解的规律。因为单测函数名叫 test_cow_only_first_writer_copies,很多人会误以为“只要第一个写入者复制一次,后面所有共享者都能直接原地写”——这个结论仅在 时成立。
更普适的规律是:每个写入者在写入前独立检查 ref_count > 1,成立则拷贝并脱离共享。因此当有 条序列共享同一个未满尾块时:
- 第 个写入者看到
ref_count = N()→ 拷贝新块,原块引用降为 ; - 第 个写入者看到
ref_count = N - 1(若仍 )→ 再次拷贝新块,原块引用降为 ; - ……
- 直到第 个写入者写入时,前面 个人都已“搬家”,它看到的
ref_count == 1→ 直接原地写入,成为原物理块的最终独占者。
整个过程不需要任何额外的状态标志,纯粹依靠引用计数的自然递减,就精确实现了 个共享者总共只需支付 次拷贝的最优分摊:
// test_cow_only_first_writer_copies(N = 2 场景验证)
Request father;
prefill(std::vector<int>(10, 1), father, mgr);
int pb_old = father.block_table[0];
Request son = fork_sequence(father, alloc);
EXPECT_EQ(alloc.get_block(pb_old).ref_count, 2);
int sid_f = decode(mgr, father); // father 先写:看到 ref=2 → 触发 CoW 分裂新块
int sid_s = decode(mgr, son); // son 后写:看到 ref=1 → 不触发 CoW,继承原块
EXPECT_TRUE(father.block_table[0] != pb_old);
EXPECT_EQ(son.block_table[0], pb_old);
EXPECT_EQ(alloc.get_block(pb_old).ref_count, 1);
来看看 demo 输出中 son 触发 CoW 的完整现场:
copy valid tokens to new block
[4] son decodes one token (tail block ref_count>1 -> CoW)
BLK #3 (ref=2) splits -> BLK #4 (ref=1); #3 stays shared by r2 (ref=1)
tail 3 -> 4, slot=72, free=11
son block_table=[0(ref=3) 1(ref=3) 4(ref=1)]
r2 (untouched) block_table=[0(ref=3) 1(ref=3) 3(ref=1)]
son 从空闲池拿走物理块 4 替换了原来的尾块 3,新槽位为 ,与第二篇的寻址公式完全一致;而 r2 依然安静地指着物理块 3,数据一字节未变。这就是写时复制的精髓:读时共享,写时分裂;写的人自己搬家,别人原地不动。
4. 前缀缓存(Prefix Cache):为什么必须是链式哈希?
上半场解决了“拿到共享块后如何安全写入”,下半场解决“系统如何自动识别出哪些历史块可以被复用”。
4.1 为什么不能只对单个物理块的 16 个 token 直接算哈希?
最直觉的想法是:每凑满 16 个 token,就计算 hash(这 16 个 token) 作为 Key 存入哈希表。
这是错误的,会导致严重的静默语义污染。 考虑下面两条序列:
序列 A: [1..16] [17..32]
序列 C: [7] [1..16] ...
序列 A 的第 0 块内容是 [1..16],序列 C 的第 1 块内容也是 [1..16]——两者的 token 序列字节完全一致。但如果让 C 的第 1 块复用 A 的第 0 块 KV,模型输出就会彻底错乱:
- A 的第
0块 KV 是在位置 、且前面没有任何上下文的条件下计算出来的; - C 的第
1块 KV 是在位置 、且前面已经 attend 过 token[7]的条件下计算出来的。
由于旋转位置编码(RoPE)和因果自注意力(Causal Attention)的存在,一个物理块的 KV Cache 不仅取决于它自身包含的 16 个 token,还唯一取决于它前面所有历史前缀 token。
4.2 链式滚动哈希(Chained Hash)
为了把“全部历史前缀”编码进当前块的指纹中,必须把上一块的哈希值作为下一块哈希计算的种子(Seed):
constexpr uint64_t PREFIX_HASH_SEED = 123456789ULL;
constexpr uint64_t BASE = 911382629ULL; // 接近 2^30 的大质数
static uint64_t compute_hash(uint64_t seed, const std::vector<int>& tokens)
{
uint64_t h = seed;
for(int t : tokens) h = h * BASE + static_cast<uint64_t>(t); // 多项式滚动哈希
return h;
}
于是整条序列的块哈希形成了一条单向密码学风格的依赖链:
任何一个 都唯一锚定了从序列开头 0 到 16 * (i + 1) 的完整上下文。由此天然推导出三条核心性质:
- 前缀完全一致:从第
0块开始逐块命中,直到遇到第一个分叉的块为止; - 中间任意一个 token 改变:该块及之后所有块的哈希值发生雪崩式变化,绝不会误命中;
- 确定性可跨进程复用:不使用
std::hash(标准库不保证跨编译器/跨进程哈希种子一致),固定确定性算法确保相同的 token 序列永远算出相同的指纹(vLLM 分布式前缀缓存同样依赖确定性哈希)。
4.3 缓存注册:register_block(request, begin)
void BlockManager::register_block(Request& request, int begin)
{
const auto& tokens = request.all_tokens;
int valid = std::min<int>(request.sequence_length, tokens.size());
int full_blocks = std::min<int>(valid / BLOCK_SIZE, request.block_table.size());
uint64_t seed = PREFIX_HASH_SEED;
for(int i = 0; i < full_blocks; i++)
{
size_t start = size_t(i) * BLOCK_SIZE;
seed = compute_hash(seed, slice_vec(tokens, start, start + BLOCK_SIZE));
if(i < begin) continue; // 前 begin 块已登记过,仅向后推进哈希链
int phys = request.block_table[i];
hash_to_block_[seed] = phys; // 全局映射:chain_hash → block_id
auto& block = allocator_->get_block(phys);
block.hash = seed; // 在物理块元数据上同步记录双字段
block.has_hash = true;
}
request.num_cached_blocks = std::max(request.num_cached_blocks, full_blocks);
}
这里有三个值得注意的工程细节:
begin参数的跳过逻辑:因为哈希是链式的,计算第i块的指纹必须从第0块一路递推下来;但前begin块(在prefill()时是命中的前缀块,在append_token()时是此前已注册的块)无需重复写表,只需推进seed即可。- 只缓存写满的整块:
full_blocks = valid / BLOCK_SIZE向下取整,末尾未满 16 个 token 的半块绝不注册。原因很简单:半块内容还在随 decode 步进变化,哈希尚未稳定(因此 40 个 token 的 prompt 只能缓存前 2 块共 32 个 token)。 - 覆盖写更新:
hash_to_block_[seed] = phys直接覆盖旧条目——如果同一段前缀之前对应的物理块已被回收并重新分配给别人,新块覆盖旧映射完全符合预期。
4.4 只读前缀匹配:match_prefix()
BlockManager::PrefixMatch BlockManager::match_prefix(const std::vector<int>& prompt_tokens)
{
size_t full_block_nums = prompt_tokens.size() / BLOCK_SIZE;
uint64_t seed = PREFIX_HASH_SEED;
PrefixMatch matched;
for(size_t i = 0; i < full_block_nums; i++)
{
size_t start = i * BLOCK_SIZE;
seed = compute_hash(seed, slice_vec(prompt_tokens, start, start + BLOCK_SIZE));
auto it = hash_to_block_.find(seed);
if(it == hash_to_block_.end()) break; // 链条在此断裂,后续块不可能命中
const auto& block = allocator_->get_block(it->second);
if(!block.has_hash || block.hash != seed) // 双字段惰性失效校验
{
hash_to_block_.erase(it); // 顺手清理过期映射
break;
}
matched.cached_blocks.push_back(it->second);
matched.num_matched_tokens += BLOCK_SIZE;
}
return matched;
}
为什么一旦某个块没命中就必须立刻 break,而不能继续往后找?
因为第 块的哈希种子依赖于第 块的全部内容。如果第 块已经分叉,哪怕第 块的 16 个 token 碰巧与缓存中某条记录相同,它们的前缀上下文也已经不同了——链式哈希从数学上保证了后续块绝不可能合法命中。
此外,match_prefix() 被严格设计为无状态副作用(只读,不修改 ref_count)。正因如此,第一篇调度器里的准入估算函数 blocks_needed_for_prefill() 才能安全地调用它做预探测,而不会污染引用计数(对应单测 test_prefix_match_prefix_is_readonly)。
4.5 惰性失效:has_hash + hash 双字段校验
回顾第二篇 3.3 节埋下的伏笔:当一个物理块被释放回 free_list_,随后又被 allocate() 分配给一个全新请求时,我们并没有在 allocate() 时去全局哈希表 hash_to_block_ 里删除旧记录(那需要维护额外的 block_id -> hash 反向索引,增加热路径开销)。
取而代之的是双字段惰性失效(Lazy Invalidation):
- 分配时清开关:
allocate()拿到空闲块时,仅执行block.has_hash = false;; - 查询时做核验:
match_prefix()查到hash_to_block_[seed] = block_id后,反向核对物理块自身的元数据是否满足block.has_hash == true && block.hash == seed。
为什么必须同时核验 has_hash 和 hash 两个字段?
- 如果物理块被重新分配后尚未写满登记新哈希,此时
block.has_hash == false→ 校验失败,说明块内容已被覆写,旧缓存失效; - 如果物理块被重新分配后已经写满并登记了另一段前缀的新哈希,此时
block.has_hash重新变成了true,但block.hash已经变成了新前缀的指纹(!= seed)→ 校验同样失败!
单测 test_prefix_stale_after_realloc 在一个仅有 2 块的极限显存池里完整验证了这两种覆盖场景:请求 A 释放后,请求 C 占满这两块并覆盖写入新内容,随后请求 B 带着 A 的前缀来查,精确返回 0 命中,彻底杜绝脏数据串台。
5. 三个最容易写错的边界陷阱
- OOM 回滚必须调用
release()(逐块dec_ref),严禁调用free(): 当一条请求通过前缀缓存命中了 2 个共享块(ref_count从 ),随后在分配第 3 个新块时遇到显存不足(OOM),回滚路径必须只把自己加上的那 1 次引用减掉。若误用强制清零的free(),会把其他正常请求正在使用的共享块直接扔回空闲链表,引发灾难性内存踩踏(单测test_prefix_oom_rollback_keeps_shared_refs专盯此边界)。 - 准入探测与实际复用的引用计数语义差异:
match_prefix()返回的命中块中,既可能包含正被其他活跃请求持有的块(ref_count > 0),也可能包含刚释放进free_list_等待复活的块(ref_count == 0)。实际prefill()时两者统一调inc_ref()即可;但在第一篇调度器的准入阶段,必须像blocks_needed_for_prefill()那样只把ref_count > 0的块算作“零空闲块消耗”,因为复活ref_count == 0的块依然会摘走一个空闲块。 fork_sequence()必须完整拷贝all_tokens与num_cached_blocks: 子序列派生后继续 decode 写满新块时,会调用register_block(son, son.num_cached_blocks)从第0块重新递推链式哈希。如果派生时漏拷了父序列的all_tokens,子序列算出的链式哈希就会完全错误,进而覆盖污染全局hash_to_block_映射表。
6. 量化收益:跨批次复用演示
在仓库 ./build/kvcache_demo 的 B 段演示中,我们设置了 32 个物理块的显存池,连续运行两波各 3 个请求(共享 48 token 公共前缀 = 3 个完整物理块):
common prefix: 48 tokens (= 3 full blocks)
[wave 1] 3 requests, all with the identical 48-token prompt
step= 1 running=3 waiting=0 free=29 preemptions=0
wave 1:
req prompt max_new generated cached_blk state
#0 48 2 2 3 FINISHED
#1 48 2 2 3 FINISHED
#2 48 2 2 3 FINISHED
peak usage 6 blocks = 3 shared prefix + 3 private decode (12 without sharing)
[wave 2] 3 requests: 48-token common prefix + 16 private tokens (4 blocks each)
req#0 pre-check before submit: 3 of 4 blocks already cached
- 波次一(同批共享):3 个各需 4 块的请求,无共享时峰值需要 块;开启前缀缓存后,3 个请求共用 3 块公共前缀 + 各自 1 块私有 decode 块,峰值仅占用 6 块,显存占用直接腰斩。
- 波次二(跨波复活):波次一全部结束、所有块引用归零回到
free_list_后,波次二的新请求在提交前探测,依然能 100% 命中前 3 块缓存,跳过重复 prefill 计算。
7. 与 vLLM 官方实现的架构对照
| 设计维度 | 本项目实现 | vLLM 官方实现(v0 / v1) | 工程权衡分析 |
|---|---|---|---|
| 哈希算法 | 多项式滚动哈希 | v0:hash((parent_hash, tuple(tokens)))v1:支持 SHA256 / 内置确定性 BlockHash | 均要求跨进程确定性,禁止依赖随机化 std::hash |
| 失效策略 | 惰性失效:分配时清 has_hash,查询时核验并剔除 | v0:回收时主动删表 v1:基于引用计数与哨兵哈希惰性驱逐 | 惰性失效省去了 block_id -> hash 反向索引,代码更干净 |
| 空闲队列与复活 | std::list FIFO, remove 摘除 | v1 free_block_queue:侵入式双向链表, 摘除 | 生产环境物理块数万级, 指针操作消除扫描瓶颈 |
| CoW 显存拷贝 | 打印调试占位(模拟层无真实张量) | copy_blocks CUDA Kernel 仅搬运 | 分页将拷贝代价锁定为 常数 |
| 缓存淘汰 | 无 LRU(未命中覆盖时自然淘汰) | 严格 LRU 驱逐(按时间戳淘汰最久未用空闲块) | 本项目聚焦机制闭环,未引入淘汰统计 |
8. 测试覆盖矩阵
kvcache_phase1_3_test 的 42 个单测中,有 26 个高密度用例专门验证本篇的共享、CoW 与前缀缓存语义:
| 测试分组 | 代表用例 | 核心验证断言 |
|---|---|---|
| 序列派生(4) | fork_inc_ref / fork_release_one / fork_chain_stress / fork_independent_growth | 1 父 3 子高频并发 decode 下引用计数严格配平,页表增长互不干扰 |
| 写时复制(4) | cow_full_tail_no_copy / cow_partial_tail_trigger / cow_only_first_writer_copies / cow_after_which_release | 验证 次拷贝规律、满尾块不触发 CoW、分裂后旧块引用正确递减 |
| 前缀缓存(18) | prefix_block_order_matters / prefix_stale_after_realloc / prefix_hit_after_owner_released / prefix_oom_rollback_keeps_shared_refs / prefix_match_prefix_is_readonly / prefix_fork_then_decode_with_cache | 链式顺序敏感性、重分配后惰性失效、释放后复活、OOM 回滚不破坏他人引用、只读探测无副作用 |
9. 坦诚的已知限制
inc_ref的 链表扫描:free_list_.remove(block_id)在块数上万时存在线性扫描开销,已在 Roadmap 中规划重构为侵入式双向链表。- 哈希表无主动淘汰上限:缺少 LRU 驱逐器,长期运行下未再被命中的旧哈希键会滞留在
hash_to_block_中直到被新内容覆写淘汰。 - 无哈希碰撞二次校验:64 位多项式哈希理论碰撞概率约为 ,工程教学场景未附加逐 token 二次比对兜底。
- 全局命中率指标缺失:目前仅在单个
Request内部记录num_cached_blocks,尚未汇总全局缓存命中率与块利用率面板。
10. 全系列收官:从调度器到存储层的完整闭环
写到这里,三篇从零手写 vLLM 分页 KV Cache 的核心脉络已经彻底闭合。回顾我们走过的 Top-Down 路径,三层架构严丝合缝地咬合在了一起:
- 顶层策略与并发控制(第一篇):
Scheduler在每个step()中以每步重算的视图驱动 Continuous Batching,通过can_append()预判显存水位,在资源见底时果断抢占队尾(preempt)并依赖保留的all_tokens实现无损重算;同时用严谨的加锁顺序与step_hook_ -> promise::set_value()时序消除多线程数据竞争。 - 中层地址映射与分配原语(第二篇):
BlockAllocator与Request页表将逻辑上连续的 token 序列打散进固定 16 槽的物理块中,把内部碎片上限死死按在 个槽位内,并通过幂等的release()保证异常回滚路径零显存泄漏。 - 底层零拷贝共享与缓存复用(本篇):依靠
ref_count三态流转、尾块 常数级写时复制(CoW)以及带双字段惰性失效的链式前缀哈希,让不同请求之间能够跨批次安全共享历史 KV Cache。
最重要的是,整套系统不仅“能跑通”,更通过四条全局不变量检查与大小池差分对拍,用工程测试证明了高并发抢占重算下的输出确定性。
11. 仓库与全系列导航
- GitHub 开源仓库:laoyeye831/learn-vllm-paged-kvcache(纯 C++17 / 零依赖 / 61 单测 + 2 压测 / Linux GCC + Windows MSVC + TSan 三套 CI)
- 一键运行完整演示:编译后执行
./build/kvcache_demo(支持--paced分步交互讲解),2 秒内完整呈现前缀复用、fork分裂、CoW 写时复制、跨波次缓存复活以及显存受限下的抢占重算全过程。 - 延伸阅读文档:仓库内
docs/VLLM_MAPPING.md提供了与 vLLM 官方源码的逐符号对照表;docs/DEVLOG.md记录了完整的 7 天开发与踩坑复盘日志。
《手写 vLLM 分页 KV Cache》全系列导航(Top-Down 拆解)
- 第一篇(已完结):全局调度器 —— Continuous Batching、抢占重算、并发控制与差分验证
- 第二篇(已完结):显存切分与物理块分配 —— BlockAllocator、Block Table、Slot Mapping 与 vLLM v1 链表演进
- 第三篇(本篇 · 全系列收官):显存共享与写时复制 —— 引用计数生命周期、CoW 尾块分裂与链式前缀缓存
本项目为个人学习复现,与 vLLM 官方项目无关,不包含 vLLM 的任何源代码。