手写 vLLM 分页 KV Cache(二):深入物理块分配、Block Table 与 Slot Mapping

0 阅读2分钟

手写 vLLM 分页 KV Cache(二):深入物理块分配、Block Table 与 Slot Mapping

系列导读:本系列采用 Top-Down(自顶向下) 的顺序拆解 vLLM 核心机制。在第一篇《手写 Continuous Batching 调度器》中,我们站在全局视角看清了请求如何流转、显存不足时如何抢占重算;本篇向下深潜一层,把“KV Cache 在显存里如何切块、如何通过页表寻址、以及物理块分配器如何管理生命周期”从零推演一遍;第三篇再展开跨请求共享与写时复制(CoW)。

全文代码来自我的学习仓库 learn-vllm-paged-kvcache:纯 C++17、零第三方依赖、无需 GPU,cmake --build 之后 ctest 就能把本文每个结论跑一遍(61 个单测 + 2 个压力测试,覆盖 Linux/GCC、Windows/MSVC、ThreadSanitizer 三套 CI)。 注:本项目为个人学习复现,与 vLLM 官方项目无关,不含其任何源代码。


0. 先看一眼要解决的问题

Transformer 在 decode 阶段有一个核心特征:生成第 tt 个 token 时,前面 t−1t - 1 个 token 的 Key 和 Value 向量完全不变。因此没有任何推理引擎会每步重算整个历史前缀——把算过的 K/V 缓存下来,每步只计算新增那一个 token 的 K/V,再与历史缓存做注意力计算(Attention)。

这份“存下来的历史 K/V”就是 KV Cache,它的显存占用量级非常惊人:

KV Bytes=2×层数×注意力头数×head_dim×序列长度×dtype_size\text{KV Bytes} = 2 \times \text{层数} \times \text{注意力头数} \times \text{head\_dim} \times \text{序列长度} \times \text{dtype\_size}

以一个典型的 7B 模型配置(32 层、32 头、head_dim = 128、FP16 半精度)来算:

2×32×32×128×2 bytes=512 KB / token2 \times 32 \times 32 \times 128 \times 2\text{ bytes} = 512\text{ KB / token}

仅仅一条 4096 token 的请求,光 KV Cache 就要吃掉 2 GB2\text{ GB} 显存。一张 24 GB24\text{ GB} 的消费级显卡,扣掉模型权重后,同时能塞下的并发请求往往只有十来条。

于是问题变成:这动辄几个 GB 的 KV Cache 如何在显存里摆放? 摆放方式直接决定了三件事——显存利用率有多高、碎片有多严重、以及多请求之间能不能共享前缀。这就是 PagedAttention 要解决的核心问题。

为了不被 CUDA 核函数与张量搬运细节淹没主线,本项目用整数模拟代替真实张量:物理块的状态机(ref_count、空闲链表、前缀哈希、映射表)100% 真实运行,KV 内容用确定性整数模拟。这样不到 400 行 C++ 就能把整套内存管理与地址转换推演清楚,并且能做到逐槽位精确对拍。


1. 朴素方案:按 max_len 预留连续显存

在 PagedAttention 出现之前,最直觉的做法和早期操作系统给进程分配内存如出一辙:每个请求进来时,按它可能达到的最大长度(max_seq_len),在显存里预留一整段连续空间。

请求 A(max_len = 4096,实际只生成到 200 个 token)
┌──────────────────────────────────────────────────────────┐
│ ████ 200 个 token 的 KV │░░░░░░░ 3896 个 token 的空洞 ░░░│
└──────────────────────────────────────────────────────────┘

这种静态连续分配有三个致命缺陷,一个比一个痛。

① 内部碎片:高达 95% 的显存空转

预留 4096 个槽位,实际只用 200 个,剩下 3896 个槽位在整个请求生命周期内只能被它独占,别人看得到用不着。这不是极端特例——真实线上流量的输入输出长度分布极度长尾,按最大长度预留意味着所有请求都在按最长规格占坑。

② 外部碎片:总空闲够用,但凑不出连续空间

