[Core] Composable parallel: Phase 1 strategy overlay (TP/DP/stage-replica) (RFC #4084) (#4281)

Signed-off-by: Kushan A. <kahmadian@nvidia.com>
Signed-off-by: kushanam <kushanam@users.noreply.github.com>
Signed-off-by: Kushan A <kahmadian@nvidia.com>
Signed-off-by: kahmadian <kahmadian@users.noreply.github.com>
Co-authored-by: kushanam <kushanam@users.noreply.github.com>
Co-authored-by: kahmadian <kahmadian@users.noreply.github.com>

tests/config/composable_parallel/test_apply.py

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Tests for applying strategy specs onto merged stage configs."""
+
+from __future__ import annotations
+
+import pytest
+
+from vllm_omni.config.composable_parallel import (
+    Broadcast,
+    FanInByStage,
+    MeshAxisSpec,
+    RouteByStage,
+    StrategyApplyError,
+    StrategySpec,
+    TakeRank,
+    apply_strategy_specs,
+)
+from vllm_omni.config.stage_config import StageConfig
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def _tp(size: int) -> StrategySpec:
+    return StrategySpec("tp", MeshAxisSpec("tp", size), Broadcast(), TakeRank())
+
+
+def _stage_replica(size: int, policy: str = "round_robin") -> StrategySpec:
+    return StrategySpec("stage_replica", MeshAxisSpec("stage_replica", size), RouteByStage(policy), FanInByStage())
+
+
+def _stage(stage_id: int, model_stage: str, engine_args=None, runtime=None) -> StageConfig:
+    return StageConfig(
+        stage_id=stage_id,
+        model_stage=model_stage,
+        yaml_engine_args=dict(engine_args or {}),
+        yaml_runtime=dict(runtime or {"num_replicas": 1}),
+    )
+
+
+def _qwen_stages() -> list[StageConfig]:
+    return [
+        _stage(0, "thinker"),
+        _stage(1, "talker"),
+        _stage(2, "code2wav"),
+    ]
+
+
+def test_apply_tp_by_role():
+    stages = _qwen_stages()
+    apply_strategy_specs(stages, {"thinker": [_tp(2)]})
+    assert stages[0].yaml_engine_args["tensor_parallel_size"] == 2
+    # untouched roles keep their config
+    assert "tensor_parallel_size" not in stages[1].yaml_engine_args
+
+
+def test_apply_by_model_stage():
+    stages = _qwen_stages()
+    apply_strategy_specs(stages, {"thinker": [_tp(2)]})
+    assert stages[0].yaml_engine_args["tensor_parallel_size"] == 2
+
+
+def test_apply_stage_replica_sets_num_replicas_and_surfaces_lb():
+    stages = _qwen_stages()
+    result = apply_strategy_specs(stages, {"talker": [_stage_replica(2, "round_robin")]})
+    assert stages[1].yaml_runtime["num_replicas"] == 2
+    assert result.omni_lb_policy == "round-robin"
+
+
+def test_only_declared_axes_are_written():
+    stages = _qwen_stages()
+    # strategy declares only stage_replica -> tp must not be forced.
+    apply_strategy_specs(stages, {"talker": [_stage_replica(2)]})
+    assert "tensor_parallel_size" not in stages[1].yaml_engine_args
+
+
+def test_conflict_on_explicit_tp():
+    stages = _qwen_stages()
+    stages[0].yaml_engine_args["tensor_parallel_size"] = 4
+    with pytest.raises(StrategyApplyError):
+        apply_strategy_specs(stages, {"thinker": [_tp(2)]})
+
+
+def test_equal_explicit_value_is_noop():
+    stages = _qwen_stages()
+    stages[0].yaml_engine_args["tensor_parallel_size"] = 2
+    apply_strategy_specs(stages, {"thinker": [_tp(2)]})
+    assert stages[0].yaml_engine_args["tensor_parallel_size"] == 2
+
+
+def test_explicit_none_conflicts_with_derived_value():
+    # An explicit YAML ``null`` (``tensor_parallel_size: null``) is a *present*
+    # value, not a missing key, so a strategy deriving a non-None size must raise
+    # rather than silently clobber the explicit None.
+    stages = _qwen_stages()
+    stages[0].yaml_engine_args["tensor_parallel_size"] = None
+    with pytest.raises(StrategyApplyError):
+        apply_strategy_specs(stages, {"thinker": [_tp(2)]})
+
+
+def test_missing_key_is_filled_without_conflict():
+    # A genuinely absent key (never set in the YAML) is filled by the strategy
+    # and must NOT raise — the contrast case to an explicit None.
+    stages = _qwen_stages()
+    assert "tensor_parallel_size" not in stages[0].yaml_engine_args
+    apply_strategy_specs(stages, {"thinker": [_tp(2)]})
+    assert stages[0].yaml_engine_args["tensor_parallel_size"] == 2
+
+
+def test_num_replicas_conflict():
+    stages = _qwen_stages()
+    stages[1].yaml_runtime["num_replicas"] = 3
+    with pytest.raises(StrategyApplyError):
+        apply_strategy_specs(stages, {"talker": [_stage_replica(2)]})
+
+
+def test_device_count_ok_template():
+    stages = _qwen_stages()
+    stages[0].yaml_runtime["devices"] = "0,1"
+    apply_strategy_specs(stages, {"thinker": [_tp(2)]})
+    assert stages[0].yaml_engine_args["tensor_parallel_size"] == 2
+
+
+def test_device_count_ok_pool():
+    # tp=2 -> world=2; 2 replicas -> pool of 4 device ids is valid.
+    stages = _qwen_stages()
+    stages[1].yaml_runtime["devices"] = "0,1,2,3"
+    apply_strategy_specs(stages, {"talker": [_tp(2), _stage_replica(2)]})
+    assert stages[1].yaml_runtime["num_replicas"] == 2
+
+
+def test_device_count_mismatch():
+    stages = _qwen_stages()
+    stages[0].yaml_runtime["devices"] = "0,1,2"
+    with pytest.raises(StrategyApplyError):
+        apply_strategy_specs(stages, {"thinker": [_tp(2)]})
+
+
+def test_unknown_role_raises():
+    stages = _qwen_stages()
+    with pytest.raises(StrategyApplyError):
+        apply_strategy_specs(stages, {"nonexistent": [_tp(2)]})
+
+
+def test_conflicting_lb_policy_across_roles():
+    stages = _qwen_stages()
+    with pytest.raises(StrategyApplyError):
+        apply_strategy_specs(
+            stages,
+            {
+                "talker": [_stage_replica(2, "round_robin")],
+                "code2wav": [_stage_replica(2, "least_queue")],
+            },
+        )

tests/config/composable_parallel/test_factory_integration.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Integration tests: strategy overlay on the real merge_pipeline_deploy seam."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import pytest
+
+from vllm_omni.config.composable_parallel import (
+    Broadcast,
+    FanInByStage,
+    MeshAxisSpec,
+    RouteByStage,
+    StrategyApplyError,
+    StrategySpec,
+    TakeRank,
+    apply_strategy_specs,
+)
+from vllm_omni.config.config_factory import StageConfigFactory
+from vllm_omni.config.pipeline_registry import OMNI_PIPELINES
+from vllm_omni.config.stage_config import load_deploy_config, merge_pipeline_deploy
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+_DEPLOY = Path(__file__).parents[3] / "vllm_omni" / "deploy" / "qwen2_5_omni.yaml"
+
+
+def _tp(size: int) -> StrategySpec:
+    return StrategySpec("tp", MeshAxisSpec("tp", size), Broadcast(), TakeRank())
+
+
+def _stage_replica(size: int, policy: str = "round_robin") -> StrategySpec:
+    return StrategySpec("stage_replica", MeshAxisSpec("stage_replica", size), RouteByStage(policy), FanInByStage())
+
+
+def _qwen_stages():
+    pipeline = OMNI_PIPELINES["qwen2_5_omni"]
+    deploy = load_deploy_config(_DEPLOY)
+    return merge_pipeline_deploy(pipeline, deploy)
+
+
+def _stage(stages, role):
+    return next(s for s in stages if s.model_stage == role)
+
+
+def test_overlay_tp_on_thinker():
+    stages = _qwen_stages()
+    # The bundled deploy pins the thinker to one GPU; a TP=2 strategy needs a
+    # matching 2-GPU layout (mirrors what a TP2 deploy would declare).
+    _stage(stages, "thinker").yaml_runtime["devices"] = "0,1"
+    result = apply_strategy_specs(stages, {"thinker": [_tp(2)]})
+    assert _stage(result.stages, "thinker").yaml_engine_args["tensor_parallel_size"] == 2
+
+
+def test_device_guard_rejects_tp_on_single_gpu_deploy():
+    # The bundled deploy pins the thinker to a single GPU, so the pre-spawn
+    # device check must refuse a TP=2 strategy on it.
+    stages = _qwen_stages()
+    with pytest.raises(StrategyApplyError):
+        apply_strategy_specs(stages, {"thinker": [_tp(2)]})
+
+
+def test_overlay_stage_replica_on_talker():
+    stages = _qwen_stages()
+    result = apply_strategy_specs(stages, {"talker": [_stage_replica(2, "round_robin")]})
+    assert _stage(result.stages, "talker").yaml_runtime["num_replicas"] == 2
+    assert result.omni_lb_policy == "round-robin"
+
+
+def test_overlay_mixed_roles():
+    stages = _qwen_stages()
+    _stage(stages, "thinker").yaml_runtime["devices"] = "0,1"
+    result = apply_strategy_specs(
+        stages,
+        {
+            "thinker": [_tp(2)],
+            "talker": [_stage_replica(2, "round_robin")],
+            "code2wav": [_stage_replica(2, "round_robin")],
+        },
+    )
+    by_role = {s.model_stage: s for s in result.stages}
+    assert by_role["thinker"].yaml_engine_args["tensor_parallel_size"] == 2
+    assert by_role["talker"].yaml_runtime["num_replicas"] == 2
+    assert by_role["code2wav"].yaml_runtime["num_replicas"] == 2
+    assert result.omni_lb_policy == "round-robin"
+
+
+def _resolved(stages, role):
+    """Return a role's fully-resolved (post-CLI) OmegaConf stage config."""
+    stage = next(s for s in stages if s.model_stage == role)
+    return stage.to_omegaconf()
+
+
+def test_device_check_survives_cli_override():
+    # Strategy replicates the talker (1-GPU template -> valid at apply time),
+    # but a CLI --stage_1_devices with 3 ids must NOT slip past the device
+    # guard: effective world=1, replicas=2 admits only 1 or 2 device ids.
+    pipeline_cfg = OMNI_PIPELINES["qwen2_5_omni"]
+    with pytest.raises(StrategyApplyError):
+        StageConfigFactory._create_from_registry(
+            "qwen2_5_omni",
+            pipeline_cfg,
+            cli_overrides={"stage_1_devices": "0,1,2"},
+            strategy_specs={"talker": [_stage_replica(2, "round_robin")]},
+        )
+
+
+def test_cli_overrides_strategy_with_warning():
+    # Strategy derives num_replicas=2 for the talker; a CLI override to 3 wins
+    # (it is the most explicit user action) but must be surfaced loudly rather
+    # than silently. The resulting layout (1 template device) stays valid.
+    #
+    # vLLM's logger sets propagate=False, so attach a handler directly to it
+    # rather than relying on pytest's caplog (which listens on the root logger).
+    messages: list[str] = []
+
+    class _Capture(logging.Handler):
+        def emit(self, record: logging.LogRecord) -> None:
+            messages.append(record.getMessage())
+
+    log = logging.getLogger("vllm_omni.config.config_factory")
+    handler = _Capture(level=logging.WARNING)
+    log.addHandler(handler)
+    try:
+        pipeline_cfg = OMNI_PIPELINES["qwen2_5_omni"]
+        stages, _ = StageConfigFactory._create_from_registry(
+            "qwen2_5_omni",
+            pipeline_cfg,
+            cli_overrides={"stage_1_num_replicas": 3},
+            strategy_specs={"talker": [_stage_replica(2, "round_robin")]},
+        )
+    finally:
+        log.removeHandler(handler)
+
+    # CLI value wins in the resolved config.
+    assert _resolved(stages, "talker").runtime.num_replicas == 3
+    # ...and the override was warned about, naming the conflicting field.
+    assert any("num_replicas" in m and "overrides the strategy-derived" in m for m in messages)

tests/config/composable_parallel/test_spec_types.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Tests for the vendored spec/pattern data types."""
+
+from __future__ import annotations
+
+import pytest
+
+from vllm_omni.config.composable_parallel.aggregation import AggregationPattern, TakeRank
+from vllm_omni.config.composable_parallel.routing import RoutingPattern
+from vllm_omni.config.composable_parallel.spec import MeshAxisSpec
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_mesh_axis_rejects_bad_kind():
+    with pytest.raises(ValueError):
+        MeshAxisSpec(kind="not_a_kind", size=2)  # type: ignore[arg-type]
+
+
+def test_mesh_axis_rejects_nonpositive_size():
+    with pytest.raises(ValueError):
+        MeshAxisSpec(kind="tp", size=0)
+
+
+def test_routing_pattern_is_closed():
+    with pytest.raises(TypeError):
+
+        class RogueRouting(RoutingPattern):  # noqa: F811
+            pass
+
+
+def test_aggregation_pattern_is_closed():
+    with pytest.raises(TypeError):
+
+        class RogueAggregation(AggregationPattern):  # noqa: F811
+            pass
+
+
+def test_take_rank_type_guard():
+    with pytest.raises(TypeError):
+        TakeRank(rank=True)  # bool is not a valid rank

tests/config/composable_parallel/test_strategy_loader.py

@@ -0,0 +1,97 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Tests for parsing/loading strategy files."""
+
+from __future__ import annotations
+
+import pytest
+
+from vllm_omni.config.composable_parallel.routing import Broadcast, RouteByStage
+from vllm_omni.config.composable_parallel.strategy_loader import (
+    StrategyLoadError,
+    load_strategy_specs,
+    parse_strategy_specs,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_parse_basic():
+    data = {
+        "strategies": {
+            "thinker": [{"axis": "tp", "size": 2}],
+            "talker": [{"axis": "stage_replica", "size": 2, "routing": "round_robin"}],
+        }
+    }
+    specs = parse_strategy_specs(data)
+    assert set(specs) == {"thinker", "talker"}
+
+    (tp_spec,) = specs["thinker"]
+    assert tp_spec.mesh_axis.kind == "tp"
+    assert tp_spec.mesh_axis.size == 2
+    assert isinstance(tp_spec.routing, Broadcast)
+
+    (sr_spec,) = specs["talker"]
+    assert sr_spec.mesh_axis.kind == "stage_replica"
+    assert isinstance(sr_spec.routing, RouteByStage)
+    assert sr_spec.routing.routing_policy == "round_robin"
+
+
+def test_parse_without_strategies_key():
+    # A bare role mapping (no top-level "strategies") is also accepted.
+    specs = parse_strategy_specs({"thinker": [{"axis": "tp", "size": 4}]})
+    assert specs["thinker"][0].mesh_axis.size == 4
+
+
+def test_l1_owner_goes_to_shard_extension():
+    specs = parse_strategy_specs({"talker": [{"axis": "stage_replica", "size": 2, "l1_owner": "delegated"}]})
+    assert specs["talker"][0].shard_extension["l1_owner"] == "delegated"
+
+
+def test_missing_axis_raises():
+    with pytest.raises(StrategyLoadError):
+        parse_strategy_specs({"thinker": [{"size": 2}]})
+
+
+def test_missing_size_raises():
+    with pytest.raises(StrategyLoadError):
+        parse_strategy_specs({"thinker": [{"axis": "tp"}]})
+
+
+def test_routing_on_non_policy_axis_raises():
+    with pytest.raises(StrategyLoadError):
+        parse_strategy_specs({"thinker": [{"axis": "tp", "size": 2, "routing": "random"}]})
+
+
+def test_bad_size_raises():
+    with pytest.raises(StrategyLoadError):
+        parse_strategy_specs({"thinker": [{"axis": "tp", "size": "two"}]})
+
+
+def test_entries_must_be_list():
+    with pytest.raises(StrategyLoadError):
+        parse_strategy_specs({"thinker": {"axis": "tp", "size": 2}})
+
+
+def test_non_mapping_entry_raises():
+    # A list whose elements are not mappings (e.g. a bare string) must raise a
+    # StrategyLoadError, not an opaque TypeError from dict(entry).
+    with pytest.raises(StrategyLoadError):
+        parse_strategy_specs({"thinker": ["tp"]})
+
+
+def test_load_from_file(tmp_path):
+    path = tmp_path / "strategy.yaml"
+    path.write_text(
+        "strategies:\n"
+        "  thinker:\n"
+        "    - axis: tp\n"
+        "      size: 2\n"
+        "  talker:\n"
+        "    - axis: stage_replica\n"
+        "      size: 2\n"
+        "      routing: least_queue\n"
+    )
+    specs = load_strategy_specs(str(path))
+    assert specs["thinker"][0].mesh_axis.size == 2
+    assert specs["talker"][0].routing.routing_policy == "least_queue"

tests/config/composable_parallel/test_translator.py

@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Tests for StrategySpec -> OmniParallelConfig translation."""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from vllm_omni.config.composable_parallel import (
+    AxisTranslationError,
+    Broadcast,
+    FanInByStage,
+    MeshAxisSpec,
+    PartitionByHash,
+    PipelineMicrobatch,
+    RouteByStage,
+    StrategySpec,
+    TakeRank,
+    Union,
+    translate_strategy_stack,
+)
+from vllm_omni.config.composable_parallel.aggregation import StitchPipeline
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def _tp(size: int) -> StrategySpec:
+    return StrategySpec("tp", MeshAxisSpec("tp", size), Broadcast(), TakeRank())
+
+
+def _dp(size: int, policy: str = "round_robin") -> StrategySpec:
+    return StrategySpec("dp", MeshAxisSpec("dp", size), RouteByStage(policy), Union())
+
+
+def _pp(size: int) -> StrategySpec:
+    return StrategySpec("pp", MeshAxisSpec("pp", size), PipelineMicrobatch(), StitchPipeline())
+
+
+def _ep(size: int) -> StrategySpec:
+    return StrategySpec("ep", MeshAxisSpec("ep", size), Broadcast(), Union())
+
+
+def _stage_replica(size: int, policy: str = "round_robin") -> StrategySpec:
+    return StrategySpec("stage_replica", MeshAxisSpec("stage_replica", size), RouteByStage(policy), FanInByStage())
+
+
+def test_tp_only():
+    cfg = translate_strategy_stack([_tp(2)])
+    assert cfg.tensor_parallel_size == 2
+    assert cfg.data_parallel_size == 1
+    assert cfg.world_size == 2
+    assert cfg.stage_replica_size == 1
+    assert cfg.l1_owners == {"tp": "engine"}
+
+
+def test_dp_is_engine_owned():
+    cfg = translate_strategy_stack([_dp(2)])
+    assert cfg.data_parallel_size == 2
+    assert cfg.world_size == 2
+    # engine DP does not emit an omni LB policy (vLLM's internal DP LB is used).
+    assert cfg.omni_lb_policy is None
+    assert cfg.as_engine_kwargs().get("omni_lb_policy") is None
+    assert cfg.l1_owners["dp"] == "engine"
+
+
+def test_tp_times_dp_world_size():
+    cfg = translate_strategy_stack([_tp(2), _dp(2)])
+    assert cfg.world_size == 4
+    assert cfg.tensor_parallel_size == 2
+    assert cfg.data_parallel_size == 2
+
+
+def test_stage_replica_is_delegated():
+    cfg = translate_strategy_stack([_stage_replica(3, "least_queue")])
+    # stage_replica is NOT a world dimension.
+    assert cfg.world_size == 1
+    assert cfg.stage_replica_size == 3
+    assert cfg.omni_lb_policy == "least-queue-length"
+    assert cfg.l1_owners["stage_replica"] == "delegated"
+    # stage_replica_size is not an engine kwarg; it's a per-stage deploy knob.
+    assert "stage_replica_size" not in cfg.as_engine_kwargs()
+
+
+def test_stage_replica_lb_policy_only_when_replicated():
+    cfg = translate_strategy_stack([_stage_replica(1)])
+    assert cfg.stage_replica_size == 1
+    assert cfg.as_engine_kwargs().get("omni_lb_policy") is None
+
+
+def test_tp_with_stage_replica():
+    cfg = translate_strategy_stack([_tp(2), _stage_replica(2)])
+    assert cfg.world_size == 2  # tp only
+    assert cfg.tensor_parallel_size == 2
+    assert cfg.stage_replica_size == 2
+    assert cfg.omni_lb_policy == "round-robin"
+
+
+def test_ep_must_match_tp_dp_product():
+    cfg = translate_strategy_stack([_tp(2), _ep(2)])
+    assert cfg.enable_expert_parallel is True
+    assert cfg.as_engine_kwargs()["enable_expert_parallel"] is True
+
+
+def test_ep_mismatch_raises():
+    with pytest.raises(Exception) as exc:
+        translate_strategy_stack([_tp(2), _ep(4)])
+    assert "must equal" in str(exc.value)
+
+
+def test_duplicate_kind_rejected():
+    with pytest.raises(AxisTranslationError):
+        translate_strategy_stack([_tp(2), _tp(2)])
+
+
+def test_unsupported_kind_rejected():
+    spec = StrategySpec("sp", MeshAxisSpec("sp_ulysses", 2), Broadcast(), TakeRank())
+    with pytest.raises(AxisTranslationError):
+        translate_strategy_stack([spec])
+
+
+def test_dp_hash_routing_rejected():
+    spec = StrategySpec("dp", MeshAxisSpec("dp", 2), PartitionByHash(), Union())
+    with pytest.raises(NotImplementedError):
+        translate_strategy_stack([spec])
+
+
+def test_dp_invalid_routing_policy_rejected():
+    spec = StrategySpec("dp", MeshAxisSpec("dp", 2), RouteByStage("bogus"), Union())
+    with pytest.raises(AxisTranslationError):
+        translate_strategy_stack([spec])
+
+
+def test_lb_policy_never_in_engine_kwargs_even_when_replicated():
+    # omni_lb_policy is pipeline-wide (applied at engine construction), not a
+    # per-stage engine arg, so it must never leak into as_engine_kwargs().
+    cfg = translate_strategy_stack([_tp(2), _stage_replica(2, "least_queue")])
+    assert cfg.omni_lb_policy == "least-queue-length"
+    assert "omni_lb_policy" not in cfg.as_engine_kwargs()
+
+
+def test_stage_replica_hash_routing_rejected():
+    spec = StrategySpec("sr", MeshAxisSpec("stage_replica", 2), RouteByStage("hash"), FanInByStage())
+    with pytest.raises(NotImplementedError):
+        translate_strategy_stack([spec])
+
+
+def test_dp_wrong_owner_rejected():
+    spec = StrategySpec(
+        "dp",
+        MeshAxisSpec("dp", 2),
+        RouteByStage("round_robin"),
+        Union(),
+        shard_extension={"l1_owner": "delegated"},
+    )
+    with pytest.raises(AxisTranslationError):
+        translate_strategy_stack([spec])
+
+
+def test_stage_replica_wrong_owner_rejected():
+    spec = StrategySpec(
+        "sr",
+        MeshAxisSpec("stage_replica", 2),
+        RouteByStage("round_robin"),
+        FanInByStage(),
+        shard_extension={"l1_owner": "engine"},
+    )
+    with pytest.raises(AxisTranslationError):
+        translate_strategy_stack([spec])
+
+
+@pytest.mark.parametrize(
+    "specs",
+    [
+        [_tp(2)],
+        [_dp(2)],
+        [_tp(2), _dp(2)],
+        [_tp(2), _ep(2)],
+        [_tp(2), _stage_replica(2)],
+        [_pp(2)],
+    ],
+)
+def test_as_engine_kwargs_are_valid_omni_engine_args(specs):
+    # Guard against desync: every key emitted by as_engine_kwargs() must be a
+    # real OmniEngineArgs field, otherwise constructing the per-stage engine args
+    # would explode at runtime. Keep this CPU-only by checking field names rather
+    # than instantiating the engine.
+    from vllm_omni.engine.arg_utils import OmniEngineArgs
+
+    valid_fields = {f.name for f in dataclasses.fields(OmniEngineArgs)}
+    cfg = translate_strategy_stack(specs)
+    kwargs = cfg.as_engine_kwargs()
+    unknown = set(kwargs) - valid_fields
+    assert not unknown, f"as_engine_kwargs emitted non-OmniEngineArgs fields: {unknown}"

tests/engine/test_async_omni_engine_stage_init.py

@@ -739,7 +739,7 @@ def test_resolve_stage_configs_injects_global_diffusion_attention_when_missing(m
     monkeypatch.setattr(
         engine_mod,
         "load_and_resolve_stage_configs",
-        lambda *args, **kwargs: ("dummy-config", [stage_cfg]),
+        lambda *args, **kwargs: ("dummy-config", [stage_cfg], None),
     )
 
     _config_path, stage_configs = engine._resolve_stage_configs(
@@ -772,7 +772,7 @@ def test_resolve_stage_configs_preserves_stage_diffusion_attention(monkeypatch):
     monkeypatch.setattr(
         engine_mod,
         "load_and_resolve_stage_configs",
-        lambda *args, **kwargs: ("dummy-config", [stage_cfg]),
+        lambda *args, **kwargs: ("dummy-config", [stage_cfg], None),
     )
 
     _config_path, stage_configs = engine._resolve_stage_configs(
@@ -798,7 +798,7 @@ def test_resolve_stage_configs_does_not_inject_diffusion_attention_into_llm_stag
     monkeypatch.setattr(
         engine_mod,
         "load_and_resolve_stage_configs",
-        lambda *args, **kwargs: ("dummy-config", [stage_cfg]),
+        lambda *args, **kwargs: ("dummy-config", [stage_cfg], None),
     )
 
     _config_path, stage_configs = engine._resolve_stage_configs(

tests/engine/test_strategy_lb_policy.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Tests for strategy-derived omni_lb_policy threading into AsyncOmniEngine.
+
+``AsyncOmniEngine._apply_strategy_lb_policy`` only touches ``self._omni_lb_policy``
+and module-level logging, so we exercise it with a lightweight stub ``self`` to
+avoid standing up a full engine (which needs GPUs/model weights).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+class _Stub:
+    def __init__(self, current: str = "random") -> None:
+        self._omni_lb_policy = current
+
+
+_apply = AsyncOmniEngine._apply_strategy_lb_policy
+
+
+def test_no_derived_policy_is_noop():
+    stub = _Stub("random")
+    _apply(stub, None, {})
+    assert stub._omni_lb_policy == "random"
+
+
+def test_derived_overrides_default_random():
+    # "random" is the engine default == "unset", so the strategy value wins.
+    stub = _Stub("random")
+    _apply(stub, "round-robin", {})
+    assert stub._omni_lb_policy == "round-robin"
+
+
+def test_derived_overrides_when_flag_absent():
+    stub = _Stub("random")
+    _apply(stub, "least-queue-length", {"omni_lb_policy": None})
+    assert stub._omni_lb_policy == "least-queue-length"
+
+
+def test_explicit_matching_flag_is_fine():
+    stub = _Stub("round-robin")
+    _apply(stub, "round-robin", {"omni_lb_policy": "round-robin"})
+    assert stub._omni_lb_policy == "round-robin"
+
+
+def test_explicit_conflicting_flag_raises():
+    stub = _Stub("round-robin")
+    with pytest.raises(ValueError, match="Conflicting load-balancer policy"):
+        _apply(stub, "least-queue-length", {"omni_lb_policy": "round-robin"})
+
+
+def test_explicit_random_is_treated_as_unset():
+    # An explicit --omni-lb-policy=random is indistinguishable from the default,
+    # so a strategy value still overrides it (documented Phase-1 semantics).
+    stub = _Stub("random")
+    _apply(stub, "round-robin", {"omni_lb_policy": "random"})
+    assert stub._omni_lb_policy == "round-robin"

tests/entrypoints/test_async_omni_diffusion_config.py

@@ -343,7 +343,7 @@ def test_resolve_stage_configs_injects_additional_config_into_diffusion_stage(mo
     )
     mocker.patch(
         "vllm_omni.engine.async_omni_engine.load_and_resolve_stage_configs",
-        return_value=("dummy.yaml", [fake_llm_stage, fake_diffusion_stage]),
+        return_value=("dummy.yaml", [fake_llm_stage, fake_diffusion_stage], None),
     )
 
     engine = AsyncOmniEngine.__new__(AsyncOmniEngine)

tests/entrypoints/test_resolve_dreamzero_config.py

@@ -32,7 +32,7 @@ def test_dreamzero_config_sets_model_class_and_policy_config(monkeypatch):
         lambda _model: True,
     )
 
-    stage_configs = load_stage_configs_from_model("GEAR-Dreams/DreamZero-DROID")
+    stage_configs, _ = load_stage_configs_from_model("GEAR-Dreams/DreamZero-DROID")
     engine_args = stage_configs[0].engine_args
 
     assert engine_args.model_class_name == "DreamZeroPipeline"

tests/entrypoints/test_serve.py

@@ -9,6 +9,7 @@ import pytest
 from pytest_mock import MockerFixture
 
 from vllm_omni.entrypoints.cli.serve import OmniServeCommand, run_headless
+from vllm_omni.entrypoints.utils import parse_stage_overrides
 from vllm_omni.utils.tracking_parser import TrackingArgumentParser, TrackingNamespace
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
@@ -31,6 +32,20 @@ def test_serve_parser_accepts_no_async_chunk_and_marks_it_explicit() -> None:
     assert not explicit["async_chunk"]
 
 
+def test_serve_parser_accepts_strategy_config() -> None:
+    """``--strategy-config`` must parse onto the ``strategy_config`` dest and be
+    forwarded as an explicit kwarg so the engine can overlay the strategy."""
+    parser = TrackingArgumentParser()
+    subparsers = parser.add_subparsers(dest="subcommand")
+    cmd = OmniServeCommand()
+    cmd.subparser_init(subparsers)
+
+    argv = ["serve", "fake-model", "--omni", "--strategy-config", "/tmp/strategy.yaml"]
+    args = parser.parse_args(argv)
+    assert args.strategy_config == "/tmp/strategy.yaml"
+    assert args.get_explicit_kwargs_dict()["strategy_config"] == "/tmp/strategy.yaml"
+
+
 def _make_headless_args(**kwargs) -> TrackingNamespace:
     defaults = {
         "model": "fake-model",
@@ -80,13 +95,97 @@ def test_run_headless_rejects_non_multiprocess_worker_backend() -> None:
         run_headless(args)
 
 
+# ---------------------------------------------------------------------------
+# --stage-overrides parsing parity (headless vs standard path)
+# ---------------------------------------------------------------------------
+
+
+def test_parse_stage_overrides_valid_json() -> None:
+    """A valid JSON string is parsed into the nested per-stage dict."""
+    parsed = parse_stage_overrides('{"0": {"devices": "0,1"}, "1": {"devices": "2"}}')
+    assert parsed == {"0": {"devices": "0,1"}, "1": {"devices": "2"}}
+
+
+def test_parse_stage_overrides_none_and_empty_return_none() -> None:
+    """No overrides (None / empty string) resolve to ``None``."""
+    assert parse_stage_overrides(None) is None
+    assert parse_stage_overrides("") is None
+
+
+def test_parse_stage_overrides_empty_dict_returns_none() -> None:
+    """An empty dict is falsy and must resolve to ``None``, locking in parity
+    with the original standard-path ``if stage_overrides_json:`` falsy check."""
+    assert parse_stage_overrides({}) is None
+
+
+def test_parse_stage_overrides_passes_through_non_str() -> None:
+    """An already-parsed mapping is returned unchanged (identity)."""
+    overrides = {"0": {"devices": "0"}}
+    assert parse_stage_overrides(overrides) is overrides
+
+
+def test_parse_stage_overrides_invalid_json_raises() -> None:
+    """Invalid JSON raises ValueError whose message matches the standard path
+    verbatim: the ``--stage-overrides is not valid JSON:`` prefix AND the
+    ``Got: <repr>`` suffix echoing the raw input."""
+    bad = "{not valid json}"
+    with pytest.raises(ValueError) as excinfo:
+        parse_stage_overrides(bad)
+    message = str(excinfo.value)
+    assert message.startswith("--stage-overrides is not valid JSON:")
+    assert f"Got: {bad!r}" in message
+
+
+def test_run_headless_parses_and_forwards_stage_overrides(mocker: MockerFixture) -> None:
+    """Regression: the headless path must parse ``--stage-overrides`` (a JSON
+    string) and forward the parsed dict to ``load_and_resolve_stage_configs``,
+    mirroring the standard engine path. Previously it was dropped entirely,
+    silently producing a different per-stage device layout."""
+    captured: dict = {}
+
+    def _fake_resolve(*args, **kwargs):
+        captured.update(kwargs)
+        # Return a stage that does NOT match stage_id=0 so run_headless stops
+        # right after the resolver call (we only care about how it was called).
+        return ("/fake/stages.yaml", [SimpleNamespace(stage_id=99)], None)
+
+    mocker.patch(
+        "vllm_omni.entrypoints.utils.load_and_resolve_stage_configs",
+        side_effect=_fake_resolve,
+    )
+
+    args = _make_headless_args(
+        stage_id=0,
+        strategy_config="/tmp/strategy.yaml",
+        stage_overrides='{"0": {"devices": "0,1"}, "1": {"devices": "2"}}',
+    )
+    with pytest.raises(ValueError, match="No stage config found for stage_id=0"):
+        run_headless(args)
+
+    assert captured["stage_overrides"] == {"0": {"devices": "0,1"}, "1": {"devices": "2"}}
+    assert captured["strategy_config_path"] == "/tmp/strategy.yaml"
+
+
+def test_run_headless_invalid_stage_overrides_raises(mocker: MockerFixture) -> None:
+    """Invalid ``--stage-overrides`` JSON in headless mode fails fast with the
+    shared ValueError instead of being silently ignored."""
+    mocker.patch(
+        "vllm_omni.entrypoints.utils.load_and_resolve_stage_configs",
+        return_value=("/fake/stages.yaml", [SimpleNamespace(stage_id=0)], None),
+    )
+
+    args = _make_headless_args(stage_id=0, stage_overrides="{not valid json}")
+    with pytest.raises(ValueError, match="--stage-overrides is not valid JSON"):
+        run_headless(args)
+
+
 def test_run_headless_raises_when_stage_id_not_in_configs(mocker: MockerFixture) -> None:
     """Headless looks up its assigned stage_id in the loaded deploy YAML and
     fails fast when the launcher's --stage-id doesn't match any entry."""
     other_stage = SimpleNamespace(stage_id=99)
     mocker.patch(
         "vllm_omni.entrypoints.utils.load_and_resolve_stage_configs",
-        return_value=("/fake/stages.yaml", [other_stage]),
+        return_value=("/fake/stages.yaml", [other_stage], None),
     )
 
     args = _make_headless_args(stage_id=0)
@@ -134,7 +233,7 @@ def test_run_headless_llm_registers_with_auto_assigned_replica_id(mocker: Mocker
 
     mocker.patch(
         "vllm_omni.entrypoints.utils.load_and_resolve_stage_configs",
-        return_value=("/fake/stages.yaml", [stage_cfg]),
+        return_value=("/fake/stages.yaml", [stage_cfg], None),
     )
     mocker.patch("vllm_omni.engine.stage_init_utils.prepare_engine_environment")
     mocker.patch("vllm_omni.engine.stage_init_utils.load_omni_transfer_config_for_model", return_value=None)
@@ -210,7 +309,7 @@ def test_run_headless_llm_launches_one_manager_per_omni_dp_size_local(mocker: Mo
 
     mocker.patch(
         "vllm_omni.entrypoints.utils.load_and_resolve_stage_configs",
-        return_value=("/fake/stages.yaml", [stage_cfg]),
+        return_value=("/fake/stages.yaml", [stage_cfg], None),
     )
     mocker.patch("vllm_omni.engine.stage_init_utils.prepare_engine_environment")
     mocker.patch("vllm_omni.engine.stage_init_utils.load_omni_transfer_config_for_model", return_value=None)
@@ -269,7 +368,7 @@ def test_run_headless_diffusion_registers_and_spawns_proc(mocker: MockerFixture)
 
     mocker.patch(
         "vllm_omni.entrypoints.utils.load_and_resolve_stage_configs",
-        return_value=("/fake/stages.yaml", [stage_cfg]),
+        return_value=("/fake/stages.yaml", [stage_cfg], None),
     )
     mocker.patch("vllm_omni.engine.stage_init_utils.prepare_engine_environment")
     mocker.patch("vllm_omni.engine.stage_init_utils.load_omni_transfer_config_for_model", return_value=None)
@@ -349,7 +448,7 @@ def test_run_headless_diffusion_raises_on_nonzero_proc_exit(mocker: MockerFixtur
 
     mocker.patch(
         "vllm_omni.entrypoints.utils.load_and_resolve_stage_configs",
-        return_value=("/fake/stages.yaml", [stage_cfg]),
+        return_value=("/fake/stages.yaml", [stage_cfg], None),
     )
     mocker.patch("vllm_omni.engine.stage_init_utils.prepare_engine_environment")
     mocker.patch("vllm_omni.engine.stage_init_utils.load_omni_transfer_config_for_model", return_value=None)

tests/entrypoints/test_utils.py

@@ -318,7 +318,7 @@ class TestLoadAndResolveStageConfigs:
     def test_load_and_resolve_with_kwargs(self):
         """Ensure that dtype survives default stage creation."""
         kwargs = {"dtype": torch.float32}
-        config_path, stage_configs = load_and_resolve_stage_configs(
+        config_path, stage_configs, _ = load_and_resolve_stage_configs(
             model="black-forest-labs/FLUX.2-klein-4B",
             stage_configs_path=None,
             kwargs=kwargs,
@@ -349,10 +349,10 @@ class TestLoadAndResolveStageConfigs:
         ]
         load_stage_configs = mocker.patch(
             "vllm_omni.entrypoints.utils.load_stage_configs_from_model",
-            return_value=returned_stage_configs,
+            return_value=(returned_stage_configs, None),
         )
 
-        config_path, stage_configs = load_and_resolve_stage_configs(
+        config_path, stage_configs, _ = load_and_resolve_stage_configs(
             model="dummy-model",
             stage_configs_path=str(deploy_path),
             kwargs={},
@@ -363,6 +363,7 @@ class TestLoadAndResolveStageConfigs:
             base_engine_args={},
             deploy_config_path=str(deploy_path),
             stage_overrides=None,
+            strategy_config_path=None,
         )
         assert config_path == str(deploy_path)
         assert len(stage_configs) == 2

tests/test_config_factory.py

@@ -1721,7 +1721,7 @@ class TestAuraOmniDeploy:
     def test_aura_omni_deploy_resolves_four_native_stages(self):
         pipeline_cfg = StageConfigFactory.resolve_pipeline_config("aura_omni")
 
-        stages = StageConfigFactory._create_from_registry(
+        stages, _ = StageConfigFactory._create_from_registry(
             "qwen3_tts",
             pipeline_cfg,
             cli_overrides={},
@@ -1943,11 +1943,12 @@ class TestSentinelDefaultPrecedence:
             model_type,
             Q3_OMNI_ALL_STAGES_HF_CONFIG,
         )
-        return StageConfigFactory._create_from_registry(
+        stages, _ = StageConfigFactory._create_from_registry(
             "qwen3_omni_moe",
             pipeline_cfg,
             cli_overrides=cli_overrides,
         )
+        return stages
 
     def test_typed_kwarg_overrides_yaml(self):
         stages = self._stages({"max_num_seqs": 999})

tests/utils/test_tracking_parser.py

@@ -591,7 +591,7 @@ def test_explicit_cli_arg_reaches_runtime_overrides(mock_stages):
     ns = p.parse_args(["--max-num-seqs", "999"])
 
     explicit_kwargs = ns.get_explicit_kwargs_dict()
-    stages = StageConfigFactory._create_from_registry(
+    stages, _ = StageConfigFactory._create_from_registry(
         _TEST_MODEL,
         _TEST_PIPELINE,
         explicit_kwargs,
@@ -608,7 +608,7 @@ def test_omitted_default_not_in_runtime_overrides(mock_stages):
     ns = p.parse_args([])
 
     explicit_kwargs = ns.get_explicit_kwargs_dict()
-    stages = StageConfigFactory._create_from_registry(
+    stages, _ = StageConfigFactory._create_from_registry(
         _TEST_MODEL,
         _TEST_PIPELINE,
         explicit_kwargs,
@@ -630,7 +630,7 @@ def test_config_file_args_reach_runtime_overrides(mock_stages):
         ns = p.parse_args(["--config", "fake.yaml"])
 
     explicit_kwargs = ns.get_explicit_kwargs_dict()
-    stages = StageConfigFactory._create_from_registry(
+    stages, _ = StageConfigFactory._create_from_registry(
         _TEST_MODEL,
         _TEST_PIPELINE,
         explicit_kwargs,
@@ -648,7 +648,7 @@ def test_per_stage_override_routes_correctly(mock_stages):
     ns = p.parse_args(["--stage-0-gpu-memory-utilization", "0.42"])
 
     explicit_kwargs = ns.get_explicit_kwargs_dict()
-    stages = StageConfigFactory._create_from_registry(
+    stages, _ = StageConfigFactory._create_from_registry(
         _TEST_MODEL,
         _TEST_PIPELINE,
         explicit_kwargs,
@@ -670,7 +670,7 @@ def test_explicit_args_omitted_from_yaml(mock_stages):
     ns = p.parse_args(["--enforce-eager"])
 
     explicit_kwargs = ns.get_explicit_kwargs_dict()
-    stages = StageConfigFactory._create_from_registry(
+    stages, _ = StageConfigFactory._create_from_registry(
         _TEST_MODEL,
         _TEST_PIPELINE,
         explicit_kwargs,