执行摘要

• 一句话：移动模型能力调整到解析管道，添加变异守门
• 推荐动作：值得精读，特别是 ServerArgs.override 的设计和棘齿测试的实现。该 PR 展示了如何通过渐进式重构加固内部契约，为大型项目配置管理提供了可参考的模式。

功能与动机

PR body 指出：“hardens its developer contract ('after post_init, server_args is the resolved configuration') on the write side: configuration is resolved in the pipeline, not by scattered assignments.” 消除分散的字段赋值，确保配置解析一致性。

实现拆解

1. 迁移模型能力调整：在 server_args.py 中添加 _handle_model_capability_adjustments 作为 __post_init__ 的最后一个处理器（在 materialize_declarations 之前），将原 ModelRunner.model_specific_adjustment 中的 HRM-Text 前缀语言模型强制和多模态块预填充禁用逻辑移入。同时删除 overrides.py 中不再使用的 refresh_declared_fields。

2. 引入唯一变异入口：在 server_args.py 中实现 ServerArgs.override(source, **fields)，写入时通过 _apply_fields（设置 _in_override 标志）绕过严格赋值守卫；白名单中的可解析字段同时加入声明存储，确保发布后解析一致。declare_load_time_override 和 run_post_process_pass 改为调用 _apply_fields。

3. 添加变异棘齿测试：新增 test_server_args_mutation_ratchet.py，通过精确的正则表达式匹配全仓库源码，检查所有非管道代码对 server_args 字段的 = 赋值，基线为零（零容忍）。新代码必须通过 override 或管道通道声明。

4. 修复关联缺陷：修复解析门控中四个被 Codex 发现的问题：HRM-Text 直接设置 cuda_graph_config 相位后端为 Backend.DISABLED 而非仅设置布尔值；恢复 add_chunked_prefix_cache_attention_backend 的 model_runner 重新导出；将块前缀缓存门控移回 ModelRunner.__init__ 加载时（因 OOT 平台注册在后）；为草案工作者添加 is_draft_worker 保护，防止非 MLA 草案模型错误禁用共享的 disable_chunked_prefix_cache。

5. 全仓库迁移：将 scheduler.py、eagle_worker_v2.py、tokenizer_control_mixin.py 等文件中的散乱赋值改为通过 override() 写入，并更新测试中的 fake server_args 工厂以支持 override。

关键文件：

• python/sglang/srt/server_args.py（模块 配置解析；类别 source；类型 dependency-wiring；符号 add_chunked_prefix_cache_attention_backend, _handle_model_capability_adjustments, _set_default_dsa_backends, override）: 核心配置解析文件，新增 _handle_model_capability_adjustments、override、__setattr__ 守卫，并引入 CHUNKED_PREFIX_CACHE_SUPPORTED_ATTENTION_BACKENDS 列表和注册函数。
• python/sglang/srt/model_executor/model_runner.py（模块 模型运行器；类别 source；类型 data-contract；符号 add_chunked_prefix_cache_attention_backend, model_specific_adjustment）: 原模型能力调整的所在位置，本次移除 model_specific_adjustment 方法，并调整 chunked prefix cache 门控逻辑为加载时执行。同时重新导出 add_chunked_prefix_cache_attention_backend。
• python/sglang/srt/arg_groups/overrides.py（模块 覆盖管理；类别 source；类型 core-logic；符号 _apply_fields, refresh_declared_fields, _hrm_text_attention_force）: 包含管道声明核心逻辑，新增 _apply_fields 辅助函数，删除 refresh_declared_fields，新增 _hrm_text_attention_force 声明函数。
• test/registered/unit/test_server_args_mutation_ratchet.py（模块 测试；类别 test；类型 test-coverage；符号 TestServerArgsMutationRatchet, test_out_of_pipeline_mutations_match_the_baseline）: 新增的突变棘齿测试，通过正则扫描全仓库禁止管道外字段赋值，基线为零。
• python/sglang/srt/managers/scheduler.py（模块 调度器；类别 source；类型 core-logic）: 将多个散乱赋值改为通过 override() 写入，包括 draft load format、pp_max_micro_batch_size、hicache 相关字段等。
• python/sglang/srt/speculative/eagle_worker_v2.py（模块 推测解码；类别 source；类型 core-logic）: 将 speculative 状态同步中的散乱赋值改为 override()，包括 hot token map、context length、adaptive spec 参数等。

