# PR #42676 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Model Runner V2] Fix kv_connector `pre_forward` order
- 合并时间：2026-05-15 23:14
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/42676

---

# 执行摘要

- 一句话：修复 KV Connector pre_forward 调用顺序
- 推荐动作：值得快速合并。这是 Model Runner V2 迁移的明确 bugfix，代码量小且已通过测试验证。

# 功能与动机

作为 Model Runner v1 到 v2 迁移的一部分（Issue #41286），需要修复 KV Connector 在多连接器场景下的事件顺序问题。原顺序导致测试断言失败：预期事件序列的 index 3 应为 'handle_preemptions' 但实际为 'bind_connector_metadata'。

# 实现拆解

在文件 `vllm/v1/worker/gpu/kv_connector.py` 的 `pre_forward` 方法中，交换了 `bind_connector_metadata` 和 `handle_preemptions` 的调用顺序：

1. **定位问题**：通过测试断言发现事件序列不匹配，index 3 预期为 `handle_preemptions` 但实际为 `bind_connector_metadata`。
2. **修改顺序**：将 `handle_preemptions` 移到 `bind_connector_metadata` 之前。
3. **验证**：执行 `VLLM_USE_V2_MODEL_RUNNER=1 pytest tests/v1/kv_connector/unit/test_multi_connector.py::test_multi_example_connector_consistency` 通过。

关键文件：
- `vllm/v1/worker/gpu/kv_connector.py`（模块 KV 连接器；类别 source；类型 core-logic）: 唯一变更文件，修改 KVConnector.pre_forward 方法中 bind_connector_metadata 和 handle_preemptions 的调用顺序。

关键符号：ActiveKVConnector.pre_forward

## 关键源码片段

### `vllm/v1/worker/gpu/kv_connector.py`

唯一变更文件，修改 KVConnector.pre_forward 方法中 bind_connector_metadata 和 handle_preemptions 的调用顺序。

```python
def pre_forward(self, scheduler_output: "SchedulerOutput") -> None:
    if self._disabled:
        return

    kv_connector_metadata = scheduler_output.kv_connector_metadata
    assert kv_connector_metadata is not None
    # 先处理抢占，再绑定元数据，确保事件顺序与期望一致
    self.kv_connector.handle_preemptions(kv_connector_metadata)
    self.kv_connector.bind_connector_metadata(kv_connector_metadata)

    # TODO: sort out KV Connectors' use of forward_context
    if is_forward_context_available():
        self.kv_connector.start_load_kv(get_forward_context())
    else:
        with set_forward_context(None, self.vllm_config):
            self.kv_connector.start_load_kv(get_forward_context())

```

# 评论区精华

无实质性 review 讨论。Claude 和 Gemini 的自动评论为常规提示，njhill 直接批准合并。

- 暂无高价值评论线程

# 风险与影响

- 风险：低风险。仅交换两行调用顺序，不涉及逻辑变更或新增依赖。但需注意，`pre_forward` 是核心路径（每次调度步调用），顺序变更可能影响 KV Connector 内部状态管理，不过当前修复符合原始设计意图。
- 影响：影响范围小，仅修复 Model Runner V2 下 KV Connector 的事件顺序问题。对启用 `VLLM_USE_V2_MODEL_RUNNER` 的用户有益，是 v1→v2 迁移的推进步骤。
- 风险标记：核心路径变更

# 关联脉络

- PR #41286 [Feature]: Migration from Model Runner v1 to Model Runner v2: 本 PR 是 v1→v2 迁移路线图中的一项任务