vLLM 源码完全拆解（二十二）：BlockPool——空闲块队列、LRU 淘汰与引用计数如何管住整块 KV

前情提要

这个系列已经沿着 vLLM V1 的源码走过了调度、块管理与前向的大部分环节：可参考 vLLM 源码完全拆解（三）：Scheduler.schedule 如何分配 Token 预算与 KV Block，以及 vLLM 源码完全拆解（四）：KVCacheManager 如何分配、复用与回收物理 Block。在那两篇里，KVCacheManager 是主角，它按请求的 token 预算决定“该给谁分配几块、从哪里找前缀命中、不够了该抢占谁”。

但 KVCacheManager 本身并不持有任何一个物理块。真正存放全部 KVCacheBlock 对象、维护空闲块链表、记录引用计数、执行前缀哈希淘汰的，是 vllm/v1/core/block_pool.py 里的 BlockPool。前几篇在讨论“分配与回收闭环”时，把它当作一个黑盒仓库一笔带过。这一篇把这个仓库本身打开：一块 KV 缓存在它的整个生命里会经历哪些状态，空闲块按什么顺序被取出，引用计数在什么时候增减，哈希表里的条目在什么时候被抹掉，以及这些细节与站内讲过的块表、槽映射如何衔接（见 KV 块的三张映射表：逻辑块号、物理块号与 KV 槽号如何串成一条 64 位索引）。

先划定边界：BlockPool 不知道注意力内核长什么样，不知道分页寻址，也不知道 HTTP 层；它唯一的工作是把 num_gpu_blocks 个整数编号的物理块当成可借可还的资源来管。V1 架构中，KVCacheManager 负责“记账的策略”，BlockPool 负责“记账的账本”。

上图出自 PagedAttention 论文（SOSP 2023）。逻辑上连续的序列被切成固定大小的块，块表把逻辑块映射到物理块。BlockPool 管理的正是右侧那一排物理块的“分配权”：块表里的物理块号必须由它发放，也只有在它允许时才可能被回收。

为什么不直接把物理块做成一个数组加一个空闲计数？因为 vLLM 要同时支撑三件事：前缀缓存要求“块被释放后可能还会被再次命中”；调度器需要 O(1) 的空闲块统计与批量分配；异步传输（KV connector、CPU 卸载）要求“块已被逻辑释放，但内容还能被读一会儿”。三件事叠加，一个计数器远远不够，必须有链表、引用计数与哈希表三套结构协同。本篇按这三套结构逐一展开，最后回到“这些结构如何在一次调度步骤里被调用”。

一块 KV 缓存的一生：状态与字段

KVCacheBlock 定义在 vllm/v1/core/kv_cache_utils.py，是一个 @dataclass。字段不多，但每一个都直接决定这块缓存能被谁用、还能被谁命中。

1
@dataclass
2
class KVCacheBlock:
3
    # Block ID, ranging from 0 to num_gpu_blocks - 1.
4
    block_id: int
5
    # Reference count.
6
    ref_cnt: int = 0
7
    # Deferred frees may contain blocks from multiple pools.
8
    pool: "BlockPool | None" = field(default=None, repr=False, compare=False, kw_only=True)
9
    # The hash key (block hash + group id), only available
10
    # when the block is full and cached.
11
    _block_hash: BlockHashWithGroupId | None = None
12
    # Number of prefix tokens covered by _block_hash.
13
    _block_hash_num_tokens: int | None = None
14
    # Used to construct a doubly linked list for free blocks.
15
    prev_free_block: "KVCacheBlock | None" = None
16
    next_free_block: "KVCacheBlock | None" = None
17
    # Whether the block is a null block that should never be cached.
18
    is_null: bool = False

逐字段解释：

• block_id：池内下标，也是块表、槽映射、KV connector 上报块号时使用的唯一身份。它在池初始化那一刻就固定，内容变了、身份不变。
• ref_cnt：引用计数。谁“正在依赖这块内容”——运行中的请求、前缀命中后的使用者、在途的异步拷贝——都持有一份引用。归零只意味着“没有人再声明依赖”，并不等于“内容被立刻抹掉”。
• pool：块归属的池。V1 允许一个调度器管理多个 BlockPool（不同 KV 组可以有自己的池），释放时可能把属于别的池的块混进同一批列表，free_blocks 靠这个字段分拣。compare=False 让它在比较两个块对象时被忽略。
• _block_hash：前缀哈希键，包含块哈希与组 id。未满块为 None；一旦块被写满并被登记进前缀缓存，它会被设置。
• _block_hash_num_tokens：这个哈希键覆盖的前缀长度。对满块而言就是块边界 token 数；引入部分前缀条目后，同一个块可以挂一个“边界落在块内部”的哈希，因此这个字段是判断“条目已经过时”的依据。
• prev_free_block / next_free_block：双向链表指针。注释写明“只应由 FreeKVCacheBlockQueue 操作”，它们不是一般意义上的前驱后继，而是空闲队列的结构。
• is_null：占位块标记。占位块不持有数据，也永远不进缓存。

