执行摘要

• 一句话：修复 PP decode 路径中 HiSparse 设备元数据未初始化问题
• 推荐动作：值得精读以理解 HiSparse 在 PP decode 路径中的初始化机制。建议将 process_retract_queue 的类似问题也纳入修复范围，并增加相应测试用例。

功能与动机

PP decode 路径使用了独立的释放流程 process_decode_transfer_queue()，但跳过了 admit_request_direct(req) 调用，导致请求开始 decode 时虽然 host KV 就绪，但 HiSparse 设备缓冲区元数据未初始化，破坏了 HiSparse swap-in。PR body 明确说明 "the PP release path match the non-PP path by calling admit_request_direct(req) before adding released requests to waiting_queue"。

实现拆解

1. 在 python/sglang/srt/managers/scheduler_pp_mixin.py 的 process_decode_transfer_queue 方法中，在将已传输完成的请求加入 waiting_queue 之前，增加条件判断 if self.enable_hisparse:，遍历 released_reqs 并调用 self.hisparse_coordinator.admit_request_direct(req)。
2. 该调用初始化 HiSparse 设备端缓冲区元数据（如 GPU 缓存槽位信息），使后续 decode 阶段的 swap-in 能正确工作。
3. 变更仅 3 行新增代码，不涉及配置、测试或部署配套改动。

关键文件：

• python/sglang/srt/managers/scheduler_pp_mixin.py（模块 调度器；类别 source；类型 core-logic；符号 process_decode_transfer_queue）: 核心修复文件：在 process_decode_transfer_queue 方法中增加 HiSparse admission 调用，3 行新增代码直接修复 PP decode 路径中 HiSparse 设备元数据缺失问题。

关键符号：process_decode_transfer_queue

关键源码片段

python/sglang/srt/managers/scheduler_pp_mixin.py

核心修复文件：在 process_decode_transfer_queue 方法中增加 HiSparse admission 调用，3 行新增代码直接修复 PP decode 路径中 HiSparse 设备元数据缺失问题。

def process_decode_transfer_queue(
    self: Scheduler, release_rids: Optional[List[str]]
):
    if release_rids is not None:
        released_reqs = self.disagg_decode_transfer_queue.pop_transferred(
            release_rids
        )
        # PP decode 路径必须与非 PP 路径一致：
        # 在加入 waiting_queue 前初始化 HiSparse 设备缓冲区元数据，
        # 否则后续 swap-in 会因缺失 GPU 缓存槽位信息而失败。
        if self.enable_hisparse:
            for req in released_reqs:
                self.hisparse_coordinator.admit_request_direct(req)
        self.waiting_queue.extend(released_reqs)
        return [req.rid for req in released_reqs]
    return None

评论区精华

Gemini Code Assist 机器人指出 process_retract_queue 中存在类似问题：请求被 retract 后 HiSparse 资源完全释放，但 resume 时直接加入 waiting_queue 而未调用 admit_request_direct，可能导致 swap-in 失败或输出错误，建议在此处也应用相同逻辑。该建议未在后续讨论中被采纳或回应，状态为未解决。

• process_retract_queue 也存在类似问题 (correctness): 未在 PR 中修复，也未见作者回应。该问题仍然存在。

风险与影响

• 风险：变更仅在 if self.enable_hisparse 条件下执行，不影响 HiSparse 未启用时的行为。但 process_retract_queue 未同步修复，若用户在 retract 后恢复请求，仍可能遇到 HiSparse 元数据缺失问题。此外，缺少针对该修复的单元测试覆盖。
• 影响：直接影响 enable_hisparse + direct-to-host + pp_size > 1 场景（即 PP decode 使用 HiSparse 和直接到主机 KV 传输），修复了核心准确率问题。对其他 HiSparse 组合无影响，非 HiSparse 用户完全无影响。代码改动极小，回归风险低。
• 风险标记：同模块有未修复的类似问题, 缺少测试覆盖

关联脉络

• PR #27489 Fix TP deadlock in unified radix cache writing_check / loading_check: 同时涉及 HiCach/HiSparse 和多进程调度路径的 bugfix，属于同一维护方向。