执行摘要

• 一句话：添加后处理解析阶段并迁移 sampling_backend 到声明式系统
• 推荐动作：值得精读，因为它引入了后处理解析阶段的核心模式——ResolvedView 只读视图和 run_post_process_pass 双应用函数。这是声明式配置解析 stack 的关键设计决策，后续字段迁移和基础设施扩展都基于此模式。建议重点关注 ResolvedView 的 __getattr__ 实现及 run_post_process_pass 如何处理过渡期的前后兼容。

功能与动机

PR body 明确指出「Normalization handlers become ordered declarative passes」。该 PR 是声明式配置解析栈（declarative config-resolution stack）的一部分，目标是将服务器启动时混杂的命令式配置规范化替换为声明式、可测试的 pass 管线，以实现最终状态下配置解析的完全声明化。

实现拆解

1. 添加 ResolvedView 与 pass 注册基础设施：在 overrides.py 中定义 ResolvedView（__slots__ = ("_server_args", "_overlay")），__getattr__ 优先返回 overlay 中的值，否则转发至 live server_args；__setattr__ 直接抛出 AttributeError 以强制执行 pass 只读契约。定义 POST_PROCESS_PASSES 列表、register_post_process 装饰器以及 run_post_process_pass 函数——该函数负责创建 ResolvedView(server_args)、调用 pass、将返回的声明追加至 server_args._resolved_overrides 并调用 apply_declarations_to_server_args 进行双应用。
2. 提取 sampling_backend 默认值逻辑为 pass _sampling_backend_default：该 pass 读取当前 sampling_backend 值（通过 view.sampling_backend），若为 None 则根据 is_flashinfer_available() 返回 {"sampling_backend": "flashinfer"} 或 "pytorch"。在 server_args.py 的 _handle_sampling_backend 中原有命令式写入被替换为 run_post_process_pass(self, _sampling_backend_default)。
3. 提取确定性推理的采样后端强制改为 pytorch 逻辑为 pass _deterministic_sampling_backend：该 pass 在非 ascend 平台强制写回 "pytorch" 并记录警告。在 server_args.py 的 _handle_deterministic_inference 中原有写入被替换为 run_post_process_pass(self, _deterministic_sampling_backend)。
4. 标记 sampling_backend 为 model_overridable 并添加 Flags 字段：在 server_args.py 中将 sampling_backend 字段的 Arg 添加 model_overridable=True；在 runtime_context.py 的 Flags 类中新增 sampling_backend: str | None = None，使该字段可被模型覆盖系统识别和发布。
5. 完善测试覆盖：在 test_model_overrides.py 中新增 TestResolvedViewAndPasses 测试类，覆盖 read-only 语义、overlay 优先、pass 追加 stash 与双应用、拒绝非 dict 返回值。更新白名单测试以包含 sampling_backend 字段。调整现有测试（如 test_mistral_large3_forces_bfloat16 和 test_control_arch_keeps_pristine_dtype）的断言方式，以兼容 _resolved_overrides 内可能存在多个条目的情况。

关键文件：

• python/sglang/srt/arg_groups/overrides.py（模块 参数覆盖；类别 source；类型 core-logic；符号 ResolvedView, init, getattr, setattr）: 核心变更文件，新增 ResolvedView 类、post-process pass 注册/执行机制、以及两个 sampling pass（_sampling_backend_default 和 _deterministic_sampling_backend），是整个后处理阶段的基础设施。
• test/registered/unit/test_model_overrides.py（模块 测试；类别 test；类型 test-coverage；符号 TestResolvedViewAndPasses, test_view_forwards_reads_and_rejects_writes, test_view_overlay_wins, test_run_pass_appends_stash_and_dual_applies）: 测试后处理阶段的核心行为：ResolvedView 读写语义、pass 调用与 stash 追加、拒绝非 dict 返回值，以及 sampling_backend pass 的集成行为。同时更新了 model_overridable_fields 白名单测试以包含 sampling_backend。
• python/sglang/srt/server_args.py（模块 服务器参数；类别 source；类型 core-logic；符号 sampling_backend, _handle_sampling_backend, _handle_deterministic_inference）: 将两个遗留的 sampling_backend 命令式处理器替换为 pass 调用，并标记 sampling_backend 字段为 model_overridable，使后续模型覆盖可影响该字段。
• python/sglang/srt/runtime_context.py（模块 运行上下文；类别 source；类型 data-contract；符号 Flags.sampling_backend）: 在 Flags 容器中添加 sampling_backend 字段，使解析后的值可被发布给读者。

