# PR #27374 完整报告

- 仓库：`sgl-project/sglang`
- 标题：fix(pd): clear stale bootstrap_room when freeing metadata buffer slot
- 合并时间：2026-06-05 19:46
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/27374

---

# 执行摘要

- 一句话：修复 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
# 文件 : 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 都旨在解决 / 改进该问题。