对外访问通过属性封装，设置与重置都带断言：

1
@property
2
def block_hash(self) -> BlockHashWithGroupId | None:
3
    return self._block_hash
4

5
def set_block_hash(self, block_hash, num_tokens=None) -> None:
6
    assert self.block_hash is None and self._block_hash_num_tokens is None, (
7
        "The block already has a hash. This should not happen."
8
    )
9
    self._block_hash = block_hash
10
    self._block_hash_num_tokens = num_tokens
11

12
def reset_hash(self):
13
    self._block_hash = None
14
    self._block_hash_num_tokens = None

set_block_hash 的断言是池的核心不变量之一：一个块只能有一个主哈希。需要多级前缀边界时（部分块、不同组块大小的倍数关系），额外哈希走 cached_block_hashes_by_block 这个旁路字典，而不是覆盖主哈希。后面讨论多条目淘汰时会再次用到这个设计。

从生命周期看，一块物理块大致在六种状态之间迁移：

最关键的一列是“能写入”，由 BlockPool.is_block_writable 判定：

1
def is_block_writable(self, block: KVCacheBlock) -> bool:
2
    """Return whether a block can be mutated by its sole owner."""
3
    return not block.is_null and block.ref_cnt == 1 and block.block_hash is None

三个条件缺一不可。is_null 排除占位块；ref_cnt == 1 保证没有别的请求在同时读它——投机解码的目标序列与草稿序列、前缀命中后的复制者都可能在同一份 KV 上同时挂引用；block_hash is None 保证这块内容没有以某个前缀身份被登记，否则原地改写会让那个前缀命中到错误的数据。这个函数在投机解码与部分命中路径中被反复调用。

构造：一次性分配对象与占位块

BlockPool 的构造函数把资源一次性准备到位：

1
self.blocks: list[KVCacheBlock] = [
2
    KVCacheBlock(idx, pool=self) for idx in range(num_gpu_blocks)
3
]
4
self.free_block_queue = FreeKVCacheBlockQueue(self.blocks)
5
self.cached_block_hash_to_block: BlockHashToBlockMap = BlockHashToBlockMap()
6
self.cached_block_hashes_by_block: dict[int, set[BlockHashWithGroupId]] = {}
7
self.null_block = self.free_block_queue.popleft()
8
self.null_block.is_null = True

第一，块对象在启动时一次性创建，运行期不再分配 Python 对象。每个 decode step 的调度循环里没有堆分配，也就没有 GC 压力；池的 Python 侧内存是一份定长列表，真实数据在 GPU 显存里，由 KVCacheManager 在初始化时按层分配。

第二，null_block 把 0 号块从队头摘出来并标记为占位块。占位块的含义是“这个逻辑位置没有有效数据”：滑动窗口注意力中被窗口跳过的前缀、分块本地注意力中被跳过的段、Mamba 混合模型的状态槽位，都会在块表里放占位块。用 block_id = 0 而不是 -1 的理由很实际：块表全是非负整数，内核无需负索引分支；代价是队列里实际可分配的块比 num_gpu_blocks 少一块，因此所有“总量”计算都要减一：

1
def get_usage(self) -> float:
2
    total_gpu_blocks = self.num_gpu_blocks - 1
3
    if not total_gpu_blocks:
4
        return 0
5
    return 1.0 - (self.get_num_free_blocks() / total_gpu_blocks)

get_usage 还有一个细节：它只按空闲队列长度算，不区分队列里的块“是否真的被请求使用”。有哈希的空闲块（缓存候选）也算“已用”。这符合 KV 缓存的实际占用语义，却是排查“利用率一直 100%”时最常见的误解来源——状态表里“空闲、缓存候选”一列正是这种情况的合法状态。

第三，cached_block_hashes_by_block 是“块 id → 额外哈希集合”。它让一个块可以挂多个哈希条目（主哈希一个、旁路若干），并在块被淘汰时把全部条目一次性删除。

reset_prefix_cache 借助占位块做完整性检查：

1
def reset_prefix_cache(self) -> bool:
2
    num_used_blocks = self.num_gpu_blocks - self.get_num_free_blocks()
3
    if num_used_blocks != 1:  # The null block is always marked as used
4
        logger.warning(
5
            "Failed to reset prefix cache because some "
6
            "blocks (%d) are not freed yet", num_used_blocks - 1,
7
        )