关键符号：ResolvedView.init, ResolvedView.getattr, ResolvedView.setattr, register_post_process, run_post_process_pass, _sampling_backend_default, _deterministic_sampling_backend, ServerArgs._handle_sampling_backend, ServerArgs._handle_deterministic_inference

关键源码片段

python/sglang/srt/arg_groups/overrides.py

核心变更文件，新增 ResolvedView 类、post-process pass 注册/执行机制、以及两个 sampling pass（_sampling_backend_default 和 _deterministic_sampling_backend），是整个后处理阶段的基础设施。

def run_post_process_pass(server_args: Any, fn: Callable[..., dict]) -> None:
    """Transition-period invocation of one pass at its legacy handler slot.
​
    Evaluates the pass on the live state (through a read-only view), appends
    its declaration to the declaration stash, and dual-applies it in place —
    byte-identical to the imperative handler write this replaces.
    """
    # 创建只读视图：所有读取转发至当前 live server_args（含之前 pass 的双应用写入）
    declared = fn(ResolvedView(server_args))
    if not isinstance(declared, dict):
        raise TypeError(
            f"post-process pass {fn.__qualname__} must return a dict, "
            f"got {type(declared).__name__}"
        )
    if declared:
        entry = (fn.__qualname__, dict(declared))
        # 追加至 stash，供后续 audit 或端状态重放使用
        server_args._resolved_overrides.append(entry)
        # 双应用：直接在 live server_args 上执行写入，效果同旧命令式写法
        apply_declarations_to_server_args(server_args, [entry])
​
​
class ResolvedView:
    """Read-only view of the resolving configuration handed to post-process
    passes.
​
    During the dual-apply transition the view forwards every read to the live
    ``server_args`` — the pristine input plus the declarations replayed so far
    plus any residual imperative writes — which is exactly the state the
    legacy handler at the same slot observed.  In the end state (dual-apply
    retired) the same type overlays the accumulated declarations on the
    pristine object.  Writes are rejected: passes return declarations.
    """
​
    __slots__ = ("_server_args", "_overlay")
​
    def __init__(self, server_args: Any, overlay: Optional[Dict[str, Any]] = None):
        object.__setattr__(self, "_server_args", server_args)
        object.__setattr__(self, "_overlay", overlay or {})
​
    def __getattr__(self, name: str) -> Any:
        # overlay 优先：若该字段已被前序 pass 声明，直接返回 overlay 中的值
        overlay = object.__getattribute__(self, "_overlay")
        if name in overlay:
            return overlay[name]
        # 否则转发至 live server_args（它已包含双应用写入，与旧命令式行为一致）
        return getattr(object.__getattribute__(self, "_server_args"), name)
​
    def __setattr__(self, name: str, value: Any) -> None:
        # 禁止写入：pass 必须将声明作为 dict 返回，不能直接修改视图
        raise AttributeError(
            "ResolvedView is read-only; post-process passes return declarations"
        )

def _sampling_backend_default(view: ResolvedView) -> Dict[str, str]:
    """Default sampling backend: flashinfer if available, else pytorch."""
    # view 是只读的，此处只读取不写入
    current = view.sampling_backend
    if current is not None:
        # 用户已显式指定，无需默认值
        return {}
    backend = "flashinfer" if is_flashinfer_available() else "pytorch"
    return {"sampling_backend": backend}
​
​
def _deterministic_sampling_backend(view: ResolvedView) -> Dict[str, str]:
    """Force pytorch sampling backend for deterministic inference (unless ascend)."""
    # 在确定性推理模式下，除 ascend 平台外均强制使用 pytorch
    if view.sampling_backend == "ascend":
        # ascend 有自身确定性实现，不覆盖
        return {}
    logger.warning("Sampling backend is set to pytorch for deterministic inference.")
    return {"sampling_backend": "pytorch"}

test/registered/unit/test_model_overrides.py

测试后处理阶段的核心行为：ResolvedView 读写语义、pass 调用与 stash 追加、拒绝非 dict 返回值，以及 sampling_backend pass 的集成行为。同时更新了 model_overridable_fields 白名单测试以包含 sampling_backend。

class TestResolvedViewAndPasses(CustomTestCase):
    """Pipeline skeleton: read-only view semantics + transition invocation."""
​
    def test_view_forwards_reads_and_rejects_writes(self):
        from sglang.srt.arg_groups.overrides import ResolvedView
        live = SimpleNamespace(a=1, method=lambda: "m")
        view = ResolvedView(live)
        # 普通读取转发至 live
        self.assertEqual(view.a, 1)
        # 方法也转发（适用于 server_args 上的 get_model_config 等）
        self.assertEqual(view.method(), "m")
        # live 写入后，view 读取的是最新值（不是快照）
        live.a = 2
        self.assertEqual(view.a, 2)
        # 写入拒绝
        with self.assertRaises(AttributeError):
            view.a = 3
