Merge remote-tracking branch 'origin/main' into codex-api-server-user-guide

Signed-off-by: hsliu_ustc <hsliu_ustc@noreply.gitcode.com>

# Conflicts:
#	docs/user_guide/examples/online_serving/text_to_audio.md
#	examples/online_serving/stable_audio/README.md

examples/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""vLLM-Omni example scripts, importable as a package.
+
+Keep this ``__init__.py``: with the upstream vLLM installed editable (which also
+places an ``examples`` package on ``sys.path``), a regular package at this repo
+root wins over the upstream ``examples`` namespace during ``import examples``.
+"""

examples/offline_inference/audex/README.md

@@ -17,7 +17,7 @@ Shared plumbing (corpus/WAV IO, tokenizer loading, the CFG cond/uncond
 pair contract) lives in `common.py`; each task script keeps only its own
 prompt recipe and flow. Note `text_to_audio.py` here drives the Audex
 two-stage AR pipeline — for diffusion text-to-audio models (Stable Audio
-Open, AudioX) use the generic
+Open) use the generic
 `examples/offline_inference/text_to_audio/text_to_audio.py` instead.
 
 ## text_to_speech.py — text → speech

examples/offline_inference/audex/text_to_audio.py

@@ -7,7 +7,7 @@ thinker generates interleaved 4-codebook <audiocodec_N> RVQ tokens under an
 RVQ phase mask, and the external XCodec1 checkpoint decodes them to a 16 kHz
 mono WAV.
 
-(For DIFFUSION text-to-audio models — Stable Audio Open, AudioX — use
+(For DIFFUSION text-to-audio models — Stable Audio Open — use
 ``examples/offline_inference/text_to_audio/text_to_audio.py`` instead; Audex
 TTA is a two-stage autoregressive pipeline with a different interface.)
 

examples/offline_inference/aura_omni/end2end.py

@@ -24,7 +24,6 @@ from vllm.assets.video import VideoAsset, video_to_ndarrays
 from vllm.multimodal.media.audio import load_audio
 from vllm.utils.argparse_utils import FlexibleArgumentParser
 
-from vllm_omni.engine.arg_utils import nullify_stage_engine_defaults
 from vllm_omni.entrypoints.omni import Omni
 from vllm_omni.model_executor.stage_input_processors.aura_omni import (
     DEFAULT_QWEN3_TTS_REF_TEXT,
@@ -228,7 +227,6 @@ def parse_args():
     parser.add_argument("--init-timeout", type=int, default=2000, help="Overall initialization timeout.")
     parser.add_argument("--stage-init-timeout", type=int, default=2000, help="Per-stage initialization timeout.")
     parser.add_argument("--log-stats", action="store_true", default=False, help="Enable stats logging.")
-    nullify_stage_engine_defaults(parser)
     return parser.parse_args()
 
 

examples/offline_inference/covo_audio/README.md

@@ -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) |

examples/offline_inference/covo_audio/end2end.py

@@ -59,7 +59,7 @@ def main(args):
 
     omni = Omni(
         model=args.model_name,
-        stage_configs_path=args.stage_configs_path,
+        deploy_config=args.deploy_config,
         log_stats=args.log_stats,
         stage_init_timeout=args.stage_init_timeout,
         batch_timeout=args.batch_timeout,
@@ -167,10 +167,10 @@ def parse_args():
         help="Sampling rate for audio loading (default: 16000).",
     )
     parser.add_argument(
-        "--stage-configs-path",
+        "--deploy-config",
         type=str,
         default=None,
-        help="Path to stage configs YAML file.",
+        help="Path to a deploy config YAML file.",
     )
     parser.add_argument(
         "--log-stats",

examples/offline_inference/custom_pipeline/image_to_image/image_edit.py

@@ -53,7 +53,6 @@ from typing import Any
 import torch
 from PIL import Image
 
-from vllm_omni.diffusion.data import DiffusionParallelConfig
 from vllm_omni.entrypoints.omni import Omni
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 from vllm_omni.outputs import OmniRequestOutput
@@ -139,12 +138,6 @@ async def main():
 
     # ---- Torch setup ----
     generator = torch.Generator(device=current_omni_platform.device_type).manual_seed(args.seed)
-    parallel_config = DiffusionParallelConfig(
-        ulysses_degree=args.ulysses_degree,
-        ring_degree=args.ring_degree,
-        cfg_parallel_size=args.cfg_parallel_size,
-        tensor_parallel_size=args.tensor_parallel_size,
-    )
 
     # ---- Cache Config ----
     if args.cache_backend == "cache_dit":
@@ -171,7 +164,10 @@ async def main():
         vae_use_tiling=args.vae_use_tiling,
         cache_backend=args.cache_backend,
         cache_config=cache_config,
-        parallel_config=parallel_config,
+        ulysses_degree=args.ulysses_degree,
+        ring_degree=args.ring_degree,
+        cfg_parallel_size=args.cfg_parallel_size,
+        tensor_parallel_size=args.tensor_parallel_size,
         enforce_eager=args.enforce_eager,
         enable_cpu_offload=args.enable_cpu_offload,
         diffusion_load_format="dummy",

examples/offline_inference/diffusion/lingbot_world_v2.py

@@ -0,0 +1,284 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Generate a LingBot-World v2 video from an image and camera trajectory.
+
+The official checkpoint is licensed separately under CC BY-NC-SA and is
+restricted to non-commercial use. This vLLM-Omni integration remains
+Apache-2.0 licensed.
+
+Example:
+    python examples/offline_inference/diffusion/lingbot_world_v2.py \
+        --prompt "The camera moves slowly forward through the scene." \
+        --image /path/to/first_frame.png \
+        --action-dir /path/to/actions/forward \
+        --output lingbot_world_v2.mp4
+
+``--action-dir`` must contain ``poses.npy`` and ``intrinsics.npy``. The
+example configures its parent as the trusted action root and sends the
+contained directory through ``extra_args["action_path"]``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+_MODEL = "robbyant/lingbot-world-v2-14b-causal-fast-diffusers"
+_NUM_INFERENCE_STEPS = 4
+_MAX_SEQUENCE_LENGTH = 512
+_MAX_PIXEL_AREA = 480 * 832
+_MAX_RAW_FRAMES = 117
+_MAX_SOURCE_CAMERA_FRAMES = 4096
+_TEMPORAL_COMPRESSION = 4
+_LATENT_FRAMES_PER_BLOCK = 3
+_SPATIAL_ALIGNMENT = 16
+
+
+@dataclass(frozen=True)
+class LingBotPaths:
+    image: Path
+    action_dir: Path
+    action_root: Path
+    action_relative: Path
+    camera_frames: int
+    output: Path
+
+
+def _validate_camera_arrays(action_dir: Path) -> int:
+    """Validate the bounded camera contract before starting the engine."""
+
+    try:
+        poses = np.load(action_dir / "poses.npy", mmap_mode="r", allow_pickle=False)
+        intrinsics = np.load(action_dir / "intrinsics.npy", mmap_mode="r", allow_pickle=False)
+    except (OSError, TypeError, ValueError):
+        raise ValueError("Camera files must be valid numeric poses.npy and intrinsics.npy arrays.") from None
+    if poses.ndim != 3 or poses.shape[1:] != (4, 4):
+        raise ValueError("poses.npy must have shape [frames, 4, 4].")
+    if intrinsics.ndim != 2 or intrinsics.shape[1:] != (4,):
+        raise ValueError("intrinsics.npy must have shape [frames, 4].")
+    if poses.shape[0] != intrinsics.shape[0]:
+        raise ValueError("poses.npy and intrinsics.npy must contain the same frame count.")
+    if not 1 <= poses.shape[0] <= _MAX_SOURCE_CAMERA_FRAMES:
+        raise ValueError("Camera arrays must contain between 1 and 4096 source frames.")
+    if poses.dtype.kind not in "fiu" or intrinsics.dtype.kind not in "fiu":
+        raise ValueError("Camera arrays must contain real numeric values.")
+    if not np.isfinite(poses).all() or not np.isfinite(intrinsics).all():
+        raise ValueError("Camera arrays must contain only finite values.")
+    return int(poses.shape[0])
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Generate a LingBot-World v2 video from a first-frame image and camera trajectory."
+    )
+    parser.add_argument("--model", default=_MODEL, help="Official Hugging Face model ID or local checkpoint path.")
+    parser.add_argument("--prompt", required=True, help="Text description of the scene and desired motion.")
+    parser.add_argument("--image", required=True, help="Path to the first-frame image.")
+    parser.add_argument(
+        "--action-dir",
+        required=True,
+        help="Camera action directory containing poses.npy and intrinsics.npy.",
+    )
+    parser.add_argument("--height", type=int, default=480, help="Output height; must be divisible by 16.")
+    parser.add_argument("--width", type=int, default=832, help="Output width; must be divisible by 16.")
+    parser.add_argument(
+        "--num-frames",
+        type=int,
+        default=9,
+        help="Raw output frame count. Nine frames are one three-latent-frame causal block.",
+    )
+    parser.add_argument("--seed", type=int, default=42, help="Random seed.")
+    parser.add_argument(
+        "--tensor-parallel-size",
+        type=int,
+        default=1,
+        help="Number of GPUs used for tensor parallelism inside the DiT.",
+    )
+    parser.add_argument("--flow-shift", type=float, default=5.0, help="Positive FlowUniPC scheduler shift.")
+    parser.add_argument("--fps", type=int, default=16, help="Frames per second in the exported MP4.")
+    parser.add_argument("--output", default="lingbot_world_v2.mp4", help="Output MP4 path.")
+    parser.add_argument(
+        "--enforce-eager",
+        action="store_true",
+        help="Disable compilation and force eager execution.",
+    )
+    return parser.parse_args(argv)
+
+
+def resolve_cli_paths(args: argparse.Namespace) -> LingBotPaths:
+    """Canonicalize local inputs and construct a safe trusted-root mapping."""
+
+    image = Path(args.image).expanduser().resolve()
+    if not image.is_file():
+        raise ValueError("--image must point to an existing file.")
+
+    action_dir = Path(args.action_dir).expanduser().resolve()
+    if not action_dir.is_dir():
+        raise ValueError("--action-dir must point to an existing directory.")
+    if not all((action_dir / name).is_file() for name in ("poses.npy", "intrinsics.npy")):
+        raise ValueError("--action-dir must contain poses.npy and intrinsics.npy.")
+    camera_frames = _validate_camera_arrays(action_dir)
+
+    action_root = action_dir.parent.resolve()
+    try:
+        action_relative = action_dir.relative_to(action_root)
+    except ValueError:
+        raise ValueError("--action-dir must be contained by its canonical trusted action root.") from None
+    if not action_relative.parts:
+        raise ValueError("--action-dir must name a directory contained by a trusted action root.")
+
+    output = Path(args.output).expanduser().resolve()
+    return LingBotPaths(
+        image=image,
+        action_dir=action_dir,
+        action_root=action_root,
+        action_relative=action_relative,
+        camera_frames=camera_frames,
+        output=output,
+    )
+
+
+def _positive_finite(value: float, flag: str) -> float:
+    result = float(value)
+    if not math.isfinite(result) or result <= 0:
+        raise ValueError(f"{flag} must be a positive finite number.")
+    return result
+
+
+def build_omni_kwargs(
+    args: argparse.Namespace,
+    paths: LingBotPaths,
+) -> dict[str, Any]:
+    """Build Omni configuration without overriding checkpoint class discovery."""
+
+    if args.tensor_parallel_size <= 0:
+        raise ValueError("--tensor-parallel-size must be a positive integer.")
+    flow_shift = _positive_finite(args.flow_shift, "--flow-shift")
+    model_path = Path(args.model).expanduser()
+    model = str(model_path.resolve()) if model_path.exists() else args.model
+    return {
+        "model": model,
+        "flow_shift": flow_shift,
+        "tensor_parallel_size": args.tensor_parallel_size,
+        "enforce_eager": args.enforce_eager,
+        "model_config": {"lingbot_action_root": str(paths.action_root)},
+    }
+
+
+def build_request(
+    args: argparse.Namespace,
+    paths: LingBotPaths,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Build the prompt and fixed v1 causal-DMD sampling contract."""
+
+    prompt_text = args.prompt.strip()
+    if not prompt_text:
+        raise ValueError("--prompt must contain non-whitespace text.")
+    if args.height <= 0 or args.width <= 0:
+        raise ValueError("--height and --width must be positive integers.")
+    if args.height % _SPATIAL_ALIGNMENT or args.width % _SPATIAL_ALIGNMENT:
+        raise ValueError("--height and --width must each be divisible by 16.")
+    if args.height * args.width > _MAX_PIXEL_AREA:
+        raise ValueError("--height * --width must not exceed 480 * 832 pixels.")
+    if args.num_frames <= 0:
+        raise ValueError("--num-frames must be a positive integer.")
+    if args.num_frames > _MAX_RAW_FRAMES:
+        raise ValueError("--num-frames must not exceed 117 raw frames.")
+    if args.num_frames > paths.camera_frames:
+        raise ValueError("Camera arrays must contain at least --num-frames frames.")
+    if (args.num_frames - 1) % _TEMPORAL_COMPRESSION:
+        raise ValueError("--num-frames must satisfy (num_frames - 1) divisible by 4.")
+    latent_frames = (args.num_frames - 1) // _TEMPORAL_COMPRESSION + 1
+    if latent_frames % _LATENT_FRAMES_PER_BLOCK:
+        raise ValueError("--num-frames must map to whole three-frame latent blocks.")
+    if args.fps <= 0:
+        raise ValueError("--fps must be a positive integer.")
+    flow_shift = _positive_finite(args.flow_shift, "--flow-shift")
+
+    prompt = {
+        "prompt": prompt_text,
+        "multi_modal_data": {"image": str(paths.image)},
+    }
+    sampling_kwargs = {
+        "height": args.height,
+        "width": args.width,
+        "num_frames": args.num_frames,
+        "num_inference_steps": _NUM_INFERENCE_STEPS,
+        "max_sequence_length": _MAX_SEQUENCE_LENGTH,
+        "seed": args.seed,
+        "fps": args.fps,
+        "extra_args": {
+            "action_path": paths.action_relative.as_posix(),
+            "flow_shift": flow_shift,
+        },
+    }
+    return prompt, sampling_kwargs
+
+
+def extract_video_array(outputs: Any) -> np.ndarray:
+    """Unwrap one standard Omni diffusion video into ``[frames, H, W, C]``."""
+
+    if not isinstance(outputs, list) or len(outputs) != 1:
+        raise ValueError("Expected exactly one Omni output for the single LingBot request.")
+    output = outputs[0]
+    request_output = getattr(output, "request_output", None)
+    if request_output is not None and getattr(request_output, "images", None):
+        output = request_output
+
+    images = getattr(output, "images", None)
+    if not images:
+        multimodal_output = getattr(output, "multimodal_output", None) or {}
+        images = multimodal_output.get("video")
+    if images is None:
+        raise ValueError("No video frames found in Omni output.")
+    if isinstance(images, list) and len(images) == 1:
+        images = images[0]
+
+    video: np.ndarray = np.asarray(images)
+    if video.ndim == 5:
+        if video.shape[0] != 1:
+            raise ValueError(f"Expected one generated video, got batch shape {video.shape}.")
+        video = video[0]
+    if video.ndim != 4 or video.shape[-1] not in (3, 4):
+        raise ValueError(f"Expected video shape [frames, height, width, channels], got {video.shape}.")
+    return video
+
+
+def main(argv: Sequence[str] | None = None) -> Path:
+    args = parse_args(argv)
+    paths = resolve_cli_paths(args)
+    prompt, sampling_kwargs = build_request(args, paths)
+    paths.output.parent.mkdir(parents=True, exist_ok=True)
+
+    # Keep vLLM imports below pure CLI/path validation so ``--help`` and the
+    # helper tests work on machines without the native vLLM runtime.
+    from diffusers.utils import export_to_video
+
+    from vllm_omni.entrypoints.omni import Omni
+    from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+
+    omni_kwargs = build_omni_kwargs(args, paths)
+    omni = Omni(**omni_kwargs)
+    try:
+        outputs = omni.generate(
+            prompt,
+            OmniDiffusionSamplingParams(**sampling_kwargs),
+            use_tqdm=False,
+        )
+    finally:
+        omni.close()
+
+    frames = extract_video_array(outputs)
+    export_to_video(frames, str(paths.output), fps=args.fps)
+    print(f"Saved {frames.shape[0]} frames to {paths.output}")
+    return paths.output
+
+
+if __name__ == "__main__":
+    main()

examples/offline_inference/diffusion/lingbot_world_v2_realtime.py

@@ -0,0 +1,238 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Run LingBot-World 2.0 as an in-process realtime AR-Diffusion session.
+
+This example exercises the internal session API. It is not a public HTTP or
+WebSocket protocol. Each JSONL event advances the world by one three-latent
+frame AR block and writes the latent plus its identity metadata. The current
+scoped implementation supports at most ten ticks per generation epoch because
+its image condition is bounded to 117 pixel frames; reset or create a session
+to start a new world.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import math
+import time
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+_MODEL = "robbyant/lingbot-world-v2-14b-causal-fast-diffusers"
+_CAMERA_ACTION_SCHEMA = "lingbot.camera_actions.v1"
+_FRAMES_PER_BLOCK = 3
+# ((117 pixel frames - 1) / VAE temporal factor 4 + 1) / 3 latent frames.
+_MAX_REALTIME_TICKS = 10
+
+
+def _camera_event_data(frames: list[list[str]]) -> dict[str, Any]:
+    """Build the event-side script consumed by LingBotCameraControlReducer."""
+    return {"mode": "script", "frames": frames}
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run an in-process realtime LingBot-World 2.0 session.")
+    parser.add_argument("--model", default=_MODEL, help="Hugging Face model ID or local checkpoint path.")
+    parser.add_argument("--image", required=True, help="Initial RGB image.")
+    parser.add_argument("--prompt", required=True, help="Initial scene prompt.")
+    parser.add_argument(
+        "--events",
+        required=True,
+        help="JSONL file with one prompt/action event per AR block; at most 10 events.",
+    )
+    parser.add_argument("--output-dir", required=True, help="Directory for chunk latents and metadata.")
+    parser.add_argument("--session-id", default="lingbot-world", help="Persistent world session identifier.")
+    parser.add_argument("--height", type=int, default=480)
+    parser.add_argument("--width", type=int, default=832)
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("--gpu-memory-fraction", type=float, default=0.1)
+    parser.add_argument("--tensor-parallel-size", type=int, default=1)
+    parser.add_argument("--enforce-eager", action="store_true")
+    return parser.parse_args(argv)
+
+
+def _load_events(path: Path) -> list[dict[str, Any]]:
+    events: list[dict[str, Any]] = []
+    for line_number, raw_line in enumerate(path.read_text().splitlines(), start=1):
+        line = raw_line.strip()
+        if not line:
+            continue
+        try:
+            value = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"events line {line_number} is not valid JSON: {exc.msg}.") from None
+        if not isinstance(value, dict):
+            raise ValueError(f"events line {line_number} must be a JSON object.")
+        event_id = value.get("event_id")
+        if isinstance(event_id, bool) or not isinstance(event_id, int) or event_id < 0:
+            raise ValueError(f"events line {line_number} requires a non-negative integer event_id.")
+        prompt = value.get("prompt")
+        if prompt is not None and (not isinstance(prompt, str) or not prompt.strip()):
+            raise ValueError(f"events line {line_number} prompt must be a non-empty string.")
+        frames = value.get("frames")
+        if frames is not None:
+            if not isinstance(frames, list) or len(frames) != _FRAMES_PER_BLOCK:
+                raise ValueError(f"events line {line_number} frames must contain exactly three lists.")
+            for frame in frames:
+                if not isinstance(frame, list) or any(not isinstance(action, str) for action in frame):
+                    raise ValueError(f"events line {line_number} frames must contain only action strings.")
+        if prompt is None and frames is None:
+            raise ValueError(f"events line {line_number} must update prompt and/or frames.")
+        events.append({"event_id": event_id, "prompt": prompt, "frames": frames})
+    if not events:
+        raise ValueError("events file must contain at least one event.")
+    if len(events) > _MAX_REALTIME_TICKS:
+        raise ValueError(
+            "events file must contain at most "
+            f"{_MAX_REALTIME_TICKS} events because the current LingBot realtime "
+            "image-condition horizon is 117 pixel frames."
+        )
+    event_ids = [event["event_id"] for event in events]
+    if event_ids != sorted(set(event_ids)):
+        raise ValueError("event_id values must be unique and strictly increasing.")
+    return events
+
+
+def _validate_args(args: argparse.Namespace) -> tuple[Path, Path, Path]:
+    image = Path(args.image).expanduser().resolve()
+    events = Path(args.events).expanduser().resolve()
+    output_dir = Path(args.output_dir).expanduser().resolve()
+    if not image.is_file():
+        raise ValueError("--image must point to an existing file.")
+    if not events.is_file():
+        raise ValueError("--events must point to an existing JSONL file.")
+    if not args.prompt.strip():
+        raise ValueError("--prompt must contain non-whitespace text.")
+    if args.height <= 0 or args.width <= 0 or args.height % 16 or args.width % 16:
+        raise ValueError("--height and --width must be positive multiples of 16.")
+    if args.tensor_parallel_size <= 0:
+        raise ValueError("--tensor-parallel-size must be positive.")
+    if not math.isfinite(args.gpu_memory_fraction) or not 0 < args.gpu_memory_fraction <= 1:
+        raise ValueError("--gpu-memory-fraction must be in (0, 1].")
+    return image, events, output_dir
+
+
+async def run(argv: Sequence[str] | None = None) -> Path:
+    args = parse_args(argv)
+    image, events_path, output_dir = _validate_args(args)
+    events = _load_events(events_path)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Imports stay below pure input validation so --help and helper tests do not
+    # require a CUDA-enabled vLLM installation.
+    import torch
+
+    from vllm_omni.diffusion.models.lingbot_world.actions import LingBotCameraControlReducer
+    from vllm_omni.entrypoints.async_omni import AsyncOmni
+    from vllm_omni.experimental.ar_diffusion.consumer import ARDiffusionOmniTickConsumer
+    from vllm_omni.experimental.ar_diffusion.session import (
+        ARDiffusionSessionEvent,
+        ARDiffusionSessionManager,
+        ARDiffusionWorkerLifecycle,
+    )
+    from vllm_omni.experimental.ar_diffusion.tick_protocol import ARDiffusionControlInput
+    from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+
+    engine = AsyncOmni(
+        model=args.model,
+        engine_backend="vllm_omni.experimental.ar_diffusion.engine.ARDiffusionEngine",
+        enforce_eager=args.enforce_eager,
+        tensor_parallel_size=args.tensor_parallel_size,
+        max_num_seqs=1,
+        model_config={
+            "ar_diffusion_height": args.height,
+            "ar_diffusion_width": args.width,
+            "ar_diffusion_kv_config": {
+                "gpu_memory_fraction": args.gpu_memory_fraction,
+                "warmup_cudagraph": True,
+            },
+        },
+    )
+    sampling = OmniDiffusionSamplingParams(
+        height=args.height,
+        width=args.width,
+        num_frames=9,
+        num_inference_steps=4,
+        max_sequence_length=512,
+        seed=args.seed,
+        output_type="latent",
+        extra_args={"flow_shift": 5.0},
+    )
+    consumer = ARDiffusionOmniTickConsumer(
+        engine,
+        prompt_provider=lambda tick: {
+            "prompt": tick.prompt,
+            "multi_modal_data": {"image": str(image)},
+        },
+        sampling_params_list=[sampling],
+        diffusion_stage_id=0,
+    )
+    manager = ARDiffusionSessionManager(
+        tick_consumer=consumer,
+        lifecycle=ARDiffusionWorkerLifecycle(engine, stage_ids=[0], timeout=180.0),
+        max_pending_events=32,
+        control_reducer_factory=LingBotCameraControlReducer,
+    )
+    session = await manager.create_session(args.session_id)
+    measurements: list[dict[str, Any]] = []
+    try:
+        for chunk_index, event in enumerate(events):
+            controls = ()
+            if event["frames"] is not None:
+                controls = (
+                    ARDiffusionControlInput(
+                        track="camera",
+                        schema=_CAMERA_ACTION_SCHEMA,
+                        data=_camera_event_data(event["frames"]),
+                    ),
+                )
+            await session.accept_event(
+                ARDiffusionSessionEvent(
+                    event_id=event["event_id"],
+                    prompt=event["prompt"]
+                    if event["prompt"] is not None
+                    else (args.prompt if chunk_index == 0 else None),
+                    controls=controls,
+                )
+            )
+            started = time.perf_counter()
+            output = await session.next_chunk()
+            elapsed = time.perf_counter() - started
+            if len(output.images) != 1 or not isinstance(output.images[0], torch.Tensor):
+                raise RuntimeError("Expected one latent tensor from each realtime LingBot chunk.")
+            latent = output.images[0].detach().float().cpu()
+            metadata = consumer.chunk_metadata(output).to_dict()
+            torch.save(latent, output_dir / f"chunk_{chunk_index:03d}.pt")
+            (output_dir / f"chunk_{chunk_index:03d}.json").write_text(
+                json.dumps(metadata, indent=2, sort_keys=True) + "\n"
+            )
+            measurements.append(
+                {
+                    "chunk_index": chunk_index,
+                    "latency_seconds": elapsed,
+                    "shape": list(latent.shape),
+                    "finite": bool(torch.isfinite(latent).all()),
+                    "metadata": metadata,
+                }
+            )
+            print(json.dumps(measurements[-1], sort_keys=True), flush=True)
+    finally:
+        try:
+            await manager.close_session(args.session_id)
+        finally:
+            engine.shutdown()
+
+    summary_path = output_dir / "summary.json"
+    summary_path.write_text(json.dumps({"chunks": measurements}, indent=2, sort_keys=True) + "\n")
+    return summary_path
+
+
+def main(argv: Sequence[str] | None = None) -> Path:
+    return asyncio.run(run(argv))
+
+
+if __name__ == "__main__":
+    main()

examples/offline_inference/dynin_omni/README.md

@@ -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).

examples/offline_inference/dynin_omni/end2end.py

