执行摘要

• 一句话：修复 PD 解耦模式下 bootstrap_room 残留导致的误报
• 推荐动作：值得合并，修复了 PR #17430 的回归；建议阅读代码中 _commit_transfer_to_req() 的 sentinel 逻辑以理解上下文。

功能与动机

Issue #17259 报告了 PD 解耦模式下的上下文损坏问题，PR #17430 通过增加 bootstrap_room 验证来检测损坏，但未在 free() 时清零该字段。这使得 sentinel 假设（actual_room == 0 表示“未写入”）在槽位复用后失效，导致高并发下约 3% 的请求被错误中止。本 PR 通过一行清零操作解决了该回归。

实现拆解

1. 在 DecodeTransferQueue.pop_transferred() 方法中，定位到释放元数据缓冲区索引的代码段（decode.py 第 1677-1682 行）。
2. 在调用 self.req_to_metadata_buffer_idx_allocator.free(idx) 之前，新增一行：self.metadata_buffers.bootstrap_room[idx] = 0。
3. 这样当槽位被重新分配时，新请求读取到的 actual_room 为 0，满足 sentinel 条件，等待 prefill 端写入有效值，从而避免误报。
4. 该修改仅涉及 3 行新增代码，无其他配置或测试配套变更。

关键文件：

• python/sglang/srt/disaggregation/decode.py（模块 调度器；类别 source；类型 core-logic）: 核心修复文件：在释放元数据缓冲区索引前将 bootstrap_room 清零，消除 sentinel 误报。

关键符号：未识别

关键源码片段

python/sglang/srt/disaggregation/decode.py

核心修复文件：在释放元数据缓冲区索引前将 bootstrap_room 清零，消除 sentinel 误报。

# 文件 : python/sglang/srt/disaggregation/decode.py
# 方法 : DecodeTransferQueue.pop_transferred()
# 关键修改 : 在 free() 前清零 bootstrap_room
​
for i in indices_to_remove:
    if self.enable_staging and self.staging_handler.is_staging_room(
        self.queue[i].req.bootstrap_room
    ):
        self.staging_handler.unregister_decode_req(
            self.queue[i].req.bootstrap_room
        )
    idx = self.queue[i].metadata_buffer_index
    assert idx != -1
    # 清零以保证下一个使用者读取到的 actual_room == 0 （" 尚未写入 "）
    # 而非残留的旧值，避免虚假的 mismatch 误报
    self.metadata_buffers.bootstrap_room[idx] = 0
    self.req_to_metadata_buffer_idx_allocator.free(idx)
​
self.queue = [
    entry for i, entry in enumerate(self.queue) if i not in indices_to_remove
]
​
return transferred_reqs

评论区精华

Review 中 gemini-code-assist[bot] 的评论确认了修改的正确性，指出没有额外反馈。ShangmingCai 批准了 PR（LGTM）。无争议性讨论。

• 暂无高价值评论线程

风险与影响

• 风险：风险较低：修改为单行清零操作，逻辑明确。但测试覆盖不足：本次改动未增加单元测试或集成测试来验证场景。建议后续添加针对槽位复用和竞态条件的测试。
• 影响：直接影响 PD 解耦模式下使用 TCP 传输的高并发场景（约 3% 的请求误报被消除）。对 RDMA 场景无副作用。不会影响其他非 PD 模式。
• 风险标记：缺少测试覆盖

关联脉络

• PR #17430 Add bootstrap_room validation to detect metadata corruption in PD disaggregation: 引入了 bootstrap_room 验证机制，但未在 free() 时清零，导致本 PR 修复的回归。
• PR #17259 [Critical Bug] Context corruption in PD disaggregation mode due to metadata buffer index race condition: 原始 bug 报告，PR #17430 和本 PR 都旨在解决/改进该问题。