执行摘要

该PR修复了调度器空闲路径在混合SSM（Mamba）场景下token_usage统计缺失Mamba使用量的bug，通过统一使用max(full_token_usage, mamba_usage)计算确保与预填充/解码路径一致。同时添加FIXME注释澄清字段命名问题，为未来API重构铺垫。变更影响限于内部统计准确性，风险较低。

功能与动机

根据PR body，修复动机源于历史不一致性：空闲路径在#12014引入，而预填充/解码路径在#17862重构后已正确包含mamba_usage，但空闲路径未同步更新。这导致在is_hybrid_ssm=True（混合SSM场景）时，self.stats.token_usage仅使用full_token_usage，忽略了mamba_usage，使得内存使用统计不准确。修复目标是确保所有路径（空闲、预填充、解码）的统计逻辑一致。

实现拆解

实现分为两个关键部分：

1. 核心逻辑修复（scheduler_runtime_checker_mixin.py）：
   • 在check_memory方法中，当is_hybrid_ssm=True时，将token_usage计算从直接使用full_token_usage改为max(full_token_usage, mamba_usage)。
   • 代码片段：
     

     full_token_usage, mamba_usage, _, _, _, _, _ = self._get_mamba_token_info()
     token_usage = max(full_token_usage, mamba_usage)
     

2. 文档注释添加（io_struct.py和metrics_collector.py）：
   • 在token_usage字段定义处添加FIXME注释，说明该字段实际表示所有内存池（KV、SWA、mamba）的最大使用率，而非仅KV token使用率。
   • 注释示例：# FIXME: token_usage is actually max usage across all pools (KV, SWA, mamba), not just KV token usage. Rename requires API deprecation.

评论区精华

由于该PR没有公开的review评论（review_comments_count: 0），讨论有限。从提交历史看，作者hnyls2002分两次提交：先修复逻辑（提交消息："fix idle token_usage missing mamba_usage"），后添加注释（提交消息："add FIXME for token_usage naming"），表明是自审自合并的PR。关联Issue评论中，作者通过/rerun-test和/tag-and-rerun-ci命令触发CI测试，确保修复通过现有Mamba测试套件。

风险与影响

• 技术风险：核心变更仅影响统计计算，不涉及内存分配或调度算法，回归风险低。但token_usage字段的命名误导性可能影响监控数据解读，不过注释已明确说明。
• 影响范围：
  • 对用户：无直接影响，纯内部修复。
  • 对系统：提升混合SSM场景下内存使用统计的准确性，有助于运维监控。
  • 对团队：澄清字段含义为未来可能的API重命名（需弃用流程）提供上下文，但当前保持向后兼容。

关联脉络

• 历史PR关联：

  • 12014：引入了空闲路径，是本修复的起源点。

  • 17862：重构了预填充/解码路径以包含mamba_usage，但未更新空闲路径，导致不一致性，是本修复的直接原因。

• 演进趋势：该PR是SGLang内存管理演进中的小步修复，反映了项目对混合SSM（如Mamba）支持逐步完善。近期历史PR中，如#22340（修复多层EAGLE草案扩展）、#22380（优化Mamba跟踪索引性能），也涉及推测解码和Mamba优化，显示团队在该领域的持续投入。