执行摘要

• 一句话：迁移混合 SWA 和 dtype 配置到声明式 override 系统
• 推荐动作：推荐审核或后续开发者关注 Exaone 分支的 explicit-backend assert 是否也应迁移到 override provider 中以完全消除 server_args.py 中的模型特定逻辑。本 PR 是声明式配置 stack 的重要组成部分，值得精读以理解如何将遗留命令式配置改写为声明式 override。

功能与动机

作为声明式配置重构 stack (9/15) 的一部分，目标是移除所有在 ServerArgs 上直接写入配置的遗留代码，将模型特定的配置调整统一注册到 overrides.py 的声明式模型中。PR body 指出：“every dtype writer inside the arch monolith is now declarative”，零新增白名单成本（zero new whitelist cost）地完成字段族清理。

实现拆解

1. 在 overrides.py 中新增四个 override provider：
   • _gemma2_gemma3_overrides：为 Gemma2、Gemma3 及其变体无条件返回 {"disable_hybrid_swa_memory": True}，忠实移植原来整个条件分支。
   • _exaone_overrides：根据 hf_config.sliding_window_pattern 是否为 None 条件返回，同时说明原分支中的 explicit-backend assert 保留在 server_args.py 中未迁移。
   • _olmo2_overrides：与 Gemma 类似，无条件禁用 hybrid SWA memory。
   • _gpt_oss_overrides：整合了两段原逻辑：XPU dtype 校验（读取 pristine server_args.dtype 并抛出 NotImplementedError）和 mxfp4 量化时强制 dtype 为 bfloat16；这是第一个由模型配置推导出的 dtype 声明（model-config-derived declaration）。
2. 清理 server_args.py 中对应的分支：删除 Gemma2ForCausalLM、Exaone4ForCausalLM、Olmo2ForCausalLM 中写入 disable_hybrid_swa_memory 的赋值，删除 GptOssForCausalLM 中 XPU dtype 校验以及 mxfp4 强制 bfloat16 的赋值，保留平台相关的 attention_backend 选择和 moe_runner_backend 选择等不受影响的部分，并在删除处添加迁移注释。
3. 新增 7 个测试用例：在 test_model_overrides.py 中增加直接测试每个新 provider 行为的用例，覆盖：Gemma2 和 Olmo2 的无条件禁用、Exaone 的条件分支、Exaone 无 pattern 时返回空、GptOss 在 mxfp4 量化时强制 bfloat16、无量化时保持原始 dtype、以及 XPU 平台对 float16 的校验抛出异常。测试同时验证 dual-apply（直接写 ServerArgs）和 publish 后的 flag 层结果，确保与旧行为一致。

关键文件：

• python/sglang/srt/arg_groups/overrides.py（模块 配置层；类别 source；类型 dependency-wiring；符号 _gemma2_gemma3_overrides, _exaone_overrides, _gpt_oss_overrides, _olmo2_overrides）: 核心配置注册表，新增 4 个 override provider，定义了 Gemma2/Gemma3、Exaone、GptOss、Olmo2 的模型特定配置迁移逻辑，是声美化重构的关键文件。
• test/registered/unit/test_model_overrides.py（模块 测试；类别 test；类型 test-coverage；符号 test_gemma2_disables_hybrid_swa_memory, test_olmo2_disables_hybrid_swa_memory, test_exaone_conditional_on_sliding_window_pattern, test_exaone_without_pattern_declares_nothing）: 新增 7 个测试用例，覆盖所有新 override provider 的主路径和边界条件，确保迁移后行为与旧代码一致。
• python/sglang/srt/server_args.py（模块 服务器参数；类别 source；类型 core-logic）: 清理 Gemma2/Gemma3、Exaone、Olmo2、GptOss 中旧的条件写入逻辑，精简 37 行代码，并保留迁移注释。

关键符号：_gemma2_gemma3_overrides, _exaone_overrides, _gpt_oss_overrides, _olmo2_overrides, test_gemma2_disables_hybrid_swa_memory, test_olmo2_disables_hybrid_swa_memory, test_exaone_conditional_on_sliding_window_pattern, test_exaone_without_pattern_declares_nothing, test_gpt_oss_mxfp4_forces_bfloat16, test_gpt_oss_without_mxfp4_keeps_pristine_dtype, test_gpt_oss_xpu_dtype_validation_reads_pristine

关键源码片段

python/sglang/srt/arg_groups/overrides.py

核心配置注册表，新增 4 个 override provider，定义了 Gemma2/Gemma3、Exaone、GptOss、Olmo2 的模型特定配置迁移逻辑，是声美化重构的关键文件。

# python/sglang/srt/arg_groups/overrides.py
​
@_register_for(
    "Gemma2ForCausalLM",
    "Gemma3ForCausalLM",
    "Gemma3ForConditionalGeneration",
    "Gemma3nForCausalLM",
    "Gemma3nForConditionalGeneration",
)
def _gemma2_gemma3_overrides(server_args: Any, hf_config: Any) -> dict:
    # FIXME: #7367 与 Gemma2 不兼容，见关联 CI 失败
    logger.warning(
        f"Disable hybrid SWA memory for {hf_config.architectures[0]} as it is not yet supported."
    )
    # 无条件禁用 hybrid SWA memory，忠实移植原无条件分支
    return {"disable_hybrid_swa_memory": True}
