执行摘要

本PR澄清了HiSparse稀疏注意力场景下的解码令牌使用日志，将原有单一的令牌统计细分为GPU令牌和CPU令牌的详细使用情况，增强了资源监控的清晰度；变更涉及hisparse_coordinator和scheduler_runtime_checker_mixin两个模块，通过新增统计数据和日志逻辑实现，风险较低，适合关注HiSparse性能监控的开发者参考。

功能与动机

PR的动机源于HiSparse环境中日志信息不够清晰的问题。在before日志中，仅显示#token: 20800, token usage: 0.29，无法区分GPU和CPU的令牌使用；after日志新增了#gpu-token: 20800, gpu token usage: 0.29, #cpu-token: 41422, cpu token usage: 0.29，从而提供更精确的资源利用率洞察，帮助用户更好地调试和优化HiSparse配置。

实现拆解

实现主要包括两个文件的关键改动：

• python/sglang/srt/managers/hisparse_coordinator.py：
  • 新增HiSparseTokenStats NamedTuple，包含device_tokens、device_token_usage、host_tokens、host_token_usage字段。
  • 新增get_token_stats方法，通过分配器计算设备（GPU）和主机（CPU）的令牌使用量和利用率。
    

    def get_token_stats(self) -> HiSparseTokenStats:
        device_allocator = self.token_to_kv_pool_allocator.hisparse_attn_allocator
        device_capacity = device_allocator.size
        device_tokens = device_capacity - device_allocator.available_size()
        host_capacity = self.mem_pool_host.size
        host_tokens = host_capacity - self.mem_pool_host.available_size()
        return HiSparseTokenStats(
            device_tokens=device_tokens,
            device_token_usage=(device_tokens / device_capacity if device_capacity > 0 else 0.0),
            host_tokens=host_tokens,
            host_token_usage=(host_tokens / host_capacity if host_capacity > 0 else 0.0),
        )
    

• python/sglang/srt/managers/scheduler_runtime_checker_mixin.py：
  • 扩展PoolStats类，添加is_hisparse、hisparse_device_tokens、hisparse_device_token_usage、hisparse_host_tokens、hisparse_host_token_usage字段。
  • 新增_get_hisparse_token_info方法，调用hisparse_coordinator.get_token_stats()并更新PoolStats。
  • 修改get_decode_usage_msg_parts方法，在HiSparse启用时输出细分统计到日志。

评论区精华

review讨论较少，核心点是字段命名建议：

• hzh0425评论："can we rename to host_tokens_usage"，针对cpu_tokens字段。
• 最终代码已使用host_tokens和host_token_usage，表明建议被采纳，命名更统一，无其他争议。

风险与影响

• 风险：日志格式变更可能破坏依赖旧格式的监控工具，需协调更新；新增统计计算引入轻微性能开销（除法运算），但仅在日志路径，影响可忽略；代码改动集中，回归风险低，但建议补充测试确保正确性。
• 影响：用户获得更详细的HiSparse资源使用日志，便于性能分析；系统可观测性提升，无功能副作用；团队受益于增强的监控能力。

关联脉络

从同仓库历史PR看，暂无直接相关的HiSparse PR；但PR 18016（新增HiCache存储后端）涉及类似缓存和监控主题，可间接参考架构模式。本PR独立于其他功能演进，专注于HiSparse模块的日志改进。