[Bug][KV Offload]: `on_request_finished()` has inconsistent guarantees across offloading layers

快速结论：该 Bug 并非运行时崩溃，而是 vLLM KV Offload 内部 API 的语义/契约问题，导致 `OffloadingManager` 与 `SecondaryTierManager` 的两个 `on_request_finished()` 钩子分别提供“完成”与“提交”两种不同的保证，影响调度一致性。优先排查 OffloadingManager 和 SecondaryTierManager 的钩子实现是否遵循提案中的统一提交契约。

问题场景

该问题由 vLLM 项目 #46027 报出，用户在使用 KV Offload 功能时（未指定模型、环境或具体运行配置），在进行请求驱动的缓存卸载/加载调度时触发。该 Bug 并非运行时崩溃，而是代码语义错误：两个 offloading 层级的 `on_request_finished` 提供了不一致的保证。

报错原文

The bug: on_request_finished has inconsistent guarantees across the two offloading layers:
- OffloadingManager.on_request_finished fires after GPU→CPU stores have **completed** (and the CPU→secondary cascades have been submitted).
- SecondaryTierManager.on_request_finished fires after the CPU→secondary submit_stores have only been **submitted**, not completed.
One hook carries a "completion" guarantee and the other a "submission" guarantee.

原因分析

这是 vLLM KV Offload 内部 API 的设计缺陷/语义不统一。在 #45823 引入对 `OffloadingManager.on_request_finished` 的完成延迟后，导致两个层级间的钩子保证不一致。提案要求在每层使用统一的“提交”契约：

钩子在“本层不再接收到该请求的 submit 调用”时触发，但完成回调和正在传输中的数据可能在之后继续。
每一层只应在自身的提交（submit）完成时才触发。
具体修复方案建议在以下三个组件中修改：

Connector（`OffloadingConnectorScheduler`）：在 `request_finished()` 中尽早触发 `OffloadingManager.on_request_finished`（回滚撤销 #45823 的完成延迟）。
`TieringOffloadingManager`：不再立即委托给 `tier.on_request_finished`，而是追踪每个请求的正在进行的 GPU→CPU 存储计数，只在请求完成且最后一个级联 `submit_store` 已发出后调用 `tier.on_request_finished`。
Docstrings：在两个 ABC 上声明统一的提交契约。

注意：这是重构性质的修复，应与正确性修复（#45823）区分。

环境排查

vLLM 版本：当前未明确指定，但该问题属于内部 API 设计问题，建议确认所使用的 vLLM 版本是否已包含 #45823 的正确性修复（2025年6月24日之后发布的版本）。
若涉及重构提案 #46284，需确认是否已合入。
该问题的复现不需要特定硬件或软件依赖，但应在有 KV Offload 启用的环境中排查。

解决步骤

检查 Issue 中提案的修复状态：该 Issue 是 #45823 的后续，修复方案在 #46284 中实现，建议在 vLLM 中查看 #46284（PR）是否已合入，并检查对应提交 log（如 0e4e5ac 等进展）。

如需自行应用（开发环境修复）：

修改 OffloadingConnectorScheduler 中的 request_finished() 方法：

在 request_finished() 中尽早触发 manager.on_request_finished，而非在 reset_cache() 或 update_connector_output() 中延迟触发。

修改 TieringOffloadingManager：

增加 per-request 的 outstanding GPU-to-CPU store 计数机制。在 prepare_store()（keys_to_store）时递增，在 complete_store() 时递减。
在 on_request_finished() 中（现在会被尽早调用），立即委托给 primary_tier.on_request_finished，但延迟触发 secondary tier 的 on_request_finished，直到 outstanding-store 计数归零。
在 complete_store() 中进行级联后，若请求已结束且计数归零，则触发 tier.on_request_finished 并清除 per-request 条目。
将 scheduler.py（约 1216-1219 行）中的 reset_cache 终结 on-abandon 处理迁移到 TieringOffloadingManager.reset_cache() 中。

更新 base.py:265 和 tiering/base.py:187 中的 ABC docstrings，明确声明统一提交契约：

on_request_finished at layer X = "X will receive no more submit calls for this request." Completions and in-flight transfers may still occur afterward.

更新测试 test_no_offload_call_after_on_request_finished（若存在），并添加新测试验证 tiering manager 中 tier.on_request_finished 在最后一个级联 submit_store 之后才触发。

确认异步调度中的最后块问题：
- 检查 scheduler.py 中 TODO（1152 行附近）涉及的异步延迟的最后 block 存储问题。修复提案要求：任何未来的最终 prepare_store() 必须在 _call_request_finished() 之前发生，以保持 finish-hook 边界。
- 如有不确定，可优先检查 #46284 中的 0e4e5ac 提交文档更新。
注意：#45823 的 test 测试在新的契约下可被修改，因为现在 eager 触发导致仍在传输中的 complete_store 可能会发生在 on_request_finished 之后。

验证方法

运行单元测试套件，特别是新增的 assert tier.on_request_finished fires only after the last cascade submit_store 测试。同时运行现有 test_no_offload_call_after_on_request_finished 测试，确认新行为（顺序变化）正确并且通过。