@@ -876,7 +876,7 @@ def parse_args(repo_root: Path) -> argparse.Namespace:
     parser.add_argument("--task", type=str, required=True, choices=TASK_CHOICES)
     parser.add_argument("--model", type=str, required=True, help="HF repo id or local model directory.")
     parser.add_argument(
-        "--stage-config-path",
+        "--deploy-config",
         type=str,
         default=str(repo_root / "vllm_omni/deploy/dynin_omni.yaml"),
         help="Path to deploy config yaml.",
@@ -1394,8 +1394,8 @@ def main() -> None:
 
     from vllm_omni.entrypoints.omni import Omni
 
-    stage_config_path = str(Path(args.stage_config_path).expanduser())
-    omni = Omni(model=model_source, stage_configs_path=stage_config_path, dtype=args.dtype)
+    deploy_config_path = str(Path(args.deploy_config).expanduser())
+    omni = Omni(model=model_source, deploy_config=deploy_config_path, dtype=args.dtype)
     sampling_params_list = [
         SamplingParams(max_tokens=int(args.max_tokens_per_stage), temperature=0.0, top_p=1.0, detokenize=False)
         for _ in range(omni.num_stages)

examples/offline_inference/hunyuan_image3/README.md

@@ -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
-`--stage-configs-path` are both omitted:
+The example chooses a deploy config automatically when `--deploy-config` is
+omitted:
 
 | `--modality` | `mode` passed to Omni | Default deploy |
 | :--- | :--- | :--- |
-| `text2img` | `text-to-image` | `hunyuan_image3.yaml` |
-| `img2img` | `image-editing` | `hunyuan_image3.yaml` |
+| `text2img` | `text-to-image` | `hunyuan_image_3_moe.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"]`. |
-| Image editing | `--deploy-config vllm_omni/deploy/hunyuan_image3.yaml` | `POST /v1/images/edits`. |
+| 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_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. |
-| `--stage-configs-path` | Legacy stage config path, kept only for compatibility. Prefer `--deploy-config`. |
+| `--deploy-config` | Optional path for unified deploy YAML overrides. |
 | `--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
 

examples/offline_inference/hunyuan_image3/end2end.py

@@ -73,7 +73,6 @@ def parse_args():
     )
     parser.add_argument("--sys-type", type=str, default=None, help="Override system prompt type.")
     parser.add_argument("--deploy-config", type=str, default=None, help="Custom deploy YAML path.")
-    parser.add_argument("--stage-configs-path", type=str, default=None, help="Custom legacy stage config YAML path.")
     parser.add_argument(
         "--stream",
         action="store_true",
@@ -146,13 +145,7 @@ def main():
     else:
         bot_task = args.bot_task
 
-    if args.deploy_config is not None and args.stage_configs_path is not None:
-        raise ValueError("--deploy-config and --stage-configs-path are mutually exclusive.")
-
-    deploy_config = args.deploy_config
-    stage_configs_path = args.stage_configs_path
-    if deploy_config is None and stage_configs_path is None:
-        deploy_config = _MODALITY_DEFAULT_DEPLOY_CONFIG[args.modality]
+    deploy_config = args.deploy_config or _MODALITY_DEFAULT_DEPLOY_CONFIG[args.modality]
 
     omni_kwargs = {
         "model": args.model,
@@ -168,10 +161,7 @@ def main():
 
     if additional_config is not None:
         omni_kwargs["additional_config"] = additional_config
-    if deploy_config is not None:
-        omni_kwargs["deploy_config"] = deploy_config
-    else:
-        omni_kwargs["stage_configs_path"] = stage_configs_path
+    omni_kwargs["deploy_config"] = deploy_config
 
     omni = Omni(**omni_kwargs)
 
@@ -272,10 +262,7 @@ def main():
     print(f"  Modality: {args.modality}")
     print(f"  Prompt task: {task}")
     print(f"  Bot task: {bot_task}")
-    if deploy_config is not None:
-        print(f"  Deploy config: {deploy_config}")
-    else:
-        print(f"  Stage config: {stage_configs_path}")
+    print(f"  Deploy config: {deploy_config}")
     print(f"  Num stages: {omni.num_stages}")
     if args.modality in ("text2img", "img2img"):
         print(f"  Inference steps: {args.steps}")

examples/offline_inference/image_to_image/image_edit.py

@@ -96,7 +96,6 @@ from typing import Any
 import torch
 from PIL import Image
 
-from vllm_omni.diffusion.data import DiffusionParallelConfig
 from vllm_omni.diffusion.utils.image_output import extract_images_from_outputs
 from vllm_omni.diffusion.utils.param_utils import apply_declared_extra_args
 from vllm_omni.entrypoints.omni import Omni
@@ -452,14 +451,6 @@ def main():
 
     generator = torch.Generator(device=current_omni_platform.device_type).manual_seed(args.seed)
 
-    parallel_config = DiffusionParallelConfig(
-        ulysses_degree=args.ulysses_degree,
-        ring_degree=args.ring_degree,
-        cfg_parallel_size=args.cfg_parallel_size,
-        tensor_parallel_size=args.tensor_parallel_size,
-        enable_expert_parallel=args.enable_expert_parallel,
-    )
-
     # Configure cache based on backend type
     cache_config = None
     if args.cache_backend == "cache_dit":
@@ -490,7 +481,11 @@ def main():
         vae_use_tiling=args.vae_use_tiling,
         cache_backend=args.cache_backend,
         cache_config=cache_config,
-        parallel_config=parallel_config,
+        ulysses_degree=args.ulysses_degree,
+        ring_degree=args.ring_degree,
+        cfg_parallel_size=args.cfg_parallel_size,
+        tensor_parallel_size=args.tensor_parallel_size,
+        enable_expert_parallel=args.enable_expert_parallel,
         enable_cpu_offload=args.enable_cpu_offload,
         enable_diffusion_pipeline_profiler=args.enable_diffusion_pipeline_profiler,
         profiler_config=args.profiler_config,

examples/offline_inference/image_to_video/README.md

@@ -1,7 +1,7 @@
 # Image-To-Video
 
 This shared example generates videos from images with VACE, Wan2.2, LTX-2,
-HunyuanVideo-1.5, Cosmos3, and other compatible pipelines.
+HunyuanVideo-1.5, SANA-Video, Cosmos3, and other compatible pipelines.
 
 - `image_to_video.py`: command-line script for single video generation with advanced options.
 
@@ -27,6 +27,8 @@ This folder provides a unified CLI script for image-to-video generation using vL
 | `Wan-AI/Wan2.2-TI2V-5B-Diffusers` | 480 x 832 | 81 | 50 | 4.0 | Around 20–25 GiB BF16, smallest I2V model |
 | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_i2v` | 480 x 832 | 121 | 50 | 6.0 | Around 100 GiB at default settings; the example enables `--enable-cpu-offload` + VAE tiling/slicing to fit an 80 GiB card |
 | `Lightricks/LTX-2` | 512 x 768 | 121 | 40 | video 3.0 / audio 7.0 | Memory use depends on frame count and tensor parallelism |
+| `Efficient-Large-Model/SANA-Video_2B_480p_diffusers` | 480 x 832 | 81 | 50 | 6.0 | Native `SanaImageToVideoPipeline`; Wan VAE |
+| `Efficient-Large-Model/SANA-Video_2B_720p_diffusers` | 704 x 1280 | 81 | 50 | 6.0 | Native `SanaImageToVideoPipeline`; LTX-2 Video VAE |
 
 !!! info
     Peak VRAM: based on basic single-card usage, batch size = 1, without any acceleration/optimization features. Some model weights cannot fit into one card with 80 GiB VRAM, which may need to use CPU offloading.
@@ -96,7 +98,7 @@ if __name__ == "__main__":
         ),
     )
     from diffusers.utils import export_to_video
-    frames = outputs[0].request_output.images
+    frames = outputs[0].images
     export_to_video(frames, "quick_test_i2v.mp4", fps=16)
 ```
 
@@ -227,6 +229,48 @@ python image_to_video.py \
 See the [LTX-2 recipe](../../../recipes/LTX/LTX-2.md) for all checkpoints,
 pipeline selection, T2V, defaults, and advanced options.
 
+### SANA-Video-2B
+
+The checkpoint metadata selects the upstream T2V pipeline, so pass
+`SanaImageToVideoPipeline` explicitly for I2V:
+
+```bash
+python image_to_video.py \
+  --model Efficient-Large-Model/SANA-Video_2B_480p_diffusers \
+  --model-class-name SanaImageToVideoPipeline \
+  --image cherry_blossom.jpg \
+  --prompt "Cherry blossoms sway in the breeze as petals drift past the camera." \
+  --negative-prompt "blurry, low quality, temporal artifacts" \
+  --height 480 \
+  --width 832 \
+  --num-frames 81 \
+  --num-inference-steps 50 \
+  --guidance-scale 6.0 \
+  --extra-body '{"motion_score": 30}' \
+  --fps 16 \
+  --seed 42 \
+  --output sana_video_i2v_480p.mp4
+```
+
+Use the 720p checkpoint with `--height 704 --width 1280`. In this example,
+81 frames at 16 FPS means the standard approximately five-second SANA-Video
+checkpoint request. It does not enable the separate LongSANA/LongLive
+minute-scale autoregressive workflow.
+
+The native `SanaImageToVideoPipeline` supports both checkpoint variants. The
+480p path uses vLLM-Omni's `DistributedAutoencoderKLWan` wrapper and the 720p
+path uses `DistributedAutoencoderKLLTX2Video`; both wrap their corresponding
+Diffusers VAE implementations. The native denoising loop intentionally keeps
+Diffusers' checkpoint-compatible `DPMSolverMultistepScheduler`.
+
+The Diffusers adapter has completed end-to-end I2V serving validation at both
+480p and 720p. For online adapter serving, select the matching checkpoint and
+use `WIDTH=1280 HEIGHT=704` for the 720p request. Adapter T2V is also validated
+at both resolutions; see the recipe for the exact backend matrix.
+
+See the [SANA-Video recipe](../../../recipes/NVIDIA/SANA-Video-2B.md) for
+online serving, native/adapter validation boundaries, and hardware notes.
+
 ## Advanced Features
 
 ### CFG Parallel

examples/offline_inference/image_to_video/image_to_video.py

@@ -1,15 +1,16 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 """
 Image-to-Video generation example using Wan2.2 I2V/TI2V models, LTX2/LTX-2.3,
-HunyuanVideo-1.5, Cosmos3, or Wan2.1 VACE.
+HunyuanVideo-1.5, SANA-Video, Cosmos3, or Wan2.1 VACE.
 
 Supports:
 - Wan2.2-I2V-A14B-Diffusers: MoE model with CLIP image encoder
 - Wan2.2-TI2V-5B-Diffusers: Unified T2V+I2V model (dense 5B)
 - LTX2 image-to-video pipeline
 - HunyuanVideo-1.5 I2V: SigLIP + VAE dual image conditioning
+- SANA-Video 2B: first-frame latent conditioning at 480p or 720p
 - Wan2.1 VACE: first/last-frame, inpainting, and reference conditioning
 
 Usage:
@@ -38,6 +39,13 @@ Usage:
         --image input.jpg --prompt "A cat playing with yarn" \
         --flow-shift 5.0 --guidance-scale 6.0
 
+    # SANA-Video 2B I2V (480p)
+    python image_to_video.py --model Efficient-Large-Model/SANA-Video_2B_480p_diffusers \
+        --model-class-name SanaImageToVideoPipeline \
+        --image input.jpg --prompt "A cat turns toward the camera." \
+        --height 480 --width 832 --num-frames 81 --num-inference-steps 50 \
+        --guidance-scale 6.0
+
     # Cosmos3 I2V (image conditioning)
     python image_to_video.py --model nvidia/Cosmos3-Nano \
         --image input.jpg --prompt "The scene comes to life with smooth, natural motion." \
@@ -56,7 +64,6 @@ import numpy as np
 import PIL.Image
 import torch
 
-from vllm_omni.diffusion.data import DiffusionParallelConfig
 from vllm_omni.diffusion.utils.param_utils import apply_declared_extra_args
 from vllm_omni.entrypoints.omni import Omni
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
@@ -68,6 +75,7 @@ from vllm_omni.model_extras import (
 from vllm_omni.model_extras import (
     get_extra_body_params,
     get_model_class_name,
+    should_preserve_reference_image_size,
 )
 from vllm_omni.outputs import OmniRequestOutput
 from vllm_omni.platforms import current_omni_platform
@@ -103,17 +111,27 @@ def build_image_to_video_prompt(
     return result
 
 
+def _validate_video_output_type(output_type: str) -> None:
+    if output_type not in {"image", "video"}:
+        raise ValueError(
+            f"Unexpected output type '{output_type}', expected 'video' or legacy 'image' for video generation."
+        )
+
+
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
         description=(
             "Generate a video from one or more images "
-            "(Wan2.2, LTX2/LTX-2.3, HunyuanVideo-1.5, Cosmos3, or Wan2.1 VACE)."
+            "(Wan2.2, LTX2/LTX-2.3, HunyuanVideo-1.5, SANA-Video, Cosmos3, or Wan2.1 VACE)."
         )
     )
     parser.add_argument(
         "--model",
         default="Wan-AI/Wan2.2-I2V-A14B-Diffusers",
-        help="Diffusers I2V model ID or local path (Wan2.2, LTX2/LTX-2.3, HunyuanVideo-1.5, Cosmos3, or Wan2.1 VACE).",
+        help=(
+            "Diffusers I2V model ID or local path "
+            "(Wan2.2, LTX2/LTX-2.3, HunyuanVideo-1.5, SANA-Video, Cosmos3, or Wan2.1 VACE)."
+        ),
     )
     parser.add_argument(
         "--model-class-name",
@@ -377,6 +395,7 @@ def main():
     is_ltx2_distilled = "distilled" in model_class_name_lower or "distilled" in model_name
     is_ltx23 = "ltx23" in model_class_name_lower or "ltx-2.3" in model_name
     is_ltx2 = is_ltx2_distilled or is_ltx23 or "ltx2" in model_class_name_lower or "ltx-2" in model_name
+    is_sana = model_class_name == "SanaImageToVideoPipeline" or "sana-video" in model_name
     is_cosmos = "cosmos" in model_name or (model_class_name is not None and "cosmos" in model_class_name.lower())
     is_cosmos_edge = is_cosmos and ("edge" in model_name or "edge" in model_class_name_lower)
 
@@ -434,6 +453,17 @@ def main():
             512 * 768,
             32,
         )
+    elif is_sana:
+        is_720p = "720p" in model_name
+        d_fps, d_guidance, d_num_frames, d_steps, d_flow_shift, d_max_area, d_mod = (
+            16,
+            6.0,
+            81,
+            50,
+            5.0,
+            (704 * 1280) if is_720p else (480 * 832),
+            32 if is_720p else 16,
+        )
     else:  # Wan2.2 / HunyuanVideo-1.5
         d_fps, d_guidance, d_num_frames, d_steps, d_flow_shift, d_max_area, d_mod = 16, 5.0, 81, 50, 5.0, 480 * 832, 16
 
@@ -454,7 +484,13 @@ def main():
 
     media_inputs: dict[str, Any] = {}
     if image is not None:
-        media_inputs["image"] = image.resize((width, height), PIL.Image.Resampling.LANCZOS)
+        preserve_image_size = should_preserve_reference_image_size(
+            model_class_name,
+            model=args.model,
+        )
+        media_inputs["image"] = (
+            image if preserve_image_size else image.resize((width, height), PIL.Image.Resampling.LANCZOS)
+        )
     if last_image is not None:
         media_inputs["last_image"] = last_image.resize((width, height), PIL.Image.Resampling.LANCZOS)
     if mask_image is not None:
@@ -496,17 +532,6 @@ def main():
         }
 
     profiler_enabled = args.profiler_config is not None
-    parallel_config = DiffusionParallelConfig(
-        ulysses_degree=args.ulysses_degree,
-        ring_degree=args.ring_degree,
-        cfg_parallel_size=args.cfg_parallel_size,
-        tensor_parallel_size=args.tensor_parallel_size,
-        vae_patch_parallel_size=args.vae_patch_parallel_size,
-        use_hsdp=args.use_hsdp,
-        hsdp_shard_size=args.hsdp_shard_size,
-        hsdp_replicate_size=args.hsdp_replicate_size,
-        pipeline_parallel_size=args.pipeline_parallel_size,
-    )
     omni_kwargs = dict(
         model=args.model,
         enable_layerwise_offload=args.enable_layerwise_offload,
@@ -517,7 +542,15 @@ def main():
         diffusion_kv_cache_skip_steps=args.diffusion_kv_cache_skip_steps,
         diffusion_kv_cache_skip_layers=args.diffusion_kv_cache_skip_layers,
         enable_cpu_offload=args.enable_cpu_offload,
-        parallel_config=parallel_config,
+        ulysses_degree=args.ulysses_degree,
+        ring_degree=args.ring_degree,
+        cfg_parallel_size=args.cfg_parallel_size,
+        tensor_parallel_size=args.tensor_parallel_size,
+        vae_patch_parallel_size=args.vae_patch_parallel_size,
+        use_hsdp=args.use_hsdp,
+        hsdp_shard_size=args.hsdp_shard_size,
+        hsdp_replicate_size=args.hsdp_replicate_size,
+        pipeline_parallel_size=args.pipeline_parallel_size,
         enforce_eager=args.enforce_eager,
         model_class_name=model_class_name,
         cache_backend=args.cache_backend,
@@ -639,10 +672,7 @@ def main():
         frames = frames[0] if frames else None
 
     if isinstance(frames, OmniRequestOutput):
-        if frames.final_output_type != "image":
-            raise ValueError(
-                f"Unexpected output type '{frames.final_output_type}', expected 'image' for video generation."
-            )
+        _validate_video_output_type(frames.final_output_type)
         if frames.multimodal_output and "audio" in frames.multimodal_output:
             audio = frames.multimodal_output["audio"]
             audio_sample_rate = frames.multimodal_output.get("audio_sample_rate", audio_sample_rate)

examples/offline_inference/lance/end2end.py

@@ -82,9 +82,6 @@ def parse_args():
     # ``max_num_seqs=1`` …) are passed as flat kwargs to ``Omni`` below
     # and ``create_default_diffusion`` materializes the stage config.
 
-    from vllm_omni.engine.arg_utils import nullify_stage_engine_defaults
-
-    nullify_stage_engine_defaults(p)
     return p.parse_args()
 
 

examples/offline_inference/longcat_video/end2end.py

@@ -15,7 +15,6 @@ import imageio
 import numpy as np
 import torch
 
-from vllm_omni.diffusion.data import DiffusionParallelConfig
 from vllm_omni.diffusion.models.longcat_video.pipeline_longcat_video_avatar import (
     prepare_longcat_video_avatar_model_for_omni,
 )
@@ -236,14 +235,6 @@ def main():
         dtype="bfloat16",
         enforce_eager=args.enforce_eager,
         additional_config=additional_config,
-        parallel_config=DiffusionParallelConfig(
-            ulysses_degree=1,
-            ring_degree=1,
-            cfg_parallel_size=1,
-            tensor_parallel_size=1,
-            vae_patch_parallel_size=1,
-            pipeline_parallel_size=1,
-        ),
     )
 
     audio_input: str | dict[str, str] | None = args.audio

examples/offline_inference/mimo_audio/README.md

@@ -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

examples/offline_inference/ming_flash_omni/README.md

@@ -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)).
 

examples/offline_inference/minicpmo/README.md

@@ -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
 

examples/offline_inference/minicpmo/end2end.py

@@ -335,7 +335,7 @@ def main(args):
     print(f"use_tts (tts_bos): {use_tts}")
 
     for stage_outputs in omni_generator:
-        output = stage_outputs.request_output
+        output = stage_outputs
         if stage_outputs.final_output_type == "text":
             request_id = output.request_id
             text_output = output.outputs[0].text
@@ -452,12 +452,6 @@ def parse_args():
         default=None,
         help="Path to a .txt file with one prompt per line (preferred).",
     )
-    parser.add_argument(
-        "--stage-configs-path",
-        type=str,
-        default=None,
-        help="Path to a stage configs file (deprecated; prefer --deploy-config).",
-    )
     parser.add_argument(
         "--deploy-config",
         type=str,

examples/offline_inference/minimax_h3/dlo_lifecycle.py

@@ -1,21 +1,32 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-"""Reproduce MiniMax-H3 request-mode and DLO/DP2 lifecycle behavior.
+"""Validate MiniMax-H3 request-mode and DLO lifecycle behavior.
+
+The DLO modes accept any positive data-parallel size.  With AllGather enabled,
+the script submits one complete DP wave and verifies recovery after an invalid
+wave.  It also checks that every mode shuts down all worker processes cleanly.
 
 Examples:
 
     VLLM_WORKER_MULTIPROC_METHOD=spawn \
     VLLM_OMNI_VIDEO_SYNC_TIMEOUT=14400 \
     VLLM_OMNI_DLO_DP_WAVE_TIMEOUT=600 \
+    CUDA_VISIBLE_DEVICES=0,1,2,3 \
+    python examples/offline_inference/minimax_h3/dlo_lifecycle.py \
+        --model /path/to/MiniMax-H3/FL2VA --mode dlo --dp-size 4
+
+    # Rank-local mmap storage, with no DLO collective or DP wave scheduling.
+    VLLM_WORKER_MULTIPROC_METHOD=spawn \
+    VLLM_OMNI_VIDEO_SYNC_TIMEOUT=14400 \
     CUDA_VISIBLE_DEVICES=0,1 \
-    python examples/offline_inference/minimax_h3/dlo_dp2_lifecycle.py \
-        --model /path/to/MiniMax-H3/FL2VA --mode dlo-dp2
+    python examples/offline_inference/minimax_h3/dlo_lifecycle.py \
+        --model /path/to/MiniMax-H3/FL2VA --mode dlo-no-allgather --dp-size 2
 
     VLLM_WORKER_MULTIPROC_METHOD=spawn \
     VLLM_OMNI_VIDEO_SYNC_TIMEOUT=14400 \
     CUDA_VISIBLE_DEVICES=0,1 \
-    python examples/offline_inference/minimax_h3/dlo_dp2_lifecycle.py \
-        --model /path/to/MiniMax-H3/FL2VA --mode request
+    python examples/offline_inference/minimax_h3/dlo_lifecycle.py \
+        --model /path/to/MiniMax-H3/FL2VA --mode request --tp-size 2
 """
 
 from __future__ import annotations
@@ -40,14 +51,33 @@ DEFAULT_PROMPTS = (
 )
 
 
+def positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 1:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return parsed
+
+
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--model", required=True, help="Path to MiniMax-H3/FL2VA")
     parser.add_argument(
         "--mode",
-        choices=("dlo-dp2", "request"),
+        choices=("dlo", "dlo-no-allgather", "request"),
         required=True,
-        help="DLO AllGather DP2 or ordinary non-DLO TP2 request mode",
+        help="DLO (with or without AllGather) or ordinary non-DLO request mode",
+    )
+    parser.add_argument(
+        "--dp-size",
+        type=positive_int,
+        default=2,
+        help="DLO data-parallel size (for example 1, 2, 4, or 8; default: 2)",
+    )
+    parser.add_argument(
+        "--tp-size",
+        type=positive_int,
+        default=2,
+        help="Tensor-parallel size used only by request mode (default: 2)",
     )
     parser.add_argument("--steps", type=int, default=2)
     parser.add_argument("--duration", type=float, default=5.0)
@@ -60,10 +90,11 @@ def parse_args() -> argparse.Namespace:
 
 
 def engine_kwargs(args: argparse.Namespace) -> dict[str, Any]:
+    is_dlo = args.mode in {"dlo", "dlo-no-allgather"}
     common: dict[str, Any] = {
         "model": args.model,
         "trust_remote_code": True,
-        "num_gpus": 2,
+        "num_gpus": args.dp_size if is_dlo else args.tp_size,
         "usp": 1,
         "ring": 1,
         "vae_parallel_mode": "tile",
@@ -74,22 +105,22 @@ def engine_kwargs(args: argparse.Namespace) -> dict[str, Any]:
         "stage_init_timeout": args.init_timeout,
         "init_timeout": args.init_timeout,
     }
-    if args.mode == "dlo-dp2":
+    if is_dlo:
         common.update(
             tensor_parallel_size=1,
-            data_parallel_size=2,
+            data_parallel_size=args.dp_size,
             text_encoder_tp_size=1,
             vae_patch_parallel_size=1,
             enable_distributed_layerwise_offload=True,
-            dlo_use_allgather=True,
+            dlo_use_allgather=args.mode == "dlo",
             dlo_resident_layers=0,
         )
     else:
         common.update(
-            tensor_parallel_size=2,
+            tensor_parallel_size=args.tp_size,
             data_parallel_size=1,
-            text_encoder_tp_size=2,
-            vae_patch_parallel_size=2,
+            text_encoder_tp_size=args.tp_size,
+            vae_patch_parallel_size=args.tp_size,
             enable_distributed_layerwise_offload=False,
         )
     return common
@@ -172,7 +203,8 @@ async def run(args: argparse.Namespace) -> dict[str, Any]:
         "engine_kwargs": engine_kwargs(args),
     }
     try:
-        if args.mode == "dlo-dp2":
+        uses_dp_wave = args.mode == "dlo" and args.dp_size > 1
+        if uses_dp_wave:
             started = time.perf_counter()
             asymmetric = await asyncio.gather(
                 generate_one(
@@ -182,12 +214,15 @@ async def run(args: argparse.Namespace) -> dict[str, Any]:
                     prompt="",
                     seed=1001,
                 ),
-                generate_one(
-                    engine,
-                    args,
-                    request_id="invalid-peer",
-                    prompt=DEFAULT_PROMPTS[0],
-                    seed=1002,
+                *(
+                    generate_one(
+                        engine,
+                        args,
+                        request_id=f"invalid-peer-{index}",
+                        prompt=DEFAULT_PROMPTS[index % len(DEFAULT_PROMPTS)],
+                        seed=1001 + index,
+                    )
+                    for index in range(1, args.dp_size)
                 ),
                 return_exceptions=True,
             )
@@ -195,18 +230,18 @@ async def run(args: argparse.Namespace) -> dict[str, Any]:
             summary["asymmetric_errors"] = [
                 f"{type(result).__name__}: {result}" for result in asymmetric if isinstance(result, BaseException)
             ]
-            if len(summary["asymmetric_errors"]) != 2:
-                raise RuntimeError("Both requests in the asymmetric DP wave must fail before dispatch")
+            if len(summary["asymmetric_errors"]) != args.dp_size:
+                raise RuntimeError("Every request in the asymmetric DP wave must fail before dispatch")
 
         started = time.perf_counter()
-        request_count = 2 if args.mode == "dlo-dp2" else 1
+        request_count = args.dp_size if uses_dp_wave else 1
         outputs = await asyncio.gather(
             *(
                 generate_one(
                     engine,
                     args,
                     request_id=f"recovery-{index}",
-                    prompt=DEFAULT_PROMPTS[index],
+                    prompt=DEFAULT_PROMPTS[index % len(DEFAULT_PROMPTS)],
                     seed=2000 + index,
                 )
                 for index in range(request_count)

examples/offline_inference/nemotron_voicechat/end2end.py

@@ -67,7 +67,7 @@ def main() -> None:
     parser.add_argument("--output-dir", default="results/nemotron_voicechat")
     parser.add_argument("--system-prompt", default=DEFAULT_SYSTEM_PROMPT)
     parser.add_argument(
-        "--stage-configs-path",
+        "--deploy-config",
         default=None,
         help=(
             "Deploy yaml override. Pass vllm_omni/deploy/nemotron_labs_voicechat_streaming.yaml "
@@ -134,8 +134,8 @@ def main() -> None:
     ]
 
     omni_kwargs: dict = {}
-    if args.stage_configs_path:
-        omni_kwargs["stage_configs_path"] = args.stage_configs_path
+    if args.deploy_config:
+        omni_kwargs["deploy_config"] = args.deploy_config
     omni = Omni(model=str(ckpt), trust_remote_code=True, **omni_kwargs)
     outputs = omni.generate(inputs, sampling_params_list)
 

examples/offline_inference/qwen2_5_omni/README.md

@@ -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
 

examples/offline_inference/qwen3_omni/README.md

@@ -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.
-   ``qwen3_omni_moe.yaml``).
+1. A deploy YAML with ``async_chunk: true`` (for example, an overlay based on
+   ``vllm_omni/deploy/qwen3_omni_moe.yaml``).
 2. Hardware that matches the config (e.g. 2x H100 for the default 3-stage
    config).
 
@@ -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

examples/offline_inference/qwen3_omni/end2end.py

@@ -484,10 +484,10 @@ def parse_args():
         help="Path to a .txt file with one prompt per line (preferred).",
     )
     parser.add_argument(
-        "--stage-configs-path",
+        "--deploy-config",
         type=str,
         default=None,
-        help="Path to a stage configs file.",
+        help="Path to a deploy config YAML.",
     )
     parser.add_argument(
         "--video-path",

examples/offline_inference/qwen3_omni/end2end_async_chunk.py

@@ -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
-        # in the YAML for each stage).
+        # Use default sampling params from the resolved pipeline and deploy
+        # 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

examples/offline_inference/speech_to_video/speech_to_video.py

@@ -23,7 +23,6 @@ from typing import Any
 
 import torch
 
-from vllm_omni.diffusion.data import DiffusionParallelConfig
 from vllm_omni.entrypoints.omni import Omni
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 from vllm_omni.platforms import current_omni_platform
@@ -250,17 +249,6 @@ def main():
             "scm_steps_policy": "dynamic",
         }
 
-    parallel_config = DiffusionParallelConfig(
-        tensor_parallel_size=args.tensor_parallel_size,
-        cfg_parallel_size=args.cfg_parallel_size,
-        vae_patch_parallel_size=args.vae_patch_parallel_size,
-        ring_degree=args.ring_degree,
-        ulysses_degree=args.ulysses_degree,
-        use_hsdp=args.use_hsdp,
-        hsdp_shard_size=args.hsdp_shard_size,
-        hsdp_replicate_size=args.hsdp_replicate_size,
-    )
-
     profiler_enabled = args.profiler_config is not None
 
     omni_kwargs = dict(
@@ -271,7 +259,14 @@ def main():
         vae_use_tiling=args.vae_use_tiling,
         enable_cpu_offload=args.enable_cpu_offload,
         enable_layerwise_offload=args.enable_layerwise_offload,
-        parallel_config=parallel_config,
+        tensor_parallel_size=args.tensor_parallel_size,
+        cfg_parallel_size=args.cfg_parallel_size,
+        vae_patch_parallel_size=args.vae_patch_parallel_size,
+        ring_degree=args.ring_degree,
+        ulysses_degree=args.ulysses_degree,
+        use_hsdp=args.use_hsdp,
+        hsdp_shard_size=args.hsdp_shard_size,
+        hsdp_replicate_size=args.hsdp_replicate_size,
         enforce_eager=args.enforce_eager,
         enable_diffusion_pipeline_profiler=args.enable_diffusion_pipeline_profiler,
         cache_backend=args.cache_backend,

examples/offline_inference/step_audio2/README.md

@@ -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 \

examples/offline_inference/step_audio2/end2end.py

@@ -232,15 +232,8 @@ def main(args):
         raise ValueError(f"Unknown query type: {args.query_type}")
 
     # Initialize vLLM-Omni with Step-Audio2
-    # Resolve deploy config path. Keep explicit stage_configs_path for legacy
-    # custom configs, but use bundled deploy configs by default.
-    deploy_config_path = None
-    stage_config_path = None
-    if args.stage_configs_path and args.deploy_config:
-        raise ValueError("--stage-configs-path and --deploy-config are mutually exclusive")
-    if args.stage_configs_path:
-        stage_config_path = args.stage_configs_path
-    elif args.deploy_config:
+    # Resolve an explicit deploy config or use the bundled task default.
+    if args.deploy_config:
         deploy_config_path = args.deploy_config
     else:
         configs_dir = Path(__file__).parent.parent.parent.parent / "vllm_omni/deploy"
@@ -262,10 +255,7 @@ def main(args):
         "ray_address": args.ray_address,
         "trust_remote_code": True,
     }
-    if stage_config_path is not None:
-        omni_kwargs["stage_configs_path"] = stage_config_path
-    else:
-        omni_kwargs["deploy_config"] = deploy_config_path
+    omni_kwargs["deploy_config"] = deploy_config_path
 
     omni_llm = Omni(**omni_kwargs)
 
@@ -418,12 +408,6 @@ def parse_args():
             "  - HuggingFace ID: stepfun-ai/Step-Audio-2-mini"
         ),
     )
-    parser.add_argument(
-        "--stage-configs-path",
-        type=str,
-        default=None,
-        help="Path to a legacy stage config YAML file (default: use bundled deploy config)",
-    )
     parser.add_argument(
         "--deploy-config",
         type=str,

examples/offline_inference/text_to_audio/README.md

@@ -1,11 +1,10 @@
 # Text-To-Audio
 
-A unified script for text/video-to-audio generation. Supported models:
+A unified script for text-to-audio generation. Supported models:
 
 | Model | Tasks | Notes |
 |-------|-------|-------|
 | `stabilityai/stable-audio-open-1.0` | text-to-audio | gated; uses `--audio-length` |
-| `zhangj1an/AudioX` | `t2a` / `t2m` / `v2a` / `v2m` / `tv2a` / `tv2m` | pass `--task`; video tasks need `--video` |
 
 The `stabilityai/stable-audio-open-1.0` pipeline generates audio from text prompts.
 
@@ -50,42 +49,12 @@ python text_to_audio.py \
   --output stable_audio_output.wav
 ```
 
