执行摘要

本PR更新了HybridSWAPoolConfigurator的注释，澄清全SWA（all-SWA）与混合模式（hybrid）在内存池配置中的语义差异，特别是cell_size计算和比例因子的应用。仅修改文档，无代码逻辑变更，但review评论揭示了混合模式下可能存在的内存浪费问题，值得后续关注。

功能与动机

PR旨在提升代码可读性，明确内存池配置逻辑。从patch可见，原始注释对全SWA模式（full_layers == 0）和混合模式（full_layers > 0）的描述不够清晰，例如全SWA模式下比例因子（ratio）是否应用、混合模式下cell_size如何计算。更新后的注释详细解释了这些差异，帮助开发者避免误解。

实现拆解

仅修改python/sglang/srt/model_executor/pool_configurator.py文件，关键变更点如下：

1. __init__方法注释更新：

   • 澄清全SWA模式下cell_size = S*ns（不应用比例因子），因为“没有完整池可关联，比例无意义”。
   • 说明混合模式下cell_size = F*nf + r*S*ns，同时考虑完整池和SWA池。

2. _solve_pool_sizes方法注释更新：

   • 在全SWA分支添加注释“比例不应用——参见__init__注释”，建立交叉引用。
   • 简化混合分支注释，明确full_tokens和swa_tokens的计算关系。

评论区精华

review中仅有一条来自gemini-code-assist[bot]的评论，指出潜在设计问题：

“注释称max_total = full_tokens，但model_runner.py中max_token_pool_size属性定义为min(self.swa_max_total_num_tokens, self.max_total_num_tokens)。由于swa_tokens = full_tokens * ratio（ratio < 1），调度器实际限制是swa_tokens，导致完整池内存浪费。”

此评论未获回复，揭示了混合模式下内存可能未充分利用的风险，但本PR未涉及代码修复。

风险与影响

• 风险：PR本身仅修改注释，无直接技术风险。但review评论暴露的混合模式内存浪费问题可能影响内存使用效率，需评估是否优化。
• 影响：对用户无功能影响；提升代码可读性，有助于团队理解内存池配置；影响范围限于使用pool_configurator.py的模块。

关联脉络

• 与PR #22389（引入MemoryPoolConfigurator类层次）直接相关，该PR创建了本文件的核心逻辑。
• 与PR #22420（为MemoryPoolConfigurator添加测试）间接相关，属于同一模块的测试补充。
• 近期历史PR中多涉及scheduling和refactor标签（如#22405、#22389），表明内存池配置是持续优化领域，本PR的文档澄清是这一演进的一部分。