vLLM 源码精读：block_pool.py —— PagedAttention 的灵魂组件

1. 文件定位：block_pool.py 在整个 vLLM 中的角色

vLLM V1 的 KV Cache 管理分三层：

block_pool.py 对应论文 §4.2 KV Cache Manager 中的 Block Allocator——管理物理 block 的分配、释放、引用计数和 Prefix Cache 索引。它不关心"哪个请求用了哪个 block"（那是上层 kv_cache_manager 的事），只关心"物理 block 池子里还有多少空闲、谁能复用"。

2. 全局架构图：两个类，三个核心数据结构

文件里有两个类：

三个核心数据结构：

3. BlockHashToBlockMap：Prefix Cache 的索引

数据结构

class BlockHashToBlockMap:
    self._cache: dict[
        BlockHashWithGroupId,              # key = (block_hash, group_id)
        KVCacheBlock | dict[int, KVCacheBlock]  # value = 单个 block 或多个 block
    ]

key 是什么？ (block_hash, group_id) 的组合。block_hash 基于 block 内 token id 序列计算，group_id 标识 KV cache 组（多头 attention 可以分组管理）。

value 为什么是 union 类型？ 大多数情况下一个 hash 只对应一个 block（直接存 KVCacheBlock）。极少数情况下同一个 hash 有多个 block（存 dict[block_id, KVCacheBlock]）。代码注释说得很清楚：这么做是为了减少 GC 开销——单个 block 时不创建 dict 对象。

三个核心方法

4. BlockPool.__init__：初始化时发生了什么

def __init__(self, num_gpu_blocks, enable_caching, hash_block_size, ...):
    # 1. 创建全部物理 block（一次性预分配）
    self.blocks = [KVCacheBlock(idx) for idx in range(num_gpu_blocks)]

    # 2. 全部 block 放进空闲链表
    self.free_block_queue = FreeKVCacheBlockQueue(self.blocks)

    # 3. 创建空的 hash 索引
    self.cached_block_hash_to_block = BlockHashToBlockMap()

    # 4. 取一个 block 出来作为 null_block（占位用）
    self.null_block = self.free_block_queue.popleft()
    self.null_block.is_null = True

几个要点：

• 一次性预分配：所有物理 block 在 init 时就创建好（对应 GPU 侧的 block engine 预分配连续显存）。后续分配/释放只是在空闲链表上移动指针，不涉及真正的显存申请/释放。
• null_block：从 pool 里拿出 1 个 block 作为占位符（详见 §10）。这意味着实际可用的 block 数 = num_gpu_blocks - 1。
• enable_caching：开关。关闭时不做 Prefix Cache（不算 hash、不查索引），分配/释放走简单路径。

5. get_new_blocks：从 pool 里拿空闲 block

def get_new_blocks(self, num_blocks: int) -> list[KVCacheBlock]:
    # 检查空闲数量
    if num_blocks > self.get_num_free_blocks():
        raise ValueError(...)

    # 从空闲链表左端取 n 个
    ret = self.free_block_queue.popleft_n(num_blocks)

    for block in ret:
        # 如果开启了缓存，取出的 block 可能还带着旧 hash → 驱逐它
        if self.enable_caching:
            self._maybe_evict_cached_block(block)
        assert block.ref_cnt == 0
        block.ref_cnt += 1   # 标记为"被使用"
    return ret

核心逻辑：

1. 从空闲链表的左端取 block（FIFO 顺序——最早释放的最先被重新分配）
2. 如果开了 Prefix Cache，取出来的 block 可能还在 hash map 里（lazy eviction 的结果）——此时要先把它从 hash map 清除
3. ref_cnt 从 0 变为 1

6. free_blocks：释放 block（但不一定真删）

def free_blocks(self, ordered_blocks, prepend=False):
    for block in blocks_list:
        block.ref_cnt -= 1         # 引用计数减 1

    # 只有 ref_cnt 真正到 0 的才放回空闲链表
    freed_blocks = [
        block for block in blocks_list
        if block.ref_cnt == 0 and not block.is_null
    ]

    if prepend:
        self.free_block_queue.prepend_n(freed_blocks)  # 放到队列前端（优先被重用）
    else:
        self.free_block_queue.append_n(freed_blocks)   # 放到队列尾部（最后被重用）

核心逻辑：

