[Docs] Remove stale stage config references (#6270)

Signed-off-by: zwhzzz0821 <2831474076@qq.com>

docs/configuration/README.md

@@ -4,11 +4,12 @@ This section lists the most common options for running vLLM-Omni.
 
 For options within a vLLM Engine, please refer to the [vLLM 0.26 configuration guide](https://docs.vllm.ai/en/v0.26.0/configuration/index.html).
 
-Currently, the main options are maintained by stage configs for each model.
+Each model defines fixed topology in a registered `PipelineConfig` and runtime
+overrides in a deploy YAML.
 
 For a specific example, see the [Qwen2.5-Omni deploy config](gh-file:vllm_omni/deploy/qwen2_5_omni.yaml). The matching frozen pipeline topology lives at [vllm_omni/model_executor/models/qwen2_5_omni/pipeline.py](gh-file:vllm_omni/model_executor/models/qwen2_5_omni/pipeline.py).
 
-For introduction, please check [Introduction for stage config](./stage_configs.md)
+For an introduction, see [Pipeline and deploy configurations](./stage_configs.md).
 
 ## Memory Configuration
 

docs/configuration/composable_parallel.md

@@ -1,6 +1,6 @@
 # Composable parallel strategies
 
-In vLLM-Omni, the `composable_parallel` system layers a declarative *parallel strategy* on top of the existing stage configs. A strategy YAML maps each pipeline stage (by its `model_stage` name) to a stack of axis declarations — one per parallelism dimension — that the engine translates into per-stage parallel sizing (`tensor_parallel_size`, `data_parallel_size`, `pipeline_parallel_size`, expert-parallel toggle, replica count) and, when relevant, an orchestrator-wide load-balancer policy.
+In vLLM-Omni, the `composable_parallel` system layers a declarative *parallel strategy* on top of the registered pipeline and deploy config. A strategy YAML maps each pipeline stage (by its `model_stage` name) to a stack of axis declarations — one per parallelism dimension — that the engine translates into per-stage parallel sizing (`tensor_parallel_size`, `data_parallel_size`, `pipeline_parallel_size`, expert-parallel toggle, replica count) and, when relevant, an orchestrator-wide load-balancer policy.
 
 Strategies are intentionally narrow: each one only writes the axes it declares, leaving every other engine arg untouched. This makes a strategy file a small, reusable overlay you can swap independently of the deploy YAML (see `configuration/stage_configs.md`).
 
@@ -195,7 +195,7 @@ Because `omni_lb_policy` is read once at `AsyncOmniEngine` construction — not
 
 Default: no default — required for every entry under `strategies:`.
 
-Strategy keys MUST be `model_stage` *names* (strings), the same labels stage configs use for `engine_args.model_stage` (see [`model_stage` in `stage_configs.md`](stage_configs.md#engine_argsmodel_stage)). Integer `stage_id` values are not accepted; the resolver matches on `model_stage` exactly (`_resolve_stage` in `vllm_omni/config/composable_parallel/apply.py`).
+Strategy keys MUST be `model_stage` *names* (strings), the same labels defined by [`StagePipelineConfig.model_stage`](stage_configs.md#pipeline-configuration). Integer `stage_id` values are not accepted; the resolver matches on `model_stage` exactly (`_resolve_stage` in `vllm_omni/config/composable_parallel/apply.py`).
 
 ## Common pitfalls
 

docs/configuration/gpu_memory_utilization.md

@@ -80,19 +80,15 @@ When multiple stages share the same GPU, you must ensure the sum of their `gpu_m
 
 **Example: Two stages on GPU 0**
 ```yaml
-stage_args:
+stages:
   - stage_id: 0
-    runtime:
-      devices: "0"
-    engine_args:
-      gpu_memory_utilization: 0.6  # Uses 60% of GPU 0
+    devices: "0"
+    gpu_memory_utilization: 0.6  # Uses 60% of GPU 0
 
   - stage_id: 1
-    runtime:
-      devices: "0"
-    engine_args:
-      gpu_memory_utilization: 0.3  # Uses 30% of GPU 0
-      # Total: 90% of GPU 0 (safe, leaves 10% buffer)
+    devices: "0"
+    gpu_memory_utilization: 0.3  # Uses 30% of GPU 0
+    # Total: 90% of GPU 0 (safe, leaves 10% buffer)
 ```
 
 **Important:** If stages run on different GPUs, each can use up to 1.0 independently.
@@ -103,14 +99,12 @@ When using `tensor_parallel_size > 1`, the model is split across multiple GPUs,
 
 **Example: 2-way tensor parallelism**
 ```yaml
-stage_args:
+stages:
   - stage_id: 0
-    runtime:
-      devices: "0,1"  # Uses both GPUs
-    engine_args:
-      tensor_parallel_size: 2
-      gpu_memory_utilization: 0.6  # 60% per GPU
-      # Model is split, so each GPU uses ~30% of model memory
+    devices: "0,1"  # Uses both GPUs
+    tensor_parallel_size: 2
+    gpu_memory_utilization: 0.6  # 60% per GPU
+    # Model is split, so each GPU uses ~30% of model memory
 ```
 
 ## Examples
@@ -118,27 +112,25 @@ stage_args:
 ### Qwen3-Omni-MoE on 2x H100-80GB
 
 ```yaml
-stage_args:
+base_config: /path/to/vllm_omni/deploy/qwen3_omni_moe.yaml
+
+stages:
   - stage_id: 0  # Thinker stage with TP=2
-    runtime:
-      devices: "0,1"
-    engine_args:
-      tensor_parallel_size: 2
-      gpu_memory_utilization: 0.6  # 48GB per GPU
+    devices: "0,1"
+    tensor_parallel_size: 2
+    gpu_memory_utilization: 0.6  # 48GB per GPU
 
   - stage_id: 1  # Talker stage
-    runtime:
-      devices: "1"
-    engine_args:
-      gpu_memory_utilization: 0.3  # 24GB on GPU 1
+    devices: "1"
+    gpu_memory_utilization: 0.3  # 24GB on GPU 1
 
   - stage_id: 2  # Code2Wav stage
-    runtime:
-      devices: "0"
-    engine_args:
-      gpu_memory_utilization: 0.1  # 8GB on GPU 0
+    devices: "0"
+    gpu_memory_utilization: 0.1  # 8GB on GPU 0
 ```
-**Note:** In this configuration, stages 0 and 2 share GPU 0, but they run at different times in the pipeline, so their memory usage doesn't overlap.
+**Note:** Stage 0 uses GPUs 0 and 1, so the combined utilization is `0.7` on
+GPU 0 and `0.9` on GPU 1. Keep the sum of all resident stages below `1.0` on
+each device.
 
 ## Troubleshooting
 

docs/configuration/stage_configs.md

@@ -3,7 +3,46 @@
 In vLLM-Omni, a model's `PipelineConfig` defines its fixed stage topology, while a deploy configuration controls how those stages run.
 
 !!! note
-    Default deploy config YAMLs (for example, `vllm_omni/deploy/qwen2_5_omni.yaml`, `vllm_omni/deploy/qwen3_omni_moe.yaml`, and `vllm_omni/deploy/qwen3_tts.yaml`) are bundled and loaded automatically when `--deploy-config` is omitted. The model registry resolves the right pipeline and deploy YAML by `model_type`.
+    Default deploy config YAMLs (for example, `vllm_omni/deploy/qwen2_5_omni.yaml`, `vllm_omni/deploy/qwen3_omni_moe.yaml`, and `vllm_omni/deploy/qwen3_tts.yaml`) are bundled and loaded automatically when `--deploy-config` is omitted. The resolved pipeline selects its default through `default_deploy_config_name`.
+
+## Pipeline configuration
+
+`PipelineConfig` and its `StagePipelineConfig` entries are Python definitions
+owned by the model implementation and registered in `OMNI_PIPELINES`. They
+describe fixed model topology and are not accepted in deploy YAMLs.
+
+Common `PipelineConfig` fields include:
+
+| Field | Description |
+|-------|-------------|
+| `model_type` | Pipeline identifier used during model and config resolution. |
+| `default_deploy_config_name` | Bundled deploy YAML loaded when the user does not pass `deploy_config`. |
+| `model_arch` | Default Hugging Face architecture for the pipeline. |
+| `hf_architectures` | Architecture names used to identify checkpoints whose `model_type` is shared. |
+| `hf_config_predicate` | Optional predicate used to select between pipelines with otherwise identical HF metadata. |
+| `diffusers_class_name` | Diffusers `_class_name` used to identify Diffusers-style repositories. |
+| `stages` | Ordered tuple of fixed `StagePipelineConfig` definitions. |
+
+Common `StagePipelineConfig` fields include:
+
+| Field | Description |
+|-------|-------------|
+| `stage_id` | Stable stage identifier. |
+| `model_stage` | Logical stage name used by runtime and strategy resolution. |
+| `execution_type` | `LLM_AR`, `LLM_GENERATION`, or `DIFFUSION`. |
+| `input_sources` | Upstream stage IDs that provide this stage's inputs. |
+| `final_output` / `final_output_type` | Whether the stage produces a user-visible output and its modality. |
+| `owns_tokenizer` | Whether this stage owns the pipeline tokenizer. |
+| `model_arch`, `hf_config_name` | Stage-specific model architecture and nested HF config selector. |
+| `engine_output_type` | Runtime output representation such as `text`, `latent`, or `audio`. |
+| `custom_process_input_func` | Processor applied to this stage's incoming payload. |
+| `custom_process_next_stage_input_func` | Processor used for full-payload handoff to the next stage. |
+| `async_chunk_process_next_stage_input_func` | Processor used for async chunk handoff. |
+| `sampling_constraints` | Model-owned sampling constraints that deploy defaults cannot override. |
+
+To add or change topology, define and register a new pipeline variant. Use
+deploy YAML only for runtime placement, resource sizing, connectors, and other
+deployment overrides.
 
 ## Deploy configuration schema
 
@@ -13,43 +52,51 @@ The new deploy schema lives under `vllm_omni/deploy/` and is paired with a froze
 |-------|------|----------|---------|-------------|
 | `base_config` | str (path) | optional | — | Overlay parent (relative or absolute). `stages:` / `platforms:` deep-merged by stage_id; other scalars overlay-wins. Intended for user-authored overlays; prod yamls stay flat. |
 | `async_chunk` | bool | optional | `true` | Enable chunked streaming between stages. Pin to `false` if the pipeline runs end-to-end. |
+| `session_mode` | str | optional | `"turn"` | Session behavior. Use `"duplex"` only with a pipeline that enables duplex control. |
+| `active_stream_window` | int | optional | `0` | Number of active downstream stream slots; `0` preserves all-stream cycling. |
+| `duplex_session` | dict | optional | runtime defaults | Full-duplex session lifecycle, buffering, replay, and capacity limits. |
 | `connectors` | dict | optional | `null` | Named connector specs (`{name, extra}`). Referenced by each stage's `input_connectors` / `output_connectors`. See [Connector schema](#connector-schema). |
 | `edges` | list | optional | `null` | Explicit edge list for the KV transfer graph. Auto-derived from stage inputs if omitted. |
-| `stages` | list | required | — | Per-stage engine args + wiring (see [Stage fields](#stage-fields)). |
+| `stages` | list | optional | `[]` | Per-stage runtime overrides matched by `stage_id`. Pipeline stages are still created from `PipelineConfig` when this list is empty. |
 | `platforms` | dict | optional | `null` | Keyed by `npu` / `rocm` / `xpu`, each contains a `stages:` list with per-platform overrides applied on top of the CUDA defaults. |
 | `pipeline` | str | optional | `null` | Override the auto-detected pipeline registry key (used for structural variants like `qwen2_5_omni_thinker_only`). |
-| `trust_remote_code` | bool | optional | `true` | **Pipeline-wide.** Trust HF remote code on model load; applies to every stage. |
+| `trust_remote_code` | bool \| null | optional | `null` | **Pipeline-wide.** Trust HF remote code on model load; applies to every stage when specified. |
 | `distributed_executor_backend` | str \| null | optional | `null` | **Pipeline-wide.** Distributed executor backend forwarded to vLLM (`"mp"`, `"ray"`, `"external_launcher"`). If omitted, vLLM auto-selects backend from runtime topology. |
 | `dtype` | str \| null | optional | `null` | **Pipeline-wide.** Model dtype for every stage. |
 | `quantization` | str \| null | optional | `null` | **Pipeline-wide.** Quantization method for every stage. |
-| `enable_prefix_caching` | bool | optional | `false` | **Pipeline-wide.** Prefix cache toggle applied to every stage. |
+| `enable_prefix_caching` | bool \| null | optional | `null` | **Pipeline-wide.** Prefix cache toggle applied to every stage when specified. |
 | `enable_chunked_prefill` | bool \| null | optional | `null` | **Pipeline-wide.** Chunked prefill toggle applied to every stage. |
-| `data_parallel_size` | int | optional | `1` | **Pipeline-wide.** DP degree for every stage. |
-| `pipeline_parallel_size` | int | optional | `1` | **Pipeline-wide.** PP degree for every stage. |
+| `data_parallel_size` | int \| null | optional | `null` | **Pipeline-wide.** DP degree for every stage. |
+| `pipeline_parallel_size` | int \| null | optional | `null` | **Pipeline-wide.** PP degree for every stage. |
+| `custom_voice_dir` | str \| null | optional | `null` | **Pipeline-wide.** Directory containing custom voice profiles for supported TTS models. |
+
+For fields whose deploy default is `null`, the deploy layer contributes no
+override. The effective value may still come from a platform section, an
+explicit CLI or stage override, or the downstream vLLM engine default.
 
 Note: for diffusion path, `distributed_executor_backend` currently defaults to
 `mp`, and `ray` / `external_launcher` are not fully supported yet.
 
 ### Stage fields
 
-Each entry under `stages:` accepts any `StageDeployConfig` field directly (no nested `engine_args:`). Only fields whose value legitimately varies across stages live here; pipeline-wide settings (trust_remote_code, distributed_executor_backend, dtype, quantization, prefix/chunked prefill, DP/PP sizes) are declared at the top level and applied to every stage. Unknown keys fall through to `engine_extras:` and are forwarded to the engine.
+Each entry under `stages:` accepts any `StageDeployConfig` field directly (no nested `engine_args:`). Only fields whose value legitimately varies across stages live here; pipeline-wide settings (trust_remote_code, distributed_executor_backend, dtype, quantization, prefix/chunked prefill, DP/PP sizes) are declared at the top level and applied to every stage. Unknown keys fall through to `engine_extras:` and are forwarded to the engine. Frequently used fields are listed below; the source-of-truth schema is `StageDeployConfig` in `vllm_omni/config/stage_config.py`.
 
 | Field | Type | Required | Default | Description |
 |-------|------|----------|---------|-------------|
 | `stage_id` | int | required | — | Stage identity; matched against `PipelineConfig.stages[*].stage_id`. |
-| `max_num_seqs` | int | optional | `64` | Max concurrent sequences per stage. |
-| `gpu_memory_utilization` | float | optional | `0.9` | Per-stage total memory target; used for automatic KV-cache sizing. |
+| `max_num_seqs` | int \| null | optional | `null` | Max concurrent sequences per stage. |
+| `gpu_memory_utilization` | float \| null | optional | `null` | Per-stage total memory target; used for automatic KV-cache sizing. |
 | `kv_cache_memory_bytes` | int \| null | optional | `null` | Explicit per-rank KV-cache budget in bytes; overrides automatic sizing. |
-| `tensor_parallel_size` | int | optional | `1` | TP degree for this stage. |
-| `enforce_eager` | bool | optional | `false` | Disable CUDA graphs. |
-| `max_num_batched_tokens` | int | optional | `32768` | Per-stage prefill/token budget; also contributes to the native maximum in-flight token limit. |
+| `tensor_parallel_size` | int \| null | optional | `null` | TP degree for this stage. |
+| `enforce_eager` | bool \| null | optional | `null` | Disable CUDA graphs. |
+| `max_num_batched_tokens` | int \| null | optional | `null` | Per-stage prefill/token budget; also contributes to the native maximum in-flight token limit. |
 | `max_model_len` | int \| null | optional | `null` | Per-sequence context or KV length; `-1` enables native cache-capacity auto-fitting, while values above the HF default auto-set `VLLM_ALLOW_LONG_MAX_MODEL_LEN=1`. |
 | `async_scheduling` | bool \| null | optional | `null` | Per-stage async scheduling toggle. |
-| `devices` | str | optional | `"0"` | `CUDA_VISIBLE_DEVICES`-style device list. |
+| `devices` | str \| null | optional | `null` | Device list assigned to this stage. |
 | `output_connectors` | dict \| null | optional | `null` | Keyed by `to_stage_<n>`; values are names registered under top-level `connectors:`. |
 | `input_connectors` | dict \| null | optional | `null` | Keyed by `from_stage_<n>`; values are names registered under top-level `connectors:`. |
 | `default_sampling_params` | dict \| null | optional | `null` | Baseline sampling params. Deep-merged with pipeline `sampling_constraints` (pipeline wins). |
-| `engine_extras` | dict | optional | `{}` | Catch-all for keys not listed above; deep-merged across overlays. Also carries per-stage overrides of pipeline-wide settings (e.g. stage-specific `dtype`). |
+| `engine_extras` | dict | optional | `{}` | Catch-all for engine fields not listed above; deep-merged across overlays and forwarded to the stage engine. |
 
 ### Connector schema
 
@@ -61,7 +108,7 @@ connectors:
     name: <ConnectorClassName>     # required — class registered in vllm_omni.distributed
     extra:                         # optional — forwarded to the connector's __init__
       <key>: <value>
-      ...
+      # Additional connector-specific options
 ```
 
 | Connector class | Use case | `extra` keys |
@@ -236,288 +283,3 @@ vllm serve Qwen/Qwen2.5-Omni-7B --omni --port 8091 --deploy-config /path/to/depl
 
 !!! important
     We are actively iterating on the definition of deployment configurations, and we welcome feedback from users and developers.
-
-## Legacy stage configuration reference
-
-The remainder of this page documents the deprecated `stage_args` schema for models that have not migrated to deploy configurations. The following historical Qwen2.5-Omni configuration illustrates that schema; current Qwen2.5-Omni deployments should use `vllm_omni/deploy/qwen2_5_omni.yaml` instead.
-
-```python
-# Historical stage configuration for Qwen2.5-Omni.
-stage_args:
-  - stage_id: 0 # mark the unique id for each stage
-    runtime: # The disaggregated configuration
-      process: true  # Run this stage in a separate process
-      devices: "0" # Logical device index for this stage (mapped through CUDA_VISIBLE_DEVICES / ASCEND_RT_VISIBLE_DEVICES if set)
-    engine_args: # Engine arguments for a certain engine
-      model_stage: thinker
-      max_num_seqs: 1
-      model_arch: Qwen2_5OmniForConditionalGeneration # The model implementation registered in model_executor/models/registry.py
-      worker_type: ar # The specific worker used
-      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler # The specific scehduler used
-      gpu_memory_utilization: 0.8 # The gpu memory allocation for the stage within a single chip
-      enforce_eager: true  # Now we only support eager mode
-      trust_remote_code: true # Needed by huggingface config parsing
-      engine_output_type: latent  # It claims that the stage will input latent hiddenstates besides token ids
-      enable_prefix_caching: false # For request with hiddenstates output, the prefix caching is not supported now
-    is_comprehension: true # If the stage is a text or multimodal comprehension module. If it is, the AsyncOmni will use its tokenizer as default
-    final_output: true # If the stage has output as part of final outputs. If it is false, which means that the stage only works as a intermediate role.
-    final_output_type: text # What is the final output type. It can be text and audio now.
-    default_sampling_params: # sampling parameters for the stage. Their meaning aligns with vLLM.
-      temperature: 0.0
-      top_p: 1.0
-      top_k: -1
-      max_tokens: 2048
-      seed: 42
-      detokenize: True
-      repetition_penalty: 1.1
-  - stage_id: 1
-    runtime:
-      process: true
-      devices: "1"
-    engine_args:
-      model_stage: talker
-      max_num_seqs: 3
-      model_arch: Qwen2_5OmniForConditionalGeneration
-      worker_type: ar
-      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler
-      gpu_memory_utilization: 0.8
-      enforce_eager: true
-      trust_remote_code: true
-      enable_prefix_caching: false
-      engine_output_type: latent
-    engine_input_source: [0]
-    default_sampling_params:
-      temperature: 0.9
-      top_p: 0.8
-      top_k: 40
-      max_tokens: 2048
-      seed: 42
-      detokenize: True
-      repetition_penalty: 1.05
-      stop_token_ids: [8294]
-  - stage_id: 2
-    runtime:
-      process: true
-      devices: "0"            # Example: use a different GPU than the previous stage; use "0" if single GPU
-    engine_args:
-      model_stage: code2wav
-      max_num_seqs: 1
-      model_arch: Qwen2_5OmniForConditionalGeneration
-      worker_type: generation
-      scheduler_cls: vllm_omni.core.sched.omni_generation_scheduler.OmniGenerationScheduler
-      gpu_memory_utilization: 0.15
-      enforce_eager: true
-      trust_remote_code: true
-      enable_prefix_caching: false
-      engine_output_type: audio
-    engine_input_source: [1]
-    final_output: true
-    final_output_type: audio
-    default_sampling_params:
-      temperature: 0.0
-      top_p: 1.0
-      top_k: -1
-      max_tokens: 2048
-      seed: 42
-      detokenize: True
-      repetition_penalty: 1.1
-
-# Top-level runtime config (concise): default windows and stage edges
-runtime:
-  enabled: true
-
-  edges:
-    - from: 0                   # thinker → talker: trigger only after receiving full input (-1)
-      to: 1
-    - from: 1                   # talker → code2wav: trigger only after receiving full input (-1)
-      to: 2
-
-```
-
-## Legacy stage configuration arguments
-
-Each stage in the `stage_args` list contains the following configuration options:
-
-### `stage_id`
-
-A unique identifier for each stage in the multi-stage pipeline. Stages are numbered sequentially starting from 0, and this ID is used to reference stages in inter-stage dependencies (e.g., `engine_input_source`).
-
-### `prompt_expand_func` (Optional)
-
-A custom Python function hook for the LLM stage (Stage 0) that expands a single incoming prompt object into multiple prompts. This is primarily used for multi-modal Classifier-Free Guidance (CFG), where it generates the necessary companion requests (like a negative text prompt) and tags them with internal roles (e.g., `cfg_text`). This ensures the upstream LLM generates the needed contextual hidden states for both the conditional and unconditional generations simultaneously.
-
-### `cfg_kv_collect_func` (Optional)
-
-A custom Python function hook for downstream diffusion stages (Stage 1+) to collect, map, and process the KV caches transferred from the companion requests fired by `prompt_expand_func`. It aggregates the hidden condition states cleanly (e.g., binding them as `cfg_text_past_key_values` and `cfg_text_kv_metadata`), allowing the diffusion runtime to perform CFG smoothly without redundantly evaluating text paths on the DiT workers.
-
-### `runtime`
-
-Configuration for disaggregated execution of the stage, controlling how the stage is deployed and executed.
-
-#### `runtime.process`
-
-Whether to run this stage in a separate process. When set to `true`, the stage will be executed in an isolated process, enabling better resource isolation and parallel execution across different stages. This is essential for multi-GPU deployments where different stages run on different devices.
-
-Default: `true`
-
-#### `runtime.devices`
-
-Logical device indices for this stage, specified as a string. Values are **logical indices** (`0`, `1`, `2`, ...) — not physical GPU IDs — and are mapped through the platform's visibility env var (`CUDA_VISIBLE_DEVICES` on CUDA, `ASCEND_RT_VISIBLE_DEVICES` on NPU) before being applied via `torch.cuda.set_device()` (or the equivalent).
-
-Example: if `CUDA_VISIBLE_DEVICES=0,2,4` is set in the environment, then `devices: "0"` selects physical GPU 0 (the first visible), `devices: "1"` selects physical GPU 2, and `devices: "0,1"` makes physical GPUs 0 and 2 available to the stage. If no visibility env var is set, logical and physical IDs coincide.
-
-Default: `"0"`
-
-#### `engine_args.max_num_seqs`
-
-The maximum number of sequences for concurrent processing in this stage. For
-LLM stages, this controls the vLLM scheduler's maximum concurrent sequences.
-For diffusion stages, this controls scheduler wave capacity in both request
-batch mode and step batch mode. `max_num_seqs: 1` is the serial/conservative
-path; values above `1` allow compatible requests to batch when the selected
-diffusion pipeline supports that batching mode.
-
-Default: `1`
-
-#### `engine_args.request_batch_max_wait_ms`
-
-The maximum time, in milliseconds, that a diffusion request-mode stage may wait
-before the first `schedule()` of a new scheduler wave so compatible requests can
-accumulate for request-level batching. This only applies to diffusion pipelines
-that support request-level batching with `step_execution` disabled.
-
-Use this together with `max_num_seqs > 1` for bursty serving traffic. `0`
-disables admission waiting and preserves the lowest first-request latency.
-For diffusion execution and batching tuning, see
-[Diffusion Execution Modes](../user_guide/diffusion/execution_modes.md).
-
-Default: `0.0`
-
-### `engine_args`
-
-Engine arguments for configuring the LLM engine, diffusion engine, or other engine types used by this stage.
-
-#### `engine_args.model_stage`
-
-The name identifier for this model stage within the multi-stage architecture. This is used internally to distinguish different stages of the same model (e.g., "thinker", "talker", "code2wav" in Qwen2.5-Omni).
-
-#### `engine_args.model_arch`
-
-The model architecture class name that is registered in `model_executor/models/registry.py`. This specifies which model implementation to use for this stage. The class must be registered in the model registry for vLLM-Omni to locate and instantiate it.
-
-#### `engine_args.worker_cls`
-
-The specific worker class to use for this stage. This determines how the model computations are executed. Examples include `vllm_omni.worker.gpu_ar_worker.GPUARWorker` for autoregressive stages and `vllm_omni.worker.gpu_generation_worker.GPUGenerationWorker` for diffusion-based stages.
-
-#### `engine_args.scheduler_cls`
-
-The scheduler class to use for this stage. The scheduler manages request queuing, batching, and execution order. Examples include `vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler` for standard stages and `vllm_omni.core.sched.omni_generation_scheduler.OmniGenerationScheduler` for diffusion stages.
-
-#### `engine_args.gpu_memory_utilization`
-
-The fraction of GPU memory to allocate for this stage within a single GPU chip. This is a value between 0.0 and 1.0, where 0.8 means 80% of the GPU memory will be used by this stage. This allows fine-grained control over memory allocation when multiple stages share the same GPU or when reserving memory for other operations.
-
-Default: `0.8`
-
-!!! tip "Memory Configuration Guide"
-    For detailed information on how to calculate memory requirements and properly configure `gpu_memory_utilization`, see the [GPU Memory Calculation and Configuration Guide](./gpu_memory_utilization.md).
-
-#### `engine_args.enforce_eager`
-
-Whether to enforce eager execution mode. When set to `true`, the engine will run in eager mode without using CUDA graphs or other compilation optimizations. Currently, vLLM-Omni only supports eager mode.
-
-Default: `true`
-
-#### `engine_args.trust_remote_code`
-
-Whether to trust remote code when loading models from Hugging Face. This is required for models that use custom code in their configuration files. Set to `true` when loading models that require custom model implementations.
-
-Default: `true`
-
-#### `engine_args.engine_output_type`
-
-Specifies the type of output produced by this stage's engine. This determines what kind of data flows to downstream stages. Possible values include `latent` (hidden states), `text` (tokenized text), and `audio` (audio waveforms). When set to `latent`, the stage outputs latent hidden states in addition to token IDs, which are consumed by downstream stages.
-
-Default: `latent`
-
-#### `engine_args.enable_prefix_caching`
-
-Whether to enable prefix caching for this stage. Prefix caching can improve performance by caching KV cache for common prompt prefixes. However, for requests that output hidden states (when `engine_output_type` is `latent`), prefix caching is not currently supported and should be set to `false`.
-
-Default: `false`
-
-### `is_comprehension`
-
-Whether this stage is a text or multimodal comprehension module. When set to `true`, the stage acts as a comprehension module that processes input text or multimodal content. If this is the first comprehension stage, `AsyncOmni` will use its tokenizer as the default tokenizer for the entire pipeline.
-
-Default: `true`
-
-### `final_output`
-
-Whether this stage produces output that is part of the final outputs returned to the user. When set to `false`, the stage only works as an intermediate stage, processing data that flows to downstream stages but not contributing directly to the final response.
-
-Default: `true`
-
-### `final_output_type`
-
-The type of final output produced by this stage. This specifies what format the output will be in when returned to the user. Currently supported values are `text` (for text generation) and `audio` (for audio generation).
-
-Default: `text`
-
-### `default_sampling_params`
-
-Default sampling parameters for this stage. These parameters control the generation behavior and align with vLLM's sampling parameter semantics. These defaults are used when no explicit sampling parameters are provided in the request.
-
-#### `default_sampling_params.temperature`
-
-Sampling temperature for controlling randomness. Lower values (e.g., 0.0) make the output more deterministic and focused, while higher values increase randomness.
-
-Default: `0.0`
-
-#### `default_sampling_params.top_p`
-
-Nucleus sampling parameter. Only tokens with cumulative probability mass up to `top_p` are considered. This helps filter out low-probability tokens while maintaining diversity.
-
-Default: `1.0`
-
-#### `default_sampling_params.top_k`
-
-Top-k sampling parameter. Only the top `k` most likely tokens are considered. Set to `-1` to disable top-k filtering and consider all tokens.
-
-Default: `-1`
-
-#### `default_sampling_params.max_tokens`
-
-Maximum number of tokens to generate in this stage. This limits the length of the output sequence.
-
-Default: `2048`
-
-#### `default_sampling_params.seed`
-
-Random seed for reproducible generation. When set, the random number generator will be initialized with this seed to ensure consistent outputs across runs.
-
-Default: `42`
-
-#### `default_sampling_params.detokenize`
-
-Whether to detokenize the output tokens into text. When set to `true`, token IDs are converted back to readable text strings.
-
-Default: `True`
-
-#### `default_sampling_params.repetition_penalty`
-
-Penalty applied to tokens that have already appeared in the generated sequence. Values greater than 1.0 discourage repetition, while values less than 1.0 encourage it. A value of 1.0 applies no penalty.
-
-Default: `1.1`
-
-### `tts_args` (TTS stages only)
-
-Configuration for Text-to-Speech specific parameters. This section is only applicable to TTS model stages (e.g., `qwen3_tts`).
-
-#### `tts_args.max_instructions_length`
-
-Maximum character length for voice style/emotion instructions. Instructions exceeding this limit will be rejected with a validation error.
-
-Default: `500`
-
-This value can be overridden at runtime using the `--tts-max-instructions-length` CLI parameter when starting the server.

docs/contributing/DOCS_GUIDE.md

@@ -46,7 +46,7 @@ class Omni:
 
     Args:
         model: Model name or path
-        stage_configs: Optional stage configurations
+        deploy_config: Optional path to a deploy configuration
         **kwargs: Additional arguments passed to the engine
 
     Example:

docs/contributing/ci/test_examples/l4_performance_tests.inc.md

@@ -31,7 +31,7 @@ Pass **`--test-config-file`** to run one JSON file as-is, or omit it for the bul
     ],
     "server_params": {
         "model": "Qwen/Qwen3-Omni-30B-A3B-Instruct",
-        "stage_config_name": "qwen3_omni.yaml"
+        "stage_config_name": "qwen3_omni_moe.yaml"
     },
     "benchmark_params": [
         {
@@ -155,7 +155,7 @@ See also [Markers for Tests](#markers-for-tests) for registered hardware markers
 | Parameter         | Required | Example                            | Description                   |
 | ----------------- | -------- | ---------------------------------- | ----------------------------- |
 | model             | Yes      | "Qwen/Qwen3-Omni-30B-A3B-Instruct" | Model name or path            |
-| stage_config_name | Yes      | "qwen3_omni.yaml"                  | Stage configuration file name |
+| stage_config_name | Yes      | "qwen3_omni_moe.yaml"              | Deploy configuration file name |
 
 *Dynamic Configuration (update/delete)*
 
@@ -171,15 +171,15 @@ Supports incremental modifications based on the basic configuration:
 ```
 "update": {
     "async_chunk": true,  // Enable asynchronous chunk processing
-    "stage_args": {
+    "stages": {
         "0": {
-            "engine_args.custom_process_next_stage_input_func": "vllm_omni.model_executor.stage_input_processors.qwen3_omni.thinker2talker_async_chunk"
+            "max_num_seqs": 64
         }
     }
 },
 "delete": {
-    "stage_args": {
-        "2": ["custom_process_input_func"]  // Delete this configuration for stage 2
+    "stages": {
+        "2": ["max_num_batched_tokens"]  // Delete this deploy override for stage 2
     }
 }
 ```

docs/contributing/ci/test_writing_guide.md

@@ -17,7 +17,7 @@ Summary:
 - **Reliability:** `tests/dfx/reliability/`
 - Do **not** add new top-level `tests/` directories unrelated to a component (or to `e2e` / `dfx` / `helpers` / `examples` / `buildkite`)
 
-Deploy YAMLs: `vllm_omni/deploy/` via `tests.helpers.stage_config.get_deploy_config_path` (see [stage configs](../../configuration/stage_configs.md)).
+Deploy YAMLs: `vllm_omni/deploy/` via `tests.helpers.stage_config.get_deploy_config_path` (see [pipeline and deploy configs](../../configuration/stage_configs.md)).
 
 ## Markers for Tests
 
@@ -581,7 +581,7 @@ When you want to add L5-level stability test cases, add or extend the appropriat
     "test_name": "test_qwen3_omni_stability",
     "server_params": {
         "model": "Qwen/Qwen3-Omni-30B-A3B-Instruct",
-        "stage_config_name": "qwen3_omni.yaml"
+        "stage_config_name": "qwen3_omni_moe.yaml"
     },
     "benchmark_params": [
         {
@@ -607,7 +607,7 @@ When you want to add L5-level stability test cases, add or extend the appropriat
 | Field            | Required | Description                                                                 |
 | ---------------- | -------- | --------------------------------------------------------------------------- |
 | test_name        | Yes      | Unique identifier for the stability test case                               |
-| server_params    | Yes      | Server-side configuration parameters (model, stage configuration, etc.)     |
+| server_params    | Yes      | Server-side configuration parameters (model, deploy configuration, etc.)    |
 | benchmark_params | Yes      | Stability benchmark running parameters (supports multiple configurations)   |
 
 ##### server_params Configuration
@@ -617,7 +617,7 @@ When you want to add L5-level stability test cases, add or extend the appropriat
 | Parameter         | Required | Example                            | Description                         |
 | ----------------- | -------- | ---------------------------------- | ----------------------------------- |
 | model             | Yes      | "Qwen/Qwen3-Omni-30B-A3B-Instruct" | Model name or path                  |
-| stage_config_name | Yes      | "qwen3_omni.yaml"                  | Stage configuration file name       |
+| stage_config_name | Yes      | "qwen3_omni_moe.yaml"              | Deploy configuration file name      |
 
 ###### Dynamic Configuration (update/delete)
 
@@ -697,8 +697,8 @@ pytest -s -v tests/dfx/reliability/test_reliability_hunyuan_image.py -m slow
 ##### Adding a new model suite
 
 1. Add `test_reliability_<model>.py` under `tests/dfx/reliability/`.
-2. Define **`RELIABILITY_SCENARIOS`** and pass them through **`create_reliability_omni_server_params()`** with the correct deploy or e2e stage-config directory (same pattern as existing files).
-3. Reuse **`helpers`** for OOM / kill / raw HTTP; prefer **`assert_fault_exception()`** and **`resolve_oom_device_spec()`** from `tests/dfx/conftest.py` for consistent device selection vs stage YAML.
+2. Define **`RELIABILITY_SCENARIOS`** and pass them through **`create_reliability_omni_server_params()`** with the correct deploy or e2e deploy-config directory (same pattern as existing files).
+3. Reuse **`helpers`** for OOM / kill / raw HTTP; prefer **`assert_fault_exception()`** and **`resolve_oom_device_spec()`** from `tests/dfx/conftest.py` for consistent device selection vs deploy YAML.
 4. Register **`slow`** (and **`hardware_test`** if needed); extend **`.buildkite/cuda/test-weekly.yml`** when the suite should run in weekly L5.
 
 </details>

docs/contributing/model/adding_omni_model.md

@@ -9,7 +9,7 @@ This guide walks through the process of adding a new multi-stage model to vLLM-O
 3. [Step-by-Step Implementation](#step-by-step-implementation)
 4. [Key Components](#key-components)
 5. [Model Registration](#model-registration)
-6. [Stage Configuration](#stage-configuration)
+6. [Pipeline and Deploy Configuration](#pipeline-and-deploy-configuration)
 7. [Stage Input Processors](#stage-input-processors)
 8. [Testing](#testing)
 9. [Adding a Model Recipe](#adding-a-model-recipe)
@@ -316,18 +316,28 @@ _OMNI_MODELS = {
 
 The registry uses lazy loading, so the model class is imported only when needed.
 
-## Stage Configuration
+## Pipeline and Deploy Configuration
 
-Create a YAML configuration file in `vllm_omni/deploy/`. For a complete example, see the [Qwen3-Omni configuration file](gh-file:vllm_omni/deploy/qwen3_omni_moe.yaml).
+Define fixed topology in `vllm_omni/model_executor/models/<model>/pipeline.py`
+with `PipelineConfig` and `StagePipelineConfig`, then register it in
+`vllm_omni/config/pipeline_registry.py`. For a complete example, see the
+[Qwen3-Omni pipeline](gh-file:vllm_omni/model_executor/models/qwen3_omni/pipeline.py).
 
-### Key Configuration Fields
+### Pipeline topology fields
 
-- **`model_stage`**: Which stage to run ("thinker", "talker", "code2wav", etc.)
-- **`model_arch`**: The model architecture name (must match registry)
-- **`engine_input_source`**: List of stage IDs that provide input to this stage
-- **`custom_process_input_func`**: Function to process inputs from previous stages
-- **`final_output`**: Whether this stage produces the final output (True/False)
-- **`final_output_type`**: Type of final output ("text", "audio", "image", etc.)
+- **`model_stage`**: Logical stage name ("thinker", "talker", "code2wav", etc.)
+- **`execution_type`**: Runtime family (`LLM_AR`, `LLM_GENERATION`, or `DIFFUSION`)
+- **`model_arch`**: Stage architecture name, when different from the pipeline default
+- **`input_sources`**: Upstream stage IDs that provide input to this stage
+- **`custom_process_input_func`**: Function that processes inputs from previous stages
+- **`final_output`**: Whether this stage produces user-facing output
+- **`final_output_type`**: Output modality ("text", "audio", "image", etc.)
+- **`owns_tokenizer`**: Whether this stage owns the pipeline tokenizer
+
+Create the matching runtime defaults in `vllm_omni/deploy/<model>.yaml` and set
+`PipelineConfig.default_deploy_config_name` to that file. The deploy YAML owns
+GPU placement, memory sizing, parallelism, connectors, and sampling defaults;
+it must not redefine topology fields.
 
 ## Stage Input Processors
 
@@ -374,7 +384,7 @@ The stage transition process follows these steps:
 
 2. **Transition Detection**: The orchestrator checks if there's a next stage and calls `process_engine_inputs()` on it
 
-3. **Input Processing**: The stage input processor configured in stage YAML (under `vllm_omni/model_executor/stage_input_processors/`) handles the transition:
+3. **Input Processing**: The stage input processor registered by the pipeline (implemented under `vllm_omni/model_executor/stage_input_processors/`) handles the transition:
    ```python
    def process_engine_inputs(
        self, stage_list: list[Any], prompt: OmniTokensPrompt | TextPrompt = None
@@ -577,7 +587,7 @@ Adding a new model to vLLM-Omni involves:
 1. **Create model directory structure** with stage implementations
 2. **Implement unified model class** that orchestrates stages
 3. **Register model** in `registry.py`
-4. **Create stage configuration** YAML file
+4. **Define pipeline topology and deploy defaults** in `pipeline.py` and `vllm_omni/deploy/`
 5. **Implement stage input processors** for stage transitions
 6. **Write tests** to verify functionality
 7. **Add model recipe** to the [vllm-project/recipes](https://github.com/vllm-project/recipes) repository (see [Adding a Model Recipe](#adding-a-model-recipe) section)
@@ -590,7 +600,8 @@ For a complete reference implementation, see:
 - **Thinker**: `vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_thinker.py`
 - **Talker**: `vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_talker.py`
 - **Code2Wav**: `vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_code2wav.py`
-- **Stage config**: `vllm_omni/deploy/qwen3_omni_moe.yaml`
+- **Pipeline topology**: `vllm_omni/model_executor/models/qwen3_omni/pipeline.py`
+- **Deploy config**: `vllm_omni/deploy/qwen3_omni_moe.yaml`
 - **Input processors**: `vllm_omni/model_executor/stage_input_processors/qwen3_omni.py`
 - **Registry**: `vllm_omni/model_executor/models/registry.py`
 - **Testing**: `vllm_omni/tests/e2e/offline_inference/test_qwen3_omni.py`
@@ -598,4 +609,4 @@ For a complete reference implementation, see:
 For more information, see:
 - [Architecture Overview](../../design/architecture_overview.md)
 - [Supported Models](../../models/supported_models.md)
-- [Stage Configuration Guide](../../configuration/stage_configs.md)
+- [Pipeline and Deploy Configuration Guide](../../configuration/stage_configs.md)

docs/contributing/model/adding_tts_model.md

@@ -20,7 +20,7 @@ pattern, refer to MOSS-TTS-Nano.
 4. [Step-by-Step Implementation](#step-by-step-implementation)
 5. [Key Components](#key-components)
 6. [Model Registration](#model-registration)
-7. [Stage Configuration](#stage-configuration)
+7. [Pipeline and Deploy Configuration](#pipeline-and-deploy-configuration)
 8. [Stage Input Processors](#stage-input-processors)
 9. [Online Serving Integration](#online-serving-integration)
 10. [Single-Stage Models](#single-stage-models)
@@ -427,112 +427,93 @@ _OMNI_MODELS = {
 
 The registry uses lazy loading - model classes are only imported when needed.
 
-## Stage Configuration
+## Pipeline and Deploy Configuration
 
-Each stage has a `worker_type` that determines how it is scheduled:
+Define fixed topology in `models/<model>/pipeline.py`. The execution type
+selects the scheduler and worker family:
 
-- `worker_type: ar` - autoregressive stage, uses `OmniARScheduler` with PagedAttention
-- `worker_type: generation` - non-AR stage (e.g. decoder), uses `OmniGenerationScheduler`
+- `StageExecutionType.LLM_AR` uses the autoregressive runtime with PagedAttention.
+- `StageExecutionType.LLM_GENERATION` uses the generation runtime for stages such as audio decoders.
 
-Key configuration fields:
+Key topology fields belong to `StagePipelineConfig`:
 
 | Field | Description |
 |-------|-------------|
-| `model_stage` | Which stage to initialize (`ar_stage`, `decoder`, etc.) |
-| `model_arch` | Architecture name, must match `registry.py` |
-| `engine_input_source` | List of upstream stage IDs that provide input (e.g. `[0]`) |
-| `engine_output_type` | Output type: `latent` for intermediate, `audio` for final |
-| `custom_process_next_stage_input_func` | Async chunk processor function path (streaming only) |
-| `final_output` | Whether this stage produces the final user-facing output |
-| `final_output_type` | Type of final output (`audio`, `text`, etc.) |
+| `model_stage` | Logical stage name (`ar_stage`, `decoder`, etc.). |
+| `execution_type` | Runtime family for this stage. |
+| `input_sources` | Upstream stage IDs that provide input. |
+| `model_arch` | Stage-specific architecture name, when it differs from the pipeline default. |
+| `engine_output_type` | Output representation such as `latent` or `audio`. |
+| `custom_process_next_stage_input_func` | Processor for full-payload stage handoff. |
+| `async_chunk_process_next_stage_input_func` | Processor for streaming chunk handoff. |
+| `final_output` / `final_output_type` | Whether this stage produces user-facing output and its modality. |
+| `owns_tokenizer` | Whether this stage supplies the pipeline tokenizer. |
 
-!!! note
-    New in-tree models should define frozen topology in `models/<model>/pipeline.py`,
-    register it in `vllm_omni/config/pipeline_registry.py`, and put deployment
-    knobs in `vllm_omni/deploy/<model>.yaml`. Use `--deploy-config` to load a
-    custom deployment YAML.
+For example, a two-stage TTS topology can be defined as:
 
-### Batch mode
+```python
+from vllm_omni.config.stage_config import (
+    PipelineConfig,
+    StageExecutionType,
+    StagePipelineConfig,
+)
 
-```yaml
-# stage_configs/your_model_name.yaml
+_PROC = "vllm_omni.model_executor.stage_input_processors.your_model_name"
 
-stage_args:
-  - stage_id: 0
-    stage_type: llm
-    runtime:
-      devices: "0"
-    engine_args:
-      model_stage: ar_stage
-      max_num_seqs: 64
-      model_arch: YourTTSModelForConditionalGeneration
-      worker_type: ar
-      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler
-      engine_output_type: latent
-    default_sampling_params:
-      temperature: 0.9
-      top_k: 50
-      max_tokens: 2048
-
-  - stage_id: 1
-    stage_type: llm
-    runtime:
-      devices: "0"
-    engine_args:
-      model_stage: decoder
-      model_arch: YourTTSModelForConditionalGeneration
-      worker_type: generation
-      scheduler_cls: vllm_omni.core.sched.omni_generation_scheduler.OmniGenerationScheduler
-      engine_output_type: audio
-    engine_input_source: [0]
-    final_output: true
-    final_output_type: audio
+YOUR_TTS_PIPELINE = PipelineConfig(
+    model_type="your_model_name",
+    default_deploy_config_name="your_model_name.yaml",
+    model_arch="YourTTSModelForConditionalGeneration",
+    stages=(
+        StagePipelineConfig(
+            stage_id=0,
+            model_stage="ar_stage",
+            execution_type=StageExecutionType.LLM_AR,
+            input_sources=(),
+            owns_tokenizer=True,
+            engine_output_type="latent",
+            custom_process_next_stage_input_func=f"{_PROC}.ar2decoder",
+            async_chunk_process_next_stage_input_func=f"{_PROC}.ar2decoder_async_chunk",
+        ),
+        StagePipelineConfig(
+            stage_id=1,
+            model_stage="decoder",
+            execution_type=StageExecutionType.LLM_GENERATION,
+            input_sources=(0,),
+            model_arch="YourTTSDecoder",
+            engine_output_type="audio",
+            final_output=True,
+            final_output_type="audio",
+        ),
+    ),
+)
 ```
 
-### Streaming mode (async_chunk)
-
-Add `async_chunk: true` at the top level and specify `custom_process_next_stage_input_func`
-on Stage 0 to define how intermediate outputs are chunked and forwarded:
+Register the pipeline in `vllm_omni/config/pipeline_registry.py`. Runtime
+placement and sizing belong in `vllm_omni/deploy/your_model_name.yaml`:
 
 ```yaml
-# stage_configs/your_model_name_async_chunk.yaml
-
 async_chunk: true
 
-stage_args:
+stages:
   - stage_id: 0
-    stage_type: llm
-    runtime:
-      devices: "0"
-    engine_args:
-      model_stage: ar_stage
-      max_num_seqs: 64
-      model_arch: YourTTSModelForConditionalGeneration
-      worker_type: ar
-      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler
-      engine_output_type: latent
-      custom_process_next_stage_input_func: >
-        vllm_omni.model_executor.stage_input_processors.your_model_name.ar2decoder_async_chunk
+    devices: "0"
+    max_num_seqs: 64
     default_sampling_params:
       temperature: 0.9
       top_k: 50
       max_tokens: 2048
 
   - stage_id: 1
-    stage_type: llm
-    runtime:
-      devices: "0"
-    engine_args:
-      model_stage: decoder
-      model_arch: YourTTSModelForConditionalGeneration
-      worker_type: generation
-      scheduler_cls: vllm_omni.core.sched.omni_generation_scheduler.OmniGenerationScheduler
-      engine_output_type: audio
-    engine_input_source: [0]
-    final_output: true
-    final_output_type: audio
+    devices: "0"
+    max_num_seqs: 1
 ```
 
+Set `async_chunk: false` for end-to-end handoff. The registered pipeline
+selects the full-payload or async chunk processor; processor paths and topology
+must not be moved into the deploy YAML. Use `--deploy-config` to load a custom
+deployment overlay.
+
 ## Stage Input Processors
 
 Stage input processors convert Stage 0 outputs into Stage 1 inputs. Create yours in
@@ -832,32 +813,40 @@ vllm_omni/deploy/your_model_name.yaml
 
 No stage input processor is needed.
 
-### Stage config
+### Pipeline and deploy config
 
-Use a single stage with `worker_type: ar`. The `is_comprehension: true` field and the
-top-level `async_chunk: false` are required — omitting them causes silent
-misclassification in the serving layer. Set `max_num_seqs` to at least 4 for
-concurrent production use.
+Use a single `LLM_AR` stage that owns the tokenizer and produces final audio:
+
+```python
+YOUR_TTS_PIPELINE = PipelineConfig(
+    model_type="your_model_name",
+    default_deploy_config_name="your_model_name.yaml",
+    model_arch="YourModelForCausalLM",
+    stages=(
+        StagePipelineConfig(
+            stage_id=0,
+            model_stage="your_model_stage_key",
+            execution_type=StageExecutionType.LLM_AR,
+            input_sources=(),
+            owns_tokenizer=True,
+            engine_output_type="audio",
+            final_output=True,
+            final_output_type="audio",
+        ),
+    ),
+)
+```
+
+The deploy YAML controls runtime behavior. Set `max_num_seqs` to at least 4
+for concurrent production use:
 
 ```yaml
-# stage_configs/your_model_name.yaml
 async_chunk: false
 
-stage_args:
+stages:
   - stage_id: 0
-    stage_type: llm
-    is_comprehension: true          # required for serving_speech.py dispatch
-    runtime:
-      devices: "0"
-    engine_args:
-      model_stage: your_model_stage_key
-      model_arch: YourModelForCausalLM
-      worker_type: ar
-      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler
-      engine_output_type: audio
-      max_num_seqs: 4               # min 4 for concurrent requests; default 1 causes gaps
-    final_output: true
-    final_output_type: audio
+    devices: "0"
+    max_num_seqs: 4
 ```
 
 ### Generator-based streaming pattern
@@ -1031,4 +1020,4 @@ For more information, see:
 
 - [Architecture Overview](../../design/architecture_overview.md)
 - [Async Chunk Design](../../design/feature/async_chunk.md)
-- [Stage Configuration Guide](../../configuration/stage_configs.md)
+- [Pipeline and Deploy Configuration Guide](../../configuration/stage_configs.md)

docs/design/architecture_overview.md

@@ -335,8 +335,8 @@ The single resolution boundary is implemented by
 `StageConfigFactory.create_from_model()` and
 `VllmOmniConfig.from_pipeline_config()` in
 [`vllm_omni/config`](https://github.com/vllm-project/vllm-omni/tree/main/vllm_omni/config).
-The legacy `stage_args` YAML path remains only for models that have not yet
-migrated to `PipelineConfig` and `DeployConfig`.
+The legacy `stage_args` YAML path has been removed. Model topology now resolves
+through `PipelineConfig`, with runtime overrides supplied by `DeployConfig`.
 
 In the typed path, each stage configuration derives from
 `BaseVllmOmniStageConfig` and is specialized as

docs/design/feature/async_chunk.md

@@ -211,38 +211,39 @@ In sequential mode, each stage must wait for the previous stage to complete enti
 
 ## Configuration
 
-Enable async_chunk in stage configuration YAML:
+Enable async chunk mode in the deploy YAML:
 
 ```yaml
 async_chunk: true
-stage_args:
-  - stage_id: 0
-    engine_args:
-      custom_process_next_stage_input_func: vllm_omni.model_executor.stage_input_processors.qwen3_omni.thinker2talker_async_chunk
-  - stage_id: 1
-    engine_args:
-      custom_process_next_stage_input_func: vllm_omni.model_executor.stage_input_processors.qwen3_omni.talker2code2wav_async_chunk
 ```
 
-### Stage Configuration
+The registered `PipelineConfig` owns the async handoff processor functions.
+For Qwen3-Omni these are `thinker2talker_async_chunk` and
+`talker2code2wav_async_chunk`; deploy YAML only selects the mode and runtime
+sizing.
+
+### Configuration ownership
 
 - `async_chunk: bool`: Enable/disable async chunk mode
-- `custom_process_next_stage_input_func: str`: Path to custom chunk processing function; receives `(transfer_manager, pooling_output, request)`. For qwen3-omni: `thinker2talker_async_chunk`, `talker2code2wav_async_chunk`
-- `stage_connector_config: dict`: Connector configuration
-- `worker_type: str`: Model type, e.g. `"ar"` or `"generation"` (used by OmniChunkTransferAdapter for mode-specific payload handling)
+- `async_chunk_process_next_stage_input_func: str`: Pipeline-owned chunk processor path
+- `execution_type: StageExecutionType`: Pipeline-owned runtime family
+- `connectors: dict`: Deploy-owned connector definitions
 - `max_num_seqs: int`: Maximum number of sequences for concurrent processing in the stage
 
-
 ### Connector Configuration
 
 ```yaml
 connectors:
-  - from_stage: 0
-    to_stage: 1
-    spec:
-      name: SharedMemoryConnector
-      extra:
-        stage_id: 0
+  connector_of_shared_memory:
+    name: SharedMemoryConnector
+
+stages:
+  - stage_id: 0
+    output_connectors:
+      to_stage_1: connector_of_shared_memory
+  - stage_id: 1
+    input_connectors:
+      from_stage_0: connector_of_shared_memory
 ```
 
 ### Code2Wav Batch Configuration
@@ -250,13 +251,10 @@ connectors:
 For optimal performance with async_chunk, the code2wav stage should be configured with batching:
 
 ```yaml
-stage_args:
+stages:
   - stage_id: 2  # code2wav stage
-    runtime:
-      devices: "1"
-    engine_args:
-      model_stage: code2wav
-      max_num_seqs: 64  # Enables batched audio generation
+    devices: "1"
+    max_num_seqs: 64  # Enables batched audio generation
 ```
 
 ## Related Files

docs/design/feature/disaggregated_inference.md

@@ -59,19 +59,18 @@ This `metadata` must be passed through the control plane so `get()` can locate t
 
 ## Configuration Model
 
-Define connectors in runtime:
+Define connectors at the top level of the deploy YAML:
 
 ```yaml
-runtime:
-  connectors:
-    connector_of_shared_memory:
-      name: SharedMemoryConnector
+connectors:
+  connector_of_shared_memory:
+    name: SharedMemoryConnector
 ```
 
 Wire stages to connectors:
 
 ```yaml
-stage_args:
+stages:
   - stage_id: 0
     output_connectors:
       to_stage_1: connector_of_shared_memory

docs/design/feature/omni_connectors/mooncake_store_connector.md

@@ -32,26 +32,25 @@ mooncake_master \
 
 ## Configuration
 
-Define the connector in runtime:
+Define the connector at the top level of the deploy YAML:
 
 ```yaml
-runtime:
-  connectors:
-    connector_of_mooncake:
-      name: MooncakeStoreConnector
-      extra:
-        host: "127.0.0.1"
-        metadata_server: "http://<MASTER_IP>:8080/metadata"
-        master: "<MASTER_IP>:50051"
-        segment: 512000000
-        localbuf: 64000000
-        proto: "tcp"
+connectors:
+  connector_of_mooncake:
+    name: MooncakeStoreConnector
+    extra:
+      host: "127.0.0.1"
+      metadata_server: "http://<MASTER_IP>:8080/metadata"
+      master: "<MASTER_IP>:50051"
+      segment: 512000000
+      localbuf: 64000000
+      proto: "tcp"
 ```
 
 Wire stages to the connector:
 
 ```yaml
-stage_args:
+stages:
   - stage_id: 0
     output_connectors:
       to_stage_1: connector_of_mooncake

docs/design/feature/omni_connectors/mooncake_transfer_engine_connector.md

@@ -21,26 +21,25 @@ InfiniBand/RoCE NICs).
 
 ## Configuration
 
-Define the connector in runtime:
+Define the connector at the top level of the deploy YAML:
 
 ```yaml
-runtime:
-  connectors:
-    rdma_connector:
-      name: MooncakeTransferEngineConnector
-      extra:
-        host: "auto"                  # Auto-detect local RDMA IP
-        zmq_port: 50051               # ZMQ base port (see "Port Offset Scheme" below)
-        protocol: "rdma"              # "rdma" or "tcp"
-        device_name: ""               # RDMA device (e.g., "mlx5_0"), empty for auto-detect
-        memory_pool_size: 4294967296  # 4 GB (CPU); use 2147483648 (2 GB) for GPU
-        memory_pool_device: "cpu"     # "cpu" for pinned memory (recommended), "cuda" for GPUDirect RDMA
+connectors:
+  rdma_connector:
+    name: MooncakeTransferEngineConnector
+    extra:
+      host: "auto"                  # Auto-detect local RDMA IP
+      zmq_port: 50051               # ZMQ base port (see "Port Offset Scheme" below)
+      protocol: "rdma"              # "rdma" or "tcp"
+      device_name: ""               # RDMA device (e.g., "mlx5_0"), empty for auto-detect
+      memory_pool_size: 4294967296  # 4 GB (CPU); use 2147483648 (2 GB) for GPU
+      memory_pool_device: "cpu"     # "cpu" for pinned memory (recommended), "cuda" for GPUDirect RDMA
 ```
 
 Wire stages to the connector:
 
 ```yaml
-stage_args:
+stages:
   - stage_id: 0
     output_connectors:
       to_stage_1: rdma_connector
@@ -415,7 +414,7 @@ A receiver connector:
 - allocates receive buffers from its own pool
 - requests metadata or transfer service from the sender
 
-The role is not inferred dynamically. It is injected by the stage configuration layer:
+The role is not inferred dynamically. It is injected from the deploy connector wiring:
 
 - incoming edge for a stage -> `role="receiver"`
 - outgoing edge for a stage -> `role="sender"`

docs/design/feature/omni_connectors/shared_memory_connector.md

@@ -13,10 +13,9 @@ segment name is returned in metadata.
 ## Configuration
 
 ```yaml
-runtime:
-  connectors:
-    connector_of_shared_memory:
-      name: SharedMemoryConnector
+connectors:
+  connector_of_shared_memory:
+    name: SharedMemoryConnector
 ```
 
 ## Notes

docs/design/feature/omni_connectors/yuanrong_connector.md

@@ -65,23 +65,22 @@ dscli stop --worker_address "${WORKER_IP}:31501"
 
 ## Configuration
 
-Define the connector in runtime:
+Define the connector at the top level of the deploy YAML:
 
 ```yaml
-runtime:
-  connectors:
-    connector_of_yuanrong:
-      name: YuanrongConnector
-      extra:
-        host: "127.0.0.1"
-        port: 31501
-        get_sub_timeout_ms: 1000
+connectors:
+  connector_of_yuanrong:
+    name: YuanrongConnector
+    extra:
+      host: "127.0.0.1"
+      port: 31501
+      get_sub_timeout_ms: 1000
 ```
 
 Wire stages to the connector:
 
 ```yaml
-stage_args:
+stages:
   - stage_id: 0
     output_connectors:
       to_stage_1: connector_of_yuanrong

docs/design/feature/omni_connectors/yuanrong_transfer_engine_connector.md

@@ -94,26 +94,23 @@ For Ascend P2P, configure the connector with `protocol: "ascend"` and an NPU
 memory pool:
 
 ```yaml
-runtime:
-  enabled: true
-  defaults:
+connectors:
+  yuanrong_te_connector:
+    name: YuanrongTransferEngineConnector
+    extra:
+      host: "auto"
+      zmq_port: 50051
+      rpc_port: "auto"
+      protocol: "ascend"
+      device_name: "auto"
+      memory_pool_size: 1073741824
+      memory_pool_device: "npu"
+
+edges:
+  - from: 0
+    to: 1
     window_size: -1
     max_inflight: 1
-  connectors:
-    yuanrong_te_connector:
-      name: YuanrongTransferEngineConnector
-      extra:
-        host: "auto"
-        zmq_port: 50051
-        rpc_port: "auto"
-        protocol: "ascend"
-        device_name: "auto"
-        memory_pool_size: 1073741824
-        memory_pool_device: "npu"
-  edges:
-    - from: 0
-      to: 1
-      window_size: -1
 ```
 
 Important fields:
@@ -141,31 +138,27 @@ For AR 4-way TP sending KV cache to DiT 4-way TP, set the stage TP topology in
 both stage `omni_kv_config` blocks:
 
 ```yaml
-stage_args:
+stages:
   - stage_id: 0
-    runtime:
-      devices: "0,1,2,3"
-    engine_args:
-      tensor_parallel_size: 4
-      omni_kv_config:
-        need_send_cache: true
-        rank_mapping:
-          from_tp: 4
-          to_tp: 4
+    devices: "0,1,2,3"
+    tensor_parallel_size: 4
+    omni_kv_config:
+      need_send_cache: true
+      rank_mapping:
+        from_tp: 4
+        to_tp: 4
     output_connectors:
       to_stage_1: yuanrong_te_connector
 
   - stage_id: 1
-    runtime:
-      devices: "4,5,6,7"
-    engine_args:
-      parallel_config:
-        tensor_parallel_size: 4
-      omni_kv_config:
-        need_recv_cache: true
-        rank_mapping:
-          from_tp: 4
-          to_tp: 4
+    devices: "4,5,6,7"
+    parallel_config:
+      tensor_parallel_size: 4
+    omni_kv_config:
+      need_recv_cache: true
+      rank_mapping:
+        from_tp: 4
+        to_tp: 4
     input_connectors:
       from_stage_0: yuanrong_te_connector
 ```

docs/design/feature/prefix_caching.md

@@ -41,7 +41,7 @@ With this in mind, consider the set of blocks in a 2D layout, where the row repr
 
 ### Example
 !!! note "Note 3"
-    Prefix caching in vLLM-Omni currently is only supported on AutoRegressive stages with one kv-cache group. It can be enabled/disabled per-stage via the `enable_prefix_caching` parameter in the model's stage config.
+    Prefix caching in vLLM-Omni currently is only supported on AutoRegressive stages with one kv-cache group. Configure it with the pipeline-wide `enable_prefix_caching` field in the deploy config.
 
 The way in which vLLM-Omni ties into vLLM's prefix caching is best understood by example. Say that we have the following:
 

docs/design/module/model_integration.md

@@ -42,7 +42,7 @@ and execution behavior to stable runtime contracts.
 ### MODEL-INV-001: Registration is explicit
 
 **Rule:** A model integration MUST declare how its model class, loader, input
-processor, and stage configuration are selected.
+processor, and pipeline configuration are selected.
 
 ### MODEL-INV-002: Model code does not route stages
 

docs/design/module/vllm_omni_config.md

@@ -10,9 +10,8 @@ owners:
 primary_code_paths:
   - vllm_omni/config/**
   - vllm_omni/deploy/**
-  - vllm_omni/model_executor/stage_configs/**
-related_code_paths:
-  - vllm_omni/platforms/*/stage_configs/**
+  - vllm_omni/model_executor/models/*/pipeline.py
+related_code_paths: []
 depends_on: []
 validation_paths:
   - tests/config/**
@@ -95,7 +94,7 @@ parallel input is effective for a diffusion stage.
 ## Safe-change guide while deferred
 
 Changes should trace every affected producer to its runtime consumer and test
-the structured, legacy, CLI, and deployment paths that are actually supported.
+the structured pipeline, CLI, and deployment paths that are actually supported.
 For inherited vLLM fields, tests should separately cover constructor behavior
 and effective `EngineArgs` projection. Do not infer a stable contract from
 this placeholder page.

docs/design/qwen3_omni_tts_performance_optimization.md

@@ -111,7 +111,7 @@ This post walks through each optimization in the same order they are typically e
 
 For both Qwen3-Omni and Qwen3-TTS, batching is a pipeline-level optimization:
 
-- Requests are grouped per stage using `runtime.max_batch_size`
+- Requests are grouped per stage using `stages[].max_num_seqs`
 - Each stage executes batch inference with its own scheduler/worker
 - Stage outputs are routed to downstream stages with per-request mapping preserved
 
@@ -171,7 +171,7 @@ At concurrency 10, batching alone brings Qwen3-TTS RTF from 2.19 (slower than re
 
 In decode-heavy serving, repeatedly launching many small kernels from CPU can become a visible overhead. CUDA Graph reduces this overhead by capturing and replaying stable execution graphs.
 
-In stage configs, this is represented by `enforce_eager: false` for stages where graph capture is desired (Thinker/Talker), while Code2Wav keeps eager mode depending on stage behavior.
+In deploy configs, this is represented by `enforce_eager: false` for stages where graph capture is desired (Thinker/Talker), while Code2Wav keeps eager mode depending on stage behavior.
 
 ### CUDA Graph results on top of batching
 
@@ -320,7 +320,7 @@ In the async chunk pipeline, the standard `codec_chunk_frames` is 25 (each chunk
 
 **Dynamic initial chunk sizing (default behavior):**
 
-Rather than using a fixed initial chunk size, vLLM-Omni dynamically selects it based on current server load. The initial chunk size is chosen from power-of-2 steps [2, 4, 8, 16] based on load factor (`active_requests / max_batch_size`):
+Rather than using a fixed initial chunk size, vLLM-Omni dynamically selects it based on current server load. The initial chunk size is chosen from power-of-2 steps [2, 4, 8, 16] based on load factor (`active_requests / max_num_seqs`):
 
 | Server load | Initial chunk frames | Rationale |
 | --- | --- | --- |
@@ -349,16 +349,15 @@ This overrides the dynamic calculation for that request.
 **Config (server-side):**
 
 ```yaml
-runtime:
-  connectors:
-    connector_of_shared_memory:
-      name: SharedMemoryConnector
-      extra:
-        codec_streaming: true
-        codec_chunk_frames: 25              # standard chunk size (~2s of audio)
-        codec_left_context_frames: 25
-        # initial chunk is computed dynamically by default
-        # set initial_codec_chunk_frames: 2 to force a fixed value
+connectors:
+  connector_of_shared_memory:
+    name: SharedMemoryConnector
+    extra:
+      codec_streaming: true
+      codec_chunk_frames: 25              # standard chunk size (~2s of audio)
+      codec_left_context_frames: 25
+      # initial chunk is computed dynamically by default
+      # set initial_codec_chunk_frames: 2 to force a fixed value
 ```
 
 The 64 ms TTFP result reported above for Qwen3-TTS at concurrency 1 uses the dynamic initial chunk, which picks `initial_codec_chunk_frames=2` at low load. At higher concurrency the dynamic sizing increases the initial chunk to maintain decode efficiency.
@@ -408,7 +407,7 @@ vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct \
 
 Notes:
 
-- `runtime.max_batch_size` controls stage-level batching.
+- `stages[].max_num_seqs` controls stage-level batching.
 - Thinker/Talker commonly use `enforce_eager: false` for CUDA Graph paths.
 - Code2Wav often remains eager (`enforce_eager: true`) depending on runtime behavior.
 - Qwen3-Omni defaults `VLLM_USE_FLASHINFER_MOE_FP16=0`. The Triton has been more stable & faster
@@ -426,33 +425,26 @@ vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct \
 
 ```yaml
 async_chunk: true
-stage_args:
+stages:
   - stage_id: 0  # thinker
-    runtime:
-      max_batch_size: 64
-    engine_args:
-      enforce_eager: false
-      max_num_batched_tokens: 32768
-      custom_process_next_stage_input_func: >-
-        vllm_omni.model_executor.stage_input_processors.qwen3_omni.thinker2talker_async_chunk
+    max_num_seqs: 64
+    enforce_eager: false
+    max_num_batched_tokens: 32768
 
   - stage_id: 1  # talker
-    runtime:
-      max_batch_size: 64
-    engine_args:
-      enforce_eager: false
-      max_num_batched_tokens: 32768
-      custom_process_next_stage_input_func: >-
-        vllm_omni.model_executor.stage_input_processors.qwen3_omni.talker2code2wav_async_chunk
+    max_num_seqs: 64
+    enforce_eager: false
+    max_num_batched_tokens: 32768
 
   - stage_id: 2  # code2wav
-    runtime:
-      max_batch_size: 64
-    engine_args:
-      enforce_eager: true
-      max_num_batched_tokens: 51200
+    max_num_seqs: 64
+    enforce_eager: true
+    max_num_batched_tokens: 51200
 ```
 
+The async handoff processors are fixed by the registered Qwen3-Omni
+`PipelineConfig`; deploy YAML only selects `async_chunk` and runtime sizing.
+
 #### Reproduce Qwen3-Omni benchmarks
 
 ```bash
@@ -483,7 +475,7 @@ vllm-omni serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \
 
 The default config (`qwen3_tts.yaml`) enables the full optimization stack:
 
-- Batching with `max_batch_size: 10` on the Talker stage
+- Batching with `max_num_seqs: 10` on the Talker stage
 - CUDA Graph on the Talker (`enforce_eager: false`)
 - Async chunk with streaming transport
 
@@ -500,33 +492,29 @@ vllm-omni serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \
 
 ```yaml
 async_chunk: true
-stage_args:
+stages:
   - stage_id: 0  # Talker (AR decoder)
-    runtime:
-      max_batch_size: 10
-    engine_args:
-      enforce_eager: false
-      max_num_batched_tokens: 512
-      custom_process_next_stage_input_func: >-
-        vllm_omni.model_executor.stage_input_processors.qwen3_tts.talker2code2wav_async_chunk
+    max_num_seqs: 10
+    enforce_eager: false
+    max_num_batched_tokens: 512
 
   - stage_id: 1  # Code2Wav (vocoder)
-    runtime:
-      max_batch_size: 1
-    engine_args:
-      enforce_eager: true
-      max_num_batched_tokens: 8192
+    max_num_seqs: 1
+    enforce_eager: true
+    max_num_batched_tokens: 8192
 
-runtime:
-  connectors:
-    connector_of_shared_memory:
-      name: SharedMemoryConnector
-      extra:
-        codec_streaming: true
-        codec_chunk_frames: 25
-        codec_left_context_frames: 25
+connectors:
+  connector_of_shared_memory:
+    name: SharedMemoryConnector
+    extra:
+      codec_streaming: true
+      codec_chunk_frames: 25
+      codec_left_context_frames: 25
 ```
 
+The async Talker-to-Code2Wav processor is defined by the registered Qwen3-TTS
+pipeline rather than the deploy YAML.
+
 #### Reproduce Qwen3-TTS benchmarks
 
 ```bash

docs/getting_started/quickstart.md

@@ -66,7 +66,7 @@ from vllm_omni.entrypoints.omni import Omni
 if __name__ == "__main__":
     omni = Omni(
         model="Tongyi-MAI/Z-Image-Turbo",
-        # stage_configs_path="./stage-config.yaml",  # See below
+        # deploy_config="./deploy-config.yaml",  # Optional deploy override
     )
     prompts = [
         "a cup of coffee on a table",

docs/serving/speech_api.md

@@ -688,7 +688,7 @@ for result in response.json()["results"]:
 |-----------|--------|---------|-------------|
 | `tts_batch_max_items` | engine kwarg | 32 | Maximum number of items per batch request |
 
-All items are fanned out to `generate()` concurrently. The engine's stage worker automatically batches them up to the configured `max_batch_size` and queues the rest — no client-side throttling needed.
+All items are fanned out to `generate()` concurrently. The engine's stage worker automatically batches them up to the configured `max_num_seqs` and queues the rest — no client-side throttling needed.
 
 For best throughput, set both stages' `max_num_seqs` above 1 via `--stage-overrides`. On the current Qwen3-TTS CustomVoice benchmark, stage 1 performed best at `max_num_seqs: 10`:
 

docs/serving/video_stream_api.md

@@ -10,7 +10,7 @@ Each server instance runs a single model specified at startup with `vllm serve <
 
 ```bash
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct \
-    --deploy-config vllm_omni/deploy/qwen3_omni.yaml \
+    --deploy-config vllm_omni/deploy/qwen3_omni_moe.yaml \
     --omni \
     --port 8000 \
     --trust-remote-code

docs/user_guide/diffusion/execution_modes.md

@@ -207,18 +207,16 @@ outputs = omni.generate(
 )
 ```
 
-## Stage Configuration
+## Deploy Configuration
 
 Use the equivalent engine arguments in a deployment YAML:
 
 ```yaml
-stage_args:
+stages:
   - stage_id: 0
-    stage_type: diffusion
-    engine_args:
-      step_execution: false
-      max_num_seqs: 4
-      request_batch_max_wait_ms: 20
+    step_execution: false
+    max_num_seqs: 4
+    request_batch_max_wait_ms: 20
 ```
 
 For step execution, set `step_execution: true` and remove

docs/user_guide/diffusion/regional_compilation.md

@@ -24,7 +24,7 @@ stages:
 
 For an experimental whole-transformer compile scope, set
 `--diffusion-compile-granularity full` or use
-`diffusion_compile_granularity: full` in the stage configuration. Full scope may
+`diffusion_compile_granularity: full` in the deploy configuration. Full scope may
 still contain graph breaks; it does not force one graph. It is rejected when
 HSDP, sequence parallelism, CPU offload, or layerwise offload is enabled. Use
 regional scope with those features.

docs/user_guide/examples/offline_inference/mimo_audio.md

@@ -22,7 +22,7 @@ MiMo-Audio provides multiple task variants for audio understanding and generatio
 
 ## Setup
 
-Please refer to the [stage configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation appropriately for your hardware setup.
+See the [pipeline and deploy configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation for your hardware.
 
 ### Environment Variables
 
@@ -188,7 +188,7 @@ Note: This task uses hardcoded message lists in the script.
 
 ### Other
 
-- If the model or stage config fails to load, check [stage configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) for memory and GPU settings.
+- If the model or deploy config fails to load, check the [pipeline and deploy configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) for memory and GPU settings.
 - For errors when reading/writing WAV (e.g. unsupported format), ensure input files are standard WAV/MP3 and that `soundfile` is linked to a working libsndfile (see above).
 
 ## Notes

docs/user_guide/examples/offline_inference/qwen2_5_omni.md

@@ -4,7 +4,7 @@ Source <https://github.com/vllm-project/vllm-omni/tree/main/examples/offline_inf
 
 
 ## Setup
-Please refer to the [stage configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation appropriately for your hardware setup.
+See the [pipeline and deploy configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation for your hardware.
 
 ## Run examples
 

docs/user_guide/examples/offline_inference/qwen3_omni.md

@@ -4,7 +4,8 @@ Source <https://github.com/vllm-project/vllm-omni/tree/main/examples/offline_inf
 
 
 ## Setup
-Please refer to the [stage configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) to configure memory allocation appropriately for your hardware setup.
+Use `--deploy-config` for deployment overrides such as stage memory allocation.
+See the [pipeline and deploy configuration documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/).
 
 ## Run examples
 
@@ -73,8 +74,8 @@ For true stage-level concurrency -- where downstream stages (Talker, Code2Wav)
 start **before** the upstream stage (Thinker) finishes -- use the async_chunk
 example. This requires:
 
-1. A stage config YAML with ``async_chunk: true`` (e.g.
-   ``qwen3_omni_moe_async_chunk.yaml``).
+1. A deploy YAML with ``async_chunk: true`` (for example, an overlay based on
+   ``vllm_omni/deploy/qwen3_omni_moe.yaml``).
 2. Hardware that matches the config (e.g. 2x H100 for the default 3-stage
    config).
 
@@ -100,11 +101,11 @@ bash run_multiple_prompts_async_chunk.sh --max-in-flight 4
 python end2end_async_chunk.py --query-type text --modalities text
 ```
 
-#### Custom stage config
+#### Custom deploy config
 ```bash
 python end2end_async_chunk.py \
     --query-type use_audio \
-    --stage-configs-path /path/to/your_async_chunk.yaml
+    --deploy-config /path/to/your_async_chunk.yaml
 ```
 
 > **Note**: The synchronous ``end2end.py`` (using ``Omni``) is still the

docs/user_guide/examples/offline_inference/text_to_speech.md

@@ -69,7 +69,7 @@ python examples/offline_inference/text_to_speech/voxcpm2/end2end.py \
 
 ### Notes
 - Output: 48 kHz mono WAV.
-- Stage config: `vllm_omni/model_executor/stage_configs/voxcpm2.yaml` (default).
+- Deploy config: `vllm_omni/deploy/voxcpm2.yaml` (default).
 
 ---
 
@@ -152,7 +152,7 @@ python examples/offline_inference/text_to_speech/fish_speech/end2end.py \
     --text "Hello, this is a streaming test." \
     --streaming
 ```
-Streaming requires `async_chunk: true` in the stage config.
+Streaming requires `async_chunk: true` in the deploy config.
 
 ### Notes
 - Output: 44.1 kHz mono WAV.
@@ -274,7 +274,7 @@ python examples/offline_inference/text_to_speech/qwen3_tts/end2end.py \
     --streaming \
     --output-dir /tmp/out_stream
 ```
-Streaming requires `async_chunk: true` in the stage config.
+Streaming requires `async_chunk: true` in the deploy config.
 
 ### Batched decoding
 The Code2Wav stage supports batched decoding through the SpeechTokenizer. Configure both stages with `max_num_seqs > 1` via `--stage-overrides` and pass multiple prompts via `--txt-prompts`:

docs/user_guide/examples/online_serving/qwen3_omni.md

@@ -271,7 +271,7 @@ The script supports the following arguments:
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091
 ```
 
-If you have custom stage configs file:
+If you have a custom deploy config file:
 ```bash
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091 --deploy-config /path/to/deploy_config_file
 ```

docs/user_guide/examples/online_serving/text_to_speech.md

@@ -419,7 +419,7 @@ curl -X POST http://localhost:8091/v1/audio/speech \
         "response_format": "pcm"
     }' --no-buffer | play -t raw -r 24000 -e signed -b 16 -c 1 -
 ```
-Raw PCM streaming requires `stream_format="audio"`, `response_format="pcm"`, and `async_chunk: true` on the stage config (default in `qwen3_tts.yaml`). `speed` is not supported when streaming.
+Raw PCM streaming requires `stream_format="audio"`, `response_format="pcm"`, and `async_chunk: true` in the deploy config (default in `qwen3_tts.yaml`). `speed` is not supported when streaming.
 
 ### Streaming WebSocket
 The `/v1/audio/speech/stream` endpoint accepts text incrementally and synthesizes the buffered text as one continuous request on `input.done`:

docs/user_guide/quantization/fp8.md

@@ -92,7 +92,7 @@ warmup_quack_fp8([(14040, 2048, 6144), (14040, 2048, 2048)])
 | FLUX.1 | `black-forest-labs/FLUX.1-dev`, `black-forest-labs/FLUX.1-schnell` | Yes | Yes | All layers | None | |
 | FLUX.2-dev | `black-forest-labs/FLUX.2-dev` | Yes | Not validated | All layers | None | ✅︎ |
 | FLUX.2-klein | `black-forest-labs/FLUX.2-klein-4B` | Yes | Yes | All layers | None | |
-| HunyuanImage-3.0 | `tencent/HunyuanImage-3.0`, `tencent/HunyuanImage-3.0-Instruct` | Yes | Yes | All layers; use the Hunyuan stage config for multi-stage runs | None | |
+| HunyuanImage-3.0 | `tencent/HunyuanImage-3.0`, `tencent/HunyuanImage-3.0-Instruct` | Yes | Yes | All layers; use the Hunyuan deploy config for multi-stage runs | None | |
 | HunyuanVideo-1.5 | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v`, `720p_t2v`, `480p_i2v` | Yes | Yes | All layers | None | |
 | Cosmos3 | `nvidia/Cosmos3-Nano`, `nvidia/Cosmos3-Super` | Yes | Not validated | All layers | None | |
 | MiniMax-H3 | `MiniMaxAI/MiniMax-H3` (`FL2VA` / `Ref2VA`) | Yes | Not validated | `quantization="fp8"` quantizes eligible DiT and text-encoder linears; mixed-precision input/output heads stay FP32 | None | ✅︎ |

docs/user_guide/quantization/msmodelslim.md

@@ -92,4 +92,4 @@ For HunyuanImage-3.0, use the Hunyuan-specific adaptation linked above.
 2. The `ascend` quantization method expects weights produced by the Ascend
    tooling; it is not a load-time CUDA quantizer.
 3. Keep the quantized checkpoint aligned with the same model architecture and
-   stage config used for BF16 inference.
+   pipeline and deploy config used for BF16 inference.

docs/user_guide/quantization/quantized_kvcache.md

@@ -83,23 +83,23 @@ Online serving:
 vllm serve <your-model> --omni --diffusion-kv-cache-dtype fp8
 ```
 
-Stage config:
+Deploy config:
 
 ```yaml
-stage_args:
+stages:
   - stage_id: 0
-    stage_type: diffusion
-    engine_args:
-      model_stage: dit
-      diffusion_kv_cache_dtype: "fp8"
-      diffusion_kv_cache_skip_steps: "0,1"
-      diffusion_kv_cache_skip_layers: "0-2"
+    diffusion_kv_cache_dtype: "fp8"
+    diffusion_kv_cache_skip_steps: "0,1"
+    diffusion_kv_cache_skip_layers: "0-2"
 ```
 
-Legacy YAML keys `kv_cache_dtype`, `kv_cache_skip_steps`, and
-`kv_cache_skip_layers` are still accepted when constructing
-`OmniDiffusionConfig` (for example via `from_kwargs`); prefer the `diffusion_*`
-names for new configs.
+The `model_stage` and diffusion execution type belong to the registered
+`PipelineConfig`; the deploy YAML only carries runtime overrides.
+
+The legacy keyword aliases `kv_cache_dtype`, `kv_cache_skip_steps`, and
+`kv_cache_skip_layers` remain accepted when constructing
+`OmniDiffusionConfig` directly. They are not deploy YAML fields; prefer the
+`diffusion_*` names for new code.
 
 ## Parameters