-### AudioX
-
-AudioX supports six tasks. Sampler and reference knobs (declared in
-`vllm_omni/model_extras/audiox.py`) are passed via the generic `--extra-body`
-JSON flag, routed into sampling `extra_args`.
-
-Text tasks (`t2a` / `t2m`):
-
-```bash
-python text_to_audio.py \
-  --model zhangj1an/AudioX --task t2a \
-  --prompt "Fireworks burst twice, followed by a clock ticking." \
-  --num-inference-steps 250 --guidance-scale 6.0 --audio-length 10.0 --seed 42 \
-  --extra-body '{"sigma_min": 0.03, "sigma_max": 1000.0}' \
-  --output t2a.wav
-```
-
-Video-conditioned tasks (`v2a` / `v2m` / `tv2a` / `tv2m`) require `--video`:
-
-```bash
-python text_to_audio.py \
-  --model zhangj1an/AudioX --task tv2a \
-  --prompt "drum beating sound and human talking" \
-  --video https://zeyuet.github.io/AudioX/static/samples/V2M/1XeBotOFqHA.mp4 \
-  --num-inference-steps 250 --guidance-scale 6.0 --audio-length 10.0 \
-  --output tv2a.wav
-```
-
 Key arguments:
 
 - `--prompt`: text description (string).
-- `--task`: [AudioX] one of `t2a`/`t2m`/`v2a`/`v2m`/`tv2a`/`tv2m`.
-- `--video`: [AudioX `v2*`/`tv2*`] video file/URL for conditioning (→ `video_path`).
-- `--audio-start`: audio start offset in seconds (→ `audio_start_in_s` for Stable Audio, `seconds_start` for AudioX).
-- `--audio-length`: audio duration in seconds (audio length for Stable Audio, `seconds_total` for AudioX).
-- `--extra-body`: JSON dict of model-specific knobs (declared in `vllm_omni/model_extras/`), merged into sampling `extra_args`. For AudioX, sampler/reference knobs go here, e.g. `'{"sigma_min": 0.03, "sigma_max": 1000.0, "cfg_rescale": 0.0, "audio_path": "ref.wav"}'`.
+- `--audio-start`: audio start offset in seconds (→ `audio_start_in_s`).
+- `--audio-length`: audio duration in seconds (audio length for Stable Audio).
+- `--extra-body`: JSON dict of model-specific knobs, merged into sampling `extra_args`.
 - `--negative-prompt`: negative prompt for classifier-free guidance.
 - `--seed`: integer seed for deterministic generation.
 - `--guidance-scale`: classifier-free guidance scale.

examples/offline_inference/text_to_audio/text_to_audio.py

@@ -2,15 +2,13 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 
 """
-Example script for text/video-to-audio generation with diffusion audio models.
+Example script for text-to-audio generation with diffusion audio models.
 
 This script supports:
   * Stable Audio Open (`stabilityai/stable-audio-open-1.0`) — text-to-audio.
-  * AudioX (`zhangj1an/AudioX`) — six tasks: t2a / t2m / v2a / v2m / tv2a / tv2m.
 
-Model-specific generation knobs are declared in `vllm_omni/model_extras` and
-routed into `sampling_params.extra_args` via `apply_declared_extra_args`, so
-the same script serves both models without per-model branching in the engine.
+Model-specific generation knobs can be passed via `--extra-body` and are
+merged into `sampling_params.extra_args`.
 
 Usage:
     # Stable Audio Open
@@ -18,15 +16,6 @@ Usage:
     python text_to_audio.py --prompt "A piano playing a gentle melody" --audio-length 10.0
     python text_to_audio.py --prompt "Thunder and rain sounds" --negative-prompt "Low quality"
     python text_to_audio.py --prompt "A soft synth pad" --cache-backend tea_cache
-
-    # AudioX (text-to-audio / text-to-music)
-    python text_to_audio.py --model zhangj1an/AudioX --task t2a \
-        --prompt "Fireworks burst twice, then a clock ticking." \
-        --num-inference-steps 250 --guidance-scale 6.0 --audio-length 10.0
-    # AudioX video-conditioned (v2*/tv2*) — pass a video file/URL
-    python text_to_audio.py --model zhangj1an/AudioX --task tv2a \
-        --prompt "drum beating sound and human talking" --video clip.mp4 \
-        --extra-body '{"sigma_min": 0.03, "sigma_max": 1000.0}'
 """
 
 import argparse
@@ -38,17 +27,11 @@ from typing import Any
 import numpy as np
 import torch
 
-from vllm_omni.diffusion.data import DiffusionParallelConfig
-from vllm_omni.diffusion.utils.param_utils import apply_declared_extra_args
 from vllm_omni.entrypoints.omni import Omni
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
-from vllm_omni.model_extras import get_extra_body_params, get_model_class_name
 from vllm_omni.outputs import OmniRequestOutput
 from vllm_omni.platforms import current_omni_platform
 
-AUDIOX_TASKS = ("t2a", "t2m", "v2a", "v2m", "tv2a", "tv2m")
-AUDIOX_VIDEO_TASKS = frozenset({"v2a", "v2m", "tv2a", "tv2m"})
-
 
 def parse_extra_body(value: str) -> dict[str, Any]:
     """Parse a JSON object string for --extra-body."""
@@ -66,7 +49,7 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument(
         "--model",
         default="stabilityai/stable-audio-open-1.0",
-        help="Audio diffusion model name or local path. Supported: stabilityai/stable-audio-open-1.0, zhangj1an/AudioX.",
+        help="Audio diffusion model name or local path. Supported: stabilityai/stable-audio-open-1.0.",
     )
     parser.add_argument(
         "--prompt",
@@ -97,19 +80,13 @@ def parse_args() -> argparse.Namespace:
         "--audio-start",
         type=float,
         default=0.0,
-        help=(
-            "Audio start offset in seconds. Applies to both models "
-            "(audio_start_in_s for Stable Audio, seconds_start for AudioX)."
-        ),
+        help="Audio start offset in seconds (maps to audio_start_in_s).",
     )
     parser.add_argument(
         "--audio-length",
         type=float,
         default=10.0,
-        help=(
-            "Audio duration in seconds. Maps to audio length for Stable Audio "
-            "(max ~47s for stable-audio-open-1.0) and seconds_total for AudioX."
-        ),
+        help=("Audio duration in seconds. Maps to audio length for Stable Audio (max ~47s for stable-audio-open-1.0)."),
     )
     parser.add_argument(
         "--num-inference-steps",
@@ -123,41 +100,20 @@ def parse_args() -> argparse.Namespace:
         default=1,
         help="Number of audio waveforms to generate for the given prompt.",
     )
-    parser.add_argument(
-        "--task",
-        type=str,
-        default=None,
-        choices=list(AUDIOX_TASKS),
-        help=(
-            "[AudioX only] Generation task: t2a/t2m/v2a/v2m/tv2a/tv2m. "
-            "v2*/tv2* require --video. Ignored for Stable Audio Open."
-        ),
-    )
-    parser.add_argument(
-        "--video",
-        type=str,
-        default=None,
-        help="[AudioX v2*/tv2*] Video file path or URL used for conditioning.",
-    )
     parser.add_argument(
         "--extra-body",
         type=parse_extra_body,
         default=None,
         help=(
-            "Model-specific generation params as a JSON object, e.g. "
-            '\'{"sigma_min": 0.03, "sigma_max": 1000.0}\'. Each key is filtered '
-            "against the model's declared extra_body_params (see vllm_omni/model_extras), "
-            "so unknown keys are silently dropped. Values here override the equivalent flags."
+            "Model-specific generation params as a JSON object, merged into "
+            "sampling extra_args. Values here override the equivalent flags."
         ),
     )
     parser.add_argument(
         "--output",
         type=str,
         default=None,
-        help=(
-            "Path to save the generated audio (WAV format). Defaults to "
-            "audiox_output.wav for AudioX and stable_audio_output.wav otherwise."
-        ),
+        help=("Path to save the generated audio (WAV format). Defaults to stable_audio_output.wav."),
     )
     parser.add_argument(
         "--sample-rate",
@@ -276,8 +232,6 @@ def save_audio(audio_data: np.ndarray, output_path: str, sample_rate: int = 4410
 
 def main():
     args = parse_args()
-    model_name = str(args.model).lower() if args.model else ""
-    is_audiox = "audiox" in model_name
     generator = torch.Generator(device=current_omni_platform.device_type).manual_seed(args.seed)
     cache_config = None
     if args.cache_backend == "tea_cache":
@@ -286,11 +240,9 @@ def main():
         }
 
     print(f"\n{'=' * 60}")
-    print("Text/Video-to-Audio Generation")
+    print("Text-to-Audio Generation")
     print(f"{'=' * 60}")
     print(f"  Model: {args.model}")
-    if args.task is not None:
-        print(f"  Task: {args.task}")
     print(f"  Prompt: {args.prompt}")
     print(f"  Negative prompt: {args.negative_prompt}")
     print(f"  Duration: {args.audio_length}s")
@@ -306,28 +258,18 @@ def main():
     print(f"  Seed: {args.seed}")
     print(f"{'=' * 60}\n")
 
-    parallel_config = DiffusionParallelConfig(
+    omni_kwargs: dict[str, Any] = dict(
+        model=args.model,
         use_hsdp=args.use_hsdp,
         hsdp_shard_size=args.hsdp_shard_size,
         hsdp_replicate_size=args.hsdp_replicate_size,
-    )
-
-    # Initialize Omni. AudioX requires an explicit pipeline class; Stable Audio
-    # is resolved from its config.
-    omni_kwargs: dict[str, Any] = dict(
-        model=args.model,
-        parallel_config=parallel_config,
         cache_backend=args.cache_backend,
         cache_config=cache_config,
         enable_diffusion_pipeline_profiler=args.enable_diffusion_pipeline_profiler,
         enable_cpu_offload=args.enable_cpu_offload,
         enable_layerwise_offload=args.enable_layerwise_offload,
     )
-    if is_audiox:
-        omni_kwargs["model_class_name"] = "AudioXPipeline"
     omni = Omni(**omni_kwargs)
-    model_class_name = get_model_class_name(omni)
-    declared_extra_body_params = get_extra_body_params(model_class_name)
 
     diffusion_params = OmniDiffusionSamplingParams(
         generator=generator,
@@ -337,38 +279,19 @@ def main():
         seed=args.seed,
     )
 
-    # Negative prompt is opt-in for both models (off by default). Including a
+    # Negative prompt is opt-in (off by default). Including a
     # non-empty negative prompt enables the separate CFG conditioning branch.
     prompt: dict[str, Any] = {"prompt": args.prompt}
     if args.negative_prompt:
         prompt["negative_prompt"] = args.negative_prompt
 
-    if model_class_name == "AudioXPipeline":
-        if args.task is None:
-            raise ValueError("AudioX requires --task (one of t2a/t2m/v2a/v2m/tv2a/tv2m).")
-        if args.task in AUDIOX_VIDEO_TASKS and not args.video:
-            raise ValueError(f"AudioX task {args.task!r} requires --video.")
-        # AudioX core knobs are surfaced as shared flags; sampler/reference knobs
-        # (sigma_min/sigma_max/cfg_rescale/audio_path) arrive via --extra-body and
-        # are filtered against the declared extra_body contract.
-        user_extra: dict[str, Any] = {
-            "audiox_task": args.task,
-            "seconds_start": args.audio_start,
-            "seconds_total": args.audio_length,
-            "video_path": args.video,
-        }
-        if args.extra_body:
-            user_extra.update(args.extra_body)
-        apply_declared_extra_args(diffusion_params, declared_extra_body_params, user_extra)
-    else:
-        # Stable Audio Open path (backward-compatible).
-        audio_end_in_s = args.audio_start + args.audio_length
-        diffusion_params.extra_args = {
-            "audio_start_in_s": args.audio_start,
-            "audio_end_in_s": audio_end_in_s,
-        }
-        if args.extra_body:
-            diffusion_params.extra_args.update(args.extra_body)
+    audio_end_in_s = args.audio_start + args.audio_length
+    diffusion_params.extra_args = {
+        "audio_start_in_s": args.audio_start,
+        "audio_end_in_s": audio_end_in_s,
+    }
+    if args.extra_body:
+        diffusion_params.extra_args.update(args.extra_body)
 
     generation_start = time.perf_counter()
 
@@ -379,7 +302,7 @@ def main():
 
     print(f"Total generation time: {generation_time:.2f} seconds")
 
-    output = args.output or ("audiox_output.wav" if model_class_name == "AudioXPipeline" else "stable_audio_output.wav")
+    output = args.output or "stable_audio_output.wav"
     output_path = Path(output)
     output_path.parent.mkdir(parents=True, exist_ok=True)
     suffix = output_path.suffix or ".wav"

examples/offline_inference/text_to_image/README.md

@@ -74,7 +74,7 @@ if __name__ == "__main__":
     omni = Omni(model="Qwen/Qwen-Image")
     prompt = "a cup of coffee on the table"
     outputs = omni.generate(prompt)
-    images = outputs[0].request_output.images
+    images = outputs[0].images
     images[0].save("coffee.png")
 ```
 
@@ -265,7 +265,7 @@ if __name__ == "__main__":
     ]
     outputs = omni.generate(prompts)
     for i, output in enumerate(outputs):
-        output.request_output.images[0].save(f"{i}.jpg")
+        output.images[0].save(f"{i}.jpg")
 ```
 
 !!! info
@@ -301,7 +301,7 @@ if __name__ == "__main__":
         }
     ])
     for i, output in enumerate(outputs):
-        output.request_output.images[0].save(f"{i}.jpg")
+        output.images[0].save(f"{i}.jpg")
 ```
 
 You can also pass a negative prompt via the CLI argument `--negative-prompt`:

examples/offline_inference/text_to_image/text_to_image.py

@@ -89,15 +89,9 @@ def parse_args() -> argparse.Namespace:
         "Qwen/Qwen-Image, Tongyi-MAI/Z-Image-Turbo, Qwen/Qwen-Image-2512, stepfun-ai/NextStep-1.1, "
         "black-forest-labs/FLUX.1-dev, black-forest-labs/FLUX.2-klein-9B, "
         "black-forest-labs/FLUX.2-dev, tencent/HunyuanImage-3.0-Instruct, "
-        "meituan-longcat/LongCat-Image, OvisAI/Ovis-Image, "
+        "HiDream-ai/HiDream-O1-Image, meituan-longcat/LongCat-Image, OvisAI/Ovis-Image, "
         "stabilityai/stable-diffusion-3.5-medium, Tongyi-MAI/Z-Image-Turbo and etc.",
     )
-    parser.add_argument(
-        "--stage-configs-path",
-        type=str,
-        default=None,
-        help="[Deprecated] Path to a legacy stage_args-format YAML. Prefer --deploy-config.",
-    )
     parser.add_argument(
         "--deploy-config",
         type=str,
@@ -475,8 +469,6 @@ def main():
         omni_kwargs["tensor_parallel_size"] = args.tensor_parallel_size
     if args.enforce_eager is not None:
         omni_kwargs["enforce_eager"] = args.enforce_eager
-    if args.stage_configs_path:
-        omni_kwargs["stage_configs_path"] = args.stage_configs_path
     if args.deploy_config:
         omni_kwargs["deploy_config"] = args.deploy_config
     if use_nextstep:
@@ -515,8 +507,8 @@ def main():
     print(f"  Image size: {args.width}x{args.height}")
     if args.lora_path:
         print(f"  LoRA: scale={args.lora_scale}")
-    if args.stage_configs_path:
-        print(f"  stage-configs-path: {args.stage_configs_path}")
+    if args.deploy_config:
+        print(f"  deploy-config: {args.deploy_config}")
     print(f"{'=' * 60}\n")
 
     # Build LoRA request when --lora-path is set

examples/offline_inference/text_to_speech/README.md

@@ -16,6 +16,7 @@ list of supported architectures across all modalities, see
 |---|---|---|---|---|---|---|
 | CosyVoice3 | `FunAudioLLM/Fun-CosyVoice3-0.5B-2512` | 2 (talker + code2wav) | ✓ | ✓ | — | 24 kHz |
 | Fish Speech S2 Pro | `fishaudio/s2-pro` | dual-AR | ✓ | ✓ | — | 44.1 kHz |
+| Gepard-1.0 | `nineninesix/gepard-1.0` | single (native AR + NanoCodec) | — (zero-shot; cloning WIP) | — (serving WIP) | zero-shot | 22.05 kHz |
 | GLM-TTS | `zai-org/GLM-TTS` | 2 (AR + DiT) | ✓ (required) | ✓ | — | 24 kHz |
 | Ming-omni-tts | `inclusionAI/Ming-omni-tts-0.5B` | 2 (AR + audio VAE) | ✓ | ✓ | style / IP / dialect / TTA / podcast | 44.1 kHz |
 | Ming-flash-omni-TTS | `Jonathan1909/Ming-flash-omni-2.0` | single (talker only) | — (caption-controlled) | — | style / IP / basic captions | 44.1 kHz |
@@ -23,6 +24,7 @@ list of supported architectures across all modalities, see
 | OmniVoice | `k2-fsa/OmniVoice` | 2 (gen + dec) | ✓ | — | voice design, language hint | 24 kHz |
 | Qwen3-TTS | `Qwen/Qwen3-TTS-12Hz-1.7B-{CustomVoice,VoiceDesign,Base}` | 2 (talker + code2wav) | ✓ (Base) | ✓ | 3 task variants | 24 kHz |
 | VoxCPM2 | `openbmb/VoxCPM2` | single (native AR) | ✓ | ✓ (online) | continuation | 48 kHz |
+| dots.tts | `rednote-hilab/dots.tts-soar` | single (native AR) | — (not wired yet) | — | — | 48 kHz |
 | IndexTTS-2 | `IndexTeam/IndexTTS-2` | 2 (AR talker + S2Mel DiT + BigVGAN) | ✓ (required) | — | emotion control (`--emo-audio`, `--emo-text`, `--emo-vector`) | 22.05 kHz |
 | IndexTTS-2.5 | native `checkpoints/` bundle | 2 (AR talker + EnhancedCodec + S2Mel DiT + BigVGAN) | ✓ (required) | — | multilingual (`--lang`) + emotion control | 22.05 kHz |
 | Voxtral TTS | `mistralai/Voxtral-4B-TTS-2603` | varies | ✓ | ✓ | voice presets | 24 kHz |
@@ -154,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.
@@ -369,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
@@ -378,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…).
 
@@ -394,6 +396,57 @@ python examples/offline_inference/text_to_speech/qwen3_tts/end2end.py \
 
 ---
 
+## Gepard-1.0
+
+Single-stage native AR TTS at 22.05 kHz. Pipeline: `Qwen3.5 backbone → 32 FSQ codebook heads (one frame/step) → NeMo NanoCodec`. Backbone runs under vLLM paged attention; the 32-head sampling + learned embedding feedback ride the native-AR runner hooks. `enforce_eager` (CUDA graph is a perf follow-up).
+
+### Prerequisites
+The NanoCodec decoder needs NeMo (NVIDIA Open Model License), installed separately:
+
+```bash
+uv pip install "nemo_toolkit[tts]==2.7.3" \
+    --overrides <(printf '%s\n' "transformers>=5.5.3" "huggingface-hub>=1.0")
+```
+
+The overrides are what make that command work. `nemo_toolkit[tts]` declares
+`transformers~=4.57.0`, so a plain install downgrades the version
+`requirements/common.txt` pins and takes `huggingface-hub` back to 0.x with it — after
+which `import vllm` fails. Both packages are named here rather than left to resolve on
+their own: transformers 5.x happens to require `huggingface-hub` 1.x, but relying on
+that would make the second repair an accident of the first. `--constraint` cannot be
+used instead, since it narrows a version range rather than overriding a dependency a
+package declares, and the two sets never intersect. NeMo 2.7.3 decodes correctly
+against transformers 5.x, so nothing is lost by holding it there.
+
+(The same clash is why this is documented here rather than declared in
+`pyproject.toml`: an extra resolves together with the base dependencies, so
+`vllm-omni[gepard]` would be unsatisfiable rather than opt-in.)
+
+On a host whose CUDA toolkit cannot build kernels for the GPU — no `nvcc`/`ninja`, or a
+consumer Blackwell (`sm_120`) card — also set `VLLM_USE_FLASHINFER_SAMPLER=0`. vLLM's
+sampler JIT-compiles through FlashInfer on first use, and where that build fails the engine
+dies inside `profile_run` long after every import has succeeded, which reads as a model
+failure rather than an environment one. The PyTorch sampler it falls back to costs nothing
+here.
+
+### Quick start (zero-shot, default voice)
+```bash
+python examples/offline_inference/text_to_speech/gepard/end2end.py \
+    --text "Hello, this is a Gepard demo."
+```
+
+### Voice cloning
+Not yet — PR1 is zero-shot only (the learned `null_prefix` default voice). Reference-audio cloning (`ref_compressor` speaker prefix) is a follow-up PR.
+
+### Notes
+- Output: 22.05 kHz mono WAV.
+- First run downloads two checkpoints, not one: the model itself, and the NanoCodec decoder it names in `codec_id` (`nvidia/nemo-nano-codec-22khz-1.89kbps-21.5fps` by default). Both are fetched automatically; expect the first startup to be correspondingly slower.
+- Offline only for now; the `/v1/audio/speech` adapter is a follow-up PR.
+- Deploy config: `vllm_omni/deploy/gepard.yaml` (the example's default; copy it and pass `--deploy-config` to change it).
+- Generation length and reproducibility are stage settings, not script flags. One output token is one audio frame, so `max_tokens` in the YAML is the frame budget; `seed` makes the in-model 32-head sampling reproducible. The script deliberately passes no `SamplingParams`: one supplied by a caller replaces the stage defaults wholesale rather than merging, which would drop the pipeline's stop token and run every request to `max_tokens`.
+- Text length: short texts are repeated internally to match the training layout (the checkpoint's `text_repetition` block); the upper bound is the stage's `max_model_len`, enforced by the engine. Empty text is rejected rather than voiced.
+- `VLLM_GEPARD_GREEDY=1` swaps the 32-head Gumbel-max sampling for argmax, for reproducible comparisons that do not depend on a seed.
+
 ## VoxCPM2
 
 Single-stage native AR TTS at 48 kHz. Pipeline: `feat_encoder → MiniCPM4 → FSQ → residual_lm → LocDiT → AudioVAE`.
@@ -430,6 +483,31 @@ Streaming is exposed through the online OpenAI Speech API (`stream=true`). See [
 
 ---
 
+## dots.tts
+
+Single-stage native AR TTS at 48 kHz (rednote-hilab). Pipeline: `Qwen2.5-1.5B base LM → DiT (10-step Euler flow matching) → patch_encoder AR loopback → AudioVAE (streaming decode)`. Same "vLLM-native base LM + side-path computation" pattern as VoxCPM2, with a plain Qwen2 backbone instead of MiniCPM4 and no FSQ / residual LM stage.
+
+### Quick start
+```bash
+python examples/offline_inference/text_to_speech/dots_tts/end2end.py \
+    --model rednote-hilab/dots.tts-soar \
+    --text "Hello, this is a test of dots TTS running on vLLM Omni."
+```
+
+### Voice cloning
+Not wired in this release — generation is zero-shot only. The CAM++ x-vector speaker encoder weights load, but `end2end.py` has no `--ref-audio`/`--ref-text` flags yet.
+
+### Streaming
+The AudioVAE decoder has an internal streaming path (`init_stream_state` / `stream_step` / `stream_flush`) used to avoid boundary artifacts between 160 ms patches, but it is not yet exposed through an online serving endpoint or example.
+
+### Notes
+- Output: 48 kHz mono WAV.
+- Deploy config: `vllm_omni/deploy/dots_tts.yaml` (auto-loaded by HF `model_type`).
+- Checkpoints: `rednote-hilab/dots.tts-soar` is the validated default. `dots.tts-base` shares the same architecture but is unvalidated in this repo. `dots.tts-mf` (MeanFlow, 2-4 step) is not supported yet.
+- Known limitation: no CUDA graph capture and no batched side-path computation yet, so concurrent requests do not currently scale (each request's DiT Euler steps run serially). See `recipes/rednote-hilab/dots.tts.md` for details and the roadmap.
+
+---
+
 ## IndexTTS-2 and IndexTTS-2.5
 
 Both versions use a 2-stage TTS pipeline and produce 22.05 kHz mono audio. Stage 0 is a GPT AR talker. IndexTTS-2 Stage 1 uses RepCodec semantic embeddings, GPT latent, S2Mel CFM/DiT, and BigVGAN. IndexTTS-2.5 replaces RepCodec with EnhancedCodec and uses the official code-only path (`use_gpt_latent=false`). Every request requires reference audio for zero-shot voice cloning.
@@ -538,100 +616,3 @@ Available voice presets are listed on the HF model card (`mistralai/Voxtral-4B-T
 - `--num-prompts N` replicates the prompt for performance measurement.
 - `--concurrency M` requires `--streaming` and must evenly divide `--num-prompts`.
 - Run `--help` for the full argument surface.