关键符号：add_chunked_prefix_cache_attention_backend, _handle_model_capability_adjustments, ServerArgs.override, _apply_fields, _hrm_text_attention_force, run_post_process_pass, TestServerArgsMutationRatchet.test_out_of_pipeline_mutations_match_the_baseline

关键源码片段

python/sglang/srt/server_args.py

核心配置解析文件，新增 _handle_model_capability_adjustments、override、__setattr__ 守卫，并引入 CHUNKED_PREFIX_CACHE_SUPPORTED_ATTENTION_BACKENDS 列表和注册函数。

# python/sglang/srt/server_args.py
# 解析管道的最后一个处理步骤：模型能力调整
# 在 materialize_declarations 之前执行，确保所有模型相关覆盖在最终发布前声明
​
def _handle_model_capability_adjustments(self):
    # 忽略 Remote Instance 连接器类型，不调整
    if parse_connector_type(self.model_path) == ConnectorType.INSTANCE:
        return
​
    from sglang.srt.arg_groups.overrides import (
        _hrm_text_attention_force,
        run_post_process_pass,
    )
​
    model_config = self.get_model_config()
    hf_config = model_config.hf_config
​
    # HRM-Text 需要双向前缀注意力，只有 Triton 后端支持
    # 且 Radix 缓存不安全，因此强制这些设置
    is_hrm_text = (
        getattr(hf_config, "model_type", None) == "hrm_text"
        or "HrmTextForCausalLM" in getattr(hf_config, "architectures", [])
    )
    if is_hrm_text and getattr(hf_config, "prefix_lm", True):
        # 通过管道声明覆盖 attention_backend 为 triton
        run_post_process_pass(self, _hrm_text_attention_force)
        # 禁用分块预填充、Radix 缓存、CUDA 图
        self.chunked_prefill_size = -1
        self.disable_radix_cache = True
        self.disable_cuda_graph = True
        # 重要：cuda_graph_config 已从布尔值解析，直接设置相位后端为 DISABLED
        # 避免图捕获仍然使用已解析的 backend
        self.cuda_graph_config.decode.backend = Backend.DISABLED
        self.cuda_graph_config.prefill.backend = Backend.DISABLED
        logger.info(
            "HRM-Text: forced attention_backend=triton, "
            "disabled chunked prefill, radix cache, and CUDA graph"
        )

python/sglang/srt/model_executor/model_runner.py

原模型能力调整的所在位置，本次移除 model_specific_adjustment 方法，并调整 chunked prefix cache 门控逻辑为加载时执行。同时重新导出 add_chunked_prefix_cache_attention_backend。

# python/sglang/srt/model_executor/model_runner.py
# 在 ModelRunner.__init__ 中加载时执行的块前缀缓存门控
# （必须在 out-of-tree 平台 init_backend 之后）
​
# （位于 __init__ 方法中，时间测量启用后，全局 server_args 设置前）
# Chunked prefix caching 需要 MLA 模型且后端在支持列表中。
# 这是加载时门控，不是解析时：OOT 平台在 init_backend() 中注册支持后端，
# 该操作在此模块导入时发生 —— 在 ServerArgs.__post_init__ 之后。
# 仅针对目标工作者：草案模型的（通常非 MLA）配置不能翻转共享设置。
if not self.is_draft_worker and (
    not self.use_mla_backend
    or server_args.attention_backend
    not in CHUNKED_PREFIX_CACHE_SUPPORTED_ATTENTION_BACKENDS
):
    if not server_args.disable_chunked_prefix_cache:
        server_args.override(
            "model_runner.chunked_prefix_cache_gate",
            disable_chunked_prefix_cache=True,
        )
if not self.is_draft_worker and not server_args.disable_chunked_prefix_cache:
    logger.info("Chunked prefix cache is turned on.")

python/sglang/srt/arg_groups/overrides.py

包含管道声明核心逻辑，新增 _apply_fields 辅助函数，删除 refresh_declared_fields，新增 _hrm_text_attention_force 声明函数。

# python/sglang/srt/arg_groups/overrides.py
# _apply_fields: 在管道上下文中写入字段，绕过严格守卫
​
def _apply_fields(server_args: Any, fields: Dict[str, Any]) -> None:
    """代表管道写入字段（绕过保护后解析变异的严格赋值守卫）。"""
    # 设置 _in_override 标志，告诉 __setattr__ 这是管道写入
    object.__setattr__(server_args, "_in_override", True)
    try:
        for field, value in fields.items():
            setattr(server_args, field, value)
    finally:
        object.__setattr__(server_args, "_in_override", False)
