手写 vLLM 分页 KV Cache(三):引用计数、写时复制(CoW)与前缀缓存

0 阅读6分钟

手写 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 节对比过的,这一步在教学仓库里为了代码简洁采用了 O(n)O(n) 的 std::list::remove,而在 vLLM v1 中则演进为了 O(1)O(1) 的侵入式双向链表。


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() 逐次归零

整套状态机只遵守两条铁律:

  1. allocate() 与 inc_ref() 都会使引用计数 +1+1:区别在于前者从空闲链表头部取走空白块,后者针对已知 block_id 增加引用(若其引用原为 00 则顺带摘出空闲链表);
  2. dec_ref() 绝不清空块内容:仅在 ref_count 归零时把 block_id 放回 free_list_ 尾部。

“归零不擦内容”是刻意为之的性能设计:擦除一块显存需要耗费 O(BLOCK_SIZE)O(\text{BLOCK\_SIZE}) 的带宽,而保留历史内容配合第 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 的时间复杂度是 O(seq_len)O(\text{seq\_len});而在分页机制下,无论序列已经生成了十万个 token,尾块里最多只有 15 个有效 token,CoW 的拷贝代价被严格封死在了 O(BLOCK_SIZE)O(\text{BLOCK\_SIZE}) 常数级。这是 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;
}

这里有三个极易写错的细节必须点透:

  1. 分支 A(offset == 0)必须优先于 ref_count 判断:当序列长度恰好是 16 的整数倍时,前一个尾块已经彻底写满,新 token 落在下一个全新的逻辑块上,直接 allocate() 即可,绝对不能对已经写满的旧尾块触发 CoW。
  2. 分支 C 中 dec_ref(tail_id) 必须放在替换与拷贝之后:如果先调 dec_ref 再拷贝,万一 tail_id 的引用计数恰好从 22 降到 11 甚至归零被回收,后续一旦有并发分配把 tail_id 领走覆写,拷贝出来的就是别人的脏数据。
  3. 只拷贝 [0,offset)[0, \text{offset}) 区间:尾块中 offset 之后的槽位尚未写入任何有效 token,无需搬运。真实 vLLM 会通过一个轻量级的 copy_blocks GPU Kernel 批量完成这一小段显存的块内拷贝。

3.3 成本分摊规律:NN 个共享者共支付 N−1N - 1 次拷贝

这是一个常被误解的规律。因为单测函数名叫 test_cow_only_first_writer_copies,很多人会误以为“只要第一个写入者复制一次,后面所有共享者都能直接原地写”——这个结论仅在 N=2N = 2 时成立。

更普适的规律是:每个写入者在写入前独立检查 ref_count > 1,成立则拷贝并脱离共享。因此当有 NN 条序列共享同一个未满尾块时:

  • 第 11 个写入者看到 ref_count = N(>1> 1)→ 拷贝新块,原块引用降为 N−1N - 1;
  • 第 22 个写入者看到 ref_count = N - 1(若仍 >1> 1)→ 再次拷贝新块,原块引用降为 N−2N - 2;
  • ……
  • 直到第 NN 个写入者写入时,前面 N−1N - 1 个人都已“搬家”,它看到的 ref_count == 1 → 直接原地写入,成为原物理块的最终独占者。

整个过程不需要任何额外的状态标志,纯粹依靠引用计数的自然递减,就精确实现了 NN 个共享者总共只需支付 N−1N - 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,新槽位为 4×16+8=724 \times 16 + 8 = 72,与第二篇的寻址公式完全一致;而 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 是在位置 0∼150 \sim 15、且前面没有任何上下文的条件下计算出来的;
  • C 的第 1 块 KV 是在位置 1∼161 \sim 16、且前面已经 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;
}

于是整条序列的块哈希形成了一条单向密码学风格的依赖链:

h0=H(SEED, tokens[0:16])h1=H(h0, tokens[16:32])h2=H(h1, tokens[32:48])\begin{aligned} h_0 &= H(\text{SEED},\ \text{tokens}[0:16]) \\ h_1 &= H(h_0,\ \text{tokens}[16:32]) \\ h_2 &= H(h_1,\ \text{tokens}[32:48]) \end{aligned}

