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

Signed-off-by: zwhzzz0821 <2831474076@qq.com>
2026-08-20 07:09:12 +08:00
1 parent efaf4276f9
commit 6f55a06fab
@@ -138,9 +138,12 @@ A shared buffer silently corrupts audio across concurrent requests — the sympt
   - Load codec weights (may need lazy loading from separate checkpoint)
   - Implement `forward()`: codec codes -> audio waveform
   - Return `OmniOutput` with `multimodal_outputs`
-5. **Create stage config YAML** defining both stages, memory allocation, and model paths
+5. **Define and register the pipeline topology** in
-6. **Create stage input processor** for prompt building
+   `vllm_omni/model_executor/models/<model>/pipeline.py`
-7. **Write end2end.py** test script
+6. **Create the deploy YAML** under `vllm_omni/deploy/` for placement,
   memory sizing, connectors, and runtime overrides
 7. **Create stage input processor** for prompt building and inter-stage handoff
 8. **Write end2end.py** test script
 ### Critical Parameters to Get Right
@@ -174,7 +177,7 @@ These bugs appear in almost every new TTS PR. Check all before the first push. S
 - **All return paths must emit `model_outputs`** — if any early-return branch skips setting `model_outputs`, the serving layer silently drops that step's audio (fish speech: `fix: ensure ALL return paths emit model_outputs`)
 - **Per-request state isolation** — for batched concurrent requests, key all state by request ID; a shared buffer corrupts audio across requests (fish speech: `fix: per-request vocode + delta emission`)
 - **Codec tensor device** — move codec codes to the codec decoder's device before calling decode; mismatches cause silent CPU fallback or crashes (fish speech: `fix: use model device for CUDA stream`)