-
----
-
-## SoulX-Singer
-
-Singing voice synthesis (SVS) and conversion (SVC) at 24 kHz. Script: `soulxsinger/end2end.py`. Deploy: `vllm_omni/deploy/soulxsinger_svs.yaml` or `soulxsinger_svc.yaml`.
-
-### Prerequisites
-
-Download DiT and preprocess weights, then set up separate SVS / SVC view directories. Copy `soulxsinger/utils/phoneme/phone_set.json` from upstream [SoulX-Singer](https://github.com/Soul-AILab/SoulX-Singer) into the model weights dir as `phoneme/phone_set.json` — HuggingFace does not ship it.
-
-```bash
-# 1. DiT weights
-export BASE=path/to/SoulX-Singer
-export PREPROCESS=path/to/SoulX-Singer-Preprocess
-export SVC_DIR=path/to/SoulX-Singer-svc
-
-huggingface-cli download Soul-AILab/SoulX-Singer --local-dir "$BASE"
-
-# 2. Preprocess weights (required)
-huggingface-cli download Soul-AILab/SoulX-Singer-Preprocess --local-dir "$PREPROCESS"
-export SOULX_PREPROCESS_WEIGHTS_DIR="$PREPROCESS"
-
-# 3. SVS / SVC view directories
-mkdir -p "$SVC_DIR"
-cp $BASE/{config.yaml,README.md,assets} $SVC_DIR
-mv $BASE/model-svc.pt $SVC_DIR/model-svc.pt
-
-cat > "$BASE/config.json" <<'EOF'
-{
-  "model_type": "soulxsinger",
-  "architectures": ["SoulXSingerPipeline"],
-  "max_num_seqs": 1
-}
-EOF
-
-cat > "$SVC_DIR/config.json" <<'EOF'
-{
-  "model_type": "soulxsinger",
-  "architectures": ["SoulXSingerSVCPipeline"],
-  "max_num_seqs": 1
-}
-EOF
-```
-
-`config.yaml` hyper-parameters live under `$BASE`; each view's `config.json` `architectures` field is the single source of truth for SVS vs SVC. Point `--model` at the matching directory (`$BASE` for SVS, `$SVC_DIR` for SVC). Deploy YAML is chosen automatically from `config.json`; optional `--svs` / `--svc` only assert the mode matches.
-
-**Online preprocess** is the default: pass `--prompt-audio` and `--target-audio`, and the worker runs vocal separation, F0, and (for SVS) lyrics/MIDI before DiT. Install only what your run needs:
-
-```bash
-pip install "BS-RoFormer"   # vocal sep + F0 on GPU — SVS and SVC
-```
-
-Mandarin SVS also needs FunASR and Chinese G2P; `ffmpeg` must be on `PATH`:
-
-```bash
-# install optional dependencies:
-pip install -e ".[soulx-svs]"
-```
-
-English SVS adds NeMo ASR and NLTK data; pass `--language English`:
-
-```bash
-pip install "nemo_toolkit[asr]==2.6.1" lhotse==1.32.2
-python -c "import nltk; nltk.download('cmudict'); nltk.download('averaged_perceptron_tagger_eng')"
-```
-
-**Precomputed metadata** is the alternative: pass both `--prompt-metadata-path` and `--target-metadata-path` and skip online ASR/ROSVOT — none of the packages above are required. JSON can be produced by integrated preprocess on a prior run, or by upstream [SoulX-Singer](https://github.com/Soul-AILab/SoulX-Singer) `preprocess/` scripts if you prefer to run that outside vLLM-Omni.
-
-### Quick start
-
-```bash
-# SVS — default demo audio: tests/assets/soulxsinger/zh_prompt.mp3 + music.mp3
-python examples/offline_inference/text_to_speech/soulxsinger/end2end.py \
-    --model "$BASE" \
-    --preprocess-weights-dir "$PREPROCESS" \
-    --control score \
-    --num-inference-steps 32 \
-    -o output.wav
-
-python examples/offline_inference/text_to_speech/soulxsinger/end2end.py \
-    --model "$SVC_DIR" \
-    --preprocess-weights-dir "$PREPROCESS" \
-    --svc \
-    --num-inference-steps 32 \
-    -o output_svc.wav
-```
-
-`SOULX_PREPROCESS_WEIGHTS_DIR` makes `--preprocess-weights-dir` optional. Long SVS targets are handled in one request. See `end2end.py --help` for `--pitch-shift`, `--vocal-sep`, `--auto-shift`, and language/control options.
-
-### Notes
-
-- Output: 24 kHz mono WAV; batch only.
-- Defaults match upstream: `--guidance-scale 3.0`, `--seed 42`, `--auto-shift` on.
-- SVS `--control`: `score` or `melody`. MIDI / lyric QC: upstream `midi_editor` only.
-
----

examples/offline_inference/text_to_speech/dots_tts/end2end.py

@@ -0,0 +1,125 @@
+"""Offline dots.tts inference example (single-stage native AR pipeline).
+
+Uses the single-stage native AR config (vllm_omni/deploy/dots_tts.yaml).
+Reference checkpoint: rednote-hilab/dots.tts-soar.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+import soundfile as sf
+import torch
+
+from vllm_omni import Omni
+from vllm_omni.utils.tracking_parser import TrackingArgumentParser
+
+REPO_ROOT = Path(__file__).resolve().parents[4]
+SAMPLE_RATE = 48_000
+
+
+def parse_args():
+    parser = TrackingArgumentParser(description="Offline dots.tts native AR inference")
+    parser.add_argument(
+        "--model",
+        type=str,
+        default="rednote-hilab/dots.tts-soar",
+        help="dots.tts model path or HuggingFace repo ID.",
+    )
+    parser.add_argument(
+        "--text",
+        type=str,
+        default="Hello, this is a test of dots TTS running on vLLM Omni.",
+        help="Text to synthesize.",
+    )
+    parser.add_argument(
+        "--output-dir",
+        type=str,
+        default="output_audio",
+        help="Directory for output WAV files.",
+    )
+    parser.add_argument(
+        "--deploy-config",
+        type=str,
+        default=None,
+        help="Override the deploy config path. If unset, auto-loads "
+        "vllm_omni/deploy/dots_tts.yaml based on the HF model_type.",
+    )
+    return parser.parse_args()
+
+
+def extract_audio(multimodal_output: dict) -> torch.Tensor:
+    """Extract the final complete audio tensor from multimodal output.
+
+    The output processor concatenates per-step delta tensors under
+    ``model_outputs``.  Falls back to ``audio`` for backwards compat.
+    """
+    audio = multimodal_output.get("model_outputs")
+    if audio is None:
+        audio = multimodal_output.get("audio")
+    if audio is None:
+        raise ValueError(f"No audio key in multimodal_output: {list(multimodal_output.keys())}")
+
+    if isinstance(audio, list):
+        valid = [torch.as_tensor(a).float().cpu().reshape(-1) for a in audio if a is not None]
+        if not valid:
+            raise ValueError("Audio list is empty or all elements are None.")
+        return torch.cat(valid, dim=0) if len(valid) > 1 else valid[0]
+
+    return torch.as_tensor(audio).float().cpu().reshape(-1)
+
+
+def main():
+    args = parse_args()
+
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    engine = Omni(
+        model=args.model,
+        deploy_config=args.deploy_config,
+    )
+
+    from transformers import AutoTokenizer
+
+    from vllm_omni.model_executor.models.dots_tts.dots_tts_prompt import (
+        build_dots_tts_prompt,
+    )
+
+    tokenizer = AutoTokenizer.from_pretrained(args.model, trust_remote_code=True)
+
+    prompt = build_dots_tts_prompt(
+        tokenizer=tokenizer,
+        text=args.text,
+    )
+
+    print(f"Model       : {args.model}")
+    print(f"Text        : {args.text}")
+    print(f"Output dir  : {output_dir}")
+    print(f"Prompt len  : {len(prompt['prompt_token_ids'])} tokens")
+
+    t_start = time.perf_counter()
+    outputs = engine.generate([prompt])
+    elapsed = time.perf_counter() - t_start
+
+    request_output = outputs[0]
+    mm = request_output.outputs[0].multimodal_output
+    audio = extract_audio(mm)
+
+    duration = audio.numel() / SAMPLE_RATE
+    rtf = elapsed / duration if duration > 0 else float("inf")
+
+    output_path = output_dir / "output.wav"
+    sf.write(str(output_path), audio.numpy(), SAMPLE_RATE, format="WAV")
+
+    print(f"Saved       : {output_path}")
+    print(f"Duration    : {duration:.2f}s")
+    print(f"Inference   : {elapsed:.2f}s")
+    print(f"RTF         : {rtf:.3f}")
+
+
+if __name__ == "__main__":
+    os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"
+    main()

examples/offline_inference/text_to_speech/fish_speech/end2end.py

@@ -38,17 +38,6 @@ from vllm_omni.utils.tracking_parser import TrackingArgumentParser
 logger = logging.getLogger(__name__)
 
 DEFAULT_MODEL = "fishaudio/s2-pro"
-DEFAULT_STAGE_CONFIG = os.path.join(
-    os.path.dirname(__file__),
-    "..",
-    "..",
-    "..",
-    "..",
-    "vllm_omni",
-    "model_executor",
-    "stage_configs",
-    "fish_speech_s2_pro.yaml",
-)
 
 
 def build_prompt(
@@ -154,8 +143,6 @@ def _build_omni_kwargs(args, model_name: str) -> dict:
     )
     if args.deploy_config:
         omni_kwargs["deploy_config"] = args.deploy_config
-    else:
-        omni_kwargs["stage_configs_path"] = args.stage_configs_path or DEFAULT_STAGE_CONFIG
     return omni_kwargs
 
 
@@ -278,12 +265,6 @@ def parse_args():
         default=None,
         help="Deploy config YAML path (under vllm_omni/deploy/).",
     )
-    parser.add_argument(
-        "--stage-configs-path",
-        type=str,
-        default=None,
-        help="Path to stage configs YAML (legacy, prefer --deploy-config).",
-    )
     parser.add_argument(
         "--output-dir",
         default="output_audio",

examples/offline_inference/text_to_speech/gepard/end2end.py

@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Offline inference example for Gepard-1.0 TTS via vLLM-Omni.
+
+Single-stage native-AR pipeline: a Qwen3.5 backbone samples one 32-code FSQ
+frame per step; the NeMo NanoCodec decodes the frames to a 22.05 kHz mono
+waveform. Zero-shot: the default learned voice, no reference audio.
+
+Generation length and seed are stage settings rather than flags here. One
+output token is one audio frame, so ``max_tokens`` in the deploy YAML is the
+frame budget; pass a copy of the YAML via ``--deploy-config`` to change it.
+
+Usage:
+  python end2end.py --text "Hello, this is Gepard speaking."
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import soundfile as sf
+import torch
+
+import vllm_omni
+from vllm_omni.utils.tracking_parser import TrackingArgumentParser
+
+os.environ.setdefault("VLLM_WORKER_MULTIPROC_METHOD", "spawn")
+
+from vllm_omni import Omni  # noqa: E402
+
+MODEL = "nineninesix/gepard-1.0"
+SAMPLE_RATE = 22050
+# Absolute: the loader hands the path straight to OmegaConf, which resolves a
+# bare name against the current working directory, not the package.
+DEFAULT_DEPLOY_CONFIG = str(Path(vllm_omni.__file__).resolve().parent / "deploy" / "gepard.yaml")
+
+
+def build_request(text: str) -> dict:
+    """Build an Omni request payload for Gepard (zero-shot, no ref audio).
+
+    The model only consumes the [speaker slots, SOT, text, EOT, SOS] layout, so
+    a bare text prompt would have no speaker slots and no SOS.
+    """
+    from transformers import AutoTokenizer
+
+    from vllm_omni.model_executor.models.gepard.configuration_gepard import GepardConfig
+    from vllm_omni.model_executor.models.gepard.prompt import build_gepard_prompt_ids
+
+    # From the checkpoint's own sidecar, which is what the worker builds its
+    # config from too. A layout that disagrees with the trained one does not
+    # fail, it just degrades the speech.
+    cfg = GepardConfig.from_checkpoint(MODEL)
+    tokenizer = AutoTokenizer.from_pretrained(MODEL, trust_remote_code=True)
+    prompt_token_ids = build_gepard_prompt_ids(
+        tokenizer(text, add_special_tokens=False)["input_ids"],
+        config=cfg,
+    )
+    return {
+        "prompt_token_ids": prompt_token_ids,
+        "additional_information": {"text": [text]},
+    }
+
+
+def save_audio(waveform: torch.Tensor, path: str, sample_rate: int = SAMPLE_RATE) -> None:
+    sf.write(path, waveform.float().numpy(), sample_rate)
+    seconds = waveform.numel() / sample_rate
+    print(
+        f"  Saved {path} ({tuple(waveform.shape)}, {sample_rate} Hz, "
+        f"{seconds:.2f}s, peak {float(waveform.abs().max()):.3f})"
+    )
+
+
+def main(args) -> None:
+    omni = Omni(
+        model=MODEL,
+        deploy_config=args.deploy_config,
+        stage_init_timeout=args.stage_init_timeout,
+        init_timeout=args.init_timeout,
+    )
+
+    # No explicit SamplingParams: one supplied here would replace the stage
+    # defaults rather than merge over them, dropping the pipeline's stop token.
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    print(f"Synthesizing: {args.text!r}")
+    inputs = build_request(text=args.text)
+
+    for i, stage_outputs in enumerate(omni.generate(inputs)):
+        for j, out in enumerate(stage_outputs.outputs):
+            mm = out.multimodal_output
+            if mm is None:
+                print(f"  [req {i}] No audio output.")
+                continue
+            # The consolidation path renames "model_outputs" to "audio".
+            audio = mm.get("audio")
+            if audio is None:
+                audio = mm.get("model_outputs")
+            if isinstance(audio, list):
+                audio = audio[0] if len(audio) else None
+            if audio is None:
+                print(f"  [req {i}] No waveform in multimodal_output (keys: {list(mm)}).")
+                continue
+            sr_tensor = mm.get("sr")
+            sr = int(sr_tensor.item()) if hasattr(sr_tensor, "item") else SAMPLE_RATE
+            save_audio(audio.cpu(), str(output_dir / f"output_{i}_{j}.wav"), sr)
+
+    print("Done.")
+
+
+def parse_args():
+    parser = TrackingArgumentParser(description="Gepard-1.0 offline TTS inference (zero-shot)")
+    parser.add_argument("--text", default="Hello, this is Gepard speaking.", help="Text to synthesize.")
+    parser.add_argument(
+        "--output-dir",
+        default=os.path.join(
+            os.environ.get("XDG_CACHE_HOME", os.path.join(os.path.expanduser("~"), ".cache")),
+            "gepard_output",
+        ),
+        help="Directory for WAV outputs (default: ~/.cache/gepard_output).",
+    )
+    parser.add_argument(
+        "--deploy-config",
+        default=DEFAULT_DEPLOY_CONFIG,
+        help=(
+            "Path to the deploy YAML (default: the packaged vllm_omni/deploy/gepard.yaml). This must "
+            "stay set: without the YAML's `pipeline: gepard` pin the architectures fallback routes "
+            "Qwen3_5ForCausalLM to the diffusion registry. Copy it to change max_tokens or seed."
+        ),
+    )
+    # The upstream defaults are too tight for a cold start.
+    parser.add_argument("--stage-init-timeout", type=int, default=900)
+    parser.add_argument("--init-timeout", type=int, default=1800)
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    main(parse_args())

examples/offline_inference/text_to_speech/glm_tts/end2end.py

@@ -145,7 +145,7 @@ def main(args):
 
     omni = Omni(
         model=args.model,
-        stage_configs_path=deploy_config_path,
+        deploy_config=deploy_config_path,
         log_stats=args.log_stats,
         stage_init_timeout=args.stage_init_timeout,
     )

examples/offline_inference/text_to_speech/ming_tts/README.md

@@ -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`.
 

examples/offline_inference/text_to_speech/ming_tts/end2end.py

@@ -13,6 +13,7 @@ import yaml
 from transformers import AutoTokenizer
 from vllm.utils.argparse_utils import FlexibleArgumentParser
 
+from vllm_omni.model_executor.models.common.ming.speaker_extractor import SpeakerEmbeddingExtractor
 from vllm_omni.model_executor.models.ming_tts.config_ming_tts import (
     KEY_CFG,
     KEY_MAX_DECODE_STEPS,
@@ -21,7 +22,6 @@ from vllm_omni.model_executor.models.ming_tts.config_ming_tts import (
     SAMPLE_RATE,
 )
 from vllm_omni.model_executor.models.ming_tts.prompt_assembly import build_ming_dense_prompt
-from vllm_omni.model_executor.models.ming_tts.speaker_extractor import MingSpeakerEmbeddingExtractor
 
 try:
     from .runner import (
@@ -142,7 +142,8 @@ def _resolve_speaker_embedding(args, case: dict, paths: list[str]):
         return _load_speaker_embedding(args.speaker_embedding)
     if not (case.get("auto_extract_speaker_embeddings") or args.extract_speaker_embeddings) or not paths:
         return None
-    embs = MingSpeakerEmbeddingExtractor(args.model).extract_many(paths)
+    # Runs before the engine is built, so nothing has pre-fetched campplus.onnx.
+    embs = SpeakerEmbeddingExtractor(args.model, allow_download=True).extract_many(paths)
     if not embs:
         raise RuntimeError("Speaker extraction produced no embeddings")
     return embs[0] if len(embs) == 1 else torch.stack(embs, dim=0)

examples/offline_inference/text_to_speech/qwen3_tts/end2end.py

@@ -490,10 +490,10 @@ def parse_args():
         help="Path to a .txt file with one prompt per line (preferred).",
     )
     parser.add_argument(
-        "--stage-configs-path",
+        "--deploy-config",
         type=str,
         default=None,
-        help="Path to a stage configs file.",
+        help="Path to a deploy config YAML.",
     )
     parser.add_argument(
         "--audio-path",

examples/offline_inference/text_to_speech/qwen3_tts/word_timestamps.py

@@ -32,11 +32,10 @@ from end2end import _estimate_prompt_len
 from vllm.utils.argparse_utils import FlexibleArgumentParser
 
 from vllm_omni import Omni
-from vllm_omni.engine.arg_utils import nullify_stage_engine_defaults
 from vllm_omni.utils.forced_aligner import align, build_forced_aligner_config
 
 
-def _default_stage_config() -> str:
+def _default_deploy_config() -> str:
     repo_root = Path(__file__).resolve().parents[4]
     return str(repo_root / "vllm_omni" / "deploy" / "qwen3_tts.yaml")
 
@@ -109,7 +108,7 @@ def main(args: Any) -> None:
         "output_dir",
     ):
         omni_kwargs.pop(key, None)
-    omni_kwargs["stage_configs_path"] = args.stage_configs_path or _default_stage_config()
+    omni_kwargs["deploy_config"] = args.deploy_config or _default_deploy_config()
     omni_kwargs["log_stats"] = args.log_stats
     omni = Omni(**omni_kwargs)
 
@@ -156,7 +155,7 @@ def parse_args() -> Any:
         default=None,
         help="Optional YAML file for forced aligner settings (incl. gpu_memory_utilization)",
     )
-    parser.add_argument("--stage-configs-path", default=None, help="Qwen3-TTS deploy YAML")
+    parser.add_argument("--deploy-config", default=None, help="Qwen3-TTS deploy YAML")
     parser.add_argument("--text", default="Hello world.", help="Text to synthesize and align")
     parser.add_argument("--language", default="English", help="Qwen3-TTS language field")
     parser.add_argument("--speaker", default="Vivian", help="CustomVoice speaker name")
@@ -164,7 +163,6 @@ def parse_args() -> Any:
     parser.add_argument("--max-new-tokens", type=int, default=2048, help="TTS max_new_tokens")
     parser.add_argument("--output-dir", default="output_audio", help="Directory for WAV and JSON sidecar")
     parser.add_argument("--log-stats", action="store_true", default=False, help="Enable vLLM-Omni stats logging")
-    nullify_stage_engine_defaults(parser)
     return parser.parse_args()
 
 

examples/offline_inference/text_to_speech/soulxsinger/benchmark.py

@@ -1,162 +0,0 @@
-"""Repeatable SoulX-Singer offline benchmark (preprocess + DiT, RTF + stage timings).
-
-Usage:
-    python benchmark.py --model /path/to/SoulX-Singer --svs \\
-        --prompt-audio ../SoulX-Singer/example/audio/zh_prompt.mp3 \\
-        --target-audio ../SoulX-Singer/example/audio/music.mp3 \\
-        --preprocess-weights-dir /path/to/SoulX-Singer-Preprocess \\
-        -o benchmark.wav
-
-    python benchmark.py ... --enable-diffusion-pipeline-profiler
-"""
-
-import argparse
-import statistics
-import time
-from pathlib import Path
-
-import soundfile as sf
-from end2end import (
-    SVC_DEPLOY_CONFIG,
-    SVS_DEPLOY_CONFIG,
-    add_inference_args,
-    build_sampling,
-    extract_audio,
-    resolve_preprocess_weights_dir,
-)
-
-from vllm_omni.entrypoints.omni import Omni
-
-
-def _audio_duration_sec(outputs) -> float:
-    audio_np, sr = extract_audio(outputs)
-    return audio_np.size / sr
-
-
-def _stage_durations_from_output(outputs) -> dict[str, float]:
-    omni_out = outputs[0]
-    durations = getattr(omni_out, "stage_durations", None) or {}
-    if durations:
-        return dict(durations)
-    ro = omni_out
-    if ro is not None:
-        return dict(getattr(ro, "stage_durations", None) or {})
-    return {}
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="SoulX-Singer offline benchmark")
-    add_inference_args(parser)
-    parser.add_argument("--warmup", type=int, default=1, help="Warmup runs (excluded from stats)")
-    parser.add_argument("--runs", type=int, default=3, help="Measured runs")
-    parser.add_argument(
-        "--enable-diffusion-pipeline-profiler",
-        action="store_true",
-        help="Enable low-overhead stage timing in DiffusionOutput.stage_durations",
-    )
-    parser.add_argument(
-        "--enforce-eager",
-        action="store_true",
-        help="Disable torch.compile on diff_estimator (eager baseline for A/B)",
-    )
-    parser.add_argument(
-        "--dtype",
-        type=str,
-        default=None,
-        choices=["bfloat16", "bf16", "float16", "fp16", "half"],
-        help="DiT trunk dtype (default from deploy YAML). Use float16 to match upstream --fp16.",
-    )
-    parser.add_argument(
-        "--output",
-        "-o",
-        type=str,
-        default=None,
-        help="Save WAV from the last measured run (after warmup)",
-    )
-    parser.add_argument(
-        "--save-each-run",
-        action="store_true",
-        help="With --output, also write measured runs as <stem>_run1.wav, _run2.wav, ...",
-    )
-    return parser.parse_args()
-
-
-def main() -> None:
-    args = parse_args()
-    preprocess_dir = resolve_preprocess_weights_dir(args.preprocess_weights_dir)
-    deploy_config = args.deploy_config or str(SVS_DEPLOY_CONFIG if args.svs else SVC_DEPLOY_CONFIG)
-    mode = "SVS" if args.svs else "SVC"
-
-    omni_kwargs: dict = {
-        "model": args.model,
-        "deploy_config": deploy_config,
-        "async_chunk": False,  # SoulX-Singer currently supports only batch mode (pseudo-streaming was stashed)
-    }
-    if args.enable_diffusion_pipeline_profiler:
-        omni_kwargs["enable_diffusion_pipeline_profiler"] = True
-    if args.enforce_eager:
-        omni_kwargs["enforce_eager"] = True
-    if args.dtype is not None:
-        omni_kwargs["dtype"] = args.dtype
-
-    compile_mode = "eager" if args.enforce_eager else "torch.compile"
-    dtype_label = args.dtype or "from deploy YAML"
-    print(f"Loading SoulX-Singer {mode} from {args.model} [{compile_mode}, dtype={dtype_label}]")
-
-    omni = Omni(**omni_kwargs)
-    kind = "svs" if args.svs else "svc"
-    sampling = build_sampling(args, preprocess_weights_dir=preprocess_dir, kind=kind)
-    prompt = {"prompt_token_ids": [0]}
-
-    latencies_ms: list[float] = []
-    rtfs: list[float] = []
-    last_stages: dict[str, float] = {}
-    last_measured_outputs = None
-
-    total_runs = args.warmup + args.runs
-    for run_idx in range(total_runs):
-        is_warmup = run_idx < args.warmup
-        label = "warmup" if is_warmup else f"run {run_idx - args.warmup + 1}/{args.runs}"
-        t0 = time.perf_counter()
-        outputs = list(omni.generate([prompt], sampling))
-        elapsed_ms = (time.perf_counter() - t0) * 1000.0
-        audio_sec = _audio_duration_sec(outputs)
-        rtf = (elapsed_ms / 1000.0) / audio_sec if audio_sec > 0 else float("inf")
-        print(f"[{label}] client={elapsed_ms:.1f} ms, audio={audio_sec:.2f}s, RTF={rtf:.3f}")
-        if not is_warmup:
-            latencies_ms.append(elapsed_ms)
-            rtfs.append(rtf)
-            last_stages = _stage_durations_from_output(outputs)
-            last_measured_outputs = outputs
-            if args.output and args.save_each_run:
-                measured_idx = run_idx - args.warmup + 1
-                out_path = Path(args.output)
-                run_path = out_path.with_name(f"{out_path.stem}_run{measured_idx}{out_path.suffix}")
-                audio_np, sr = extract_audio(outputs)
-                sf.write(str(run_path), audio_np, sr)
-                print(f"  saved {run_path} ({sr} Hz, {audio_np.size / sr:.2f}s)")
-
-    omni.close()
-
-    if args.output and last_measured_outputs is not None:
-        audio_np, sr = extract_audio(last_measured_outputs)
-        out_path = Path(args.output)
-        out_path.parent.mkdir(parents=True, exist_ok=True)
-        sf.write(str(out_path), audio_np, sr)
-        print(f"\nSaved last measured run → {out_path} ({sr} Hz, {audio_np.size / sr:.2f}s)")
-
-    if latencies_ms:
-        print("\n=== Summary (measured runs) ===")
-        print(f"client_ms: mean={statistics.mean(latencies_ms):.1f}, stdev={statistics.pstdev(latencies_ms):.1f}")
-        print(f"RTF:       mean={statistics.mean(rtfs):.3f}, stdev={statistics.pstdev(rtfs):.3f}")
-        if last_stages:
-            print("\nStage durations (last measured run):")
-            for name, value in sorted(last_stages.items()):
-                if name.endswith("_ms"):
-                    print(f"  {name}: {value:.1f} ms")
-                else:
-                    print(f"  {name}: {value * 1000.0:.1f} ms")
-
-
-if __name__ == "__main__":
-    main()

examples/offline_inference/text_to_speech/soulxsinger/end2end.py

@@ -1,285 +0,0 @@
-"""Offline SoulX-Singer SVS / SVC: single-stage DiT (preprocess inline).
-
-Pass raw prompt/target audio; vLLM-Omni runs integrated preprocess then inference.
-
-Usage:
-    # SVS (default)
-    python end2end.py --model /path/to/SoulX-Singer \\
-        --prompt-audio path/to/prompt/audio.mp3 \\
-        --target-audio path/to/target/audio.mp3 \\
-        --preprocess-weights-dir /path/to/SoulX-Singer-Preprocess \\
-        -o output.wav
-
-    # SVC (config.json must declare SoulXSingerSVCPipeline; --model points at SVC view)
-    python end2end.py --model /path/to/SoulX-Singer-svc \\
-        --prompt-audio path/to/prompt/audio.mp3 \\
-        --target-audio path/to/target/audio.mp3 \\
-        --preprocess-weights-dir /path/to/SoulX-Singer-Preprocess \\
-        -o output_svc.wav
-"""
-
-import argparse
-import os
-from pathlib import Path
-
-import numpy as np
-import soundfile as sf
-
-from vllm_omni.diffusion.models.soulx_singer.utils import resolve_soulx_kind, validate_soulx_extra_args
-from vllm_omni.entrypoints.omni import Omni
-from vllm_omni.inputs.data import OmniDiffusionSamplingParams
-
-REPO_ROOT = Path(__file__).resolve().parents[4]
-SVS_DEPLOY_CONFIG = REPO_ROOT / "vllm_omni" / "deploy" / "soulxsinger_svs.yaml"
-SVC_DEPLOY_CONFIG = REPO_ROOT / "vllm_omni" / "deploy" / "soulxsinger_svc.yaml"
-DEFAULT_PROMPT_AUDIO = REPO_ROOT / "tests" / "assets" / "soulxsinger" / "zh_prompt.mp3"
-DEFAULT_TARGET_AUDIO = REPO_ROOT / "tests" / "assets" / "soulxsinger" / "music.mp3"
-_SAMPLE_RATE = 24000
-
-
-def _require_paths(paths: dict[str, str | None]) -> None:
-    missing = [name for name, p in paths.items() if not p or not os.path.isfile(p)]
-    if missing:
-        raise FileNotFoundError("Missing file(s): " + ", ".join(f"{k}={paths[k]!r}" for k in missing))
-
-
-def resolve_preprocess_weights_dir(explicit: str | None) -> str:
-    if explicit:
-        path = Path(explicit).expanduser().resolve()
-        if not (path / "rmvpe" / "rmvpe.pt").is_file():
-            raise FileNotFoundError(f"--preprocess-weights-dir must contain rmvpe/rmvpe.pt: {path}")
-        return str(path)
-    env = os.environ.get("SOULX_PREPROCESS_WEIGHTS_DIR")
-    if env:
-        path = Path(env).expanduser().resolve()
-        if (path / "rmvpe" / "rmvpe.pt").is_file():
-            return str(path)
-    raise FileNotFoundError(
-        "SoulX preprocess weights not found. Pass --preprocess-weights-dir or set "
-        "SOULX_PREPROCESS_WEIGHTS_DIR to a directory containing rmvpe/rmvpe.pt "
-        "(huggingface-cli download Soul-AILab/SoulX-Singer-Preprocess)."
-    )
-
-
-def build_sampling(
-    args: argparse.Namespace,
-    *,
-    preprocess_weights_dir: str,
-    kind: str,
-) -> OmniDiffusionSamplingParams:
-    extra: dict = {
-        "prompt_audio": os.path.abspath(args.prompt_audio),
-        "target_audio": os.path.abspath(args.target_audio),
-        "preprocess_weights_dir": preprocess_weights_dir,
-        "vocal_sep": args.vocal_sep,
-        "auto_shift": args.auto_shift,
-        "pitch_shift": args.pitch_shift,
-    }
-    if kind == "svs":
-        extra["language"] = args.language
-        extra["control"] = args.control
-        if args.prompt_metadata_path:
-            extra["prompt_metadata_path"] = os.path.abspath(args.prompt_metadata_path)
-        if args.target_metadata_path:
-            extra["target_metadata_path"] = os.path.abspath(args.target_metadata_path)
-        if args.prompt_metadata_path or args.target_metadata_path:
-            extra["audio_path"] = os.path.abspath(args.prompt_wav_path or args.prompt_audio)
-
-    extra = validate_soulx_extra_args(kind, extra)
-
-    return OmniDiffusionSamplingParams(
-        num_inference_steps=args.num_inference_steps,
-        guidance_scale=args.guidance_scale,
-        seed=args.seed,
-        extra_args=extra,
-    )
-
-
-def extract_audio(outputs) -> tuple[np.ndarray, int]:
-    out = outputs[0]
-    mm = getattr(out, "multimodal_output", None)
-    if mm is None:
-        ro = out
-        if ro is not None:
-            mm = getattr(ro, "multimodal_output", None)
-            if mm is None and ro.outputs:
-                mm = getattr(ro.outputs[0], "multimodal_output", None)
-    if not mm or "audio" not in mm:
-        raise RuntimeError("No audio in multimodal_output")
-
-    audio_val = mm["audio"]
-    if isinstance(audio_val, list):
-        chunks = [
-            np.asarray(chunk.detach().cpu().float().numpy() if hasattr(chunk, "detach") else chunk).reshape(-1)
-            for chunk in audio_val
-            if chunk is not None
-        ]
-        audio_np = np.concatenate(chunks, axis=0) if chunks else np.array([], dtype=np.float32)
-    elif hasattr(audio_val, "cpu"):
-        audio_np = audio_val.detach().cpu().numpy().squeeze()
-    else:
-        audio_np = np.asarray(audio_val, dtype=np.float32).squeeze()
-
-    sr_val = mm.get("sr", mm.get("audio_sample_rate", _SAMPLE_RATE))
-    if isinstance(sr_val, list) and sr_val:
-        sr_val = sr_val[-1]
-    if hasattr(sr_val, "item"):
-        sr_val = sr_val.item()
-    return audio_np.astype(np.float32, copy=False), int(sr_val)
-
-
-def add_inference_args(parser: argparse.ArgumentParser) -> None:
-    mode = parser.add_mutually_exclusive_group()
-    mode.add_argument(
-        "--svc",
-        action="store_true",
-        help="Assert SVC mode (must match config.json architectures)",
-    )
-    parser.add_argument(
-        "--model",
-        type=str,
-        required=True,
-        help="SoulX-Singer weight directory ($BASE for SVS, $SVC_DIR for SVC)",
-    )
-    parser.add_argument(
-        "--deploy-config",
-        type=str,
-        default=None,
-        help="Override deploy YAML (default: soulxsinger_svs.yaml or soulxsinger_svc.yaml)",
-    )
-    parser.add_argument(
-        "--prompt-audio",
-        type=str,
-        default=str(DEFAULT_PROMPT_AUDIO),
-        help="Prompt / reference audio (mp3 or wav)",
-    )
-    parser.add_argument(
-        "--target-audio",
-        type=str,
-        default=str(DEFAULT_TARGET_AUDIO),
-        help="Target content audio (mp3 or wav)",
-    )
-    parser.add_argument(
-        "--prompt-metadata-path",
-        type=str,
-        default=None,
-        help="SVS precomputed prompt metadata.json (skips online ASR/ROSVOT for prompt)",
-    )
-    parser.add_argument(
-        "--target-metadata-path",
-        type=str,
-        default=None,
-        help="SVS precomputed target metadata.json (skips online ASR/ROSVOT for target)",
-    )
-    parser.add_argument(
-        "--prompt-wav-path",
-        type=str,
-        default=None,
-        help="SVS prompt vocal wav for metadata processor when using --prompt-metadata-path (default: --prompt-audio)",
-    )
-    parser.add_argument(
-        "--preprocess-weights-dir",
-        type=str,
-        default=None,
-        help="SoulX-Singer-Preprocess weights (or set SOULX_PREPROCESS_WEIGHTS_DIR)",
-    )
-    parser.add_argument(
-        "--language",
-        type=str,
-        default="Mandarin",
-        help="SVS lyrics language (Mandarin, Cantonese, English)",
-    )
-    parser.add_argument(
-        "--control",
-        type=str,
-        default="melody",
-        choices=["score", "melody"],
-        help="SVS control mode",
-    )
-    parser.add_argument(
-        "--vocal-sep",
-        action=argparse.BooleanOptionalAction,
-        default=False,
-        help="Run vocal separation during preprocess",
-    )
-    parser.add_argument(
-        "--auto-shift",
-        action=argparse.BooleanOptionalAction,
-        default=True,
-        help="Auto pitch shift to align target pitch with prompt",
-    )
-    parser.add_argument("--pitch-shift", type=int, default=0)
-    parser.add_argument("--num-inference-steps", type=int, default=32)
-    parser.add_argument("--guidance-scale", type=float, default=3.0)
-    parser.add_argument(
-        "--seed",
-        type=int,
-        default=42,
-        help="Optional CFM RNG seed. Omit for non-deterministic sampling.",
-    )
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="SoulX-Singer offline SVS / SVC (preprocess + DiT)")
-    add_inference_args(parser)
-    parser.add_argument("--output", "-o", type=str, default="output.wav")
-    args = parser.parse_args()
-    return args
-
-
-def main() -> None:
-    args = parse_args()
-    kind = resolve_soulx_kind(args.model)
-
-    if not (args.svc ^ (kind == "svs")):
-        raise ValueError(f"mode mismatch: {args.model}/config.json (declares {kind!r}), --svc={args.svc}")
-
-    required = {
-        "prompt_audio": args.prompt_audio,
-        "target_audio": args.target_audio,
-    }
-    if kind == "svs" and bool(args.prompt_metadata_path) ^ bool(args.target_metadata_path):
-        raise ValueError(
-            "SVS precomputed metadata requires both --prompt-metadata-path and "
-            "--target-metadata-path (or neither, for online preprocess)."
-        )
-    if args.prompt_metadata_path:
-        required["prompt_metadata_path"] = args.prompt_metadata_path
-        required["target_metadata_path"] = args.target_metadata_path
-    if args.prompt_wav_path:
-        required["prompt_wav_path"] = args.prompt_wav_path
-    _require_paths(required)
-    preprocess_dir = resolve_preprocess_weights_dir(args.preprocess_weights_dir)
-    deploy_config = args.deploy_config or str(SVC_DEPLOY_CONFIG if kind == "svc" else SVS_DEPLOY_CONFIG)
-    mode = kind.upper()
-
-    print(f"Loading SoulX-Singer {mode} from {args.model}")
-    print(f"  deploy: {deploy_config}")
-    print(f"  prompt: {args.prompt_audio}")
-    print(f"  target: {args.target_audio}")
-
-    omni = Omni(model=args.model, deploy_config=deploy_config, async_chunk=False)  # SoulX-Singer is batch-only
-    sampling = build_sampling(
-        args,
-        preprocess_weights_dir=preprocess_dir,
-        kind=kind,
-    )
-    prompt = {"prompt_token_ids": [0], "multi_modal_data": {}}
-
-    print("Running generate (inline preprocess + DiT)...")
-    outputs = list(omni.generate([prompt], sampling))
-    if not outputs:
-        raise RuntimeError("No output from omni.generate")
-
-    err = getattr(outputs[0], "error", None)
-    if err is not None:
-        raise RuntimeError(f"Pipeline error: {err}")
-
-    audio_np, sr = extract_audio(outputs)
-    sf.write(args.output, audio_np, sr)
-    print(f"Saved {args.output} ({sr} Hz, {len(audio_np) / sr:.2f}s)")
-    omni.close()
-
-
-if __name__ == "__main__":
-    main()

examples/offline_inference/text_to_speech/voxtral_tts/end2end.py

@@ -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",

examples/offline_inference/text_to_video/text_to_video.md

@@ -14,6 +14,8 @@ A unified script for text-to-video generation. Supports multiple models with mod
 | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v` | 720x1280 | 121 | 50 | 6.0 | FP8 + VAE tiling required |
 | `nvidia/Cosmos3-Nano` | 720x1280 | 189 | 35 | 6.0 | ~46 GiB (peak, 720p) |
 | `BestWishYsh/Helios-Base` / `Helios-Mid` / `Helios-Distilled` | 384x640 | 99 | 50 | 5.0 / 5.0 / 1.0 | — |
+| `Efficient-Large-Model/SANA-Video_2B_480p_diffusers` | 480x832 | 81 | 50 | 6.0 | BF16 DiT + FP32 Wan VAE wrapper |
+| `Efficient-Large-Model/SANA-Video_2B_720p_diffusers` | 704x1280 | 81 | 50 | 6.0 | BF16 DiT + LTX-2 Video VAE wrapper |
 
 ## Local CLI Usage
 
@@ -151,6 +153,40 @@ python text_to_video.py \
   --output quick_test.mp4
 ```
 
+### SANA-Video-2B
+
+Select the native T2V pipeline explicitly:
+
+```bash
+python text_to_video.py \
+  --model Efficient-Large-Model/SANA-Video_2B_480p_diffusers \
+  --model-class-name SanaVideoPipeline \
+  --prompt "A cinematic tracking shot of a sailboat crossing the ocean at sunset." \
+  --height 480 \
+  --width 832 \
+  --num-frames 81 \
+  --num-inference-steps 50 \
+  --guidance-scale 6.0 \
+  --extra-body '{"motion_score": 30}' \
+  --fps 16 \
+  --output sana_video_480p.mp4
+```
+
+For the 720p checkpoint, switch the model to
+`Efficient-Large-Model/SANA-Video_2B_720p_diffusers`, use
+`--height 704 --width 1280`, and write to a different output path. Both native
+checkpoint variants are supported. The Diffusers adapter T2V compatibility
+path is also validated at both resolutions through online serving.
+
+The native 480p path uses vLLM-Omni's `DistributedAutoencoderKLWan` wrapper;
+the native 720p path uses `DistributedAutoencoderKLLTX2Video`. Both wrappers
+retain their underlying Diffusers autoencoders. The pipeline intentionally
+uses Diffusers' checkpoint-compatible `DPMSolverMultistepScheduler`.
+
+For image-to-video, use the shared
+[`image_to_video.py`](../image_to_video/README.md#sana-video-2b) example with
+`--model-class-name SanaImageToVideoPipeline` and `--image <path>`.
+
 ### Cosmos3
 
 ```bash

examples/offline_inference/text_to_video/text_to_video.py

@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 import argparse
 import json
@@ -10,7 +10,6 @@ from typing import Any
 import numpy as np
 import torch
 
-from vllm_omni.diffusion.data import DiffusionParallelConfig
 from vllm_omni.diffusion.utils.param_utils import apply_declared_extra_args
 from vllm_omni.entrypoints.omni import Omni
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
@@ -115,12 +114,32 @@ _MODEL_PRESETS = {
         "fps": 24,
         "output": "ltx23_output.mp4",
     },
+    "sana_480p": {
+        "height": 480,
+        "width": 832,
+        "num_frames": 81,
+        "num_inference_steps": 50,
+        "guidance_scale": 6.0,
+        "fps": 16,
+        "output": "sana_video_480p.mp4",
+    },
+    "sana_720p": {
+        "height": 704,
+        "width": 1280,
+        "num_frames": 81,
+        "num_inference_steps": 50,
+        "guidance_scale": 6.0,
+        "fps": 16,
+        "output": "sana_video_720p.mp4",
+    },
 }
 
 
 def _detect_preset(model: str, model_class_name: str | None = None) -> dict:
     model_lower = model.lower()
     class_lower = (model_class_name or "").lower()
+    if "sana-video" in model_lower or "sana_video" in model_lower or "sanavideo" in class_lower:
+        return _MODEL_PRESETS["sana_720p" if "720p" in model_lower else "sana_480p"]
     if "lingbot" in model_lower or "lingbotvideo" in class_lower:
         return _MODEL_PRESETS["lingbot"]
     if "ltx" in class_lower or "ltx" in model_lower:
@@ -155,6 +174,13 @@ def build_text_to_video_prompt(prompt: str, negative_prompt: str | None) -> dict
     return result
 
 
+def _validate_video_output_type(output_type: str) -> None:
+    if output_type not in {"image", "video"}:
+        raise ValueError(
+            f"Unexpected output type '{output_type}', expected 'video' or legacy 'image' for video generation."
+        )
+
+
 def _normalize_float_tensor(tensor: torch.Tensor, source_range: str) -> torch.Tensor:
     """Normalize decoded frames according to the pipeline's output contract."""
     if not tensor.is_floating_point():
@@ -462,17 +488,6 @@ def main():
             "scm_steps_policy": "dynamic",
         }
 
-    # Configure parallel settings
-    parallel_config = DiffusionParallelConfig(
-        ulysses_degree=args.ulysses_degree,
-        ring_degree=args.ring_degree,
-        cfg_parallel_size=args.cfg_parallel_size,
-        tensor_parallel_size=args.tensor_parallel_size,
-        vae_patch_parallel_size=args.vae_patch_parallel_size,
-        pipeline_parallel_size=args.pipeline_parallel_size,
-        enable_expert_parallel=args.enable_expert_parallel,
-    )
-
     profiler_enabled = args.profiler_config is not None
 
     omni_kwargs = dict(
@@ -481,7 +496,13 @@ def main():
         vae_use_slicing=args.vae_use_slicing,
         vae_use_tiling=args.vae_use_tiling,
         enable_cpu_offload=args.enable_cpu_offload,
-        parallel_config=parallel_config,
+        ulysses_degree=args.ulysses_degree,
+        ring_degree=args.ring_degree,
+        cfg_parallel_size=args.cfg_parallel_size,
+        tensor_parallel_size=args.tensor_parallel_size,
+        vae_patch_parallel_size=args.vae_patch_parallel_size,
+        pipeline_parallel_size=args.pipeline_parallel_size,
+        enable_expert_parallel=args.enable_expert_parallel,
         enforce_eager=args.enforce_eager,
         model_class_name=model_class_name,
         cache_backend=args.cache_backend,
@@ -570,6 +591,8 @@ def main():
         num_frames=args.num_frames,
         extra_args=extra_args,
     )
+    if args.frame_rate is not None:
+        sampling_kwargs["frame_rate"] = args.frame_rate
     if args.guidance_scale_high is not None:
         sampling_kwargs["guidance_scale_2"] = args.guidance_scale_high
 
@@ -604,10 +627,7 @@ def main():
         frames = frames[0] if frames else None
 
     if isinstance(frames, OmniRequestOutput):
-        if frames.final_output_type != "image":
-            raise ValueError(
-                f"Unexpected output type '{frames.final_output_type}', expected 'image' for video generation."
-            )
+        _validate_video_output_type(frames.final_output_type)
         if frames.multimodal_output and "audio" in frames.multimodal_output:
             audio = frames.multimodal_output["audio"]
             audio_sample_rate = frames.multimodal_output.get("audio_sample_rate", audio_sample_rate)

examples/offline_inference/x_to_video_audio/download_dreamid_omni.py

@@ -1,108 +0,0 @@
-import argparse
-import fcntl
-import os
-import site
-import subprocess
-import tempfile
-import time
-from pathlib import Path
-
-from huggingface_hub import snapshot_download
-
-DEPENDENCY_REPO = "https://github.com/bytedance/DreamID-V.git"
-DEPENDENCY_BRANCH = "omni"
-CACHE_DIR = Path(tempfile.gettempdir()) / "vllm-omni-dependency"
-LOCK_FILE = CACHE_DIR / ".install.lock"
-DEPENDENCY_DIR = CACHE_DIR / "DreamID-Omni"
-
-
-def download_dependency():
-    CACHE_DIR.mkdir(parents=True, exist_ok=True)
-
-    with open(LOCK_FILE, "w") as f:
-        fcntl.flock(f, fcntl.LOCK_EX)
-        if not DEPENDENCY_DIR.exists():
-            print(f"Downloading DreamID-Omni to {DEPENDENCY_DIR} ...")
-            subprocess.run(
-                ["git", "clone", "--depth", "1", DEPENDENCY_REPO, "--branch", DEPENDENCY_BRANCH, str(DEPENDENCY_DIR)],
-                check=True,
-            )
-            print("Download finished.")
-        fcntl.flock(f, fcntl.LOCK_UN)
-
-    # write .pth to site-packages
-    site_packages = Path(site.getsitepackages()[0])
-    pth_file = site_packages / "vllm_omni_dependency.pth"
-    pth_file.write_text(str(DEPENDENCY_DIR))
-    print(f"Added {DEPENDENCY_DIR} to site-packages via {pth_file}")
-
-
-def timed_download(repo_id: str, local_dir: str, allow_patterns: list | None = None):
-    """Download files from HF repo and log time + destination."""
-    if os.path.exists(local_dir):
-        print(f"Directory {local_dir} already exists. Skipping download.")
-        return
-    print(f"Starting download from {repo_id} into {local_dir}")
-    start_time = time.time()
-
-    snapshot_download(
-        repo_id=repo_id,
-        local_dir=local_dir,
-        local_dir_use_symlinks=False,
-        allow_patterns=allow_patterns,
-    )
-
-    elapsed = time.time() - start_time
-    print(f"✅ Finished downloading {repo_id} in {elapsed:.2f} seconds. Files saved at: {local_dir}")
-
-
-def main(output_dir: str):
-    # Wan2.2
-    wan_dir = os.path.join(output_dir, "Wan2.2-TI2V-5B")
-    timed_download(
-        repo_id="Wan-AI/Wan2.2-TI2V-5B",
-        local_dir=wan_dir,
-        allow_patterns=["google/*", "models_t5_umt5-xxl-enc-bf16.pth", "Wan2.2_VAE.pth"],
-    )
-
-    # MMAudio
-    mm_audio_dir = os.path.join(output_dir, "MMAudio")
-    timed_download(
-        repo_id="hkchengrex/MMAudio",
-        local_dir=mm_audio_dir,
-        allow_patterns=["ext_weights/best_netG.pt", "ext_weights/v1-16.pth"],
-    )
-
-    dreamid_dir = os.path.join(output_dir, "DreamID-Omni")
-
-    timed_download(repo_id="XuGuo699/DreamID-Omni", local_dir=dreamid_dir)
-
-    # Now we construct the config file
-    import json
-
-    data = {
-        "_class_name": "DreamIDOmniPipeline",
-    }
-
-    with open(os.path.join(output_dir, "model_index.json"), "w", encoding="utf-8") as f:
-        json.dump(data, f, indent=2)
-
-    print(f"model_index.json created at {os.path.join(output_dir, 'model_index.json')}")
-
-    transformer_dir = os.path.join(output_dir, "transformer")
-    os.makedirs(transformer_dir, exist_ok=True)
-    with open(os.path.join(transformer_dir, "config.json"), "w", encoding="utf-8") as f:
-        json.dump({"fusion": "DreamID-Omni/dreamid_omni.safetensors"}, f)
-    print(f"transformer/config.json created at {os.path.join(transformer_dir, 'config.json')}")
-
-    # now we download the dependency code
-    download_dependency()
-
-
-if __name__ == "__main__":
-    parser = argparse.ArgumentParser(description="Download models from Hugging Face")
-    parser.add_argument(
-        "--output-dir", type=str, default="./dreamid_omni", help="Base directory to save downloaded models"
-    )
-    args = parser.parse_args()
-    main(args.output_dir)

examples/offline_inference/x_to_video_audio/x_to_video_audio.md

@@ -1,163 +0,0 @@
-# X-To-Video-Audio
-
-The `DreamID-Omni` pipeline generates short videos from text, image and video.
-
-## Local CLI Usage
-### Download the Model locally
-Since DreamID-Omni combine multiple models, and without any config, so we need to download them locally.
-
-```bash
-python download_dreamid_omni.py --output-dir ./dreamid_omni
-```
-After download, the model directory will look like this:
-
-```
-dreamid_omni/
-├── DreamID-Omni/
-│   ├── dreamid_omni.safetensors
-├── MMAudio/
-│   ├── ext_weights/
-│   │   ├── best_netG.pt
-│   │   ├── v1-16.pth
-├── Wan2.2-TI2V-5B/
-│   ├── google/*
-│   ├── models_t5_umt5-xxl-enc-bf16.pth
-│   ├── Wan2.2_VAE.pth
-│
-├── model_index.json
-└── transformer/
-    └── config.json   # create by download_dreamid_omni.py
-```
-
-### Run the Inference
-```python
-python x_to_video_audio.py \
-  --model /path/to/dreamid_omni \
-  --prompt "Two people walking together and singing happily" \
-  --image-path ./example0.png ./example1.png \
-  --audio-path ./example0.wav ./example1.wav \
-  --video-negative-prompt "jitter, bad hands, blur, distortion" \
-  --audio-negative-prompt "robotic, muffled, echo, distorted" \
-  --cfg-parallel-size 2 \
-  --num-inference-steps 45 \
-  --height 704 \
-  --width 1280 \
-  --output out_dreamid_omni_twoip.mp4
-```
-In the current test scenario (2 images + 2 audio inputs), the VRAM requirement is 72GB, regardless of whether cfg-parallel is enabled or disabled.
-The VRAM usage can be reduced by enabling CPU offload via --enable-cpu-offload.
-For multi-GPU memory reduction on the fused DreamID-Omni transformer, you can also enable HSDP:
-
-```python
-python x_to_video_audio.py \
-  --model /path/to/dreamid_omni \
-  --prompt "Two people walking together and singing happily" \
-  --image-path ./example0.png ./example1.png \
-  --audio-path ./example0.wav ./example1.wav \
-  --video-negative-prompt "jitter, bad hands, blur, distortion" \
-  --audio-negative-prompt "robotic, muffled, echo, distorted" \
-  --cfg-parallel-size 2 \
-  --num-inference-steps 45 \
-  --height 704 \
-  --width 1280 \
-  --use-hsdp \
-  --hsdp-shard-size 2 \
-  --output out_dreamid_omni_twoip.mp4
-```
-
-
-You could take reference images/audios from the test cases in the official repo: https://github.com/Guoxu1233/DreamID-Omni
-
-For example, single IP ref resources can be found under https://github.com/Guoxu1233/DreamID-Omni/tree/main/test_case/oneip, you could download them correspondingly to your local and use them for testing.
-
-```python
-# Example usage for oneip, ref media from the official repo DreamID-Omni
-python x_to_video_audio.py \
-  --model /path/to/dreamid_omni \
-  --prompt "<img1>: In the frame, a woman with black long hair is identified as <sub1>.\n**Overall Environment/Scene**: A lively open-kitchen café at night; stove flames flare, steam rises, and warm pendant lights swing slightly as staff move behind her. The shot is an upper-body close-up.\n**Main Characters/Subjects Appearance**: <sub1> is a young woman with thick dark wavy hair and a side part. She wears a fitted black top under a light apron, a thin gold chain necklace, and small stud earrings.\n**Main Characters/Subjects Actions**: <sub1> tastes the sauce with a spoon, then turns her face toward the camera while still holding the spoon, her expression shifting from focused to conflicted.\n<sub1> maintains eye contact, swallows as if choosing her words, and says, <S>I keep telling myself I’m fine,but some nights it feels like I’m just performing calm.<E>" \
-  --image-path 9.png \
-  --audio-path 9.wav \
-  --video-negative-prompt "jitter, bad hands, blur, distortion" \
-  --audio-negative-prompt "robotic, muffled, echo, distorted" \
-  --cfg-parallel-size 2 \
-  --num-inference-steps 45 \
-  --height 704 \
-  --width 1280 \
-  --output out_dreamid_omni_oneip.mp4
-```
-
-
-## MagiHuman (`--model-type magi-human`)
-
-MagiHuman is a text → video+audio model with a DiT MoE backbone and a ~9B-param
-T5Gemma text encoder. A detailed text prompt is the only required input; an optional
-image and/or audio file may be supplied for conditioning. Natively supports Tensor
-Parallelism. For an 80GB node, `--tensor-parallel-size 4` is recommended to shard
-the MoE weights and the text encoder.
-
-> Install [MagiCompiler](https://github.com/SandAI-org/MagiCompiler) for correct
-> attention-kernel behaviour (the pipeline otherwise falls back to stubs).
-
-Text-only generation:
-
-```bash
-python x_to_video_audio.py \
-  --model-type magi-human \
-  --model /path/to/daVinci-MagiHuman \
-  --prompt "A young woman with long, wavy golden blonde hair... <dialogue and background sound>" \
-  --tensor-parallel-size 4 \
-  --height 256 --width 448 \
-  --num-inference-steps 8 \
-  --seed 52 \
-  --extra-body '{"seconds": 5, "sr_height": 1080, "sr_width": 1920, "sr_num_inference_steps": 5}' \
-  --output output_magihuman.mp4
-```
-
-With optional image and audio conditioning:
-
-```bash
-python x_to_video_audio.py \
-  --model-type magi-human \
-  --model /path/to/daVinci-MagiHuman \
-  --prompt "A young woman..." \
-  --tensor-parallel-size 4 \
-  --height 256 --width 448 \
-  --num-inference-steps 8 \
-  --seed 52 \
-  --extra-body '{"image_path": "/path/to/ref.jpg", "audio_path": "/path/to/ref.wav", "sr_height": 1080, "sr_width": 1920, "sr_num_inference_steps": 5}' \
-  --output output_magihuman.mp4
-```
-
-MagiHuman-specific arguments are passed as a JSON dict via `--extra-body` (declared
-in `vllm_omni/model_extras/magi_human.py`, routed via `extra_args`):
-
-- `seconds`: output duration in seconds (default 10; ignored when `audio_path` is set,
-  because the audio length then determines the number of frames).
-- `audio_path`: path to an audio file for audio-to-video conditioning. When provided,
-  the audio drives the frame count and is encoded as a latent condition into the DiT
-  (`is_a2v` mode). Omit for pure text-to-video+audio generation.
-- `image_path`: path to an image file for visual conditioning. Applied at both the
-  base-resolution (BR) and super-resolution (SR) stages when SR is enabled.
-- `sr_height` / `sr_width`: super-resolution output resolution. SR stage is skipped
-  when these are omitted.
-- `sr_num_inference_steps`: denoising steps for the SR stage.
-
-## DreamID-Omni arguments
-
-Key arguments:
-- `--prompt`: text description (string).
-- `--model`: path to the model local directory.
-- `--height/--width`: output resolution (defaults 704 * 1024).
-- `--image-path`: path to the input image list.
-- `--audio-path`: path to the input audio list, indicate the timbre of the output video.
-- `--cfg-parallel-size`: number of parallel cfg parallel (defaults 1).
-- `--use-hsdp`: enable HSDP weight sharding for DreamID-Omni fused blocks.
-- `--hsdp-shard-size`: number of GPUs used for HSDP sharding.
-- `--hsdp-replicate-size`: number of HSDP replica groups.
-- `--num-inference-steps`: number of denoising steps (defaults 45).
-- `--video-negative-prompt`: negative prompt for video generation.
-- `--audio-negative-prompt`: negative prompt for audio generation.
-- `--enable-cpu-offload`: enable CPU offload (defaults False).
-- `--cache-backend`: enable `cache_dit` for acceleration.
-- `--quantization`: online (dynamic) quantization method — `fp8` or `int8`.
-  (VAEs, the T5 text encoder, norms and modulation stay bf16.)

examples/offline_inference/x_to_video_audio/x_to_video_audio.py

@@ -1,284 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-
-import argparse
-import json
-import re
-import time
-from typing import Any
-
-import numpy as np
-from PIL import Image
-from vllm.multimodal.media.audio import load_audio
-
-from vllm_omni.diffusion.data import DiffusionParallelConfig
-from vllm_omni.diffusion.utils.media_utils import mux_video_audio_bytes
-from vllm_omni.entrypoints.omni import Omni
-from vllm_omni.inputs.data import OmniDiffusionSamplingParams
-
-IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".bmp", ".webp", ".gif"}
-AUDIO_EXTENSIONS = {".wav", ".mp3", ".flac", ".m4a", ".aac", ".ogg"}
-
-
-def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="Offline inference for X -> video+audio models.")
-    parser.add_argument("--model", required=True, help="Model ckpt root directory.")
-    parser.add_argument(
-        "--model-type",
-        default="dreamid-omni",
-        choices=["dreamid-omni", "magi-human"],
-        help="Model type.",
-    )
-    parser.add_argument("--prompt", default=None, help="Text prompt.")
-
-    parser.add_argument("--image-path", type=str, nargs="+", help="list of image-path")
-    parser.add_argument("--audio-path", type=str, nargs="+", help="list of audio-path")
-    parser.add_argument("--prompt-file", type=str, default=None, help="Text prompt in json format.")
-    parser.add_argument(
-        "--extra-body",
-        type=str,
-        default=None,
-        help="[magi-human] JSON dict of model-specific extra params (declared in vllm_omni/model_extras/), "
-        'merged into sampling extra_args. Example: \'{"image_path": "/path/to/img.jpg", "seconds": 5}\'.',
-    )
-
-    parser.add_argument("--height", type=int, default=704, help="Video height.")
-    parser.add_argument("--width", type=int, default=1280, help="Video width.")
-    parser.add_argument("--num-inference-steps", type=int, default=45, help="Sampling steps.")
-    parser.add_argument("--solver-name", default="unipc", help="Solver name: unipc|dpm++|euler.")
-    parser.add_argument("--shift", type=float, default=5.0, help="Scheduler shift.")
-    parser.add_argument("--seed", type=int, default=103, help="Random seed for reproducible generation.")
-    parser.add_argument(
-        "--cfg-parallel-size",
-        type=int,
-        default=1,
-        choices=[1, 2, 3, 4],
-        help="Number of GPUs used for classifier free guidance parallel size (max 4 branches).",
-    )
-    parser.add_argument(
-        "--tensor-parallel-size",
-        type=int,
-        default=1,
-        help=("Number of GPUs used for tensor parallelism (TP) inside the DiT."),
-    )
-    parser.add_argument(
-        "--video-negative-prompt",
-        default="jitter, bad hands, blur, distortion",
-        help="Negative prompt for video.",
-    )
-    parser.add_argument(
-        "--audio-negative-prompt",
-        default="robotic, muffled, echo, distorted",
-        help="Negative prompt for audio.",
-    )
-    parser.add_argument("--output", default="dreamid_output.mp4", help="Output video path.")
-    parser.add_argument(
-        "--quantization",
-        type=str,
-        default=None,
-        choices=["fp8", "int8"],
-        help=("Online (dynamic) quantization method for the DreamID-Omni transformer. "),
-    )
-    parser.add_argument(
-        "--enable-cpu-offload",
-        action="store_true",
-        default=False,
-        help="Enable CPU offloading for diffusion models.",
-    )
-    parser.add_argument(
-        "--enable-layerwise-offload",
-        action="store_true",
-        help="Enable layerwise (blockwise) offloading on DiT modules.",
-    )
-    parser.add_argument("--cache-backend", type=str, default=None, choices=["cache_dit"], help="Cache backend.")
-    parser.add_argument(
-        "--use-hsdp",
-        action="store_true",
-        help="Enable HSDP for DreamID-Omni fused transformer blocks.",
-    )
-    parser.add_argument(
-        "--hsdp-shard-size",
-        type=int,
-        default=1,
-        help="Number of GPUs used for HSDP sharding when HSDP is enabled.",
-    )
-    parser.add_argument(
-        "--hsdp-replicate-size",
-        type=int,
-        default=1,
-        help="Number of HSDP replica groups. Default 1 means pure sharding.",
-    )
-    return parser.parse_args()
-
-
-def load_image_and_audio(image_paths, audio_paths):
-    image = []
-    audio = []
-
-    for path in image_paths:
-        with Image.open(path) as img:
-            img = img.convert("RGB")
-            image.append(img)
-
-    for path in audio_paths:
-        audio_array, sr = load_audio(path, sr=16000)
-        audio_array = audio_array[int(sr * 1) : int(sr * 3)]
-        audio.append(audio_array)
-    return image, audio
-
-
-def _extract_peak_memory_mb(result: Any) -> float:
-    """Pull worker-reported peak VRAM (MiB) generation result.
-
-    Mirrors vllm_omni/entrypoints/openai/serving_video.py:_extract_peak_memory_mb.
-    """
-    if isinstance(result, list):
-        result = result[0] if result else None
-    if result is None:
-        return 0.0
-    val = getattr(result, "peak_memory_mb", 0.0)
-    if not val:
-        inner = result
-        if isinstance(inner, list):
-            inner = inner[0] if inner else None
-        val = getattr(inner, "peak_memory_mb", 0.0)
-    try:
-        return float(val or 0.0)
-    except (TypeError, ValueError):
-        return 0.0
-
-
-def main() -> None:
-    args = parse_args()
-    if args.prompt is None and args.prompt_file is None:
-        raise ValueError("Either --prompt or --prompt-file must be provided.")
-
-    text_prompt = args.prompt
-    if args.prompt_file:
-        with open(args.prompt_file) as f:
-            text_prompt = json.load(f)
-            text_prompt = re.sub(
-                r"\[SPEAKER_TIMESTAMPS_START\].*?\[SPEAKER_TIMESTAMPS_END\]", "", text_prompt, flags=re.DOTALL
-            ).strip()
-            text_prompt = re.sub(
-                r"\[AUDIO_DESCRIPTION_START].*?\[AUDIO_DESCRIPTION_END]", "", text_prompt, flags=re.DOTALL
-            ).strip()
-            text_prompt = re.sub(r"\[[A-Z_]+\]", "", text_prompt)
-            text_prompt = re.sub(r"\n\s*\n", "\n", text_prompt).strip()
-
-    if args.model_type == "magi-human":
-        prompt = text_prompt
-        extra_args = json.loads(args.extra_body) if args.extra_body else {}
-        sampling_params = OmniDiffusionSamplingParams(
-            height=args.height,
-            width=args.width,
-            num_inference_steps=args.num_inference_steps,
-            seed=args.seed,
-            extra_args=extra_args,
-        )
-    else:
-        image, audio = load_image_and_audio(args.image_path, args.audio_path)
-
-        prompt = {
-            "prompt": text_prompt,
-            "video_negative_prompt": args.video_negative_prompt,
-            "audio_negative_prompt": args.audio_negative_prompt,
-            "multi_modal_data": {"image": image, "audio": audio},
-        }
-
-        sampling_params = OmniDiffusionSamplingParams(
-            height=args.height,
-            width=args.width,
-            num_inference_steps=args.num_inference_steps,
-            seed=args.seed,
-            extra_args={
-                "solver_name": args.solver_name,
-                "shift": args.shift,
-            },
-        )
-
-    parallel_config = DiffusionParallelConfig(
-        cfg_parallel_size=args.cfg_parallel_size,
-        tensor_parallel_size=args.tensor_parallel_size,
-        use_hsdp=args.use_hsdp,
-        hsdp_shard_size=args.hsdp_shard_size,
-        hsdp_replicate_size=args.hsdp_replicate_size,
-    )
-
-    cache_config = None
-    if args.cache_backend == "cache_dit":
-        cache_config = {
-            "Fn_compute_blocks": 1,
-            "Bn_compute_blocks": 0,
-            "max_warmup_steps": 4,
-            "max_cached_steps": 20,
-            "residual_diff_threshold": 0.24,
-            "max_continuous_cached_steps": 3,
-            "enable_taylorseer": False,
-            "taylorseer_order": 1,
-            "scm_steps_mask_policy": None,
-            "scm_steps_policy": "dynamic",
-        }
-
-    omni_kwargs = dict(
-        model=args.model,
-        parallel_config=parallel_config,
-        model_type=args.model_type,
-        enable_cpu_offload=args.enable_cpu_offload,
-        enable_layerwise_offload=args.enable_layerwise_offload,
-        cache_backend=args.cache_backend,
-        cache_config=cache_config,
-    )
-    if args.quantization is not None:
-        omni_kwargs["quantization"] = args.quantization
-    omni = Omni(**omni_kwargs)
-    start = time.perf_counter()
-    outputs = omni.generate(prompt, sampling_params)
-    elapsed = time.perf_counter() - start
-
-    if not outputs:
-        raise RuntimeError("No output returned from the model.")
-    result = outputs[0]
-    if not result.images:
-        raise RuntimeError("No video frames found in model output.")
-    generated_video = result.images[0]
-    mm = result.multimodal_output or {}
-    generated_audio = mm.get("audio")
-
-    if args.model_type == "magi-human":
-        # MagiHuman returns frames already as (F, H, W, C) uint8, ready to mux.
-        fps = float(mm.get("fps", 25))
-        sample_rate = int(mm.get("audio_sample_rate", 24000))
-        frames = generated_video
-    else:
-        fps = float(mm.get("fps", 24))
-        sample_rate = int(mm.get("audio_sample_rate", 16000))
-        # DreamID-Omni returns video as (C, F, H, W) float32 in [-1, 1].
-        # mux_video_audio_bytes expects (F, H, W, C) uint8.
-        if not isinstance(generated_video, np.ndarray) or generated_video.ndim != 4:
-            raise RuntimeError(f"Unexpected video shape: {getattr(generated_video, 'shape', None)}")
-        frames = generated_video.transpose(1, 2, 3, 0)
-        frames = (np.clip((frames + 1.0) / 2.0, 0.0, 1.0) * 255.0).round().astype(np.uint8)
-
-    audio_np = None
-    if generated_audio is not None:
-        audio_np = np.squeeze(np.asarray(generated_audio)).astype(np.float32)
-
-    output_path = args.output
-    video_bytes = mux_video_audio_bytes(
-        frames,
-        audio_np,
-        fps=float(fps),
-        audio_sample_rate=sample_rate,
-    )
-    with open(output_path, "wb") as f:
-        f.write(video_bytes)
-    print(f"Saved generated video to {output_path}")
-    print(f"Total time: {elapsed:.2f}s")
-    peak_mb = _extract_peak_memory_mb(outputs)
-    if peak_mb:
-        print(f"Worker peak GPU memory (reserved): {peak_mb:.2f} MiB ({peak_mb / 1024:.2f} GiB)")
-
-
-if __name__ == "__main__":
-    main()

