vLLM 源码精读：KV Cache 管理层 —— 从门面到 block_pool 的调用链

1. 四层架构总览

vLLM V1 的 KV Cache 管理由四个 Python 文件协作完成，共约 3200 行代码：

2. KVCacheManager：对外门面

KVCacheManager 是 Scheduler 跟 KV Cache 子系统之间的唯一接口。它不包含分配逻辑，只做路由 + 状态记录。

对外暴露的核心方法

3. KVCacheCoordinator：多 group 协调者

为什么需要 Coordinator

一个模型可能有多个 KV cache group，比如：

• 混合模型：部分层用 Full Attention、部分层用 Mamba
• 不同层有不同的 block_size

每个 group 有自己独立的 SingleTypeKVCacheManager 和 BlockPool。Coordinator 负责：

4. SingleTypeKVCacheManager：抽象基类

这是承载最多业务逻辑的文件（1407 行）。使用模板方法模式：基类定义流程骨架，子类 override 差异化部分。

抽象方法：子类必须实现

有默认实现的核心方法

5. FullAttention vs SlidingWindow：关键差异

所有子类中，FullAttentionManager（约 60 行）和 SlidingWindowManager 是最核心的两个。它们的差异就在 find_longest_cache_hit 的实现上。

FullAttentionManager

前缀匹配策略：从左到右，逐个 block 检查 hash 是否命中块池缓存。
找到第一个 miss → 返回命中 block 数 = i。

原理：标准全注意力中，每个 token 依赖全部历史 context。
前缀的 KV 跟后面的 token 重新生成无关。

SlidingWindowManager

前缀匹配策略：从右到左，在 window 范围内逐个 block 匹配。
找到最长的连续命中 → 返回命中 block 数。

原理：滑动窗口注意力中，每个 token 只看固定窗口（如 4096）内的历史。
窗口外的历史 token 即使内容相同也不算命中——因为对新 token 没有影响。

6. 四条核心路径走读

路径一：Prefill 阶段分配新 block

Scheduler: 一个新请求进来，prompt 100 token
    │
    ▼
KVCacheManager.prefill_allocation(request):
    │
    ▼
KVCacheCoordinator:
    │  ① hash_block_size 取 min → 统一 hash 粒度
    │  ② 对每个 group: SingleTypeKVCacheManager.allocate_slots()
    ▼
SingleTypeKVCacheManager:
    │  ① 算前缀命中: find_longest_cache_hit → touch 命中 block
    │  ② 算要分配的: get_num_blocks_to_allocate
    │  ③ 分配物理: block_pool.get_new_blocks()
    │  ④ 建立映射: block_table[i] = physical_block
    ▼
BlockPool:
    │  ① free_block_queue.popleft_n(n)
    │  ② _maybe_evict_cached_block 清旧 hash
    │  ③ ref_cnt = 1

路径二：Decode 阶段追加 token

Scheduler: RUNNING 请求生成 1 个新 token
    │
    ▼
KVCacheManager 路由 → Coordinator 分发 → SingleTypeKVCacheManager.append_slots()
    │
    ├── 最后一个 block 还有空位 → 直接填入，不需要新 block ⚡ 快路径
    │
    └── 最后一个 block 已满
        ├── 判断 free_blocks 是否够（扣除预留）
        ├── 够 → block_pool.get_new_blocks(1) → 加入 block_table
        └── 不够 → 返回 None → Scheduler 走抢占

路径三：前缀命中的处理

新请求 arrive → KVCacheManager → Coordinator → SingleTypeKVCacheManager
    │
    │  find_longest_cache_hit:
    │    for each block (左→右 for FullAttention):
    │      调用 get_cached_block(hash) 查 block_pool 的 hash map
    │      命中 → 继续
    │      miss → break，返回命中的 block 数
    │
    │  命中 block = touch(blocks):
    │    ref_cnt == 0 → 从 free_queue 移除（不能再被驱逐了）
    │    ref_cnt += 1
    │
    │  其余 token → 走路径一分配新 block

路径四：请求结束释放

Scheduler: 请求完成
    │
    ▼
KVCacheManager.free(request_id)
    │
    ▼
Coordinator 分发 → SingleTypeKVCacheManager.free()
    │
    │  ① 收集该请求所有 block (block_table 里所有物理 block)
    │  ② 调用 block_pool.free_blocks(blocks, prepend=False)
    ▼
BlockPool:
    │  ① block.ref_cnt -= 1
    │  ② ref_cnt == 0 → 加入 free_block_queue（append）
    │  ③ hash 保留！← Lazy Eviction

7. 论文映射

8. ⭐ 高频卡点答疑

9. 参考资料

• 源码：kv_cache_manager.py / kv_cache_coordinator.py / single_type_kv_cache_manager.py / block_pool.py
• 上一篇：08 · block_pool.py 源码精读
• 下一篇：10 · vLLM 调度器源码精读（Scheduler 的 RUNNING/WAITING/抢占/收尾全流程）

这是 Stage 1 / Week 2 的第三篇，对应 AI Infra 转型学习计划"读 vLLM 源码"任务。