执行摘要

• 一句话：将 attention_backend 解析链迁移至声明式覆盖系统
• 推荐动作：建议架构师和关注配置分层的开发者精读 overrides.py 中各声明函数的实现，特别是 slot 保留机制和 refresh_declared_fields 的作用。一般开发者了解变更范围和测试覆盖即可。

功能与动机

PR body 指出 attention_backend 解析链在 legacy 代码中分布于多个过程式分支，难以组合和测试。迁移到声明式覆盖系统使每个架构族独立注册，最后写入者获胜保证行为不变，同时消除 ServerArgs 的直接变异，提升可维护性和可测试性。

实现拆解

1. 声明式覆盖函数：在 overrides.py 中为 GptOss、Llama4、Gemma4、MiniCPM-V4.6、FalconH1/Jet、GraniteMoeHybrid、LFM2、GLM4-MoE 等架构族新增 @register_model_override 装饰的函数，使用平台检测（SM90/SM100/XPU/HIP/NPU/CPU-AMX）自动选择 attention_backend。同时添加默认填充、兼容性回退、确定性推理冲突检查、DLLM 平台强制等辅助 pass，保持与 legacy 完全一致的行为。
2. ServerArgs 字段标记：在 server_args.py 中将 attention_backend 字段添加 model_overridable=True，并从 _handle_model_specific_adjustments 中删除对应过程赋值代码，保留 HRM-Text 等非注意力相关分支。
3. 叶子映射：在 runtime_context.py 的 AttnFlags 中添加 backend: str | None 字段，并在 FLAG_LEAF_MAP 中映射 attention_backend -> attn.backend，使 resolved flag 路径化。
4. 后调整刷新：在 model_runner.py 的 model_specific_adjustment 末尾调用 refresh_declared_fields(server_args, ("attention_backend",))，确保被过程代码（如 HRM-Text）覆盖的声明字段重新同步，维持 publish parity。
5. 测试覆盖：新增 20+ 测试用例，验证各架构族的选择路径、确定性推理与后端冲突抛出 ValueError、DLLM 平台强制 flashinfer、用户选择不被覆盖、兼容性 pass slot 行为、以及叶子端到端一致性。

关键文件：

• python/sglang/srt/arg_groups/overrides.py（模块 配置覆盖；类别 source；类型 dependency-wiring；符号 _gpt_oss_overrides, _llama4_overrides, _gemma4_overrides, _minicpm_v4_6_overrides）: 核心变更文件，新增九个架构族的 attention_backend 声明函数和辅助 pass
• test/registered/unit/test_model_overrides.py（模块 覆盖测试；类别 test；类型 test-coverage；符号 test_attention_backend_leaf_materializes_end_state, test_dllm_forces_flashinfer_with_cuda_graph, test_deterministic_incompatible_backend_raises, test_deterministic_attention_backend）: 新增大量测试覆盖 attention_backend 解析路径，保障迁移后行为不变
• python/sglang/srt/server_args.py（模块 启动参数；类别 source；类型 dependency-wiring）: 删除大量过程代码，标记 attention_backend 为 model_overridable，简化模型特定调整
• python/sglang/srt/model_executor/model_runner.py（模块 模型执行器；类别 source；类型 data-contract）: 添加 refresh_declared_fields 调用以保持声明一致性
• python/sglang/srt/runtime_context.py（模块 运行时上下文；类别 source；类型 core-logic）: 新增 Backend 叶子字段和 FLAG_LEAF_MAP 映射，使 attention_backend 解析结果路径化

关键符号：_gpt_oss_overrides, _llama4_overrides, _gemma4_overrides, _minicpm_v4_6_overrides, _falcon_h1_jet_overrides, _granite_moe_hybrid_overrides, _lfm2_overrides, _glm4_moe_overrides, _step3p_overrides, _olmo2_overrides, _get_default_attn_backend, _default_attention_backend, _compatibility_attention_backend, _dllm_attention_backend, _deterministic_attention_backend, _deterministic_is_deepseek_model, refresh_declared_fields, test_attention_backend_leaf_materializes_end_state, test_dllm_forces_flashinfer_with_cuda_graph, test_deterministic_incompatible_backend_raises, test_dllm_platform_paths_at_callable_level, test_compatibility_passes_at_callable_level, test_attention_backend_user_choice_declares_nothing_extra, test_runner_side_adjustment_can_refresh_declaration