examples/online_serving/audiox/README.md

@@ -1,64 +0,0 @@
-# AudioX online serving
-
-Launches the `AudioXPipeline` behind vLLM-Omni's OpenAI-compatible chat endpoint and provides a
-minimal Python client that covers all six tasks (`t2a`, `t2m`, `v2a`, `v2m`, `tv2a`, `tv2m`).
-
-## Start the server
-
-```bash
-cd examples/online_serving/audiox
-bash run_server.sh                 # defaults: MODEL=zhangj1an/AudioX, PORT=8099
-```
-
-Environment overrides: `MODEL`, `PORT`, `DIFFUSION_ATTENTION_BACKEND`.
-
-## Call from Python
-
-```bash
-# text-to-audio
-python openai_chat_client.py --task t2a \
-    --prompt "Fireworks burst twice, followed by a period of silence before a clock begins ticking." \
-    --output t2a.wav
-
-# text-to-music
-python openai_chat_client.py --task t2m \
-    --prompt "Uplifting ukulele tune for a travel vlog" \
-    --output t2m.wav
-
-# video-to-audio (no text)
-python openai_chat_client.py --task v2a --video path/to/clip.mp4 --output v2a.wav
-
-# text+video-to-audio
-python openai_chat_client.py --task tv2a \
-    --prompt "drum beating sound and human talking" \
-    --video path/to/clip.mp4 \
-    --output tv2a.wav
-```
-
-The client sends:
-
-- `num_inference_steps`, `guidance_scale`, `seed`, `audiox_task`, `seconds_start`,
-  `seconds_total`, `sigma_min`, `sigma_max` as flattened keys under `extra_body`. The server
-  routes the declared knobs (see `vllm_omni/model_extras/audiox.py`) into the pipeline's
-  `sampling_params.extra_args`.
-- For `v2*` / `tv2*` tasks, the video as a `video_url` content item (data URI for local files)
-
-## curl
-
-```bash
-curl -sS -X POST http://localhost:8099/v1/chat/completions \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "model": "zhangj1an/AudioX",
-    "messages": [{"role": "user", "content": [{"type": "text", "text": "Uplifting ukulele"}]}],
-    "extra_body": {
-      "num_inference_steps": 250,
-      "guidance_scale": 7.0,
-      "seed": 42,
-      "audiox_task": "t2m",
-      "seconds_total": 10.0,
-      "sigma_min": 0.3,
-      "sigma_max": 500.0
-    }
-  }' > t2m.json
-```