​
​
@_register_for("GptOssForCausalLM")
def _gpt_oss_overrides(server_args: Any, hf_config: Any) -> dict:
    # XPU dtype 校验：读取 pristine server_args.dtype，与旧代码读取 self.dtype 等价
    if is_xpu():
        if server_args.dtype == "auto":
            logger.warning(
                "GptOssForCausalLM on Intel XPU currently supports bfloat16 dtype only"
            )
        elif server_args.dtype not in ["bfloat16"]:
            raise NotImplementedError(
                f"GptOssForCausalLM on Intel XPU only supports bfloat16 dtype, "
                f"but got '{server_args.dtype}'. Please use --dtype bfloat16 or remove --dtype to use auto."
            )
    # mxfp4 量化时强制 dtype 为 bfloat16，读取 hf_config 中的 quantization_config
    quantization_config = getattr(hf_config, "quantization_config", None)
    if (
        quantization_config is not None
        and quantization_config.get("quant_method") == "mxfp4"
    ):
        return {"dtype": "bfloat16"}
    return {}

test/registered/unit/test_model_overrides.py

新增 7 个测试用例，覆盖所有新 override provider 的主路径和边界条件，确保迁移后行为与旧代码一致。

# test/registered/unit/test_model_overrides.py
​
def test_gpt_oss_mxfp4_forces_bfloat16(self):
    from sglang.srt.layers.quantization import QUANTIZATION_METHODS
    # mxfp4 注册是平台依赖的，非 CUDA/CPU 引擎可能跳过
    if "mxfp4" not in QUANTIZATION_METHODS:
        self.skipTest("mxfp4 quantization is not registered on this platform")
    sa = self._construct(
        "GptOssForCausalLM",
        "llama",
        config_extra={"quantization_config": {"quant_method": "mxfp4"}},
    )
    # dual-apply 后应与旧行为一致：dtype 被强制为 bfloat16
    self.assertEqual(sa.dtype, "bfloat16")
    self.assertEqual(self._publish(sa).dtype, "bfloat16")
​
def test_gpt_oss_xpu_dtype_validation_reads_pristine(self):
    from sglang.srt.arg_groups.overrides import _gpt_oss_overrides
    # 模拟 XPU 环境下传入 float16，应抛出 NotImplementedError
    with patch.object(overrides_module, "is_xpu", return_value=True):
        with self.assertRaises(NotImplementedError):
            _gpt_oss_overrides(
                SimpleNamespace(dtype="float16"),
                SimpleNamespace(architectures=["GptOssForCausalLM"]),
            )

评论区精华

无 review 讨论。PR 由作者自行合并，仅包含一条 gemini-code-assist 的配额提示评论。

• 暂无高价值评论线程

风险与影响

• 风险：主要风险在于迁移过程中逻辑可能不一致，特别是 GptOss 的 mxfp4 dtype 强制：旧代码在 server_args.py 中分两处计算 is_mxfp4_quant_format（重复计算），迁移后只在 override provider 中计算一次，行为需要对齐；测试已覆盖主路径。XPU dtype 校验从读取 self.dtype（可能已被前置分支修改）改为读取 server_args.dtype（pristine 输入），旧代码在 GptOss 分支之前没有其他 dtype 写入，因此 server_args.dtype 与 self.dtype 等价，风险较低。Exaone 的 explicit-backend assert 留在 server_args.py 中未迁移，若未来改动可能遗漏。
• 影响：对用户无功能影响（纯重构）。对开发者影响：配置逻辑集中到 overrides.py，减少 server_args.py 中的条件蔓延；新增的 override provider 遵循统一的声明式模式，便于后续维护；测试覆盖增强，提高回归防护。server_args.py 精简了 37 行代码。
• 风险标记：配置迁移行为需对齐, Exaone 分支断言未迁移, mxfp4 测试依赖平台, 核心路径变更

关联脉络

• PR #30072 [refactor] Add the post-process resolution stage; migrate sampling_backend (stack 10/15): 同一声明式配置 stack 的上下 PR，先迁移采样后端后处理阶段，本 PR 在此基础上迁移 disable_hybrid_swa_memory 和 dtype。
• PR #30073 [refactor] Migrate the attention_backend resolution chain (stack 11/15): 同一 stack 中迁移 attention_backend，与本 PR 迁移的 disable_hybrid_swa_memory 属于同一注意力配置领域。
• PR #30076 [refactor] Migrate the DeepSeek family and the parallel-request chains (stack 14/15): 同一 stack 中迁移 DeepSeek 配置，采用完全相同的声明式模式，本 PR 是其前置步骤。
• PR #30077 [refactor] Rename Arg.model_overridable to Arg.resolvable (stack 15/15): 同一 stack 的最终 PR，统一重命名基础设施，本 PR 直接依赖其引入的注册机制。