[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/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.