关键源码片段

python/sglang/srt/arg_groups/overrides.py

核心变更文件，新增九个架构族的 attention_backend 声明函数和辅助 pass

@_register_for("GptOssForCausalLM")
def _gpt_oss_overrides(server_args: Any, hf_config: Any) -> dict:
    # 收集所有需要覆盖的字段，最后统一返回声明字典
    overrides: Dict[str, Any] = {}
​
    # 若用户未指定 attention_backend，根据平台自动选择
    if server_args.is_attention_backend_not_set():
        if is_sm100_supported():
            overrides["attention_backend"] = "trtllm_mha"
        elif is_sm90_supported():
            overrides["attention_backend"] = "fa3"
        elif is_cpu() and cpu_has_amx_support():
            overrides["attention_backend"] = "intel_amx"
        elif is_xpu():
            overrides["attention_backend"] = "intel_xpu"
        elif is_hip():
            overrides["attention_backend"] = "aiter"
        else:
            overrides["attention_backend"] = "triton"
​
    # XPU 专有：检查 dtype 是否为 bfloat16
    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}'."
            )
​
    # mxfp4 量化路径需强制 bfloat16（triton 要求）
    quantization_config = getattr(hf_config, "quantization_config", None)
    if quantization_config is not None and quantization_config.get("quant_method") == "mxfp4":
        overrides["dtype"] = "bfloat16"
​
    return overrides

test/registered/unit/test_model_overrides.py

新增大量测试覆盖 attention_backend 解析路径，保障迁移后行为不变

def test_attention_backend_leaf_materializes_end_state(self):
    # 验证默认填充 pass 声明了 attention_backend，且叶子状态与 ServerArgs 一致（publish parity）
    sa = self._construct("LlamaForCausalLM", "llama")
    # _resolved_overrides 记录所有 pass 产生的声明字段
    declared = {field for _, d in sa._resolved_overrides for field in d}
    self.assertIn("attention_backend", declared)
    # 发布后的叶子 Flags 应等于 ServerArgs 最终值
    self.assertEqual(self._publish(sa).attn.backend, sa.attention_backend)

评论区精华

PR 无独立 review 评论（0 条回复）；作为 stack 11/15，迁移方案已在系列 PR 中达成共识，大部分讨论发生在 stack 顶层 PR #30062。

• 暂无高价值评论线程

风险与影响

• 风险：
  1) overrides.py 平台检测兼容性：新增的 platform 分支（如 XPU+AMX、HIP+NPU 组合）可能遗漏边缘场景，导致 fallback 不符合 legacy 行为。
  2) server_args.py 删除遗漏：大量过程代码删除可能漏掉未覆盖的模型特定调整（如 HRM-Text 以外的分支）。
  3) refresh_declared_fields 临时性：model_runner.py 中的刷新机制是事后修补，若其他过程覆盖字段未同步，会产生声明与实际值的不一致窗口。
  4) 叶子映射影响：runtime_context.py 新增 attn.backend 映射，所有读取该叶子的代码现在必须通过 resolved flag 访问，旧路径可能过时。
  • 影响：对用户：attention_backend 自动选择行为完全不变。对开发者：新增架构族只需在 overrides.py 注册一个函数，无需改动 ServerArgs 过程代码，降低未来维护成本。对团队：声明式覆盖模式成为 attention_backend 解析标准，统一了此前分散的赋值策略。测试从 23 行增至 244 行，覆盖显著提升。
  • 风险标记：核心路径变更, 多平台兼容性风险, 声明刷新临时修补, 叶子映射影响旧读取代码

关联脉络

• PR #30077 [refactor] Rename Arg.model_overridable to Arg.resolvable (stack 15/15): 同一堆栈的上层 PR，重命名机制字段，与本 PR 共享覆盖系统基础
• PR #30076 [refactor] Migrate the DeepSeek family and the parallel-request chains (stack 14/15): 此前步骤迁移 DeepSeek 配置到声明式系统，与本 PR 同为覆盖迁移系列
• PR #30075 [refactor] Migrate the moe_runner_backend / quantization resolution chains (stack 13/15): 迁移 MoE 后端和量化链，与本 PR 共享覆盖注册机制
• PR #30074 [refactor] Migrate the page_size resolution chain (stack 12/15): 迁移 page_size 解析，为本 PR 的直接前序（stack 11/15 的上一级）