examples/online_serving/audiox/openai_chat_client.py

@@ -1,119 +0,0 @@
-#!/usr/bin/env python3
-"""AudioX OpenAI-compatible chat client.
-
-AudioX supports 6 tasks (t2a, t2m, v2a, v2m, tv2a, tv2m). Text-only tasks send the prompt as the
-chat message; video-conditioned tasks additionally attach the video via a ``video_url`` content
-item (data URI for local files). Task + generation knobs (steps, cfg, sigma range, seconds, seed)
-are sent as flattened keys under ``extra_body``; the server routes the declared knobs into
-``sampling_params.extra_args`` (see ``vllm_omni/model_extras/audiox.py``).
-
-Usage:
-  python openai_chat_client.py --task t2a --prompt "Fireworks burst twice..." --output t2a.wav
-  python openai_chat_client.py --task tv2a --prompt "drum beating" --video clip.mp4 -o tv2a.wav
-"""
-
-from __future__ import annotations
-
-import argparse
-import base64
-import io
-import mimetypes
-import sys
-from pathlib import Path
-
-import requests
-import soundfile
-import torch
-
-VIDEO_TASKS = frozenset({"v2a", "v2m", "tv2a", "tv2m"})
-TEXT_TASKS = frozenset({"t2a", "t2m", "tv2a", "tv2m"})
-
-
-def _to_data_url(path: str) -> str:
-    mime, _ = mimetypes.guess_type(path)
-    mime = mime or "video/mp4"
-    with open(path, "rb") as f:
-        data = base64.b64encode(f.read()).decode("ascii")
-    return f"data:{mime};base64,{data}"
-
-
-def _save_wav(audio: torch.Tensor, path: Path, sample_rate: int) -> None:
-    audio = audio.to(torch.float32)
-    audio = audio / audio.abs().max().clamp(min=1e-8)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    # soundfile expects channels-last (T, C); project convention is (C, T).
-    soundfile.write(str(path), audio.clamp(-1.0, 1.0).cpu().T.numpy(), sample_rate, subtype="PCM_16")
-
-
-def _decode_audio_from_response(body: dict) -> tuple[torch.Tensor, int]:
-    for choice in body.get("choices", []):
-        audio_obj = choice.get("message", {}).get("audio")
-        if not (isinstance(audio_obj, dict) and audio_obj.get("data")):
-            continue
-        data, sr = soundfile.read(io.BytesIO(base64.b64decode(audio_obj["data"])), dtype="float32", always_2d=True)
-        return torch.from_numpy(data).transpose(0, 1), sr
-    brief = {k: v for k, v in body.items() if k != "choices"}
-    raise RuntimeError(f"no audio in response message.audio: {brief}")
-
-
-def main() -> int:
-    p = argparse.ArgumentParser(description="AudioX OpenAI chat client")
-    p.add_argument("--task", required=True, choices=["t2a", "t2m", "v2a", "v2m", "tv2a", "tv2m"])
-    p.add_argument("--prompt", "-p", default="", help="Text prompt (required for t2*/tv2*).")
-    p.add_argument("--video", help="Video path or URL (required for v2*/tv2*).")
-    p.add_argument("--output", "-o", default="audiox_out.wav")
-    p.add_argument("--server", "-s", default="http://localhost:8099")
-    p.add_argument("--model", default="zhangj1an/AudioX")
-    p.add_argument("--steps", type=int, default=250)
-    p.add_argument("--guidance-scale", type=float, default=7.0)
-    p.add_argument("--seed", type=int, default=42)
-    p.add_argument("--seconds-total", type=float, default=10.0)
-    p.add_argument("--seconds-start", type=float, default=0.0)
-    p.add_argument("--sigma-min", type=float, default=0.03)
-    p.add_argument("--sigma-max", type=float, default=1000.0)
-    args = p.parse_args()
-
-    if args.task in VIDEO_TASKS and not args.video:
-        print(f"ERROR: task {args.task!r} requires --video", file=sys.stderr)
-        return 2
-    if args.task in TEXT_TASKS and not args.prompt.strip() and args.task not in {"v2a", "v2m"}:
-        print(f"ERROR: task {args.task!r} requires --prompt", file=sys.stderr)
-        return 2
-
-    content: list[dict] = [{"type": "text", "text": args.prompt}]
-    if args.task in VIDEO_TASKS:
-        vurl = args.video if args.video.startswith(("http://", "https://")) else _to_data_url(args.video)
-        content.append({"type": "video_url", "video_url": {"url": vurl}})
-
-    payload = {
-        "model": args.model,
-        "messages": [{"role": "user", "content": content}],
-        "extra_body": {
-            "num_inference_steps": args.steps,
-            "guidance_scale": args.guidance_scale,
-            "seed": args.seed,
-            "audiox_task": args.task,
-            "seconds_start": args.seconds_start,
-            "seconds_total": args.seconds_total,
-            "sigma_min": args.sigma_min,
-            "sigma_max": args.sigma_max,
-        },
-    }
-
-    print(f"POST {args.server}/v1/chat/completions  task={args.task} steps={args.steps}")
-    r = requests.post(
-        f"{args.server}/v1/chat/completions",
-        headers={"Content-Type": "application/json"},
-        json=payload,
-        timeout=600,
-    )
-    r.raise_for_status()
-    audio, sr = _decode_audio_from_response(r.json())
-    _save_wav(audio, Path(args.output), sr)
-    dur = audio.shape[-1] / sr
-    print(f"saved {args.output}  sr={sr}Hz  duration={dur:.2f}s  channels={audio.shape[0]}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

examples/online_serving/audiox/run_server.sh

@@ -1,16 +0,0 @@
-#!/bin/bash
-# AudioX online serving startup script.
-
-MODEL="${MODEL:-zhangj1an/AudioX}"
-PORT="${PORT:-8099}"
-DIFFUSION_ATTENTION_BACKEND="${DIFFUSION_ATTENTION_BACKEND:-FLASH_ATTN}"
-
-echo "Starting AudioX server..."
-echo "Model: $MODEL"
-echo "Port: $PORT"
-echo "Diffusion attention backend: $DIFFUSION_ATTENTION_BACKEND"
-
-DIFFUSION_ATTENTION_BACKEND="$DIFFUSION_ATTENTION_BACKEND" \
-    vllm serve "$MODEL" --omni \
-        --model-class-name AudioXPipeline \
-        --port "$PORT"

examples/online_serving/image_to_video/README.md

@@ -1,5 +1,19 @@
 # Image-To-Video
 
+This example demonstrates how to deploy image-to-video models for online
+video generation using vLLM-Omni.
+
+## Supported Models
+
+| Model | Model ID |
+|-------|----------|
+| Wan2.2 I2V | `Wan-AI/Wan2.2-I2V-A14B-Diffusers` |
+| SANA-Video 2B (480p) | `Efficient-Large-Model/SANA-Video_2B_480p_diffusers` |
+| SANA-Video 2B (720p) | `Efficient-Large-Model/SANA-Video_2B_720p_diffusers` |
+
+For SANA-Video 2B image-to-video online serving, see the
+[SANA-Video 2B recipe](../../../recipes/NVIDIA/SANA-Video-2B.md).
+
 This example demonstrates online image-to-video generation with vLLM-Omni.
 The startup script defaults to Wan2.2, but `MODEL` can select any supported
 image-to-video model. The existing curl helper remains a concrete Wan2.2

examples/online_serving/image_to_video/run_curl_sana_video.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# Submit and download a standard SANA-Video-2B image-to-video request.
+
+set -euo pipefail
+
+INPUT_IMAGE="${INPUT_IMAGE:-}"
+BASE_URL="${BASE_URL:-http://localhost:8099}"
+OUTPUT_PATH="${OUTPUT_PATH:-sana_video_i2v.mp4}"
+WIDTH="${WIDTH:-832}"
+HEIGHT="${HEIGHT:-480}"
+POLL_INTERVAL="${POLL_INTERVAL:-2}"
+
+if [ -z "$INPUT_IMAGE" ] || [ ! -f "$INPUT_IMAGE" ]; then
+    echo "Set INPUT_IMAGE to an existing image file."
+    exit 1
+fi
+
+create_response="$(
+    curl -sS -X POST "${BASE_URL}/v1/videos" \
+        -H "Accept: application/json" \
+        -F "prompt=A cat turns toward the camera with smooth, natural motion." \
+        -F "negative_prompt=blurry, low quality, temporal artifacts" \
+        -F "input_reference=@${INPUT_IMAGE}" \
+        -F "width=${WIDTH}" \
+        -F "height=${HEIGHT}" \
+        -F "num_frames=81" \
+        -F "fps=16" \
+        -F "num_inference_steps=50" \
+        -F "guidance_scale=6.0" \
+        -F "seed=42" \
+        -F 'extra_params={"motion_score":30}'
+)"
+
+video_id="$(echo "${create_response}" | jq -r '.id')"
+if [ -z "${video_id}" ] || [ "${video_id}" = "null" ]; then
+    echo "Failed to create SANA-Video job:"
+    echo "${create_response}" | jq .
+    exit 1
+fi
+
+while true; do
+    status_response="$(curl -sS "${BASE_URL}/v1/videos/${video_id}")"
+    status="$(echo "${status_response}" | jq -r '.status')"
+
+    case "${status}" in
+        queued|in_progress)
+            echo "Video job ${video_id} status: ${status}"
+            sleep "${POLL_INTERVAL}"
+            ;;
+        completed)
+            break
+            ;;
+        failed)
+            echo "SANA-Video generation failed:"
+            echo "${status_response}" | jq .
+            exit 1
+            ;;
+        *)
+            echo "Unexpected status response:"
+            echo "${status_response}" | jq .
+            exit 1
+            ;;
+    esac
+done
+
+curl -sS -L "${BASE_URL}/v1/videos/${video_id}/content" -o "${OUTPUT_PATH}"
+echo "Saved SANA-Video to ${OUTPUT_PATH}"

examples/online_serving/image_to_video/run_server_sana_video.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+# SANA-Video-2B native image-to-video serving.
+
+set -euo pipefail
+
+MODEL="${MODEL:-Efficient-Large-Model/SANA-Video_2B_480p_diffusers}"
+PORT="${PORT:-8099}"
+
+vllm serve "$MODEL" \
+    --omni \
+    --model-class-name SanaImageToVideoPipeline \
+    --dtype bfloat16 \
+    --port "$PORT"

examples/online_serving/image_to_video/run_server_sana_video_diffusers.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# SANA-Video-2B image-to-video serving through the Diffusers adapter.
+# Both 480p and 720p checkpoints are validated. For 720p:
+# MODEL=Efficient-Large-Model/SANA-Video_2B_720p_diffusers bash run_server_sana_video_diffusers.sh
+# INPUT_IMAGE=input.jpg WIDTH=1280 HEIGHT=704 bash run_curl_sana_video.sh
+
+set -euo pipefail
+
+MODEL="${MODEL:-Efficient-Large-Model/SANA-Video_2B_480p_diffusers}"
+PORT="${PORT:-8099}"
+
+vllm serve "$MODEL" \
+    --omni \
+    --model-class-name SanaImageToVideoPipeline \
+    --diffusion-load-format diffusers \
+    --diffusion-attention-backend TORCH_SDPA \
+    --dtype bfloat16 \
+    --port "$PORT"

examples/online_serving/mimo_audio/openai_chat_completion_client_for_multimodal_generation.py

@@ -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)

examples/online_serving/minicpmo/README.md

@@ -32,12 +32,14 @@ GPU 0 (90%) and colocates the Talker (55%) and Code2Wav (35%) on GPU 1. That
 profile admits at most four concurrent sequences per stage.
 
 | deploy config | GPUs | Notes |
-|---|---|---|
+| --- | --- | --- |
 | `minicpmo_4_5.yaml` (default) | 1 | Memory-constrained compatibility layout. |
 | `minicpmo_4_5_2gpu.yaml` | 2 | Recommended continuous-batching layout; Talker and Code2Wav share GPU 1. |
 | `minicpmo_4_5_3gpu.yaml` | 3 | One GPU per stage. |
 | `minicpmo_4_5_8x4090.yaml` | 8 | Full 8x4090 layout. |
-| `minicpmo_4_5_duplex.yaml` | 1 | Experimental native full-duplex overlay. |
+
+Every profile sets `session_mode: duplex`, so native full-duplex is served
+from the same process as `/v1/chat/completions`.
 
 The split pipeline preserves native-duplex epoch/turn identity, segment text,
 turn completion, reference voice, and terminal-audio metadata through
@@ -55,8 +57,8 @@ vllm serve openbmb/MiniCPM-o-4_5 \
 ```
 
 For local ModelScope checkpoints, replace `openbmb/MiniCPM-o-4_5` with the
-checkpoint path. To start the experimental native duplex backend, use
-`vllm_omni/deploy/minicpmo_4_5_duplex.yaml`.
+checkpoint path. For native full-duplex, connect `/v1/realtime?duplex=1` on
+this same server.
 
 ### Per-stage overrides
 
@@ -145,7 +147,7 @@ assistant template, so it is not an apples-to-apples accuracy run.
 
 ## Run the Realtime duplex CLI demo
 
-After the duplex backend is running, stream one WAV through the Realtime
+After the server is running, stream one WAV through the Realtime
 WebSocket endpoint:
 
 ```bash