- **AR stage `max_num_seqs`** — set to at least 4 in production configs; for single-stage models this is the only stage. For two-stage models, Stage 0 (AR) needs `max_num_seqs ≥ 4` to pipeline concurrent requests; Stage 1 (codec decoder) typically uses `max_num_seqs: 1` intentionally. Default of 1 everywhere causes audio gaps under concurrency because the codec window round-robins across requests (RFC #2568)
+- **AR stage `max_num_seqs`** — set to at least 4 in production deploy configs; for single-stage models this is the only stage. For two-stage models, Stage 0 (AR) needs `max_num_seqs ≥ 4` to pipeline concurrent requests; Stage 1 (codec decoder) is model-specific and may intentionally use `max_num_seqs: 1`. Defaulting the AR stage to 1 causes audio gaps under concurrency because the codec window round-robins across requests (RFC #2568)
 ### Optional Dependency Handling
@@ -190,18 +193,18 @@ pattern, signature constraints, and MOSS-TTS-Nano reference.
 When the upstream model cannot be cleanly split into an AR stage and a
 separate decoder, run the full pipeline inside a single AR worker and
 stream audio through a per-request `inference_stream()` generator keyed by
-`_omni_req_id`. Stage config must set `worker_type: ar`,
+`_omni_req_id`. Define one `StagePipelineConfig` with
-`engine_output_type: audio`, `final_output: true`, `is_comprehension: true`,
+`execution_type=StageExecutionType.LLM_AR`, `engine_output_type="audio"`,
-and `async_chunk: false` at the top level. Only extract params from
+`final_output=True`, and `owns_tokenizer=True`. Set `async_chunk: false` in
 the deploy YAML. Only extract params from
 `additional_information` that you actually forward, or pre-commit fails
 `ruff F841`.
 Full walkthrough with the complete `forward()` / `_create_stream_gen()`
-skeleton and stage-config fields:
+skeleton plus pipeline/deploy definitions:
 [references/single-stage-ar.md](references/single-stage-ar.md). For an
 in-tree reference, look for any single-stage AR model under
-`vllm_omni/model_executor/models/` — e.g. the MOSS-TTS-Nano integration when
+`vllm_omni/model_executor/models/`, such as MOSS-TTS-Nano.
 it lands.
 **VoxCPM2 is a different pattern** and should not reuse this skeleton — it
 runs the base LM under vLLM PagedAttention with external side-computation.
@@ -210,7 +213,8 @@ See `plan/voxcpm2_native_ar_design.md`.
 ### Deliverables
 - Model files in `vllm_omni/model_executor/models/<model_name>/`
- Stage config YAML
+- Registered `pipeline.py` topology
 - Deploy YAML under `vllm_omni/deploy/`
 - Working `end2end.py` at `examples/offline_inference/text_to_speech/<model>/end2end.py`
 - New section in `examples/offline_inference/text_to_speech/README.md` (table row + per-model section). Do **not** create a top-level `examples/offline_inference/<model>/` dir or a per-model `README.md` inside `text_to_speech/<model>/` — the hub README is the documented surface and the mkdocs `generate_examples` hook only descends one level into `examples/<category>/`.
@@ -400,21 +404,29 @@ See [vllm-omni-test skill](../vllm-omni-test/SKILL.md) § **Runtime send helpers
 ### Steps
-1. **Update stage config YAML**:
+1. **Update the pipeline topology** so the producing stage declares its async
   handoff processor with `async_chunk_process_next_stage_input_func`.
 2. **Update the deploy YAML** to enable async chunk and configure the connector:
   ```yaml
   async_chunk: true
-   codec_chunk_frames: 25      # frames per chunk
+
-   codec_left_context_frames: 25  # overlap for smooth boundaries
+   connectors:
     connector_of_shared_memory:
       name: SharedMemoryConnector
       extra:
         codec_streaming: true
         codec_chunk_frames: 25
         codec_left_context_frames: 25
   ```
-2. **Implement chunk handling in Stage 1**:
+3. **Implement chunk handling in Stage 1**:
   - Accept partial input (chunk of codec codes)
   - Handle left context for smooth audio boundaries
   - Return partial audio in `OmniOutput`
-3. **Test streaming**:
+4. **Test streaming**:
   - Verify audio quality matches non-streaming output
   - Check for artifacts at chunk boundaries
   - Measure TTFA (time to first audio)
-4. **Update online serving** to support `stream=true` with PCM output
+5. **Update online serving** to support `stream=true` with PCM output
 ### Streaming Architecture
@@ -435,7 +447,8 @@ Stage 0 (AR)                    Stage 1 (Decoder)
 ### Deliverables
- Updated stage config with async_chunk enabled
+- Updated pipeline async handoff processor and deploy config with
  `async_chunk: true`
 - Smooth streaming audio without boundary artifacts
 - TTFA metrics
@@ -507,14 +520,15 @@ Use this checklist when integrating a new TTS model:
 - [ ] Config classes created with `model_type` registration
 - [ ] Stage 0 (AR) implemented and generates correct tokens
 - [ ] Stage 1 (Decoder) produces correct audio from tokens — dtype float32 for codec decoder
- [ ] Stage 1 `max_num_seqs` ≥ 4 in production config (default 1 causes gaps under concurrency)
+- [ ] AR stage `max_num_seqs` ≥ 4 in the production deploy config unless the model has a tested lower limit
 - [ ] Optional dependency fallbacks handled at `load_weights()` time (torchaudio/soundfile/etc.)
 - [ ] Streaming: codec codes accumulated across AR steps (not reset per step)
 - [ ] Streaming: delta audio emitted per chunk, not full re-decoded waveform
 - [ ] Streaming: all `forward()` return paths emit `model_outputs`
 - [ ] Streaming: per-request state keyed by request ID (not shared across requests)
 - [ ] Streaming: codec tensors moved to codec decoder device before decode
- [ ] Stage config YAML created
+- [ ] Pipeline topology defined in `pipeline.py` and registered in `OMNI_PIPELINES`
 - [ ] Deploy YAML created under `vllm_omni/deploy/`
 - [ ] `end2end.py` produces audio matching reference quality
 - [ ] README.md written
@@ -531,7 +545,8 @@ Use this checklist when integrating a new TTS model:
 - [ ] Documentation added (offline + online docs, nav, supported models)
 ### Phase 4: Async Chunk
- [ ] Stage config updated with `async_chunk: true`
+- [ ] Pipeline declares the async handoff processor
 - [ ] Deploy config sets `async_chunk: true` and connector chunk parameters
 - [ ] Stage 1 handles partial chunks correctly
 - [ ] No audio artifacts at chunk boundaries
 - [ ] Streaming via API (`stream=true`) works
@@ -86,12 +86,51 @@ class YourModelForCausalLM(nn.Module):
 - Handle both `"audio"` (incremental) and `"result"` (final combined) event
  types from upstream models.
-## Stage config
+## Pipeline and deploy config
-Single stage with `worker_type: ar`, `engine_output_type: audio`,
+Define the fixed single-stage topology in `pipeline.py`:
-`final_output: true`, `is_comprehension: true`, and `async_chunk: false` at
+
-the top level. Omitting any of these causes silent misclassification in the
+```python
-serving layer.
+from vllm_omni.config.stage_config import (
    PipelineConfig,
    StageExecutionType,
    StagePipelineConfig,
 )
 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_name",
            execution_type=StageExecutionType.LLM_AR,
            input_sources=(),
            owns_tokenizer=True,
            engine_output_type="audio",
            final_output=True,
            final_output_type="audio",
        ),
    ),
 )
 ```
 Register it in `vllm_omni/config/pipeline_registry.py`. Keep placement and
 runtime sizing in `vllm_omni/deploy/your_model_name.yaml`:
 ```yaml
 async_chunk: false
 stages:
  - stage_id: 0
    devices: "0"
    max_num_seqs: 4
    gpu_memory_utilization: 0.8
 ```
 Do not move `execution_type`, output ownership, tokenizer ownership, or model
 architecture into the deploy YAML; those are pipeline topology.
 ## Lint discipline
@@ -101,8 +140,5 @@ pre-commit.
 ## Reference implementation
-Look for any single-stage AR model under
+Use `vllm_omni/model_executor/models/moss_tts_nano/pipeline.py` and
-`vllm_omni/model_executor/models/` — e.g. `moss_tts_nano/` when its
+`vllm_omni/deploy/moss_tts_nano.yaml` as the in-tree reference.
 integration lands. If none is in tree yet, follow the skeleton above and
 cross-check against the `is_comprehension: true` / `async_chunk: false`
 dispatch in `vllm_omni/entrypoints/openai/serving_speech.py`.
@@ -92,7 +92,7 @@ If docs and live code disagree, verify the code/tests and report the drift.
 | Reference | Read when |
 | --- | --- |
-| [model-addition-checklist.md](references/checks/model-addition-checklist.md) | A model, architecture, loader, processor, registry, or stage config is added. |
+| [model-addition-checklist.md](references/checks/model-addition-checklist.md) | A model, architecture, loader, processor, registry, pipeline config, or deploy config is added. |
 | [perf-verification.md](references/checks/perf-verification.md) | The PR makes a latency, throughput, memory, or quality claim. |
 | [test-quality-evaluation.md](references/checks/test-quality-evaluation.md) | Tests change, are absent for risky code, or may not exercise production behavior. |
 | [tests-docs-checklist.md](references/checks/tests-docs-checklist.md) | Coverage, CI markers, examples, user docs, or PR evidence need review. |
@@ -1,7 +1,7 @@
 # Model Addition Checklist
 Read this reference when a PR adds or expands a model architecture, pipeline,
-loader, processor, registry entry, or stage configuration.
+loader, processor, registry entry, pipeline config, or deploy config.
 Official docs: [model contribution guides](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/model/),
 [adding an omni model](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/model/adding_omni_model/),
@@ -3,7 +3,7 @@
 Primary design: [vLLM-Omni Configuration](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/vllm_omni_config/).
 Use for config construction, deploy YAML, registries, schema, defaults,
-aliases, CLI projection, stage config, and topology. Inspect the reviewed
+aliases, CLI projection, pipeline config, and topology. Inspect the reviewed
 page's status: while its contract remains deferred or draft, current code and
 tests—not proposed precedence rules—are authoritative.
@@ -48,7 +48,7 @@ compatibility changes.
 | Signal | Read | Optional repo-local skill |
 | --- | --- | --- |
-| New or expanded model, loader, processor, registry, or stage config | [model-addition-checklist.md](../checks/model-addition-checklist.md) | [`add-tts-model`](../../../add-tts-model/SKILL.md) or [`add-diffusion-model`](../../../add-diffusion-model/SKILL.md) |
+| New or expanded model, loader, processor, registry, pipeline config, or deploy config | [model-addition-checklist.md](../checks/model-addition-checklist.md) | [`add-tts-model`](../../../add-tts-model/SKILL.md) or [`add-diffusion-model`](../../../add-diffusion-model/SKILL.md) |
 | Latency, throughput, memory, scaling, precision, or quality claim | [perf-verification.md](../checks/perf-verification.md) | [`diffusion-perf-opt`](../../../diffusion-perf-opt/SKILL.md) for diffusion |
 | Tests changed, absent for risky behavior, or test-only | [test-quality-evaluation.md](../checks/test-quality-evaluation.md) | [`vllm-omni-test`](../../../vllm-omni-test/SKILL.md) |
 | CI, examples, docs, public behavior, or contributor evidence | [tests-docs-checklist.md](../checks/tests-docs-checklist.md) | None |
@@ -110,10 +110,10 @@ After choosing offline/online/docs/perf, classify the **product under test** and
 |-----------|------------------------------|----------------------------|----------------------------------------|
 | **What it is** | Multimodal LLM pipeline (thinker/talker/stages; text + vision + audio I/O) | Speech synthesis / voice models | Generative diffusion (noise → image, audio, text, or video) |
 | **Examples** | Qwen2.5-Omni, Qwen3-Omni | Qwen3-TTS, VoxCPM2, Higgs-Audio, Step-Audio2 | Qwen-Image, BAGEL, Wan2.2, HunyuanVideo |
-| **Offline runner** | `omni_runner` + `omni_runner_handler`, `generate_multimodal` | `Omni(...).generate` or stage YAML + TTS params | `Omni(...).generate` + `OmniDiffusionSamplingParams` |
+| **Offline runner** | `omni_runner` + `omni_runner_handler`, `generate_multimodal` | `Omni(...).generate` with deploy YAML + TTS params | `Omni(...).generate` + `OmniDiffusionSamplingParams` |
 | **Online client** | `openai_client.send_omni_request` (chat completions, modalities) | `openai_client.send_audio_speech_request` (`/v1/audio/speech`) | `send_diffusion_request` (chat/T2I), `send_video_diffusion_request` (`/v1/videos`, X2V), or `send_images_generations_http_request` / `send_images_edits_http_request` (DALL-E routes) |
 | **Typical assertions** | Stage outputs, text/audio keywords via `OmniRunnerHandler` / response handler | WAV bytes, stream chunks, speech endpoint contract | Image/video dimensions, `final_output_type`, `assert_diffusion_response` |
-| **Stage / deploy YAML** | Per-model omni stage configs (`ci/qwen3_omni_moe.yaml`, …) | `qwen3_tts.yaml`, `voxcpm2.yaml`, … | Often default serve; parallel/offload YAML for heavy DiT |
+| **Deploy YAML** | Per-model deploy configs (`ci/qwen3_omni_moe.yaml`, …) | `qwen3_tts.yaml`, `voxcpm2.yaml`, … | Often default serve; parallel/offload YAML for heavy DiT |
 | **Nightly group** (`test-nightly.yml`) | **Omni Model Test** — `-m "full_model and omni"` | **TTS Model Test** — `-m "full_model and tts"` | **Diffusion X2I(&A&T)** *or* **Diffusion X2V** (see Step 3 table; same `diffusion` marker, different YAML group / file shard) |
 | **L4 pressure** | Expansion per modality/model as needed | Expansion + accuracy/perf in TTS group | X2I: merge feature combos per [#1832](https://github.com/vllm-project/vllm-omni/issues/1832); X2V: separate nightly group |
@@ -79,8 +79,6 @@
 /vllm_omni/model_executor/models/ @tzhouam @gcanlin @Sy0307 @amy-why-3459 @linyueqian
 /vllm_omni/model_extras/ @tzhouam @gcanlin @princepride
 /vllm_omni/plugins/ @gcanlin @tjtanaa @xuechendi
 # Config override within model_executor — docs/design/module/vllm_omni_config.md
 /vllm_omni/model_executor/stage_configs/ @lishunyang12 @alex-jw-brooks
 # Execution platforms (hardware backends) — docs/design/module/execution_platforms.md
 /vllm_omni/platforms/ @gcanlin @tjtanaa @xuechendi
@@ -83,7 +83,7 @@ body:
      omni = Omni(
          model="Qwen/Qwen-Image",
-          stage_configs_path="/path/to/stage_configs.yaml",
+          deploy_config="/path/to/deploy_config.yaml",
      )
      prompts = [{"prompt": "A scenic watercolor painting of a lighthouse at sunset"}]
@@ -18,8 +18,8 @@ vllm serve Qwen/Qwen3-TTS-12Hz-1.7B-Base --omni --port 8000
 ```
 The server auto-loads its Deploy YAML from `vllm_omni/deploy/qwen3_tts.yaml`
-(Pipeline + Deploy schema introduced in #2383). No `--stage-configs-path` or
+(Pipeline + Deploy schema introduced in #2383). No explicit `--deploy-config`
-`--deploy-config` flag is needed for any registered model.
+flag is needed for a registered model.
 ### 2. Run the benchmark (`vllm bench serve --omni`)
@@ -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
@@ -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
@@ -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"
-      devices: "0"
+    gpu_memory_utilization: 0.6  # Uses 60% of GPU 0
    engine_args:
      gpu_memory_utilization: 0.6  # Uses 60% of GPU 0
  - stage_id: 1
-    runtime:
+    devices: "0"
-      devices: "0"
+    gpu_memory_utilization: 0.3  # Uses 30% of GPU 0
-    engine_args:
+    # Total: 90% of GPU 0 (safe, leaves 10% buffer)
      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
-      devices: "0,1"  # Uses both GPUs
+    tensor_parallel_size: 2
-    engine_args:
+    gpu_memory_utilization: 0.6  # 60% per GPU
-      tensor_parallel_size: 2
+    # Model is split, so each GPU uses ~30% of model memory
      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"
-      devices: "0,1"
+    tensor_parallel_size: 2
-    engine_args:
+    gpu_memory_utilization: 0.6  # 48GB per GPU
      tensor_parallel_size: 2
      gpu_memory_utilization: 0.6  # 48GB per GPU
  - stage_id: 1  # Talker stage
-    runtime:
+    devices: "1"
-      devices: "1"
+    gpu_memory_utilization: 0.3  # 24GB on GPU 1
    engine_args:
      gpu_memory_utilization: 0.3  # 24GB on GPU 1
  - stage_id: 2  # Code2Wav stage
-    runtime:
+    devices: "0"
-      devices: "0"
+    gpu_memory_utilization: 0.1  # 8GB on GPU 0
    engine_args:
      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
@@ -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. |
+| `data_parallel_size` | int \| null | optional | `null` | **Pipeline-wide.** DP degree for every stage. |
-| `pipeline_parallel_size` | int | optional | `1` | **Pipeline-wide.** PP 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. |
+| `max_num_seqs` | int \| null | optional | `null` | Max concurrent sequences per stage. |
-| `gpu_memory_utilization` | float | optional | `0.9` | Per-stage total memory target; used for automatic KV-cache sizing. |
+| `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. |
+| `tensor_parallel_size` | int \| null | optional | `null` | TP degree for this stage. |
-| `enforce_eager` | bool | optional | `false` | Disable CUDA graphs. |
+| `enforce_eager` | bool \| null | optional | `null` | 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. |
+| `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.
@@ -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:
@@ -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": {
+    "stages": {
-        "2": ["custom_process_input_func"]  // Delete this configuration for stage 2
+        "2": ["max_num_batched_tokens"]  // Delete this deploy override for stage 2
    }
 }
 ```
@@ -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).
+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 stage YAML.
+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>
@@ -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_stage`**: Logical stage name ("thinker", "talker", "code2wav", etc.)
- **`model_arch`**: The model architecture name (must match registry)
+- **`execution_type`**: Runtime family (`LLM_AR`, `LLM_GENERATION`, or `DIFFUSION`)
- **`engine_input_source`**: List of stage IDs that provide input to this stage
+- **`model_arch`**: Stage architecture name, when different from the pipeline default
- **`custom_process_input_func`**: Function to process inputs from previous stages
+- **`input_sources`**: Upstream stage IDs that provide input to this stage
- **`final_output`**: Whether this stage produces the final output (True/False)
+- **`custom_process_input_func`**: Function that processes inputs from previous stages
- **`final_output_type`**: Type of final output ("text", "audio", "image", etc.)
+- **`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)
@@ -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
+- `StageExecutionType.LLM_AR` uses the autoregressive runtime with PagedAttention.
- `worker_type: generation` - non-AR stage (e.g. decoder), uses `OmniGenerationScheduler`
+- `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_stage` | Logical stage name (`ar_stage`, `decoder`, etc.). |
-| `model_arch` | Architecture name, must match `registry.py` |
+| `execution_type` | Runtime family for this stage. |
-| `engine_input_source` | List of upstream stage IDs that provide input (e.g. `[0]`) |
+| `input_sources` | Upstream stage IDs that provide input. |
-| `engine_output_type` | Output type: `latent` for intermediate, `audio` for final |
+| `model_arch` | Stage-specific architecture name, when it differs from the pipeline default. |
-| `custom_process_next_stage_input_func` | Async chunk processor function path (streaming only) |
+| `engine_output_type` | Output representation such as `latent` or `audio`. |
-| `final_output` | Whether this stage produces the final user-facing output |
+| `custom_process_next_stage_input_func` | Processor for full-payload stage handoff. |
-| `final_output_type` | Type of final output (`audio`, `text`, etc.) |
+| `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
+For example, a two-stage TTS topology can be defined as:
    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.
-### Batch mode
+```python
 from vllm_omni.config.stage_config import (
    PipelineConfig,
    StageExecutionType,
    StagePipelineConfig,
 )
-```yaml
+_PROC = "vllm_omni.model_executor.stage_input_processors.your_model_name"
 # stage_configs/your_model_name.yaml
-stage_args:
+YOUR_TTS_PIPELINE = PipelineConfig(
-  - stage_id: 0
+    model_type="your_model_name",
-    stage_type: llm
+    default_deploy_config_name="your_model_name.yaml",
-    runtime:
+    model_arch="YourTTSModelForConditionalGeneration",
-      devices: "0"
+    stages=(
-    engine_args:
+        StagePipelineConfig(
-      model_stage: ar_stage
+            stage_id=0,
-      max_num_seqs: 64
+            model_stage="ar_stage",
-      model_arch: YourTTSModelForConditionalGeneration
+            execution_type=StageExecutionType.LLM_AR,
-      worker_type: ar
+            input_sources=(),
-      scheduler_cls: vllm_omni.core.sched.omni_ar_scheduler.OmniARScheduler
+            owns_tokenizer=True,
-      engine_output_type: latent
+            engine_output_type="latent",
-    default_sampling_params:
+            custom_process_next_stage_input_func=f"{_PROC}.ar2decoder",
-      temperature: 0.9
+            async_chunk_process_next_stage_input_func=f"{_PROC}.ar2decoder_async_chunk",
-      top_k: 50
+        ),
-      max_tokens: 2048
+        StagePipelineConfig(
-
+            stage_id=1,
-  - stage_id: 1
+            model_stage="decoder",
-    stage_type: llm
+            execution_type=StageExecutionType.LLM_GENERATION,
-    runtime:
+            input_sources=(0,),
-      devices: "0"
+            model_arch="YourTTSDecoder",
-    engine_args:
+            engine_output_type="audio",
-      model_stage: decoder
+            final_output=True,
-      model_arch: YourTTSModelForConditionalGeneration
+            final_output_type="audio",
-      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
 ```
-### Streaming mode (async_chunk)
+Register the pipeline in `vllm_omni/config/pipeline_registry.py`. Runtime
-
+placement and sizing belong in `vllm_omni/deploy/your_model_name.yaml`:
 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:
 ```yaml
 # stage_configs/your_model_name_async_chunk.yaml
 async_chunk: true
-stage_args:
+stages:
  - stage_id: 0
-    stage_type: llm
+    devices: "0"
-    runtime:
+    max_num_seqs: 64
      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
    default_sampling_params:
      temperature: 0.9
      top_k: 50
      max_tokens: 2048
  - stage_id: 1
-    stage_type: llm
+    devices: "0"
-    runtime:
+    max_num_seqs: 1
      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
 ```
 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
+Use a single `LLM_AR` stage that owns the tokenizer and produces final audio:
-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
+```python
-concurrent production use.
+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
+    devices: "0"
-    is_comprehension: true          # required for serving_speech.py dispatch
+    max_num_seqs: 4
    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
 ```
 ### 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)
@@ -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
+The legacy `stage_args` YAML path has been removed. Model topology now resolves
-migrated to `PipelineConfig` and `DeployConfig`.
+through `PipelineConfig`, with runtime overrides supplied by `DeployConfig`.
 In the typed path, each stage configuration derives from
 `BaseVllmOmniStageConfig` and is specialized as
@@ -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`
+- `async_chunk_process_next_stage_input_func: str`: Pipeline-owned chunk processor path
- `stage_connector_config: dict`: Connector configuration
+- `execution_type: StageExecutionType`: Pipeline-owned runtime family
- `worker_type: str`: Model type, e.g. `"ar"` or `"generation"` (used by OmniChunkTransferAdapter for mode-specific payload handling)
+- `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
+  connector_of_shared_memory:
-    to_stage: 1
+    name: SharedMemoryConnector
-    spec:
+
-      name: SharedMemoryConnector
+stages:
-      extra:
+  - stage_id: 0
-        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"
-      devices: "1"
+    max_num_seqs: 64  # Enables batched audio generation
    engine_args:
      model_stage: code2wav
      max_num_seqs: 64  # Enables batched audio generation
 ```
 ## Related Files
@@ -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:
-  connectors:
+  connector_of_shared_memory:
-    connector_of_shared_memory:
+    name: SharedMemoryConnector
      name: SharedMemoryConnector
 ```
 Wire stages to connectors:
 ```yaml
-stage_args:
+stages:
  - stage_id: 0
    output_connectors:
      to_stage_1: connector_of_shared_memory
@@ -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:
-  connectors:
+  connector_of_mooncake:
-    connector_of_mooncake:
+    name: MooncakeStoreConnector
-      name: MooncakeStoreConnector
+    extra:
-      extra:
+      host: "127.0.0.1"
-        host: "127.0.0.1"
+      metadata_server: "http://<MASTER_IP>:8080/metadata"
-        metadata_server: "http://<MASTER_IP>:8080/metadata"
+      master: "<MASTER_IP>:50051"
-        master: "<MASTER_IP>:50051"
+      segment: 512000000
-        segment: 512000000
+      localbuf: 64000000
-        localbuf: 64000000
+      proto: "tcp"
        proto: "tcp"
 ```
 Wire stages to the connector:
 ```yaml
-stage_args:
+stages:
  - stage_id: 0
    output_connectors:
      to_stage_1: connector_of_mooncake
@@ -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:
-  connectors:
+  rdma_connector:
-    rdma_connector:
+    name: MooncakeTransferEngineConnector
-      name: MooncakeTransferEngineConnector
+    extra:
-      extra:
+      host: "auto"                  # Auto-detect local RDMA IP
-        host: "auto"                  # Auto-detect local RDMA IP
+      zmq_port: 50051               # ZMQ base port (see "Port Offset Scheme" below)
-        zmq_port: 50051               # ZMQ base port (see "Port Offset Scheme" below)
+      protocol: "rdma"              # "rdma" or "tcp"
-        protocol: "rdma"              # "rdma" or "tcp"
+      device_name: ""               # RDMA device (e.g., "mlx5_0"), empty for auto-detect
-        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_size: 4294967296  # 4 GB (CPU); use 2147483648 (2 GB) for GPU
+      memory_pool_device: "cpu"     # "cpu" for pinned memory (recommended), "cuda" for GPUDirect RDMA
        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"`
@@ -13,10 +13,9 @@ segment name is returned in metadata.
 ## Configuration
 ```yaml
-runtime:
+connectors:
-  connectors:
+  connector_of_shared_memory:
-    connector_of_shared_memory:
+    name: SharedMemoryConnector
      name: SharedMemoryConnector
 ```
 ## Notes
@@ -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:
-  connectors:
+  connector_of_yuanrong:
-    connector_of_yuanrong:
+    name: YuanrongConnector
-      name: YuanrongConnector
+    extra:
-      extra:
+      host: "127.0.0.1"
-        host: "127.0.0.1"
+      port: 31501
-        port: 31501
+      get_sub_timeout_ms: 1000
        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
@@ -94,26 +94,23 @@ For Ascend P2P, configure the connector with `protocol: "ascend"` and an NPU
 memory pool:
 ```yaml
-runtime:
+connectors:
-  enabled: true
+  yuanrong_te_connector:
-  defaults:
+    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"
-      devices: "0,1,2,3"
+    tensor_parallel_size: 4
-    engine_args:
+    omni_kv_config:
-      tensor_parallel_size: 4
+      need_send_cache: true
-      omni_kv_config:
+      rank_mapping:
-        need_send_cache: true
+        from_tp: 4
-        rank_mapping:
+        to_tp: 4
          from_tp: 4
          to_tp: 4
    output_connectors:
      to_stage_1: yuanrong_te_connector
  - stage_id: 1
-    runtime:
+    devices: "4,5,6,7"
-      devices: "4,5,6,7"
+    parallel_config:
-    engine_args:
+      tensor_parallel_size: 4
-      parallel_config:
+    omni_kv_config:
-        tensor_parallel_size: 4
+      need_recv_cache: true
-      omni_kv_config:
+      rank_mapping:
-        need_recv_cache: true
+        from_tp: 4
-        rank_mapping:
+        to_tp: 4
          from_tp: 4
          to_tp: 4
    input_connectors:
      from_stage_0: yuanrong_te_connector
 ```
@@ -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:
@@ -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
@@ -10,9 +10,8 @@ owners:
 primary_code_paths:
  - vllm_omni/config/**
  - vllm_omni/deploy/**
-  - vllm_omni/model_executor/stage_configs/**
+  - vllm_omni/model_executor/models/*/pipeline.py
-related_code_paths:
+related_code_paths: []
  - vllm_omni/platforms/*/stage_configs/**
 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.
@@ -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:
-  connectors:
+  connector_of_shared_memory:
-    connector_of_shared_memory:
+    name: SharedMemoryConnector
-      name: SharedMemoryConnector
+    extra:
-      extra:
+      codec_streaming: true
-        codec_streaming: true
+      codec_chunk_frames: 25              # standard chunk size (~2s of audio)
-        codec_chunk_frames: 25              # standard chunk size (~2s of audio)
+      codec_left_context_frames: 25
-        codec_left_context_frames: 25
+      # initial chunk is computed dynamically by default
-        # initial chunk is computed dynamically by default
+      # set initial_codec_chunk_frames: 2 to force a fixed value
        # 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_num_seqs: 64
-      max_batch_size: 64
+    enforce_eager: false
-    engine_args:
+    max_num_batched_tokens: 32768
      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
  - stage_id: 1  # talker
-    runtime:
+    max_num_seqs: 64
-      max_batch_size: 64
+    enforce_eager: false
-    engine_args:
+    max_num_batched_tokens: 32768
      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
  - stage_id: 2  # code2wav
-    runtime:
+    max_num_seqs: 64
-      max_batch_size: 64
+    enforce_eager: true
-    engine_args:
+    max_num_batched_tokens: 51200
      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_num_seqs: 10
-      max_batch_size: 10
+    enforce_eager: false
-    engine_args:
+    max_num_batched_tokens: 512
      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
  - stage_id: 1  # Code2Wav (vocoder)
-    runtime:
+    max_num_seqs: 1
-      max_batch_size: 1
+    enforce_eager: true
-    engine_args:
+    max_num_batched_tokens: 8192
      enforce_eager: true
      max_num_batched_tokens: 8192
-runtime:
+connectors:
-  connectors:
+  connector_of_shared_memory:
-    connector_of_shared_memory:
+    name: SharedMemoryConnector
-      name: SharedMemoryConnector
+    extra:
-      extra:
+      codec_streaming: true
-        codec_streaming: true
+      codec_chunk_frames: 25
-        codec_chunk_frames: 25
+      codec_left_context_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
@@ -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",
@@ -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`:
@@ -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
@@ -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
+    step_execution: false
-    engine_args:
+    max_num_seqs: 4
-      step_execution: false
+    request_batch_max_wait_ms: 20
      max_num_seqs: 4
      request_batch_max_wait_ms: 20
 ```
 For step execution, set `step_execution: true` and remove
@@ -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.
@@ -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
@@ -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
@@ -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.
+1. A deploy YAML with ``async_chunk: true`` (for example, an overlay based on
-   ``qwen3_omni_moe_async_chunk.yaml``).
+   ``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
@@ -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`:
@@ -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
 ```
@@ -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`:
@@ -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 | ✅︎ |
@@ -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.
@@ -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
+    diffusion_kv_cache_dtype: "fp8"
-    engine_args:
+    diffusion_kv_cache_skip_steps: "0,1"
-      model_stage: dit
+    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
+The `model_stage` and diffusion execution type belong to the registered
-`kv_cache_skip_layers` are still accepted when constructing
+`PipelineConfig`; the deploy YAML only carries runtime overrides.
-`OmniDiffusionConfig` (for example via `from_kwargs`); prefer the `diffusion_*`
+
-names for new configs.
+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
@@ -2,7 +2,8 @@
 ## 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/).
 > **Note**
 > Covo-Audio code2wav requires `torchdiffeq`. Install it with: `pip install torchdiffeq`
@@ -41,7 +42,7 @@ python end2end.py -m /path/to/Covo-Audio-Chat --output-dir ./my_output
 | `--sampling-rate` | | `16000` | Sampling rate for audio loading (Hz) |
 | `--output-dir` | | `./output_audio` | Output directory for generated files |
 | `--num-prompts` | | `1` | Number of prompts to generate |
-| `--stage-configs-path` | | (auto) | Path to stage configs YAML file |
+| `--deploy-config` | | (auto) | Optional path to a deploy YAML override |
 | `--log-stats` | | `false` | Enable detailed statistics logging |
 | `--stage-init-timeout` | | `300` | Stage initialization timeout (seconds) |
 | `--batch-timeout` | | `5` | Batching timeout (seconds) |
@@ -107,4 +107,4 @@ python <REPO_ROOT>/examples/offline_inference/dynin_omni/end2end.py \
 - If you want to force local config resolution, pass `--dynin-config-path <PATH_TO_DYNIN_OMNI_YAML>`.
 - If you see the warning
  `max_num_batched_tokens (32768) exceeds max_num_seqs * max_model_len (4096)`,
-  reduce `max_num_batched_tokens` in stage config (for example, `4096` in CI config).
+  reduce `max_num_batched_tokens` in the deploy config (for example, `4096` in the CI config).
@@ -7,17 +7,17 @@ YAMLs under `vllm_omni/deploy/`.
 | File | Topology | Default use |
 | :--- | :--- | :--- |
-| `vllm_omni/deploy/hunyuan_image3.yaml` | AR + DiT | Default for `text2img` and `img2img`. |
+| `vllm_omni/deploy/hunyuan_image_3_moe.yaml` | AR + DiT | Default for `text2img` and `img2img`. |
 | `vllm_omni/deploy/hunyuan_image3_ar.yaml` | AR only | Default for `img2text` and `text2text`. |
 | `vllm_omni/deploy/hunyuan_image3_dit.yaml` | DiT only | Standalone diffusion stage. Pass it explicitly with `--deploy-config`. |
-The example chooses a deploy config automatically when `--deploy-config` and
+The example chooses a deploy config automatically when `--deploy-config` is
-`--stage-configs-path` are both omitted:
+omitted:
 | `--modality` | `mode` passed to Omni | Default deploy |
 | :--- | :--- | :--- |
-| `text2img` | `text-to-image` | `hunyuan_image3.yaml` |
+| `text2img` | `text-to-image` | `hunyuan_image_3_moe.yaml` |
-| `img2img` | `image-editing` | `hunyuan_image3.yaml` |
+| `img2img` | `image-editing` | `hunyuan_image_3_moe.yaml` |
 | `img2text` | `image-to-text` | `hunyuan_image3_ar.yaml` |
 | `text2text` | `text-to-text` | `hunyuan_image3_ar.yaml` |
@@ -35,8 +35,8 @@ path; the image endpoints infer the image task from the endpoint and payload.
 | Online scenario | Server deploy | Request |
 | :--- | :--- | :--- |
-| Text to image | `--deploy-config vllm_omni/deploy/hunyuan_image3.yaml` | `POST /v1/images/generations`, or `POST /v1/chat/completions` with `"modalities": ["image"]`. |
+| Text to image | `--deploy-config vllm_omni/deploy/hunyuan_image_3_moe.yaml` | `POST /v1/images/generations`, or `POST /v1/chat/completions` with `"modalities": ["image"]`. |
-| Image editing | `--deploy-config vllm_omni/deploy/hunyuan_image3.yaml` | `POST /v1/images/edits`. |
+| Image editing | `--deploy-config vllm_omni/deploy/hunyuan_image_3_moe.yaml` | `POST /v1/images/edits`. |
 | Image/text to text | `--deploy-config vllm_omni/deploy/hunyuan_image3_ar.yaml` | `POST /v1/chat/completions` for text output, for example with `"modalities": ["text"]`. |
 | DiT-only image generation | `--deploy-config vllm_omni/deploy/hunyuan_image3_dit.yaml` | `POST /v1/images/generations`. |
@@ -96,7 +96,7 @@ Override the default full AR + DiT deploy explicitly:
 python examples/offline_inference/hunyuan_image3/end2end.py \
  --model tencent/HunyuanImage-3.0-Instruct \
  --modality text2img \
-  --deploy-config vllm_omni/deploy/hunyuan_image3.yaml \
+  --deploy-config vllm_omni/deploy/hunyuan_image_3_moe.yaml \
  --prompts "A cute cat"
 ```
@@ -117,8 +117,7 @@ python end2end.py --modality text2img \
 | Argument | Description |
 | :--- | :--- |
-| `--deploy-config` | Preferred config path for unified deploy YAMLs. |
+| `--deploy-config` | Optional path for unified deploy YAML overrides. |
 | `--stage-configs-path` | Legacy stage config path, kept only for compatibility. Prefer `--deploy-config`. |
 | `--additional-config` | JSON object forwarded to diffusion worker `additional_config`. |
 | `--modality` | Offline-only convenience flag. One of `text2img`, `img2img`, `img2text`, `text2text`. It selects prompt formatting, internal `mode`, and default deploy config for this script. Online serving uses `--deploy-config` plus the endpoint and, for chat completions, request `modalities` instead. |
 | `--steps` | Number of diffusion inference steps for image generation. |
@@ -132,7 +131,7 @@ python end2end.py --modality text2img \
 - `hunyuan_image3_ar.yaml` is a 4-card AR-only text/comprehension deploy.
 - `hunyuan_image3_dit.yaml` is a single-stage DiT deploy with `stage_id: 0`.
- The old HunyuanImage3 YAMLs under `model_executor/stage_configs/` and `platforms/*/stage_configs/` have been folded into the deploy YAMLs.
+- Platform-specific overrides are included in the unified deploy YAMLs.
 ## Prompt Format
@@ -19,7 +19,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
@@ -189,7 +189,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
@@ -14,7 +14,7 @@ For standalone TTS (talker only), see the [Ming-flash-omni-TTS section in the Te
 ## 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.
 When no `--deploy-config` is passed, the model registry auto-loads the full thinker+talker `vllm_omni/deploy/ming_flash_omni.yaml` (See [Omni-Speech](#omni-speech-thinker--talker)).
@@ -8,7 +8,7 @@ Two-stage pipeline: **thinker** (multimodal understanding) → **talker + Token2
 - Install talker deps: `pip install stepaudio2-minicpmo`
 - `--trust-remote-code` is always passed by `end2end.py` (required for MiniCPMO)
- See [stage configuration docs](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) for memory tuning
+- See [pipeline and deploy configuration docs](https://docs.vllm.ai/projects/vllm-omni/en/latest/configuration/stage_configs/) for memory tuning
 ## Run examples
@@ -1,7 +1,7 @@
 # Qwen2.5-Omni: Offline inference
 ## 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
@@ -1,7 +1,8 @@
 # Qwen3-Omni: Offline inference
 ## 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
@@ -70,8 +71,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 deploy config YAML with ``async_chunk: true`` (e.g.
+1. A deploy YAML with ``async_chunk: true`` (for example, an overlay based on
-   ``qwen3_omni_moe.yaml``).
+   ``vllm_omni/deploy/qwen3_omni_moe.yaml``).
 2. Hardware that matches the config (e.g. 2x H100 for the default 3-stage
   config).
@@ -97,11 +98,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 \
-    --deploy-config /path/to/your_deploy_config.yaml
+    --deploy-config /path/to/your_async_chunk.yaml
 ```
 > **Note**: The synchronous ``end2end.py`` (using ``Omni``) is still the
@@ -386,8 +386,8 @@ async def run_all(args):
        # argparse defaults do not silently override deploy YAML values.
        async_omni = AsyncOmni.from_cli_args(args, model=args.model)
-        # Use default sampling params from stage config (they are pre-configured
+        # Use default sampling params from the resolved pipeline and deploy
-        # in the YAML for each stage).
+        # config.
        #
        # NOTE: Since we do not set the sampling params directly, .generate in
        # will automatically set the output kind to delta, since this is what
@@ -29,7 +29,7 @@ Step-Audio2 is a two-stage audio model:
 **Notes:**
 - Single GPU mode requires high VRAM due to both stages sharing memory
 - Multi GPU mode separates Stage 0 (Thinker) and Stage 1 (Token2Wav) across GPUs
- VRAM usage can be adjusted via `gpu_memory_utilization` in stage config
+- VRAM usage can be adjusted via `gpu_memory_utilization` in the deploy config
 ## Performance Benchmark
@@ -197,11 +197,6 @@ This mode:
 ### Advanced Options
 ```bash
 # Use custom stage configuration
 python end2end.py --query-type audio_to_text \
    --model stepfun-ai/Step-Audio-2-mini \
    --stage-configs-path /path/to/custom_config.yaml
 # Use custom deploy configuration
 python end2end.py --query-type audio_to_text \
    --model stepfun-ai/Step-Audio-2-mini \
@@ -156,7 +156,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.
@@ -371,7 +371,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.
 ### Word Timestamps
 Word-level timestamps are currently a serving-path feature: launch
@@ -380,13 +380,13 @@ Word-level timestamps are currently a serving-path feature: launch
 example is not provided in this release.
 ### Batched decoding
-The Code2Wav stage supports batched decoding through the SpeechTokenizer. Pass multiple prompts via `--txt-prompts` and set `--batch-size` accordingly. To raise `max_num_seqs` on either stage, point `--stage-configs-path` at a stage configs YAML with the desired values (see `vllm_omni/model_executor/stage_configs/` for templates):
+The Code2Wav stage supports batched decoding through the SpeechTokenizer. Pass multiple prompts via `--txt-prompts` and set `--batch-size` accordingly. To raise `max_num_seqs` on either stage, create an overlay based on `vllm_omni/deploy/qwen3_tts.yaml` and pass it with `--deploy-config`:
 ```bash
 python examples/offline_inference/text_to_speech/qwen3_tts/end2end.py \
    --query-type CustomVoice \
    --txt-prompts examples/offline_inference/text_to_speech/qwen3_tts/benchmark_prompts.txt \
    --batch-size 4 \
-    --stage-configs-path /path/to/qwen3_tts_batched.yaml
+    --deploy-config /path/to/qwen3_tts_batched.yaml
 ```
 `--batch-size` must match a CUDA-graph capture size (1, 2, 4, 8, 16…).
@@ -131,7 +131,7 @@ python examples/offline_inference/text_to_speech/ming_tts/end2end.py \
    --enforce-eager
 ```
-`--streaming` uses `AsyncOmni` and the async_chunk stage config. It currently
+`--streaming` uses `AsyncOmni` and the async chunk deploy config. It currently
 supports one prompt per process invocation; use blocking mode for
 `--num-prompts > 1`.
@@ -304,7 +304,7 @@ def parse_args() -> Namespace:
        "--cfg-alpha",
        type=float,
        default=None,
-        help="CFG alpha for flow-matching guidance (default: use value from stage config, typically 1.2).",
+        help="CFG alpha for flow-matching guidance (default: use the deploy config value, typically 1.2).",
    )
    parser.add_argument(
        "--quantization",
@@ -328,7 +328,7 @@ def run_multimodal_generation(args) -> None:
    extra_body = {
        "sampling_params_list": sampling_params_list
-        # Optional, it has a default setting in stage_configs of the corresponding model.
+        # Optional; defaults come from the resolved pipeline and deploy config.
    }
    # Build messages list (filter None so concurrent tasks get valid structure)
@@ -415,7 +415,7 @@ def run_multimodal_generation(args, client: OpenAI) -> None:
            audio_path=audio_path,
        )
        extra_body = {
-            # Optional, it has default settings in stage configs. you can override them here.
+            # Optional; defaults come from the resolved pipeline and deploy config.
        }
        if args.query_type == "use_audio_in_video":
            extra_body["mm_processor_kwargs"] = {"use_audio_in_video": True}
