address review: rename load_yaml_raw, drop Tier-1/2 terminology, fix OmegaConf import

Signed-off-by: lishunyang <lishunyang12@163.com>

Author: lishunyang12

examples/offline_inference/qwen3_omni/end2end.py

@@ -21,7 +21,6 @@
 from vllm.multimodal.image import convert_image_mode
 from vllm.utils.argparse_utils import FlexibleArgumentParser
 
-# Import StageConfigFactory for Tier-2 CLI override testing
 from vllm_omni.entrypoints.omni import Omni
 
 SEED = 42
@@ -295,7 +294,7 @@ def main(args):
     else:
         query_result = query_func()
 
-    # Build kwargs with Tier-2 CLI overrides.
+    # Build kwargs with CLI overrides.
     # Global params (e.g. --gpu-memory-utilization) apply to all stages;
     # per-stage overrides (--stage-N-*) take precedence when specified.
     omni_kwargs = {
@@ -304,7 +303,7 @@ def main(args):
         "stage_init_timeout": args.stage_init_timeout,
     }
 
-    # Add Tier-2 CLI overrides if specified
+    # Add CLI overrides if specified
     if args.gpu_memory_utilization is not None:
         omni_kwargs["gpu_memory_utilization"] = args.gpu_memory_utilization
     if args.tensor_parallel_size is not None:
@@ -500,38 +499,38 @@ def parse_args():
         "--stage-configs-path",
         type=str,
         default=None,
-        help="Path to a stage configs file. If not specified, uses auto-detected Tier-1 topology.",
+        help="Path to a stage configs file. If not specified, uses auto-detected model pipeline config.",
     )
-    # Tier-2 CLI override arguments
+    # CLI override arguments (applied to all stages by default)
     parser.add_argument(
         "--gpu-memory-utilization",
         type=float,
         default=None,
-        help="GPU memory utilization for all stages (Tier-2 override). Example: 0.9",
+        help="GPU memory utilization for all stages. Example: 0.9",
     )
     parser.add_argument(
         "--tensor-parallel-size",
         type=int,
         default=None,
-        help="Tensor parallel size for all stages (Tier-2 override). Example: 2",
+        help="Tensor parallel size for all stages. Example: 2",
     )
     parser.add_argument(
         "--devices",
         type=str,
         default=None,
-        help="Device assignment for stages (Tier-2 override). Example: '0,1'",
+        help="Device assignment for stages. Example: '0,1'",
     )
     parser.add_argument(
         "--enforce-eager",
         action="store_true",
         default=False,
-        help="Enforce eager mode for all stages (Tier-2 override).",
+        help="Enforce eager mode for all stages.",
     )
     parser.add_argument(
         "--trust-remote-code",
         action="store_true",
         default=False,
-        help="Trust remote code for model loading (Tier-2 override).",
+        help="Trust remote code for model loading.",
     )
     parser.add_argument(
         "--video-path",

vllm_omni/config/__init__.py

@@ -12,7 +12,7 @@
 )
 from vllm_omni.config.yaml_util import (
     create_config,
-    load_yaml_raw,
+    load_yaml_to_config,
     merge_configs,
     to_dict,
 )
@@ -25,7 +25,7 @@
     "StageTopology",
     "StageType",
     "create_config",
-    "load_yaml_raw",
+    "load_yaml_to_config",
     "merge_configs",
     "to_dict",
 ]

vllm_omni/config/stage_config.py

@@ -1,13 +1,14 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 """
-Two-Tier Stage Configuration System for vLLM-Omni.
+Model Pipeline Configuration System for vLLM-Omni.
 
 Design Principles:
-- Tier-1 (Pipeline Topology): INTERNAL ONLY - set by model developers at integration time
-- Tier-2 (Runtime Config): User-configurable via CLI args (VllmConfig/OmniDiffusionConfig params)
+- Model Pipeline Config: INTERNAL ONLY - set by model developers at integration time.
+  Defines pipeline structure (stages, types, data-flow).
+- Runtime Config: User-configurable via CLI args (VllmConfig/OmniDiffusionConfig params).
 
-Users interact only with Tier-2 (CLI). Tier-1 topology is bundled with models.
+Users interact only with CLI args. Pipeline config is bundled with models.
 """
 
 from __future__ import annotations