8
        return False
9
    self.cached_block_hash_to_block = BlockHashToBlockMap()
10
    self.cached_block_hashes_by_block.clear()
11
    ...

占位块永远“在用”，所以 num_used_blocks != 1 意味着还有请求或异步传输持有块。此时拒绝重置而不是强行清空，是为了避免把仍在写的块登记进一个“已经清空”的缓存。这个接口在 RL 微调更新权重后（旧前缀缓存不再对应新权重），或 benchmark 需要干净起点时使用；后者需要先释放所有请求再调用。

1
class FreeKVCacheBlockQueue:
2
    def __init__(self, blocks: list[KVCacheBlock]) -> None:
3
        self.num_free_blocks = len(blocks)
4
        # Initialize doubly links of consecutive blocks
5
        for i in range(self.num_free_blocks):
6
            if i > 0:
7
                blocks[i].prev_free_block = blocks[i - 1]
8
            if i < self.num_free_blocks - 1:
9
                blocks[i].next_free_block = blocks[i + 1]
10
        # Create a fake head and a tail block for the doubly linked list
11
        # to reduce branching in the code
12
        self.fake_free_list_head = KVCacheBlock(block_id=-1)
13
        self.fake_free_list_tail = KVCacheBlock(block_id=-1)
14
        if self.num_free_blocks > 0:
15
            self.fake_free_list_head.next_free_block = blocks[0]
16
            blocks[0].prev_free_block = self.fake_free_list_head
17
            self.fake_free_list_tail.prev_free_block = blocks[-1]
18
            blocks[-1].next_free_block = self.fake_free_list_tail

1
The queue is ordered by block ID in the beginning. When a block is allocated
2
and then freed, it will be appended back with the eviction order:
3
1. The least recent used block is at the front (LRU).
4
2. If two blocks have the same last accessed time (allocated by the
5
   same sequence), the one with more hash tokens (the tail of a block
6
   chain) is at the front.
7
Note that we maintain this order by reversing the block order when free
8
blocks of a request. This operation is outside of this class.

队列的六个操作：出队只有一个方向

队列的接口有 popleft、popleft_n、remove、append、append_n、prepend、prepend_n，外加只读的 iter_blocks_after 与测试用的 get_all_free_blocks。

popleft_n 的实现很直白：从 fake head 的 next 开始取 n 个块，逐块清空 prev/next，最后把 fake head 接到第 n+1 块上：

1
def popleft_n(self, n: int) -> list[KVCacheBlock]:
2
    if n == 0:
3
        return []
4
    assert self.num_free_blocks >= n
5
    self.num_free_blocks -= n
6
    curr_block = self.fake_free_list_head.next_free_block
7
    ...
8
    ret = []
9
    for _ in range(n):
10
        ret.append(curr_block)
11
        last_block = curr_block
12
        curr_block = curr_block.next_free_block
13
        # Reset prev_free_block and next_free_block of all popped blocks
14
        last_block.prev_free_block = None
15
        last_block.next_free_block = None
16
    if curr_block is not None:
17
        self.fake_free_list_head.next_free_block = curr_block
18
        curr_block.prev_free_block = self.fake_free_list_head
19
    return ret

取出后的块指针被置为 None，这不是多余操作：remove 以 prev is None or next is None 判定非法调用，指针干净才能让“重复移除”“移除一个不在链上的块”立刻报错，而不是悄悄破坏链表。

append_n / prepend_n 分别把列表接在 fake tail 之前、fake head 之后。它们接受列表而不是单块，是因为一次释放往往是一批块；代码里没有对列表排序或去重，顺序完全由调用方给定，因此“批内顺序”是调用方的契约——下一节会看到管理器如何用 reversed 把尾块排到前面。

remove 是 touch 路径的核心：

1
def remove(self, block: KVCacheBlock) -> None:
2
    prev_block = block.prev_free_block
3
    next_block = block.next_free_block
4
    if prev_block is None or next_block is None:
5
        raise RuntimeError(f"remove() called on an invalid block: {block}")
6
    prev_block.next_free_block = next_block
7
    next_block.prev_free_block = prev_block
8
    block.prev_free_block = block.next_free_block = None
9
    self.num_free_blocks -= 1

这里没有遍历或查找：只要块对象还挂着链指针，删除就是改两个指针。这是双向链表相对 deque 的唯一优势，也是这类“按对象摘除”的调度结构普遍采用双向链表的原因。SGLang 的前缀缓存选择 radix 树形态，vLLM 选择链表，两者的数据结构差异直接决定了命中与淘汰的实现方式。

回收顺序：LIFO 与 FIFO 为何同时存在

BlockPool.free_blocks 是理解整个池的钥匙：

