执行摘要

• 一句话：合并 _logical_to_remote_kernel_block_ids 到 _logical_to_kernel_block_ids
• 推荐动作：建议精读。该 PR 展示了如何通过参数化消除重复函数，以及如何借助测试注释传递关键设计意图（如静默精度损坏的根因）。对于维护 NIXL 模块的工程师是必须理解的变更。

功能与动机

PR body 中说明要统一函数以避免重复代码。测试注释进一步指出原先的重复实现曾导致 Qwen3.5 上静默精度损坏，因为远程扩展使用了错误的本地比率。统一后可确保始终使用正确的扩展比率。

实现拆解

1. 在 base_worker.py 中，修改 _logical_to_kernel_block_ids 函数，增加 ratio: int 参数，使其同时支持本地和远程扩展逻辑；删除独立的 _logical_to_remote_kernel_block_ids 方法。
2. 在 push_worker.py 和 pull_worker.py 中，将所有对 _logical_to_kernel_block_ids 和 _logical_to_remote_kernel_block_ids 的调用替换为统一的 _logical_to_kernel_block_ids，并传入正确的比率：本地场景使用 self._physical_blocks_per_logical_kv_block，远程场景使用 remote_info.remote_physical_blocks_per_logical。
3. 更新测试文件 test_nixl_connector_hma.py：将 test_logical_to_kernel_block_ids_with_hma 调用改为传递比率参数；将 test_logical_to_remote_kernel_block_ids 重命名为 test_logical_to_kernel_block_ids_with_remote_ratio，并统一调用新函数。
4. 更新 test_nixl_push_connector.py 中的 stub lambda 函数，使其接受 (x, ratio) 两个参数以匹配新签名。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py（模块 KV传输；类别 source；类型 core-logic；符号 _logical_to_kernel_block_ids, _logical_to_remote_kernel_block_ids）: 核心变更所在：合并 _logical_to_remote_kernel_block_ids 到 _logical_to_kernel_block_ids，增加 ratio 参数，统一两种扩展逻辑。
• tests/v1/kv_connector/unit/test_nixl_connector_hma.py（模块 KV传输测试；类别 test；类型 test-coverage；符号 test_logical_to_kernel_block_ids_with_remote_ratio, test_logical_to_remote_kernel_block_ids）: 测试文件同步更新：调整已有测试调用新签名，重命名测试函数以反映统一后的行为。
• vllm/distributed/kv_transfer/kv_connector/v1/nixl/push_worker.py（模块 KV传输；类别 source；类型 core-logic）: 更新两处调用点，分别传入本地和远程比率。
• vllm/distributed/kv_transfer/kv_connector/v1/nixl/pull_worker.py（模块 KV传输；类别 source；类型 core-logic）: 更新两处调用点，分别传入本地和远程比率。
• tests/v1/kv_connector/unit/test_nixl_push_connector.py（模块 KV传输测试；类别 test；类型 test-coverage）: 更新 stub lambda 以匹配新函数签名。

关键符号：_logical_to_kernel_block_ids, _logical_to_remote_kernel_block_ids, test_logical_to_kernel_block_ids_with_remote_ratio, test_logical_to_remote_kernel_block_ids

关键源码片段

vllm/distributed/kv_transfer/kv_connector/v1/nixl/base_worker.py

核心变更所在：合并 _logical_to_remote_kernel_block_ids 到 _logical_to_kernel_block_ids，增加 ratio 参数，统一两种扩展逻辑。

def _logical_to_kernel_block_ids(self, block_ids: BlockIds, ratio: int) -> BlockIds:
    """
    Convert block ids to kernel physical block ids.
    This is required when the logical block size (the one set by the user)
    does not match the one required by the attn backend.
    `ratio` is the number of physical blocks per logical block.
    We always receive logical blocks from the engine, so we expand them here eg:
    logical block ids: [(SW-clipped) [1], (FA) [2, 3]], ratio=2
    physical block ids: [(SW-clipped) [2, 3], (FA) [4, 5, 6, 7]]
    """
    # 当每逻辑块对应的物理块数为 1 时，物理块大小与逻辑块大小一致，直接返回
    if ratio == 1:
        return block_ids
    block_arange = np.arange(0, ratio).reshape(1, -1)
    # Mamba 块没有逻辑块与物理块的差异（块大小固定为 1）
    group_specs = self.kv_cache_config.kv_cache_groups
    physical_block_ids = []
    for i, group in enumerate(block_ids):
        spec = group_specs[i].kv_cache_spec
        if isinstance(spec, MambaSpec):
            physical_block_ids.append(group)
        else:
            physical_block_ids.append(
                BlockTable.map_to_kernel_blocks(
                    np.array(group), ratio, block_arange
                ).tolist()
            )
    return physical_block_ids

评论区精华

无实质讨论。两位 reviewer（ZhanqiuHu、DarkLight1337）均直接 LGTM/Approve，claude bot 仅说明由于来自 fork 自动 review 被禁用。

• 暂无高价值评论线程

风险与影响

• 风险：重构风险较低，但需注意：（1）所有调用点都必须传入正确的 ratio 参数，否则可能导致 block id 映射错误，引发注意力计算偏移或精度下降；（2）删除的 _logical_to_remote_kernel_block_ids 是保护方法，外部模块如有猴子补丁可能失效，但可能性极小；（3）测试已覆盖本地和远程场景的主要路径，但仍需关注混合注意力模型（如 Mamba+FA）的分支逻辑。
• 影响：直接用户无感知。对 NIXL KV 传输模块的开发者和维护者：代码更易维护，消除重复逻辑；统一接口降低了未来添加新块扩展策略的难度。影响范围限于 v1 kv-connector 子系统的 4 个源文件和 2 个测试文件。
• 风险标记：重构核心函数, 需回归验证

关联脉络

• PR #48209 Vectorize prep xfer list creation: 同为 NIXL 模块 base_worker.py 的改进，进行性能优化；本 PR 的统一接口可能为类似的扩展优化奠定基础。