即使显存里加起来还有 4 GB4\text{ GB} 空闲,只要它们被切碎成几段不连续的空洞,新的长请求依然无法准入。连续分配对物理地址连续性的硬约束,随着请求不断到达和结束会迅速把显存切成“瑞士奶酪”。

③ 彻底无法共享(最本质的短板)

假设 100 个并发请求共用了同一段 2000 token 的 System Prompt,在连续内存模型下,系统必须老老实实存 100 份一模一样的 KV 副本。Prefix Cache(前缀缓存)、Beam Search(束搜索)、Parallel Sampling(并行采样)全部无从谈起——共享的前提是“多条逻辑序列指向同一段物理显存”,而“一整段连续私有缓冲区”模型里根本没有页表映射这一层抽象。

核心洞察:分页机制(Paging)最根本的动机不是为了省那点碎片,而是为了让“跨序列零拷贝共享”成为可能,消除外部碎片只是水到渠成的副产品。


2. 分页三件套:用“页表”解耦逻辑与物理

借鉴操作系统的虚拟内存分页,PagedAttention 把 KV Cache 切成固定大小的物理块(Block),请求不再直接拥有一段连续显存,而是持有一张逻辑块到物理块的映射表。

2.1 核心数据结构

constexpr int BLOCK_SIZE = 16; // 每个物理块固定存放 16 个 token 的 KV

struct Request
{
    std::vector<int> block_table;  // 逻辑块号 → 物理块号(block_id)
    std::vector<int> slot_mapping; // 本步要写入的物理槽位号(每步重建)
    std::vector<int> all_tokens;   // prompt + 已生成 token
    int sequence_length{0};
    int num_cached_blocks{0};      // block_table 开头已命中/已注册缓存的块数
    // ...
};
概念职责定位操作系统类比
物理块(Physical Block)显存池中一块固定容纳 16 个 token 的空间,用 block_id 索引物理页帧(Page Frame)
block_table记录当前序列的第 0,1,2,…0, 1, 2, \dots 个逻辑块分别映射到哪个 block_id进程页表(Page Table)
slot_mapping仅限本步要写入的新 token 在一维展平 KV Cache 里的物理槽位下标散射写入地址表

slot_mapping 是初学者最容易理解错的字段:它不是历史所有 token 的地址累积,而是“这一步有几个新 token 需要写 KV,它们各自该写进显存池的哪个槽”。

2.2 寻址公式

所有物理块在底层显存池中按 block_id 连续排列,每块占据 BLOCK_SIZE 个槽位。因此任意一个 token 的全局物理槽位号为:

slot_id=physical_block_id×BLOCK_SIZE+offset_in_block\text{slot\_id} = \text{physical\_block\_id} \times \text{BLOCK\_SIZE} + \text{offset\_in\_block}

推导成代码非常干净:

// prefill 阶段为每个 prompt token 计算物理写入槽位
for(int t = 0; t < N; t++)
{
    int logical_block_idx = t / BLOCK_SIZE;   // 落在第几个逻辑块
    int offset            = t % BLOCK_SIZE;   // 块内第几个槽位
    int phys              = request.block_table[logical_block_idx];
    int slot_id           = phys * BLOCK_SIZE + offset;
    request.slot_mapping.push_back(slot_id);
}

这套计算出的 slot_mapping 最终会传给底层 Attention Kernel,等效于执行一次散射写入(Scatter):

kv_cache[slot_id] = new_token_kv; // 将本步算出的 K/V 写入对应的物理槽位

2.3 图解地址映射

假设 BLOCK_SIZE = 16,某条请求有 40 个 prompt token,分配到的物理块依次为 0、1、3:

flowchart LR
    subgraph L[&#34;逻辑视图(40 tokens)&#34;]
        L0[&#34;逻辑块 0<br/>token 0–15&#34;]
        L1[&#34;逻辑块 1<br/>token 16–31&#34;]
        L2[&#34;逻辑块 2<br/>token 32–39(未满)&#34;]
    end
    subgraph T[&#34;block_table = [0, 1, 3]&#34;]
        T0[&#34;[0] → 0&#34;]
        T1[&#34;[1] → 1&#34;]
        T2[&#34;[2] → 3&#34;]
    end
    subgraph P[&#34;物理显存池(每块 16 槽)&#34;]
        P0[&#34;物理块 0<br/>槽 0–15&#34;]
        P1[&#34;物理块 1<br/>槽 16–31&#34;]
        P3[&#34;物理块 3<br/>槽 48–63<br/>仅使用 48–55&#34;]
    end
    L0 --> T0 --> P0
    L1 --> T1 --> P1
    L2 --> T2 --> P3

对应的 slot_mapping 结果为:

token  0..15 → slot  0..15      (物理块 0)
token 16..31 → slot 16..31      (物理块 1)
token 32..39 → slot 48..55      (物理块 3)

注意:物理块 3 中剩下的 8 个槽位(56..63)在当前步虽然空着,但不能分给其他请求使用。这就是分页机制唯一的内部碎片代价——每条请求最多只会在最后一个未满块上浪费 BLOCK_SIZE−1\text{BLOCK\_SIZE} - 1 个槽位。

40 个 token 占用 3 块(48 槽),浪费 8 槽(约 16.7%16.7\%)。更重要的是,这个浪费上界是常数级封顶的——即便序列长到 100,000 token,内部碎片依然最多只有 15 个槽位。

2.4 向上取整的工程写法

40 个 token 需要 ⌈40/16⌉=3\lceil 40 / 16 \rceil = 3 个块。代码里统一写作:

int block_nums = (N + BLOCK_SIZE - 1) / BLOCK_SIZE; // 整数向上取整

这个公式贯穿了 prefill、调度器准入估算与不变量检查。千万不要图省事写成 N / BLOCK_SIZE + 1——当 NN 恰好是 16 的整数倍时,后者会凭空多算出一整块。

2.5 开发踩坑:slot_mapping 必须每步清空重建

我在 Day 1 写第一版时,误把 slot_mapping 当成了历史累积数组,每次 decode 都往后 push_back。结果跑到第 20 步时数组里攒了几十个槽号,而 decode kernel 每次只生成 1 个 token,期望拿到的 slot_mapping 长度必须严格等于 1。

修正后的契约非常清晰:slot_mapping 每步清空重建,只装本步新产生 token 的写入地址。因此 append_slot() 入口的第一行就是清空:

request.slot_mapping.clear(); // 清空上一轮的槽位映射
request.slot_mapping.push_back(slot_id);

Prefill 一次写入 NN 个 token,slot_mapping.size() == N;Decode 每步写入 1 个 token,slot_mapping.size() == 1。语义完全统一。


3. 物理块分配器(BlockAllocator)

有了页表映射,还需要一个管家来追踪“哪些物理块空闲、哪些正在被多少条序列共享”。这就是 BlockAllocator。

3.1 物理块元信息

struct PhysicalBlock
{
    int block_id;
    int ref_count{0};          // 引用计数:当前有多少条活跃序列指向该块
    uint64_t last_accessed{0}; // 预留时间戳(用于 LRU 淘汰,当前未使用)
    uint64_t hash{0};          // 前缀缓存中该块对应的链式哈希值
    bool has_hash{false};      // 当前是否仍有效登记在前缀缓存哈希表中
};

这里故意不包含任何 KV 缓存指针或数据数组:在真实推理引擎中,BlockAllocator 同样只管理纯元数据,GPU 显存里预先开辟好一块形如 [num_blocks, 2, num_layers, num_heads, BLOCK_SIZE, head_dim] 的大张量,block_id 直接作为第一维下标索引显存。两者在架构上是完全正交的。

3.2 空闲链表与状态流转

class BlockAllocator
{
private:
    std::vector<PhysicalBlock> blocks_;
    std::list<int> free_list_;          // 空闲块链表
    mutable std::mutex alloc_mutex_;
};

初始化时,编号 0 .. num_blocks - 1 的所有物理块 ref_count 均为 0,并全部挂入 free_list_。每个物理块在整个生命周期内只在三种引用状态间流转:

  • ref_count == 0:空闲状态,位于 free_list_ 中等待分配(但旧的 KV 内容和哈希标签可能仍保留在块上);
  • ref_count == 1:独占状态,仅被一条序列持有,可直接原地追加写入;
  • ref_count > 1:共享状态,被多条序列通过前缀缓存或派生(Fork)共同持有,只读不可原地修改。

3.3 allocate():取走空闲块与惰性失效

int BlockAllocator::allocate()
{
    std::lock_guard<std::mutex> lock(alloc_mutex_);
    if(free_list_.empty()) return -1;          // 显存耗尽,返回 -1 而非抛异常

    int id = free_list_.front();
    free_list_.pop_front();

    auto& block = blocks_[id];
    block.ref_count += 1;
    block.has_hash = false;                    // 物理块即将被覆写,旧哈希标签失效
    return id;
}

这里有两个关键的工程设计:

  1. 为什么显存耗尽返回 -1,而不是抛异常? 在推理调度中,“空闲块不足”是高频出现的正常控制流,而不是程序异常。用 -1 作为返回值,上层可以直接用 if (id < 0) 触发回滚或抢占(正如我们在第一篇 preempt() 中看到的);若改用异常,高频抢占场景下的栈展开开销和调用链 try-catch 污染会非常难看。
  2. 为什么要顺手把 has_hash 置为 false? 一块刚刚释放进 free_list_ 的物理块,它的 hash 字段和前缀缓存映射表里的记录并没有被立刻擦除——因为如果下一个请求恰好命中同一段前缀,它还能直接“复活”(见 3.5 节)。只有当这块物理内存真正被 allocate() 分配出去准备覆写新数据时,旧缓存才算彻底失效。这种**惰性失效(Lazy Invalidation)**省去了释放时反查哈希表的开销,第三篇我们会详细展开它的双字段校验机制。

3.4 释放路径:dec_ref() 的幂等保护

void BlockAllocator::dec_ref(int block_id)
{
    std::lock_guard<std::mutex> lock(alloc_mutex_);
    auto& block = blocks_[block_id];
    if(block.ref_count <= 0) return;       // 幂等保护:防止重复释放导致双重入链
    block.ref_count -= 1;
    if(block.ref_count == 0) free_list_.push_back(block_id); // 引用归零才真正归还
}

void BlockAllocator::free(int block_id)    // 强制直接回收(调试/特殊清理路径)
{
    std::lock_guard<std::mutex> lock(alloc_mutex_);
    auto& block = blocks_[block_id];
    if(block.ref_count == 0) return;
    block.ref_count = 0;
    free_list_.push_back(block_id);
}

所有正常业务释放一律走 dec_ref()。其中的 if (block.ref_count <= 0) return; 是一道关键防线:一旦某个 bug 触发了两次释放,没有这行保护就会把同一个 block_id 塞进 free_list_ 两次,随后同一块物理内存会被分配给两个毫不相干的请求,引发静默的数据踩踏——这是并发内存管理中最难排查的 Bug 之一。

3.5 inc_ref():让刚释放的块“原地复活”

下面这段代码是 Prefix Cache 能够跨请求复用的关键:

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;
}

想象这样一个场景:请求 A 用 2 个块跑完生成并结束,调用 release() 后引用计数归零,这两个块回到了 free_list_ 尾部。但显存里的 KV 数据和块上的哈希标签都还在。几毫秒后,请求 B 带着完全相同的 32 个 token 前缀到达,前缀匹配器精准命中了这两个块。

此时调用 inc_ref(block_id),发现它的 ref_count == 0——说明它正躺在空闲链表里等待被别人领走。如果只把 ref_count 加成 1 却忘了把它从 free_list_ 摘出来,下一次 allocate() 就会把它当成空闲块再分配给请求 C,导致 B 和 C 踩踏同一块显存!

性能取舍与 vLLM v1 演进对比: 注意上面这行 free_list_.remove(block_id)——在 std::list<int> 上按值删除需要从头到尾线性扫描,时间复杂度为 O(n)O(n)(nn 为当前空闲块数)。 在我们的教学仓库里,物理块数量通常在几十到几百之间,O(n)O(n) 扫描微不足道,换来的是标准库容器的零心智负担;但在生产环境中,单卡显存池动辄数万个块,每次缓存复活都扫一遍链表不可接受。因此 vLLM v1 彻底抛弃了标准库链表,改为侵入式双向链表(Intrusive Doubly-Linked List):直接在每个 PhysicalBlock 内部嵌入 prev_free_block 和 next_free_block 指针,拿到 block_id 后直接 O(1)O(1) 修改前后节点指针即可完成摘除,且全程零堆内存分配。


4. 串起完整链路:走一遍 prefill() 与 append_slot()

现在把三件套和分配器组装起来,看一条新请求进入系统时的完整动作:

bool prefill(const std::vector<int>& prompt_tokens, Request& request, BlockManager& manager)
{
    auto allocator = manager.get_allocator();
    manager.release(request);                     // ① 幂等清理:支持被抢占请求重新 prefill

    int N = static_cast<int>(prompt_tokens.size());
    if(N == 0) return true;

    int block_nums = (N + BLOCK_SIZE - 1) / BLOCK_SIZE;
    request.block_table.reserve(block_nums);

    // ② 查询前缀缓存,尽可能复用已有物理块
    auto matched = manager.match_prefix(prompt_tokens);
    int matched_blocks_num = static_cast<int>(matched.cached_blocks.size());

    for(auto id : matched.cached_blocks)
    {
        allocator->inc_ref(id);                   // 命中块增加引用(若在 free_list_ 中则顺带摘除)
        request.block_table.push_back(id);
    }

    // ③ 剩余未命中的逻辑块,从空闲链表新分配
    for(int i = matched_blocks_num; i < block_nums; i++)
    {
        int temp_id = allocator->allocate();
        if(temp_id < 0)                           // 分配失败 → 必须整体回滚!
        {
            manager.release(request);
            return false;
        }
        request.block_table.push_back(temp_id);
    }

    request.all_tokens = prompt_tokens;
    // ④ 计算本步所有 prompt token 的物理写入槽位
    for(int t = 0; t < N; t++)
    {
        int logical = t / BLOCK_SIZE;
        int offset  = t % BLOCK_SIZE;
        request.slot_mapping.push_back(request.block_table[logical] * BLOCK_SIZE + offset);
    }
    request.sequence_length = N;
    request.num_cached_blocks = matched_blocks_num;

    // ⑤ 将本次新写满的整块注册进前缀缓存,供后续请求复用
    manager.register_block(request, matched_blocks_num);
    return true;
}

这段 45 行的函数里藏着四个必须说透的工程细节:

4.1 为什么入口第一行要先 release(request)?

因为 prefill() 不仅服务于首次到达的新请求,还服务于第一篇讲过的“被抢占后重新恢复的请求”。调用方传入的可能是同一个 Request 对象,先调一次幂等的 release() 清空旧状态,能确保任何重入路径都不会发生引用计数累加泄漏。

4.2 失败路径的原子回滚(All-or-Nothing)

假设一条请求需要 3 个块,前缀命中了 1 个块(执行了 inc_ref),新分配了第 2 个块(allocate 成功),到第 3 个块时显存耗尽返回 -1。如果此时直接 return false,前 2 个块的引用就永远泄漏在外面了。

调用 manager.release(request) 会遍历当前已放入 request.block_table 的所有块逐一 dec_ref(),把状态精确回滚到调用 prefill() 之前。单测 test_prefill_out_of_memory_rollback 专门验证了这一点:2 块容量的池子尝试 prefill 48 个 token(需 3 块)失败后,空闲块数必须严格保持为 2。

4.3 release() 刻意保留 all_tokens

void BlockManager::release(Request& req)
{
    for(int id : req.block_table) allocator_->dec_ref(id);
    req.block_table.clear();
    req.slot_mapping.clear();
    req.sequence_length = 0;
    req.num_cached_blocks = 0;
    // 刻意不清空 req.all_tokens!
}

sequence_length 归零、物理块全部归还,但 all_tokens 完整保留——这正是第一篇调度器 preempt() 能够实现无损重算的基石。

4.4 为什么只有“写满的整块”才注册前缀缓存?

第 ⑤ 步 register_block() 只会注册 sequence_length / BLOCK_SIZE 个完整块,末尾那个没写满的半块绝不登记。

原因很朴素:前缀缓存的哈希是按整块(16 个 token)计算的。一个只写了 8 个 token 的半块,在接下来的 decode 步里还会不断往里填新 token,内容和哈希每步都在变;如果此时登记进哈希表,不仅后续请求根本匹配不上,还会污染缓存映射。

来看仓库中 ./build/kvcache_demo 的实际运行输出,数字严丝合缝地印证了这条规则:

[1] r1 prefill(40 tokens): ok=1, registered full blocks=2, free=13
r1                 block_table=[0(ref=1) 1(ref=1) 2(ref=1)]

[2] r2 prefill same prompt: ok=1, hit blocks=2, free=12
    -> first 2 blocks reuse r1's blocks (ref 1 -> 2), only 1 block is new
r2                 block_table=[0(ref=2) 1(ref=2) 3(ref=1)]

在 16 块的显存池中:

  • r1 输入 40 个 token,占用 3 块([0, 1, 2]),空闲块从 16 降为 13;但因为第 3 块只写了 8 个 token,只有前 2 个整块(32 tokens)注册进了前缀缓存;
  • r2 带着完全相同的 40 个 token 进来,精准命中前 2 块(块 0 和块 1 的 ref_count 从 1 涨到 2,不消耗空闲块),第 3 块无法复用,于是从 free_list_ 头部新分配了块 3,空闲块变为 12。

同时要注意一条关键不变量:两条不同序列的 block_table 可以包含相同的 block_id(共享),但同一条序列的 block_table 内部绝不允许出现重复的 block_id——否则意味着逻辑块 ii 和逻辑块 jj 指向同一块物理内存,后续写入会直接覆盖自己的历史 KV。

4.5 Decode 单步分配:append_slot() 三分支

Prefill 完成后,每生成一个新 token 都要先调用 append_slot() 申请写入槽位:

sequence_length % 16尾块 ref_count执行动作显存代价
=0= 0—上一块已写满,新 allocate() 一块追加到 block_table 尾部消耗 1 块
≠0\neq 0=1= 1尾块未满且当前序列独占,直接计算槽位原地写入0
≠0\neq 0>1> 1触发 CoW:分配新块、拷贝尾块已有 token、替换表尾、原块 dec_ref消耗 1 块 + 拷贝

第三种 CoW 分支正是我们下一篇要拆解的核心机制。


5. 为什么 BLOCK_SIZE 选 16?

在工程实现里,BLOCK_SIZE = 16 不是拍脑袋定出来的,而是一个典型的三向权衡甜点(Sweet Spot):

块尺寸调小(如 BLOCK_SIZE = 1)块尺寸调大(如 BLOCK_SIZE = 128)
内部碎片极小(几乎零浪费)内部碎片变大(单请求最多浪费 127 槽)
block_table 急剧膨胀(4K 长度需 4096 表项)block_table 紧凑,元数据开销小
前缀共享粒度极细,但指针跳转毫无访存局部性前缀必须凑满 128 token 才能共享,命中率下降

极端情况下,如果把 BLOCK_SIZE 设为 1,分页就退化成了逐 token 指针链表:不仅页表本身占用海量显存,Attention Kernel 在读取 K/V 时每读一个 token 都要做一次间接寻址,彻底破坏 GPU 显存的合并访存(Memory Coalescing)。反之若设为 128,短 prompt 场景下内部碎片率会飙升,跨请求共享也会变得非常困难。

16 恰好卡在硬件访存宽度(Warp / Cache Line 对齐)与细粒度共享的平衡点上——这也正是 vLLM 官方长期采用 16 作为默认块大小的根本原因。


6. 怎么验证底层地址计算没写错?

底层地址计算一旦出现差一错误(Off-by-one),程序通常不会崩溃,而是表现成**“模型偶尔胡言乱语、生成质量莫名下降”**——这是大模型推理引擎里最难定位的 Bug 类型。

因此,本项目的 42 个底层单测拒绝“只看运行不报错”的模糊断言,全部采用逐槽位精确算术比对:

// 分配器生命周期与幂等性
test_allocator_allocate_unique       // 连续 allocate 拿到的 block_id 集合必须两两互异
test_allocator_exhaust               // 耗尽后严格返回 -1
test_allocator_reclaim               // dec_ref 归零后物理块重新回到可分配状态
test_allocator_inc_dec_balance       // inc → dec → dec 过程中 ref_count (1→2→1→0) 与空闲数严格配平

// prefill / decode 跨块边界地址计算
test_prefill_empty                   // 0 token 输入:不占块、不报错
test_prefill_one_token               // slot[0] == block_table[0] * 16 + 0
test_prefill_exactly_one_block       // 16 token 恰好占满 1 块,无多余分配
test_prefill_spans_two_blocks        // 17 token 跨越 2 块,第 17 个 token 严格落在第 2 块 offset 0
test_prefill_out_of_memory_rollback  // OOM 失败后空闲块数 100% 还原
test_prefill_reused_request_no_leak  // 同一 Request 重复 prefill,slot_mapping 不累积
test_decode_new_block_at_boundary    // 第 16 → 17 个 token 触发新开块,offset 归零
test_decode_long_sequence            // 103 token 严格占用 ceil(103/16) = 7 块

例如在 test_prefill_spans_two_blocks 中,直接断言每个 token 的物理槽号:

for(int t = 0; t < 16; t++)
    EXPECT_EQ(req.slot_mapping[t], pb0 * BLOCK_SIZE + t);
EXPECT_EQ(req.slot_mapping[16], pb1 * BLOCK_SIZE + 0); // 跨块边界精确对齐

7. 坦诚的已知限制

  • BLOCK_SIZE 为编译期常量:当前通过 constexpr int BLOCK_SIZE = 16 写死,暂不支持运行时按不同模型动态配置块大小。
  • FIFO 空闲队列:BlockAllocator 目前采用先释放先复用的 FIFO 策略,未启用 LRU 淘汰(PhysicalBlock::last_accessed 字段已预留)。
  • inc_ref 存在 O(n)O(n) 链表扫描:free_list_.remove(block_id) 在块数上万时会成为瓶颈,后续可按第 3.5 节所述重构为侵入式双向链表。
  • get_block() 返回非线程安全引用:为减少高频热路径锁开销,get_block() 直接返回 PhysicalBlock&,要求调用方在单线程 step() 上下文中访问。
  • 模拟层未执行真实张量拷贝:CoW 分支目前仅打印调试日志并更新元数据,未分配实际显存缓冲区。

8. 仓库与系列导航

  • GitHub 仓库:laoyeye831/learn-vllm-paged-kvcache(C++17 / 零依赖 / 61 单测 + 2 压测 / Linux GCC + Windows MSVC + TSan CI)
  • 快速演示:编译后运行 ./build/kvcache_demo,其中 A 段完整演示了本篇的块分配、前缀复用与跨块边界增长。
  • 源码对照与开发日志:docs/VLLM_MAPPING.md 逐符号对照了本项目与 vLLM 的实现映射;docs/DEVLOG.md 记录了 Day 1 踩坑 slot_mapping 累积 Bug 的全过程。

本系列完整导航(Top-Down 拆解)

  • 第一篇(已更):全局调度器 —— Continuous Batching、抢占重算、并发控制与差分验证
  • 第二篇(本篇):显存切分与物理块分配 —— BlockAllocator、Block Table、Slot Mapping 与 vLLM v1 链表演进
  • 第三篇(待更):显存共享与写时复制 —— 前缀哈希链式匹配、惰性失效校验、CoW 尾块分裂与 fork_sequence