@@ -38,7 +38,7 @@ full-duplex control plane:
 CUDA_VISIBLE_DEVICES=0 python -m vllm_omni.entrypoints.cli.main serve \
  /path/to/personaplex-7b-v1 \
  --omni \
-  --stage-configs-path vllm_omni/deploy/personaplex.yaml
+  --deploy-config vllm_omni/deploy/personaplex.yaml
 ```
 Validate the actual `/v1/realtime?duplex=1` scheduler path with paced 24 kHz
@@ -51,7 +51,7 @@ code2wav_sampling_params='{
  "detokenize": true,
  "repetition_penalty": 1.1
 }'
-# Above is optional, it has a default setting in stage_configs of the corresponding model.
+# The block above is optional; defaults come from the resolved pipeline and deploy config.
 # Define URLs for assets
 MARY_HAD_LAMB_AUDIO_URL="https://vllm-public-assets.s3.us-west-2.amazonaws.com/multimodal_asset/mary_had_lamb.ogg"
@@ -513,7 +513,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
 ```
@@ -50,7 +50,7 @@ code2wav_sampling_params='{
  "detokenize": true,
  "repetition_penalty": 1.1
 }'
-# Above is optional, it has a default setting in stage_configs of the corresponding model.
+# The block above is optional; defaults come from the resolved pipeline and deploy config.
 # Define URLs for assets
 MARY_HAD_LAMB_AUDIO_URL="https://vllm-public-assets.s3.us-west-2.amazonaws.com/multimodal_asset/mary_had_lamb.ogg"