1
def free_blocks(self, ordered_blocks: Iterable[KVCacheBlock]) -> None:
2
    blocks_to_evict_last = []
3
    blocks_to_evict_first = []
4
    other_pools: dict[BlockPool, list[KVCacheBlock]] = {}
5
    for block in ordered_blocks:
6
        if block.is_null:  # never pooled; its ref_cnt is not maintained
7
            continue
8
        if block.pool is not None and block.pool is not self:
9
            other_pools.setdefault(block.pool, []).append(block)
10
            continue
11
        block.ref_cnt -= 1
12
        if block.ref_cnt == 0:
13
            if block.block_hash is None or not self.enable_caching:
14
                # LIFO reuse of non-cached blocks for better GPU locality.
15
                blocks_to_evict_first.append(block)
16
            else:
17
                # FIFO reuse of cached blocks for LRU eviction behavior.
18
                blocks_to_evict_last.append(block)
19
    self.free_block_queue.prepend_n(blocks_to_evict_first)
20
    self.free_block_queue.append_n(blocks_to_evict_last)
21
    for pool, blocks in other_pools.items():
22
        pool.free_blocks(blocks)

源码注释已点明两条规则的理由，这里从性能与语义两方面展开。

无哈希块走 LIFO（放到队头）。只写了几个 token 的尾块、被 reset_hash 过的不完整块、CoW 复制产生的新块，在不满足满块条件时都不可能是前缀命中目标，下次被分配时内容一定会被覆盖。既然如此，刚释放的无哈希块应立刻被优先分配：它与请求当前活跃块表的空间距离最近，GPU 侧页表项、块表缓存的迁移代价都更低；调试时块号变化也更小，更容易追踪。

有哈希块走 FIFO（放到队尾）。已登记的块是前缀缓存候选，未来有两种命运：被同前缀请求命中并 touch，或排到队头被重新分配。要最大化命中率，应让最久未被命中的块最先淘汰，也就是 LRU。而“命中”在代码里等价于“remove 出队列、引用清零后 append 回队尾”，因此队尾顺序天然是“越晚释放或命中越靠后”，popleft 从队头取就是最古老的候选。这就是注释所说的“FIFO reuse of cached blocks for LRU eviction behavior”。

一个重要的推论：空闲队列不是单一的 LRU。它同时承载栈语义（无哈希块）与 LRU 语义（有哈希块），入队端由 block_hash is None 决定。把两者混在一个队列里是为了减少结构数量，不必维护两套队列；代价是调试时不能把“位置”理解为唯一含义。

1
def free(self, request_id: str) -> None:
2
    """Free the blocks for the request."""
3
    # Free blocks in reverse order so that the tail blocks are freed first.
4
    self.block_pool.free_blocks(reversed(self.pop_blocks_for_free(request_id)))

1
请求 R 的块序列（逻辑顺序）:  B0  B1  B2  B3  B4
2
pop_blocks_for_free 返回:     B0  B1  B2  B3  B4
3
reversed(...) 入队顺序:       B4  B3  B2  B1  B0
4

5
无哈希块 -> prepend_n: [B4 B3 B2 B1 B0 ...其余空闲...]   <- B4 最先被分配
6
有哈希块 -> append_n : [...其余空闲... B4 B3 B2 B1 B0]   <- B4 最先被淘汰，B0 最后淘汰

1
for pool, blocks in other_pools.items():
2
    pool.free_blocks(blocks)

引用计数：入口、不变量与回收

ref_cnt 的生命周期只有几处入口：构造时为 0；get_new_blocks 分配时 +1；touch 命中复用时 +1；free_blocks 与 unpin_blocks 释放时 -1；CoW 路径额外 +1（后文展开）。get_new_blocks 的写法值得逐行看：

1
def get_new_blocks(self, num_blocks: int) -> list[KVCacheBlock]:
2
    if num_blocks > self.get_num_free_blocks():
3
        raise ValueError(f"Cannot get {num_blocks} free blocks from the pool")
4
    ret: list[KVCacheBlock] = self.free_block_queue.popleft_n(num_blocks)
5
    if self._reuse_watchers:
6
        self._notify_reuse(ret)
7
    if self.enable_caching:
8
        for block in ret:
9
            self._maybe_evict_cached_block(block)
10
            assert block.ref_cnt == 0
11
            block.ref_cnt += 1
12
            if self.metrics_collector:
13
                self.metrics_collector.on_block_allocated(block)
14
    else:
15
        for block in ret:
16
            assert block.ref_cnt == 0
17
            block.ref_cnt += 1
18
            ...
19
    return ret

四个关键点：

