手写 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 阶段有一个核心特征:生成第 个 token 时,前面 个 token 的 Key 和 Value 向量完全不变。因此没有任何推理引擎会每步重算整个历史前缀——把算过的 K/V 缓存下来,每步只计算新增那一个 token 的 K/V,再与历史缓存做注意力计算(Attention)。
这份“存下来的历史 K/V”就是 KV Cache,它的显存占用量级非常惊人:
以一个典型的 7B 模型配置(32 层、32 头、head_dim = 128、FP16 半精度)来算:
仅仅一条 4096 token 的请求,光 KV Cache 就要吃掉 显存。一张 的消费级显卡,扣掉模型权重后,同时能塞下的并发请求往往只有十来条。
于是问题变成:这动辄几个 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 个槽位在整个请求生命周期内只能被它独占,别人看得到用不着。这不是极端特例——真实线上流量的输入输出长度分布极度长尾,按最大长度预留意味着所有请求都在按最长规格占坑。
② 外部碎片:总空闲够用,但凑不出连续空间
即使显存里加起来还有 空闲,只要它们被切碎成几段不连续的空洞,新的长请求依然无法准入。连续分配对物理地址连续性的硬约束,随着请求不断到达和结束会迅速把显存切成“瑞士奶酪”。
③ 彻底无法共享(最本质的短板)
假设 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 | 记录当前序列的第 个逻辑块分别映射到哪个 block_id | 进程页表(Page Table) |
slot_mapping | 仅限本步要写入的新 token 在一维展平 KV Cache 里的物理槽位下标 | 散射写入地址表 |
slot_mapping 是初学者最容易理解错的字段:它不是历史所有 token 的地址累积,而是“这一步有几个新 token 需要写 KV,它们各自该写进显存池的哪个槽”。
2.2 寻址公式
所有物理块在底层显存池中按 block_id 连续排列,每块占据 BLOCK_SIZE 个槽位。因此任意一个 token 的全局物理槽位号为:
推导成代码非常干净:
// 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["逻辑视图(40 tokens)"]
L0["逻辑块 0<br/>token 0–15"]
L1["逻辑块 1<br/>token 16–31"]
L2["逻辑块 2<br/>token 32–39(未满)"]
end
subgraph T["block_table = [0, 1, 3]"]
T0["[0] → 0"]
T1["[1] → 1"]
T2["[2] → 3"]
end
subgraph P["物理显存池(每块 16 槽)"]
P0["物理块 0<br/>槽 0–15"]
P1["物理块 1<br/>槽 16–31"]
P3["物理块 3<br/>槽 48–63<br/>仅使用 48–55"]
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)在当前步虽然空着,但不能分给其他请求使用。这就是分页机制唯一的内部碎片代价——每条请求最多只会在最后一个未满块上浪费 个槽位。
40 个 token 占用 3 块(48 槽),浪费 8 槽(约 )。更重要的是,这个浪费上界是常数级封顶的——即便序列长到 100,000 token,内部碎片依然最多只有 15 个槽位。
2.4 向上取整的工程写法
40 个 token 需要 个块。代码里统一写作:
int block_nums = (N + BLOCK_SIZE - 1) / BLOCK_SIZE; // 整数向上取整
这个公式贯穿了 prefill、调度器准入估算与不变量检查。千万不要图省事写成 N / BLOCK_SIZE + 1——当 恰好是 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 一次写入 个 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作为返回值,上层可以直接用if (id < 0)触发回滚或抢占(正如我们在第一篇preempt()中看到的);若改用异常,高频抢占场景下的栈展开开销和调用链try-catch污染会非常难看。 - 为什么要顺手把
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>上按值删除需要从头到尾线性扫描,时间复杂度为 ( 为当前空闲块数)。 在我们的教学仓库里,物理块数量通常在几十到几百之间, 扫描微不足道,换来的是标准库容器的零心智负担;但在生产环境中,单卡显存池动辄数万个块,每次缓存复活都扫一遍链表不可接受。因此 vLLM v1 彻底抛弃了标准库链表,改为侵入式双向链表(Intrusive Doubly-Linked List):直接在每个PhysicalBlock内部嵌入prev_free_block和next_free_block指针,拿到block_id后直接 修改前后节点指针即可完成摘除,且全程零堆内存分配。
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——否则意味着逻辑块 和逻辑块 指向同一块物理内存,后续写入会直接覆盖自己的历史 KV。
4.5 Decode 单步分配:append_slot() 三分支
Prefill 完成后,每生成一个新 token 都要先调用 append_slot() 申请写入槽位:
sequence_length % 16 | 尾块 ref_count | 执行动作 | 显存代价 |
|---|---|---|---|
| — | 上一块已写满,新 allocate() 一块追加到 block_table 尾部 | 消耗 1 块 | |
| 尾块未满且当前序列独占,直接计算槽位原地写入 | 0 | ||
触发 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存在 链表扫描: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