# PR #22990 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[Bug Fix] Ensure prefill_info_table is populated before honoring disagg_prefill_dp_rank
- 合并时间：2026-04-17 11:10
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/22990

---

# 执行摘要

- 一句话：修复解聚模式下首个请求携带 disagg_prefill_dp_rank 时因缓存未初始化而失败的问题。
- 推荐动作：该 PR 值得精读，特别是 `_resolve_prefill_dp_rank` 方法的调整，展示了缓存初始化与客户端参数处理的正确顺序，对于理解解聚模式下的请求处理流程有参考价值。

# 功能与动机

根据 PR body 描述，当首个请求携带 `disagg_prefill_dp_rank` 参数时，会因 `prefill_info_table` 缓存未初始化而失败，错误信息为“Prefill server with bootstrap_addr: {self.bootstrap_addr} is healthy before”。根本原因是 `_resolve_prefill_dp_rank` 方法中，对 `req.disagg_prefill_dp_rank` 的检查早于缓存查询，导致缓存未被填充，后续健康检查失败。

# 实现拆解

1. **核心逻辑调整**：修改 `python/sglang/srt/disaggregation/decode.py` 中的 `_resolve_prefill_dp_rank` 方法，将 `prefill_info = self.kv_manager.prefill_info_table.get(_bootstrap_addr(req))` 移到方法开头，并优先检查缓存是否存在。如果缓存为空，则返回 `None`，触发慢路径查询和填充缓存。
2. **调试日志添加**：在 `add` 方法中，为 `prefill_dp_rank` 添加 `logger.debug` 日志输出，便于追踪调试。
3. **测试代码优化**：修改 `test/registered/unit/managers/test_hisparse_unit.py` 中的 `_assert_matches_naive` 方法，将变量名 `nd` 和 `kd` 重命名为更具描述性的 `naive_data` 和 `kernel_data`，以修复 lint 错误并提升代码可读性。

关键文件：
- `python/sglang/srt/disaggregation/decode.py`（模块 解聚模块；类别 source；类型 core-logic；符号 _resolve_prefill_dp_rank, add）: 核心逻辑文件，修复了缓存初始化与客户端参数处理的顺序问题。
- `test/registered/unit/managers/test_hisparse_unit.py`（模块 HiCache；类别 test；类型 test-coverage；符号 _assert_matches_naive）: 测试文件，修复了 lint 错误并优化了变量命名。

关键符号：_resolve_prefill_dp_rank, add, _assert_matches_naive


## 关键源码片段

### `python/sglang/srt/disaggregation/decode.py`

核心逻辑文件，修复了缓存初始化与客户端参数处理的顺序问题。

```python
def _resolve_prefill_dp_rank(self, req: Req) -> Optional[int]:
    # 优先查询缓存，确保 prefill_info_table 被初始化
    prefill_info = self.kv_manager.prefill_info_table.get(_bootstrap_addr(req))
    # 如果缓存为空，返回 None，触发慢路径查询并填充缓存
    if prefill_info is None:
        return None

    # 缓存存在后，再处理客户端提供的 disagg_prefill_dp_rank
    if req.disagg_prefill_dp_rank is not None:
        return req.disagg_prefill_dp_rank

    # 根据缓存信息计算预填充 DP rank
    if prefill_info.dp_size == 1:
        return 0

    if (
        prefill_info.follow_bootstrap_room
        and not envs.SGLANG_DISAGGREGATION_FORCE_QUERY_PREFILL_DP_RANK.get()
    ):
        return req.bootstrap_room % prefill_info.dp_size

    return None
```

# 评论区精华

Review 讨论较少，仅有一条评论来自 ByronHsu，指出测试文件中存在 lint 错误需要修复。ShangmingCai 批准了 PR，未提出其他争议或疑虑。

- 测试文件 lint 错误修复 (style): 变量名被重命名为更具描述性的形式，修复了 lint 错误。

# 风险与影响

- 风险：1. **回归风险**：修改了 `_resolve_prefill_dp_rank` 方法的执行顺序，可能影响其他依赖此方法的逻辑，但变更较小且逻辑清晰，风险较低。
2. **性能风险**：在 `add` 方法中添加了调试日志，可能在生产环境中引入轻微性能开销，但日志级别为 debug，通常不影响性能。
3. **兼容性风险**：无，此变更修复了现有 bug，不涉及接口或行为变更。
- 影响：1. **用户影响**：修复了 PD 模式下首个请求携带 `disagg_prefill_dp_rank` 时的失败问题，提升了系统稳定性和用户体验。
2. **系统影响**：确保缓存机制正确工作，避免因缓存未初始化导致的健康检查失败，影响请求处理流程。
3. **团队影响**：代码变更较小，易于理解和维护，测试覆盖调整有助于提升代码质量。
- 风险标记：核心路径变更 , 缺少测试覆盖

# 关联脉络

- PR #22406 [sgl] improve accuracy of additional page requirement during spec decode: 同属调度和解聚相关优化，涉及内存分配和请求处理逻辑。
- PR #22989 [Ray] Bind scheduler actors to GPU-local NUMA node: 同属调度模块的改进，关注性能优化和资源绑定。