1. 不查哈希表。get_new_blocks 只从队列取块，不关心内容是否与当前请求相关。前缀命中是更早的 get_cached_block 阶段完成的，命中块通过 touch 增引用，而不走分配。
2. 先清哈希。_maybe_evict_cached_block 把该块所有哈希条目从哈希表删除并 reset_hash；块在被重新分配的那一刻就失去了缓存身份。
3. assert block.ref_cnt == 0。这是池的完整性不变量：空闲队列中所有块的引用计数都必须为零。断言触发说明有代码在未释放引用的情况下把块放进了队列，通常是对 free_blocks 调用不当。
4. 不足时抛错而不是部分分配。num_blocks > free 直接抛 ValueError；部分分配会破坏调用方“块预算 = token 预算”的假设，错误可能表现为注意力元数据里块表长度不对，而非显式分配失败。让它在源头失败更容易诊断。

touch 是反向操作：

1
def touch(self, blocks: Sequence[KVCacheBlock]) -> None:
2
    for block in blocks:
3
        if block.is_null:
4
            continue
5
        # ref_cnt=0 means this block is in the free list (i.e. eviction
6
        # candidate), so remove it.
7
        if block.ref_cnt == 0:
8
            self.free_block_queue.remove(block)
9
        block.ref_cnt += 1
10
        if self.metrics_collector:
11
            self.metrics_collector.on_block_accessed(block)

if block.ref_cnt == 0 是把块拉出队列的唯一判断：引用为 0 意味着它在队列里作为淘汰候选；引用大于 0 的块被活跃请求持有，本来就不在队列中。remove 同时维护 num_free_blocks，因此空闲统计与使用率不必单独计数。

池的两条核心不变量可以写成：

1
(1) free_block_queue 中的块 <=> ref_cnt == 0（占位块除外）
2
(2) 块对象一经创建，block_id 不变；块被重新分配时哈希必然先被清除

占位块是第一条的例外：它在构造时被 popleft 出来，ref_cnt 恒为 0 且永不维护，因此 touch 与 free_blocks 都显式跳过 is_null。第二条保证了块表在 worker 侧可以只追加——已被分配出去的块号不会变，变的只是它被谁持有。

1
def _notify_reuse(self, blocks: Iterable[KVCacheBlock]) -> None:
2
    for block in blocks:
3
        watcher = self._reuse_watchers.pop(block.block_id, None)
4
        if watcher is not None:
5
            watcher(block)

unpin_blocks：被释放但还能读的块

绝大多数释放走 free_blocks，有一类特殊场景走 unpin_blocks：

1
def unpin_blocks(
2
    self,
3
    blocks: Iterable[KVCacheBlock],
4
    on_reuse: Callable[[KVCacheBlock], None],
5
) -> None:
6
    """Release references to blocks that stay readable until reused.
7

8
    The blocks become last-resort eviction candidates regardless of prefix
9
    caching: they join the tail of the free queue and count as free.
10
    ``on_reuse`` fires when ``get_new_blocks`` hands a block out (or the
11
    cache is reset), so the caller can stop reading it.
12
    """
13
    released: list[KVCacheBlock] = []
14
    for block in blocks:
15
        assert block.ref_cnt > 0 and not block.is_null
16
        block.ref_cnt -= 1
17
        self._reuse_watchers[block.block_id] = on_reuse
18
        if block.ref_cnt == 0:
19
            released.append(block)
20
    self.free_block_queue.append_n(released)

三个要点：

• 无论是否开启前缀缓存，都放队尾。unpin 的块不是缓存候选，而是“最后才考虑淘汰”的块：排在队尾意味着它们要等所有有哈希候选与无哈希块都被分配完后才轮到。
• 注册 on_reuse 回调。每个块只保留一个回调（字典按 block_id 存储，后注册覆盖先注册）。这要求调用方保证同一块同一时刻只有一份在途读取；若两个传输并发读同一块，后一个回调覆盖前一个，前者不会收到停止信号。
• 回调在块被真正取出时触发。注册发生在 ref_cnt 减到 0 之前，触发发生在块被重新分配或缓存被重置时；pop 保证每个回调只触发一次。

这个接口的真实用途是 KV connector 的 D2H 拷贝与跨实例传输：读写方在 CPU/NIC 侧还有在途操作，若按普通 free_blocks 放进队头，下一步调度可能立刻把它重新分配并写入，传输中的内容就被覆盖；unpin_blocks 把它放到队尾，并把“传输完成”的时间点精确传递到复用的那一刻。reset_prefix_cache 里也有一处 _notify_reuse，用来在强制重置缓存时告知所有挂着的 watcher 其块将被复用。