任何一个 hih_i 都唯一锚定了从序列开头 0 到 16 * (i + 1) 的完整上下文。由此天然推导出三条核心性质:

  1. 前缀完全一致:从第 0 块开始逐块命中,直到遇到第一个分叉的块为止;
  2. 中间任意一个 token 改变:该块及之后所有块的哈希值发生雪崩式变化,绝不会误命中;
  3. 确定性可跨进程复用:不使用 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,而不能继续往后找? 因为第 i+1i + 1 块的哈希种子依赖于第 ii 块的全部内容。如果第 ii 块已经分叉,哪怕第 i+1i + 1 块的 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):

  1. 分配时清开关:allocate() 拿到空闲块时,仅执行 block.has_hash = false;;
  2. 查询时做核验: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. 三个最容易写错的边界陷阱

  1. OOM 回滚必须调用 release()(逐块 dec_ref),严禁调用 free(): 当一条请求通过前缀缓存命中了 2 个共享块(ref_count 从 1→21 \to 2),随后在分配第 3 个新块时遇到显存不足(OOM),回滚路径必须只把自己加上的那 1 次引用减掉。若误用强制清零的 free(),会把其他正常请求正在使用的共享块直接扔回空闲链表,引发灾难性内存踩踏(单测 test_prefix_oom_rollback_keeps_shared_refs 专盯此边界)。
  2. 准入探测与实际复用的引用计数语义差异: match_prefix() 返回的命中块中,既可能包含正被其他活跃请求持有的块(ref_count > 0),也可能包含刚释放进 free_list_ 等待复活的块(ref_count == 0)。实际 prefill() 时两者统一调 inc_ref() 即可;但在第一篇调度器的准入阶段,必须像 blocks_needed_for_prefill() 那样只把 ref_count > 0 的块算作“零空闲块消耗”,因为复活 ref_count == 0 的块依然会摘走一个空闲块。
  3. 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×4=123 \times 4 = 12 块;开启前缀缓存后,3 个请求共用 3 块公共前缀 + 各自 1 块私有 decode 块,峰值仅占用 6 块,显存占用直接腰斩。
  • 波次二(跨波复活):波次一全部结束、所有块引用归零回到 free_list_ 后,波次二的新请求在提交前探测,依然能 100% 命中前 3 块缓存,跳过重复 prefill 计算。

7. 与 vLLM 官方实现的架构对照

设计维度本项目实现vLLM 官方实现(v0 / v1)工程权衡分析
哈希算法多项式滚动哈希 h=h×BASE+th = h \times \text{BASE} + tv0:hash((parent_hash, tuple(tokens)))
v1:支持 SHA256 / 内置确定性 BlockHash
均要求跨进程确定性,禁止依赖随机化 std::hash
失效策略惰性失效:分配时清 has_hash,查询时核验并剔除v0:回收时主动删表
v1:基于引用计数与哨兵哈希惰性驱逐
惰性失效省去了 block_id -> hash 反向索引,代码更干净
空闲队列与复活std::list FIFO,O(n)O(n) remove 摘除v1 free_block_queue:侵入式双向链表,O(1)O(1) 摘除生产环境物理块数万级,O(1)O(1) 指针操作消除扫描瓶颈
CoW 显存拷贝打印调试占位(模拟层无真实张量)copy_blocks CUDA Kernel 仅搬运 [0,offset)[0, \text{offset})分页将拷贝代价锁定为 O(BLOCK_SIZE)O(\text{BLOCK\_SIZE}) 常数
缓存淘汰无 LRU(未命中覆盖时自然淘汰)严格 LRU 驱逐(按时间戳淘汰最久未用空闲块)本项目聚焦机制闭环,未引入淘汰统计

8. 测试覆盖矩阵

kvcache_phase1_3_test 的 42 个单测中,有 26 个高密度用例专门验证本篇的共享、CoW 与前缀缓存语义:

测试分组代表用例核心验证断言
序列派生(4)fork_inc_ref / fork_release_one / fork_chain_stress / fork_independent_growth1 父 3 子高频并发 decode 下引用计数严格配平,页表增长互不干扰
写时复制(4)cow_full_tail_no_copy / cow_partial_tail_trigger / cow_only_first_writer_copies / cow_after_which_release验证 N−1N - 1 次拷贝规律、满尾块不触发 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 的 O(n)O(n) 链表扫描:free_list_.remove(block_id) 在块数上万时存在线性扫描开销,已在 Roadmap 中规划重构为侵入式双向链表。
  • 哈希表无主动淘汰上限:缺少 LRU 驱逐器,长期运行下未再被命中的旧哈希键会滞留在 hash_to_block_ 中直到被新内容覆写淘汰。
  • 无哈希碰撞二次校验:64 位多项式哈希理论碰撞概率约为 2−642^{-64},工程教学场景未附加逐 token 二次比对兜底。
  • 全局命中率指标缺失:目前仅在单个 Request 内部记录 num_cached_blocks,尚未汇总全局缓存命中率与块利用率面板。

10. 全系列收官:从调度器到存储层的完整闭环

写到这里,三篇从零手写 vLLM 分页 KV Cache 的核心脉络已经彻底闭合。回顾我们走过的 Top-Down 路径,三层架构严丝合缝地咬合在了一起:

  1. 顶层策略与并发控制(第一篇):Scheduler 在每个 step() 中以每步重算的视图驱动 Continuous Batching,通过 can_append() 预判显存水位,在资源见底时果断抢占队尾(preempt)并依赖保留的 all_tokens 实现无损重算;同时用严谨的加锁顺序与 step_hook_ -> promise::set_value() 时序消除多线程数据竞争。
  2. 中层地址映射与分配原语(第二篇):BlockAllocator 与 Request 页表将逻辑上连续的 token 序列打散进固定 16 槽的物理块中,把内部碎片上限死死按在 BLOCK_SIZE−1\text{BLOCK\_SIZE} - 1 个槽位内,并通过幂等的 release() 保证异常回滚路径零显存泄漏。
  3. 底层零拷贝共享与缓存复用(本篇):依靠 ref_count 三态流转、尾块 O(BLOCK_SIZE)O(\text{BLOCK\_SIZE}) 常数级写时复制(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 拆解)


本项目为个人学习复现,与 vLLM 官方项目无关,不包含 vLLM 的任何源代码。