执行摘要

• 一句话：推迟请求完成通知，防止KV卸载EngineCore崩溃
• 推荐动作：该 PR 修复了生产环境中的关键时序 bug，设计讨论体现了良好的信号集中化策略。值得阅读以理解 KV offloading 的请求生命周期管理。对于使用 KV offloading 的部署，建议尽快合入。

功能与动机

Issue #49635 报告了 KV offloading 的 EngineCore 崩溃：当请求完成时，request_finished 立即调用 manager.on_request_finished，而该请求的最终 KV 块存储作业可能尚未提交。manager 因此删除 _req_state，随后 _build_store_jobs 中的 prepare_store 引用已删除的状态导致 KeyError，使 EngineCore 崩溃。此修复确保 manager 在所有 final store jobs 构建完成后再接收通知。

实现拆解

1. 在 RequestOffloadState 中添加 finished_signaled 字段，标记是否已向 manager 发送完成信号。
2. 移除 _maybe_cleanup_finished_req 方法，改为在 build_connector_meta 中顺序调用 _build_store_jobs 后统一遍历 finished_req_ids：设置 finished_signaled、调用 manager.on_request_finished，若无进行中传输则删除状态。
3. 修改 request_finished 方法：不再立即通知 manager，仅记录完成状态、更新 offload keys 并将请求加入 finished_req_ids。
4. 修改 update_connector_output 的清理条件：从检查 is_finished() 改为检查 finished_signaled，确保信号已发送后才清理。
5. 同步修改 reset_cache 中的清理逻辑，防止重复或遗漏。
6. 更新测试：调整 test_last_block_offloaded_at_request_finish 断言为 req_status 被清理；重命名并修改 test_on_request_finished_is_not_deferred_until_store_completion 为 test_on_request_finished_not_deferred_until_store_completion，修正 docstring 和期望；测试运行器 _run 在循环条件、EOS 后继续条件中加入 finished_req_ids 检测，确保最终存储步骤完全执行。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py（模块 卸载调度；类别 source；类型 core-logic；符号 _maybe_cleanup_finished_req, RequestOffloadState, build_connector_meta, update_connector_output）: 核心逻辑修改：重构请求完成通知时序，添加 finished_signaled 标记，修改 build_connector_meta、update_connector_output、request_finished 等关键方法。
• tests/v1/kv_connector/unit/offloading_connector/test_scheduler.py（模块 卸载测试；类别 test；类型 test-coverage；符号 test_last_block_offloaded_at_request_finish, test_on_request_finished_not_deferred_until_store_completion, test_on_request_finished_is_not_deferred_until_store_completion）: 测试覆盖：新增和修改测试用例验证最终存储后才通知 manager、合理清理状态，确保新行为正确。
• tests/v1/kv_connector/unit/offloading_connector/utils.py（模块 测试工具；类别 test；类型 test-coverage）: 测试工具：调整测试运行器循环条件，加入 finished_req_ids 判断，确保最终存储步骤不会被跳过。

关键符号：_maybe_cleanup_finished_req, request_finished, build_connector_meta, update_connector_output, reset_cache

关键源码片段

vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py

核心逻辑修改：重构请求完成通知时序，添加 finished_signaled 标记，修改 build_connector_meta、update_connector_output、request_finished 等关键方法。

# vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py
​
# RequestOffloadState 新增字段
@dataclass(slots=True)
class RequestOffloadState:
    # ... 原有字段 ...
    # True once on_request_finished has been signaled to the manager.
    finished_signaled: bool = False
​
# build_connector_meta 方法改造（关键部分）
def build_connector_meta(self, scheduler_output: SchedulerOutput) -> KVConnectorMetadata:
    # ... 构建 store_jobs ( 调用 _build_store_jobs) ...
​
    # 所有 finished 请求的 final store jobs 已通过 prepare_store 提交，
    # 现在可以安全地发送完成信号。注意：complete_store 可能仍异步进行。
    for req_id in scheduler_output.finished_req_ids or ():
        req_status = self._req_status.get(req_id)
        if req_status is None:
            continue
        req_status.finished_signaled = True
        self.manager.on_request_finished(req_status.req_context)
        if not req_status.transfer_jobs:
            # 没有进行中的传输，直接清理状态
            del self._req_status[req_id]
​
    # ... 返回 metadata ...
​
# update_connector_output 中清理条件变更
def update_connector_output(self, connector_output: KVConnectorOutput):
    # ... 处理 job completion ...
    req_status.transfer_jobs.remove(job_id)
    # 之前 : if not req_status.transfer_jobs and req_status.req.is_finished()
    # 现在 : 必须等到 finished_signaled 后才清理，避免过早删除
    if req_status.finished_signaled and not req_status.transfer_jobs:
        del self._req_status[job_status.req_id]

评论区精华

1. 设计讨论：orozery 提供了一个替代修复方案（fa07027d），建议用统一中心化结构处理完成信号。作者采纳并适配了测试，形成 ecf6bc52af。
2. 生产验证：nilig 在原始 issue 集群上部署验证，单请求和 16/100 突发无 EngineCore 重启，确认修复有效。
3. 断言保留：orozery 强调不应删除 manager 中的严格断言，作者保留该断言。

• 完成信号中心化建议 (design): 作者采纳该建议，在 ecf6bc52af 中实现中心化结构并调整测试适配。
• 生产环境验证 (testing): 补丁通过生产环境验证。
• 保留 Manager 严格断言 (design): 作者保留 manager 中的严格断言，未删除。

风险与影响

• 风险：核心变更影响 KV offloading 的生命周期，可能引发以下风险：
  • 若 finished_signaled 在某些路径（如 reset_cache）下未正确设置，可能导致请求状态泄漏或重复清理。
  • 时序依赖：build_connector_meta 必须在每次调度步骤中正确调用，如果未来重构此方法而忽略 finalization 部分，可能 reintroduce 该 bug。
  • 测试覆盖了主要场景，但未覆盖多请求并发、大 burst 等所有边缘情况，虽有生产验证仍存在一定风险。
  • 影响：影响范围仅限于使用 KV offloading（OffloadingConnector）的用户，且仅涉及请求完成与 KV 存储的交互时序。不改变其他功能。修复后消除了特定配置下的 EngineCore 崩溃，提升了系统稳定性。
  • 风险标记：核心生命周期变更, Manager 断言依赖

关联脉络

• 暂无明显关联 PR