@@ -15,7 +15,7 @@ so an output is a deterministic function of its own input and nothing else.
 Measuring replica scaling
 -------------------------
 This client is replica-agnostic. Vary the *server's* replica count
-(`runtime.num_replicas` in the stage config; see run_server.sh) and keep the
+(`stages[].num_replicas` in the deploy config; see run_server.sh) and keep the
 client workload fixed, then compare throughput:
    N=1 -> baseline
@@ -189,5 +189,5 @@ Async chunk reduces TTFP by **67%** by streaming audio token chunks from Thinker
 - Check server logs for errors
 ### Out of memory
- Reduce `gpu_memory_utilization` in stage configs
+- Reduce `gpu_memory_utilization` in the deploy config
 - Use a smaller batch size
@@ -570,7 +570,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`:
@@ -57,14 +57,14 @@ move the diffusion stage to a second GPU in a custom deploy config.
 #### Offline Commands
 Run text-to-image with the shared offline example from the repository root.
-Pick the topology with `--stage-configs-path` and forward BAGEL-specific
+Pick the topology with `--deploy-config` and forward BAGEL-specific
 generation parameters as a JSON object through `--extra-body`:
 ```bash
 # Two-stage (Thinker + DiT), shares one GPU by default
 python examples/offline_inference/text_to_image/text_to_image.py \
  --model ByteDance-Seed/BAGEL-7B-MoT \