1. ref_cnt - 1，不是直接释放。如果还有其他序列引用（Beam Search / Parallel Sampling 共享），减完后 ref_cnt > 0，不释放。
2. ref_cnt 到 0 才真正归还空闲链表。
3. 不从 hash map 删除——block 的 hash 还留着（Lazy Eviction）。下次有新请求前缀匹配时还能命中。
4. prepend 参数控制优先级：prepend=True 放到队列前端，意味着会被优先重新分配（用于被抢占请求的 block——这些 block 不太可能被复用，优先回收）。

7. touch：Prefix Cache 命中时的处理

def touch(self, blocks: Sequence[KVCacheBlock]):
    for block in blocks:
        if block.ref_cnt == 0 and not block.is_null:
            # ref_cnt=0 说明在空闲链表里（eviction candidate）
            # 命中了 → 从空闲链表移除（不能被驱逐了）
            self.free_block_queue.remove(block)
        block.ref_cnt += 1

场景：新请求到来，其前缀的 hash 在 Prefix Cache 中命中了。命中的 block 可能 ref_cnt=0（之前的请求已结束，block 在空闲链表里等待驱逐）。此时：

1. 把 block 从空闲链表中移除（不能被驱逐了，因为有新用户了）
2. ref_cnt + 1

8. cache_full_blocks：block 写满后注册到 hash map

这是 Prefix Cache 的写入路径。当一个 block 被 token 填满后，需要计算 hash 并注册到索引中。

def cache_full_blocks(self, request, blocks, num_cached_blocks,
                      num_full_blocks, block_size, kv_cache_group_id, ...):
    # 只处理新变满的 block（跳过已经缓存的）
    new_full_blocks = blocks[num_cached_blocks:num_full_blocks]

    for i, blk in enumerate(new_full_blocks):
        if blk.is_null:  # 跳过空 block（SWA 等稀疏 attention 场景）
            continue

        block_hash = new_block_hashes[i]

        # 给 block 打上 hash 标记
        block_hash_with_group_id = make_block_hash_with_group_id(
            block_hash, kv_cache_group_id)
        blk.block_hash = block_hash_with_group_id

        # 注册到 hash map
        self.cached_block_hash_to_block.insert(
            block_hash_with_group_id, blk)

核心逻辑：

1. 只处理区间 [num_cached_blocks, num_full_blocks) 里的 block——已经 cache 过的不重复处理
2. 跳过 null block（稀疏 attention 场景如 SWA 可能有 null block）
3. 给 block 设置 block_hash 属性
4. 注册到 cached_block_hash_to_block hash map
5. 如果开了 KV Cache Events（分布式场景），还会发 BlockStored 事件通知其他节点

9. _maybe_evict_cached_block：延迟驱逐（Lazy Eviction）

def _maybe_evict_cached_block(self, block: KVCacheBlock) -> bool:
    block_hash = block.block_hash
    if block_hash is None:
        return False  # 没有 hash，不需要驱逐

    # 从 hash map 中移除
    if self.cached_block_hash_to_block.pop(
            block_hash, block.block_id) is None:
        return False  # hash map 里找不到，不需要驱逐

    block.reset_hash()  # 清除 block 上的 hash 元数据
    return True

调用时机：在 get_new_blocks 中，当一个空闲 block 被重新分配时。

完整的 Lazy Eviction 生命周期：

10. null_block：一个特殊的占位 block

# 初始化时取出一个 block 作为 null_block
self.null_block = self.free_block_queue.popleft()
self.null_block.is_null = True

null_block 是什么？ 一个"占位符"block，block_id=0。用于以下场景：

• 稀疏 attention（如 Sliding Window Attention）：不是所有层都需要 KV cache，不需要 cache 的位置用 null_block 占位
• Mamba 等非 attention 模型的 prefix caching align mode
• 逻辑上需要一个 block table 条目但物理上不需要存储数据时

特殊规则：

• null_block 的 ref_cnt 不维护（代码里有注释：needs special care to avoid freeing it）
• free_blocks 里过滤掉 is_null 的 block，不放回空闲链表
• touch 里也跳过 null_block
• get_usage 里总数减 1 扣掉 null_block

11. 论文到代码的完整映射

12. ⭐ 高频卡点答疑（8 个 Q）

13. 参考资料

• 源码文件：vllm/v1/core/block_pool.py（GitHub 链接）
• 依赖文件：vllm/v1/core/kv_cache_utils.py（KVCacheBlock / FreeKVCacheBlockQueue 定义）
• 上一篇博客：07 · PagedAttention 论文精读
• 下一篇预告：博客 09 · vLLM 源码精读：kv_cache_manager.py（block_pool 的上层调用者）

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