[Refactor] Migrate Legacy Stage Configs to the Pipeline Registry (#5031)

Signed-off-by: zwhzzz0821 <2831474076@qq.com>
Co-authored-by: zwhzzz0821 <zwhzzz0821@users.noreply.github.com>
Co-authored-by: SYLAR <125541396+lishunyang12@users.noreply.github.com>
Co-authored-by: Hongsheng Liu <liuhongsheng4@huawei.com>

docs/cli/serve.md

@@ -8,8 +8,7 @@ The stage-based CLI is designed for deployments that require launching each pipe
 - For **migrated models** that utilize the bundled deployment YAML configurations located in
   `vllm_omni/deploy/`, the `--deploy-config` flag is only required to override the default configuration. By default, executing `vllm serve MODEL --omni ...`
   automatically loads the bundled deployment configuration.
-- For **legacy models** utilizing configuration files located in
-  `vllm_omni/model_executor/stage_configs/`, the `--stage-configs-path` parameter remains mandatory.
+- For custom legacy `stage_args` YAMLs, pass the file with `--stage-configs-path`.
 
 Example: Initializing Stage 0 (Orchestrator and API Server):
 The commands below show a common device mapping where Stage 0 uses GPU 0 and

docs/configuration/stage_configs.md

@@ -3,7 +3,7 @@
 In vLLM-Omni, a model's `PipelineConfig` defines its fixed stage topology, while a deploy configuration controls how those stages run. Models that have not migrated to this split still use legacy stage configurations with a `stage_args` schema.
 
 !!! 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 neither `--stage-configs-path` nor `--deploy-config` is provided — the model registry resolves the right pipeline + deploy YAML by `model_type`. The bundled defaults have been verified on 1xH100 for Qwen2.5-Omni and 2xH100 for Qwen3-Omni. Models that have not yet migrated to the new schema continue to use the legacy `vllm_omni/model_executor/stage_configs/<model>.yaml` files via `--stage-configs-path`.
+    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 neither `--stage-configs-path` nor `--deploy-config` is provided — the model registry resolves the right pipeline + deploy YAML by `model_type`. Custom legacy `stage_args` YAMLs are still accepted via `--stage-configs-path`.
 
 ## Deploy configuration schema
 

docs/contributing/model/adding_omni_model.md

@@ -34,6 +34,7 @@ vllm_omni/model_executor/models/
 └── your_model_name/              # Model directory (e.g., qwen3_omni)
     ├── __init__.py               # Exports main model class
     ├── your_model.py             # Main unified model class
+    ├── pipeline.py               # Pipeline topology registry entry
     ├── your_model_stage1_implementation.py      # Stage 1 implementation (e.g., thinker)
     ├── your_model_stage2_implementation.py      # Stage 2 implementation (e.g., talker)
     └── your_model_stage3_implementation.py      # Stage 3 implementation (e.g., code2wav)
@@ -42,10 +43,14 @@ vllm_omni/model_executor/models/
 vllm_omni/model_executor/stage_input_processors/
 └── your_model_name.py            # Stage transition processors
 
-vllm_omni/model_executor/stage_configs/
-└── your_model_name.yaml          # Stage configuration file
+vllm_omni/deploy/
+└── your_model_name.yaml          # Deployment configuration file
 ```
 
+New in-tree models should register their `PipelineConfig` in
+`vllm_omni/config/pipeline_registry.py`; use `--stage-configs-path` only for
+custom legacy `stage_args` YAMLs.
+
 ## Step-by-Step Implementation
 
 ### Step 1: Create the Model Directory

docs/contributing/model/adding_tts_model.md

@@ -175,15 +175,16 @@ vllm_omni/model_executor/models/
   your_model_name/
     __init__.py
     your_model.py                    # Unified class (stage dispatch)
+    pipeline.py                      # Pipeline topology registry entry
     your_model_ar_stage.py           # Stage 0: AR stage
     your_model_decoder.py            # Stage 1: audio decoder
 
 vllm_omni/model_executor/stage_input_processors/
   your_model_name.py                 # Stage 0 -> Stage 1 transition
 
-vllm_omni/model_executor/stage_configs/
-  your_model_name.yaml               # Batch mode config
-  your_model_name_async_chunk.yaml   # Streaming mode config
+vllm_omni/deploy/
+  your_model_name.yaml               # Batch/deploy config
+  your_model_name_async_chunk.yaml   # Streaming/deploy config
 ```
 
 ### Example placement
@@ -445,6 +446,13 @@ Key configuration fields:
 | `final_output` | Whether this stage produces the final user-facing output |
 | `final_output_type` | Type of final output (`audio`, `text`, etc.) |
 
+!!! note
+    New in-tree models should define frozen topology in `models/<model>/pipeline.py`,
+    register it in `vllm_omni/config/pipeline_registry.py`, and put deployment
+    knobs in `vllm_omni/deploy/<model>.yaml`. Legacy `stage_args` YAMLs are still
+    accepted for custom configs via `--stage-configs-path`, but should not be used
+    for new bundled defaults.
+
 ### Batch mode
 
 ```yaml
@@ -771,8 +779,9 @@ directly from the model's own generator.
 vllm_omni/model_executor/models/your_model_name/
     __init__.py
     modeling_your_model_name.py    # unified class: load_weights + forward + streaming
+    pipeline.py                    # single-stage pipeline topology
 
-vllm_omni/model_executor/stage_configs/your_model_name.yaml
+vllm_omni/deploy/your_model_name.yaml
 ```
 
 No stage input processor is needed.