@@ -157,6 +159,33 @@ python examples/online_serving/minicpmo/realtime_duplex_demo.py \
     --output-dir /tmp/minicpmo_realtime_duplex_demo
 ```
 
+Video input uses the same session. PyAV demuxes JPEG frames at `--video-fps`
+(default 1.0) and vLLM `load_audio` extracts a 16 kHz mono WAV unless
+`--input-wav` overrides the soundtrack. Frames keep their capture size
+(`--frame-max-side 0`); the server `process_image` normalizes at 448.
+
+`--stack-frames N` raises the visual refresh rate the way official duplex does:
+each 1 s unit also samples the `N-1` sub-frames captured inside it and tiles
+them into a single composite image sent next to that unit's base frame. The
+audio cadence never changes — a unit is always one second — and the wire always
+carries 2 images per unit however large `N` is, because the sub-frames share one
+composite. Official uses 5 for high refresh rate mode:
+
+```bash
+python examples/online_serving/minicpmo/realtime_duplex_demo.py \
+    --url ws://localhost:8099/v1/realtime?duplex=1 \
+    --model openbmb/MiniCPM-o-4_5 \
+    --input-video /path/to/clip.mp4 \
+    --stack-frames 5 \
+    --ref-audio /path/to/MiniCPM-o-Demo/assets/ref_audio/ref_minicpm_signature.wav \
+    --output-dir /tmp/minicpmo_realtime_duplex_video_demo
+```
+
+Detail inside a composite is capped by `scale_resolution=448` at
+`max_slice_nums=1`: official suggests HD slicing (`max_slice_nums=[2, 1]`) for
+stacked frames, which the duplex adapter does not implement yet. Reading small
+text or digits out of a wide scene is limited by that, not by frame timing.
+
 ## Open the experimental browser client
 
 The browser UI serves the page and proxies the same-origin Realtime WebSocket to
@@ -190,6 +219,64 @@ stronger `response-required` mode is diagnostic: it requires a purpose-built
 two-response WAV, its `--input-sha256`, and an
 `--expect-second-response-substring` value.
 
+## Run Omni-DuplexEval
+
+Omni-DuplexEval generation uses the vLLM-Omni native MiniCPM-o duplex
+endpoint. Evaluation uses a separate OpenAI-compatible multimodal judge
+served from the same vLLM-Omni environment. This validates the vLLM-Omni
+duplex client and local judge integration; it does not reproduce the paper's
+original MiniCPM-o inference implementation.
+
+Start the duplex generation server:
+
+```bash
+vllm serve openbmb/MiniCPM-o-4_5 --omni --trust-remote-code \
+    --deploy-config vllm_omni/deploy/minicpmo_4_5_duplex.yaml \
+    --served-model-name openbmb/MiniCPM-o-4_5 \
+    --host 0.0.0.0 --port 8099
+```
+
+Start a separate multimodal judge. The allowed path must contain any local
+videos passed with `--judge-video-mode video_url`:
+
+```bash
+vllm serve Qwen/Qwen2.5-VL-7B-Instruct \
+    --served-model-name Qwen/Qwen2.5-VL-7B-Instruct \
+    --allowed-local-media-path /data/omni-duplex-eval \
+    --host 0.0.0.0 --port 8000
+```
+
+Generate, evaluate, and summarize:
+
+```bash
+vllm bench omni-duplex-eval --omni generate \
+    --url ws://127.0.0.1:8099/v1/realtime?duplex=1 \
+    --model openbmb/MiniCPM-o-4_5 \
+    --ref-audio /data/ref.wav \
+    --dataset Hothan/Omni-DuplexEval \
+    --concurrency 2 \
+    --response-root /data/omni-duplex-eval/responses
+
+vllm bench omni-duplex-eval --omni evaluate \
+    --dataset Hothan/Omni-DuplexEval \
+    --response-root /data/omni-duplex-eval/responses \
+    --score-root /data/omni-duplex-eval/scores \
+    --judge-base-url http://127.0.0.1:8000 \
+    --judge-model Qwen/Qwen2.5-VL-7B-Instruct \
+    --judge-video-mode video_url \
+    --eval-workers 4
+
+vllm bench omni-duplex-eval --omni summarize \
+    --score-root /data/omni-duplex-eval/scores
+```
+
+The dataset names such as `RTD_OCR` and `PR_correction` are Hugging Face
+splits, not dataset configurations. Pass one with `--split`, or omit it to
+run all nine splits. `--limit 1` is useful for a smoke test. Realtime
+generation records `clock=media`; artifacts generated with
+`--pace as-fast-as-possible` record `clock=invalid` and evaluation rejects
+them unless `--allow-invalid-clock` is explicit.
+
 ## Related examples
 
 - [Offline MiniCPM-o inference](../../offline_inference/minicpmo/)

examples/online_serving/minicpmo/realtime_duplex_demo.py

@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 """Minimal single-input MiniCPM-o 4.5 Realtime duplex demo.
 
 Run this after starting the duplex server. Strict lifecycle, overlap, and
@@ -9,7 +12,9 @@ from __future__ import annotations
 import argparse
 import asyncio
 import base64
+import io
 import json
+import math
 import sys
 import time
 from pathlib import Path
@@ -28,6 +33,17 @@ from vllm_omni.experimental.fullduplex.client import (  # noqa: E402
     wait_for,
     write_pcm16_wav,
 )
+from vllm_omni.experimental.fullduplex.client import chunk_period_ms as _chunk_period_ms  # noqa: E402
+from vllm_omni.experimental.fullduplex.client import (  # noqa: E402
+    has_residual_model_unit as _has_residual_model_unit,
+)
+from vllm_omni.experimental.fullduplex.client import (  # noqa: E402
+    reference_audio_data_url as _ref_audio_data_url,
+)
+from vllm_omni.experimental.fullduplex.video_stacking import (  # noqa: E402
+    concat_frames_b64,
+    unit_subframe_offsets,
+)
 
 
 class _StreamingOutputWriter:
@@ -133,31 +149,29 @@ def _latest_model_decision(
     return decision
 
 
-def _chunk_period_ms(events: list[dict[str, object]]) -> int:
-    for event in reversed(events):
-        session = event.get("session")
-        if not isinstance(session, dict):
-            continue
-        capabilities = session.get("capabilities")
-        if not isinstance(capabilities, dict):
-            continue
-        chunk_period_ms = capabilities.get("chunk_period_ms")
-        if isinstance(chunk_period_ms, int) and chunk_period_ms > 0:
-            return chunk_period_ms
-    return 1000
-
-
-def _has_residual_model_unit(pcm16: bytes, *, chunk_period_ms: int) -> bool:
-    unit_bytes = PCM16_SAMPLE_RATE * PCM16_BYTES_PER_SAMPLE * chunk_period_ms // 1000
-    return bool(unit_bytes > 0 and len(pcm16) % unit_bytes)
-
-
 def _response_in_progress(events: list[dict[str, object]]) -> bool:
     return sum(event.get("type") == "response.created" for event in events) > sum(
         event.get("type") == "response.done" for event in events
     )
 
 
+async def _commit_input_after_playback_checkpoint(client: RealtimeDuplexClient) -> float:
+    """Commit input only after preserving already-played assistant history.
+
+    Native duplex can finish several responses while the user is still
+    streaming.  Under the ``ack_only`` playback policy, acknowledging those
+    responses after the final input commit is intentionally rejected: it could
+    append an old assistant message after the newly committed user message.
+    Checkpoint playback first so the server commits each assistant item at its
+    original history position.  A second acknowledgement after the commit can
+    then safely advance response-local playback that drained in the meantime.
+    """
+    await client.acknowledge_playback()
+    commit_sent_at_s = time.monotonic()
+    await client.commit()
+    return commit_sent_at_s
+
+
 def _event_count_after(
     events: list[dict[str, object]],
     event_type: str,
@@ -168,21 +182,258 @@ def _event_count_after(
     return sum(event.get("type") == event_type for event in events[index + 1 :])
 
 
-def _ref_audio_data_url(path: str | None) -> str | None:
-    if path is None:
-        return None
-    ref_path = Path(path).expanduser()
-    return "data:audio/wav;base64," + base64.b64encode(ref_path.read_bytes()).decode("ascii")
+def _probe_video_frames_and_fps(video_path: Path) -> tuple[int, float]:
+    """Frame count and average FPS via PyAV (same approach as Daily-Omni)."""
+    import av
+
+    with av.open(str(video_path)) as container:
+        stream = container.streams.video[0]
+        avg_fps = float(stream.average_rate) if stream.average_rate else 0.0
+        num_frames = stream.frames or 0
+        if num_frames <= 0:
+            duration: float | None = None
+            if stream.duration is not None and stream.time_base is not None:
+                duration = float(stream.duration * stream.time_base)
+            elif container.duration is not None:
+                duration = container.duration / av.time_base
+            if duration and avg_fps:
+                num_frames = int(math.floor(duration * avg_fps))
+        if num_frames <= 0:
+            stream.thread_type = "AUTO"
+            num_frames = sum(1 for _ in container.decode(stream))
+    if num_frames <= 0:
+        raise ValueError(f"No decodable video frames in {video_path}")
+    return num_frames, avg_fps or 1.0
+
+
+def _upright(image, rotation: int):
+    """Apply a container display-matrix rotation, in degrees, to ``image``.
+
+    PyAV hands back the stored raster and leaves the display matrix for the
+    caller, unlike the ffmpeg CLI which autorotates. Phone clips routinely
+    carry +/-90, so skipping this feeds the model a sideways frame: arrows and
+    digits stop being readable and the model mirrors the motion it reports.
+    """
+    from PIL import Image
+
+    quarter_turns = {
+        90: Image.Transpose.ROTATE_90,
+        180: Image.Transpose.ROTATE_180,
+        270: Image.Transpose.ROTATE_270,
+    }
+    turn = quarter_turns.get(int(rotation) % 360)
+    return image.transpose(turn) if turn is not None else image
+
+
+def _decode_video_frames_rgb(video_path: Path, frame_idx: list[int]) -> list:
+    """Decode presentation-order ``frame_idx`` into upright RGB ``PIL.Image``s."""
+    import av
+
+    wanted = sorted({int(i) for i in frame_idx})
+    if not wanted:
+        return []
+
+    decoded: dict[int, object] = {}
+    with av.open(str(video_path)) as container:
+        stream = container.streams.video[0]
+        stream.thread_type = "AUTO"
+        cursor = 0
+        for position, frame in enumerate(container.decode(stream)):
+            if wanted[cursor] > position:
+                continue
+            image = _upright(frame.to_image(), getattr(frame, "rotation", 0) or 0)
+            while cursor < len(wanted) and wanted[cursor] <= position:
+                decoded[wanted[cursor]] = image
+                cursor += 1
+            if cursor >= len(wanted):
+                break
+
+    if not decoded:
+        raise ValueError(f"Decoded no frames from {video_path} for indices {wanted[:8]}")
+    last_image = decoded[max(decoded)]
+    return [decoded.get(int(i), last_image) for i in frame_idx]
+
+
+def _resize_max_side(image, max_side: int):
+    width, height = image.size
+    longest = max(width, height)
+    if longest <= max_side or max_side <= 0:
+        return image
+    scale = max_side / float(longest)
+    new_size = (max(1, int(round(width * scale))), max(1, int(round(height * scale))))
+    return image.resize(new_size)
+
+
+def _jpeg_bytes(image, *, quality: int = 95) -> bytes:
+    buf = io.BytesIO()
+    image.convert("RGB").save(buf, format="JPEG", quality=quality)
+    return buf.getvalue()
+
+
+def _to_pcm16_bytes(audio_np) -> bytes:
+    import numpy as np
+
+    arr = np.asarray(audio_np).reshape(-1)
+    if arr.dtype != np.int16:
+        arr = (np.clip(arr, -1.0, 1.0) * 32767.0).astype(np.int16)
+    return arr.tobytes()
+
+
+def _pcm16_wav_duration_s(path: Path) -> float:
+    pcm16 = read_pcm16_wav(path)
+    return len(pcm16) / float(PCM16_SAMPLE_RATE * PCM16_BYTES_PER_SAMPLE)
+
+
+def _extract_video_frames(
+    video_path: Path,
+    work_dir: Path,
+    *,
+    fps: float,
+    max_side: int,
+    duration_s: float,
+    stack_frames: int = 1,
+) -> tuple[list[str], list[str | None]]:
+    """Demux JPEG frames only. Frame count follows ``duration_s``, not soundtrack.
+
+    Returns the base frames (one per model unit) and the parallel stacked track.
+    With ``stack_frames=N`` each unit also samples its ``N-1`` interior
+    sub-frames and tiles them into one composite, which is how official duplex
+    raises the visual refresh rate while keeping one second of audio per unit.
+    A unit whose interior falls past the end of the clip stacks nothing.
+    """
+    num_frames, avg_fps = _probe_video_frames_and_fps(video_path)
+    sample_fps = max(float(fps), 1e-6)
+    unit_s = 1.0 / sample_fps
+    timeline_s = max(float(duration_s), unit_s)
+    num_samples = max(1, int(math.ceil(timeline_s * sample_fps - 1e-9)))
+    offsets = unit_subframe_offsets(stack_frames, unit_s=unit_s)
+
+    def frame_at(seconds: float) -> int:
+        # Official get_video_frame_audio_segments uses truncating int(), not
+        # round(), so 29.97 fps lands on the same presentation index.
+        return min(int(seconds * avg_fps), num_frames - 1)
+
+    base_idx = [frame_at(unit * unit_s) for unit in range(num_samples)]
+    sub_times = [
+        [unit * unit_s + offset for offset in offsets if unit * unit_s + offset < timeline_s]
+        for unit in range(num_samples)
+    ]
+    sub_idx = [frame_at(seconds) for times in sub_times for seconds in times]
+    images = _decode_video_frames_rgb(video_path, base_idx + sub_idx)
+    sub_images = iter(images[len(base_idx) :])
+
+    frame_dir = work_dir / "frames"
+    frame_dir.mkdir(parents=True, exist_ok=True)
+    for stale in frame_dir.glob("*.jpg"):
+        stale.unlink()
+    frames_b64: list[str] = []
+    stacked_b64: list[str | None] = []
+    for index, (image, times) in enumerate(zip(images[: len(base_idx)], sub_times), start=1):
+        jpeg = _jpeg_bytes(_resize_max_side(image, max_side))
+        (frame_dir / f"frame_{index:05d}.jpg").write_bytes(jpeg)
+        frames_b64.append(base64.b64encode(jpeg).decode("ascii"))
+        interior = [_resize_max_side(next(sub_images), max_side) for _ in times]
+        if not interior:
+            stacked_b64.append(None)
+            continue
+        composite = concat_frames_b64(interior)
+        (frame_dir / f"stack_{index:05d}.jpg").write_bytes(base64.b64decode(composite))
+        stacked_b64.append(composite)
+    return frames_b64, stacked_b64
+
+
+def _extract_video_soundtrack(video_path: Path, work_dir: Path) -> Path:
+    """Write a 16 kHz mono WAV from the video soundtrack."""
+    try:
+        from vllm.multimodal.media.audio import load_audio
+    except ImportError as exc:  # pragma: no cover
+        raise SystemExit("--input-video needs vLLM audio helpers (load_audio)") from exc
+
+    audio_np, sr = load_audio(str(video_path), sr=PCM16_SAMPLE_RATE, mono=True)
+    work_dir.mkdir(parents=True, exist_ok=True)
+    audio_path = work_dir / "input_16k.wav"
+    write_pcm16_wav(audio_path, _to_pcm16_bytes(audio_np), sample_rate_hz=int(sr))
+    return audio_path
+
+
+def _extract_video_input(
+    video_path: Path,
+    work_dir: Path,
+    *,
+    fps: float,
+    max_side: int,
+    stack_frames: int,
+) -> tuple[Path, list[str], list[str | None]]:
+    """Demux a video into duplex inputs: 16 kHz mono WAV plus JPEG frames.
+
+    Use this only when the video soundtrack is the audio source. When the
+    caller already has ``--input-wav``, extract frames against that WAV
+    duration instead so a silent clip cannot fail ``load_audio``.
+    """
+    audio_path = _extract_video_soundtrack(video_path, work_dir)
+    frames_b64, stacked_b64 = _extract_video_frames(
+        video_path,
+        work_dir,
+        fps=fps,
+        max_side=max_side,
+        duration_s=_pcm16_wav_duration_s(audio_path),
+        stack_frames=stack_frames,
+    )
+    return audio_path, frames_b64, stacked_b64
+
+
+def _resolve_duplex_av_inputs(
+    *,
+    input_wav: str | None,
+    input_video: str | None,
+    work_dir: Path,
+    fps: float,
+    max_side: int,
+    stack_frames: int = 1,
+) -> tuple[str, list[str], list[str | None]]:
+    """Return ``(wav_path, frames_b64, stacked_b64)``. External WAV wins over video audio."""
+    if input_video:
+        video_path = Path(input_video)
+        if input_wav:
+            frames, stacked = _extract_video_frames(
+                video_path,
+                work_dir,
+                fps=fps,
+                max_side=max_side,
+                duration_s=_pcm16_wav_duration_s(Path(input_wav)),
+                stack_frames=stack_frames,
+            )
+            return input_wav, frames, stacked
+        extracted_wav, frames, stacked = _extract_video_input(
+            video_path,
+            work_dir,
+            fps=fps,
+            max_side=max_side,
+            stack_frames=stack_frames,
+        )
+        return str(extracted_wav), frames, stacked
+    if not input_wav:
+        raise SystemExit("provide --input-wav, --input-video, or both")
+    return input_wav, [], []
 
 
 async def run_demo(args: argparse.Namespace) -> dict[str, object]:
-    input_pcm16 = read_pcm16_wav(Path(args.input_wav))
-    if not input_pcm16:
-        raise ValueError("input WAV has no audio")
-
     output_dir = Path(args.output_dir)
     stream_writer = _StreamingOutputWriter(output_dir)
 
+    input_wav, video_frames, stacked_video_frames = _resolve_duplex_av_inputs(
+        input_wav=args.input_wav,
+        input_video=args.input_video,
+        work_dir=output_dir / "video_input",
+        fps=args.video_fps,
+        max_side=args.frame_max_side,
+        stack_frames=args.stack_frames,
+    )
+
+    input_pcm16 = read_pcm16_wav(Path(input_wav))
+    if not input_pcm16:
+        raise ValueError("input WAV has no audio")
+
     url = build_realtime_url(
         args.url,
         args.model,
@@ -200,10 +451,12 @@ async def run_demo(args: argparse.Namespace) -> dict[str, object]:
             timeout_s=args.timeout_s,
         )
         stream_event_cursor = len(client.events.events)
-        await client.stream_pcm16(
+        frames_sent = await client.stream_pcm16(
             input_pcm16,
             chunk_ms=args.chunk_ms,
             realtime=not args.no_realtime_pacing,
+            video_frames=video_frames,
+            stacked_video_frames=stacked_video_frames,
         )
         commit_event_cursor = len(client.events.events)
         stream_decision = _latest_model_decision(client.events.events, stream_event_cursor)
@@ -212,8 +465,7 @@ async def run_demo(args: argparse.Namespace) -> dict[str, object]:
             chunk_period_ms=_chunk_period_ms(client.events.events),
         )
         wait_for_post_commit_decision = False
-        commit_sent_at_s = time.monotonic()
-        await client.commit()
+        commit_sent_at_s = await _commit_input_after_playback_checkpoint(client)
         wait_error: str | None = None
         committed_index: int | None = None
         post_commit_decision: str | None = None
@@ -326,6 +578,10 @@ async def run_demo(args: argparse.Namespace) -> dict[str, object]:
                     committed_index,
                 ),
             },
+            "input_video": args.input_video,
+            "video_frames_extracted": len(video_frames),
+            "video_frames_sent": frames_sent,
+            "video_stacked_frames_extracted": sum(frame is not None for frame in stacked_video_frames),
             "audio_bytes": len(audio),
             "audio_chunk_count": len(stream_writer.audio_chunk_paths),
             "audio_chunk_files": [str(path) for path in stream_writer.audio_chunk_paths],
@@ -372,7 +628,48 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--url", default="ws://localhost:8099/v1/realtime?duplex=1")
     parser.add_argument("--model", default="openbmb/MiniCPM-o-4_5")
     parser.add_argument("--session-id")
-    parser.add_argument("--input-wav", required=True)
+    parser.add_argument(
+        "--input-wav",
+        help="Mono 16 kHz PCM16 clip to stream. Optional when --input-video carries the audio track.",
+    )
+    parser.add_argument(
+        "--input-video",
+        help=(
+            "Video to stream as omni duplex input. PyAV demuxes frames and "
+            "vLLM load_audio extracts a 16 kHz mono WAV (unless --input-wav overrides the audio)."
+        ),
+    )
+    parser.add_argument(
+        "--video-fps",
+        type=float,
+        default=1.0,
+        help="Frame extraction rate. The wire contract carries ~1 frame per second of audio.",
+    )
+    parser.add_argument(
+        "--frame-max-side",
+        type=int,
+        default=0,
+        help=(
+            "Optional client-side downscale of the longest side, in pixels. "
+            "0 (default) keeps the capture resolution so the server "
+            "process_image can normalize at scale_resolution=448 from a "
+            "higher-quality source. The web demo never resizes on the client."
+        ),
+    )
+    parser.add_argument(
+        "--stack-frames",
+        type=int,
+        default=1,
+        help=(
+            "Frames sampled per 1 s audio unit. 1 (default) sends the unit's "
+            "frame alone. N > 1 also samples the N-1 sub-frames inside the unit "
+            "and tiles them into one composite sent next to the base frame, so "
+            "motion (arrows, doors, digits changing) is visible at N fps while "
+            "the audio stays 1 s per unit. Official uses 5 for high refresh "
+            "rate mode; the wire carries 2 images per unit at any N because the "
+            "sub-frames share one composite."
+        ),
+    )
     parser.add_argument(
         "--ref-audio",
         required=True,
@@ -388,7 +685,7 @@ def parse_args() -> argparse.Namespace:
         "--temperature",
         type=float,
         default=None,
-        help="Stage0 sampling temperature; response-required soft-interrupt uses 0.0.",
+        help="Stage 0 sampling temperature; omit to preserve the model default.",
     )
     parser.add_argument("--no-realtime-pacing", action="store_true")
     parser.add_argument("--require-audio", action="store_true")

examples/online_serving/openai_chat_completion_client_for_multimodal_generation.py

@@ -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}

examples/online_serving/personaplex/README.md

@@ -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

examples/online_serving/pi0/README.md

@@ -0,0 +1,104 @@
+# π0 (Pi-Zero) VLA — OpenPI realtime serving
+
+[π0](https://www.physicalintelligence.company/blog/pi0) is a Vision-Language-Action
+model from Physical Intelligence: multi-camera images + a language instruction +
+robot proprioceptive state → a continuous action chunk via flow-matching denoising
+(it does **not** emit text tokens). This example serves π0 over the OpenPI realtime
+websocket protocol at `/v1/realtime/robot/openpi`.
+
+## Install extras
+
+The core `pip install -e .` does not include the OpenPI client used here:
+
+- `openpi-client` (from the [openpi](https://github.com/Physical-Intelligence/openpi)
+  repo: `pip install -e packages/openpi-client`), `websockets`, `msgpack`, `msgpack-numpy`
+
+## Weights
+
+π0 uses the LeRobot `lerobot/pi0_base` checkpoint (HF, ~13 GB). Either let the server
+download it (`MODEL=lerobot/pi0_base`) or point at a local copy
+(`MODEL=/path/to/pi0_base`).
+
+## Run the server
+
+```bash
+vllm serve lerobot/pi0_base --omni --port 8000 \
+    --served-model-name pi0 \
+    --deploy-config vllm_omni/deploy/pi0.yaml \
+    --enforce-eager --disable-log-stats
+```
+
+The deploy config (`vllm_omni/deploy/pi0.yaml`) declares a single diffusion stage
+(`Pi0Pipeline`), float32, `max_num_seqs: 1`, and the `policy_server_config` handshake
+metadata (3 cameras, `joint_position`, action horizon 50, action dim 32).
+
+### Commonly adjusted `model_config` keys
+
+These live under `stages[0].model_config` in `vllm_omni/deploy/pi0.yaml`:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `chunk_size` | `50` | Action-chunk length (timesteps) the model predicts per inference. |
+| `num_inference_steps` | `10` | Flow-matching Euler denoising steps. |
+| `max_action_dim` | `32` | Action dimensionality (state/action are padded to this). |
+| `max_state_dim` | `32` | Proprioceptive-state dimensionality (zero-padded to this). |
+| `image_resolution` | `[224, 224]` | Per-camera input size (square; SigLIP). |
+| `tokenizer_max_length` | `48` | Max PaliGemma prompt tokens. |
+| `max_cameras` | `3` | Camera slots the model attends to (real + `-1`-padded). |
+| `image_feature_keys` | 3 `observation.images.*` keys | Camera order the model attends to. |
+| `image_key_map` | `{}` | Map raw obs camera keys → `image_feature_keys` (empty = verbatim). |
+
+The `policy_server_config` block below them is the OpenPI handshake metadata
+advertised to the client; keep its `action_horizon` / `action_dim` /
+`image_resolution` in sync with the `model_config` values above. The e2e test
+`tests/e2e/online_serving/test_pi0_expansion.py::test_pi0_openpi_online` connects to a
+live server and asserts the advertised metadata matches these `pi0.yaml` values.
+
+## Run the client
+
+```bash
+python examples/online_serving/pi0/openpi_client.py --host 127.0.0.1 --port 8000 \
+    --prompt "pick up the red block and place it in the bin"
+```
+
+It connects, prints the server metadata, sends robot observations, and prints the
+returned `[action_horizon, action_dim] = [50, 32]` action chunks. Replace the blank
+cameras / zero state in `_make_dummy_obs` with real frames (HWC uint8) and
+proprioceptive state to drive a robot.
+
+### Observation format
+
+The client sends a flat dict per inference:
+
+```python
+{
+    "observation.images.base_0_rgb":       np.uint8[H, W, 3],
+    "observation.images.left_wrist_0_rgb": np.uint8[H, W, 3],
+    "observation.images.right_wrist_0_rgb":np.uint8[H, W, 3],
+    "state":   np.float32[state_dim],   # zero-padded to max_state_dim=32 server-side
+    "prompt":  "pick up the red block",
+    "session_id": "<uuid>",             # accepted but ignored (π0 is stateless)
+}
+```
+
+Camera keys must match the server's `image_feature_keys` (the checkpoint's
+`input_features` order). If your robot uses different camera names, set
+`model_config.image_key_map` in `pi0.yaml` to map raw obs keys → feature keys.
+
+## Correctness
+
+π0's flow-matching kernel is bit-for-bit matched to the LeRobot `PI0Policy` reference
+(`max|Δ| = 7.15e-07`, CPU/float32, fixed noise; see
+`tests/diffusion/models/pi0/test_pi0_parity.py::test_pi0_vllm_omni_vs_lerobot`) and is
+version-stable across transformers releases (the version-stability checks in
+`tests/diffusion/models/pi0/test_pi0_units.py`). An OpenPI websocket online-serving e2e
+lives in `tests/e2e/online_serving/test_pi0_expansion.py::test_pi0_openpi_online`.
+
+## Limitations
+
+- **Normalization stats**: `lerobot/pi0_base` uses identity normalization, which is
+  fully supported (state passes through, actions are returned in the model's space).
+  Per-dataset `norm_stats` declared in a checkpoint's `config.json` are honored, but
+  stats stored only in LeRobot's `policy_preprocessor.json` companion safetensors are
+  not yet loaded — a fine-tuned checkpoint that relies on those would need that bridge
+  added before its actions are in real-world units.

examples/online_serving/pi0/openpi_client.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+"""Minimal OpenPI client for the π0 (Pi-Zero) VLA policy server.
+
+Connects to a running π0 server (see README.md), sends a single robot
+observation (3 cameras + state + language instruction), and prints the returned
+continuous action chunk ``[action_horizon, action_dim]``.
+
+The server speaks the OpenPI websocket protocol:
+    connect -> server sends msgpack(policy_server_config metadata)
+    infer   -> client sends msgpack(obs), server replies msgpack(actions ndarray)
+
+Usage:
+    python openpi_client.py --host 127.0.0.1 --port 8000 \
+        --prompt "pick up the red block"
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+import uuid
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+try:
+    # Avoid shadowing the installed ``openpi_client`` package with this dir.
+    example_dir = str(Path(__file__).resolve().parent)
+    removed = sys.path and sys.path[0] == example_dir
+    if removed:
+        sys.path.pop(0)
+    try:
+        from openpi_client.websocket_client_policy import WebsocketClientPolicy
+    finally:
+        if removed:
+            sys.path.insert(0, example_dir)
+except ImportError as exc:  # pragma: no cover - runtime dependency guard
+    raise ImportError("π0 OpenPI example requires `openpi-client`.") from exc
+
+logger = logging.getLogger("pi0_openpi_client")
+
+DEFAULT_HOST = "127.0.0.1"
+DEFAULT_PORT = 8000
+DEFAULT_PATH = "/v1/realtime/robot/openpi"
+DEFAULT_PROMPT = "pick up the red block and place it in the bin"
+
+# π0 / pi0_base camera identities (must match the server's image_feature_keys).
+CAMERA_KEYS = (
+    "observation.images.base_0_rgb",
+    "observation.images.left_wrist_0_rgb",
+    "observation.images.right_wrist_0_rgb",
+)
+STATE_DIM = 32
+
+
+def _make_dummy_obs(prompt: str, session_id: str, image_size: int = 224) -> dict[str, Any]:
+    """Build a single π0 observation with blank cameras + zero state.
+
+    Replace the zeros with real camera frames (HWC uint8) and proprioceptive
+    state to drive an actual robot.
+    """
+    obs: dict[str, Any] = {cam: np.zeros((image_size, image_size, 3), dtype=np.uint8) for cam in CAMERA_KEYS}
+    obs["state"] = np.zeros(STATE_DIM, dtype=np.float32)
+    obs["prompt"] = prompt
+    obs["session_id"] = session_id
+    return obs
+
+
+def _ws_uri(host: str, port: int, path: str) -> str:
+    """Build the full websocket URI. WebsocketClientPolicy takes the whole URI as
+    ``host`` (it has no separate path arg)."""
+    if host.startswith(("ws://", "wss://")):
+        return host
+    return f"ws://{host}:{port}{path}"
+
+
+def _as_action_array(response: Any) -> np.ndarray:
+    if isinstance(response, dict) and response.get("type") == "error":
+        raise RuntimeError(f"Inference failed: {response.get('message', response)}")
+    return np.asarray(response, dtype=np.float32)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="π0 OpenPI client")
+    parser.add_argument("--host", default=DEFAULT_HOST)
+    parser.add_argument("--port", type=int, default=DEFAULT_PORT)
+    parser.add_argument("--path", default=DEFAULT_PATH)
+    parser.add_argument("--prompt", default=DEFAULT_PROMPT)
+    parser.add_argument("--num-steps", type=int, default=2, help="Inference observations to send.")
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+
+    policy = WebsocketClientPolicy(host=_ws_uri(args.host, args.port, args.path))
+    metadata = dict(policy.get_server_metadata())
+    logger.info("Server metadata: %s", metadata)
+
+    session_id = str(uuid.uuid4())
+    for step in range(args.num_steps):
+        obs = _make_dummy_obs(args.prompt, session_id)
+        actions = _as_action_array(policy.infer(obs))
+        logger.info(
+            "[step %d] actions shape=%s mean=%.4f std=%.4f",
+            step,
+            actions.shape,
+            float(actions.mean()),
+            float(actions.std()),
+        )
+        if not np.isfinite(actions).all():
+            raise RuntimeError("Server returned non-finite actions.")
+    logger.info("Done — π0 OpenPI round-trip OK.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

examples/online_serving/qwen2_5_omni/run_curl_multimodal_generation.sh

@@ -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"

examples/online_serving/qwen3_omni/README.md

@@ -24,6 +24,18 @@ vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091 \
     --deploy-config /path/to/your_deploy_config.yaml
 ```
 
