执行摘要

• 一句话：重构 Mamba radix cache 配置并重命名参数
• 推荐动作：值得精读，尤其是 _handle_mamba_radix_cache 的扁平化重构和 DeprecatedAction 使用。注意后续跟进将 assert 替换为 ValueError 以保证生产环境健壮性。

功能与动机

关联 issue #27418 指出 Mamba radix cache 策略选择代码散布在三处互相干扰，且名称 mamba_scheduler_strategy 易引起混淆。PR 旨在清理代码，将逻辑扁平化为四步结构，仅在 radix cache 启用时运行。

实现拆解

1. 重命名常量和属性：将 MAMBA_SCHEDULER_STRATEGY_CHOICES 改为 MAMBA_RADIX_CACHE_STRATEGY_CHOICES，server_args.mamba_scheduler_strategy 改为 mamba_radix_cache_strategy。
2. 重构 _handle_mamba_radix_cache：简化签名，移除 support_mamba_cache 等参数，内部通过新辅助方法 _support_mamba_cache_extra_buffer 判断模型能力；添加步骤：缓存关闭跳过 → 模型不支持则关闭 → 自动选择策略 → 验证策略。
3. 提取验证方法：新增 _validate_mamba_no_buffer 和 _validate_mamba_extra_buffer，将模型特定断言集中到这两个方法中。
4. 清理调用点：在 server_args.py、nemotron_h_hook.py、pd_disaggregation_hook.py 中移除多余参数传递；pd_disaggregation_hook.py 删除 decode 模式强制覆写策略的代码，因为现在由 _handle_mamba_radix_cache 统一处理。
5. 添加 DeprecatedAction：CLI 参数同时支持 --mamba-scheduler-strategy 和 --mamba-radix-cache-strategy，旧名称发出废弃警告，保障向后兼容性。

关键文件：

• python/sglang/srt/server_args.py（模块 启动配置；类别 source；类型 core-logic；符号 _handle_mamba_radix_cache, _support_mamba_cache_extra_buffer, _validate_mamba_no_buffer, _validate_mamba_extra_buffer）: 核心文件，重构了 Mamba radix cache 配置初始化逻辑，重命名参数并提取验证方法。
• python/sglang/srt/arg_groups/nemotron_h_hook.py（模块 模型 Hook；类别 source；类型 core-logic；符号 apply_nemotron_h_defaults）: 简化为调用 _handle_mamba_radix_cache，移除了依赖旧版本参数传递。
• python/sglang/srt/arg_groups/pd_disaggregation_hook.py（模块 解聚 Hook；类别 source；类型 core-logic；符号 handle_pd_disaggregation）: 移除 decode 模式下强制覆写 mamba_scheduler_strategy 的代码，依赖统一逻辑。

关键符号：_handle_mamba_radix_cache, _support_mamba_cache_extra_buffer, _validate_mamba_no_buffer, _validate_mamba_extra_buffer, apply_nemotron_h_defaults, handle_pd_disaggregation

关键源码片段

python/sglang/srt/server_args.py

核心文件，重构了 Mamba radix cache 配置初始化逻辑，重命名参数并提取验证方法。

# 常量重命名
MAMBA_RADIX_CACHE_STRATEGY_CHOICES = [
    "auto",
    "no_buffer",
    "extra_buffer",
    "extra_buffer_lazy",
]
​
class ServerArgs:
    # 属性重命名
    mamba_radix_cache_strategy: str = "auto"
​
    # CLI 参数添加 DeprecatedAction
    parser.add_argument(
        "--mamba-scheduler-strategy",
        "--mamba-radix-cache-strategy",
        type=str,
        default="auto",
        action=DeprecatedAction,
        help="...",
    )

评论区精华

• assert 使用风险：gemini-code-assist[bot] 指出使用 assert 验证用户输入在 -O 下会被跳过，建议改为 ValueError。该问题未在本次 PR 修复，需后续跟进。
• spec 兼容性：ispobock 询问 no_buffer 是否需要专门验证 spec，yizhang2077 回应 no_buffer 兼容 spec，无需额外限制。
• Kimi 模型支持：merrymercy 询问 Kimi 模型处理方式，PR 已添加 KimiLinearForCausalLM 的 no_buffer 绕过，但架构硬编码问题未根本解决。

• 文档更新：ispobock 要求更新文档及设置 DeprecatedAction，已通过 CLI 参数实现。

  • assert 使用不当 (correctness): 需修复，但 PR 已合并，作为后续跟进。
  • 需要更新文档和 DeprecatedAction (documentation): 开发者已添加 DeprecatedAction，文档后续更新。
  • spec 模式与 no_buffer 兼容性 (question): yizhang2077 回应 no_buffer 兼容 spec，无需额外逻辑。
  • Kimi 模型和架构硬编码 (design): PR 添加了 KimiLinearForCausalLM 的 no_buffer 支持，但架构字符串硬编码未被解决，留待后续改进。

风险与影响

• 风险：
  • assert 绕过风险：_validate_mamba_no_buffer 和 _validate_mamba_extra_buffer 使用 assert 进行配置校验，若以 -O 运行 Python，校验会被跳过，可能导致静默的不兼容配置。
  • 参数重命名兼容性：旧参数名通过 DeprecatedAction 保留，但用户可能未注意到警告并迁移，短期无中断风险。
  • 行为变化：pd_disaggregation_hook 移除了强制设置 no_buffer 的逻辑，当 decode 禁用 radix cache 时，策略不再被覆写；预期行为正确，但可能影响依赖旧行为的自定义部署脚本。
  • 缺少测试覆盖：本次重构未新增测试用例，验证方法可能在边界条件下存在缺陷。
• 影响：
  • 用户：参数名变化，但旧名仍可用，短期无影响；长期需迁移到新名称。
  • 系统：启动配置更清晰，减少了配置冲突的可能性，尤其是混合模型和分解场景。
  • 团队：维护性提高，新模型接入 mamba radix cache 时只需按约定添加架构字符串即可。
  • 风险标记：assert 绕过风险, 参数重命名兼容, 行为变化

关联脉络

• 暂无明显关联 PR