执行摘要

• 一句话：澄清 BlockPool.free_blocks 驱逐优先级注释与命名
• 推荐动作：无需精读，但值得快速浏览 free_blocks 的新注释，以理解 v1 前缀缓存中缓存块与非缓存块的驱逐优先级设计（LIFO vs FIFO）。

功能与动机

PR body 指出 BlockPool.free_blocks() 中解释驱逐优先级的注释模糊/令人困惑，希望让注释更清晰明确。该函数是 v1 前缀缓存块释放的关键路径，注释不清晰容易让维护者误解缓存块与非缓存块在 free queue 中的插入方向。

实现拆解

1. 变量重命名：将 blocks_with_hash 改为 blocks_to_evict_last，将 blocks_without_hash 改为 blocks_to_evict_first，使变量名直接表达其在驱逐队列中的位置。
2. 分支注释重写：当 block_hash is None 或缓存禁用时，注释明确为 “LIFO reuse of non-cached blocks for better GPU locality.”；否则注释为 “FIFO reuse of cached blocks for LRU eviction behavior.”，清晰解释了复用顺序与驱逐优先级的关系。
3. 入队操作注释：将 prepend_n 与 append_n 的注释分别更新为“先复用的块放在队首”和“后复用的块放在队尾”，与 LIFO/FIFO 语义对齐。
   无测试、配置或部署配套改动，也不需要——因为行为未变。

关键文件：

• vllm/v1/core/block_pool.py（模块 块池；类别 source；类型 refactor；符号 free_blocks）: 唯一改动文件，重命名内部变量并重写注释以澄清驱逐优先级。

关键符号：free_blocks

关键源码片段

vllm/v1/core/block_pool.py

唯一改动文件，重命名内部变量并重写注释以澄清驱逐优先级。

def free_blocks(self, ordered_blocks: Iterable[KVCacheBlock]) -> None:
    """释放一批块，按驱逐优先级排序，第一个块最先被驱逐。
​
    Args:
        ordered_blocks: 按驱逐优先级排序的待释放块列表。
    """
    # 区分有 hash（参加 LRU 缓存）与无 hash（永不匹配 APC）的块。
    # 有 hash 的块按 FIFO 复用（后者后驱逐），无 hash 的块按 LIFO 复用（优先复用刚释放的），
    # 以提升 GPU cache locality。
    blocks_to_evict_last = [] # 有 hash，参与 LRU，最后被驱逐
    blocks_to_evict_first = [] # 无 hash，最早被驱逐
    for block in ordered_blocks:
        block.ref_cnt -= 1
        if block.ref_cnt == 0 and not block.is_null:
            if block.block_hash is None or not self.enable_caching:
                # LIFO 复用非缓存块，提高 GPU 局部性。
                blocks_to_evict_first.append(block)
            else:
                # FIFO 复用缓存块，实现 LRU 驱逐行为。
                blocks_to_evict_last.append(block)
​
    # 先复用的块放到队首，后复用的块放到队尾。
    self.free_block_queue.prepend_n(blocks_to_evict_first)
    self.free_block_queue.append_n(blocks_to_evict_last)

评论区精华

该 PR 没有实质技术讨论。claude[bot] 因来自 fork 自动 review 被禁用，simon-mo 直接批准。

• 无实质 review 讨论 (other): 无争议，直接合并。

风险与影响

• 风险：风险极低。纯局部变量重命名与注释修改，不改变函数签名、控制流或任意常量值。唯一潜在的回归点是若代码库中有依赖这些局部变量名的外部逻辑，但 Python 局部变量不跨作用域，因此不存在。CI 已通过。
• 影响：对用户和运行时无影响，仅提高 BlockPool 代码可读性，降低维护者误解驱逐优先级的概率，便于后续改动以防引入方向性错误。
• 风险标记：无逻辑变更, 仅注释改动

关联脉络

• 暂无明显关联 PR