unpin_blocks 只做 -1 再入队，不参与 LIFO/FIFO 分拣——这是它与 free_blocks 最本质的区别。两者合起来覆盖“释放并立即重用”（普通路径）与“释放但延迟可读”（异步路径）两类语义。

前缀哈希表：多条目、不去重与淘汰

前缀缓存的整体形态可以用 vLLM 官方文档的这张图概括：多个请求的前缀共享同一批物理块，命中时不需要重新计算 KV，只需要把请求的块表指向已存在的块。

图中每个请求的逻辑块表指向同一批物理块；共享部分的块引用计数大于 1，任何一个请求结束时都不会真正释放它们，只有最后一个持有者离开后，块才回到空闲队列并进入 LRU 候选区。这张图里没有出现池的内部结构，但共享得以成立的两个前提——哈希相等与引用计数正确——都由 BlockPool 保证。

1
self._cache: dict[BlockHashWithGroupId, KVCacheBlock | dict[int, KVCacheBlock]] = {}

1
NOTE #1: We currently don't de-duplicate the blocks in the cache,
2
meaning that if a block becomes full and is cached, we don't check
3
if there is already an identical block in the cache. This is because
4
we want to make sure the allocated block IDs won't change so that
5
block tables are append-only.

1
def _remove_cached_block_hashes(self, block: KVCacheBlock) -> list[BlockHashWithGroupId]:
2
    block_hashes: list[BlockHashWithGroupId] = []
3
    if block.block_hash is not None:
4
        block_hashes.append(block.block_hash)
5
    block_hashes.extend(self.cached_block_hashes_by_block.pop(block.block_id, ()))
6
    if not block_hashes:
7
        return []
8
    removed_hashes: list[BlockHashWithGroupId] = []
9
    for block_hash in block_hashes:
10
        if self.cached_block_hash_to_block.pop(block_hash, block.block_id) is not None:
11
            removed_hashes.append(block_hash)
12
    block.reset_hash()
13
    return removed_hashes

1
def _maybe_evict_cached_block(self, block: KVCacheBlock) -> bool:
2
    if self.metrics_collector:
3
        self.metrics_collector.on_block_evicted(block)
4
    evicted_hashes = self._remove_cached_block_hashes(block)
5
    if not evicted_hashes:
6
        # The block doesn't have hash, eviction is not needed
7
        return False
8
    self._emit_block_removed_events(evicted_hashes)
9
    return True

1
assert block_id < len(self.blocks), (
2
    f"Invalid block_id {block_id} >= {len(self.blocks)}. "
3
    "This indicates a bug in the KV connector - workers should "
4
    "only report block IDs that were allocated by the scheduler.")

命中、写时复制与部分块

1
def get_cached_block(self, block_hash, kv_cache_group_ids):
2
    cached_blocks = []
3
    for group_id in kv_cache_group_ids:
4
        block_hash_with_group_id = make_block_hash_with_group_id(block_hash, group_id)
5
        block = self.cached_block_hash_to_block.get_one_block(block_hash_with_group_id)
6
        if not block:
7
            return None
8
        cached_blocks.append(block)
9
    return cached_blocks

1
num_hash_tokens = (num_cached_blocks + i + 1) * block_size

1
def cache_partial_block(self, request, block, num_tokens, kv_cache_group_id,
2
                        block_size, replace_existing_hashes=False):
3
    if block.is_null:
4
        return None
5
    assert block_size % self.hash_block_size == 0
6
    block_hash = self._get_partial_block_hash(request, num_tokens)
7
    num_hash_blocks = num_tokens // self.hash_block_size
8
    ...

1
def move_block_hashes(self, src_block: KVCacheBlock, dst_block: KVCacheBlock) -> None:
2
    """Re-point ``src_block``'s prefix-cache entries to ``dst_block``.
3

4
    Used when the request owning ``src_block`` keeps writing into it :
5
    the prefix cache holds a private copy (``dst_block``)
6
    under the same hashes instead. Entries stay live; no events emitted.
7
    """
8
    assert dst_block.block_hash is None
9
    assert dst_block.block_id not in self.cached_block_hashes_by_block
10
    num_tokens = src_block.block_hash_num_tokens
11
    for block_hash in self._remove_cached_block_hashes(src_block):
12
        # `num_tokens` only applies to the first (primary) insertion.
13
        self._insert_block_hash(block_hash, dst_block, num_tokens=num_tokens)

1
if partial_hit is not None:
2
    block_idx, source_block = partial_hit
3
    cow_block = new_blocks[0]
4
    new_blocks = new_blocks[1:]
5
    if blocks_allocated:
6
        # The worker block table of a running request is append-only, so the
7
        # request must stay on source_block. Move the cache entry to cow_block
8
        # instead; the queued copy fills it before forward overwrites source_block.