@@ -19,7 +20,7 @@
 
 from vllm.logger import init_logger
 
-from vllm_omni.config.yaml_util import create_config, load_yaml_raw, to_dict
+from vllm_omni.config.yaml_util import create_config, load_yaml_to_config, to_dict
 from vllm_omni.model_executor.stage_topologies import get_topology_path
 
 logger = init_logger(__name__)
@@ -39,10 +40,10 @@ class StageConfig:
     Note: Engine params (gpu_memory_utilization, tp_size, etc.) come from
     VllmConfig or OmniDiffusionConfig via CLI, NOT from this class.
 
-    This class represents Tier-1 (Internal) configuration that is:
+    This class represents pipeline configuration that is:
     - Set by model developers at integration time
     - NOT user-editable
-    - Defines pipeline topology, worker types, and processing hooks
+    - Defines pipeline structure, worker types, and processing hooks
 
     Attributes:
         stage_id: Unique identifier for this stage in the pipeline.
@@ -69,28 +70,28 @@ class StageConfig:
     # Stage type
     stage_type: StageType = StageType.LLM
 
-    # Pipeline topology (Tier-1 - Internal, set by developer).
+    # Pipeline topology (internal, set by developer).
     # Lists upstream stage IDs this stage receives data from.
     # Future: may be derived from StageTopology.edges for richer
     # edge metadata (e.g., data format, buffering policy).
     input_sources: list[int] = field(default_factory=list)
 
-    # Processing hooks (Tier-1 - Internal)
+    # Processing hooks (internal)
     custom_process_input_func: str | None = None
 
-    # Output configuration (Tier-1 - Internal)
+    # Output configuration (internal)
     final_output: bool = False
     final_output_type: str | None = None  # "text", "audio", "image"
 
-    # Worker configuration (Tier-1 - Internal)
+    # Worker configuration (internal)
     worker_type: str | None = None  # "ar" or "generation"
     scheduler_cls: str | None = None
     hf_config_name: str | None = None
 
     # Comprehension flag
     is_comprehension: bool = False
 
-    # Runtime overrides (Tier-2 - populated from CLI, not from topology file)
+    # Runtime overrides (populated from CLI, not from pipeline config)
     runtime_overrides: dict[str, Any] = field(default_factory=dict)
 
     def to_omegaconf(self) -> Any:
@@ -111,7 +112,7 @@ def to_omegaconf(self) -> Any:
         if self.hf_config_name:
             engine_args["hf_config_name"] = self.hf_config_name
 
-        # Apply runtime overrides from Tier-2 (CLI args)
+        # Apply runtime overrides from CLI args
         for key, value in self.runtime_overrides.items():
             if key not in ("devices", "max_batch_size"):
                 engine_args[key] = value
@@ -144,7 +145,7 @@ def to_omegaconf(self) -> Any:
 
 @dataclass
 class StageTopology:
-    """Internal Tier-1 topology - bundled with model, not user-editable.
+    """Model pipeline topology - bundled with model, not user-editable.
 
     This class represents the complete pipeline topology for a multi-stage model.
     It is defined by model developers and validated at integration time (not runtime).
@@ -218,12 +219,12 @@ def validate_topology(self) -> list[str]:
 
 
 class StageConfigFactory:
-    """Factory merges Tier-1 pipeline topology with Tier-2 CLI overrides.
+    """Factory merges model pipeline config with CLI overrides.
 
     This factory is the main entry point for creating stage configurations.
     It handles:
-    - Loading internal Tier-1 pipeline topology files
-    - Merging CLI overrides (Tier-2) into stage configs
+    - Loading model pipeline config files
+    - Merging CLI overrides into stage configs
     - Supporting both single-stage and multi-stage models
     """
 
@@ -247,7 +248,7 @@ def create_from_model(
 
         Args:
             model: Model name or path.
-            cli_overrides: Tier-2 CLI overrides from VllmConfig/OmniDiffusionConfig.
+            cli_overrides: CLI overrides from VllmConfig/OmniDiffusionConfig.
 
         Returns:
             List of StageConfig objects with CLI overrides applied.
@@ -328,7 +329,7 @@ def create_default_diffusion(cls, kwargs: dict[str, Any]) -> list[dict[str, Any]
 
     @classmethod
     def _load_topology(cls, model: str) -> StageTopology | None:
-        """Load internal Tier-1 pipeline topology YAML for the model.
+        """Load model pipeline config YAML for the model.
 
         Args:
             model: Model name or path.
@@ -355,7 +356,7 @@ def _load_topology(cls, model: str) -> StageTopology | None:
 
     @classmethod
     def _parse_topology_yaml(cls, path: Path, model_type: str) -> StageTopology:
-        """Parse a Tier-1 pipeline topology YAML file.
+        """Parse a model pipeline config YAML file.
 
         Args:
             path: Path to the YAML file.
@@ -364,7 +365,7 @@ def _parse_topology_yaml(cls, path: Path, model_type: str) -> StageTopology:
         Returns:
             StageTopology object.
         """
-        config_data = load_yaml_raw(path)
+        config_data = load_yaml_to_config(path)
 
         stages: list[StageConfig] = []
         for stage_data in config_data.stages:

vllm_omni/config/yaml_util.py

@@ -15,19 +15,22 @@
 from omegaconf import DictConfig, OmegaConf
 
 
-def load_yaml_raw(path: str | Any) -> DictConfig:
-    """Load a YAML file and return the raw DictConfig.
-
-    Use this when downstream code needs attribute-style access
-    (e.g., ``cfg.stage_args``). Prefer ``load_yaml()`` for new code.
+def load_yaml_to_config(path: str) -> DictConfig:
+    """Load a YAML file and return it as a DictConfig.
 
     Args:
         path: Path to the YAML file.
 
     Returns:
         OmegaConf DictConfig.
+
+    Raises:
+        TypeError: If the loaded YAML is not a mapping (e.g., a bare list).
     """
-    return OmegaConf.load(path)  # type: ignore[return-value]
+    cfg = OmegaConf.load(path)
+    if not isinstance(cfg, DictConfig):
+        raise TypeError(f"Expected a DictConfig from {path}, but got {type(cfg)}")
+    return cfg
 
 
 def create_config(data: Any) -> DictConfig:

vllm_omni/entrypoints/utils.py

@@ -9,7 +9,7 @@
 from vllm.transformers_utils.config import get_config, get_hf_file_to_dict
 from vllm.transformers_utils.repo_utils import file_or_path_exists
 
-from vllm_omni.config.yaml_util import create_config, load_yaml_raw, merge_configs
+from vllm_omni.config.yaml_util import create_config, load_yaml_to_config, merge_configs
 from vllm_omni.entrypoints.stage_utils import _to_dict
 from vllm_omni.platforms import current_omni_platform
 
@@ -275,7 +275,7 @@ def load_stage_configs_from_yaml(config_path: str, base_engine_args: dict | None
     """
     if base_engine_args is None:
         base_engine_args = {}
-    config_data = load_yaml_raw(config_path)
+    config_data = load_yaml_to_config(config_path)
     stage_args = config_data.stage_args
     global_async_chunk = config_data.get("async_chunk", False)
     # Convert any nested dataclass objects to dicts before creating DictConfig