​
    def test_view_overlay_wins(self):
        from sglang.srt.arg_groups.overrides import ResolvedView
        view = ResolvedView(SimpleNamespace(a=1, b=2), overlay={"a": 10})
        self.assertEqual(view.a, 10) # overlay 优先
        self.assertEqual(view.b, 2) # 无 overlay 时转发
​
    def test_run_pass_appends_stash_and_dual_applies(self):
        from sglang.srt.arg_groups.overrides import run_post_process_pass
        live = SimpleNamespace(x=None, _resolved_overrides=[])
​
        def _fill_x(view):
            return {"x": "filled"} if view.x is None else {}
​
        run_post_process_pass(live, _fill_x)
        self.assertEqual(live.x, "filled") # 双应用生效
        self.assertEqual(
            live._resolved_overrides,
            [(_fill_x.__qualname__, {"x": "filled"})]
        )
        # 再次调用 pass，因条件不满足，stash 不新增条目
        run_post_process_pass(live, _fill_x)
        self.assertEqual(len(live._resolved_overrides), 1)
​
    def test_run_pass_rejects_non_dict(self):
        from sglang.srt.arg_groups.overrides import run_post_process_pass
        with self.assertRaises(TypeError):
            run_post_process_pass(
                SimpleNamespace(_resolved_overrides=[]),
                lambda view: None
            )

    def test_server_args_whitelist_is_exactly_the_migrated_fields(self):
        # ... 已有断言 ...
        self.assertEqual(
            model_overridable_fields(ServerArgs),
            frozenset({
                "dtype",
                "enable_tf32_matmul",
                "enable_multi_layer_eagle",
                "swa_full_tokens_ratio",
                "disable_hybrid_swa_memory",
                "sampling_backend", # 新增字段
            }),
        )

评论区精华

该 PR 无 review 评论。仅有一个 gemini-code-assist[bot] 的 Issue 评论提示配额已满，与 PR 内容无关。

• 暂无高价值评论线程

风险与影响

• 风险：
  • 回归风险：_handle_sampling_backend 和 _handle_deterministic_inference 的替换依赖 run_post_process_pass 正确创建 live view 并双应用。若 ResolvedView 的 __getattr__ 转发行为与原有逻辑存在偏差（如 overlay 未正确反映写入状态），可能导致默认值错误。测试覆盖了基础路径但未涵盖所有平台（如 ascend 的 sampling_backend 场景）。
  • 兼容性风险：原有代码直接对 self.sampling_backend 赋值，现在通过 stash 和双应用写入，最终值应一致。但若其他代码在 _handle_deterministic_inference 之后依赖 self.sampling_backend 未被覆盖，可能出现行为差异。
  • 双应用过渡期风险：当前部分字段仍保留命令式写入，run_post_process_pass 通过 live view 观察当前状态，理论上与原有顺序一致。但若后续 pass 的注册顺序与遗留调用顺序不匹配，可能导致 last-writer-wins 语义不一致。
  • 测试覆盖不足：缺少对 ascend 平台 _deterministic_sampling_backend 分支的测试。
  • 影响：对用户透明：sampling_backend 的默认值逻辑和确定性推理覆盖逻辑在行为上与之前完全一致。对系统的影响在于 sampling_backend 现在进入 model_overridable 白名单，可被模型声明式覆盖（后续 stack 会利用此能力）。对团队而言，这是声明式迁移的重要基础设施 PR，后续所有字段的后处理逻辑可沿用相同模式。
  • 风险标记：核心路径变更, 缺少跨平台测试覆盖, 双应用过渡期风险

关联脉络

• PR #30073 [refactor] Migrate the attention_backend resolution chain (stack 11/15): 同一 stack 中的后续 PR，迁移 attention_backend 到声明式系统，同样使用 post-process pass 模式。
• PR #30074 [refactor] Migrate the page_size resolution chain (stack 12/15): 同一 stack 中的后续 PR，迁移 page_size 解析。
• PR #30075 [refactor] Migrate the moe_runner_backend / quantization resolution chains (stack 13/15): 同一 stack 中的后续 PR，迁移 MoE 和量化配置。
• PR #30076 [refactor] Migrate the DeepSeek family and the parallel-request chains (stack 14/15): 同一 stack 中的后续 PR，迁移 DeepSeek 模型覆盖和并行请求链。
• PR #30077 [refactor] Rename Arg.model_overridable to Arg.resolvable (stack 15/15): 同一 stack 的最后一步，重命名属性以统一概念。