-  --stage-configs-path vllm_omni/deploy/bagel.yaml \
+  --deploy-config vllm_omni/deploy/bagel.yaml \
  --prompt "A beautiful sunset over mountains" \
  --height 1024 \
  --width 1024 \
@@ -79,7 +79,7 @@ python examples/offline_inference/text_to_image/text_to_image.py \
 # Single-stage (DiT only, with internal LLM/ViT/VAE)
 python examples/offline_inference/text_to_image/text_to_image.py \
  --model ByteDance-Seed/BAGEL-7B-MoT \
-  --stage-configs-path vllm_omni/deploy/bagel_single_stage.yaml \
+  --deploy-config vllm_omni/deploy/bagel_single_stage.yaml \
  --prompt "A beautiful sunset over mountains" \
  --height 1024 \
  --width 1024 \
@@ -52,7 +52,7 @@ Start the server from the repository root:
 vllm serve zai-org/GLM-Image --omni --port 8091
 ```
-To use the bundled stage config explicitly (same default as above):
+To use the bundled deploy config explicitly (same default as above):
 ```bash
 vllm serve zai-org/GLM-Image \
@@ -106,7 +106,7 @@ Overall summary from the run’s metrics. Rough wall-time split: **Stage 0 (AR)*
 #### Notes
 - Memory usage: Roughly **~38 GiB + KV** on Stage 0 (AR) and **~20 GiB** on Stage 1 (DiT+VAE) per the user guide; two 80 GB cards match the default split.