+To serve **thinker-only** (text output, no talker / code2wav loaded) with Instruct
+weights, pass the bundled thinker-only deploy YAML. The `pipeline:` key
+`qwen3_omni_moe_thinker_only` overrides the HF `enable_audio_output` resolver:
+
+```bash
+vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091 \
+    --deploy-config vllm_omni/deploy/qwen3_omni_moe_thinking.yaml
+```
+
+Captioner / Thinking checkpoints (`enable_audio_output=false`) still auto-select
+the same single-stage pipeline without `--deploy-config`.
+
 For a 3x-GPU multi-replica layout (talker/code2wav scale-out on cuda:1,2),
 use `--stage-overrides` on top of the default config:
 
@@ -513,7 +525,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
 ```

examples/online_serving/qwen3_omni/run_curl_multimodal_generation.sh

@@ -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"

examples/online_serving/replica_data_parallel/bench_replica_dp.py

@@ -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

examples/online_serving/stable_audio/README.md

@@ -1,234 +0,0 @@
-# Stable Audio Online Serving
-
-Generate audio from text prompts using Stable Audio models via an OpenAI-compatible API endpoint.
-
-## Features
-
-- **OpenAI-compatible API**: Use `/v1/audio/generate` endpoint
-- **Flexible control**: Adjust audio length, guidance scale, inference steps
-- **Quality control**: Use negative prompts to avoid unwanted characteristics
-- **Reproducible**: Set random seed for deterministic generation
-
-## Quick Start
-
-### 1. Start the Server
-
-```bash
-vllm serve stabilityai/stable-audio-open-1.0 \
-    --host 0.0.0.0 \
-    --port 8091 \
-    --gpu-memory-utilization 0.9 \
-    --trust-remote-code \
-    --enforce-eager \
-    --omni
-```
-
-### 2. Generate Audio
-
-#### Using curl
-
-```bash
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "The sound of a cat purring",
-        "audio_length": 10.0
-    }' --output cat.wav
-```
-
-#### Using Python Client
-
-```bash
-python stable_audio_client.py \
-    --text "The sound of a cat purring" \
-    --audio_length 10.0 \
-    --output cat.wav
-```
-
-#### Using Bash Script
-
-```bash
-bash curl_examples.sh
-```
-
-## API Reference
-
-### Endpoint
-
-```
-POST /v1/audio/generate
-```
-
-### Request Body
-
-```json
-{
-    "input": "Text description of the audio",
-    "audio_length": 10.0,
-    "audio_start": 0.0,
-    "negative_prompt": "Low quality",
-    "guidance_scale": 7.0,
-    "num_inference_steps": 100,
-    "seed": 42,
-    "response_format": "wav"
-}
-```
-
-### Parameters
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `input` | string | **required** | Text prompt describing the audio to generate |
-| `audio_length` | float | ~47s | Audio duration in seconds (max ~47s for stable-audio-open-1.0) |
-| `audio_start` | float | 0.0 | Audio start time in seconds |
-| `negative_prompt` | string | null | Text describing what to avoid in generation |
-| `guidance_scale` | float | 7.0 | Classifier-free guidance scale (higher = more adherence to prompt) |
-| `num_inference_steps` | int | 50 | Number of denoising steps (higher = better quality, slower) |
-| `seed` | int | null | Random seed for reproducibility |
-| `response_format` | string | "wav" | Output format: wav, mp3, flac, pcm |
-
-### Response
-
-Returns audio data in the requested format (default: WAV).
-
-## Usage Examples
-
-### Basic Generation
-
-```bash
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "The sound of ocean waves"
-    }' --output ocean.wav
-```
-
-### Custom Duration
-
-```bash
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "A dog barking",
-        "audio_length": 5.0
-    }' --output dog_5s.wav
-```
-
-### High Quality with Negative Prompt
-
-```bash
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "A piano playing a gentle melody",
-        "audio_length": 10.0,
-        "negative_prompt": "Low quality, distorted, noisy",
-        "guidance_scale": 8.0,
-        "num_inference_steps": 150
-    }' --output piano_hq.wav
-```
-
-### Reproducible Generation
-
-```bash
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "Thunder and rain sounds",
-        "audio_length": 15.0,
-        "seed": 42
-    }' --output thunder.wav
-```
-
-### Quick Generation (Fewer Steps)
-
-For faster generation with slightly lower quality:
-
-```bash
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "Birds chirping in a forest",
-        "audio_length": 8.0,
-        "num_inference_steps": 50
-    }' --output birds_quick.wav
-```
-
-## Python Client Examples
-
-### Simple Generation
-
-```bash
-python stable_audio_client.py \
-    --text "The sound of a cat purring"
-```
-
-### Custom Parameters
-
-```bash
-python stable_audio_client.py \
-    --text "Thunder and rain" \
-    --audio_length 15.0 \
-    --negative_prompt "Low quality" \
-    --guidance_scale 7.0 \
-    --num_inference_steps 100 \
-    --seed 42 \
-    --output thunder.wav
-```
-
-### Different Output Format
-
-```bash
-python stable_audio_client.py \
-    --text "Guitar playing" \
-    --response_format mp3 \
-    --output guitar.mp3
-```
-
-## Tips
-
-1. **Audio Length**: Keep under 47 seconds for `stable-audio-open-1.0`
-2. **Quality vs Speed**:
-   - 50 steps: Fast, decent quality
-   - 100 steps: Good balance (default)
-   - 150+ steps: High quality, slower
-3. **Guidance Scale**:
-   - Lower (3-5): More creative/varied
-   - Default (7): Good balance
-   - Higher (10+): More literal to prompt
-4. **Negative Prompts**: Use to avoid "Low quality", "distorted", "noisy", etc.
-5. **Seeds**: Use same seed for reproducible results
-
-## Performance
-
-| Inference Steps | Quality | Speed | Use Case |
-|----------------|---------|-------|----------|
-| 50 | Good | Fast | Quick previews |
-| 100 (default) | Very Good | Medium | Production |
-| 150+ | Excellent | Slow | Final/critical audio |
-
-## Troubleshooting
-
-### Server not responding
-- Check if server is running: `curl http://localhost:8091/health`
-- Check server logs for errors
-
-### Audio quality issues
-- Increase `num_inference_steps` (e.g., 150)
-- Add negative prompts: `"Low quality, distorted, noisy"`
-- Increase `guidance_scale` for more prompt adherence
-
-### Generation timeout
-- Reduce `num_inference_steps`
-- Reduce `audio_length`
-- Check GPU memory with `nvidia-smi`
-
-### Wrong audio length
-- Ensure `audio_length` is within model limits (~47s max)
-- Adjust `audio_start` if trimming is needed
-
-## See Also
-
-- [Offline Inference Example](../../offline_inference/text_to_audio/README.md)
-- [Stable Audio Model Card](https://huggingface.co/stabilityai/stable-audio-open-1.0)
-- [vLLM-Omni Documentation](https://github.com/vllm-project/vllm-omni)

examples/online_serving/stable_audio/curl_examples.sh

@@ -1,54 +0,0 @@
-#!/bin/bash
-# Examples for using Stable Audio with curl via /v1/audio/generate endpoint
-
-# Example 1: Simple request with default parameters
-echo "Example 1: Simple request with default parameters"
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "The sound audience clapping and cheering in a stadium"
-    }' --output stadium.wav
-
-# Example 2: Request with custom audio_length
-echo "Example 2: Custom audio length (5 seconds)"
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "The sound of a dog barking",
-        "audio_length": 5.0
-    }' --output dog_5s.wav
-
-# Example 3: Request with negative prompt for quality control
-echo "Example 3: With negative prompt"
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "A piano playing a gentle melody",
-        "audio_length": 10.0,
-        "negative_prompt": "Low quality, distorted, noisy"
-    }' --output piano.wav
-
-# Example 4: Full control with all parameters
-echo "Example 4: Full control (custom length, guidance, steps, seed)"
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "Thunder and rain sounds",
-        "audio_length": 15.0,
-        "negative_prompt": "Low quality",
-        "guidance_scale": 7.0,
-        "num_inference_steps": 100,
-        "seed": 42
-    }' --output thunder_rain.wav
-
-# Example 5: Quick generation with fewer steps (faster but lower quality)
-echo "Example 5: Quick generation (fewer steps)"
-curl -X POST http://localhost:8091/v1/audio/generate \
-    -H "Content-Type: application/json" \
-    -d '{
-        "input": "Ocean waves crashing on a beach",
-        "audio_length": 8.0,
-        "num_inference_steps": 50
-    }' --output ocean.wav
-
-echo "All examples completed!"

examples/online_serving/stable_audio/stable_audio_client.py

@@ -1,170 +0,0 @@
-#!/usr/bin/env python3
-"""
-OpenAI-compatible client for Stable Audio via /v1/audio/generate endpoint.
-
-This script demonstrates how to use the OpenAI-compatible speech API
-to generate audio from text using Stable Audio models.
-
-Examples:
-    # Simple generation
-    python stable_audio_client.py --text "The sound of a cat purring"
-
-    # With custom duration
-    python stable_audio_client.py --text "A dog barking" --audio_length 5.0
-
-    # With all parameters
-    python stable_audio_client.py --text "Thunder and rain" \
-        --audio_length 15.0 \
-        --negative_prompt "Low quality" \
-        --guidance_scale 7.0 \
-        --num_inference_steps 100 \
-        --seed 42 \
-        --output thunder.wav
-"""
-
-import argparse
-import sys
-
-import requests
-
-
-def parse_args():
-    parser = argparse.ArgumentParser(description="Generate audio with Stable Audio via OpenAI-compatible API")
-    parser.add_argument(
-        "--api_url",
-        default="http://localhost:8091/v1/audio/generate",
-        help="API endpoint URL",
-    )
-    parser.add_argument(
-        "--text",
-        default="The sound of a cat purring",
-        help="Text prompt for audio generation",
-    )
-    parser.add_argument(
-        "--audio_length",
-        type=float,
-        default=10.0,
-        help="Audio length in seconds (max ~47s for stable-audio-open-1.0)",
-    )
-    parser.add_argument(
-        "--audio_start",
-        type=float,
-        default=0.0,
-        help="Audio start time in seconds",
-    )
-    parser.add_argument(
-        "--negative_prompt",
-        default="Low quality",
-        help="Negative prompt for classifier-free guidance",
-    )
-    parser.add_argument(
-        "--guidance_scale",
-        type=float,
-        default=7.0,
-        help="Guidance scale for diffusion (higher = more adherence to prompt)",
-    )
-    parser.add_argument(
-        "--num_inference_steps",
-        type=int,
-        default=100,
-        help="Number of inference steps (higher = better quality, slower)",
-    )
-    parser.add_argument(
-        "--seed",
-        type=int,
-        default=None,
-        help="Random seed for reproducibility",
-    )
-    parser.add_argument(
-        "--output",
-        default="stable_audio_output.wav",
-        help="Output file path",
-    )
-    parser.add_argument(
-        "--response_format",
-        default="wav",
-        choices=["wav", "mp3", "flac", "pcm"],
-        help="Audio output format",
-    )
-    return parser.parse_args()
-
-
-def generate_audio(args):
-    """Generate audio using the API."""
-
-    # Build request payload
-    payload = {
-        "input": args.text,
-        "audio_length": args.audio_length,
-        "audio_start": args.audio_start,
-        "response_format": args.response_format,
-    }
-
-    # Add optional parameters
-    if args.negative_prompt:
-        payload["negative_prompt"] = args.negative_prompt
-    if args.guidance_scale:
-        payload["guidance_scale"] = args.guidance_scale
-    if args.num_inference_steps:
-        payload["num_inference_steps"] = args.num_inference_steps
-    if args.seed is not None:
-        payload["seed"] = args.seed
-
-    print(f"\n{'=' * 60}")
-    print("Stable Audio - Text-to-Audio Generation")
-    print(f"{'=' * 60}")
-    print(f"API URL: {args.api_url}")
-    print(f"Prompt: {args.text}")
-    print(f"Audio length: {args.audio_length}s")
-    print(f"Negative prompt: {args.negative_prompt}")
-    print(f"Guidance scale: {args.guidance_scale}")
-    print(f"Inference steps: {args.num_inference_steps}")
-    if args.seed is not None:
-        print(f"Seed: {args.seed}")
-    print(f"Output: {args.output}")
-    print(f"{'=' * 60}\n")
-
-    try:
-        # Make the API request
-        print("Generating audio...")
-        response = requests.post(
-            args.api_url,
-            json=payload,
-            headers={"Content-Type": "application/json"},
-            timeout=300,  # 5 minute timeout for long generations
-        )
-
-        # Check for errors
-        if response.status_code != 200:
-            print(f"Error: API returned status code {response.status_code}")
-            print(f"Response: {response.text}")
-            return False
-
-        # Save the audio
-        with open(args.output, "wb") as f:
-            f.write(response.content)
-
-        print(f"✓ Audio saved to {args.output}")
-        print(f"  File size: {len(response.content) / 1024:.1f} KB")
-        return True
-
-    except requests.exceptions.Timeout:
-        print("Error: Request timed out. Try reducing inference steps or audio length.")
-        return False
-    except requests.exceptions.ConnectionError:
-        print(f"Error: Could not connect to {args.api_url}")
-        print("Make sure the server is running.")
-        return False
-    except Exception as e:
-        print(f"Error: {e}")
-        return False
-
-
-def main():
-    args = parse_args()
-    success = generate_audio(args)
-    sys.exit(0 if success else 1)
-
-
-if __name__ == "__main__":
-    main()

examples/online_serving/step_audio2/README.md

@@ -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

examples/online_serving/text_to_speech/README.md

@@ -25,7 +25,6 @@ For the full list of supported architectures across all modalities, see
 | Qwen3-TTS | `Qwen/Qwen3-TTS-12Hz-1.7B-{CustomVoice,VoiceDesign,Base}` | ✓ (Base) | ✓ (PCM + WebSocket) | ✓ (presets + `/v1/audio/voices` upload) | ✓ (standard + FastRTC) |
 | VoxCPM2 | `openbmb/VoxCPM2` | ✓ | ✓ (AudioWorklet via gradio) | — | ✓ |
 | Voxtral TTS | `mistralai/Voxtral-4B-TTS-2603` | ✓ (gated upstream) | ✓ | ✓ (presets) | ✓ |
-| SoulX-Singer | `Soul-AILab/SoulX-Singer` | ✓ (prompt audio) | — (batch only) | — (prompt + target audio) | — (chat client) |
 
 CosyVoice3 is intentionally absent: no online example exists for it yet. See its [offline section](../../offline_inference/text_to_speech/README.md#cosyvoice3) instead.
 
@@ -570,7 +569,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`:
@@ -715,65 +714,3 @@ The demo handles voice-preset selection and reference-audio upload. `voxtral_tts
 - Voice presets are listed on the HF model card (`mistralai/Voxtral-4B-TTS-2603`).
 - Voice cloning is gated upstream and may require a recent `mistral_common`.
 - A standalone CLI client is not yet shipped; the gradio demo is the canonical reference for now.
-
----
-
-## SoulX-Singer
-
-Singing voice synthesis (SVS) and conversion (SVC) at 24 kHz. Single-stage DiT with inline preprocess. Uses the `/v1/chat/completions` endpoint with multimodal input (`prompt_audio` + `target_audio`).
-
-### Prerequisites
-
-Download DiT and preprocess weights, then set up separate SVS / SVC view directories and install dependencies as described in the [offline README](../../offline_inference/text_to_speech/README.md#soulx-singer). `config.json` `architectures` field is the single source of truth for SVS vs SVC — point `MODEL` at the matching directory.
-
-### Launch
-
-```bash
-# SVS (default)
-export MODEL=/path/to/SoulX-Singer
-export PREPROCESS=/path/to/SoulX-Singer-Preprocess
-bash examples/online_serving/text_to_speech/soulxsinger/run_server.sh
-
-# SVC
-export MODE=svc
-export MODEL=/path/to/SoulX-Singer-svc
-bash examples/online_serving/text_to_speech/soulxsinger/run_server.sh
-```
-
-Or equivalently, set `SOULX_PREPROCESS_WEIGHTS_DIR` and launch directly:
-```bash
-export SOULX_PREPROCESS_WEIGHTS_DIR=$PREPROCESS
-vllm serve $MODEL --omni \
-    --deploy-config vllm_omni/deploy/soulxsinger_${MODE}.yaml \
-    --port 8192 --trust-remote-code --enforce-eager
-```
-
-### Sending requests
-
-Audio paths must be reachable from the server host (local filesystem or data URL). The client sends prompt vocal via `input_audio` and target accompaniment via `extra_args['target_audio']`.
-
-```bash
-# Default demo audio: tests/assets/soulxsinger/zh_prompt.mp3 + music.mp3
-python examples/online_serving/text_to_speech/soulxsinger/openai_chat_client.py \
-    --prompt-audio /path/on/server/zh_prompt.mp3 \
-    --target-audio /path/on/server/music.mp3 \
-    --preprocess-weights-dir /path/on/server/SoulX-Singer-Preprocess \
-    -o output.wav
-```
-
-Use precomputed metadata to skip online preprocess with following command:
-```bash
-python examples/online_serving/text_to_speech/soulxsinger/openai_chat_client.py \
-    --prompt-metadata-path /path/on/server/zh_prompt.json \
-    --target-metadata-path /path/on/server/music.json \
-    --audio-path /path/on/server/zh_prompt.mp3 \
-    -o output.wav
-```
-
-`SOULX_PREPROCESS_WEIGHTS_DIR` makes `--preprocess-weights-dir` optional. See `openai_chat_client.py --help` for `--vocal-sep`, `--language`, `--num-inference-steps`, `--guidance-scale`, and `--seed`.
-
-### Notes
-
-- Output: 24 kHz mono WAV; batch only.
-- Defaults match upstream: `--guidance-scale 3.0`, `--seed 42`, `--auto-shift` on.
-- SVS `--control`: `score` or `melody`. MIDI / lyric QC: upstream `midi_editor` only.

examples/online_serving/text_to_speech/soulxsinger/openai_chat_client.py

@@ -1,186 +0,0 @@
-#!/usr/bin/env python3
-"""SoulX-Singer OpenAI-compatible chat client (SVS / SVC).
-
-Sends prompt audio via ``input_audio`` and target accompaniment via
-``extra_args['target_audio']`` (server-local path). For integrated preprocess,
-also pass ``preprocess_weights_dir`` in ``extra_args``.
-
-Usage:
-  python openai_chat_client.py \\
-      --prompt-audio /path/on/server/zh_prompt.mp3 \\
-      --target-audio /path/on/server/music.mp3 \\
-      --preprocess-weights-dir /path/on/server/SoulX-Singer-Preprocess \\
-      -o output.wav
-"""
-
-from __future__ import annotations
-
-import argparse
-import base64
-import io
-import sys
-from pathlib import Path
-
-import requests
-import soundfile
-import torch
-
-
-def _audio_to_data_url(path: Path) -> str:
-    with path.open("rb") as handle:
-        data = base64.b64encode(handle.read()).decode("ascii")
-    return f"data:audio/mpeg;base64,{data}"
-
-
-def _save_wav(audio: torch.Tensor, path: Path, sample_rate: int) -> None:
-    audio = audio.to(torch.float32)
-    peak = audio.abs().max().clamp(min=1e-8)
-    audio = audio / peak
-    path.parent.mkdir(parents=True, exist_ok=True)
-    soundfile.write(str(path), audio.clamp(-1.0, 1.0).cpu().T.numpy(), sample_rate, subtype="PCM_16")
-
-
-def _decode_audio_from_response(body: dict) -> tuple[torch.Tensor, int]:
-    for choice in body.get("choices", []):
-        audio_obj = choice.get("message", {}).get("audio")
-        if isinstance(audio_obj, dict) and audio_obj.get("data"):
-            data, sr = soundfile.read(
-                io.BytesIO(base64.b64decode(audio_obj["data"])),
-                dtype="float32",
-                always_2d=True,
-            )
-            return torch.from_numpy(data).transpose(0, 1), sr
-    brief = {k: v for k, v in body.items() if k != "choices"}
-    raise RuntimeError(f"no audio in response message.audio: {brief}")
-
-
-def main() -> int:
-    repo_root = Path(__file__).resolve().parents[4]
-    default_assets = repo_root / "tests" / "assets" / "soulxsinger"
-
-    parser = argparse.ArgumentParser(description="SoulX-Singer online chat client")
-    parser.add_argument("--port", type=int, default=8192)
-    parser.add_argument("--model", default="Soul-AILab/SoulX-Singer")
-    parser.add_argument(
-        "--prompt-audio",
-        default=str(default_assets / "zh_prompt.mp3"),
-        help="Prompt vocal audio (path on server if using extra_args, or local for input_audio)",
-    )
-    parser.add_argument(
-        "--target-audio",
-        default=str(default_assets / "music.mp3"),
-        help="Target accompaniment path on the server (extra_args['target_audio'])",
-    )
-    parser.add_argument(
-        "--prompt-metadata-path",
-        default=None,
-        help="SVS precomputed prompt metadata.json",
-    )
-    parser.add_argument(
-        "--target-metadata-path",
-        default=None,
-        help="SVS precomputed target metadata.json",
-    )
-    parser.add_argument(
-        "--audio-path",
-        default=None,
-        help="SVS prompt vocal wav for precomputed metadata",
-    )
-    parser.add_argument("--preprocess-weights-dir", default=None)
-    parser.add_argument("--output", "-o", default="soulxsinger_out.wav")
-    parser.add_argument("--svc", action="store_true", help="Use SVC mode knobs")
-    parser.add_argument("--language", default="Mandarin")
-    parser.add_argument("--num-inference-steps", type=int, default=32)
-    parser.add_argument("--guidance-scale", type=float, default=3.0)
-    parser.add_argument(
-        "--seed",
-        type=int,
-        default=42,
-        help="Optional CFM seed. Omit for non-deterministic sampling.",
-    )
-    parser.add_argument(
-        "--auto-shift",
-        action=argparse.BooleanOptionalAction,
-        default=True,
-        help="Auto pitch shift (default: on, original upstream infer.sh)",
-    )
-    parser.add_argument(
-        "--control",
-        default="melody",
-        choices=["melody", "score"],
-        help="SVS control mode",
-    )
-    parser.add_argument("--vocal-sep", action="store_true")
-    args = parser.parse_args()
-
-    meta_paths = (args.prompt_metadata_path, args.target_metadata_path, args.audio_path)
-    if any(meta_paths) and not all(meta_paths):
-        print(
-            "ERROR: precomputed metadata requires --prompt-metadata-path, "
-            "--target-metadata-path, and --audio-path together.",
-            file=sys.stderr,
-        )
-        return 2
-
-    extra_args: dict = {
-        "vocal_sep": args.vocal_sep,
-        "auto_shift": args.auto_shift,
-        "pitch_shift": 0,
-    }
-    if all(meta_paths):
-        extra_args.update(
-            {
-                "prompt_metadata_path": str(Path(args.prompt_metadata_path).expanduser().resolve()),
-                "target_metadata_path": str(Path(args.target_metadata_path).expanduser().resolve()),
-                "audio_path": str(Path(args.audio_path).expanduser().resolve()),
-            }
-        )
-        content = [{"type": "text", "text": "soulx-singer"}]
-    else:
-        prompt_path = Path(args.prompt_audio).expanduser().resolve()
-        if not prompt_path.is_file():
-            print(f"ERROR: prompt audio not found: {prompt_path}", file=sys.stderr)
-            return 2
-        extra_args["prompt_audio"] = str(prompt_path)
-        extra_args["target_audio"] = str(Path(args.target_audio).expanduser().resolve())
-        if args.preprocess_weights_dir:
-            extra_args["preprocess_weights_dir"] = str(Path(args.preprocess_weights_dir).expanduser().resolve())
-        content = [
-            {"type": "text", "text": "soulx-singer"},
-            {
-                "type": "input_audio",
-                "input_audio": {"data": _audio_to_data_url(prompt_path), "format": "mp3"},
-            },
-        ]
-    if not args.svc:
-        extra_args["language"] = args.language
-        extra_args["control"] = args.control
-
-    payload = {
-        "model": args.model,
-        "modalities": ["audio"],
-        "messages": [{"role": "user", "content": content}],
-        "num_inference_steps": args.num_inference_steps,
-        "guidance_scale": args.guidance_scale,
-        "extra_args": extra_args,
-    }
-    if args.seed is not None:
-        payload["seed"] = args.seed
-
-    print(f"POST http://localhost:{args.port}/v1/chat/completions")
-    response = requests.post(
-        f"http://localhost:{args.port}/v1/chat/completions",
-        headers={"Content-Type": "application/json"},
-        json=payload,
-        timeout=1800,
-    )
-    response.raise_for_status()
-    audio, sample_rate = _decode_audio_from_response(response.json())
-    _save_wav(audio, Path(args.output), sample_rate)
-    duration = audio.shape[-1] / sample_rate
-    print(f"saved {args.output}  sr={sample_rate}Hz  duration={duration:.2f}s")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

examples/online_serving/text_to_speech/soulxsinger/run_server.sh

@@ -1,39 +0,0 @@
-#!/bin/bash
-# Launch vLLM-Omni server for SoulX-Singer (single-stage DiT, preprocess inline).
-#
-# Usage:
-#   MODEL=/path/to/SoulX-Singer PREPROCESS=/path/to/Preprocess \
-#
-# Audio paths in client extra_args must be readable on the server host.
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
-
-MODEL="${MODEL:-Soul-AILab/SoulX-Singer}"
-MODE="${MODE:-svs}"
-PORT="${PORT:-8192}"
-GPUS="${GPUS:-0}"
-
-if [[ "$MODE" == "svc" ]]; then
-  DEPLOY_CONFIG="${DEPLOY_CONFIG:-$REPO_ROOT/vllm_omni/deploy/soulxsinger_svc.yaml}"
-else
-  DEPLOY_CONFIG="${DEPLOY_CONFIG:-$REPO_ROOT/vllm_omni/deploy/soulxsinger_svs.yaml}"
-fi
-
-echo "Starting SoulX-Singer server"
-echo "  MODEL=$MODEL"
-echo "  MODE=$MODE"
-echo "  PORT=$PORT"
-echo "  DEPLOY_CONFIG=$DEPLOY_CONFIG"
-echo "  CUDA_VISIBLE_DEVICES=$GPUS"
-
-CUDA_VISIBLE_DEVICES="$GPUS" \
-vllm serve "$MODEL" \
-    --omni \
-    --deploy-config "$DEPLOY_CONFIG" \
-    --host 0.0.0.0 \
-    --port "$PORT" \
-    --trust-remote-code \
-    --enforce-eager

examples/online_serving/text_to_video/README.md

@@ -11,6 +11,11 @@ This example demonstrates how to deploy text-to-video models for online video ge
 | Wan2.2 T2V | `Wan-AI/Wan2.2-T2V-A14B-Diffusers` |
 | LTX-2 | `Lightricks/LTX-2` |
 | Helios (Base / Mid / Distilled) | `BestWishYsh/Helios-Base`, `Helios-Mid`, `Helios-Distilled` |
+| SANA-Video 2B (480p) | `Efficient-Large-Model/SANA-Video_2B_480p_diffusers` |
+| SANA-Video 2B (720p) | `Efficient-Large-Model/SANA-Video_2B_720p_diffusers` |
+
+For SANA-Video 2B text-to-video online serving, see the
+[SANA-Video 2B recipe](../../../recipes/NVIDIA/SANA-Video-2B.md).
 
 ## Wan2.2 T2V
 

examples/online_serving/text_to_video/run_curl_sana_video.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+
+BASE_URL="${BASE_URL:-http://localhost:8091}"
+OUTPUT_PATH="${OUTPUT_PATH:-sana_video.mp4}"
+
+curl -sS -X POST "$BASE_URL/v1/videos/sync" \
+    -F "prompt=A cinematic tracking shot of a sailboat crossing the ocean at sunset" \
+    -F "height=480" \
+    -F "width=832" \
+    -F "num_frames=81" \
+    -F "fps=16" \
+    -F "num_inference_steps=50" \
+    -F "guidance_scale=6.0" \
+    -F "seed=42" \
+    -F 'extra_params={"motion_score":30}' \
+    --output "$OUTPUT_PATH"

examples/online_serving/text_to_video/run_server_sana_video.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+# SANA-Video-2B text-to-video serving.
+
+MODEL="${MODEL:-Efficient-Large-Model/SANA-Video_2B_480p_diffusers}"
+PORT="${PORT:-8091}"
+
+vllm serve "$MODEL" \
+    --omni \
+    --model-class-name SanaVideoPipeline \
+    --dtype bfloat16 \
+    --port "$PORT"

examples/online_serving/text_to_video/run_server_sana_video_diffusers.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# SANA-Video through the black-box Diffusers backend adapter.
+
+MODEL="${MODEL:-Efficient-Large-Model/SANA-Video_2B_480p_diffusers}"
+PORT="${PORT:-8091}"
+
+vllm serve "$MODEL" \
+    --omni \
+    --diffusion-load-format diffusers \
+    --diffusion-attention-backend TORCH_SDPA \
+    --dtype bfloat16 \
+    --port "$PORT"