@@ -320,7 +320,7 @@ def load_and_resolve_stage_configs(
         if not stage_configs:
             if default_stage_cfg_factory is not None:
                 default_stage_cfg = default_stage_cfg_factory()
-                stage_configs = OmegaConf.create(default_stage_cfg)
+                stage_configs = create_config(default_stage_cfg)
             else:
                 stage_configs = []
     else:

vllm_omni/model_executor/stage_topologies/__init__.py

@@ -1,12 +1,11 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 """
-Stage topology definitions for vLLM-Omni pipeline models.
+Model pipeline config definitions for vLLM-Omni pipeline models.
 
-Topology YAML files in this directory define Tier-1 (internal) pipeline
-structure: stages, their types, and data-flow connections.  Runtime
-parameters (GPU memory, tensor-parallel size, etc.) are NOT stored here;
-they come from CLI flags (Tier-2).
+YAML files in this directory define pipeline structure: stages, their
+types, and data-flow connections.  Runtime parameters (GPU memory,
+tensor-parallel size, etc.) are NOT stored here; they come from CLI flags.
 """
 
 from pathlib import Path

vllm_omni/model_executor/stage_topologies/bagel.yaml

@@ -1,12 +1,9 @@
-# Tier-1 Stage Topology for Bagel
-# This file is set by model developers at integration time.
-# Users NEVER edit this - they use CLI for Tier-2 params.
+# Model Pipeline Config for Bagel
+# Defines pipeline structure (stages, types, data-flow).
+# Runtime params (gpu_memory_utilization, tp_size, etc.) come from CLI.
 #
 # Stage 0: Thinker (LLM - multimodal understanding + text generation)
 # Stage 1: DiT (Diffusion - image generation from KV cache)
-#
-# NOTE: Engine params like gpu_memory_utilization, tensor_parallel_size,
-# devices, max_batch_size come from CLI (Tier-2), NOT from this file.
 
 model_type: bagel
 

vllm_omni/model_executor/stage_topologies/qwen2_5_omni.yaml

@@ -1,13 +1,10 @@
-# Tier-1 Stage Topology for Qwen2.5-Omni
-# This file is set by model developers at integration time.
-# Users NEVER edit this - they use CLI for Tier-2 params.
+# Model Pipeline Config for Qwen2.5-Omni
+# Defines pipeline structure (stages, types, data-flow).
+# Runtime params (gpu_memory_utilization, tp_size, etc.) come from CLI.
 #
 # Stage 0: Thinker (multimodal understanding + text generation)
 # Stage 1: Talker (text embeddings -> audio codec codes)
 # Stage 2: Code2Wav (codec codes -> audio waveform)
-#
-# NOTE: Engine params like gpu_memory_utilization, tensor_parallel_size,
-# devices, max_batch_size come from CLI (Tier-2), NOT from this file.
 
 model_type: qwen2_5_omni
 

vllm_omni/model_executor/stage_topologies/qwen3_omni_moe.yaml

@@ -1,13 +1,10 @@
-# Tier-1 Stage Topology for Qwen3-Omni-MoE
-# This file is set by model developers at integration time.
-# Users NEVER edit this - they use CLI for Tier-2 params.
+# Model Pipeline Config for Qwen3-Omni-MoE
+# Defines pipeline structure (stages, types, data-flow).
+# Runtime params (gpu_memory_utilization, tp_size, etc.) come from CLI.
 #
 # Stage 0: Thinker (multimodal understanding + text generation)
 # Stage 1: Talker (text embeddings -> 8-layer RVQ codec codes)
 # Stage 2: Code2Wav (8-layer RVQ codes -> audio waveform)
-#
-# NOTE: Engine params like gpu_memory_utilization, tensor_parallel_size,
-# devices, max_batch_size come from CLI (Tier-2), NOT from this file.
 
 model_type: qwen3_omni_moe
 

vllm_omni/model_executor/stage_topologies/qwen3_tts.yaml

@@ -1,12 +1,9 @@
-# Tier-1 Stage Topology for Qwen3-TTS
-# This file is set by model developers at integration time.
-# Users NEVER edit this - they use CLI for Tier-2 params.
+# Model Pipeline Config for Qwen3-TTS
+# Defines pipeline structure (stages, types, data-flow).
+# Runtime params (gpu_memory_utilization, tp_size, etc.) come from CLI.
 #
-# Stage 0: Talker (text -> audio codec codes)
+# Stage 0: Qwen3-TTS (text -> audio codec codes)
 # Stage 1: Code2Wav (codec codes -> audio waveform)
-#
-# NOTE: Engine params like gpu_memory_utilization, tensor_parallel_size,
-# devices, max_batch_size come from CLI (Tier-2), NOT from this file.
 
 model_type: qwen3_tts