9
        assert req_blocks[block_idx] is source_block
10
        self.block_pool.move_block_hashes(source_block, cow_block)
11
        self._pending_cow_copies.append((source_block, cow_block))
12
        source_block.ref_cnt += 1

1
def _apply_cow(self, request_id, block_idx, source_block, cow_block) -> None:
2
    req_blocks = self.req_to_blocks[request_id]
3
    assert req_blocks[block_idx] is source_block
4
    assert not source_block.is_null and source_block.ref_cnt > 0
5
    req_blocks[block_idx] = cow_block
6
    self._pending_cow_copies.append((source_block, cow_block))
7
    cow_block.ref_cnt += 1

与 KVCacheManager 的接口边界

vLLM V1 的前缀缓存总体结构可以对照官方博客的示意图来读：调度器侧持有哈希表与块池，worker 侧只持有块表与实际的 KV 张量。

图中“调度器侧”的哈希表就是本篇讨论的 cached_block_hash_to_block，块池就是 BlockPool；worker 侧拿到的只是每步调度生成的块表与槽位映射。BlockPool 的所有状态都在调度器进程里，worker 侧没有副本，因此池的引用计数与哈希条目是全局唯一事实来源。这也是为什么所有 KV 事件都从池发出，而不是从 worker 发出。

典型调用点：

1
# 分配新块
2
num_required_blocks = cdiv(num_tokens, self.block_size)
3
num_new_blocks = num_required_blocks - len(req_blocks)
4
if num_new_blocks > 0:
5
    new_blocks = self.block_pool.get_new_blocks(num_new_blocks)
6

7
# 释放
8
self.block_pool.free_blocks(reversed(self.pop_blocks_for_free(request_id)))
9

10
# 命中前查询
11
if cached_block := block_pool.get_cached_block(block_hash, kv_cache_group_ids):
12
    ...
13

14
# 写满后登记
15
self.block_pool.cache_full_blocks(
16
    request=request,
17
    blocks=self.req_to_blocks[request.request_id],
18
    num_cached_blocks=num_cached_blocks,
19
    num_full_blocks=num_full_blocks,
20
    block_size=self.block_size,
21
    kv_cache_group_id=self.kv_cache_group_id,
22
    block_mask=block_mask,
23
)

源码中有一处调度顺序要求值得记录：

1
Must run only after every group's local blocks have been touched via
2
`add_local_computed_blocks`, so this group's `get_new_blocks` cannot
3
evict another group's cache-hit blocks.

原因是 get_new_blocks 会淘汰缓存候选。如果某一组先分配新块，它可能把另一个组的缓存命中块挤出队列，导致同一请求在混合模型里“一组命中、一组未命中”。强制“先 touch 所有本地命中、再分配外部块”的顺序，是为了让命中的块先被拉出淘汰区。这类跨组顺序约束正是多池结构下最容易踩的坑。站内 GLM-5.3 推理全链路（九）：混批——一条 8K 预填请求并进 32 条解码请求之后 里对“混批时块数与 token 预算如何对齐”的分析，也依赖同一套池语义。

get_num_free_blocks 是调度器判断“还能不能再来一个请求”的唯一依据：

1
def get_num_free_blocks(self) -> int:
2
    return self.free_block_queue.num_free_blocks

它是维护好的计数器而非遍历长度——每次出队、入队、移除都同步更新，O(1) 读取。

三个子管理器在池上的特殊用法

1
class CircularBufferManager(FullAttentionManager):
2
    """Claims the ring's single block per request; prefix caching disabled."""
3
    supports_fine_grained_hash_lookup: ClassVar[bool] = False
4

5
    def _claim_ring_block(self, request_id: str, record_for_zeroing: bool = True) -> list[KVCacheBlock]:
6
        req_blocks = self.req_to_blocks[request_id]
7
        if req_blocks:
8
            return []
9
        new_blocks = self.block_pool.get_new_blocks(1)
10
        req_blocks.extend(new_blocks)
11
        return new_blocks

1
computed.extend([block_pool.null_block] * block_idx)

1
self.block_pool._maybe_evict_cached_block(checkpoint_block)
2
return self.block_pool.cache_partial_block(...)

哈希是怎么算出来的：前缀链、组 id 与 salt

池里所有淘汰与命中判断都建立在“块哈希”之上，而哈希本身在 kv_cache_utils.py 中计算。理解它的构造方式，才能理解 get_cached_block 为什么按组查询、以及 extra_keys 为什么会进入哈希。

1
def hash_block_tokens(
2
    hash_function: Callable[[Any], bytes],
3
    parent_block_hash: BlockHash | None,
4
    curr_block_token_ids: Sequence[int],
5
    extra_keys: tuple[Any, ...] | None = None,
6
) -> BlockHash:
7
    if not parent_block_hash:
8
        parent_block_hash = NONE_HASH
9
    curr_block_token_ids_tuple = tuple(curr_block_token_ids)
10
    return BlockHash(
11
        hash_function((parent_block_hash, curr_block_token_ids_tuple, extra_keys))
12
    )

1
def get_block_hash(key: BlockHashWithGroupId) -> BlockHash:
2
    return BlockHash(key[:-4])
3

4
def get_group_id(key: BlockHashWithGroupId) -> int:
5
    return int.from_bytes(key[-4:], "big", signed=False)

1
if block_size == hash_block_size:
2
    return block_hashes
3
...
4
assert block_size % hash_block_size == 0
5
return BlockHashListWithBlockSize(block_hashes, hash_block_size, block_size)

工程上的坑与排查建议

1. KV Cache usage 接近 1.0，但请求很快完成。先看是否有大量有哈希块停留在空闲队列。它们计为“已用”，get_usage 只按队列长度计算。这是 LRU 组的预期行为；若持续逼近上限，说明缓存候选过多、新请求挤不进来。
2. 前缀命中率低于预期。检查 hash_block_size 与 block_size 是否一致，cache_partial_block 是否启用，SWA 组的 block_mask 是否排除过多块，以及 num_hash_lookahead_tokens 是否让边界变粗。
3. 多组 KV 命中率异常。get_cached_block 要求所有组命中；任何一个组缺少同一块哈希都会整体 miss。同时检查 allocate_external_computed_tokens 的调用顺序是否违反“先 touch 后分配”。
4. reset_prefix_cache 返回 False。检查是否有请求未释放，或 unpin_blocks 注册的 watcher 仍存在。占位块永远“在用”，num_used_blocks 至少为 1 才能重置。
5. KV connector 上报块号时报错。evict_blocks 的 block_id < len(self.blocks) 断言说明 worker 上报了调度器从未分配过的块号，通常是远端连接器的块号映射没对齐。
6. 块数账对不上。多池场景下 block.pool 设错或同一块被两个池释放，会造成引用计数重复扣减。排查时对每个块打印 (block_id, ref_cnt, block_hash, pool)，核对 free_block_queue 里每块 ref_cnt == 0。
7. 异步传输后内容被覆盖。检查是否误用了 free_blocks 而非 unpin_blocks：前者放队头，可能在同一调度步被重新分配；后者放队尾并注册回调。
8. 块表在运行请求中被“改写”。这违反只追加不变量，常见于部分命中路径误用 _apply_cow 之外的方式改块表，正确做法是 move_block_hashes 搬运哈希而非改块表。

小结

BlockPool 并不起眼，但没有它，KVCacheManager 的策略只能悬浮在数字上。它把“物理块”变成一个可借、可还、可共享、可淘汰、可上报事件的对象，用少量字段和一条双向链表把全部状态收进可推理的范围。几条最重要、也最容易被误解的决定：

• 空闲队列同时承载 LIFO 与 LRU 两种语义。无哈希块走栈语义（放队头，立即重用，利于局部性）；有哈希块走 LRU 淘汰（放队尾，越久未命中越早淘汰，利于前缀命中）。位置不代表唯一含义。
• 引用计数是“能否被分配”的唯一依据。共享、命中、异步传输都通过引用计数表达；unpin_blocks 把“逻辑释放但保留可读”编码为引用计数与回调的组合。
• 哈希表不做去重，块可以挂多条目。前者保证块表严格追加；后者让部分块、组间块大小差异与 CoW 都能在一个哈希空间里正确表示。
• 策略在管理器、机制在池。找最长命中、决定分配多少、何时抢占由 KVCacheManager 做；池只提供 get_new_blocks、touch、free_blocks、cache_full_blocks、get_cached_block 这些原子操作。

弄清这些机制后，再看调度器的抢占、前缀命中与混批，许多“块为什么没释放”“命中为什么少一块”的问题会变得有迹可循：它们大多不是内核问题，而是池里的状态与引用计数没有按约定流转。

下一篇讨论 KVCacheManager 在多组模型（MLA latent、SWA、DSA 索引器）之间做协同分配时，如何在“全有或全无”命中之外，用每组独立的块预算与掩码把池的原子操作拼成一个完整调度步。

参考资料

1. vLLM V1 block_pool.py 源码
2. vLLM V1 kv_cache_utils.py 源码
3. vLLM V1 single_type_kv_cache_manager.py 源码
4. vLLM 官方文档：Automatic Prefix Caching
5. vLLM V1 Alpha 发布博客
6. Efficient Memory Management for Large Language Model Serving with PagedAttention (arXiv:2309.06180)