[Config] Round 6.1: "unset" gets its own spelling, and the declaration says what it means (#38046)

First of five. The stack continues a series that moved configuration out of `ServerArgs` and into the runtime context's namespace bags. This one fixes something that was actually broken, and gives the fix its other half. ## "Unset" gets its own spelling on two ratio fields `swa_full_tokens_ratio` and `mamba_full_memory_ratio` carried real values as their class defaults (0.8, 0.9), so a model family with an opinion had to ask "is this field still equal to the class default?" to find out whether the operator had set it. That question has two wrong answers: it says "the operator set it" as soon as any earlier pass declares the field, and it says "the operator did not set it" when the operator types the default value. Both become `Optional[float] = None`. The record carries what the operator typed and nothing else, and the family test becomes `is None`. `mamba_radix_cache_strategy` keeps `"auto"`: unlike the ratios it already has a spelling for "unset" that an operator can type and that means exactly that -- only its comparison changes, from the class default to the token itself, which is the fix the comment at that site already prescribed. With that, neither family module imports `ServerArgs` any more. ## And the declaration says what the field means when nobody answers Making the default `None` leaves a hole: something has to supply the generic value. `Arg(fallback=...)` supplies it from the declaration. ```python swa_full_tokens_ratio: A[ Optional[float], Arg(help="...", resolvable=True, fallback=0.8), NS("schedule"), ] = None ``` The dataclass default stays `None`. A fallback is not a default: the record is the wire format, and a child process has to keep being able to tell "unset" from "set to the value resolution would have picked anyway". ### Which surface it lives on is the whole design Precedence becomes **override -> decision -> input -> fallback**, applied in `resolution_result` -- which the projection, `/server_info` and every config bag read through. Deliberately **not** in `resolving_view` / `resolved_view`. Those are the decision-over-input surface a pass reads *while it is deciding*, and two model families branch on exactly this: ```python # model_overrides/inkling.py, and the same shape in deepseek_v4.py if cfg.swa_full_tokens_ratio is None: overrides["swa_full_tokens_ratio"] = 0.1 ``` A fallback answering there is not "the generic value, later" -- a `__getattr__` layer is read-time, so there is no later. Every read during resolution would already get 0.8 and the branch would never fire. Running `_inkling_overrides` against both versions: ``` --- fallback on the effective surface only (this PR) --- cfg.swa_full_tokens_ratio during resolution = None family declared swa = 0.1 mamba = 0.1 --- fallback also on the view a pass reads --- cfg.swa_full_tokens_ratio during resolution = 0.8 family declared swa = None mamba = None <- the key never lands ``` So "resolution first, then the fallback" holds -- not because a step is appended to the pipeline, but because of which surface the value lives on. Exactly one reader consults the effective surface during resolution: the range check on the ratio, which wants the value the pools will be sized against. It asks `resolution_result` directly -- what its comment already claimed it was doing -- and it runs after the model families. ### The alternative, and why not A pass that fills the field in when nothing claimed it needs a slot (after the families, or it beats them), a second call site (the dummy-model short circuit returns long before that slot), an idempotence requirement so the second call is harmless, and the value written twice -- once as a literal, once as prose in the help (`"Unset means 0.8"`). An earlier revision of this series did exactly that and deleted it four PRs later. A declaration needs none of it, and `pipeline.py` is untouched by the whole series as a result. ### What may be declared this way, and what may not Across every hook, `if x is None: x = ...` appears at **55 sites over 29 fields**. They are not one thing: | | count | examples | declarable | |---|---|---|---| | unconditional constant | 5 | the two ratios, `grammar_backend="xgrammar"`, `mm_process_config={}`, `custom_weight_loader=[]` | **yes** | | unconditional, computed from another field | 4 | `tokenizer_path=model_path`, `device=get_device()`, `served_model_name`, `speculative_draft_model_quantization` | needs a `fallback="dotted.path"` form; not here | | **conditional decision** | ~20 | `chunked_prefill_size` across seven memory tiers, `max_bs` across eight, `max_running_requests` at 48 or 256 by model family | **no, and it should not be** | Only a value fixed for the life of the configuration belongs in a declaration. One that depends on the machine, on another field, or on anything impure (`random_seed = random.randint(...)`) is a decision, and decisions stay in a hook where their order is visible. This PR converts the two ratios only. ## Verification - `resolve_once` ends with the same effective values: the resolution result is identical across 24 launch shapes x 489 fields except for the two intended ratio changes. Separately, 16 launch shapes resolved on both sides, real model and dummy: 7,904 field readings, and the only difference is `random_seed`, a fresh `random.randint` per process. - The CLI registers the same 507 options with the same choices and actions; only the two defaults move. - `test_declared_fallbacks.py`, 17 cases. One pins the inverse of the dead branch above: what a pass sees while deciding is still `None`. - The whole series was swept over all 648 registered unit-test files against its merge-base: 19 failures on both sides, the same 19, none of them config. --- ### CI States Latest PR Test (Base): ❌ [Run #34083705463](https://github.com/sgl-project/sglang/actions/runs/34083705463) Latest PR Test (Extra): ❌ [Run #34083705284](https://github.com/sgl-project/sglang/actions/runs/34083705284) Latest PR Test (AMD ROCm 7.2): ❌ [Run #34083705383](https://github.com/sgl-project/sglang/actions/runs/34083705383)
2026-09-06 21:38:29 -07:00
parent df2f34cca1
commit 45c24444b1
8 changed files with 374 additions and 22 deletions
@@ -39,6 +39,7 @@ annotation is equivalent to ``Arg(help=that_string)``.

 from __future__ import annotations

+import copy
 import dataclasses
 import functools
 import types
@@ -58,6 +59,20 @@ from typing import (
 A = Annotated


+class _NoFallback:
+    """Sentinel for ``Arg.fallback``: this field declares none.
+
+    ``None`` cannot serve, because ``None`` is what a field *holds* when the
+    operator did not type it -- the state a fallback answers for.
+    """
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return "<no fallback>"
+
+
+NO_FALLBACK = _NoFallback()
+
+
@dataclasses.dataclass(frozen=True)
 class Arg:
    """CLI argument metadata attached to a dataclass field via ``Annotated``."""
@@ -80,6 +95,14 @@ class Arg:
    # `resolution_result` and the config bags answer with the decision. The
    # field keeps what the operator passed.
    resolvable: bool = False
+    # What the field means when nobody said anything -- the bottom of the read
+    # chain: override, decision, input, then this. Not the dataclass default,
+    # which stays `None` because that is how the record spells "not typed".
+    #
+    # Only a value fixed for the life of the configuration belongs here. One
+    # that depends on the machine, on another field, or on anything impure is a
+    # decision, and decisions stay in a hook where their order is visible.
+    fallback: Any = NO_FALLBACK


@dataclasses.dataclass(frozen=True)
@@ -145,6 +168,47 @@ def resolvable_fields(cls) -> frozenset:
    return frozenset(names)


+@functools.cache
+def fallbacks_of(cls) -> dict:
+    """``{field_name: value}`` for every field of ``cls`` that declares one.
+
+    Read the same way `resolvable_fields` reads its flag, so a fallback lives
+    beside the help text of the field it belongs to rather than in whatever
+    hook used to fill it in.
+    """
+    if not dataclasses.is_dataclass(cls):
+        return {}
+    hints = get_type_hints(cls, include_extras=True)
+    out = {}
+    for field in dataclasses.fields(cls):
+        _, arg = _unwrap_annotated(hints.get(field.name, field.type))
+        if arg is not None and arg.fallback is not NO_FALLBACK:
+            out[field.name] = arg.fallback
+    return out
+
+
+def with_fallback(cls, name: str, value: Any) -> Any:
+    """``value``, or the declared fallback when nothing has answered.
+
+    `resolution_result` calls this as its last step -- the effective surface,
+    which the config bags and `/server_info` read through. Deliberately not the
+    views a pass reads *while deciding*: `model_overrides/inkling.py` branches
+    on `if cfg.swa_full_tokens_ratio is None`, and a fallback answering there
+    would make that branch dead. `test_declared_fallbacks.py` pins both halves.
+
+    A container fallback is copied, for the reason a dataclass spells this
+    `default_factory`.
+    """
+    if value is not None:
+        return value
+    fallback = fallbacks_of(cls).get(name, NO_FALLBACK)
+    if fallback is NO_FALLBACK:
+        return value
+    if isinstance(fallback, (list, dict, set)):
+        return copy.deepcopy(fallback)
+    return fallback
+
+
 # ---------------------------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------------------------
@@ -10,6 +10,7 @@ from sglang.srt.arg_groups.overrides import (
    attention_backends_of,
    declare_resolution,
    model_config_of,
+    resolution_result,
    resolved_view,
    resolving_view,
    use_mla_backend,
@@ -189,7 +190,9 @@ def handle_cache_compatibility(server_args: Any) -> None:
    # Validate the effective ratio: model branches may declare a reset
    # (e.g. Step3p forces 1.0 under hierarchical cache) that supersedes
    # the user input before it ever takes effect.
-    if not (0 < resolved_view(server_args).swa_full_tokens_ratio <= 1.0):
+    # `resolution_result`, not a view: a view answers `None` while nobody has
+    # claimed the field, and the value to range-check is the effective one.
+    if not (0 < resolution_result(server_args, "swa_full_tokens_ratio") <= 1.0):
        raise ValueError("--swa-full-tokens-ratio should be in range (0, 1.0].")


@@ -24,7 +24,6 @@ def _deepseek_v4_overrides(server_args: Any, hf_config: Any) -> dict:
    writes, the max_running_requests fill and the validations stay in the
    hook at its legacy slot."""
    cfg = resolving_view(server_args)
-    from sglang.srt.server_args import ServerArgs

    model_arch = hf_config.architectures[0]
    overrides: Dict[str, Any] = {"attention_backend": "dsv4"}
@@ -44,7 +43,7 @@ def _deepseek_v4_overrides(server_args: Any, hf_config: Any) -> dict:
        f"Use dsv4 attention backend for {model_arch}, setting page_size to {page_size}."
    )

-    if cfg.swa_full_tokens_ratio == ServerArgs.swa_full_tokens_ratio:
+    if cfg.swa_full_tokens_ratio is None:
        overrides["swa_full_tokens_ratio"] = 0.1
        logger.info(f"Setting swa_full_tokens_ratio to 0.1 for {model_arch}.")

@@ -27,14 +27,14 @@ def _inkling_overrides(server_args: Any, hf_config: Any) -> dict:
    tree (which Inkling requires — models/inkling.py asserts it). The full-graph
    prefill default is set separately (inline, before cuda-graph resolution) —
    see ServerArgs.__post_init__ / _apply_inkling_prefill_cuda_graph_default. The
-    server-arg defaults each yield to an explicit user value (compared against
-    the ServerArgs class default); the prefill declaration is materialized
+    server-arg defaults each yield to an explicit user value (the ratios read
+    `None`, the mamba strategy its "auto" token); the prefill declaration is
+    materialized
    before _parse_cuda_graph_config folds cuda_graph_backend_prefill into
    prefill.backend, and an explicit --cuda-graph-backend-prefill /
    --disable-prefill-cuda-graph still wins. The unified-radix env write follows
    the MiniMax-M3 handler precedent (env is not a resolvable server-arg)."""
    cfg = resolving_view(server_args)
-    from sglang.srt.server_args import ServerArgs

    overrides: Dict[str, Any] = {}
    # NOTE: the full-graph prefill default is NOT set here. cuda-graph config is
@@ -42,21 +42,21 @@ def _inkling_overrides(server_args: Any, hf_config: Any) -> dict:
    # cuda_graph_backend_prefill declared here lands too late (the breakable
    # default would already have been auto-disabled for this multimodal arch).
    # It is set inline before _handle_cuda_graph_config instead.
-    if cfg.swa_full_tokens_ratio == ServerArgs.swa_full_tokens_ratio:
+    if cfg.swa_full_tokens_ratio is None:
        overrides["swa_full_tokens_ratio"] = 0.1
-    if cfg.mamba_full_memory_ratio == ServerArgs.mamba_full_memory_ratio:
+    if cfg.mamba_full_memory_ratio is None:
        overrides["mamba_full_memory_ratio"] = 0.1
    # Inkling requires the extra-buffer mamba strategy (inkling.py asserts
    # enable_mamba_extra_buffer()); the generic "auto" resolution does not cover
    # Inkling, so pin it here. Yields to an explicit --mamba-scheduler-strategy.
    #
-    # The default comparison answers "unset" only while nothing has declared the
-    # field first. `_mamba_radix_cache_resolution` would, from the slot just
-    # above `collect_model_override_declarations`, for an architecture whose
+    # Compared against the unresolved token rather than the class default: the
+    # default only answers "unset" while nothing has declared the field first,
+    # and `_mamba_radix_cache_resolution` would -- from the slot just above
+    # `collect_model_override_declarations` -- for an architecture whose
    # linear-attention spec sets `uses_mamba_radix_cache`. Inkling has no such
-    # spec; giving it one silently stops this pin from firing, so compare
-    # against the unresolved token ("auto") if that day comes.
-    if cfg.mamba_radix_cache_strategy == ServerArgs.mamba_radix_cache_strategy:
+    # spec today, but giving it one would silently stop this pin from firing.
+    if cfg.mamba_radix_cache_strategy == "auto":
        overrides["mamba_radix_cache_strategy"] = "extra_buffer"
    # Inkling attention runs only on the fa4 (Blackwell) or triton backends --
    # models/inkling_common/attn.py asserts attention_backend in {fa4, triton}.
@@ -41,7 +41,11 @@ import math
 from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple

 from sglang.srt.arg_groups import model_override_base
-from sglang.srt.arg_groups.arg_utils import field_names, resolvable_fields
+from sglang.srt.arg_groups.arg_utils import (
+    field_names,
+    resolvable_fields,
+    with_fallback,
+)

 # Re-exported for the callers that already import these names from here; the
 # declarations under ``model_overrides/`` import them from the base directly.
@@ -268,7 +272,13 @@ def declare_direct_writes(

 def resolution_result(server_args: Any, field: str, default: Any = None) -> Any:
    """What resolution decided for ``field``: the declaration if there is one,
-    otherwise what the caller supplied.
+    otherwise what the caller supplied, otherwise the field's declared
+    fallback.
+
+    The fallback is last because it is what the field means when nobody said
+    anything -- an operator who types a value and a pass that decides one both
+    sit above it. It is read from the declaration rather than filled in by a
+    pass, so there is no slot to place and no second call to make idempotent.

    This is what the config projection reads. Reading the field instead would
    work whatever the caller passed onto the record -- and
@@ -283,8 +293,8 @@ def resolution_result(server_args: Any, field: str, default: Any = None) -> Any:
            return declared[field]
    raw = getattr(server_args, "_raw_input", None)
    if raw is not None and field in raw:
-        return raw[field]
-    return getattr(server_args, field, default)
+        return with_fallback(type(server_args), field, raw[field])
+    return with_fallback(type(server_args), field, getattr(server_args, field, default))


 def resolution_projection(server_args: Any) -> Dict[str, Any]:
@@ -815,7 +815,7 @@ class ServerArgs:
        NS("schedule"),
    ] = 16
    swa_full_tokens_ratio: A[
-        float,
+        Optional[float],
        Arg(
            help=(
                "The ratio of SWA layer KV tokens / full layer KV tokens, regardless "
@@ -824,9 +824,10 @@ class ServerArgs:
                "layer has 100 tokens."
            ),
            resolvable=True,
+            fallback=0.8,
        ),
        NS("schedule"),
-    ] = 0.8
+    ] = None
    disable_hybrid_swa_memory: A[
        bool,
        Arg(help="Disable the hybrid SWA memory pool.", resolvable=True),
@@ -2642,13 +2643,14 @@ class ServerArgs:
        NS("exec.mamba"),
    ] = 0
    mamba_full_memory_ratio: A[
-        float,
+        Optional[float],
        Arg(
            help="The ratio of mamba state memory to full kv cache memory.",
            resolvable=True,
+            fallback=0.9,
        ),
        NS("schedule"),
-    ] = 0.9
+    ] = None
    mamba_radix_cache_strategy: A[
        str,
        Arg(