minke.yu/sglang
1
0
Fork 0
Code Issues Pull Requests Actions 13 Packages Projects Releases Wiki Activity

[Config] Round 6.5: a namespace declares what it derives, next to what it derives it from (#38113)

Browse Source 
Fifth of five; stacked on #38049. The split gave every namespace a file, but
only for the half an operator types. This is the other half.

## The parallel quotients are declared, not written out

`attn_tp_size` and its five siblings were sixty lines of near-identical
properties in the runtime context, a file away from the leaves they are
quotients of, so reading `parallel.py` told you what you could set and nothing
about what that decides.

They are declared in `Parallel` now, in the same class as those leaves. They
carry no annotation, so they are not dataclass fields and
`collect_input_fields` never puts them on the record -- the same mechanism that
already keeps `_NS_PATH` off it. That is the right exclusion: a quotient has no
operator input to preserve, and the record is what crosses a process boundary,
where a stamped width is one an elastic scale-up will not refresh.

## A quotient is a value in the bag, like every other derived one

`_derived_width` answered from a stamp or, failing that, a live process group.
The group read could never disagree with the stamp:

- `initialize_model_parallel` stamps all six as its last statement,
  unconditionally;
- an elastic scale-up restamps `attn_dp_size` through
  `update_dp_attention_post_scale` -- the comment claiming it does *not* was
  wrong;
- no hardware backend builds groups of its own;
- `multimodal_gen`, which has its own `initialize_model_parallel` and does not
  stamp, never reads a quotient.

So a built group was always already stamped, and the group read goes -- and with
it the last reason for a quotient to be resolved on every read.

Every input to `derive_parallel_widths` is a record field. `dcp_enabled` is
`decode_context_parallel_size > 1`, not a fact about a built group; it was
spelled `_DCP is not None`, which is a longer way to say the same thing. So the
six are fixed once the configuration is fixed -- the same test every other
`Derived(fn=...)` in this PR passes. They are declared the same way and computed
the same way: once, at publish, into ordinary bag leaves.

What remains is override -> stamp -> published leaf. The stamp stays above the
leaf because an elastic scale-up restamps `attn_dp_size`; the override stays on
top because that is how a test names a width.

## One answer for the config-derived predicates

`enable_mamba_extra_buffer` and its lazy variant, `is_ep_joiner`,
`is_ep_scale_joiner`, `is_startup_weight_load_overlap`: each existed as a
`ServerArgs` member for the resolution pipeline and, for most of them, again as
a `runtime_context` function for readers after publish. Three places to keep
saying the same thing.

A `Derived(fn=...)` is a pure function of the published configuration, so
`publish` computes it once and stores it as an ordinary bag leaf -- a plain
attribute load, which is what a read inside compiled model code needs. The
function is handed the whole resolved config rather than the bag it lands in,
because a derivation is free to span namespaces and the mamba one does: it
reads `memory.disable_radix_cache` alongside its own `exec.mamba` strategy,
which is why it could never have been a method on either bag.

The pre-publish helpers stay -- resolution needs the predicate before there is
a bag to read -- and three readers keep them, because they run before their own
process publishes: `initialize_dp_attention`, which the weight-cache daemon
calls while building its groups thirty lines before its `publish`, and
`PortArgs.init_new`, a factory handed the record that already reads eighteen
other fields off it.

## Notes for a reviewer

**Overriding a leaf does not move its quotient.** `override(tp_size=2)` leaves
`attn_tp_size` where the published config put it, because nothing is recomputed
on read. A test states a topology by publishing a config -- which is what a
real process does -- or by naming the width it wants, `override(attn_tp_size=2)`.
Six tests say it that way now. This is the price of having one answer computed
once, and it is the same price every other derived value in the config already
carries.

A caller that reads a quotient without publishing or overriding now gets an
explicit error naming the field, instead of a default that an uninitialised
group happened to supply. One fixture was in that state --
`TestMlaWriteDoorsUnderDcp` built a bare pool and asked whether DCP was on --
and it publishes a config now, which is what the process it stands in for
does.

Eighteen sites read these predicates without calling them. That is correct --
they are properties -- but it is worth saying they were checked, because a
census that assumes otherwise reports eighteen always-true conditions.

## The skill that documents this subsystem is updated with it

`.claude/rules/modify-component-must-read.md` points at
`.claude/skills/sglang-runtime-context/SKILL.md` before anyone touches these
files, so a stale sentence there is a wrong instruction rather than a stale
note. Four of its load-bearing statements stopped being true across this series
and are corrected here: `NS(...)` is no longer how a field states its namespace
(the declaring class is); the DCP degrade rule is gone, because the quotients
are not live reads; `mamba_extra_buffer_enabled()` and the other predicate
functions it named as the shape to copy no longer exist; and the
namespace-coverage ratchet is described in terms of the marker. The docstring of
`test_server_args_namespaces.py` said the same thing and is fixed too.

The consequence a test author actually trips over is stated there as well:
overriding a leaf no longer moves its quotient, so a topology is stated by
publishing a config or by naming the width.

## Verification

A full registered-unit sweep (648 files) against this stack's merge-base:
19 failures on both sides, the same 19 -- AMD `gfx950`, `modelopt`,
`cuda_vmm`, `weight_checker` and friends, none of them config. The narrower 139-file config sweep used earlier in this series
does not contain the files this change reaches -- `test_kv_index_translator`
never names `get_parallel()`, it constructs an object that does -- which is why
the baseline differential over everything is what is quoted here.
This commit is contained in:
Cheng Wan
2026-09-06 21:44:24 -07:00
committed by GitHub
parent b99175dc7d
commit aaf9a95763
56 changed files with 1118 additions and 379 deletions
Download Patch File Download Diff File Expand all files Collapse all files
python/sglang/srt/runtime_context.py
+146 -94
View File
@@ -182,6 +182,62 @@ def derive_parallel_widths(
}
def parallel_widths_of(cfg: Any) -> dict:
"""The six quotients, from a resolved config.
Every input is a record field, so this is a function of the configuration
and nothing else -- which is why the six are declared `Derived(fn=...)` and
computed once at publish rather than on every read. `dcp_enabled` is
`dcp_size > 1` because that is exactly when `initialize_model_parallel`
builds the group.
"""
attn_dp_size, _ = derive_attention_widths(
tp_size=cfg.tp_size,
attn_cp_size=cfg.attn_cp_size,
dp_size=cfg.dp_size,
enable_dp_attention=cfg.enable_dp_attention,
)
return derive_parallel_widths(
tp_size=cfg.tp_size,
attn_cp_size=cfg.attn_cp_size,
attn_dp_size=attn_dp_size,
moe_ep_size=cfg.ep_size,
moe_dp_size=cfg.moe_dp_size,
dcp_size=cfg.dcp_size,
dcp_enabled=cfg.dcp_size > 1,
)
def attn_tp_size_of(cfg: Any):
"""`attn_tp_size`, computed at publish. See `parallel_widths_of`."""
return parallel_widths_of(cfg)["attn_tp_size"]
def attn_dp_size_of(cfg: Any):
"""`attn_dp_size`, computed at publish. See `parallel_widths_of`."""
return parallel_widths_of(cfg)["attn_dp_size"]
def attn_dcp_size_of(cfg: Any):
"""`attn_dcp_size`, computed at publish. See `parallel_widths_of`."""
return parallel_widths_of(cfg)["attn_dcp_size"]
def moe_ep_size_of(cfg: Any):
"""`moe_ep_size`, computed at publish. See `parallel_widths_of`."""
return parallel_widths_of(cfg)["moe_ep_size"]
def moe_tp_size_of(cfg: Any):
"""`moe_tp_size`, computed at publish. See `parallel_widths_of`."""
return parallel_widths_of(cfg)["moe_tp_size"]
def dcp_enabled_of(cfg: Any):
"""`dcp_enabled`, computed at publish. See `parallel_widths_of`."""
return parallel_widths_of(cfg)["dcp_enabled"]
class ParallelContext:
"""Parallel-topology namespace: one spelling per name.
@@ -247,13 +303,17 @@ class ParallelContext:
def clear_derived_widths(self) -> None:
self._derived.clear()
def _derived_width(self, name, getter):
"""A width the leaves imply: the stamp, else the live group.
def _derived_width(self, name):
"""A width the configuration implies: override, else stamp, else the
published leaf.
The fallback keeps a process that installed groups without going
through `initialize_model_parallel` working. When neither is there,
the failure says which of the two is missing rather than surfacing a
group getter's bare assertion.
The leaf is computed at publish by `parallel_widths_of`; the stamp sits
above it because an elastic scale-up restamps `attn_dp_size` after
publish, and a scope that swaps in another TP group states the quotients
through `override`.
Nothing is recomputed on read, so overriding `tp_size` does not move
`attn_tp_size`: name the width, or publish a config.
"""
overrides = self._overrides
if name in overrides:
@@ -261,16 +321,16 @@ class ParallelContext:
derived = self._derived
if name in derived:
return derived[name]
try:
return getter()
except (AssertionError, AttributeError, RuntimeError) as exc:
raise RuntimeError(
f"derived parallel width {name!r} is not available: it is "
"computed from the configured leaves when the process groups "
"are built (initialize_model_parallel / "
"initialize_dp_attention), and neither a stamp nor a live "
"group is present"
) from exc
config = self._config
if config is not None and name in config._fields:
return getattr(config, name)
raise RuntimeError(
f"derived parallel width {name!r} is not available: it is computed "
"from the configured leaves at publish, and restamped when the "
"process groups are built. Nothing is published and nothing has "
"been stamped -- publish a parallel config, or state the width "
f"with get_parallel().override({name}=...)"
)
@contextmanager
def override(self, **kwargs):
@@ -302,12 +362,6 @@ class ParallelContext:
def pp_rank(self) -> int:
return self._v("pp_rank", _ps().get_pipeline_model_parallel_rank)
@property
def moe_ep_size(self) -> int:
return self._derived_width(
"moe_ep_size", _ps().get_moe_expert_parallel_world_size
)
@property
def moe_ep_rank(self) -> int:
return self._v("moe_ep_rank", _ps().get_moe_expert_parallel_rank)
@@ -316,22 +370,10 @@ class ParallelContext:
def moe_dp_rank(self) -> int:
return self._v("moe_dp_rank", _ps().get_moe_data_parallel_rank)
@property
def moe_tp_size(self) -> int:
return self._derived_width(
"moe_tp_size", _ps().get_moe_tensor_parallel_world_size
)
@property
def moe_tp_rank(self) -> int:
return self._v("moe_tp_rank", _ps().get_moe_tensor_parallel_rank)
@property
def attn_tp_size(self) -> int:
return self._derived_width(
"attn_tp_size", _ps().get_attn_tensor_model_parallel_world_size
)
@property
def attn_tp_rank(self) -> int:
return self._v("attn_tp_rank", _ps().get_attn_tensor_model_parallel_rank)
@@ -344,32 +386,12 @@ class ParallelContext:
def dcp_rank(self) -> int:
return self._v("dcp_rank", _ps().get_dcp_rank)
@property
def dcp_enabled(self) -> bool:
def getter():
if _ps().get_dcp_group_no_assert() is None:
return False
return _ps().get_dcp_world_size() > 1
return self._derived_width("dcp_enabled", getter)
@property
def attn_dcp_size(self) -> int:
return self._derived_width(
"attn_dcp_size",
lambda: _ps().get_dcp_world_size() if self.dcp_enabled else 1,
)
@property
def attn_dcp_rank(self) -> int:
return self._v(
"attn_dcp_rank", lambda: self.dcp_rank if self.dcp_enabled else 0
)
@property
def attn_dp_size(self) -> int:
return self._derived_width("attn_dp_size", _dp().get_attention_dp_size)
@property
def attn_dp_rank(self) -> int:
return self._v("attn_dp_rank", _dp().get_attention_dp_rank)
@@ -411,6 +433,34 @@ class ParallelContext:
return self._v("dcp_group", _ps().get_dcp_group)
def _install_derived_widths() -> None:
"""Give `ParallelContext` a property per declared quotient.
They are declared in `arg_groups/fields/parallel.py`, in the same class as
the leaves they are computed from -- unannotated, so `collect_input_fields`
leaves them off the record while they still live where the namespace does. Written here as
properties rather than answered by `__getattr__` because they are read
inside compiled model code, where an attribute load is traceable and a
dynamic lookup is not.
"""
from sglang.srt.arg_groups.arg_utils import Derived
from sglang.srt.arg_groups.fields.parallel import Parallel
for name, decl in vars(Parallel).items():
if not isinstance(decl, Derived):
continue
def getter(self, _name=name):
return self._derived_width(_name)
getter.__name__ = name
getter.__doc__ = decl.doc
setattr(ParallelContext, name, property(getter))
_install_derived_widths()
class _FlagGroupBase:
"""Shared flag-group behavior: typo-safe writes + transactional ``override()``.
@@ -845,9 +895,49 @@ def _build_config_bags(server_args: Any) -> dict:
"clashes with a subgroup of the same name"
)
bag._set(field, value)
_install_derived_leaves(tops, server_args)
return tops
def _install_derived_leaves(tops: dict, server_args: Any) -> None:
"""Compute the declared config-derived fields into their bags.
A `Derived(fn=...)` is a pure function of the published configuration, so it
is computed once, here, and stored as an ordinary leaf: readers get a plain
attribute load, and there is one answer rather than a pre-publish spelling
and a post-publish one that have to be kept saying the same thing.
The function is handed the whole resolved config, not the bag it lands in.
A derivation is free to span namespaces and they do -- the mamba
extra-buffer predicate reads `memory.disable_radix_cache` alongside its own
`exec.mamba` strategy -- which is exactly why it cannot be written as a
method on either bag.
"""
import importlib
from sglang.srt.arg_groups.arg_utils import Derived
from sglang.srt.arg_groups.overrides import resolved_view
namespaces = getattr(type(server_args), "_NAMESPACES", None)
if not namespaces:
return
view = resolved_view(server_args)
for source in namespaces:
path = getattr(source, "_NS_PATH", None)
if path is None:
continue
for name, decl in vars(source).items():
if not isinstance(decl, Derived) or not decl.fn:
continue
module, _, attr = decl.fn.rpartition(".")
bag = tops.get(path.split(".")[0])
for segment in path.split(".")[1:]:
bag = bag and getattr(bag, segment, None)
if bag is None:
continue
bag._set(name, getattr(importlib.import_module(module), attr)(view))
def _resolved_or_field(server_args: Any, name: str, default: Any) -> Any:
"""What resolution decided for `name`, falling back to the field.
@@ -1662,8 +1752,8 @@ def reset_context() -> None:
``server_args`` and install fresh ``Flags`` and ``Resources``.
``parallel`` holds the stamped derived widths, which go with the lifecycle
that stamped them: `_derived_width` prefers the stamp over the live group,
so leaving one behind lets the next test read the previous topology.
that stamped them: `_derived_width` prefers the stamp over the leaves, so
leaving one behind lets the next test read the previous topology.
"""
_CONTEXT._server_args = None
_CONTEXT._config_bags = None
@@ -1677,29 +1767,6 @@ def reset_context() -> None:
set_global_dwdp_manager(None)
def mamba_extra_buffer_enabled() -> bool:
"""Whether the mamba radix cache keeps its extra state buffer.
A predicate over two published leaves (``memory.disable_radix_cache`` and
``exec.mamba.mamba_radix_cache_strategy``), so it reads the bags rather
than the startup record — the ``ServerArgs`` member of the same name is the
pre-publish equivalent used inside the resolution pipeline.
"""
return (
get_memory().disable_radix_cache is False
and get_exec().mamba.mamba_radix_cache_strategy
in ("extra_buffer", "extra_buffer_lazy")
)
def mamba_extra_buffer_lazy_enabled() -> bool:
"""The lazy variant of :func:`mamba_extra_buffer_enabled`."""
return (
get_memory().disable_radix_cache is False
and get_exec().mamba.mamba_radix_cache_strategy == "extra_buffer_lazy"
)
def remote_instance_transfer_engine_enabled(load_format: str | None = None) -> bool:
"""Whether remote-instance weight loading runs over the transfer engine.
@@ -2034,21 +2101,6 @@ def cutedsl_moe_max_num_tokens() -> int:
return max(prefill_tokens, decode_max_bs * num_tokens_per_req)
def is_ep_joiner() -> bool:
"""True in a process launched as an elastic-EP joiner (scale or recover).
A predicate over the published ``exec.moe.ep_join_mode`` leaf, so it follows
a post-publish override; the same-named ``ServerArgs`` property is the
pre-publish equivalent.
"""
return get_exec().moe.ep_join_mode in ("scale", "recover")
def is_ep_scale_joiner() -> bool:
"""True in a process launched as an elastic-EP scale-up joiner."""
return get_exec().moe.ep_join_mode == "scale"
def describe_kv_events_publisher(server_args: Any) -> Optional[dict]:
"""Return a structured description of this server's KV-event
publisher, or `None` if publishing is disabled / misconfigured.