执行摘要

• 一句话：修复解聚模式下首个请求携带 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

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

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: 同属调度模块的改进，关注性能优化和资源绑定。