- Key flags: `--omni` is required; `--stage-configs-path` is optional unless you use a custom YAML (for example single-GPU).
+- Key flags: `--omni` is required; `--deploy-config` is optional unless you use a custom YAML (for example single-GPU).
 - Keep **Transformers ≥ 5.5.1** (this recipe used **5.5.4**) so `glm_image` configs resolve; otherwise Stage 0 can fail at `ModelConfig` validation.
 - Known limitations: This starter recipe follows the dual-GPU online path documented under `examples/online_serving/glm_image`. The first request may be slower due to warmup.
 - Generation time: about **61 s** wall time end-to-end for the sample above (50 inference steps, 1024×1024).
@@ -79,7 +79,7 @@ Total generation time: <seconds> seconds (<milliseconds> ms)
 Saved generated video to helios_t2v_base.mp4
 ```
-#### Important flags and stage configs
+#### Important flags and deploy config
 - `--model BestWishYsh/Helios-Base` selects the base Helios checkpoint used by
  this recipe.
@@ -88,7 +88,7 @@ Saved generated video to helios_t2v_base.mp4
 - `--cache-backend cache_dit` enables the cache-dit acceleration path.
 - `--enable-cache-dit-summary` prints cache-dit summary information after
  diffusion forward passes.
- No separate stage config is required for this offline recipe; the shared
+- No separate deploy config is required for this offline recipe; the shared
  `text_to_video.py` example configures the pipeline through its arguments.
 - Helios-specific knobs (declared in `vllm_omni/model_extras/helios.py`) are
  passed via the generic `--extra-body` JSON flag:
@@ -44,7 +44,7 @@ vllm serve nvidia/GR00T-N1.7-3B \
  --host 127.0.0.1 \
  --port 8000 \
  --served-model-name gr00t-n1d7 \
-  --stage-configs-path vllm_omni/deploy/Gr00tN1d7.yaml
+  --deploy-config vllm_omni/deploy/Gr00tN1d7.yaml
 ```
 Notes:
@@ -54,7 +54,7 @@ NemotronH (~3B active parameters). Pick the pipeline by task:
 vllm serve nvidia/Nemotron-Labs-Audex-2B \
    --host 0.0.0.0 --port 8097 \
    --trust-remote-code --omni
-# other modes: add --stage-configs-path vllm_omni/deploy/audex_{tta,thinker_only,s2s}.yaml
+# other modes: add --deploy-config vllm_omni/deploy/audex_{tta,thinker_only,s2s}.yaml
 # or use the launcher: MODE=s2s PORT=8098 examples/online_serving/audex/run_server.sh
 ```
@@ -112,7 +112,7 @@ auto-resolves to the 2B-tuned config otherwise):
 vllm serve nvidia/Nemotron-Labs-Audex-30B-A3B \
    --host 0.0.0.0 --port 8097 \
    --trust-remote-code --omni \
-    --stage-configs-path vllm_omni/deploy/audex_tts_30b.yaml
+    --deploy-config vllm_omni/deploy/audex_tts_30b.yaml
 # or: SIZE=30b MODE=tts examples/online_serving/audex/run_server.sh
 ```
@@ -9,7 +9,7 @@
 #       --deploy-config vllm_omni/deploy/bagel_single_stage.yaml
 #
 # Or programmatically:
-#   Omni(model="...", deploy_config_path="vllm_omni/deploy/bagel_single_stage.yaml")
+#   Omni(model="...", deploy_config="vllm_omni/deploy/bagel_single_stage.yaml")
 pipeline: bagel_single_stage
 async_chunk: false
@@ -11,7 +11,7 @@
 #
 # Or programmatically:
 #   Omni(model="fishaudio/s2-pro",
-#        deploy_config_path="vllm_omni/deploy/fish_qwen3_omni_2gpu.yaml")
+#        deploy_config="vllm_omni/deploy/fish_qwen3_omni_2gpu.yaml")
 async_chunk: true
 enable_chunked_prefill: false
@@ -32,7 +32,7 @@ stages:
    max_num_batched_tokens: 16384
    devices: "0"
    # Required for MiniCPM interleaved image/audio Daily-Omni packs (~78% recipe).
-    # Keep these in YAML so they survive both --deploy-config and --stage-configs-path.
+    # Keep these in YAML so they are applied through --deploy-config.
    interleave_mm_strings: true
    media_io_kwargs:
      video:
@@ -6,8 +6,8 @@
 #   * enforce_eager=true — the model uses upstream inference_stream() with
 #     trust_remote_code; CUDA graph capture is not wired up.
 #   * gpu_memory_utilization=0.3 — the AR LM + codec fit in ~2 GiB.
-#   * max_num_seqs=4 — mirrors the legacy stage_configs contract; per-request
+#   * max_num_seqs=4 — supports per-request streaming generators stored in
-#     streaming generators are stored in self._stream_gens.
+#     self._stream_gens.
 #
 # MOSS-TTS-Nano has no multimodal input preprocessing, so skip_mm_profiling
 # bypasses the dummy-MM pass at profile time.
@@ -829,7 +829,7 @@ class OmniServeCommand(CLISubcommand):
            "--tts-max-instructions-length",
            type=int,
            default=None,
-            help="Maximum length for TTS voice style instructions (overrides stage config, default: 500).",
+            help="Maximum length for TTS voice style instructions (overrides the pipeline default, default: 500).",
        )
        # Disable safety guardrails for this server (currently only applicable for Cosmos3)
@@ -521,7 +521,7 @@ class StreamingSpeechSessionConfig(BaseModel):
    initial_codec_chunk_frames: int | None = Field(
        default=None,
        ge=0,
-        description="Initial chunk size for reduced TTFA. Overrides stage config for this session.",
+        description="Initial chunk size for reduced TTFA. Overrides the deploy config for this session.",
    )
    non_streaming_mode: bool | None = Field(
        default=None,
@@ -1272,7 +1272,7 @@ class OmniOpenAIServingChat(OpenAIServingChat, AudioMixin):
        max_tokens is NOT computed dynamically — it uses the deploy YAML default.
        Args:
-            default_params: Default SamplingParams from stage config YAML.
+            default_params: Default SamplingParams from the resolved pipeline and deploy configuration.
            request: The chat completion request containing user-provided values.
        Returns:
@@ -284,14 +284,14 @@ class MiMoAudioDataParser(MultiModalDataParser):
        if not self.audio_tokenizer_path:
            raise ValueError(
                "Audio tokenizer path is not set. Provide "
-                "`model_config.audio_tokenizer_path` in the stage config "
+                "`model_config.audio_tokenizer_path` in the model configuration "
                "or export MIMO_AUDIO_TOKENIZER_PATH."
            )
        if not os.path.exists(self.audio_tokenizer_path):
            raise ValueError(
                "Audio tokenizer not exists. Provide "
-                "`model_config.audio_tokenizer_path` in the stage config "
+                "`model_config.audio_tokenizer_path` in the model configuration "
                "or export MIMO_AUDIO_TOKENIZER_PATH."
            )
@@ -459,7 +459,7 @@ class MiMoAudioToken2WavForConditionalGenerationVLLM(nn.Module, SupportsPP):
        if not self.audio_tokenizer_path:
            raise ValueError(
                "Audio tokenizer path is not set. Provide "
-                "`model_config.audio_tokenizer_path` in the stage config "
+                "`model_config.audio_tokenizer_path` in the model configuration "
                "or export MIMO_AUDIO_TOKENIZER_PATH."
            )
@@ -45,7 +45,7 @@ class OmniNPUWorkerBase(NPUWorker):
        if self.profiler is None:
            raise RuntimeError(
                "Profiling is not enabled. For diffusion models, set --profiler-config via CLI. "
-                "For omni models, add profiler_config to your stage config file."
+                "For omni models, add profiler_config to the relevant deploy config stage."
            )
        if is_start:
            from vllm_omni.profiler import OmniTorchProfilerWrapper
@@ -74,7 +74,7 @@ class OmniGPUWorkerBase(GPUWorker):
        if self.profiler is None:
            raise RuntimeError(
                "Profiling is not enabled. For diffusion models, set --profiler-config via CLI. "
-                "For omni models, add profiler_config to your stage config file."
+                "For omni models, add profiler_config to the relevant deploy config stage."
            )
        if is_start:
            from vllm_omni.profiler import OmniTorchProfilerWrapper
@@ -23,8 +23,8 @@ logger = init_logger(__name__)
 class GPUGenerationWorker(OmniWorkerMixin, OmniGPUWorkerBase):
    """GPU Worker for Generation model (non-autoregressive waveform generation).
-    Usage in stage config:
+    Selected for stages whose pipeline topology uses
-        worker_cls: "vllm_omni.worker.gpu_generation_model_runner.GPUGenerationModelRunner"
+    ``execution_type=StageExecutionType.LLM_GENERATION``.
    """
    @instrument(span_name="Init device")
@@ -96,7 +96,7 @@ def get_process_gpu_memory(local_rank: int) -> int | None:
            except Exception as e:
                raise RuntimeError(
                    f"Failed to get NVML handle for device '{device_id}' (local_rank={local_rank}). "
-                    f"Check CUDA_VISIBLE_DEVICES or stage config 'devices' setting."
+                    f"Check CUDA_VISIBLE_DEVICES or the deploy config `devices` setting."
                ) from e
        else:
            # No CUDA_VISIBLE_DEVICES or local_rank out of range: use index directly
@@ -104,7 +104,7 @@ def get_process_gpu_memory(local_rank: int) -> int | None:
            if local_rank >= device_count:
                raise RuntimeError(
                    f"Invalid GPU device {local_rank}. Only {device_count} GPU(s) available. "
-                    f"Check CUDA_VISIBLE_DEVICES or stage config 'devices' setting."
+                    f"Check CUDA_VISIBLE_DEVICES or the deploy config `devices` setting."
                )
            handle = nvmlDeviceGetHandleByIndex(local_rank)