​
​
# _hrm_text_attention_force: HRM-Text 的双向前缀注意力仅在 Triton 后端工作
# 作为解析的最后一个注意力声明调用（反映原有加载时强制顺序）
def _hrm_text_attention_force(view: Any) -> dict:
    if view.attention_backend not in (None, "triton"):
        logger.warning(
            f"Overriding --attention-backend "
            f"{view.attention_backend!r} -> 'triton': only the "
            "Triton backend supports HRM-Text's bidirectional prefix "
            "attention."
        )
    return {"attention_backend": "triton"}

评论区精华

Codex 机器人发现四个 P2 级别问题，均由作者 ch-wan 回复并修复：

• HRM-Text 的 disable_cuda_graph 布尔值设置无效，因为 cuda_graph_config 已从该布尔值解析完毕；作者改为直接设置相位后端为 Backend.DISABLED。
• add_chunked_prefix_cache_attention_backend 钩子丢失了从 model_runner 的重新导出，导致 OOT 平台导入失败；作者添加了 re-export。
• 块前缀缓存门控在 __post_init__ 中计算时，OOT 平台的 init_backend() 尚未运行（发生在 model_runner 导入时），导致门控错判；作者将门控移回 ModelRunner.__init__ 加载时，通过 override 写入。

• 草案工作者缺少 is_draft_worker 检查，非 MLA 草案会错误禁用共享的缓存；作者恢复该守卫。

• HRM-Text 强制关闭 CUDA 图捕获的遗留缺陷 (correctness): 作者 ch-wan 修复：在 HRM-Text 分支中直接设置 cuda_graph_config.decode.backend 和 prefill.backend 为 Backend.DISABLED，布尔值翻转保留用于其他工作者。

• 丢失 add_chunked_prefix_cache_attention_backend 的重新导出 (correctness): 作者 ch-wan 修复：在 model_runner.py 的 from sglang.srt.server_args import ... 中添加 add_chunked_prefix_cache_attention_backend 和 CHUNKED_PREFIX_CACHE_SUPPORTED_ATTENTION_BACKENDS 的重新导出。
• 分辨率门控先于 OOT 后端注册执行 (design): 作者 ch-wan 修复：将门控移回 ModelRunner.__init__ 加载时，通过 override("model_runner.chunked_prefix_cache_gate", ...) 写入，恢复原始时序。
• 草案工作者误触发块前缀缓存门控 (correctness): 作者 ch-wan 修复：在 ModelRunner.__init__ 的门控中添加 not self.is_draft_worker 检查，恢复原始守卫。

风险与影响

• 风险：

  1. 回归风险：虽然大部分赋值已改为 override，但可能有遗漏的赋值未被测试覆盖，尤其是一些条件分支中的赋值。棘齿测试仅检查正则匹配，可能漏掉动态生成的赋值或通过 setattr 的赋值。
  2. OOT 平台兼容性：门控逻辑的时序变化可能影响 OOT 平台的初始化顺序，需要 OOT 维护者更新。
  3. 测试覆盖：棘齿测试基线为零，但未排除某些合法赋值情境（如 mock 测试）。另外，未运行 SGLANG_STRICT_CONFIG_MUTATION=1 的严格模式测试。
  4. 性能：新增的字符串正则扫描在 CI 中可能增加少量时间，但影响可忽略。
     - 影响：对开发者：新代码必须通过 override 或管道声明来修改 server_args 字段，直接赋值将在严格模式下报错。学习成本中等。
     对系统：配置解析更严格，减少因散乱赋值导致的不一致问题。功能上无变化。
     对用户：无直接影响。
     对团队：强制了更好的配置管理实践，便于后续维护和审计。

• 风险标记：核心路径变更, 外部赋值点可能遗漏, OOT 平台兼容性风险, 测试覆盖依赖正则

关联脉络

• PR #30297 [refactor] ctx.resources: named slots, stream leases, and workspace buffer leases: 该 PR 直接栈式依赖在此 PR 之前，为其提供基础设施。此 PR 强化其‘post_init 后 server_args 已解析’的契约。
• PR #30346 [refactor] Read resolved config from server_args fields; retire the flags mirror tier: 同系列重构，退役 flags 镜像层，统一读取 server_args，与该 PR 的配置解析管道设计互补。
• PR #30347 [refactor] Collect MoE and DP-attention runtime state into typed flag groups: 同系列重构，收集运行时状态到类型化标志组，与该 PR 的配置管道强化一致。