执行摘要

• 一句话：新增 NIXL KV Cache 租约续期设计文档
• 推荐动作：建议所有使用或评估分离式 prefill/decode 部署的团队成员阅读该文档，尤其是调度器和工作器开发者。文档中关于心跳时机、批量续期和配置项的设计决策值得关注。

功能与动机

原始设计使用单一超时控制 P 保留 KV 块的时间。当 D 崩溃时，P 会持有几 GB 的“死块”长达 8 分钟才回收。降低超时则导致在流量激增时 D 队列中的请求还未调度，块就被释放，造成不必要的重计算。租约续期机制通过 P 授予短初始租约，D 定期发送心跳延长租约，同时解决了这两个问题。

实现拆解

1. 问题分析：文档先阐述了单超时问题和过载问题，明确设计目标。
2. 租约生命周期设计：P 完成 prefill 后锁定 KV 块并设置初始租约（默认 30s）。后续可通过 D 的传输完成通知立即释放，或通过心跳持续延长租约，否则超时回收。
3. 心跳机制设计：D 复用 NIXL 现有的通知系统（send_notif / get_new_notifs）向 P 发送心跳，每条心跳消息可续期该 D 在 P 上的所有请求，实现了批量续期。
4. 调度端跟踪：关键设计决策是 D 在请求进入调度器队列即开始发送心跳，而非等到请求调度到 GPU，确保即使在排队阶段也能维持租约。
5. 配置项说明：文档列出了关键配置参数如 VLLM_NIXL_KV_LEASE_DURATION（初始租约持续时间）及其默认值，方便用户调整。

关键文件：

• docs/design/nixl_kv_cache_lease.md（模块 设计文档；类别 docs；类型 documentation）: 唯一新增文件，是租约续期机制的完整设计文档，包含动机、生命周期、心跳复用和配置等核心内容，是所有后续实现讨论的参考基准。

关键符号：未识别

评论区精华

主要讨论点：

• 序列图箭头方向：gemini-code-assist[bot] 指出传输完成通知箭头应从 D 指向 P 而非 P 指向 D，因为 RDMA 读取方 D 才知道传输何时完成。该问题已被修正。
• 文件名与标题：markmc 建议在文件名和标题中加入 NIXL 以明确关联，已采纳。

• 措辞优化：markmc 对"group requests on D by destination"表述提出改进建议，已采纳。

  • 序列图箭头方向错误 (correctness): 作者根据建议修正了序列图，箭头方向改为从 D 指向 P。
  • 文件名和标题中加入 NIXL (documentation): 作者采纳建议，最终文件名为 nixl_kv_cache_lease.md，标题也包含 NIXL。
  • 措辞优化建议 (style): 作者采纳建议并修改了相关表述。

风险与影响

• 风险：文档变更本身无代码风险。主要风险是文档与 PR #41383 的实际实现之间可能存在的偏差，例如默认值、行为描述等，如果文档未及时随代码更新，可能误导用户。此外，文档未覆盖所有配置项或边缘情况，用户依赖此文档进行生产部署时需确认与实际版本一致。
• 影响：对用户：提供清晰的设计参考，降低对租约机制的理解门槛。对系统：无直接影响，仅增加文档。对团队：有利于新成员快速上手，减少后续设计沟通成本。影响范围限于涉及分离式部署的用户和相关开发者。
• 风险标记：文档-代码一致性风险

关联脉络

• PR #41383 NIXL KV cache lease renewal implementation: 本文档是 PR #41383 引入的租约续期机制的设计文档，为该功能的实现提供设计说明和参考。