docs: define module ownership contracts

Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>

.buildkite/common/ci_mirror_hardwares.yml

@@ -8,7 +8,7 @@
 # NPU naming: {queue}_{resource_class}
 #   a2b3_npu_1  — ascend-a2b3, resource_class npu-1 (A2/B3 CI image)
 #   a2b3_npu_4  — ascend-a2b3, resource_class npu-4
-#   a3_npu_2    — ascend-a3, resource_class npu-2
+#   a3_npu_2    — ascend-a3, resource_class npu-2 (A3 CI image tag …:$BUILDKITE_COMMIT-a3)
 
 x-npu-k8s-plugins: &npu_k8s_plugins
   - kubernetes:

.buildkite/cuda/test-merge.yml

@@ -139,11 +139,6 @@ steps:
         timeout_in_minutes: 50
         commands:
           - pytest -s -v tests/e2e/offline_inference/test_minicpmo_4_5.py tests/e2e/online_serving/test_minicpmo_4_5.py -m 'advanced_model and cuda' --run-level 'advanced_model'
-        # h100_2, not h100_1: advanced_model asserts transcribe every audio
-        # response with Whisper, and tests/helpers/media.py only uses an
-        # accelerator for Whisper when a spare GPU exists. On a single card it
-        # grades on CPU: ~8-10 min per clip vs ~30 s, which alone overruns the
-        # 50-minute job timeout (build 2956).
         mirror_hardwares: h100_2
 
       - label: "Omni · MiniCPM-o 4.5 Duplex Test"
@@ -153,10 +148,10 @@ steps:
           - tests/e2e/online_serving/test_minicpmo_4_5_duplex.py
           - tests/e2e/online_serving/test_minicpmo_4_5_duplex_expansion.py
           - tests/e2e/online_serving/test_minicpmo_realtime_duplex_drivers.py
-          - tests/e2e/online_serving/helpers/minicpmo_realtime_duplex_scenarios.py
+          - tests/e2e/online_serving/minicpmo_realtime_duplex_scenarios.py
           - tests/e2e/online_serving/run_minicpmo_realtime_duplex_multi_session.py
           - tests/e2e/online_serving/run_minicpmo_realtime_duplex_soft_interrupt.py
-          - tests/e2e/online_serving/helpers/minicpmo_4_5_duplex.py
+          - tests/helpers/minicpmo_4_5_duplex.py
           - vllm_omni/deploy/minicpmo_4_5_duplex.yaml
           - vllm_omni/experimental/fullduplex/
           - vllm_omni/model_executor/models/minicpmo_4_5/
@@ -169,7 +164,7 @@ steps:
         timeout_in_minutes: 50
         commands:
           - pytest -s -v tests/e2e/online_serving/test_minicpmo_4_5_duplex.py -m 'advanced_model and cuda' --run-level 'advanced_model'
-        mirror_hardwares: h100_1
+        mirror_hardwares: h100_2
 
       - label: "TTS · VoxCPM2 Test"
         source_file_dependencies:

.buildkite/cuda/test-nightly.yml

@@ -22,7 +22,7 @@ steps:
         timeout_in_minutes: 50
         commands:
           - pytest -s -v tests/e2e/online_serving/test_minicpmo_4_5_duplex_expansion.py -m "full_model and cuda and H100 and omni" --run-level "full_model"
-        mirror_hardwares: h100_1
+        mirror_hardwares: h100_2
 
       - label: ":full_moon: Omni · Doc Test with L4"
         timeout_in_minutes: 90
@@ -50,19 +50,6 @@ steps:
             exit $$EXIT
         mirror_hardwares: h100_2
 
-      - label: ":full_moon: Omni · MiniCPM-o 4.5 · Accuracy Test"
-        timeout_in_minutes: 180
-        commands:
-          - export SEED_TTS_WER_EVAL=1
-          - export SEED_TTS_EVAL_DEVICE=cuda:1
-          - |
-            set +e
-            pytest -s -v tests/e2e/accuracy/minicpmo_4_5/test_minicpmo_4_5.py -m "full_model and cuda" --run-level full_model
-            EXIT=$$?
-            buildkite-agent artifact upload "tests/e2e/accuracy/minicpmo_4_5/results/*.json"
-            exit $$EXIT
-        mirror_hardwares: h100_2
-
       - label: ":full_moon: Omni · Perf Test · No Async Chunk"
         key: nightly-omni-performance-no-async-chunk
         timeout_in_minutes: 300
@@ -115,32 +102,6 @@ steps:
             exit $$EXIT
         mirror_hardwares: h100_3
 
-      - label: ":full_moon: Omni · MiniCPM-o 4.5 · Perf Test"
-        key: nightly-omni-performance-minicpmo-4-5
-        timeout_in_minutes: 180
-        commands:
-          - export BENCHMARK_DIR=tests/dfx/perf/results
-          - |
-            set +e
-            pytest -s -v tests/dfx/perf/scripts/run_benchmark.py --test-config-file tests/dfx/perf/tests/test_minicpmo_4_5.json
-            EXIT=$$?
-            buildkite-agent artifact upload "tests/dfx/perf/results/*.json"
-            exit $$EXIT
-        mirror_hardwares: h100_1
-
-      - label: ":full_moon: Omni · MiniCPM-o 4.5 · Duplex Seed-TTS Perf Test"
-        key: nightly-omni-performance-minicpmo-4-5-duplex-seed-tts
-        timeout_in_minutes: 180
-        commands:
-          - export BENCHMARK_DIR=tests/dfx/perf/results
-          - |
-            set +e
-            pytest -s -v tests/dfx/perf/scripts/run_benchmark.py --test-config-file tests/dfx/perf/tests/test_minicpmo_4_5_duplex_seed_tts.json
-            EXIT=$$?
-            buildkite-agent artifact upload "tests/dfx/perf/results/*.json"
-            exit $$EXIT
-        mirror_hardwares: h100_1
-
       - label: ":full_moon: Omni · Multi-Replica Startup Test with 4x H100"
         timeout_in_minutes: 45
         commands:
@@ -345,7 +306,7 @@ steps:
         commands:
           - export DIFFUSION_BENCHMARK_DIR=tests/dfx/perf/results
           - export DIFFUSION_ATTENTION_BACKEND=FLASH_ATTN
-          - export CACHE_DIT_VERSION=1.5.0
+          - export CACHE_DIT_VERSION=1.3.0
           - |
             set +e
             pytest -s -v tests/dfx/perf/scripts/run_diffusion_benchmark.py --test-config-file tests/dfx/perf/tests/test_qwen_image_vllm_omni.json
@@ -361,7 +322,7 @@ steps:
         commands:
           - export DIFFUSION_BENCHMARK_DIR=tests/dfx/perf/results
           - export DIFFUSION_ATTENTION_BACKEND=FLASH_ATTN
-          - export CACHE_DIT_VERSION=1.5.0
+          - export CACHE_DIT_VERSION=1.3.0
           - |
             set +e
             pytest -s -v tests/dfx/perf/scripts/run_diffusion_benchmark.py --test-config-file tests/dfx/perf/tests/test_qwen_image_edit_vllm_omni.json
@@ -377,7 +338,7 @@ steps:
         commands:
           - export DIFFUSION_BENCHMARK_DIR=tests/dfx/perf/results
           - export DIFFUSION_ATTENTION_BACKEND=FLASH_ATTN
-          - export CACHE_DIT_VERSION=1.5.0
+          - export CACHE_DIT_VERSION=1.3.0
           - |
             set +e
             pytest -s -v tests/dfx/perf/scripts/run_diffusion_benchmark.py --test-config-file tests/dfx/perf/tests/test_qwen_image_edit_2511_vllm_omni.json
@@ -393,7 +354,7 @@ steps:
         commands:
           - export DIFFUSION_BENCHMARK_DIR=tests/dfx/perf/results
           - export DIFFUSION_ATTENTION_BACKEND=FLASH_ATTN
-          - export CACHE_DIT_VERSION=1.5.0
+          - export CACHE_DIT_VERSION=1.3.0
           - |
             set +e
             pytest -s -v tests/dfx/perf/scripts/run_diffusion_benchmark.py --test-config-file tests/dfx/perf/tests/test_qwen_image_layered_vllm_omni.json
@@ -409,7 +370,7 @@ steps:
         commands:
           - export DIFFUSION_BENCHMARK_DIR=tests/dfx/perf/results
           - export DIFFUSION_ATTENTION_BACKEND=FLASH_ATTN
-          - export CACHE_DIT_VERSION=1.5.0
+          - export CACHE_DIT_VERSION=1.3.0
           - |
             set +e
             pytest -s -v tests/dfx/perf/scripts/run_diffusion_benchmark.py --test-config-file tests/dfx/perf/tests/test_bagel_vllm_omni.json
@@ -443,7 +404,7 @@ steps:
       - label: ":full_moon: Diffusion X2V · LingBot Video MoE Function Test"
         timeout_in_minutes: 90
         commands:
-          - pytest -s -v tests/e2e/online_serving/test_lingbot_video_moe.py -k "video_generation" -m "full_model and cuda" --run-level "full_model"
+          - pytest -s -v tests/e2e/online_serving/test_lingbot_video_moe.py -m "full_model and cuda" --run-level "full_model"
         mirror_hardwares: h100_1
 
       - label: ":full_moon: Diffusion X2V · Doc Test"
@@ -466,10 +427,10 @@ steps:
           - pytest -s -v tests/e2e/accuracy/test_diffusers_backend_similarity.py -k '2v_matches_diffusers' -m full_model --run-level full_model
         mirror_hardwares: h100_2
 
-      - label: ":full_moon: Diffusion X2V · MiniMax H3 I2VA/Ref2VA Accuracy Test"
+      - label: ":full_moon: Diffusion X2V · MiniMax H3 T2VA Accuracy Test"
         timeout_in_minutes: 180
         commands:
-          - pytest -s -v tests/e2e/accuracy/minimax_h3/test_minimax_h3_i2va_ref2va_similarity.py -m full_model --run-level full_model
+          - pytest -s -v tests/e2e/accuracy/minimax_h3/test_minimax_h3_t2va_similarity.py -m full_model --run-level full_model
         mirror_hardwares: h100_4
 
       - label: ":full_moon: Diffusion X2V · Other Accuracy Test"

.buildkite/cuda/test-ready.yml

@@ -47,17 +47,15 @@ steps:
           - timeout 15m pytest -sv tests/diffusion/batching -m 'core_model and cuda' --run-level "core_model"
         mirror_hardwares: l4_1
 
-      - label: "Diffusion · Distributed & Attention Test"
+      - label: "Diffusion · Distributed Test"
         source_file_dependencies:
           - tests/diffusion/distributed/
-          - tests/diffusion/attention/test_attention_sp.py
           - vllm_omni/diffusion/distributed/
-          - vllm_omni/diffusion/attention/
+          - vllm_omni/diffusion/attention/parallel/
           - vllm_omni/diffusion/data.py
           - vllm_omni/diffusion/models/
         commands:
           - timeout 20m pytest -sv tests/diffusion/distributed -m 'core_model and cuda' --run-level "core_model"
-          - timeout 20m pytest -sv tests/diffusion/attention/test_attention_sp.py -m 'core_model and cuda' --run-level "core_model"
         mirror_hardwares: l4_4
 
       - label: "Diffusion · Model Test"
@@ -128,21 +126,6 @@ steps:
               image: public.ecr.aws/q9t5s3a7/vllm-ci-test-repo:$BUILDKITE_COMMIT
               always-pull: true
               propagate-environment: true
-              # vLLM 0.27 added a pre-flight capacity check in
-              # distributed/device_communicators/shm_broadcast.py. Without this
-              # the container gets Docker's 64 MiB default and every test in
-              # this step dies at engine start with
-              #   RuntimeError: Insufficient space in /dev/shm:
-              #                 240 MiB required, 64 MiB available
-              # (9 failed in 8.7s on build #2949). vLLM 0.26 had no such check
-              # and allocated regardless, so this step passed on main while
-              # being under-provisioned the whole time — 0.27 turned a silent
-              # risk into an explicit error.
-              #
-              # This is the only inline docker plugin block in .buildkite/cuda/;
-              # every other step inherits common/ci_mirror_hardwares.yml, which
-              # already sets 8gb. Matching that rather than inventing a value.
-              shm-size: "8gb"
               environment:
                 - "HF_HOME=/fsx/hf_cache"
               volumes:
@@ -187,7 +170,7 @@ steps:
             timeout 20m bash -c "
               pytest -s -v tests/e2e/offline_inference/test_minicpmo_4_5.py -m 'core_model' --run-level 'core_model'
             "
-        mirror_hardwares: h100_1
+        mirror_hardwares: h100_2
 
       - label: "Omni · MiniCPM-o 4.5 Online Test"
         source_file_dependencies:
@@ -198,7 +181,7 @@ steps:
             timeout 20m bash -c "
               pytest -s -v tests/e2e/online_serving/test_minicpmo_4_5.py -m 'core_model' --run-level 'core_model'
             "
-        mirror_hardwares: h100_1
+        mirror_hardwares: h100_2
 
       - label: "Omni · MiniCPM-o 4.5 Duplex Test"
         source_file_dependencies:
@@ -207,10 +190,10 @@ steps:
           - tests/e2e/online_serving/test_minicpmo_4_5_duplex.py
           - tests/e2e/online_serving/test_minicpmo_4_5_duplex_expansion.py
           - tests/e2e/online_serving/test_minicpmo_realtime_duplex_drivers.py
-          - tests/e2e/online_serving/helpers/minicpmo_realtime_duplex_scenarios.py
+          - tests/e2e/online_serving/minicpmo_realtime_duplex_scenarios.py
           - tests/e2e/online_serving/run_minicpmo_realtime_duplex_multi_session.py
           - tests/e2e/online_serving/run_minicpmo_realtime_duplex_soft_interrupt.py
-          - tests/e2e/online_serving/helpers/minicpmo_4_5_duplex.py
+          - tests/helpers/minicpmo_4_5_duplex.py
           - vllm_omni/deploy/minicpmo_4_5_duplex.yaml
           - vllm_omni/experimental/fullduplex/
           - vllm_omni/model_executor/models/minicpmo_4_5/
@@ -225,19 +208,7 @@ steps:
             timeout 20m bash -c "
               pytest -s -v tests/e2e/online_serving/test_minicpmo_4_5_duplex.py -m 'core_model and cuda' --run-level 'core_model'
             "
-        mirror_hardwares: h100_1
+        mirror_hardwares: h100_2
-
-      - label: "Omni · MiniCPM-o 4.5 Perf Test"
-        timeout_in_minutes: 60
-        source_file_dependencies:
-          - tests/dfx/perf/tests/test_minicpmo_4_5_ready.json
-          - vllm_omni/deploy/minicpmo_4_5.yaml
-          - vllm_omni/model_executor/models/minicpmo_4_5/
-          - vllm_omni/model_executor/stage_input_processors/minicpmo_4_5_omni.py
-        commands:
-          - export BENCHMARK_DIR=tests/dfx/perf/results
-          - pytest -s -v tests/dfx/perf/scripts/run_benchmark.py --test-config-file tests/dfx/perf/tests/test_minicpmo_4_5_ready.json -m 'core_model and cuda'
-        mirror_hardwares: h100_1
 
       - label: "TTS · VoxCPM2 Test"
         source_file_dependencies:

.buildkite/intel/pipeline-intel.yml

@@ -10,7 +10,7 @@ steps:
           DOCKER_BUILDKIT: "1"
           # Buildkite will automatically replace this with the actual commit hash
           VLLM_IMAGE_TAG: "${BUILDKITE_COMMIT}"
-          VLLM_VERSION: "v0.27.0"
+          VLLM_VERSION: "v0.26.0"
         priority: 100
         timeout_in_minutes: 60
         soft_fail: false

.buildkite/intel/scripts/run-xpu-test.sh

@@ -34,23 +34,8 @@ docker_build() {
     docker build "${out[@]}" "$@" -f docker/Dockerfile.xpu .
 }
 
-build_vllm_base() (
-    local vllm_source_dir
-    vllm_source_dir=$(mktemp -d)
-    trap 'rm -rf "${vllm_source_dir}"' EXIT
-
-    git clone --depth 1 --branch "${VLLM_VERSION}" \
-        https://github.com/vllm-project/vllm "${vllm_source_dir}"
-
-    local out=("${export_args[@]/'{{IMAGE}}'/${base_image_name}}")
-    docker build "${out[@]}" \
-        --target vllm-openai \
-        -f "${vllm_source_dir}/docker/Dockerfile.xpu" \
-        "${vllm_source_dir}"
-)
-
 if [ -z "$(docker images -q "${base_image_name}")" ]; then
-    build_vllm_base
+    docker_build "${base_image_name}" --target vllm-base --build-arg "VLLM_VERSION=${VLLM_VERSION}"
 fi
 
 # Try building the docker image

.buildkite/npu/test-npu-nightly.yml

@@ -39,7 +39,7 @@ steps:
             EXIT=$$?
             buildkite-agent artifact upload "tests/dfx/perf/results/*.json"
             exit $$EXIT
-      - label: ":full_moon: Omni · MiniCPM-o 4.5 Test"
+      - label: ":robot: Omni · MiniCPM-o 4.5 Test"
         mirror_hardwares: a3_npu_2
         env:
           VLLM_WORKER_MULTIPROC_METHOD: spawn
@@ -47,34 +47,6 @@ steps:
           HF_TOKEN: "${HF_TOKEN}"
         commands:
           - pytest -s -v tests/e2e/offline_inference/test_minicpmo_4_5.py tests/e2e/online_serving/test_minicpmo_4_5.py tests/e2e/online_serving/test_minicpmo_4_5_expansion.py -m 'full_model' --run-level 'full_model'
-      - label: ":full_moon: Omni · MiniCPM-o 4.5 · Duplex Test"
-        timeout_in_minutes: 180
-        mirror_hardwares: a3_npu_2
-        env:
-          VLLM_WORKER_MULTIPROC_METHOD: spawn
-          VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
-          HF_TOKEN: "${HF_TOKEN}"
-        commands:
-          - >-
-            pytest -s -v
-            tests/e2e/online_serving/test_minicpmo_4_5_duplex.py
-            tests/e2e/online_serving/test_minicpmo_4_5_duplex_expansion.py
-            -m "npu and A3 and omni"
-            --run-level full_model
-      - label: ":full_moon: Omni · MiniCPM-o 4.5 · Accuracy Test"
-        timeout_in_minutes: 180
-        mirror_hardwares: a3_npu_2
-        env:
-          VLLM_WORKER_MULTIPROC_METHOD: spawn
-          VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
-          HF_TOKEN: "${HF_TOKEN}"
-        commands:
-          - |
-            set +e
-            pytest -s -v tests/e2e/accuracy/minicpmo_4_5/test_minicpmo_4_5.py -m "full_model and npu and A3" --run-level full_model
-            EXIT=$$?
-            buildkite-agent artifact upload "tests/e2e/accuracy/minicpmo_4_5/results/*.json"
-            exit $$EXIT
   - group: ":card_index_dividers: TTS Model Test"
     key: nightly-tts-test-group
     depends_on: upload-nightly-pipeline
@@ -115,7 +87,7 @@ steps:
           DIFFUSION_ATTENTION_BACKEND: TORCH_SDPA
         commands:
           - export DIFFUSION_BENCHMARK_DIR=tests/dfx/perf/results
-          - export CACHE_DIT_VERSION=1.5.0
+          - export CACHE_DIT_VERSION=1.3.0
           - |
             set +e
             pytest -s -v tests/dfx/perf/scripts/run_diffusion_benchmark.py -m npu --test-config-file tests/dfx/perf/tests/test_qwen_image_edit_2511_vllm_omni.json

.buildkite/npu/test-npu-ready.yml

@@ -3,29 +3,22 @@ steps:
     key: ready-omni-group
     depends_on: upload-ready-pipeline
     steps:
-      - label: "Omni · MiniCPM-o 4.5 Test"
+      - label: ":robot: Omni · MiniCPM-o 4.5 Test"
-        mirror_hardwares: a3_npu_2
+        agents:
+          queue: "ascend-a3"
+          resource_class: "npu-2"
+        image: "swr.cn-southwest-2.myhuaweicloud.com/modelfoundry/vllm-omni-ci-npu:${BUILDKITE_COMMIT}-a3"
+        plugins:
+          - kubernetes:
+              podSpecPatch:
+                imagePullSecrets:
+                  - name: swr-secret
         env:
           VLLM_WORKER_MULTIPROC_METHOD: spawn
           VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
+          HF_TOKEN: "${HF_TOKEN}"
         commands:
-          - pytest -s -v tests/e2e/offline_inference/test_minicpmo_4_5.py tests/e2e/online_serving/test_minicpmo_4_5.py -m 'core_model and npu and A3 and omni' --run-level 'core_model'
+          - pytest -s -v tests/e2e/offline_inference/test_minicpmo_4_5.py tests/e2e/online_serving/test_minicpmo_4_5.py -m 'core_model' --run-level 'core_model'
-      - label: "Omni · MiniCPM-o 4.5 Duplex Test"
-        mirror_hardwares: a3_npu_2
-        env:
-          VLLM_WORKER_MULTIPROC_METHOD: spawn
-          VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
-        commands:
-          - pytest -s -v tests/e2e/online_serving/test_minicpmo_4_5_duplex.py -m 'core_model and npu and A3 and omni' --run-level 'core_model'
-      - label: "Omni · MiniCPM-o 4.5 Perf Test"
-        timeout_in_minutes: 60
-        mirror_hardwares: a3_npu_2
-        env:
-          VLLM_WORKER_MULTIPROC_METHOD: spawn
-          VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
-        commands:
-          - export BENCHMARK_DIR=tests/dfx/perf/results
-          - pytest -s -v tests/dfx/perf/scripts/run_benchmark.py --test-config-file tests/dfx/perf/tests/test_minicpmo_4_5_ready.json -m 'core_model and npu and A3 and omni'
 
   - group: ":card_index_dividers: TTS Model Test"
     key: ready-tts-group

.buildkite/release/release-pipeline.yml

@@ -40,11 +40,9 @@ steps:
     commands:
       - "bash .buildkite/release/scripts/publish-release-wheels-pypi.sh"
 
-  # Auto-skip when NIGHTLY=1 (scheduled); otherwise require manual unblock.
   - block: "Unblock to build release Docker images"
     depends_on: ~
     key: block-build-release-images
-    if: build.env("NIGHTLY") != "1"
 
   - group: "Build release Docker images"
     key: "build-release-images"
@@ -65,7 +63,7 @@ steps:
               --progress plain \
               -f docker/Dockerfile.cuda .
           - "docker push public.ecr.aws/q9t5s3a7/vllm-omni-release-repo:$BUILDKITE_COMMIT-$(uname -m)"
-          # Fallback default tag (no arch suffix) if arm64 build fails.
+          # re-tag to default image tag and push, just in case arm64 build fails
           - "docker tag public.ecr.aws/q9t5s3a7/vllm-omni-release-repo:$BUILDKITE_COMMIT-$(uname -m) public.ecr.aws/q9t5s3a7/vllm-omni-release-repo:$BUILDKITE_COMMIT"
           - "docker push public.ecr.aws/q9t5s3a7/vllm-omni-release-repo:$BUILDKITE_COMMIT"
         env:
@@ -88,26 +86,6 @@ steps:
         env:
           DOCKER_BUILDKIT: "1"
 
-  # NIGHTLY=1 only: promote ECR images to DockerHub nightly tags, then prune.
-  - label: "Publish nightly multi-arch image to DockerHub"
-    depends_on:
-      - build-release-image-x86
-      - build-release-image-arm64
-    if: build.env("NIGHTLY") == "1"
-    key: publish-nightly-images-dockerhub
-    agents:
-      queue: small_cpu_queue_release
-    commands:
-      - "bash .buildkite/release/scripts/publish-release-images.sh nightly"
-      - "bash .buildkite/release/scripts/cleanup-nightly-builds.sh"
-    plugins:
-      - docker-login#v3.0.0:
-          username: vllmbot
-          password-env: DOCKERHUB_TOKEN
-    env:
-      DOCKER_BUILDKIT: "1"
-      DOCKERHUB_USERNAME: "vllmbot"
-
   - block: "Publish release images to DockerHub"
     key: block-publish-release-images
     depends_on:

.buildkite/release/scripts/cleanup-nightly-builds.sh

@@ -1,147 +0,0 @@
-#!/bin/bash
-# SPDX-License-Identifier: Apache-2.0
-#
-# Clean up old nightly builds from DockerHub (vllm/vllm-omni), keeping the
-# newest 14 tags with the nightly- prefix.
-
-set -ex
-
-TAG_PREFIX="nightly-"
-REPO="vllm/vllm-omni"
-REPO_API_URL="https://hub.docker.com/v2/repositories/${REPO}/tags"
-
-echo "Cleaning up tags with prefix: $TAG_PREFIX in repository: $REPO"
-
-if [ -z "$DOCKERHUB_TOKEN" ]; then
-  echo "Error: DOCKERHUB_TOKEN environment variable is not set"
-  exit 1
-fi
-
-if [ -z "$DOCKERHUB_USERNAME" ]; then
-  echo "Error: DOCKERHUB_USERNAME environment variable is not set"
-  exit 1
-fi
-
-echo "Getting DockerHub bearer token..."
-set +x
-BEARER_TOKEN=$(curl -s -X POST \
-  -H "Content-Type: application/json" \
-  -d "{\"username\": \"$DOCKERHUB_USERNAME\", \"password\": \"$DOCKERHUB_TOKEN\"}" \
-  "https://hub.docker.com/v2/users/login" | jq -r '.token')
-set -x
-
-if [ -z "$BEARER_TOKEN" ] || [ "$BEARER_TOKEN" = "null" ]; then
-  echo "Error: Failed to get DockerHub bearer token"
-  exit 1
-fi
-
-get_all_tags() {
-  local page=1
-  local all_tags=""
-  # Hub `name` is a partial match (not a strict prefix). Use it to narrow the
-  # list, then enforce startswith() client-side. Exhaust API pages; do not
-  # stop merely because a page has no matching tags after filtering.
-  local name_query
-  name_query=$(printf '%s' "$TAG_PREFIX" | jq -sRr @uri)
-
-  while true; do
-    set +x
-    local response
-    response=$(curl -s -H "Authorization: Bearer $BEARER_TOKEN" \
-      "$REPO_API_URL?page=$page&page_size=100&name=${name_query}")
-    set -x
-
-    local page_count
-    page_count=$(echo "$response" | jq -r '.results | length')
-    if [ -z "$page_count" ] || [ "$page_count" = "0" ] || [ "$page_count" = "null" ]; then
-      break
-    fi
-
-    local tags
-    tags=$(echo "$response" | jq -r --arg prefix "$TAG_PREFIX" \
-      '.results[] | select(.name | startswith($prefix)) | "\(.last_updated)|\(.name)"')
-
-    if [ -n "$tags" ]; then
-      all_tags="$all_tags$tags"$'\n'
-    fi
-    page=$((page + 1))
-  done
-
-  echo "$all_tags" | sort -r | cut -d'|' -f2
-}
-
-delete_tag() {
-  local tag_name="$1"
-  echo "Deleting tag: $tag_name"
-
-  local delete_url="https://hub.docker.com/v2/repositories/${REPO}/tags/$tag_name"
-  set +x
-  local response http_code body
-  response=$(curl -s -w "\n%{http_code}" -X DELETE \
-    -H "Authorization: Bearer $BEARER_TOKEN" "$delete_url")
-  set -x
-  http_code=$(printf '%s\n' "$response" | tail -n1)
-  body=$(printf '%s\n' "$response" | sed '$d')
-
-  if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
-    echo "Successfully deleted tag: $tag_name (HTTP ${http_code})"
-    return 0
-  fi
-
-  local detail=""
-  if echo "$body" | jq -e '.detail' > /dev/null 2>&1; then
-    detail=$(echo "$body" | jq -r '.detail')
-  elif [ -n "$body" ]; then
-    detail="$body"
-  else
-    detail="(empty response body)"
-  fi
-  echo "Error: Failed to delete tag $tag_name (HTTP ${http_code}): ${detail}"
-  return 1
-}
-
-echo "Fetching all tags from DockerHub..."
-all_tags=$(get_all_tags)
-
-if [ -z "$all_tags" ]; then
-  echo "No tags found to clean up"
-  exit 0
-fi
-
-total_tags=$(echo "$all_tags" | wc -l)
-echo "Found $total_tags tags"
-
-tags_to_keep=14
-tags_to_delete=$((total_tags - tags_to_keep))
-
-if [ $tags_to_delete -le 0 ]; then
-  echo "No tags need to be deleted (only $total_tags tags found, keeping $tags_to_keep)"
-  exit 0
-fi
-
-echo "Will delete $tags_to_delete old tags, keeping the newest $tags_to_keep"
-
-tags_to_delete_list=$(echo "$all_tags" | tail -n +$((tags_to_keep + 1)))
-
-if [ -z "$tags_to_delete_list" ]; then
-  echo "No tags to delete"
-  exit 0
-fi
-
-echo "Deleting old tags..."
-delete_failures=0
-while IFS= read -r tag; do
-  if [ -n "$tag" ]; then
-    if ! delete_tag "$tag"; then
-      delete_failures=$((delete_failures + 1))
-    fi
-    sleep 1
-  fi
-done <<< "$tags_to_delete_list"
-
-if [ "$delete_failures" -gt 0 ]; then
-  echo "Cleanup finished with ${delete_failures} deletion failure(s)"
-  exit 1
-fi
-
-echo "Cleanup completed successfully"

.buildkite/release/scripts/publish-release-images.sh

@@ -1,87 +1,50 @@
 #!/bin/bash
 # SPDX-License-Identifier: Apache-2.0
 #
-# Publish Docker images from ECR staging to DockerHub.
+# Publish release Docker images from ECR to DockerHub.
-#
+# Pulls per-arch images, tags with `latest` and versioned tags, pushes them,
-# Usage:
+# then creates and pushes a multi-arch manifest.
-#   publish-release-images.sh            # release mode (default)
-#   publish-release-images.sh release
-#   publish-release-images.sh nightly
-#
-# Release tags: latest, v<version>
-# Nightly tags: nightly, nightly-<commit>
 
 set -euo pipefail
 
-MODE="${1:-release}"
+RELEASE_VERSION=$(buildkite-agent meta-data get release-version --default "" | sed 's/^v//')
-
+if [ -z "${RELEASE_VERSION}" ]; then
-DOCKERHUB_REPO="vllm/vllm-omni"
-ECR_REPO="public.ecr.aws/q9t5s3a7/vllm-omni-release-repo"
-COMMIT="$BUILDKITE_COMMIT"
-PRIMARY_TAGS=()
-EXTRA_MANIFEST_TAGS=()
-
-case "${MODE}" in
-  release)
-    RELEASE_VERSION=$(buildkite-agent meta-data get release-version --default "" | sed 's/^v//')
-    if [ -z "${RELEASE_VERSION}" ]; then
   echo "ERROR: release-version metadata not set"
   exit 1
-    fi
-    PRIMARY_TAGS=("latest" "v${RELEASE_VERSION}")
-    ;;
-  nightly)
-    # Commit-pinned manifest reuses nightly-{x86_64,aarch64} arch images.
-    PRIMARY_TAGS=("nightly")
-    EXTRA_MANIFEST_TAGS=("nightly-${COMMIT}")
-    ;;
-  *)
-    echo "Usage: $0 {release|nightly}"
-    exit 2
-    ;;
-esac
-
-echo "========================================"
-echo "Publishing ${MODE} images to ${DOCKERHUB_REPO}"
-echo "  Commit: ${COMMIT}"
-echo "  Primary tags: ${PRIMARY_TAGS[*]}"
-if [ ${#EXTRA_MANIFEST_TAGS[@]} -gt 0 ]; then
-  echo "  Extra manifests: ${EXTRA_MANIFEST_TAGS[*]}"
 fi
+
+COMMIT="$BUILDKITE_COMMIT"
+DOCKERHUB_REPO="vllm/vllm-omni"
+ECR_REPO="public.ecr.aws/q9t5s3a7/vllm-omni-release-repo"
+
+echo "========================================"
+echo "Publishing release images v${RELEASE_VERSION}"
+echo "  Commit: ${COMMIT}"
 echo "========================================"
 
+# Login to ECR to pull staging images
 aws ecr-public get-login-password --region us-east-1 | \
   docker login --username AWS --password-stdin public.ecr.aws/q9t5s3a7
 
-SRC_X86="${ECR_REPO}:${COMMIT}-x86_64"
+docker pull "${ECR_REPO}:${COMMIT}-x86_64"
-SRC_ARM="${ECR_REPO}:${COMMIT}-aarch64"
+docker pull "${ECR_REPO}:${COMMIT}-aarch64"
 
-docker pull "${SRC_X86}"
+docker tag "${ECR_REPO}:${COMMIT}-x86_64" "${DOCKERHUB_REPO}:latest-x86_64"
-docker pull "${SRC_ARM}"
+docker tag "${ECR_REPO}:${COMMIT}-x86_64" "${DOCKERHUB_REPO}:v${RELEASE_VERSION}-x86_64"
+docker push "${DOCKERHUB_REPO}:latest-x86_64"
+docker push "${DOCKERHUB_REPO}:v${RELEASE_VERSION}-x86_64"
 
-publish_manifest() {
+docker tag "${ECR_REPO}:${COMMIT}-aarch64" "${DOCKERHUB_REPO}:latest-aarch64"
-  local tag="$1"
+docker tag "${ECR_REPO}:${COMMIT}-aarch64" "${DOCKERHUB_REPO}:v${RELEASE_VERSION}-aarch64"
-  local arch_tag_base="$2"
+docker push "${DOCKERHUB_REPO}:latest-aarch64"
-  docker manifest rm "${DOCKERHUB_REPO}:${tag}" || true
+docker push "${DOCKERHUB_REPO}:v${RELEASE_VERSION}-aarch64"
-  docker manifest create \
-    "${DOCKERHUB_REPO}:${tag}" \
-    "${DOCKERHUB_REPO}:${arch_tag_base}-x86_64" \
-    "${DOCKERHUB_REPO}:${arch_tag_base}-aarch64"
-  docker manifest push "${DOCKERHUB_REPO}:${tag}"
-}
 
-for tag in "${PRIMARY_TAGS[@]}"; do
+docker manifest rm "${DOCKERHUB_REPO}:latest" || true
-  docker tag "${SRC_X86}" "${DOCKERHUB_REPO}:${tag}-x86_64"
+docker manifest rm "${DOCKERHUB_REPO}:v${RELEASE_VERSION}" || true
-  docker tag "${SRC_ARM}" "${DOCKERHUB_REPO}:${tag}-aarch64"
+docker manifest create "${DOCKERHUB_REPO}:latest" "${DOCKERHUB_REPO}:latest-x86_64" "${DOCKERHUB_REPO}:latest-aarch64"
-  docker push "${DOCKERHUB_REPO}:${tag}-x86_64"
+docker manifest create "${DOCKERHUB_REPO}:v${RELEASE_VERSION}" "${DOCKERHUB_REPO}:v${RELEASE_VERSION}-x86_64" "${DOCKERHUB_REPO}:v${RELEASE_VERSION}-aarch64"
-  docker push "${DOCKERHUB_REPO}:${tag}-aarch64"
+docker manifest push "${DOCKERHUB_REPO}:latest"
-  publish_manifest "${tag}" "${tag}"
+docker manifest push "${DOCKERHUB_REPO}:v${RELEASE_VERSION}"
-done
-
-ARCH_BASE="${PRIMARY_TAGS[0]}"
-for tag in "${EXTRA_MANIFEST_TAGS[@]}"; do
-  publish_manifest "${tag}" "${ARCH_BASE}"
-done
 
 echo ""
-echo "Successfully published ${MODE} images"
+echo "Successfully published release images for v${RELEASE_VERSION}"

.claude/skills/add-tts-model/SKILL.md

@@ -220,70 +220,65 @@ See `plan/voxcpm2_native_ar_design.md`.
 
 ### Steps
 
-1. **Write one adapter** under `vllm_omni/entrypoints/openai/tts_adapters/`.
+1. **Register in `serving_speech.py`** — add all 5 points in a **single commit**;
-   `serving_speech.py` should not need an edit — detection, stage discovery and
+   partial integration causes hard-to-debug failures. This file is modified by every
-   dispatch are all derived from what the adapter declares.
+   model PR and is the most common source of rebase conflicts — see conflict note below.
 
-   Create `vllm_omni/entrypoints/openai/tts_adapters/your_model.py`:
+   **Point 1** — stage constant (near the top, alongside the other `_*_TTS_MODEL_STAGES` sets):
    ```python
-   @register_tts_adapter
+   _YOUR_MODEL_TTS_MODEL_STAGES = {"your_stage_key"}
-   class YourModelAdapter(ARTTSAdapter):
+   ```
-       name = "your_model"                              # registry key + log label
-       stage_keys = frozenset({"your_stage_key"})       # the deploy yaml's model_stage
 
-       def validate(self, request) -> str | None:
+   **Point 2** — union into `_TTS_MODEL_STAGES`:
+   ```python
+   _TTS_MODEL_STAGES: set[str] = (
+       ...
+       | _YOUR_MODEL_TTS_MODEL_STAGES
+   )
+   ```
+
+   **Point 3** — model type detection in `_detect_tts_model_type()`:
+   ```python
+   if model_stage in _YOUR_MODEL_TTS_MODEL_STAGES:
+       return "your_model"
+   ```
+
+   **Point 4** — validation dispatch in `_validate_tts_request()`:
+   ```python
+   if self._tts_model_type == "your_model":
+       return self._validate_your_model_request(request)
+   ```
+
+   **Point 5** — validation + parameter-builder methods:
+   ```python
+   def _validate_your_model_request(self, request) -> str | None:
        if not request.input or not request.input.strip():
            return "Input text cannot be empty"
        return None
 
-       async def build(self, request, sampling_params_list, has_inline_ref_audio):
+   def _build_your_model_params(self, request) -> dict:
        params = {"text": [request.input]}
        if request.voice is not None:
            params["voice"] = [request.voice]
-           return PreparedRequest(
+       return params
-               prompt={"prompt": request.input},
-               tts_params=params,
-               model_type=self.name,
-           )
    ```
+   Wire `_build_your_model_params` into `_create_tts_request()` alongside the other
+   model-specific param builders.
 
-   Then add the module to the import block at the bottom of
+   > **Two dispatch patterns coexist**: Fish Speech uses a `self._is_fish_speech` boolean
-   `tts_adapters/__init__.py` so it registers. That import line is the only shared
+   > instance attribute checked before `elif self._is_tts`, while all newer models
-   file a new model touches — which is also why the old rebase-conflict hotspot is
+   > (CosyVoice3, MOSS-TTS-Nano) use the `_tts_model_type` string returned by
-   gone.
+   > `_detect_tts_model_type()`. For new models, always use the `_tts_model_type` string
+   > pattern — do not add new `_is_*` flags.
 
-   > **Pure-diffusion TTS does not go through adapters yet.** Under
+   > **Unused variable rule**: only extract fields in `_build_your_model_params` that
-   > `for_diffusion()`, `create_speech()` routes straight to
+   > are actually forwarded to the model. Unused extractions fail `ruff F841`.
-   > `_create_diffusion_speech()` and never calls `validate()`/`build()`.
+   > For voice-cloning fields (`ref_audio` → `prompt_audio_path`, `ref_text` →
-   > `DiffusionTTSAdapter` is scaffolding with no production subclass, so logic
+   > `prompt_text`), add them to the param builder and verify they reach the model call.
-   > placed in one would silently never run. Diffusion-engine models follow the
-   > existing diffusion path; wiring it through adapters is open work (#4855).
 
-   **If a stage key alone cannot identify the model**, declare
+   **Rebase conflict note**: when rebasing onto `main` after another model was merged,
-   `model_archs = frozenset({"YourModelForConditionalGeneration"})`; add
+   `serving_speech.py` will conflict. Resolution: always keep *both* the upstream
-   `arch_identifies_entry_stage = True` when the model owns no stage key at all
+   model's additions and your own — never discard either side.
-   (Ming dense). For a rule that is not set membership, override `matches()` (see
-   `covo_audio.py`). For a genuine overlap with another adapter, give one an
-   explicit `detect_priority` — `test_tts_detection.py` fails on an unordered
-   overlap. Models that only serve speech in some topologies override
-   `stage_serves_speech()` (see `audex.py`).
-
-   **Reuse shared helpers via `self.ctx.server`** rather than reimplementing them:
-   `_resolve_ref_audio`, `_apply_uploaded_speaker`, `_validate_ref_audio_format`,
-   `_max_instructions_length`. Read a comparable adapter first — `fish_speech.py`
-   (voice cloning), `higgs_audio_v3.py` (parameter-heavy), `moss_tts.py` (family
-   sharing a base class).
-
-   > **Do not add `self._tts_model_type == ...` branches to `serving_speech.py`.**
-   > Older models predate the adapter framework and still have them; they are being
-   > migrated out (RFC #4327, #4855). `tools/pre_commit/check_tts_adapter.py` is a
-   > ratchet on the remaining count and fails the commit if it grows. Behaviour that
-   > no adapter hook can express is a missing hook — propose it on the RFC.
-
-   > **Unused variable rule**: only extract fields in `build()` that are actually
-   > forwarded to the model. Unused extractions fail `ruff F841`. For voice-cloning
-   > fields (`ref_audio` -> `prompt_audio_path`, `ref_text` -> `prompt_text`), add
-   > them to the params and verify they reach the model call.
 
 2. **Handle model-specific parameters**:
    - Voice cloning: `ref_audio` encoding and prompt injection
@@ -300,7 +295,7 @@ import base64
 from pathlib import Path
 
 def build_voice_clone_prompt(ref_audio_path: str, text: str, codec) -> list:
-    """Build prompt with reference audio for voice cloning, called from the adapter."""
+    """Build prompt with reference audio for voice cloning in serving_speech.py."""
     audio_bytes = Path(ref_audio_path).read_bytes()
     codes = codec.encode(audio_bytes)  # Encode on CPU using model's codec (e.g., DAC)
     token_ids = [code + codec.vocab_offset for code in codes.flatten().tolist()]
@@ -326,7 +321,7 @@ Classify the model's **CI priority** first (high / medium / low). High-priority
 
 | Level | Location | Marker | CI pipeline | Notes |
 |-------|----------|--------|-------------|-------|
-| **L1** | `tests/model_executor/…`, `tests/entrypoints/openai_api/…`, stage-processor tests | `core_model` + `cpu` | `test-ready.yml` | Prompt assembly, async_chunk helpers, adapter validation — no GPU |
+| **L1** | `tests/model_executor/…`, `tests/entrypoints/openai_api/…`, stage-processor tests | `core_model` + `cpu` | `test-ready.yml` | Prompt assembly, async_chunk helpers, `serving_speech` validation — no GPU |
 | **L2** | `tests/e2e/online_serving/test_{slug}.py` | **`core_model` + `advanced_model`** (both on baseline smoke) + `tts` + `@hardware_test(...)` | `test-ready.yml` (`ready` label) | Default deploy smoke: single `/v1/audio/speech` or offline `OmniRunner` path |
 | **L3** | `tests/e2e/online_serving/test_{slug}.py` **and** `tests/e2e/offline_inference/test_{slug}.py` | Baseline smoke: **`core_model` + `advanced_model`**; heavier cases: `advanced_model` only (+ `tts`) | `test-merge.yml` **or** merged into nightly TTS function job | Streaming, voice clone, batch/queue, async_chunk |
 | **L4** | `tests/e2e/online_serving/test_{slug}_expansion.py`, optional offline expansion | `full_model` + `tts` | `test-nightly.yml` (`:full_moon: TTS · Function Test with L4`) | Feature matrix; perf → `tests/dfx/perf/tests/test_tts.json` |
@@ -371,7 +366,7 @@ See [vllm-omni-test skill](../vllm-omni-test/SKILL.md) § **Runtime send helpers
 
 ### Deliverables
 
-- One adapter file under `tts_adapters/` plus its line in the package import block
+- Updated `serving_speech.py` with all 5 integration points (single commit)
 - Client scripts and server launcher under `examples/online_serving/text_to_speech/<model>/`
 - Gradio demo with streaming and voice cloning UI in the same dir
 - E2E tests per **Test Case Writing (CI Levels)** above (priority tier determines L1–L4 scope)
@@ -519,8 +514,8 @@ Use this checklist when integrating a new TTS model:
 - [ ] README.md written
 
 ### Phase 3: Online Serving
-- [ ] Adapter written under `tts_adapters/` and registered in the import block
+- [ ] All 5 `serving_speech.py` integration points added in one commit
-- [ ] Only extract params in `build()` that are forwarded to the model call (ruff F841)
+- [ ] Only extract params in `_build_*_params` that are forwarded to the model call (ruff F841)
 - [ ] Prompt builder handles text input correctly
 - [ ] Voice cloning works (if supported)
 - [ ] All response formats work (wav, mp3, flac, pcm)

.claude/skills/precheck-pr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: precheck-pr
-description: Self-check your branch before creating a PR — catch dead code, prevent new model-specific Python examples, verify accuracy/perf claims, validate PR title format, and confirm merge readiness. Use when the user says "precheck", "self review", "pre-submit check", or "check my PR before I open it." Never posts to GitHub.
+description: Self-check your branch before creating a PR — catch dead code, verify accuracy/perf claims, validate PR title format, and confirm merge readiness. Use when the user says "precheck", "self review", "pre-submit check", or "check my PR before I open it." Never posts to GitHub.
 ---
 
 # PR Pre-Check
@@ -65,8 +65,6 @@ Ask: "Quick mode or full mode?" Then walk the checklist for the detected PR type
 
 **Also run the Code-Quality sweep on every PR**, regardless of type or mode: the five diff-scoped checks in [references/code-quality.md](references/code-quality.md) — kwargs fragility, broad-except swallow, `Any`/wrong type hints, hot-path `.clone()`/`deepcopy`, and event-loop blocking — plus the advisory conventions (log level, structured logging, synchronization, cleanup, dependencies, naming) in [checklists.md](references/checklists.md). These count only lines the PR *adds* — the pre-existing backlog across the repo is out of scope.
 
-**Also run the Examples-Policy check on every PR** using [references/examples-policy.md](references/examples-policy.md). Inspect only Python paths introduced by the diff. Treat a new model-, checkpoint-, vendor-, or family-specific Python example as blocking; do not report pre-existing example debt.
-
 ### Step 5: Print Report
 
 ```
@@ -79,7 +77,6 @@ Pre-check report for <branch>
   ─────────────────  ──────
   PR title format    ✓
   Code quality       ⚠ 1 broad except, 2 Any hints
-  Examples policy    ✗ new model-specific Python example
   PR desc integrity  ✓
   Registry/config    ✓
   Dead code          ⚠ 2 warnings

.claude/skills/precheck-pr/references/checklists.md

@@ -47,19 +47,6 @@ Diff-scoped sweep for five fragility patterns that are pervasive in the existing
 
 Roll the ⚠/✗ counts into the report as a single **Code quality** dimension row.
 
----
-
-## All PRs: Examples Policy (run on every PR, quick & full)
-
-Inspect Python files introduced under `examples/` using
-[examples-policy.md](examples-policy.md). This is a diff-scoped ratchet: existing
-model-specific examples may be edited or removed without triggering the check.
-
-- [ ] **No new model-specific Python examples:** the diff adds, copies, or renames no Python file whose path or behavior is specific to one model, checkpoint, vendor, or model family. ✗ for any violation. Route inference through a shared task/protocol entrypoint, model request behavior through `vllm_omni/model_extras`, and commands through task docs or `recipes/`.
-- [ ] **New generic example code is justified:** any new task-neutral Python file under `examples/` is an actual user-facing entrypoint rather than reusable production logic, a benchmark, an app, a setup tool, or a reproducer. ⚠ when the placement is questionable.
-
-Roll the result into the report as a separate **Examples policy** dimension.
-
 ### Conventions (eyeball — no grep)
 
 Judgment calls that don't grep cleanly — apply them while reading the diff, not as a mechanical check:

.claude/skills/precheck-pr/references/examples-policy.md

@@ -1,68 +0,0 @@
-# Examples Python Policy
-
-Prevent new model-specific Python examples without forcing cleanup of the
-existing backlog. Run this check on every PR in quick and full modes.
-
-## Scope
-
-Set the merge base as in the main workflow, then list Python paths introduced
-by the PR, including additions, copies, and renames:
-
-```bash
-BASE="$(git merge-base HEAD origin/main)"
-git diff --name-status --diff-filter=ACR --find-renames --find-copies \
-  "${BASE}"...HEAD -- 'examples/**/*.py'
-```
-
-Inspect destination paths for copies and renames. Existing model-specific files
-that are only modified or deleted are grandfathered and must not be reported.
-
-## Blocking classification
-
-Mark ✗ when a newly introduced Python file does any of the following:
-
-- Names or scopes a path to one model, checkpoint, vendor, or model family.
-- Hard-codes a model identifier, model-specific prompt, request shape, output
-  conversion, or launch configuration behind an otherwise generic filename.
-- Duplicates an existing task/protocol runner to demonstrate one model.
-- Adds a per-model helper below a generic task hub such as `text_to_speech/`.
-
-Do not infer safety from a generic filename alone. For example, a file named
-`text_to_audio.py` is still model-specific if it only implements one model's
-contract.
-
-## Acceptable additions
-
-A new Python example may pass when it is a genuinely model-neutral,
-user-facing task or protocol entrypoint. It must accept model selection through
-configuration and keep model-specific behavior out of the script.
-
-Use ⚠ when the file is model-neutral but reusable logic appears misplaced under
-`examples/`. Route code by purpose:
-
-| Code purpose | Preferred location |
-|---|---|
-| Model prompt, defaults, request/output adaptation | `vllm_omni/model_extras/` or production model modules |
-| Runnable model command and validation evidence | Task documentation or `recipes/` |
-| UI or interactive application | `apps/` |
-| Benchmark or evaluator | `benchmarks/` |
-| Regression reproducer | `tests/` |
-| Download, conversion, or setup utility | `tools/` |
-
-If a model cannot use an existing shared runner, report the missing generic
-capability. Do not solve the gap by adding a model-specific Python example.
-
-## Report format
-
-Add one row to the pre-check report:
-
-```text
-Examples policy    ✓ no new Python example paths
-Examples policy    ⚠ generic helper belongs in tools/
-Examples policy    ✗ examples/offline_inference/new_model/end2end.py is model-specific
-Examples policy    ✗ examples/offline_inference/x_to_y_model_name.py is model-specific
-```
-
-For a blocker, name the path, the model-specific behavior, and the appropriate
-shared runner or destination. Do not propose deleting unrelated existing
-examples as part of the PR.

.claude/skills/readme.md

@@ -1,9 +1,9 @@
-# Repository Skills for vLLM-Omni
+# Claude Skills for vLLM-Omni
 
-This directory contains repository-scale skills maintained for `vllm-omni`.
+This directory contains Claude Code skills maintained for the `vllm-omni`
-They capture repeatable workflows for common contributor and maintainer tasks
+repository. These skills capture repeatable workflows for common contributor
-such as model integration, CI-aligned testing, performance optimization, and
+tasks such as model integration, pull request review, and release note
-pull request review.
+generation.
 
 ## Directory Structure
 
@@ -14,41 +14,31 @@ include:
 - `references/`: focused reference material used by the skill
 - `scripts/`: small helper scripts used by the skill
 
-## Using the Skills
-
-Coding agents that discover repository skills can invoke the relevant skill by
-name. For other agents, point them to the skill's `SKILL.md` and ask them to
-read it before changing code. Combine a domain skill with `vllm-omni-test` when
-tests or CI coverage change, then use `precheck-pr` for the contributor's final
-self-check.
-
 ## Available Skills
 
-- [`add-diffusion-model`](add-diffusion-model/SKILL.md): guides integration of
+- `add-diffusion-model`: guides integration of a new diffusion model into
-  a new diffusion model into `vllm-omni`
+  `vllm-omni`
-- [`add-tts-model`](add-tts-model/SKILL.md): covers integration of new TTS
+- `diffusion-perf-opt`: guides diffusion model performance optimization,
-  models and related serving workflows
+  including profiling traces, parallel strategies, stage timing analysis, and
-- [`diffusion-perf-opt`](diffusion-perf-opt/SKILL.md): guides diffusion model
+  benchmark-driven tuning
-  performance optimization, including profiling traces, parallel strategies,
+- `quantization`: guides quantization method selection, model integration,
-  stage timing analysis, and benchmark-driven tuning
+  checkpoint loading, and quality/performance validation for vLLM-Omni
-- [`precheck-pr`](precheck-pr/SKILL.md): self-checks a branch before creating a
+- `add-omni-model`: covers addition of new omni-modality model support
-  PR by validating title format, dead code, accuracy and performance claims,
+- `add-tts-model`: covers integration of new TTS models and related serving
-  and merge readiness
+  workflows
-- [`quantization`](quantization/SKILL.md): guides quantization method selection,
+- `generate-release-note`: helps prepare release notes for repository changes
-  model integration, checkpoint loading, and quality/performance validation
+- `precheck-pr`: self-check a branch before creating a PR — validates PR title
-  for vLLM-Omni
+  format, catches dead code, verifies accuracy/perf claims, and confirms merge
-- [`review-pr`](review-pr/SKILL.md): provides a frozen-snapshot, contract-aware
+  readiness
-  workflow for maintainers and reviewers; contributors should use
+- `vllm-omni-test`: guides generation and execution of CI-aligned tests (L1–L4),
-  `precheck-pr` for self-review
+  pytest marker selection (`core_model` / `advanced_model` / `full_model`,
-- [`vllm-omni-npu-model-runner-upgrade`](vllm-omni-npu-upgrade/SKILL.md):
+  `omni` / `tts` / `diffusion`), Buildkite wiring (`test-ready.yml`,
-  upgrades NPU model runners to align with the latest vllm-ascend
+  `test-merge.yml`, `test-nightly.yml`, `test-weekly.yml`), and copy-paste
-  `NPUModelRunner`
+  local plus CI-like `pytest` commands; see `references/test-routing.md` for
-- [`vllm-omni-test`](vllm-omni-test/SKILL.md): guides generation and execution
+  level-to-command mapping
-  of CI-aligned tests (L1–L4), pytest marker selection (`core_model` /
+- `review-pr`: provides a structured workflow for reviewing pull requests
-  `advanced_model` / `full_model`, `omni` / `tts` / `diffusion`), Buildkite
+- `vllm-omni-npu-model-runner-upgrade`: upgrades NPU model runners to align with the
-  wiring (`test-ready.yml`, `test-merge.yml`, `test-nightly.yml`,
+  latest vllm-ascend NPUModelRunner
-  `test-weekly.yml`), and copy-paste local plus CI-like `pytest` commands; see
-  `references/test-routing.md` for level-to-command mapping
 
 ## Maintenance Guidelines
 

.claude/skills/review-pr/SKILL.md

@@ -1,239 +0,0 @@
----
-name: review-pr
-description: Review pull requests and local branches for vllm-project/vllm-omni with a frozen snapshot, module-design ownership, feature-design overlays, targeted validation, and concise evidence-backed findings. Use for default, detailed, or repeat maintainer reviews; checking correctness, compatibility, tests, benchmarks, model additions, distributed changes, or breaking behavior; and identifying or explicitly requesting the most relevant code-owner reviewers. Use precheck-pr instead for an author's pre-submit self-check.
----
-
-# Review vLLM-Omni Pull Requests
-
-Review like a maintainer: direct, selective, and focused on issues that CI does
-not prove. Prefer a few high-confidence findings over exhaustive commentary.
-Zero findings is a valid result.
-
-## Quality contract
-
-Make every finding:
-
-- **Correct:** prove a reachable failure, not a suspicion.
-- **Prioritized:** lead with merge blockers and high-impact defects.
-- **Actionable:** identify the smallest safe fix direction.
-- **Evidence-based:** cite code, tests, docs, CI, or measurements.
-- **Concise:** avoid review templates and repeated summaries.
-- **Calibrated:** match severity to user and maintainer impact.
-
-Do not report unrelated backlog, style already enforced by pre-commit, or a
-missing test that would not protect changed behavior.
-
-## Select the input and depth
-
-Use `vllm-project/vllm-omni` as the base repository. Accept its forks and local
-checkouts; use another skill for unrelated repositories.
-
-| Input | Review surface |
-| --- | --- |
-| PR number or URL | Frozen PR metadata, full diff, and relevant threads. |
-| Local branch/worktree | Frozen target-base SHA through committed, staged, unstaged, and in-scope untracked changes. |
-| Pre-filled context | Reuse supplied metadata; fetch only missing facts and the full diff. |
-
-Default to maintainer brevity. A detailed or audit request expands coverage and
-lists `path:line` findings, but keeps the same confidence and severity bar.
-
-## Reference guide
-
-Load references in review order: process, one primary module contract, matching
-feature designs, evidence checks, then delivery. Every file is linked directly
-below; do not load unrelated module references.
-
-Each concise reference links to the maintained
-[vLLM-Omni documentation](https://docs.vllm.ai/projects/vllm-omni/en/latest/).
-For branch-specific behavior, inspect the matching `docs/` file in the reviewed
-checkout first; use the published latest docs for current guidance and discovery.
-If docs and live code disagree, verify the code/tests and report the drift.
-
-### Review process
-
-| Reference | Read when |
-| --- | --- |
-| [review-execution.md](references/process/review-execution.md) | Every review; freeze inputs, inspect safely, and deliver against the same snapshot. |
-| [general-checks.md](references/process/general-checks.md) | Every review; apply repository-wide correctness and evidence rules. |
-| [design-contracts.md](references/process/design-contracts.md) | Every production review; resolve branch-local module and feature design status. |
-| [review-routing.md](references/process/review-routing.md) | After the diff census; select one primary module and conditional overlays. |
-
-### Primary module contract
-
-| Reference | Read when |
-| --- | --- |
-| [entrypoints.md](references/modules/entrypoints.md) | Offline/CLI/API ingress, validation, rendering, streaming, or sessions change. |
-| [configuration.md](references/modules/configuration.md) | Config construction, deploy/stage schema, defaults, registry, or topology changes. |
-| [input-output-modality.md](references/modules/input-output-modality.md) | Requests, messages, serialization, output types, accumulation, or completion change. |
-| [error-contracts.md](references/modules/error-contracts.md) | Error classification, fatality, propagation, sanitization, or rendering changes. |
-| [engine-orchestration.md](references/modules/engine-orchestration.md) | Cross-stage routing, request state, output ordering, RPC correlation, or terminal convergence changes. |
-| [stage-runtime.md](references/modules/stage-runtime.md) | Placement, startup, readiness, replica identity, affinity, membership, or shutdown changes. |
-| [omni-connector.md](references/modules/omni-connector.md) | Cross-stage/process/device/node transport or synchronization changes. |
-| [model-integration.md](references/modules/model-integration.md) | Registration, preprocessing, loading, runners, or model-specific execution changes. |
-| [ar-runtime.md](references/modules/ar-runtime.md) | AR scheduling, request/cache state, adapters, workers, or upstream vLLM semantics change. |
-| [diffusion.md](references/modules/diffusion.md) | Diffusion runtime, models, batching, parallelism, or offload changes. |
-| [execution-platforms.md](references/modules/execution-platforms.md) | Hardware selection, capabilities, vendor workers, kernels, or patches change. |
-| [cache-management.md](references/modules/cache-management.md) | Cache identity, reuse, validity, reset, eviction, or teardown changes. |
-| [quantization.md](references/modules/quantization.md) | Quantization selection, checkpoint metadata, layer mapping, precision, or constraints change. |
-| [observability.md](references/modules/observability.md) | Metrics, logs, units, labels, correlation, or lifecycle changes. |
-| [profiling.md](references/modules/profiling.md) | Profiling instrumentation, traces, start/stop lifecycle, or overhead changes. |
-| [benchmarking.md](references/modules/benchmarking.md) | Benchmark workload, metric calculation, CLI, or result metadata changes. |
-
-### Feature-design overlays
-
-| Reference | Read when |
-| --- | --- |
-| [runtime-stage-execution.md](references/features/runtime-stage-execution.md) | Disaggregated inference, async chunk/output/materialization, or prefix caching changes. |
-| [communication.md](references/features/communication.md) | A concrete OmniConnector backend or its deployment contract changes. |
-| [diffusion-acceleration.md](references/features/diffusion-acceleration.md) | Diffusion parallelism, attention, quantization, cache, batching, or offload changes. |
-| [infrastructure-performance.md](references/features/infrastructure-performance.md) | Metrics infrastructure or documented speech optimization stacks change. |
-
-### Evidence and quality checks
-
-| Reference | Read when |
-| --- | --- |
-| [model-addition-checklist.md](references/checks/model-addition-checklist.md) | A model, architecture, loader, processor, registry, or stage config is added. |
-| [perf-verification.md](references/checks/perf-verification.md) | The PR makes a latency, throughput, memory, or quality claim. |
-| [test-quality-evaluation.md](references/checks/test-quality-evaluation.md) | Tests change, are absent for risky code, or may not exercise production behavior. |
-| [tests-docs-checklist.md](references/checks/tests-docs-checklist.md) | Coverage, CI markers, examples, user docs, or PR evidence need review. |
-| [verification.md](references/checks/verification.md) | Hardware, a server, or a runnable affected path is available for active verification. |
-| [examples-policy.md](../precheck-pr/references/examples-policy.md) | The PR adds, copies, or renames Python under `examples/`; apply the canonical policy shared with `precheck-pr`. |
-
-### Delivery and reviewer coordination
-
-| Reference | Read when |
-| --- | --- |
-| [maintainer-style-study.md](references/delivery/maintainer-style-study.md) | Findings are ready for concise maintainer-style delivery. |
-| [review-requests.md](references/delivery/review-requests.md) | The user asks to identify, suggest, request, or ping code-owner reviewers. |
-
-## Workflow
-
-### 1. Freeze and report the snapshot
-
-Pin the base and head before reading source or running validation. Within 60 seconds,
-report the pinned head, CI, mergeability, and preliminary findings in the host
-conversation. Do not wait for CI or post this update to GitHub.
-
-If the target changes while fetching, discard the evidence and retry once. If
-it changes again, report the churn and wait for a stable target.
-
-For a trusted PR head, materialize the pinned head in an isolated detached
-worktree. A worktree freezes identity but is not a security sandbox. Treat fork
-heads as untrusted unless the user and environment policy explicitly establish
-otherwise: execute them only in a disposable, secret-free sandbox with restricted
-filesystem, network, and resources; without one, use static SHA-addressed reads
-and CI evidence only. For a local review, freeze the committed, index, worktree,
-and NUL-safe in-scope untracked contents. Follow
-[review-execution.md](references/process/review-execution.md) for trust gates,
-state fingerprints, and byte-for-byte staleness checks.
-
-### 2. Build the diff census
-
-Group files into production code, tests, docs, configuration, build/CI, and
-generated artifacts. Map each changed production file and test group to the PR
-goal. Compare the title/body claims with the actual diff; use linked issues only
-when they define the contract or reproduction.
-
-Mark unrelated scope and unexplained generated artifacts. Do not infer behavior
-from the PR description without tracing the live code.
-
-### 3. Route from the live behavior
-
-Trace each claimed behavior through the changed producer to its live consumer,
-then use [design-contracts.md](references/process/design-contracts.md) and
-[review-routing.md](references/process/review-routing.md) to select one primary
-module contract, a second only for a real documented cross-boundary call path,
-and every matching feature-design and evidence overlay. Treat titles and paths
-as hints; live behavior and the frozen head's current design metadata are
-authoritative. For docs-, tests-, or CI-only changes, route to the production
-contract they protect or use only the applicable evidence checks.
-
-### 4. Run the blocker scan
-
-Apply every category in [general-checks.md](references/process/general-checks.md) before
-lower-priority comments.
-
-If the diff census contains an added, copied, or renamed Python path under
-`examples/`, read and apply the canonical
-[examples policy](../precheck-pr/references/examples-policy.md). Treat a new
-model-specific Python example as blocking. Do not flag model-specific example
-debt that the PR only modifies or removes, and do not run the rest of the
-author-oriented `precheck-pr` workflow.
-
-For each changed value or behavior, trace:
-
-```text
-public ingress -> validation/defaulting -> producer -> transformations
-  -> stage/worker/connector boundary -> final consumer -> terminal cleanup
-```
-
-Cover every applicable offline/online, streaming/non-streaming, sync/async,
-feature-on/off, topology, and compatibility path. Search bounded callers and
-sibling implementations rather than assuming the changed hunk is the only path.
-
-### 5. Apply module and feature contracts
-
-Apply the reference set selected in step 3 and any matching repo-local skill.
-Read the exact module and feature pages in the frozen head, including status,
-ownership boundary, dependencies, candidate invariants, safe-change guide, and
-promotion gate. Candidate or draft rules are questions, not blockers, unless
-current code, tests, or policy enforce them. Inspect both sides of any config,
-registry, serialization, connector, cache, or stage boundary.
-
-When a diff adds or expands a helper, class, fallback, compatibility branch, or
-public behavior, run a subtraction pass: remove out-of-scope behavior and check
-whether each new abstraction can be deleted, merged, moved, or inlined.
-
-### 6. Verify the changed path
-
-Before each validation group, verify the frozen SHA plus the tracked, index,
-untracked, and ignored-file fingerprint, or recreate a pristine snapshot. On a
-trusted head or inside the required sandbox, run an import/version preflight,
-then the narrowest relevant tests and low-cost static checks. Bind every result
-to the head SHA, snapshot fingerprint, and environment fingerprint. Never run
-imports, tests, builds, hooks, or repo-configurable tooling from an untrusted
-head on the reviewer host.
-
-- Treat CI as status evidence; inspect only the first overlapping failure.
-- For docs-only changes, use diff hygiene, links/build checks, and bounded live
-  contract verification instead of dependency setup or pytest.
-- For hardware-dependent paths, run available static/CPU checks and name the
-  exact GPU/NPU gap. Never simulate device evidence.
-- For performance or accuracy claims, require comparable base/head runs with
-  the same environment, workload, warmup, repetitions, and quality criteria.
-
-Stop when each changed semantic path has a supported finding or an explicit
-no-issue conclusion. Do not search further only to increase confidence.
-
-### 7. Consolidate and deliver
-
-Verify each finding against the current diff, deduplicate by root cause, and
-order by severity.
-
-Re-read the remote head and reverify or recreate the pristine validation
-snapshot immediately before delivery. If either changed, mark the review stale
-and restart from the new snapshot.
-
-Return findings first. Use
-[maintainer-style-study.md](references/delivery/maintainer-style-study.md) to keep them
-direct and brief. Each finding must include an exact `path:line`, trigger or
-call path, current behavior, impact, and smallest fix direction. If there are
-no findings, say so briefly and name material validation gaps.
-
-Keep the review read-only unless the user explicitly authorizes posting. Do not
-submit `APPROVE`, `COMMENT`, or `REQUEST_CHANGES`, add labels, edit code, or push
-commits as an implied part of review.
-
-### 8. Optionally request focused owner reviews
-
-Only when the user asks to identify or request reviewers, read
-[review-requests.md](references/delivery/review-requests.md). Rank path-matched
-CODEOWNERS with the frozen module page's owners or required reviewers and
-documented governance expertise; propose one to three focused reviewers with an
-explicit contract rationale.
-
-Identifying or suggesting reviewers is read-only. Requesting reviewers or
-posting `@mention` comments changes external state and requires explicit user
-authorization. When authorized, recheck the head, deduplicate existing
-requests, and post at most one consolidated comment. Do not infer this
-permission from a request to review the code.

.claude/skills/review-pr/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "vLLM-Omni PR Review"
-  short_description: "Review vLLM-Omni PRs and route owner requests"
-  default_prompt: "Use $review-pr to review this vLLM-Omni pull request with owner-specific rules and evidence-backed findings."

.claude/skills/review-pr/references/checks/model-addition-checklist.md

@@ -1,121 +0,0 @@
-# Model Addition Checklist
-
-Read this reference when a PR adds or expands a model architecture, pipeline,
-loader, processor, registry entry, or stage configuration.
-
-Official docs: [model contribution guides](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/model/),
-[adding an omni model](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/model/adding_omni_model/),
-[adding a diffusion model](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/model/adding_diffusion_model/),
-[adding a TTS model](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/model/adding_tts_model/),
-[supported models](https://docs.vllm.ai/projects/vllm-omni/en/latest/models/supported_models/),
-[diffusion features](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion_features/),
-and [feature compatibility](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/feature_compatibility/).
-
-## Match claims to the diff
-
-- Reconcile every claimed architecture, modality, variant, feature, and example
-  with changed files and registry entries.
-- Resolve config model types, architecture names, callable paths, exports, and
-  dependency extras against live symbols.
-- Check sibling generations sharing an architecture name are disambiguated by
-  a stable config predicate rather than import order or an accidental default.
-
-## Close the integration chain
-
-Trace:
-
-```text
-public model id -> config/pipeline selection -> registry -> loader/processor
-  -> stage inputs -> model execution -> stage/public output
-```
-
-Verify optional dependencies fail with an actionable message, weight names and
-dtypes map correctly, and each advertised serving mode reaches the production
-dispatcher. Confirm outputs are non-empty and valid for their modality, shape,
-sample rate, or response schema.
-
-## Keep support documentation truthful
-
-- Build an evidence-backed inventory of the new model's exact architecture and
-  checkpoint identifiers, modalities and tasks, hardware backends, serving
-  modes, and supported acceleration, parallelism, cache, offload, and
-  quantization features. Treat untested support as unknown, not supported.
-- Update `docs/models/supported_models.md` with the architecture, model family,
-  example checkpoints, and only the backends validated by the PR.
-- For a diffusion model, add it to the applicable ImageGen, VideoGen, or
-  AudioGen table in `docs/user_guide/diffusion_features.md`. Fill every feature
-  column according to its legend and document partial support or constraints.
-- Update `docs/user_guide/feature_compatibility.md` when the model changes valid
-  feature combinations, configuration constraints, examples, or limitations,
-  and update any other branch-local support table affected by the claims.
-- Cross-check every documented support mark against the registry, configuration,
-  production-path tests, and PR evidence; do not copy a sibling model's support
-  claims without validation.
-
-## Ship the model recipe
-
-- Require every new model PR to add or update one model-family recipe under
-  `recipes/<vendor>/` and its row in the `recipes/README.md` Available Recipes
-  table. Follow [`recipes/TEMPLATE.md`](../../../../../recipes/TEMPLATE.md) and
-  the layout rules in
-  [`recipes/README.md`](../../../../../recipes/README.md); the
-  external recipes repository is a structural reference, not a substitute.
-- Include only tested task, serving-mode, and hardware configurations. Keep the
-  exact model identifiers, flags, commands, verification, feature support,
-  constraints, and limitations consistent with code, tests, examples, and the
-  support documentation.
-- Cover each validated platform in its own hardware section. Use one recipe per
-  model family by default; justify a split when configurations cannot be kept
-  clear in one file, and do not add placeholder sections for untested platforms.
-
-## Compare the reference implementation
-
-Require every new model PR to include a head-versus-reference accuracy or
-quality and performance comparison:
-
-- Name the canonical implementation and pin its repository revision, package
-  version, configuration, and checkpoint. If it cannot run, explain why and use
-  the closest runnable reference; do not silently omit the comparison.
-- Match inputs or dataset, seed, output settings, precision or quantization,
-  hardware, software, warmup, repetitions, synchronization, and timing and
-  memory scope. Include exact commands and environment details for both sides.
-- Compare accuracy or output quality with a task-appropriate metric and explicit
-  tolerance. When no reliable metric exists, provide paired fixed-input outputs,
-  artifacts, and evaluation criteria, and explain expected numerical or
-  qualitative differences.
-- Report end-to-end latency, task-appropriate throughput, peak device memory,
-  run-to-run variability, and head/reference ratios at equivalent output quality.
-- Prefer a timing split for preprocessing or encoding, each model stage,
-  inter-stage transfer or communication, decoding or postprocessing, and output
-  assembly. Define the boundaries, account for overlap, reconcile the split with
-  end-to-end time, and explain any unavailable stage measurement.
-
-Use [perf-verification.md](perf-verification.md) for the comparison protocol and
-repository benchmark and profiling links.
-
-## Remove accidental surface
-
-Search bounded call sites for:
-
-- inference-dead training `forward()` paths, unused factories/wrappers, never-set
-  branch keys, and immediately discarded parameters;
-- duplicate payload strings, validation, or shape coercion across stages;
-- compatibility aliases in brand-new code without an existing caller;
-- private symbols re-exported as public API or module-level side effects.
-
-Keep code only when it has a distinct live caller, invariant, or compatibility
-contract. Prefer one typed producer-consumer schema to repeated string keys.
-
-## Require proportionate evidence
-
-- Run a representative production-path inference and assert output content, not
-  only process survival.
-- Require profiling or A/B tables when the PR makes performance, memory,
-  precision, or quality claims, or when a suspected hot-path/device bug needs
-  that evidence. Do not impose fixed utilization or regression thresholds that
-  the repository does not define.
-- Require focused registry/config/loading tests, a representative E2E path, and
-  user-facing model/usage documentation.
-
-Use [diffusion.md](../modules/diffusion.md) for diffusion models and
-[perf-verification.md](perf-verification.md) for quantitative claims.

.claude/skills/review-pr/references/checks/perf-verification.md

@@ -1,51 +0,0 @@
-# Performance and Accuracy Verification
-
-Activate this reference when the PR adds a model or claims or intentionally
-changes latency, throughput, memory, scaling, precision, or output quality.
-
-Official docs: [profiling](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/profiling/),
-[serving benchmarks](https://docs.vllm.ai/projects/vllm-omni/en/latest/cli/bench/serve/),
-and [metrics](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/metrics/).
-
-## Comparable A/B contract
-
-Compare frozen base and head for an existing path. For a new model absent from
-base, compare head with a pinned canonical reference implementation. Use the same:
-
-- hardware, driver, software versions, model/checkpoint, and dependencies;
-- input or dataset, seed, precision, batch/concurrency, topology, and feature
-  flags;
-- warmup, measured repetitions, synchronization, timing scope, and memory
-  collection method.
-
-Keep exact commands and report variability rather than a cherry-picked run.
-Use the repository's benchmark when it covers the claim; otherwise use the
-smallest reproducible workload that reaches the changed production path.
-
-## Evidence table
-
-| Dimension | Typical evidence |
-| --- | --- |
-| Latency | End-to-end latency and, when available, TTFT plus a defined per-stage and transfer-time split. |
-| Throughput/scaling | Requests, tokens, frames, or audio duration per second across the claimed concurrency/topology. |
-| Memory | Peak allocated/reserved device memory and OOM boundary if relevant. |
-| Quality/accuracy | Repository metric or known-good output comparison with an explicit tolerance; paired samples when no metric exists. |
-
-Every optimization needs correctness or quality evidence. A faster result on a
-different workload, precision, seed, or topology is not a valid comparison.
-
-## Reviewer verification ladder
-
-1. Run base/head A/B on suitable hardware when affordable.
-2. If only one side can run, verify the script and request a comparable pair.
-3. If hardware or assets are unavailable, audit methodology, code path, and
-   contributor evidence; name the exact unverified claim.
-
-Classify discrepancies before reporting: implementation regression, benchmark
-bug, environmental drift, noise, or unsupported claim. Explain material
-regressions against the PR's stated goal or repository contract; do not invent
-universal percentage thresholds.
-
-Report claimed and measured values together, bind them to the frozen SHAs and
-environment, and keep unavailable hardware as a validation gap rather than a
-fabricated pass.

.claude/skills/review-pr/references/checks/test-quality-evaluation.md

@@ -1,39 +0,0 @@
-# Test Quality Evaluation
-
-Read this reference when tests change, a risky production path has no test, or
-a test-only PR may not prove the intended behavior.
-
-Official docs: [test system overview](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/ci/test_system_overview/)
-and [test writing guide](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/ci/test_writing_guide/).
-
-## Static proof check
-
-For each changed semantic path, ask whether the test would fail if that behavior
-were reverted or broken. Check:
-
-- assertions pin the contract, not only non-null output, logs, or “no crash”;
-- the production dispatcher, registry, connector, or scheduler is reached
-  instead of the changed behavior being mocked away;
-- fakes preserve relevant types, MRO, shapes, devices, async behavior, and
-  lifecycle transitions;
-- seeds, ordering, timing, synchronization, external services, and numeric
-  tolerances are deterministic or explicitly controlled;
-- normal, invalid, boundary, feature-off, failure/cancellation, and regression
-  paths are covered where the diff changes them;
-- run-level and domain markers place hardware/model tests in the intended CI
-  lane without silently skipping the contract.
-
-Map source symbols to tests with bounded `rg` searches; do not assume the test
-tree mirrors production paths.
-
-## Runtime check
-
-Run the narrowest affected tests supported by the environment. Record skipped
-hardware/model cases as gaps. Classify failures as code, test, infrastructure,
-or flaky before turning them into findings; one passing rerun does not erase a
-flakiness signal.
-
-Keep grades or matrices internal. Report only concrete code bugs or the one or
-two test defects that leave changed behavior materially unprotected. Use
-[tests-docs-checklist.md](tests-docs-checklist.md) for CI and documentation
-coverage.

.claude/skills/review-pr/references/checks/tests-docs-checklist.md

@@ -1,48 +0,0 @@
-# Tests and Documentation Checklist
-
-Use this reference to connect changed behavior to coverage, CI selection,
-examples, documentation, and reproducible PR evidence.
-
-Official docs: [test writing guide](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/ci/test_writing_guide/),
-[test execution guide](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/ci/test_execution_guide/),
-and [documentation guide](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/DOCS_GUIDE/).
-
-## Coverage packet
-
-For each high-risk change, record a compact internal packet:
-
-```text
-change and failure risk -> existing unit/E2E coverage -> uncovered boundary
-  -> smallest test and stable assertion that closes the gap
-```
-
-Prefer a regression test that fails on the frozen base for bug fixes. Check
-numeric tolerances, deterministic inputs, realistic mocks, hardware/domain
-markers, and Buildkite/CI wiring using the documentation present on the reviewed
-branch. A skipped test is not a pass.
-
-## Documentation sync
-
-Require user-facing updates when the diff changes a model, feature, CLI/API,
-config key, default, compatibility behavior, or supported platform. Verify:
-
-- the actual docs navigation and support tables used by the branch;
-- exact identifiers, defaults, constraints, known limitations, and migration;
-- a minimal runnable example for newly exposed behavior;
-- examples and docs agree on commands, parameters, output schema, and supported
-  modes;
-- links and the bounded live contract build or resolve correctly.
-
-Do not request docs for internal behavior with no user-visible contract.
-
-## PR evidence
-
-For contributor-run tests or benchmarks, require enough provenance to evaluate
-the claim: hardware, relevant software versions, exact commands, inputs/model,
-result, and approximate runtime. Performance or accuracy evidence must compare
-base and head under equivalent conditions; use
-[perf-verification.md](perf-verification.md).
-
-Turn a missing test or document into a finding only when it protects or explains
-changed behavior. Name the smallest useful addition rather than requesting a
-broad coverage expansion.

.claude/skills/review-pr/references/checks/verification.md

@@ -1,36 +0,0 @@
-# Active Verification
-
-Read this reference when a runnable affected path and suitable local or remote
-hardware are available. Never claim device evidence from static analysis or a
-simulated backend.
-
-Official docs: [installation](https://docs.vllm.ai/projects/vllm-omni/en/latest/getting_started/installation/)
-and [test execution guide](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/ci/test_execution_guide/).
-
-## Choose the narrowest level
-
-| Available environment | Verification |
-| --- | --- |
-| Matching accelerator, model/assets, and server | Targeted unit/integration test plus one representative E2E request. |
-| Matching accelerator without serving setup | Targeted model/runtime test and output or metric inspection. |
-| CPU/static environment only | Import/version preflight, focused CPU tests, config/registry resolution, and static contract checks. |
-| Missing dependencies or inaccessible hardware | Record the exact gap and evaluate contributor/CI evidence. |
-
-## Execute safely
-
-1. Bind the run to the frozen head SHA and record Python, platform, dependency,
-   model, device, and relevant environment fingerprints.
-2. Run the smallest affected unit test before an E2E workload.
-3. Exercise the changed public or production-dispatch path with bounded inputs.
-4. Compare actual output, metrics, cleanup, and exit behavior with the PR claim.
-5. For base/head claims, use the equivalent A/B protocol in
-   [perf-verification.md](perf-verification.md).
-
-Avoid disturbing shared servers, ports, models, or accelerators without user
-authorization. Do not install large dependencies, download gated assets, or
-start remote workloads merely because hardware might exist.
-
-Report the command, environment, result, and any skipped path. Classify failures
-as change-induced, pre-existing, infrastructure, environment, or flaky before
-making a finding. A hardware gap lowers confidence; it is not automatic proof
-of a defect.

.claude/skills/review-pr/references/delivery/maintainer-style-study.md

@@ -1,105 +0,0 @@
-# Maintainer Review Style
-
-Use this reference only when turning proved findings into comments. The baseline
-maintainer samples favor short, direct comments and reserve long explanations
-for architecture or non-obvious failure paths.
-
-Official docs: [contributing and review process](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/).
-
-## Evidence basis
-
-This calibration used 928 PRs merged from 2026-05-10 through 2026-08-08.
-Candidates were ranked by substantive human inline-review threads, then by
-distinct reviewers and review rounds. Author self-comments, bots and AI
-reviewers, and bodyless approvals were excluded. Counts selected the sample;
-the practices below came from reading root comments and follow-up replies.
-
-The main set contains the six leaders after filtering; three other high-ranked
-PRs add core-runtime and benchmark coverage. All were merged.
-
-| PR | Review boundary |
-| --- | --- |
-| [#2906](https://github.com/vllm-project/vllm-omni/pull/2906) | New TTS model, shared utilities, recipes, and request state. |
-| [#3907](https://github.com/vllm-project/vllm-omni/pull/3907) | Full-duplex API, session lifecycle, concurrency, and realtime evidence. |
-| [#2162](https://github.com/vllm-project/vllm-omni/pull/2162) | Diffusion world model, OpenPI serving, tests, examples, and docs. |
-| [#3454](https://github.com/vllm-project/vllm-omni/pull/3454) | Diffusion model, generic CLI surface, loaders, and configuration scope. |
-| [#4425](https://github.com/vllm-project/vllm-omni/pull/4425) | Structured configuration, typing, defaults, and compatibility. |
-| [#5397](https://github.com/vllm-project/vllm-omni/pull/5397) | Distributed offload, collectives, failure handling, and load semantics. |
-| [#4281](https://github.com/vllm-project/vllm-omni/pull/4281) | Composable parallelism, configuration contracts, and examples. |
-| [#3628](https://github.com/vllm-project/vllm-omni/pull/3628) | Stage metrics, benchmark definitions, opt-in API behavior, and cleanup. |
-| [#3855](https://github.com/vllm-project/vllm-omni/pull/3855) | Stage runtime, thread safety, startup, and compatibility. |
-
-Historical comments calibrate delivery; they do not create merge policy. Live
-code, tests, repository docs, and the current `CODEOWNERS` file remain
-authoritative. When refreshing this study, promote a practice only when it
-recurs across at least three PRs or is supported by current repository guidance.
-
-## Recurring review behavior
-
-- Start from a changed contract, not a style preference. State the exact
-  request, configuration, topology, or failure path that triggers the issue.
-- Protect repository boundaries. Keep model-specific behavior in its domain,
-  move genuinely reusable logic to a shared module, and reuse existing loaders,
-  protocols, definitions, and config sources instead of bypassing them.
-- Challenge unrelated scope and abstractions. Ask why a new flag, config, class,
-  helper, fallback, or file is needed when an existing path appears sufficient.
-- Trace concurrency and terminal paths: overlapping requests, disconnect,
-  cancellation, partial failure, stale replies, collective schedule mismatch,
-  cleanup, and retry. Prefer an explicit startup error for unsupported
-  combinations over silently running with incomplete state or wrong weights.
-- Preserve user-visible behavior across variants. An accepted CLI/API/config
-  field must be applied, explicitly rejected, or visibly warned about; compare
-  normal and headless, offline and online, and streaming and non-streaming paths.
-- Ask for evidence at the affected boundary: a regression test using the real
-  tensor or protocol shape, correct pytest markers so CI runs it, comparable A/B
-  performance results, or an SLO-oriented latency/quality measurement.
-- Keep interfaces explicit: avoid `Any` and opaque strings where a precise
-  union, enum, or typed envelope exists; remove dead code and duplicated
-  constants; validate requests before expensive execution.
-- Document module scope and non-obvious invariants. Update examples, recipes,
-  supported-model/feature docs, and hardware assumptions when users rely on
-  them.
-- When expertise crosses an ownership boundary, ask a named owner to inspect a
-  specific file or contract and explain why. Do not send a generic `PTAL` list.
-- Keep non-blocking cleanup in a linked follow-up only after the current PR is
-  safe. If a revision fixes only part of a failure chain, continue the existing
-  thread with the remaining trigger instead of opening a duplicate finding.
-
-## Write the finding
-
-- Lead with the issue or decisive question; omit a review preamble.
-- Name the concrete trigger and impact, then the smallest fix direction.
-- Keep obvious fixes to one sentence. Use more detail only when the call path or
-  ownership boundary is otherwise unclear.
-- Prefer one root-cause comment over repeated symptom comments.
-- Hedge only when evidence is genuinely incomplete; mark that item as a
-  question or validation gap rather than overstating severity.
-- Say briefly that no findings were found when the review is clean; zero
-  comments is a valid outcome when posting is authorized.
-
-Useful forms:
-
-```text
-This leaves <state> allocated when <failure/cancellation path>. Release it in
-the shared terminal cleanup path.
-```
-
-```text
-Does this producer also update <consumer>? It still reads the old field here.
-```
-
-```text
-With <configuration>, this bypasses <existing loader/validator>, so <impact>.
-Reuse that path or reject this combination before startup.
-```
-
-```text
-@<owner>, could you check <specific boundary>? This changes <contract> used by
-<consumer>.
-```
-
-Use a priority label only for a proved high-impact defect. Avoid generic praise,
-routine “Nit:” prefixes, decorative severity labels, audit templates, rule IDs,
-comment-count narration, and “I left a few comments.” Keep approvals, review
-events, reviewer requests, mentions, and GitHub replies subject to the user's
-explicit authorization.

.claude/skills/review-pr/references/delivery/review-requests.md

@@ -1,99 +0,0 @@
-# Focused Code-Owner Review Requests
-
-Read only when the user asks to identify, suggest, request, add, or ping
-reviewers. Finding candidates is read-only; GitHub review requests and
-`@mention` comments are external writes.
-
-Owner sources, in order:
-
-1. the reviewed head's
-   [CODEOWNERS](https://github.com/vllm-project/vllm-omni/blob/main/.github/CODEOWNERS)
-   for path ownership;
-2. the active module design page's `owners` and `required_reviewers` metadata
-   for contract ownership and mandatory design review; and
-3. documented
-   [governance expertise](https://docs.vllm.ai/projects/vllm-omni/en/latest/community/governance/)
-   for specialization and tie-breaking.
-
-Resolve all three from the reviewed head when available because ownership
-changes over time. Use published docs only to discover a page absent from an
-older checkout, never to override the frozen head, and do not copy a static
-owner list into review output. CODEOWNERS remains the path authority; module
-metadata identifies contract experts and required design reviewers.
-
-## Rank candidates
-
-1. Freeze the PR head and collect changed files, author, requested reviewers,
-   submitted reviews, and existing comments.
-2. Resolve the **last matching CODEOWNERS rule** for each changed file. Do not
-   union an earlier broad rule with a later specific rule.
-3. Resolve the primary module and feature overlays through
-   [design-contracts.md](../process/design-contracts.md). Read the active module
-   page's status, `owners`, and `required_reviewers`; do not treat owners on an
-   archived, superseded, or unrelated page as current authority.
-4. Group files by the selected primary owner and the exact module or feature
-   contract needing review. Weight production owners and live consumers above
-   tests/docs/CI owners and the repository-wide fallback. Include an applicable
-   `required_reviewers` entry even when it is not the path owner, and label why.
-5. Use documented governance specialties only to choose among matching owners:
-   for example serving versus configuration, diffusion model versus cache or
-   parallelism, TTS versus generic model execution, or CI versus tests.
-6. Exclude the PR author, bots, users who already completed the needed review,
-   and duplicate pending requests. Do not infer availability or invent
-   expertise from a username.
-7. Select one reviewer for a single-owner change and at most three for a real
-   cross-module change. If more are plausible, rank them but do not ping a
-   broad group; ask the user before exceeding three.
-
-If every specific owner is excluded, consider one repository-wide fallback
-owner and label that choice as a fallback rather than a path match. Never fan
-out to the full fallback list. Prefer a qualified owner who covers multiple
-critical path groups over separate reviewers for each file. If CODEOWNERS is
-missing or invalid, state that gap and use governance only as a labeled fallback.
-
-Recent file history may break a tie only when CODEOWNERS and governance remain
-ambiguous. Never use commit count alone to override an explicit current owner.
-
-## Preview before writing
-
-Show the user the exact candidate set and rationale:
-
-```text
-@owner — <owned paths or module role>; please verify <specific module or feature contract>.
-```
-
-Draft one consolidated comment tied to the frozen head:
-
-```text
-Requesting focused review for `<short-head-sha>`:
-
-- @owner1: could you check the <module contract> in `<path/group>`?
-- @owner2: could you check the <feature or cross-boundary contract> in `<path/group>`?
-
-Relevant validation: <one concise result or exact remaining gap>.
-```
-
-Mention only owners being requested. Keep the reason specific enough that each
-person knows what decision or invariant needs attention; do not post a generic
-“please review” or a generated ownership audit.
-
-## External-write gate
-
-- “Who should review?”, “suggest reviewers”, or “draft a request” authorizes
-  only the preview.
-- “Request/add these reviewers” authorizes the GitHub review-request mutation.
-- “Ping/comment/tag the owners” authorizes the consolidated comment.
-- When the user explicitly asks to request reviews **with an owner comment**,
-  both writes are authorized. Obey narrower wording when only one action is
-  requested.
-
-Immediately before an authorized write, verify the PR is still open, the head
-SHA is unchanged, and the candidate is not the author or already satisfied.
-Report draft/WIP state and avoid notifications unless the user explicitly wants
-reviewers requested before ready-for-review.
-
-Use the GitHub connector for reviewer requests and the single top-level comment;
-use `gh` only when connector coverage is unavailable. Do not submit an approval,
-request-changes event, label, assignment, or multiple comments as part of this
-action. After writing, reread the PR and report the reviewers requested and the
-comment URL. If the head changed, discard the draft and rerank before posting.

.claude/skills/review-pr/references/features/communication.md

@@ -1,24 +0,0 @@
-# Communication Features
-
-Use with the OmniConnector, stage-runtime, configuration, and I/O module
-contracts. Load the concrete backend design from the reviewed head:
-
-| Backend | Design |
-| --- | --- |
-| Mooncake store | [MooncakeStoreConnector](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/omni_connectors/mooncake_store_connector/) |
-| Mooncake transfer engine | [MooncakeTransferEngineConnector](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/omni_connectors/mooncake_transfer_engine_connector/) |
-| Mori transfer engine | [MoriTransferEngineConnector](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/omni_connectors/mori_transfer_engine_connector/) |
-| Shared memory | [SharedMemoryConnector](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/omni_connectors/shared_memory_connector/) |
-| Yuanrong store | [YuanrongConnector](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/omni_connectors/yuanrong_connector/) |
-| Yuanrong transfer engine | [YuanrongTransferEngineConnector](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/omni_connectors/yuanrong_transfer_engine_connector/) |
-
-## Feature checks
-
-- Verify dependency, service, device/network, port, memory-pool, and environment
-  prerequisites with actionable startup errors.
-- Match key/metadata construction, sender and receiver roles, allocation,
-  ownership, completion, and supported fast/serialized paths.
-- Exercise timeout, retry, stale sender/buffer reclamation, partial transfer,
-  cancellation, and connector close semantics.
-- Validate the smallest supported same-host or cross-node topology and document
-  backend limitations and operational diagnostics.

.claude/skills/review-pr/references/features/diffusion-acceleration.md

@@ -1,26 +0,0 @@
-# Diffusion Acceleration Features
-
-Use with the exact diffusion submodule plus platform, cache, quantization, or
-benchmarking contracts selected by the live path.
-
-| Feature family | Designs |
-| --- | --- |
-| Parallelism | [CFG](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/cfg_parallel/), [Expert](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/expert_parallel/), [HSDP](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/hsdp/), [Pipeline](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/pipeline_parallel/), [Sequence](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/sequence_parallel/), [Tensor](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/tensor_parallel/), [VAE patch](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/vae_parallel/) |
-| Attention | [Skip-Softmax](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/skip_softmax/) |
-| Quantization | [Quantization](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/quantization/) |
-| Cache | [Cache-DiT](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/cache_dit/), [TeaCache](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/teacache/) |
-| Batching | [Diffusion Continuous Batching](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/diffusion_continuous_batching/) |
-| Offload | [Distributed Layerwise Offload](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/distributed_layerwise_offload/) |
-
-## Feature checks
-
-- Verify feature selection, supported models/platforms/topologies, defaults,
-  dependencies, and every touched feature combination.
-- Preserve feature-off and single-rank correctness; reject unsupported
-  combinations before collectives, loading, or execution begin.
-- Trace shapes, shards, ranks, collectives, precision, cache validity, residency,
-  and per-request state through the selected runtime hooks.
-- Compare output quality or accuracy against the disabled/reference path before
-  accepting latency or memory improvements.
-- Require exact commands, topology, environment, warmup, repetitions, and
-  measurements for performance claims; update feature compatibility docs.

.claude/skills/review-pr/references/features/infrastructure-performance.md

@@ -1,22 +0,0 @@
-# Infrastructure and Performance Features
-
-Load the matching design from the reviewed head:
-
-- [Prometheus Metrics](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/metrics/)
-  for logger wrapping, gating, lifecycle, stage transfer, and metric definitions.
-- [Speech Generation Performance Optimizations](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/qwen3_omni_tts_performance_optimization/)
-  for stage batching, CUDA graphs, async chunk, streaming, re-prefill, compile,
-  and deployment evidence.
-
-## Feature checks
-
-- Route instrumentation changes through observability or profiling and result
-  methodology through benchmarking and the performance evidence check.
-- Preserve opt-in/default behavior, units, labels, aggregation, timing scope,
-  lifecycle resets, and bounded overhead.
-- For stacked optimizations, measure each increment against the same baseline
-  and explain interactions, quality guards, regressions, and limitations.
-- Require exact model, checkpoint, hardware, software, workload, topology,
-  concurrency, warmup, repetitions, and production commands.
-- Update the design page when metric meaning, supported optimization stack, or
-  deployment guidance changes.

.claude/skills/review-pr/references/features/runtime-stage-execution.md

@@ -1,24 +0,0 @@
-# Runtime and Stage Execution Features
-
-Load the matching design from the reviewed head:
-
-| Feature | Design | Primary module intersections |
-| --- | --- | --- |
-| Disaggregated inference | [Design](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/disaggregated_inference/) | Configuration, stage runtime, OmniConnector, I/O contracts |
-| Async chunk | [Design](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/async_chunk/) | Model integration, orchestration, stage runtime, connector, I/O |
-| Async diffusion output | [Design](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/async_diffusion_output/) | Diffusion runtime, I/O contracts, entrypoints |
-| Async Omni output materialization | [Design](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/omni_async_output_materialization/) | AR runtime, model integration, I/O contracts, orchestration |
-| Automatic prefix caching | [Design](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/feature/prefix_caching/) | AR runtime, cache management, I/O contracts |
-
-## Feature checks
-
-- Confirm the feature's supported models, entrypoints, stage types, topology,
-  configuration, default, and compatibility limitations.
-- Trace enablement from public/config ingress through every participating module
-  and verify the advertised production dispatch actually selects it.
-- Preserve a correct disabled or fallback path and make unsupported combinations
-  fail or warn as documented.
-- Test overlap, ordering, identity, backpressure, cancellation, failure, final
-  partial output, and cleanup at each asynchronous boundary.
-- Update the feature page, support matrices, examples, and recipes when behavior
-  or coverage changes.

.claude/skills/review-pr/references/modules/ar-runtime.md

@@ -1,22 +0,0 @@
-# Autoregressive Runtime
-
-Primary design: [Autoregressive Runtime](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/ar_runtime/).
-
-Use for AR request queues, scheduling state, token and memory budgets, KV/input
-readiness, workers, runners, and upstream vLLM request/cache transitions.
-
-## Contract checks
-
-- Preserve upstream request-state, scheduling, cache, and preemption semantics
-  unless an Omni-specific difference is documented and tested.
-- Convert modality-specific data through explicit input or output adapters; do
-  not inject it through unrelated scheduler state.
-- Keep workers and model runners focused on assigned execution rather than
-  admission or cross-stage routing.
-- Synchronize token, sequence, batch, and memory budgets with worker-visible
-  state and prevent starvation, double counting, or stale readiness.
-- Preserve legal transitions and one terminal cleanup path across completion,
-  abort, timeout, preemption, worker failure, and shutdown.
-
-Test request lifecycle, scheduling decisions, abort, cache state, adapters, and
-every affected worker execution mode against the pinned upstream contract.

.claude/skills/review-pr/references/modules/benchmarking.md

@@ -1,24 +0,0 @@
-# Benchmarking
-
-Primary design: [Benchmarking](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/benchmarking/).
-
-Use when benchmark code, workloads, metric calculations, CLI benchmark
-entrypoints, or result metadata change. Use the performance check separately
-when a PR uses benchmark results as evidence.
-
-## Contract checks
-
-- Record model and revision, code SHA, hardware, software, configuration,
-  workload, precision, topology, concurrency, warmup, repetitions, and
-  measurement window.
-- Validate successful and semantically acceptable outputs before accepting
-  timing, memory, or scaling results.
-- Define every metric's unit, population, aggregation, synchronization, and
-  timing scope.
-- Keep workload parsing and metric computation deterministic and reusable
-  across base and head.
-- Reject comparisons that change material workload or runtime settings without
-  isolating and explaining that difference.
-
-Test workload parsing and metric calculations with deterministic fixtures and
-publish exact commands plus variability for quantitative claims.

.claude/skills/review-pr/references/modules/cache-management.md

@@ -1,22 +0,0 @@
-# Cache Management
-
-Primary design: [Cache Management](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/cache_management/).
-
-Use for AR or diffusion cache identity, reusable state, validity, lifecycle,
-reset, eviction, and teardown.
-
-## Contract checks
-
-- Include every model, request, input, timestep, precision, device, topology,
-  and feature property that can change a reused value in cache identity.
-- Preserve a correct disabled and miss path; never reuse after validity inputs
-  change.
-- Isolate request-scoped state across concurrent requests and define ownership
-  for model-scoped state.
-- Make reset, invalidation, eviction, capacity, and teardown explicit on
-  completion, cancellation, failure, model reload, and shutdown.
-- Keep cache optimizations behind the owning runtime's hooks rather than adding
-  a second request lifecycle.
-
-Test hit, miss, invalidation, disabled behavior, concurrency, capacity, reset,
-and teardown, with quality comparison when reuse is approximate.

.claude/skills/review-pr/references/modules/configuration.md

@@ -1,24 +0,0 @@
-# vLLM-Omni Configuration
-
-Primary design: [vLLM-Omni Configuration](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/vllm_omni_config/).
-
-Use for config construction, deploy YAML, registries, schema, defaults,
-aliases, CLI projection, stage config, and topology. Inspect the reviewed
-page's status: while its contract remains deferred or draft, current code and
-tests—not proposed precedence rules—are authoritative.
-
-## Contract checks
-
-- Resolve each supported structured, legacy, CLI, environment, default, alias,
-  and stage-override producer through its actual runtime consumer.
-- Reject unknown or owner-mismatched fields explicitly; keep process-local
-  runtime objects out of transportable configuration.
-- Verify default, explicit, and feature-off values reach every live factory and
-  consumer without silent reinterpretation.
-- Treat stage count, placement, connector, parallelism, device, and memory
-  fields as one topology contract and reject impossible combinations early.
-- Preserve supported construction-path parity until a documented migration
-  removes a path.
-
-Require normalization and schema tests, a live-consumer assertion, and docs for
-public keys, defaults, constraints, precedence, or migration behavior.

.claude/skills/review-pr/references/modules/diffusion.md

@@ -1,33 +0,0 @@
-# Diffusion Module Family
-
-Primary design: [Diffusion Modules](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/diffusion/).
-
-Use for diffusion-stage behavior, then load the exact submodule page from the
-reviewed head:
-
-| Submodule | Signals | Design |
-| --- | --- | --- |
-| Runtime | Admission, scheduling, execution, progress, outputs, cancellation, hooks, cleanup | [Diffusion Runtime](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/diffusion/diffusion_runtime/) |
-| Model Integration | Pipelines, registry, loader, adapters, shared layers, model-specific processing | [Diffusion Model Integration](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/diffusion/diffusion_model_integration/) |
-| Continuous Batching | Compatibility, request/step batches, per-request progress, capacity | [Continuous Batching](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/diffusion/continuous_batching/) |
-| Parallelism | Rank topology, process groups, sharding, collectives, distributed execution | [Parallelism](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/diffusion/parallelism/) |
-| Offloader | Residency, transfers, memory accounting, prefetch, teardown | [Offloader](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/diffusion/offloader/) |
-
-## Family-wide checks
-
-- Keep one scheduler-owned lifecycle from admission through completion,
-  cancellation, failure, and cleanup; optional features must use defined hooks.
-- Select pipelines through registry and loader contracts instead of scattered
-  model-name conditionals; keep genuine model differences in model directories.
-- Trace latent, conditioning, timestep, generator, shape, layout, dtype, device,
-  batch expansion, and output conversion through the actual consumer.
-- Make batch compatibility and per-request isolation explicit; never associate
-  output by unstable batch position.
-- Derive topology from validated configuration, define every sharding boundary,
-  keep collectives symmetric, and preserve a supported single-rank path.
-- Track one residency owner per offloaded component, wait for transfer readiness,
-  preserve model state, bound retained copies, and clean up deterministically.
-
-Load matching feature designs for cache, quantization, parallelism, continuous
-batching, or offload. Require feature-off correctness, representative inference,
-terminal-path tests, and quality evidence for optimizations.

.claude/skills/review-pr/references/modules/engine-orchestration.md

@@ -1,23 +0,0 @@
-# Engine Orchestration
-
-Primary design: [Engine Orchestration](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/engine_orchestration/).
-
-Use for request-state creation, cross-stage routing, output ordering, companion
-tracking, RPC correlation, cancellation propagation, and terminal convergence.
-Orchestration does not own replica placement, stage-process startup, public
-rendering, connector transport, or payload and error schemas.
-
-## Contract checks
-
-- Keep one owner for cross-stage routing; entrypoints, models, and stage clients
-  must not independently select the next logical stage.
-- Preserve request identity and output order across concurrent stages and
-  correlate every control or RPC result to the originating request and wave.
-- Make terminal state monotonic: no new forwarding after success, abort,
-  request failure, or fatal engine failure.
-- Propagate cancellation and failure to every active stage and release
-  orchestrator-owned tasks, queues, companions, and request state.
-- Preserve shutdown ordering across the orchestrator and stage runtime.
-
-Test representative multi-stage routing, ordering, correlation, cancellation,
-failure, and repeated shutdown.

.claude/skills/review-pr/references/modules/entrypoints.md

@@ -1,25 +0,0 @@
-# Entrypoints and Serving Boundaries
-
-Primary design: [Entrypoints and Serving Boundaries](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/entrypoints/).
-
-Use for offline APIs, CLI and server composition, OpenAI-compatible routes,
-request validation, response conversion, streaming, sessions, and engine
-handoff. Entrypoints adapt public contracts; they do not own cross-stage
-routing, stage lifecycle, configuration precedence, payload schemas, or error
-classification.
-
-## Contract checks
-
-- Normalize and validate public values once before engine submission.
-- Preserve request identity, modality, ordering, and exactly one terminal event
-  across streaming, disconnect, cancellation, and failure.
-- Translate internal outputs and errors explicitly for each advertised offline,
-  HTTP, SSE, WebSocket, or asynchronous-job path.
-- Keep model-specific behavior behind a common adapter or processor instead of
-  adding model-name policy to generic entrypoints.
-- Require API or CLI changes to explain necessity, alternatives, compatibility,
-  migration, and the supported route or transport matrix.
-
-Test the affected public protocol, normalization, engine handoff, rendering,
-and terminal outcomes. Route orchestration, I/O schema, and semantic error
-changes to their module contracts.

.claude/skills/review-pr/references/modules/error-contracts.md

@@ -1,24 +0,0 @@
-# Error Classification, Propagation, and Rendering
-
-Primary design: [Error Classification, Propagation, and Rendering](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/error_contracts/).
-
-Use when a change classifies failures, crosses process boundaries, decides
-fatal versus request-scoped impact, sanitizes context, or renders offline,
-HTTP, SSE, WebSocket, or asynchronous-job errors. The I/O module owns the wire
-schema; this module owns the meaning of its error fields.
-
-## Contract checks
-
-- Keep request-scoped failure isolated unless the underlying engine is no
-  longer usable.
-- Preserve stable classification and request context across process and
-  protocol boundaries without exposing prompts, outputs, secrets, or internal
-  stack details.
-- Keep cancellation distinguishable from internal failure.
-- Terminate each public transport exactly once with consistent status, body,
-  event, finish reason, and metrics classification.
-- Maintain compatibility across mixed or older producers only when the
-  reviewed contract defines that behavior.
-
-Test table-driven classification, wire round trips, fatal/request-scoped
-propagation, cancellation, sanitization, and every affected public renderer.

.claude/skills/review-pr/references/modules/execution-platforms.md

@@ -1,23 +0,0 @@
-# Execution Platforms
-
-Primary design: [Execution Platforms](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/execution_platforms/).
-
-Use for hardware capability detection, worker selection, patches, kernels,
-attention backends, and vendor-specific configuration or connectors.
-
-## Contract checks
-
-- Guard hardware behavior through platform selection or capability detection
-  and fail clearly when unsupported.
-- Keep portable modules free of direct vendor imports when a common selector
-  exists; verify portable imports without the target accelerator.
-- Override only behavior that differs from common or upstream implementations,
-  and compare sibling worker hooks when inheritance does not provide parity.
-- Preserve dtype, layout, rank, stream, synchronization, workspace,
-  graph-capture, and resource-lifetime contracts.
-- Do not let simplified CPU doubles hide platform MRO, initialization, or
-  dispatch failures.
-
-Run portable checks first, then the smallest matching-device test in a fresh
-environment. Report unavailable hardware as a validation gap, never simulated
-device evidence.

.claude/skills/review-pr/references/modules/input-output-modality.md

@@ -1,23 +0,0 @@
-# Input, Output, and Modality Contracts
-
-Primary design: [Input, Output, and Modality Contracts](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/input_output_modality_contracts/).
-
-Use for requests, prompt and modality types, message schemas, serialization,
-output types, accumulation, completion, and compatibility shims crossing
-entrypoint, orchestration, stage, connector, or model boundaries.
-
-## Contract checks
-
-- Give every boundary value an explicit modality and validated typed schema.
-- Preserve request and stage identity across conversion, serialization,
-  streaming updates, batching, cancellation, and errors.
-- Distinguish partial, final, empty, and failed output states for every modality.
-- Verify producer and consumer agreement on shape, layout, dtype, device,
-  ownership, metadata, ordering, and optional or unknown fields.
-- Keep internal objects out of public protocols; translate them at the owning
-  entrypoint.
-- Preserve wire compatibility deliberately and give deprecated shims a bounded
-  migration path.
-
-Require construction, round-trip, accumulation, completion, rejection, and
-compatibility tests at each changed producer-consumer boundary.

.claude/skills/review-pr/references/modules/model-integration.md

@@ -1,25 +0,0 @@
-# Model Integration
-
-Primary design: [Model Integration](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/model_integration/).
-
-Use for model registration, configuration adapters, preprocessing, checkpoint
-loading, stage inputs, model-specific hooks, shared layers, runners, and model
-execution. Use the diffusion family reference for diffusion models.
-
-## Contract checks
-
-- Declare explicitly how the model class, loader, input processor, stage
-  configuration, and runtime capabilities are selected.
-- Preserve weight-name mapping, dtype/device placement, optional-dependency
-  errors, and checkpoint-specific loading semantics.
-- Trace each typed input and output through preprocessing, runner state, model
-  call, and its actual consumer.
-- Reuse upstream vLLM behavior when sufficient; document and test the precise
-  difference for every override or patch.
-- Keep model code out of admission, cross-stage routing, public policy, and
-  terminal lifecycle ownership.
-- Place reusable behavior in shared modules and test it with more than one
-  integration.
-
-Require focused registry, loader, processor, runner, and representative model
-execution tests. Apply the model-addition check for new or expanded support.

.claude/skills/review-pr/references/modules/observability.md

@@ -1,21 +0,0 @@
-# Observability
-
-Primary design: [Observability](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/observability/).
-
-Use for metrics, logs, correlation fields, and cross-stage request visibility.
-
-## Contract checks
-
-- Preserve stable request and stage identity across entrypoints, orchestration,
-  stages, workers, errors, and terminal cleanup.
-- Treat metric names, units, labels, aggregation, and lifecycle as public
-  contracts; document any semantic change.
-- Keep labels bounded: never use request IDs, prompts, outputs, paths, or other
-  unbounded user values.
-- Register and reset metrics exactly once across repeated startup and shutdown,
-  and keep disabled instrumentation inexpensive.
-- Align emitted values with their actual timing and lifecycle owner rather than
-  reconstructing them from ambiguous client strings.
-
-Test registration, label sets, units, resets, error classification, and
-representative multi-stage emission.

.claude/skills/review-pr/references/modules/omni-connector.md

@@ -1,24 +0,0 @@
-# OmniConnector
-
-Primary design: [OmniConnector](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/omni_connector/).
-
-Use for connector contracts and model-agnostic data transfer across stages,
-processes, devices, or nodes. Connector implementations transport and
-synchronize data; they do not choose the next stage or implement model policy.
-
-## Contract checks
-
-- Prove producer and consumer agreement on request/stage identity, shape,
-  layout, dtype, placement, ownership, ordering, and completion.
-- Keep backend selection and metadata/key construction explicit; do not silently
-  reinterpret or drop payloads across SHM, store, network, or vendor paths.
-- Bound connect, put/get, retry, synchronization, and readiness waits with
-  backpressure, cancellation, and actionable errors.
-- Prevent route, endpoint, port, key, and buffer collisions across repeated
-  startup, concurrent requests, and replica replacement.
-- Release connections, handles, buffers, listener work, and stale sender state
-  on success, cancellation, failure, and shutdown.
-
-Load the matching communication feature design for a concrete backend. Require
-focused producer-consumer tests and the smallest runnable multi-process or
-multi-node path.

.claude/skills/review-pr/references/modules/profiling.md

@@ -1,21 +0,0 @@
-# Profiling
-
-Primary design: [Profiling](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/profiling/).
-
-Use for opt-in instrumentation and trace collection across supported profiler
-backends.
-
-## Contract checks
-
-- Keep expensive collection disabled by default and bounded by explicit start,
-  stop, timeout, and cleanup behavior.
-- Preserve scheduling, generated outputs, resource ownership, and concurrency
-  semantics apart from documented synchronization overhead.
-- Include stage, rank, worker, operation, and request correlation where useful
-  without embedding user payloads or secrets.
-- Make repeated start/stop and partial failure safe, including multi-rank trace
-  naming and artifact ownership.
-- Measure disabled and enabled overhead before making performance claims.
-
-Test the disabled path, repeated lifecycle, failure cleanup, trace context, and
-each affected backend.

.claude/skills/review-pr/references/modules/quantization.md

@@ -1,22 +0,0 @@
-# Quantization
-
-Primary design: [Quantization](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/quantization/).
-
-Use for method registration, checkpoint interpretation, layer replacement,
-reduced precision, platform capability, and runtime constraints.
-
-## Contract checks
-
-- Validate checkpoint metadata, selected method, supported layers, device
-  capability, required dependencies, and parallel layout before loading.
-- Preserve loader and weight-name mapping semantics, dtype, scale/granularity,
-  zero point, padding, and buffer handling through the real kernel consumer.
-- Fail clearly for unsupported combinations; do not silently choose a different
-  method or precision.
-- Keep online and pre-quantized checkpoint paths explicit and ensure patches or
-  fallbacks do not bypass model-owned loaders.
-- Require numerical comparison against a defined reference with explicit
-  tolerance before treating performance results as valid.
-
-Test registration, loading, representative layers, metadata, platform guards,
-parallel combinations, and numerical correctness separately from performance.

.claude/skills/review-pr/references/modules/stage-runtime.md

@@ -1,23 +0,0 @@
-# Stage Runtime and Replica Lifecycle
-
-Primary design: [Stage Runtime and Replica Lifecycle](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/module/stage_runtime/).
-
-Use for local or distributed placement, startup, readiness, stage pools,
-replica identity and membership, selection, affinity, liveness, draining, and
-stage-client or process lifecycle. Cross-stage request policy belongs to engine
-orchestration; model scheduling belongs to the owning runtime.
-
-## Contract checks
-
-- Acquire, replace, and retire replicas through one stage-runtime lifecycle.
-- Preserve stable replica identity and request affinity until termination or a
-  declared replica loss.
-- Make readiness explicit before admission; surface partial-startup and
-  membership failures without leaving half-initialized capacity.
-- Keep local and distributed semantics aligned for supported modes.
-- Make drain, shutdown, and cleanup idempotent across repeated signals and
-  process failure.
-
-Test startup, readiness, selection, affinity, membership changes, abort,
-process loss, draining, and repeated shutdown on affected local/distributed
-paths.

.claude/skills/review-pr/references/process/design-contracts.md

@@ -1,34 +0,0 @@
-# Resolve Design Contracts
-
-Use after freezing the review head and before selecting module or feature
-references. The maintained [design index](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/)
-defines two routing axes:
-
-- **Module designs** own code boundaries and invariants. Select one primary
-  module and a second only when the live producer-consumer path crosses it.
-- **Feature designs** describe behavior spanning modules. Load every feature
-  page whose implementation, default, support, or contract changes.
-
-## Resolution order
-
-1. Open `docs/design/index.md` in the reviewed head, not the reviewer's checkout
-   or published latest tree.
-2. Match changed behavior against each module page's `primary_code_paths`,
-   `primary_path_exceptions`, ownership boundary, and `depends_on` metadata.
-3. Read `status`, `architecture_state`, `last_verified_commit`, and any linked
-   in-flight work before treating prose as current behavior.
-4. Use current code and tests when a page is draft, deferred, stale, absent, or
-   conflicts with the frozen implementation. Report material documentation
-   drift separately.
-5. Treat candidate invariants and promotion gates as review questions until
-   repository policy, current code/tests, or owner-approved normative text
-   makes them enforceable. Do not turn a draft identifier into an automatic
-   blocker.
-6. Use published latest docs only for discovery when the reviewed head lacks a
-   page; never import a newer contract into an older branch silently.
-
-When behavior changes an active module or feature contract, require the same PR
-to update that page. Require a new page only when repository policy, an accepted
-RFC/issue, or explicit maintainer acceptance criteria do so; otherwise treat it
-as a non-blocking design suggestion. Do not demand a second page when an existing
-design already owns the exact contract.

.claude/skills/review-pr/references/process/general-checks.md

@@ -1,129 +0,0 @@
-# General Review Checks
-
-Apply these checks to every PR after freezing the review surface. A pattern is
-not a finding until the diff introduces or exposes a reachable trigger, impact,
-and smallest safe fix. Do not report unrelated backlog.
-
-Official docs: [contributing guide](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/)
-[feature compatibility](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/feature_compatibility/),
-and [design documents](https://docs.vllm.ai/projects/vllm-omni/en/latest/design/).
-
-## Contract and scope
-
-- Match the title/body claims to every changed production path, test, config,
-  dependency, generated artifact, and user-visible document.
-- Trace each changed value through public ingress, validation/defaulting,
-  producer, transformations, process or device boundaries, final consumer, and
-  terminal cleanup.
-- Check every applicable sync/async, offline/online, streaming/non-streaming,
-  feature-off, topology, and compatibility path without demanding unsupported
-  modes merely for symmetry.
-
-## Module, API, and class design
-
-Apply these rules to new or materially changed production code; do not require
-unrelated cleanup from untouched files.
-
-1. Start each source module with a concise module docstring that defines its
-   responsibility and boundaries and identifies its primary classes and key
-   functions. Place it after any required license header and before imports.
-2. Give every added or materially changed class and function a clear docstring
-   covering its responsibility, parameters, return value, raised exceptions,
-   and non-obvious invariants. Use explicit typed parameters at owned API
-   boundaries; avoid opaque `**kwargs` and `Any`. Allow them only when an
-   upstream or compatibility interface requires them, and document and validate
-   the accepted keys and concrete types.
-3. Move stable helpers shared by multiple features into an appropriately scoped
-   utility module. Do not let feature modules accumulate large collections of
-   unrelated private utility functions; keep a private helper local only when
-   it is single-purpose and tightly coupled to that feature.
-4. Keep every method on a key class within that class's stated responsibility,
-   and document non-obvious design decisions and invariants. Before adding a
-   method, prefer reuse, consolidation, or extension of an existing abstraction;
-   split the class when new behavior creates a separate responsibility or makes
-   the class unnecessarily long.
-5. Require changes to user-facing behavior to update `docs/`. When an existing
-   active module or feature design page owns the changed contract, update that
-   page. Require a new design page only when the reviewed branch's repository
-   policy, an accepted RFC/issue, or explicit maintainer acceptance criteria do
-   so; otherwise suggest it as non-blocking. For a major architectural change,
-   apply the branch's contributing policy for a design RFC or issue; the current
-   policy uses more than 500 changed production-code lines, excluding kernel,
-   data, config, and test changes. Resolve page status and authority through
-   [design-contracts.md](design-contracts.md), and do not demand a duplicate page
-   when an existing design owns the exact contract. When required, cover scope,
-   data flow, public contracts, failure behavior, alternatives, validation,
-   limitations, and rollout.
-6. Require every performance PR to provide reproducible base-versus-head A/B
-   results under the same hardware, software, model, workload, precision,
-   topology, warmup, repetitions, and measurement scope. Include exact commands,
-   variability, and a correctness or quality guard; one-sided or non-comparable
-   numbers are incomplete evidence. For a new model absent from the frozen base,
-   compare head with its pinned canonical reference implementation under rule 12
-   instead. Follow
-   [perf-verification.md](../checks/perf-verification.md) for the full protocol.
-7. Require every addition, removal, default change, or semantic change to a
-   user-facing inference API or CLI to explain why it is necessary, which
-   alternatives were considered, and why the chosen interface is preferable.
-   Record compatibility, deprecation or migration behavior, and the rationale
-   in the PR. Update the corresponding module and feature design documents when
-   they define the changed interface or workflow, or when policy requires one.
-8. Require every bug-fix PR to add an automated regression test that reproduces
-   the defect on the frozen base and passes on the fixed head. Exercise the
-   production path or nearest stable boundary and assert the corrected behavior,
-   not only process survival. Record the exact base/head command and result, and
-   place hardware- or model-specific coverage in the correct CI lane. A manual
-   reproduction supplements but does not replace the regression test.
-9. Require every new or materially changed recipe to follow
-   [`recipes/TEMPLATE.md`](../../../../../recipes/TEMPLATE.md) and the naming and
-   layout conventions in
-   [`recipes/README.md`](../../../../../recipes/README.md).
-   Complete every applicable summary, use-case, reference, hardware,
-   environment, exact-command, verification, and notes section with tested,
-   reproducible details; explain any intentional deviation in the PR.
-10. Require every new model to verify its supported modalities, platforms,
-    execution modes, and features with production-path evidence. Update
-    `docs/models/supported_models.md` and every applicable feature support or
-    compatibility table; do not claim support that the PR does not validate.
-    Follow
-    [model-addition-checklist.md](../checks/model-addition-checklist.md) for the
-    model-specific documentation checks.
-11. Require every new model PR to add or update its in-repository model-family
-    recipe under `recipes/` and its `recipes/README.md` index entry. Apply rule
-    9, and keep the recipe's model identifiers, tasks, serving modes, hardware,
-    commands, supported features, and limitations aligned with validated PR
-    evidence. An external recipe link does not replace the in-repository recipe.
-12. Require every new model to compare accuracy or output quality and performance
-    against a pinned baseline or canonical reference implementation. Match the
-    checkpoint, inputs, precision, hardware, workload, and measurement method;
-    provide exact commands, results, and explanations for material differences.
-    Prefer a detailed timing split for each stage and explain when it is
-    unavailable. Follow
-    [model-addition-checklist.md](../checks/model-addition-checklist.md) and
-    [perf-verification.md](../checks/perf-verification.md) for the evidence
-    contract.
-
-## Blocking risk scan
-
-| Risk | Prove before reporting |
-| --- | --- |
-| Correctness | A live input reaches a wrong output, exception, silent drop, shape/dtype/device mismatch, or partially initialized state. |
-| Compatibility | A supported API, config key, default, serialization schema, model identifier, or caller breaks without validation, migration, or deprecation. |
-| Lifecycle | Allocation or startup lacks cleanup on partial failure, timeout, cancellation, shutdown, or repeated requests. |
-| Concurrency/distribution | Ordering, identity, rank, world size, completion, timeout, backpressure, or collective assumptions fail on a supported path. |
-| Cache/shared state | Identity omits a correctness-affecting input, or isolation, invalidation, disabled behavior, eviction, or cleanup is incomplete. |
-| Async behavior | Blocking I/O, sleep, a lock across `await`, or unnecessary serialization harms a reachable async path. |
-| Security/data handling | Secrets, user payloads, unsafe deserialization/eval/shell, unvalidated paths, or unbounded metric labels are reachable. |
-| Validation evidence | Tests bypass the production dispatcher, mock away the change, use unrealistic types/MRO, or cannot fail when the defect returns. |
-| User contract | User-visible model, feature, API, CLI, config, default, or compatibility behavior changes without accurate docs or examples. |
-
-Search bounded callers and sibling implementations before reporting dead code,
-duplication, or a missed consumer. Keep new abstractions only when they have a
-distinct live caller, invariant, or compatibility need.
-
-## Finding bar
-
-Anchor each finding to a changed `path:line`; name the trigger or call path,
-current behavior, impact, and smallest fix direction. Treat pending CI, missing
-hardware, or unsupported measurements as validation gaps unless the repository
-contract makes that evidence a merge requirement.

.claude/skills/review-pr/references/process/review-execution.md

@@ -1,191 +0,0 @@
-# Review Execution and Delivery
-
-Use this reference for every review. It defines snapshot collection, gates,
-validation records, delivery permissions, maintainer tone, and re-review.
-
-Official docs: [contributing guide](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/)
-and [CI failure triage](https://docs.vllm.ai/projects/vllm-omni/en/latest/contributing/ci/failures/).
-
-## Contents
-
-- [Freeze the review surface](#freeze-the-review-surface)
-- [Report status before analysis](#report-status-before-analysis)
-- [Apply review gates](#apply-review-gates)
-- [Run bounded validation](#run-bounded-validation)
-- [Deliver maintainer-style findings](#deliver-maintainer-style-findings)
-- [Re-review safely](#re-review-safely)
-
-## Freeze the review surface
-
-For a GitHub PR, read the base/head SHA before and after fetching metadata and
-the diff:
-
-```bash
-gh api "repos/vllm-project/vllm-omni/pulls/<PR>" \
-  --jq '{base_sha: .base.sha, head_sha: .head.sha}'
-REVIEW_FIELDS="number,url,title,body,isDraft,baseRefName,headRefName,mergeable,mergeStateStatus,statusCheckRollup,files"
-gh pr view <PR> --repo vllm-project/vllm-omni \
-  --json "${REVIEW_FIELDS}"
-gh pr diff <PR> --repo vllm-project/vllm-omni
-gh api "repos/vllm-project/vllm-omni/pulls/<PR>" \
-  --jq '{base_sha: .base.sha, head_sha: .head.sha}'
-```
-
-Discard the snapshot if either SHA changed. Do not mix comments or validation
-from different heads.
-
-After the SHAs stabilize, fetch and materialize a trusted `head_sha` in an
-isolated detached worktree. Run every source read, `rg` search, import, and test
-from that snapshot, not the caller's checkout. A detached worktree provides
-snapshot isolation, not a security boundary.
-
-Treat a fork head as untrusted unless the user and environment policy explicitly
-establish trust. Never run its imports, tests, builds, hooks, package setup, or
-repo-configurable linters/plugins on the reviewer host. Execute them only in a
-disposable sandbox or VM with no credentials or inherited secrets, no host agent
-or service sockets, minimal read-only host mounts, disabled or explicitly
-allowlisted network, resource/time limits, and destruction after the run. If
-that boundary is unavailable, limit the review to the remote diff, SHA-addressed
-reads such as `git show <head_sha>:<path>`, and existing CI evidence; report all
-executable validation as a gap.
-
-Before the first source read, record a pristine snapshot fingerprint outside
-the reviewed worktree. Include `HEAD`, the NUL-delimited index entries and blob
-IDs, and a NUL-safe manifest of every worktree entry except Git metadata,
-including tracked, untracked, and ignored paths with file type, mode, symlink
-target, and content hash. Before each validation group and delivery, recompute
-and byte-compare the fingerprint as well as asserting `HEAD == head_sha`. If a
-tool changes or creates any entry, discard affected evidence and recreate the
-snapshot before another group; do not rely on `HEAD` alone or clean an unknown
-worktree in place. If an exact snapshot cannot be created, use SHA-addressed
-reads and report filesystem-dependent validation as a gap.
-
-For a local branch/worktree, determine the target ref from the user, current PR,
-or configured upstream; never infer it from the branch name. Resolve the target
-once and include all task-owned worktree state:
-
-```bash
-git status --porcelain=v2 -z
-git rev-parse HEAD
-git rev-parse <target-ref>
-git merge-base <target-base-sha> HEAD
-git diff --stat <comparison-commit>
-git diff --name-status <comparison-commit>
-git diff --binary <comparison-commit>
-git diff --cached --binary <comparison-commit>
-git diff --binary
-git ls-files --others --exclude-standard -z
-```
-
-Freeze the exact bytes of every in-scope untracked file from the NUL-delimited
-list, plus a NUL-safe path, file-type, mode, and content-hash manifest. Also
-fingerprint `HEAD`, the target and merge base, porcelain status, and both binary
-index and worktree patches. Recording only untracked names is insufficient.
-Keep these snapshots in the evidence packet and do not mutate the reviewed
-checkout during a read-only review.
-
-For local changes without PR metadata, mark the title/body as synthetic. Base
-them on the user request and commit messages without inventing validation claims.
-
-If no PR, branch, or usable worktree is identifiable, ask for a PR URL/number or
-explicit base and head rather than guessing.
-
-## Report status before analysis
-
-Within 60 seconds of starting, and before source searches or tests, send this
-host update:
-
-```text
-Pinned head: <SHA>
-Base/comparison: <ref and SHA>
-CI: <pass/fail/pending/not applicable>
-Mergeability: <state/not applicable>
-Preliminary findings: <brief finding or none yet>
-```
-
-Mark early findings as preliminary and continue. This is not a GitHub comment.
-
-## Apply review gates
-
-- Report draft/WIP state. Continue a local review when explicitly requested,
-  but do not publish review events without separate authorization.
-- Record DCO, pre-commit, required CI, and mergeability. Pending or unknown gates
-  do not block source review.
-- Treat a failed gate as its own evidence. Do not restate its formatting/lint
-  output as a new code-review finding.
-- Open CI logs only when the first failing step overlaps the frozen diff or
-  blocks the verdict. Start with the first error, not the last cascade.
-- Treat the PR body as navigation. Commands, benchmark tables, and claimed tests
-  become evidence only after their provenance and relevance are checked.
-
-## Run bounded validation
-
-Keep one evidence packet for files read, bounded searches, callers, tests, CI,
-hardware, routes, and findings. Reuse it rather than refetching facts.
-
-Before pytest, run a short import/version compatibility check. Record each
-validation result with:
-
-```text
-repo, head SHA, command, result, Python/platform, dependency or lock fingerprint
-```
-
-After preflight, run targeted tests and low-cost static checks alongside source
-inspection when possible. Imports, tests, builds, and linters may create caches
-or rewrite files, so isolate each potentially mutating group in a disposable
-snapshot or recreate the pinned snapshot before continuing. Map source symbols
-to tests with bounded `rg` searches rather than assuming the test directory
-mirrors production paths.
-
-Classify failures as code, test, infrastructure, or flaky before reporting.
-Skipped hardware tests are gaps, not passes. For available hardware, verify the
-smallest representative unit/E2E path and compare actual output with PR claims.
-
-## Deliver maintainer-style findings
-
-Default to roughly 1-5 short comments, but treat that as calibration rather than
-a quota: report every real blocker and report no finding when there is no issue.
-
-Write each finding as:
-
-```text
-[P1] Short imperative title — path/to/file.py:<line>
-<Trigger or call path>. <Current behavior and impact>. <Smallest fix direction>.
-```
-
-Use [maintainer-style-study.md](../delivery/maintainer-style-study.md) for
-comment tone.
-Keep rule IDs, grades, and audit matrices internal unless the user asks for the
-complete audit.
-
-Verify every inline `path:line` against the frozen diff before delivery. For a
-PR, re-read the remote head and byte-compare the detached snapshot fingerprint,
-or recreate it from `head_sha`, before asserting current lines. For a local
-review, recompute and byte-compare the frozen `HEAD`, target, merge base, status,
-index patch, worktree patch, and untracked-content manifest. Any mismatch makes
-the review stale; discard the affected evidence and restart. Prefer one
-root-cause comment to several symptom comments.
-
-Local presentation is the default. Only explicit authorization permits GitHub
-posting. When authorized, publish one consolidated final review after
-validation; do not post preliminary or incremental comments. Submit a review
-event (`APPROVE`, `COMMENT`, or `REQUEST_CHANGES`) only when the user explicitly
-chooses that event.
-
-Reviewer requests and owner `@mention` comments are separate external writes;
-follow [review-requests.md](../delivery/review-requests.md) when the user asks
-for them.
-
-## Re-review safely
-
-Freeze the new head and compare it with the previously reviewed SHA. Then:
-
-1. inspect the delta and every file affected by conflict resolution or rebase;
-2. revalidate earlier findings against current lines and behavior;
-3. read unresolved, non-outdated threads and the author's evidence;
-4. rerun only checks invalidated by the delta;
-5. look for new regressions introduced by the fix;
-6. do not repeat resolved or outdated comments.
-
-If the target head changes during re-review, discard stale validation and start
-again from the new snapshot.

.claude/skills/review-pr/references/process/review-routing.md

@@ -1,76 +0,0 @@
-# Module and Feature Review Routing
-
-Read [design-contracts.md](design-contracts.md) first. Route from the frozen
-head's live producer-consumer behavior, then confirm the result against its
-`docs/design/` metadata. Titles and paths are evidence, not the deciding rule.
-
-## Primary module contract
-
-Choose one primary module and a second only when the live call path crosses a
-documented dependency or primary-path exception.
-
-| Module | Live behavior signals | Read |
-| --- | --- | --- |
-| Entrypoints | Offline/CLI/API ingress, validation, rendering, streaming, sessions | [entrypoints.md](../modules/entrypoints.md) |
-| Configuration | Schema, defaults, deploy/stage construction, registry, topology | [configuration.md](../modules/configuration.md) |
-| I/O and Modality | Requests, messages, serialization, output types, accumulation, completion | [input-output-modality.md](../modules/input-output-modality.md) |
-| Error Contracts | Classification, fatality, propagation, sanitization, public rendering | [error-contracts.md](../modules/error-contracts.md) |
-| Engine Orchestration | Cross-stage routing, request state, ordering, RPC correlation, terminal convergence | [engine-orchestration.md](../modules/engine-orchestration.md) |
-| Stage Runtime | Placement, startup, readiness, replicas, affinity, membership, shutdown | [stage-runtime.md](../modules/stage-runtime.md) |
-| OmniConnector | Cross-stage/process/device/node transport and synchronization | [omni-connector.md](../modules/omni-connector.md) |
-| Model Integration | Registration, preprocessing, loading, runners, model-specific execution | [model-integration.md](../modules/model-integration.md) |
-| AR Runtime | Scheduling, request/cache state, adapters, workers, upstream vLLM semantics | [ar-runtime.md](../modules/ar-runtime.md) |
-| Diffusion Family | Diffusion runtime, models, batching, parallelism, or offload | [diffusion.md](../modules/diffusion.md) |
-| Execution Platforms | Hardware selection, capabilities, vendor workers, kernels, patches | [execution-platforms.md](../modules/execution-platforms.md) |
-| Cache Management | Cache identity, validity, reuse, eviction, reset, teardown | [cache-management.md](../modules/cache-management.md) |
-| Quantization | Method/metadata selection, layer mapping, reduced precision, constraints | [quantization.md](../modules/quantization.md) |
-| Observability | Metrics, logs, labels, units, correlation, lifecycle | [observability.md](../modules/observability.md) |
-| Profiling | Opt-in instrumentation, traces, start/stop lifecycle, overhead | [profiling.md](../modules/profiling.md) |
-| Benchmarking | Workloads, metric computation, benchmark CLI, result metadata | [benchmarking.md](../modules/benchmarking.md) |
-
-For tests-, docs-, CI-, or recipe-only changes, route to the production module
-whose contract they protect. When none exists, use the applicable evidence
-check without inventing a production owner.
-
-## Feature-design overlays
-
-Load every category whose documented behavior, enablement, default, support, or
-compatibility changes.
-
-| Feature-design section | Read |
-| --- | --- |
-| Runtime and stage execution | [runtime-stage-execution.md](../features/runtime-stage-execution.md) |
-| Communication and concrete connectors | [communication.md](../features/communication.md) |
-| Diffusion acceleration | [diffusion-acceleration.md](../features/diffusion-acceleration.md) |
-| Infrastructure and performance | [infrastructure-performance.md](../features/infrastructure-performance.md) |
-
-## Evidence and change overlays
-
-| Signal | Read | Optional repo-local skill |
-| --- | --- | --- |
-| New or expanded model, loader, processor, registry, or stage config | [model-addition-checklist.md](../checks/model-addition-checklist.md) | [`add-tts-model`](../../../add-tts-model/SKILL.md) or [`add-diffusion-model`](../../../add-diffusion-model/SKILL.md) |
-| Latency, throughput, memory, scaling, precision, or quality claim | [perf-verification.md](../checks/perf-verification.md) | [`diffusion-perf-opt`](../../../diffusion-perf-opt/SKILL.md) for diffusion |
-| Tests changed, absent for risky behavior, or test-only | [test-quality-evaluation.md](../checks/test-quality-evaluation.md) | [`vllm-omni-test`](../../../vllm-omni-test/SKILL.md) |
-| CI, examples, docs, public behavior, or contributor evidence | [tests-docs-checklist.md](../checks/tests-docs-checklist.md) | None |
-| Suitable hardware/server and runnable affected path | [verification.md](../checks/verification.md) | None |
-| User asks who should review or requests owner notification | [review-requests.md](../delivery/review-requests.md) | None |
-
-Use [`quantization`](../../../quantization/SKILL.md) for a quantization module
-change and [`$vllm-omni-npu-model-runner-upgrade`](../../../vllm-omni-npu-upgrade/SKILL.md)
-for an NPU execution-platform change when those skills are available.
-
-For a bug fix, require a reachable reproduction and regression test. For a
-refactor, prove parity and remove obsolete paths. For a feature, verify the
-public/config contract, module integration, compatibility/default behavior,
-production dispatch, feature design, and docs.
-
-## Calibrate findings
-
-- **P0:** security exposure, data corruption, or broad project unusability.
-- **P1:** reachable runtime failure, wrong output, compatibility break, or
-  unsafe lifecycle in the changed behavior.
-- **P2:** real non-blocking defect with a concrete future failure mode.
-
-Treat draft candidate invariants, missing hardware, and unsupported claims as
-questions or validation gaps unless current code, tests, or policy makes them a
-merge requirement.

.github/CODEOWNERS

@@ -1,11 +1,6 @@
 # CODEOWNERS is used to automatically assign PR reviewers
 # Format: path pattern @username or @team
 # More info: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
-#
-# The vllm_omni/** source-tree rules below are derived from the `owners` and
-# `primary_code_paths` front matter in docs/design/module/*.md. When updating
-# ownership, update the design doc first, then regenerate the matching rule here.
-# Last-match-wins: more specific rules must come AFTER broader ones.
 
 # Default owners (fallback reviewers for all files)
 * @Gaohan123 @hsliuustc0106 @ywang96
@@ -26,10 +21,25 @@
 # CI
 /.buildkite/ @yenuo26 @congw729 @NickCao
 
-# ComfyUI / external apps
+# Engine and model_executor
-/apps/ @fhfuih @alex-jw-brooks
+/vllm_omni/core/ @tzhouam @yinpeiqi @fake0fan @Sy0307
+/vllm_omni/engine/ @tzhouam @yinpeiqi @fake0fan @Sy0307
+/vllm_omni/entrypoints/ @tzhouam @yinpeiqi @fake0fan @alex-jw-brooks @NickCao
+/vllm_omni/model_executor/ @tzhouam @gcanlin
+/vllm_omni/worker/ @tzhouam @gcanlin
 
-# Benchmarks (out-of-tree)
+# Diffusion
+/vllm_omni/diffusion/ @Isotr0py @princepride @SamitHuang @wtomin @ZJY0516 @RuixiangMa @david6666666 @xuechendi
+/vllm_omni/lora/ @princepride @SamitHuang @wtomin @ZJY0516 @RuixiangMa @yuanheng-zhao
+
+# Diffusion CPU offloading
+/vllm_omni/diffusion/offloader/ @Isotr0py @princepride @SamitHuang @wtomin @ZJY0516 @RuixiangMa @yuanheng-zhao @xuechendi
+
+# Omni and TTS support
+/vllm_omni/transformers_utils/ @tzhouam @yuanheng-zhao
+/vllm_omni/model_executor/models/ @linyueqian @ZeldaHuang @princepride @yuanheng-zhao @amy-why-3459 @Bounty-hunter @Sy0307 @gcanlin @NickCao
+
+# Benchmarks
 /benchmarks/accuracy/ @david6666666
 /benchmarks/build_dataset/ @linyueqian @yuanheng-zhao
 /benchmarks/diffusion/ @Isotr0py @princepride @SamitHuang @wtomin @ZJY0516 @RuixiangMa @xuechendi
@@ -37,112 +47,20 @@
 /benchmarks/glm_image/ @princepride @JaredforReal
 /benchmarks/tts/ @linyueqian @ZeldaHuang @princepride @Sy0307 @gcanlin
 
-# =====================================================================
+# Usability and Observability
-# Module design ownership (docs/design/module/*.md)
+/vllm_omni/deploy/ @tzhouam @lishunyang12
-# Each section header cites the source design doc.
+/vllm_omni/metrics/ @lishunyang12
-# =====================================================================
-
-# Autoregressive runtime — docs/design/module/ar_runtime.md
-/vllm_omni/core/ @tzhouam @yinpeiqi @fake0fan @Sy0307 @Gaohan123
-/vllm_omni/worker/ @tzhouam @yinpeiqi @fake0fan @Sy0307 @Gaohan123
-
-# Engine orchestration & stage runtime — docs/design/module/engine_orchestration.md, stage_runtime.md
-/vllm_omni/engine/ @tzhouam @fake0fan
-# File-level overrides: input/output modality contracts own these engine files
-# — docs/design/module/input_output_modality_contracts.md
-/vllm_omni/engine/messages.py @Sy0307 @amy-why-3459 @Gaohan123 @alex-jw-brooks
-/vllm_omni/engine/serialization.py @Sy0307 @amy-why-3459 @Gaohan123 @alex-jw-brooks
-/vllm_omni/engine/mm_outputs.py @Sy0307 @amy-why-3459 @Gaohan123 @alex-jw-brooks
-/vllm_omni/engine/output_modality.py @Sy0307 @amy-why-3459 @Gaohan123 @alex-jw-brooks
-/vllm_omni/engine/output_processor.py @Sy0307 @amy-why-3459 @Gaohan123 @alex-jw-brooks
-
-# Input/output modality contracts — docs/design/module/input_output_modality_contracts.md
-/vllm_omni/inputs/ @Sy0307 @amy-why-3459 @Gaohan123 @alex-jw-brooks
-/vllm_omni/outputs/ @Sy0307 @amy-why-3459 @Gaohan123 @alex-jw-brooks
-/vllm_omni/request.py @Sy0307 @amy-why-3459 @Gaohan123 @alex-jw-brooks
-/vllm_omni/data_entry_keys.py @Sy0307 @amy-why-3459 @Gaohan123 @alex-jw-brooks
-
-# Entrypoints and serving boundaries — docs/design/module/entrypoints.md
-/vllm_omni/entrypoints/ @alex-jw-brooks @linyueqian @NickCao
-# File-level overrides within entrypoints/
-/vllm_omni/entrypoints/openai/errors.py @alex-jw-brooks @NickCao
-/vllm_omni/entrypoints/cli/benchmark/ @alex-jw-brooks @Bounty-hunter
-
-# Error contracts — docs/design/module/error_contracts.md
-/vllm_omni/errors.py @alex-jw-brooks @NickCao
-
-# OmniConnector (inter-stage transport) — docs/design/module/omni_connector.md
-/vllm_omni/distributed/ @princepride @yuanheng-zhao @xuechendi @natureofnature @fake0fan
-
-# Model integration — docs/design/module/model_integration.md
-/vllm_omni/model_executor/ @tzhouam @gcanlin
-/vllm_omni/model_executor/models/ @tzhouam @gcanlin @Sy0307 @amy-why-3459 @linyueqian
-/vllm_omni/model_extras/ @tzhouam @gcanlin @princepride
-/vllm_omni/plugins/ @gcanlin @tjtanaa @xuechendi
-# Config override within model_executor — docs/design/module/vllm_omni_config.md
-/vllm_omni/model_executor/stage_configs/ @lishunyang12 @alex-jw-brooks
-
-# Execution platforms (hardware backends) — docs/design/module/execution_platforms.md
-/vllm_omni/platforms/ @gcanlin @tjtanaa @xuechendi
-/vllm_omni/attention/ @gcanlin @tjtanaa @xuechendi @david6666666 @lishunyang12
-
-# Configuration & deploy — docs/design/module/vllm_omni_config.md
-/vllm_omni/config/ @lishunyang12 @alex-jw-brooks
-/vllm_omni/deploy/ @lishunyang12 @alex-jw-brooks
-
-# Quantization — docs/design/module/quantization.md
-/vllm_omni/quantization/ @david6666666 @Isotr0py @lishunyang12
-
-# Observability — docs/design/module/observability.md
-/vllm_omni/metrics/ @lishunyang12 @vraiti
-
-# Profiling — docs/design/module/profiling.md
 /vllm_omni/profiler/ @gcanlin
 
-# Benchmarking (in-tree) — docs/design/module/benchmarking.md
+# ComfyUI
-/vllm_omni/benchmarks/ @alex-jw-brooks @Bounty-hunter
+/apps/ @fhfuih @alex-jw-brooks
 
-# LoRA (no dedicated design doc; ownership intentionally narrowed)
+# Large Scale Serving
-/vllm_omni/lora/ @SamitHuang @wtomin
+/vllm_omni/distributed/ @princepride @yuanheng-zhao @xuechendi @natureofnature @fake0fan
 
-# Transformers utils (related path only in design docs; preserves prior ownership)
+# Quantization and configuration
-/vllm_omni/transformers_utils/ @tzhouam @yuanheng-zhao
+/vllm_omni/config/ @lishunyang12 @alex-jw-brooks
+/vllm_omni/quantization/ @david6666666 @Isotr0py @lishunyang12
 
-# =====================================================================
+# Hardware plugins and accelerators
-# Diffusion module family — docs/design/module/diffusion/
+/vllm_omni/platforms/ @gcanlin @tjtanaa @xuechendi
-# Umbrella rule first; sub-module rules after it win via last-match.
-# =====================================================================
-
-# Diffusion umbrella (top-level files: data.py, forward_context.py, etc.)
-# — docs/design/module/diffusion/index.md
-/vllm_omni/diffusion/ @Isotr0py @princepride @SamitHuang @wtomin @ZJY0516 @RuixiangMa @david6666666 @xuechendi
-
-# Cache management — docs/design/module/cache_management.md
-/vllm_omni/diffusion/cache/ @Isotr0py @princepride @SamitHuang
-
-# Diffusion quantization — docs/design/module/quantization.md
-/vllm_omni/diffusion/quantization/ @david6666666 @Isotr0py @lishunyang12
-
-# Diffusion profiling — docs/design/module/profiling.md
-/vllm_omni/diffusion/profiler/ @gcanlin
-
-# Diffusion runtime (scheduler, executor, worker)
-# — docs/design/module/diffusion/diffusion_runtime.md, continuous_batching.md
-/vllm_omni/diffusion/sched/ @Isotr0py @princepride @SamitHuang @fhfuih
-/vllm_omni/diffusion/executor/ @Isotr0py @princepride @SamitHuang @fhfuih
-/vllm_omni/diffusion/worker/ @Isotr0py @princepride @SamitHuang @fhfuih
-
-# Diffusion model integration (pipelines, registration, checkpoint loading)
-# — docs/design/module/diffusion/diffusion_model_integration.md
-/vllm_omni/diffusion/models/ @fhfuih @Bounty-hunter @wtomin
-/vllm_omni/diffusion/model_loader/ @fhfuih @Bounty-hunter @wtomin @RuixiangMa
-/vllm_omni/diffusion/lora/ @fhfuih @Bounty-hunter @wtomin @RuixiangMa
-
-# Diffusion parallelism (rank topology, TP/SP/PP/VAE patch)
-# — docs/design/module/diffusion/parallelism.md
-/vllm_omni/diffusion/distributed/ @princepride @yuanheng-zhao @xuechendi @Bounty-hunter
-/vllm_omni/diffusion/attention/parallel/ @princepride @yuanheng-zhao @xuechendi @Bounty-hunter
-
-# Diffusion offloader (CPU offloading, DLO)
-# — docs/design/module/diffusion/offloader.md
-/vllm_omni/diffusion/offloader/ @yuanheng-zhao @david6666666 @lishunyang12

.pre-commit-config.yaml

@@ -61,16 +61,6 @@ repos:
       types: [python]
       files: ^tests/
 
-    - id: check-tts-adapter-migration
-      name: Ratchet TTS per-model branches out of serving_speech.py
-      entry: python tools/pre_commit/check_tts_adapter.py
-      language: python
-      pass_filenames: false
-      files: ^(vllm_omni/entrypoints/openai/(serving_speech\.py|tts_adapters/__init__\.py)|tools/pre_commit/check_tts_adapter\.py)$
-      # The budget-is-now-slack reminder is printed on a PASSING run, and
-      # pre-commit hides output from passing hooks unless the hook is verbose.
-      verbose: true
-
     # Keep `suggestion` last
     - id: suggestion
       name: Suggestion

.readthedocs.yml

@@ -11,15 +11,10 @@ build:
     post_checkout:
       - git fetch --unshallow || true
     pre_install:
-      # `pre_install` runs before RTD upgrades pip, and the seeded pip 23.1
-      # rejects the `typing_extensions` wheel torch needs (fixed in pip 23.2).
-      - python -m pip install --upgrade pip
       # Pre-install CPU torch so the subsequent `pip install .[docs]` does not
       # pull ~2 GB of CUDA 13 libs (cuBLAS/cuDNN/NCCL/...) that exceed RTD's
-      # 1 GB memory cap and time out the mkdocs build. Wheel-only: `--index-url`
+      # 1 GB memory cap and time out the mkdocs build.
-      # replaces PyPI, so an sdist fallback cannot reach its build deps. The
+      - python -m pip install --index-url https://download.pytorch.org/whl/cpu torch
-      # quotes keep YAML from reading `:all:` as a mapping key.
-      - "python -m pip install --only-binary=:all: --index-url https://download.pytorch.org/whl/cpu torch"
 
 mkdocs:
   configuration: mkdocs.yml

README.md

@@ -9,7 +9,7 @@ Easy, fast, and cheap omni-modality model serving for everyone
 </h3>
 
 <p align="center">
-| <a href="https://vllm-omni.readthedocs.io/en/latest/"><b>Documentation</b></a> | <a href="https://deepwiki.com/vllm-project/vllm-omni"><b>DeepWiki</b></a> | <a href="https://discuss.vllm.ai"><b>User Forum</b></a> | <a href="https://slack.vllm.ai"><b>Developer Slack</b></a> | <a href="docs/assets/WeChat.jpg"><b>WeChat</b></a> | <a href="https://arxiv.org/abs/2602.02204"><b>Paper</b></a> | <a href="https://docs.google.com/presentation/d/1aPj0OGl_-ZVoib-Qne5dGDAlrRFB-PdHl6E-EE99g8E/edit?usp=sharing"><b>Slides</b></a> |
+| <a href="https://vllm-omni.readthedocs.io/en/latest/"><b>Documentation</b></a> | <a href="https://deepwiki.com/vllm-project/vllm-omni"><b>DeepWiki</b></a> | <a href="https://discuss.vllm.ai"><b>User Forum</b></a> | <a href="https://slack.vllm.ai"><b>Developer Slack</b></a> | <a href="docs/assets/WeChat.jpg"><b>WeChat</b></a> | <a href="https://arxiv.org/abs/2602.02204"><b>Paper</b></a> | <a href="https://docs.google.com/presentation/d/111-L8zF7A1j_YI_cR8JsblofdScdRr2f/edit?usp=sharing&ouid=110473603432222024453&rtpof=true&sd=true"><b>Slides</b></a> |
 </p>
 
 

benchmarks/diffusion/quantization_quality.py

@@ -158,6 +158,7 @@ def _build_omni_kwargs(args, quantization=None):
 def _generate_image(omni, args, prompt, seed):
     """Generate a single image and return (PIL.Image, time_seconds, memory_gib)."""
     from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+    from vllm_omni.outputs import OmniRequestOutput
     from vllm_omni.platforms import current_omni_platform
 
     generator = torch.Generator(device=current_omni_platform.device_type).manual_seed(seed)
@@ -175,7 +176,7 @@ def _generate_image(omni, args, prompt, seed):
     elapsed = time.perf_counter() - start
     peak_mem = torch.accelerator.max_memory_allocated() / (1024**3)
 
-    req_out = outputs[0] if isinstance(outputs, list) else outputs
+    req_out = OmniRequestOutput.unwrap_result(outputs)
     if not req_out.images:
         raise ValueError("Could not extract image output from result.")
     img = req_out.images[0]
@@ -205,15 +206,15 @@ def _generate_video(omni, args, prompt, seed):
     elapsed = time.perf_counter() - start
     peak_mem = torch.accelerator.max_memory_allocated() / (1024**3)
 
-    if isinstance(outputs, list) and isinstance(outputs[0], OmniRequestOutput):
     first = outputs[0]
-    elif isinstance(outputs, OmniRequestOutput):
+    if hasattr(first, "request_output") and isinstance(first.request_output, list):
-        first = outputs
+        inner = first.request_output[0]
+        if isinstance(inner, OmniRequestOutput) and hasattr(inner, "images"):
+            frames = inner.images[0] if inner.images else None
         else:
-        raise ValueError("Could not extract video frames from output.")
+            frames = inner
-
+    elif hasattr(first, "images") and first.images:
-    if hasattr(first, "images"):
+        frames = first.images[0]
-        frames = first.images[0] if first.images else None
     else:
         raise ValueError("Could not extract video frames from output.")
 

benchmarks/glm_image/vllm-omni/inference.py

@@ -300,7 +300,7 @@ def benchmark(args: argparse.Namespace) -> None:
         output_idx = 0
         for stage_outputs in omni.generate(all_prompts, sampling_params_list, py_generator=True):
             if stage_outputs.final_output_type == "image":
-                request_output = stage_outputs
+                request_output = stage_outputs.request_output
                 request_id = getattr(request_output, "request_id", "")
 
                 images = getattr(request_output, "images", [])

benchmarks/lingbot_video/dense_pipeline_parity.py

@@ -167,11 +167,9 @@ def main() -> None:
     ]
     native_cmd = [
         sys.executable,
-        "examples/offline_inference/text_to_video/text_to_video.py",
+        "examples/offline_inference/text_to_video/text_to_video_lingbot.py",
         "--model",
         args.model,
-        "--model-class-name",
-        "LingBotVideoPipeline",
         "--prompt",
         args.prompt,
         "--output",

benchmarks/tts/README.md

@@ -139,34 +139,6 @@ python benchmarks/tts/bench_tts.py \
     --output-dir ./results
 ```
 
-#### Fixed IndexTTS 2.5 performance sweep
-
-IndexTTS 2.5 is registered in `model_configs.yaml` like the other TTS models.
-Use `--served-model-name` when the server was launched from a local native
-bundle instead of the registry key. The command below reproduces the acceptance
-workload: Seed-TTS Eval EN, `n=500`, concurrency `4/8/16/32`, five warmups, and
-dataset seed 0.
-
-```bash
-python benchmarks/tts/bench_tts.py \
-    --model IndexTeam/IndexTTS-2.5 \
-    --served-model-name /path/to/indextts-2.5 \
-    --task voice_clone --locale en \
-    --dataset-path /path/to/seedtts_testset \
-    --host 127.0.0.1 --port 8092 \
-    --concurrency 4 8 16 32 \
-    --num-prompts 500 --num-warmups 5 \
-    --output-dir ./results/indextts2_5 \
-    -- \
-    --tokenizer /path/to/indextts-2.5/qwen0.6bemo4-merge \
-    --seed 0 --metric-percentiles 50,95,99 --disable-tqdm --save-detailed
-```
-
-The wrapper benchmarks an already-running server. For reproducible quality
-comparisons, add `--request-seed 42`; production-performance runs should omit
-it. The trailing `--seed 0` controls Seed-TTS row selection rather than model
-sampling.
-
 ### 4. Plot a sweep
 
 ```bash

benchmarks/tts/bench_tts.py

@@ -84,17 +84,12 @@ def build_bench_args(
     result_filename: str | None,
     extra_cli_args: list[str],
     output_len: int | None = None,
-    served_model_name: str | None = None,
-    num_warmups: int = 2,
-    request_seed: int | None = None,
 ) -> list[str]:
     """Build the ``vllm bench serve --omni`` command for one (task, concurrency) run."""
     dataset_name = _TASK_TO_DATASET[task]
     backend: str = model_cfg["backend"]
     endpoint: str = model_cfg["endpoint"]
-    task_extra_body: dict[str, Any] = dict((model_cfg.get("task_extra_body") or {}).get(task) or {})
+    task_extra_body: dict[str, Any] = (model_cfg.get("task_extra_body") or {}).get(task) or {}
-    if request_seed is not None:
-        task_extra_body["seed"] = request_seed
 
     # Resolve dataset path
     if dataset_path:
@@ -114,7 +109,7 @@ def build_bench_args(
         "--port",
         str(port),
         "--model",
-        served_model_name or model,
+        model,
         "--backend",
         backend,
         "--endpoint",
@@ -124,7 +119,7 @@ def build_bench_args(
         "--num-prompts",
         str(num_prompts),
         "--num-warmups",
-        str(num_warmups),
+        "2",
         "--percentile-metrics",
         "ttft,e2el,audio_rtf,audio_ttfp,audio_duration,audio_underrun",
     ]
@@ -157,8 +152,7 @@ def build_bench_args(
         if result_filename:
             cmd += ["--result-filename", result_filename]
 
-    passthrough = extra_cli_args[1:] if extra_cli_args[:1] == ["--"] else extra_cli_args
+    cmd += extra_cli_args
-    cmd += passthrough
     return cmd
 
 
@@ -231,12 +225,6 @@ def main() -> None:
     parser.add_argument(
         "--model", required=True, help="HuggingFace model ID (e.g. Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice)"
     )
-    parser.add_argument(
-        "--served-model-name",
-        default=None,
-        help="Model name/path accepted by the running server. Use this when --model selects a registry entry "
-        "but the server was launched from a local bundle path.",
-    )
     parser.add_argument("--task", default="all", help="Task type: voice_clone | default_voice | voice_design | all")
     parser.add_argument("--locale", default="en", choices=["en", "zh"])
     parser.add_argument("--concurrency", type=int, nargs="+", default=[1, 4], metavar="N")
@@ -248,13 +236,6 @@ def main() -> None:
         metavar="N",
         help="Number of prompts per run. If one value, applied to all concurrency levels.",
     )
-    parser.add_argument("--num-warmups", type=int, default=2, help="Warmup requests before each measured run")
-    parser.add_argument(
-        "--request-seed",
-        type=int,
-        default=None,
-        help="Optional model sampling seed added to every request body for reproducible quality runs",
-    )
     parser.add_argument(
         "--dataset-path", default=None, help="Root of seed-tts-eval dataset (required for voice_clone/default_voice)"
     )
@@ -275,9 +256,6 @@ def main() -> None:
     parser.add_argument("extra", nargs=argparse.REMAINDER, help="Extra args passed directly to vllm bench serve")
     args = parser.parse_args()
 
-    if args.num_warmups < 0:
-        parser.error("--num-warmups cannot be negative")
-
     model_configs = load_model_configs(Path(args.model_configs))
     if args.model not in model_configs:
         known = "\n  ".join(model_configs.keys())
@@ -330,9 +308,6 @@ def main() -> None:
                 result_filename=result_filename,
                 extra_cli_args=args.extra or [],
                 output_len=args.output_len,
-                served_model_name=args.served_model_name,
-                num_warmups=args.num_warmups,
-                request_seed=args.request_seed,
             )
             result = run_one_benchmark(cmd)
             if result is not None:

benchmarks/tts/model_configs.yaml

@@ -7,17 +7,6 @@
 # is tracked here.
 
 models:
-  IndexTeam/IndexTTS-2.5:
-    supported_tasks: [voice_clone]
-    backend: openai-audio-speech
-    endpoint: /v1/audio/speech
-    trust_remote_code: true
-    task_extra_body:
-      voice_clone:
-        extra_params:
-          lang: en
-          text_normalization: true
-
   # -CustomVoice checkpoints lack speaker_encoder weights, so voice_clone is
   # NOT supported (an attempt raises ValueError from _extract_speaker_embedding
   # at model runtime).  Use -Base for voice_clone.

docker/Dockerfile.ci

@@ -1,24 +1,7 @@
-# Target vllm version: v0.27.0 (releases/v0.27.0 branch).
+# Target vllm version: v0.26.0 (releases/v0.26.0 branch).
 # Keep VLLM_BASE_TAG aligned with the target vLLM release on every rebase.
-#
-# Release-boundary form: there is no precompiled-wheel pin here, because the
-# base image already ships exactly the target vLLM. Everything the runtime
-# needs — torch, flashinfer, nvJitLink, numpy — comes from that image as one
-# self-consistent set.
-#
-# This block reappears only when the rebase targets a vLLM commit that is NOT a
-# released tag. During the 0.27 rebase, targeting v0.27.0rc1 on top of the
-# v0.26.0 base image required reinstalling vLLM from wheels.vllm.ai and then
-# hand-repairing the fallout: pinning torch ahead of flashinfer (installing it
-# after bound flashinfer's TVM FFI runtime to the old torch and aborted engine
-# core init), registering libnvJitLink.so.13 with ldconfig, and re-pinning numpy
-# under numba's ceiling. All of it was compensation for a base image and a vLLM
-# that disagreed. At a real release boundary they agree, so none of it is
-# needed. If you pin an untagged commit again, restore the reinstall block —
-# agent/tasks/20_update_wheel_url.sh fails the run rather than letting the
-# Dockerfile silently ship the wrong vLLM.
 ARG VLLM_BASE_IMAGE=vllm/vllm-openai
-ARG VLLM_BASE_TAG=v0.27.0
+ARG VLLM_BASE_TAG=v0.26.0
 
 # We use registry-based layer caching for the dependencies,
 # where the tag is determined based on the hash of the contents

docker/Dockerfile.npu

@@ -1,5 +1,5 @@
 ARG VLLM_ASCEND_IMAGE=quay.io/atlas-ci/vllm-ascend
-ARG VLLM_ASCEND_TAG=v0.27.0
+ARG VLLM_ASCEND_TAG=v0.26.0
 FROM ${VLLM_ASCEND_IMAGE}:${VLLM_ASCEND_TAG}
 
 # WORKDIR /vllm-workspace/vllm

docker/Dockerfile.npu.a3

@@ -1,5 +1,5 @@
 ARG VLLM_ASCEND_IMAGE=quay.io/atlas-ci/vllm-ascend
-ARG VLLM_ASCEND_TAG=v0.27.0-a3
+ARG VLLM_ASCEND_TAG=v0.26.0-a3
 FROM ${VLLM_ASCEND_IMAGE}:${VLLM_ASCEND_TAG}
 
 # WORKDIR /vllm-workspace/vllm

docker/Dockerfile.npu.ci

@@ -1,5 +1,5 @@
 ARG VLLM_ASCEND_IMAGE=quay.io/atlas-ci/vllm-ascend
-ARG VLLM_ASCEND_TAG=v0.27.0
+ARG VLLM_ASCEND_TAG=v0.26.0
 FROM ${VLLM_ASCEND_IMAGE}:${VLLM_ASCEND_TAG}
 
 ARG APP_DIR=/vllm-workspace/vllm-omni
@@ -45,7 +45,6 @@ RUN source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
       "hyperpyyaml>=1.2.0" \
       "onnx>=1.16.0" \
       "librosa>=0.10.0" \
-      "datasets>=3.0.0" \
       --index-url http://cache-service.nginx-pypi-cache.svc.cluster.local/pypi/simple \
       --trusted-host cache-service.nginx-pypi-cache.svc.cluster.local \
       --default-timeout=60 && \

docker/Dockerfile.npu.ci.a3

@@ -1,5 +1,5 @@
 ARG VLLM_ASCEND_IMAGE=quay.io/atlas-ci/vllm-ascend
-ARG VLLM_ASCEND_TAG=v0.27.0-a3
+ARG VLLM_ASCEND_TAG=v0.26.0-a3
 FROM ${VLLM_ASCEND_IMAGE}:${VLLM_ASCEND_TAG}
 
 ARG APP_DIR=/vllm-workspace/vllm-omni
@@ -46,7 +46,6 @@ RUN source /usr/local/Ascend/ascend-toolkit/set_env.sh && \
       "onnx>=1.16.0" \
       "librosa>=0.10.0" \
       "torchmetrics>=1.9.0" \
-      "datasets>=3.0.0" \
       --index-url http://cache-service.nginx-pypi-cache.svc.cluster.local/pypi/simple \
       --trusted-host cache-service.nginx-pypi-cache.svc.cluster.local \
       --default-timeout=60 && \

docker/Dockerfile.xpu

@@ -88,7 +88,7 @@ ENV UV_EXTRA_INDEX_URL=${PIP_EXTRA_INDEX_URL}
 ENV UV_INDEX_STRATEGY="unsafe-best-match"
 ENV UV_LINK_MODE="copy"
 
-ARG VLLM_VERSION=v0.27.0
+ARG VLLM_VERSION=v0.26.0
 RUN git clone -b ${VLLM_VERSION} https://github.com/vllm-project/vllm
 WORKDIR /workspace/vllm
 
@@ -108,7 +108,7 @@ ENV VLLM_WORKER_MULTIPROC_METHOD=spawn
 
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv pip uninstall triton triton-xpu && \
-    uv pip install triton-xpu==3.7.2 && \
+    uv pip install triton-xpu==3.7.1 && \
     uv pip install --no-build-isolation --no-deps .
 
 CMD ["/bin/bash"]
@@ -144,13 +144,12 @@ WORKDIR /workspace/vllm-omni
 COPY . .
 
 ENV VLLM_OMNI_TARGET_DEVICE=xpu
-# Keep the upstream oneCCL packages paired with the XPU torch runtime.
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv pip install --no-build-isolation \
     --extra-index-url https://mirrors.ustc.edu.cn/pypi/simple/ \
     ".[dev]" && \
-    uv pip uninstall triton && \
+    uv pip uninstall triton oneccl oneccl-devel && \
-    uv pip install triton-xpu==3.7.2 --reinstall
+    uv pip install triton-xpu==3.7.1 --reinstall
 
 FROM vllm-omni AS vllm-omni-openai
 

docs/.nav.yml

@@ -16,21 +16,31 @@ nav:
   - Examples:
     - examples/README.md
     - Offline Inference:
+      - GLM-Image Multistage End-to-End Inference: user_guide/examples/offline_inference/glm_image.md
+      - HunyuanImage-3.0 Image-to-Text Inference: user_guide/examples/offline_inference/hunyuan_image3.md
       - Image-To-Image: user_guide/examples/offline_inference/image_to_image.md
       - Image-To-Video: user_guide/examples/offline_inference/image_to_video.md
-      - Speech-To-Video: user_guide/examples/offline_inference/speech_to_video.md
+      - InternVLA-A1: user_guide/examples/offline_inference/internvla_a1.md
+      - MiMo-Audio: user_guide/examples/offline_inference/mimo_audio.md
+      - Qwen2.5-Omni: user_guide/examples/offline_inference/qwen2_5_omni.md
+      - Qwen3-Omni: user_guide/examples/offline_inference/qwen3_omni.md
       - Text-To-Audio: user_guide/examples/offline_inference/text_to_audio.md
       - Text-To-Image: user_guide/examples/offline_inference/text_to_image.md
       - Text-To-Speech: user_guide/examples/offline_inference/text_to_speech.md
       - Text-To-Video: user_guide/examples/offline_inference/text_to_video.md
-      - X-To-Text: user_guide/examples/offline_inference/x_to_text.md
       - X-To-Video-Audio: user_guide/examples/offline_inference/x_to_video_audio.md
     - Online Serving:
+      - BAGEL-7B-MoT: user_guide/examples/online_serving/bagel.md
+      - vLLM-Omni Helm Chart: user_guide/examples/online_serving/chart-helm.md
+      - Diffusers Backend Adapter: user_guide/examples/online_serving/diffusers_pipeline_adapter.md
+      - GLM-Image Online Serving: user_guide/examples/online_serving/glm_image.md
       - Image-To-Image: user_guide/examples/online_serving/image_to_image.md
       - Image-To-Video: user_guide/examples/online_serving/image_to_video.md
-      - Speech-To-Video: user_guide/examples/online_serving/speech_to_video.md
+      - MiMo-Audio: user_guide/examples/online_serving/mimo_audio.md
-      - Text-To-Image: user_guide/examples/online_serving/text_to_image.md
+      - Qwen2.5-Omni: user_guide/examples/online_serving/qwen2_5_omni.md
+      - Qwen3-Omni: user_guide/examples/online_serving/qwen3_omni.md
       - Text-To-Speech: user_guide/examples/online_serving/text_to_speech.md
+      - Text-To-Image: user_guide/examples/online_serving/text_to_image.md
       - Text-To-Video: user_guide/examples/online_serving/text_to_video.md
   - General:
     - usage/*
@@ -40,12 +50,30 @@ nav:
   - Models:
     - models/supported_models.md
   - Features:
-    - Overview: features/README.md
-    - Runtime and Stage Execution:
-      - Execution Modes and Streaming: user_guide/diffusion/execution_modes.md
     - Sleep Mode: features/sleep_mode.md
+    - Diffusion Features:
+      - Overview: user_guide/diffusion_features.md
+      - Feature Compatibility: user_guide/feature_compatibility.md
+      - Regional Compilation: user_guide/diffusion/regional_compilation.md
+      - Cache Acceleration:
+        - TeaCache: user_guide/diffusion/cache_acceleration/teacache.md
+        - Cache-DiT: user_guide/diffusion/cache_acceleration/cache_dit.md
+      - Attention Backends: user_guide/diffusion/attention_backends.md
+      - Frame Interpolation: user_guide/diffusion/frame_interpolation.md
+      - Parallelism:
+        - Overview: user_guide/diffusion/parallelism/overview.md
+        - CFG Parallel: user_guide/diffusion/parallelism/cfg_parallel.md
+        - Expert Parallel: user_guide/diffusion/parallelism/expert_parallel.md
+        - Hybrid Sharded Data Parallel: user_guide/diffusion/parallelism/hsdp.md
+        - Sequence Parallel: user_guide/diffusion/parallelism/sequence_parallel.md
+        - Tensor Parallel: user_guide/diffusion/parallelism/tensor_parallel.md
+        - VAE Parallelism: user_guide/diffusion/parallelism/vae_parallelism.md
+      - CPU Offloading: user_guide/diffusion/cpu_offload.md
+      - LoRA: user_guide/diffusion/lora.md
+      - Custom Pipeline: features/custom_pipeline.md
+      - Execution Modes: user_guide/diffusion/execution_modes.md
     - Quantization:
-      - Overview: user_guide/quantization/overview.md
+      - Quantization: user_guide/quantization/overview.md
       - Online Quantization: user_guide/quantization/online.md
       - Quantized KV Cache: user_guide/quantization/quantized_kvcache.md
       - FP8 W8A8: user_guide/quantization/fp8.md
@@ -54,33 +82,9 @@ nav:
       - MXFP8 W8A8: user_guide/quantization/mxfp8.md
       - MXFP4 W4A4: user_guide/quantization/mxfp4.md
       - ModelOpt: user_guide/quantization/modelopt.md
+      - GGUF: user_guide/quantization/gguf.md
       - AutoRound: user_guide/quantization/autoround.md
       - msModelSlim: user_guide/quantization/msmodelslim.md
-    - Diffusion Acceleration:
-      - Overview and Compatibility:
-        - Overview: user_guide/diffusion_features.md
-        - Feature Compatibility: user_guide/feature_compatibility.md
-      - CPU Offloading: user_guide/diffusion/cpu_offload.md
-      - Cache Acceleration:
-        - TeaCache: user_guide/diffusion/cache_acceleration/teacache.md
-        - Cache-DiT: user_guide/diffusion/cache_acceleration/cache_dit.md
-      - Parallelism:
-        - Overview: user_guide/diffusion/parallelism/overview.md
-        - CFG Parallel: user_guide/diffusion/parallelism/cfg_parallel.md
-        - Expert Parallel: user_guide/diffusion/parallelism/expert_parallel.md
-        - Hybrid Sharded Data Parallel: user_guide/diffusion/parallelism/hsdp.md
-        - Sequence Parallel: user_guide/diffusion/parallelism/sequence_parallel.md
-        - Tensor Parallel: user_guide/diffusion/parallelism/tensor_parallel.md
-        - VAE Parallel: user_guide/diffusion/parallelism/vae_parallel.md
-      - Attention Backends: user_guide/diffusion/attention_backends.md
-      - Regional Compilation: user_guide/diffusion/regional_compilation.md
-      - Frame Interpolation: user_guide/diffusion/frame_interpolation.md
-      - Startup and Loading: user_guide/diffusion/startup_and_loading.md
-      - LoRA: user_guide/diffusion/lora.md
-    - Experimental:
-      - Session State Manager: features/session_state_manager.md
-  - Integrations:
-    - Custom Diffusion Pipeline: features/custom_pipeline.md
     - ComfyUI: features/comfyui.md
   - Fault Tolerance:
     - Failure Modes: user_guide/fault_injection_reliability_matrix.md
@@ -114,7 +118,6 @@ nav:
           - Shared Memory Connector: design/feature/omni_connectors/shared_memory_connector.md
           - Yuanrong Store Connector: design/feature/omni_connectors/yuanrong_connector.md
           - Yuanrong Transfer Engine Connector: design/feature/omni_connectors/yuanrong_transfer_engine_connector.md
-      - Quantization: design/feature/quantization.md
       - Diffusion Acceleration:
         - Parallelism:
           - CFG-Parallel: design/feature/cfg_parallel.md
@@ -123,9 +126,10 @@ nav:
           - Pipeline Parallel: design/feature/pipeline_parallel.md
           - Sequence Parallel: design/feature/sequence_parallel.md
           - Tensor Parallel: design/feature/tensor_parallel.md
-          - VAE Parallel: design/feature/vae_parallel.md
+          - VAE Patch Parallelism: design/feature/vae_parallel.md
-        - Attention Optimization:
+        - Attention Backends:
           - Skip-Softmax: design/feature/skip_softmax.md
+        - Quantization: design/feature/quantization.md
         - Cache-DiT: design/feature/cache_dit.md
         - TeaCache: design/feature/teacache.md
         - Diffusion Continuous Batching: design/feature/diffusion_continuous_batching.md
@@ -163,8 +167,7 @@ nav:
 - CLI Reference: cli
 - Community:
   - Governance: community/governance.md
-  - Contact Us: community/contact_us.md
+  - community/*
-  - Community Meetings: community/meetings.md
   - Slack: https://slack.vllm.ai
   - Blog: https://blog.vllm.ai
   - Forum: https://discuss.vllm.ai

docs/README.md

@@ -63,5 +63,5 @@ vLLM-Omni seamlessly supports most popular open-source models on HuggingFace, in
 
 For more information, checkout the following:
 
-- [vllm-omni architecture design and recent roadmaps](https://docs.google.com/presentation/d/1aPj0OGl_-ZVoib-Qne5dGDAlrRFB-PdHl6E-EE99g8E/edit?usp=sharing)
+- [vllm-omni architecture design and recent roadmaps](https://docs.google.com/presentation/d/1XJWgv79lORl8rbaVvp2d5Sqs6ZEBgAgj/edit?slide=id.p1#slide=id.p1)
 - [vllm-omni announcement blogpost](https://blog.vllm.ai/2025/11/30/vllm-omni.html)

docs/community/contact_us.md

@@ -1,9 +1,5 @@
 # Contact Us
 
-- For bugs and feature requests, search or open a GitHub [issue](https://github.com/vllm-project/vllm-omni/issues).
+- For technical questions and feature requests, please use GitHub [Issues](https://github.com/vllm-project/vllm-omni/issues)
-- For technical and usage questions, join the `sig-omni` channel in [vLLM Slack](https://slack.vllm.ai/) or use the [vLLM Forum](https://discuss.vllm.ai/).
+- For coordinating contributions and development and discussing with other users and developers, please join `sig-omni` channel in our [Slack](https://slack.vllm.ai/) or use the [vLLM Forum](https://discuss.vllm.ai/)
-- For coordinating contributions and development, use `sig-omni`, the forum, or join a [community meeting](meetings.md).
+- For security disclosures, please use GitHub's [Security Advisories](https://github.com/vllm-project/vllm-omni/security/advisories) feature
-
-## Security Disclosures
-
-Do not share vulnerability details in public GitHub issues, pull requests, discussions, or Slack channels. To arrange a private report, send a direct message to one of the [lead maintainers](governance.md#lead-maintainers) in [vLLM Slack](https://slack.vllm.ai/). If you cannot send a direct message, you may post a detail-free request in `sig-omni` asking a lead maintainer to contact you privately; do not include any vulnerability details in that request.

docs/community/governance.md

@@ -52,11 +52,31 @@ Committers have write access and merge rights. They typically have deep expertis
 - [@ZJY0516](https://github.com/ZJY0516): Diffusion attention backend, kernel fusion, and CustomOp
 - [@yuanheng-zhao](https://github.com/yuanheng-zhao): Diffusion cache, offload, and Omni Support
 
-## Reviewer Routing
+## Diffusion Workload Division
 
-For path-based reviewer routing, consult [`.github/CODEOWNERS`](https://github.com/vllm-project/vllm-omni/blob/main/.github/CODEOWNERS). Detailed subsystem boundaries and safe-change guidance live in the [module design documents](../design/index.md#module-design-documents).
+This section breaks down diffusion-related responsibilities. If you have PRs touching these areas, please ping the listed owners for review.
 
-`CODEOWNERS` is operational routing metadata, not a governance or approval policy. Being listed does not grant committer status or merge rights, and it does not mean every listed reviewer must approve a change. The maintainer roster above is authoritative for project roles and merge rights.
+### Runtime-related
+
+- Diffusion models: @RuixiangMa, @wtomin, @xuechendi
+
+### Optimization
+
+- Parallel: @RuixiangMa, @wtomin
+- Attention backend: @ZJY0516
+- Cache: @yuanheng-zhao, @RuixiangMa, @SamitHuang
+- Offload: @yuanheng-zhao
+- Intel GPU support: @xuechendi
+- Quantization: @lishunyang12, @david6666666
+- Kernel fusion / communication-computation: @ZJY0516
+
+### Docs & Test
+
+- Diffusion docs: @RuixiangMa, @wtomin
+
+## Meetings
+
+Committers hold **bi-weekly meetings** to discuss future directions and collaborations of the project.
 
 ## Committer Nomination Process
 

docs/community/meetings.md

@@ -1,8 +0,0 @@
-# Community Meetings
-
-vLLM-Omni hosts developer-facing meetings for Chinese- and English-language audiences. Schedules and access details can change, so use these maintained documents as the source of truth:
-
-- [Chinese-language meeting document](https://docs.google.com/document/d/1pdUBiS_7mdOUNDtdwy-9OUf7jsMWN324BIbps5olDME/edit?tab=t.0)
-- [English-language meeting document](https://docs.google.com/document/d/19AlD08T8uJ7wqfs8VtYCi0iGMTwlTYVVlAxFZ3S7OIg/edit?tab=t.0)
-
-Each document contains the current schedule, access details, agendas, and past meeting notes. For broader vLLM community events, see the [vLLM events calendar](https://vllm.ai/events/).

docs/community/meetups.md

@@ -0,0 +1 @@
+# Meetups

docs/community/volunteers.md

@@ -0,0 +1,12 @@
+# Volunteers for Bugfix and CI
+
+We encourage you to check current docs and [issues](https://github.com/vllm-project/vllm-omni/issues) to find possible solutions for your questions. If non of these can solve it, please propose an issue to describe your questions about bug or CI problems for developing.
+
+If you have urgent need for locating and solving bugfix or CI problems, please find community volunteers below.
+
+| Dec 4-Dec 12 | Dec 15-Dec 19 | Dec 22-Dec 26 | Dec 29- Jan 2, 2026| Jan 5-Jan 9 | Jan 12-Jan 16 |
+|----------|----------|----------|----------|----------|----------|
+| <a href="https://github.com/congw729">Conw729</a> | <a href="https://github.com/yinpeiqi">yinpeiqi</a> | <a href="https://github.com/tzhouam">tzhouam</a> | <a href="https://github.com/SamitHuang">SamitHuang</a> | <a href="https://github.com/gcanlin">gcanlin</a> | <a href="https://github.com/natureofnature">natureofnature</a> |
+| <a href="https://github.com/david6666666">david6666666</a> | <a href="https://github.com/R2-Y">R2-Y</a> | <a href="https://github.com/hsliuustc0106">hsliuustc0106</a> | <a href="https://github.com/Gaohan123">Gaohan123</a> | <a href="https://github.com/ZJY0516">ZJY0516</a> | <a href="https://github.com/qibaoyuan">qibaoyuan</a> |
+
+We kindly welcome more contributors to fix bugs and contribute new features!

docs/contributing/README.md

@@ -3,7 +3,7 @@
 Thank you for your interest in contributing to vLLM-Omni! This document provides guidelines and instructions for contributing.
 
 !!! note
-    vLLM-Omni hosts developer-facing meetings for Chinese- and English-language audiences. See [Community Meetings](../community/meetings.md) for current schedules, access details, agendas, and past notes.
+    We host weekly developer-facing online meetings to discuss milestones and updates **every Tuesday at 19:30 PDT**. Meeting link as well as the past meeting notes can be found [here](https://tinyurl.com/vllm-omni-meeting).
 
 ## Getting Started
 
@@ -76,53 +76,12 @@ Please refer to the [test instructions](./ci/test_execution_guide.md) for detail
 !!! warning
     Currently, not all unit tests pass when run on CPU platforms. If you don't have access to a GPU platform to run unit tests locally, rely on the continuous integration system to run the tests for now.
 
-### Using repository skills with coding agents
-
-vLLM-Omni maintains [repository-scale skills](https://github.com/vllm-project/vllm-omni/tree/main/.claude/skills) for common coding, testing, performance, and review workflows. These skills capture repository-specific structure, validation requirements, and evidence standards that a general coding agent may not know.
-
-If your coding agent discovers repository skills automatically, ask it to use the relevant skill by name. Otherwise, point it to the linked `SKILL.md` and ask it to read the file before changing code. Skills can be combined: use a domain skill for the implementation, `vllm-omni-test` for test and CI decisions, and `precheck-pr` before opening the pull request.
-
-| Task | Repository skill |
-| --- | --- |
-| Add or extend a diffusion model | [`add-diffusion-model`](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/add-diffusion-model/SKILL.md) |
-| Add or extend a text-to-speech model | [`add-tts-model`](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/add-tts-model/SKILL.md) |
-| Add, select, or debug quantization | [`quantization`](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/quantization/SKILL.md) |
-| Diagnose or optimize diffusion performance | [`diffusion-perf-opt`](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/diffusion-perf-opt/SKILL.md) |
-| Upgrade an NPU model runner | [`vllm-omni-npu-model-runner-upgrade`](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/vllm-omni-npu-upgrade/SKILL.md) |
-| Add a regression test, choose L1-L4 coverage, or wire Buildkite | [`vllm-omni-test`](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/vllm-omni-test/SKILL.md) |
-| Self-check a branch before opening a pull request | [`precheck-pr`](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/precheck-pr/SKILL.md) |
-| Perform a maintainer or reviewer review of an existing pull request or local branch | [`review-pr`](https://github.com/vllm-project/vllm-omni/blob/main/.claude/skills/review-pr/SKILL.md) |
-
-Use the following workflow when collaborating with a coding agent:
-
-1. **Ground the task.** Provide the issue, RFC, or design document that defines the expected behavior. Ask the agent to state its assumptions and identify the affected module or feature contracts before editing code.
-2. **Select the narrowest applicable skills.** Start with the domain skill that owns the change. Add `vllm-omni-test` whenever production behavior or tests change. For a bug fix, ask for the smallest reproducer and a regression test tied to the original symptom.
-3. **Require executable evidence.** Ask the agent to run the narrowest relevant checks and report the exact commands and results. It must identify tests it could not run because of unavailable hardware, model weights, credentials, or dependencies; an unrun check is not a pass.
-4. **Inspect the resulting diff.** Confirm that the implementation stays within the issue or RFC, does not overwrite unrelated work, and includes the required tests, documentation, and benchmark or accuracy evidence.
-5. **Run the pre-submit workflow.** Use `precheck-pr`, then run the applicable local tests and pre-commit hooks before opening the pull request.
-
-For example:
-
-```text
-Use add-diffusion-model and vllm-omni-test to implement the linked issue.
-Read the relevant design documents first, keep the change within the issue,
-and report every test command, result, and hardware validation gap.
-```
-
-```text
-Use vllm-omni-test to turn this bug reproducer into the smallest deterministic
-regression test. Prefer L1 CPU coverage; if the failure requires real weights
-or serving, explain the required L2/L3 environment and provide the exact command.
-```
-
-Repository skills guide the agent, but they do not replace contributor judgment, the accepted issue or RFC, required test evidence, or maintainer review. Review all generated changes before submitting them.
-
 ## Issues
 
 If you encounter a bug or have a feature request, please search existing issues first to see if it has already been reported. If not, please file a new issue, providing as much relevant information as possible.
 
 !!! important
-    Do not report suspected security vulnerabilities through a public issue, pull request, discussion, or Slack channel. Follow the [security disclosure instructions](../community/contact_us.md#security-disclosures) to arrange a private report.
+    If you discover a security vulnerability, please report it by creating a GitHub issue with the `security` label.
 
 ## Pull Requests & Code Reviews
 

docs/contributing/model/adding_tts_model.md

@@ -672,147 +672,100 @@ down and spawn a new one mid-module. A few rules that save real CI debugging tim
 
 ## Online Serving Integration
 
-To expose your model through the `/v1/audio/speech` OpenAI-compatible endpoint, write
+To expose your model through the `/v1/audio/speech` OpenAI-compatible endpoint, add
-one adapter under `vllm_omni/entrypoints/openai/tts_adapters/`. The adapter declares
+**all five** of the following integration points to
-how your model is recognized and owns its request handling; `serving_speech.py` should
+`vllm_omni/entrypoints/openai/serving_speech.py` in a **single commit**. Adding them
-not need an edit.
+piecemeal causes partial-integration failures that are hard to debug.
 
-### 1. Write the adapter
+### 1. Stage constant
 
-Create `vllm_omni/entrypoints/openai/tts_adapters/your_model.py`:
+Near the top of the file, alongside the other `_*_TTS_MODEL_STAGES` constants:
 
 ```python
-# SPDX-License-Identifier: Apache-2.0
+_YOUR_MODEL_TTS_MODEL_STAGES = {"your_model_stage_key"}
-"""YourModel serving adapter."""
+```
 
-from typing import TYPE_CHECKING
+### 2. Union into `_TTS_MODEL_STAGES`
 
-from vllm_omni.entrypoints.openai.tts_adapters import register_tts_adapter
+Add to the `_TTS_MODEL_STAGES` set union:
-from vllm_omni.entrypoints.openai.tts_adapters.base import ARTTSAdapter, PreparedRequest
 
-if TYPE_CHECKING:
+```python
-    from vllm_omni.entrypoints.openai.protocol.audio import OpenAICreateSpeechRequest
+_TTS_MODEL_STAGES: set[str] = (
+    ...
+    | _YOUR_MODEL_TTS_MODEL_STAGES
+)
+```
 
+### 3. Model type detection
 
-@register_tts_adapter
+In `_detect_tts_model_type()`, add before the final `return None`:
-class YourModelAdapter(ARTTSAdapter):
-    # The registry key, and the model-type string used in logs.
-    name = "your_model"
-    # The engine ``model_stage`` value(s) your deployment yaml sets. Detection,
-    # stage discovery and `/v1/audio/speech` routing all derive from this.
-    stage_keys = frozenset({"your_model_stage_key"})
 
-    def validate(self, request: "OpenAICreateSpeechRequest") -> str | None:
+```python
-        """Return an error string, or None if the request is valid."""
+if model_stage in _YOUR_MODEL_TTS_MODEL_STAGES:
+    return "your_model"
+```
+
+### 4. Request validation dispatch
+
+In `_validate_tts_request()`, add before the fallback `return`:
+
+```python
+if self._tts_model_type == "your_model":
+    return self._validate_your_model_request(request)
+```
+
+### 5. Validation and parameter-builder methods
+
+Add two new methods:
+
+```python
+def _validate_your_model_request(
+    self, request: OpenAICreateSpeechRequest
+) -> str | None:
+    """Validate YourModel request. Returns an error string or None."""
     if not request.input or not request.input.strip():
         return "Input text cannot be empty"
     return None
 
-    async def build(
+def _build_your_model_params(
-        self,
+    self, request: OpenAICreateSpeechRequest
-        request: "OpenAICreateSpeechRequest",
+) -> dict[str, Any]:
-        sampling_params_list: list,
+    """Build additional_information dict for YourModel."""
-        has_inline_ref_audio: bool,
+    params: dict[str, Any] = {"text": [request.input]}
-    ) -> PreparedRequest:
-        """Build the engine prompt and per-model parameters."""
-        params: dict[str, list] = {"text": [request.input]}
     if request.voice is not None:
         params["voice"] = [request.voice]
-        return PreparedRequest(
+    # Add any other model-specific fields here
-            prompt={"prompt": request.input},
+    return params
-            tts_params=params,
-            model_type=self.name,
-        )
 ```
 
-Then add it to the import block at the bottom of
+Then wire `_build_your_model_params` into the request-dispatch block in
-`vllm_omni/entrypoints/openai/tts_adapters/__init__.py` so it registers on import.
+`_create_tts_request()` (search for the equivalent `_build_*_params` call for an
-That import line is the only shared file a new model has to touch.
+existing model to find the right location). If the model supports voice cloning
+(`ref_audio` → `prompt_audio_path`, `ref_text` → `prompt_text`), add those mappings
+here too — follow any existing `_build_<model>_params` in `serving_speech.py` (e.g.
+`_build_moss_tts_params` for the voice-cloning variant) for the pattern.
 
-> **Pure-diffusion TTS does not go through adapters yet.** When the server is built
+> **Two dispatch patterns coexist:** Fish Speech uses a `self._is_fish_speech` boolean
-> by `OmniOpenAIServingSpeech.for_diffusion()`, `create_speech()` routes straight to
+> checked *before* `elif self._is_tts`. All newer models use the `_tts_model_type`
-> `_create_diffusion_speech()` and never calls `validate()` or `build()`.
+> string pattern shown above. For new models, always use the string pattern — do not
-> `DiffusionTTSAdapter` is scaffolding for that migration and has no production
+> add new `_is_*` boolean flags.
-> subclass today, so validation or prompt construction placed in one would silently
-> never run. If your model is served by the diffusion engine rather than
-> `engine_client`, follow the existing diffusion path and say so on #4855 — wiring
-> that path through the adapter layer is open work, not something to do inside a
-> new-model PR.
 
-### 2. If a stage key alone cannot identify your model
+> **Note on unused variables:** Only extract parameters in `_build_your_model_params`
-
+> that you actually pass to the model's generate / `inference_stream` call. Extracting
-Two escape hatches, in order of preference:
+> a variable without forwarding it will trigger a `ruff F841` pre-commit failure.
-
-```python
-# The architecture is authoritative (e.g. your model has no dedicated
-# model_stage value, or shares one with another model).
-model_archs = frozenset({"YourModelForConditionalGeneration"})
-
-# Set this too if your model owns NO stage key, so stage discovery has to find
-# your AR entry stage by architecture.
-arch_identifies_entry_stage = True
-```
-
-If your rule is not a set-membership test, override `matches()` — see
-`covo_audio.py`, which shares the generic `fused_thinker_talker` stage key with
-non-CoVo deployments and confirms with the architecture:
-
-```python
-@classmethod
-def matches(cls, model_stage: str | None, model_arch: str | None) -> bool:
-    return super().matches(model_stage, model_arch) and bool(model_arch) and "CovoAudio" in model_arch
-```
-
-If your model can match the same deployment as another adapter, give one of them an
-explicit `detect_priority` (lower runs first). `tests/entrypoints/openai_api/
-test_tts_detection.py` fails if two same-priority detectors can both match one input,
-so an unordered overlap cannot be merged.
-
-Models that are speech-capable only in some deployment topologies override
-`stage_serves_speech()` — see `audex.py`, whose omni thinker is text-final unless the
-speech decoder is deployed alongside it.
-
-### 3. Reuse the shared helpers
-
-Adapters reach shared serving helpers through `self.ctx.server`: reference-audio
-resolution (`_resolve_ref_audio`), uploaded-speaker handling
-(`_apply_uploaded_speaker`), format validation (`_validate_ref_audio_format`), and
-prompt-length limits (`_max_instructions_length`). Read a comparable adapter before
-writing your own — `fish_speech.py` for voice cloning, `higgs_audio_v3.py` for
-parameter-heavy models, `moss_tts.py` for a family sharing one base class.
-
-### 4. Test it
-
-`tests/entrypoints/openai_api/test_tts_adapter.py` covers registry invariants and
-`test_tts_detection.py` covers detection. Add your model to
-`EXPECTED_MODEL_TYPES` in the former, and a case to the latter if you added a
-`model_archs` or `matches()` rule.
-
-### Do not add branches to `serving_speech.py`
-
-Older models predate the adapter framework and still have per-model branches in
-`serving_speech.py`; they are being migrated out (RFC #4327, #4855). Do not copy
-that pattern. `tools/pre_commit/check_tts_adapter.py` is a ratchet on the remaining
-`self._tts_model_type == ...` comparisons and fails the commit if the count grows.
-
-If your model genuinely needs behaviour that no adapter hook can express, that is a
-missing hook — propose it on the RFC rather than adding a branch.
 
 ### Merge conflicts
 
-Your adapter is a new file, so it cannot conflict. The one shared line is your entry
+`serving_speech.py` is modified by every new model PR and is the most common source of
-in the import block at the bottom of `tts_adapters/__init__.py`, which conflicts only
+rebase conflicts. When rebasing onto `main` and a conflict appears here, the resolution
-when another model lands at the same time. The resolution is always to **keep both**
+is always to **keep both** the upstream model's additions and your own — never discard
-imports — never discard either side. After resolving:
+either side. After resolving:
 
 ```bash
-git add vllm_omni/entrypoints/openai/tts_adapters/__init__.py
+git add vllm_omni/entrypoints/openai/serving_speech.py
 git rebase --continue
 ```
 
-If you find yourself resolving a conflict inside `serving_speech.py`, something in
-your model is still going through the legacy path; see the note above.
-
 ## Single-Stage Models
 
 Some TTS models (e.g. MOSS-TTS-Nano) do not use a two-stage pipeline. Instead the

docs/design/architecture_overview.md

@@ -1,6 +1,6 @@
 # Architecture Overview
 
-This document outlines the architecture of vLLM-Omni.
+This document outlines the architectural design for vLLM-Omni.
 
 <p align="center">
   <picture>
@@ -9,456 +9,194 @@ This document outlines the architecture of vLLM-Omni.
   </picture>
 </p>
 
-## Design goals
+# Goals
 
-The primary goal of vLLM-Omni is to provide a fast and easy-to-use inference
+The primary goal of the vLLM-Omni project is to build the fastest and easiest-to-use open-source Omni-Modality model inference & serving engine. vLLM-Omni extends the original vLLM, which was created to support large language models for text-based autoregressive (AR) generation tasks. vLLM-Omni is designed to support:
-and serving engine for omni-modality models. vLLM-Omni extends vLLM's
-text-oriented autoregressive (AR) runtime with stage-based execution for
-non-textual outputs and non-autoregressive model components.
 
-The architecture is designed to:
+* **Non-textual Output:** Enables the integration, efficient processing and output of various data types, including but not limited to, images, audio, video, and action trajectories, alongside text.
+* **Non-Autoregressive Structure:** Support model structure beyond autoregressive, especially Diffusion Transformer (DiT), which is widely used in visual and audio generation.
+* **Integration with vLLM Core:** Maintain compatibility and leverage existing vLLM key modules and optimizations where applicable.
+* **Extensibility:** Design a modular and flexible architecture that can easily accommodate new modalities, model architectures, and output formats.
 
-* support text, image, audio, video, and action inputs and outputs;
-* compose autoregressive, generation, and diffusion stages in one pipeline;
-* reuse vLLM scheduling, cache, distributed-execution, and serving
-  primitives where they fit; and
-* keep model topology, deployment placement, runtime lifecycle, transport,
-  and public API concerns in separate layers.
 
-## Model execution
+# Representative omni-modality models
 
-These four examples show how vLLM-Omni maps model components to stage-local
+According to analysis for current popular open-source models, most of them have the combination of AR+DiT. Specifically, they can be further categorized into 3 types below:
-execution policies. Each summary covers the model-owned path, batching,
-attention, parallelism, quantization, and primary serving targets. The profiles
-are representative; a model may support multiple `PipelineConfig` and
-`DeployConfig` combinations.
 
-| Model | Model-owned path | vLLM-Omni stage view | Primary serving target |
+**DiT as a main structure, with AR as text encoder (e.g.: Qwen-Image)**
-| --- | --- | --- | --- |
+  A powerful image generation foundation model capable of complex text rendering and precise image editing.
-| Qwen3-Omni | Thinker → Talker → Code2Wav | Three stages with asynchronous chunk hand-off | TTFT/TTFP, TPOT, E2EL, audio RTF, and concurrent throughput |
-| HunyuanImage-3.0 | Multimodal AR understanding/reasoning plus image-generation DiT | AR-only, DiT-only, or split AR → DiT deployment | DiT E2EL/denoising latency and image throughput; TTFT/TPOT for AR tasks |
-| MiniMax-H3 | Text encoder → task-specific FL2VA or Ref2VA DiT → video/audio VAE decoder | Three logical component/phase boundaries within one registered diffusion stage | Video/audio E2EL and media throughput; RTF when audio streaming is measured |
-| Cosmos3 | Unified MoT reasoner tower plus diffusion generator tower | One diffusion pipeline materializes both towers inside the stage | Image/video/action E2EL and throughput; RTF for synchronized audio |
-
-### Serving metric vocabulary
-
-The target metric follows the output modality, not just the model name.
-
-| Metric | Meaning in this document | Most useful for |
-| --- | --- | --- |
-| **TTFT** | Time to the first text token | AR reasoning or text output |
-| **TPOT** | Time per output token after the first token | AR decode stages |
-| **TTFP** | Time to the first streamed media packet, such as audio | Interactive speech and multimodal chat |
-| **E2EL** | End-to-end latency from request admission to the final output | Image, video, audio, and action requests |
-| **RTF** | Wall-clock processing time divided by generated audio duration; lower is faster than real time | Audio generation |
-| **Throughput** | Requests, tokens, or media seconds produced per wall-clock second | Offline and concurrent serving |
-
-### Qwen3-Omni: streaming AR pipeline
-
-Qwen3-Omni illustrates a multi-stage streaming AR pipeline: Thinker → Talker →
-Code2Wav. The [technical report](https://arxiv.org/abs/2509.17765) describes
-the model components, and the figure shows the stage-level streaming schedule
-used by vLLM-Omni.
 
 <p align="center">
-  <a href="https://github.com/vllm-project/vllm-omni/blob/main/docs/source/architecture/qwen3-omni-async-chunk.png">
+  <picture>
-    <img alt="Qwen3-Omni Thinker, Talker, and Code2Wav streaming stages" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/qwen3-omni-async-chunk.png" width="80%">
+    <source media="(prefers-color-scheme: dark)" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/dit-main-architecture.png">
-  </a>
+    <img alt="Qwen-Image" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/dit-main-architecture.png" width=30%>
+  </picture>
 </p>
 
-#### Model architecture by stage
+**AR as a main structure, with DiT as multi-modal generator (e.g. BAGEL)**
-
+  A unified multimodal comprehension and generation model, with cot text output and visual generation.
-| Stage | Model component | Stage output |
-| --- | --- | --- |
-| **Thinker** | AuT audio encoder, SigLIP2 vision encoder, and the 30B-total/3B-active Thinker MoE Transformer | Text tokens and conditioning for the Talker |
-| **Talker** | 3B-total/0.3B-active Talker MoE Transformer with the MTP code-prediction path | Text tokens and audio codec tokens |
-| **Code2Wav** | Approximately 200M-parameter ConvNet audio decoder | Waveform/audio chunks |
-
-#### Representative stage execution
-
-| Stage | Batching | Attention and execution | Parallelism | Quantization |
-| --- | --- | --- | --- | --- |
-| **Thinker** | Continuous batching with stage-local `max_num_seqs` and token budgets | vLLM KV-cached AR attention; CUDA Graph execution when the stage is not eager | Independent stage placement; use the AR runtime's configured tensor parallelism | Supported ModelOpt FP8/NVFP4 or AutoRound checkpoint paths target the Thinker; encoders remain BF16 in the documented paths |
-| **Talker** | Continuous batching over autoregressive decode requests | KV-cached token decode with async-chunk output to Code2Wav | Independent stage placement; typically a separate GPU or replica from Thinker | BF16 baseline; no generic Talker quantization path is assumed |
-| **Code2Wav** | Static/chunk batching for codec-to-waveform decode | Non-AR chunked audio decode; eager execution is commonly retained | Separate stage or colocated placement, depending on the deployment | BF16 baseline; keep codec/vocoder precision model-specific |
-
-For this pipeline, the main serving target is interactive responsiveness:
-TTFT for text, TTFP for the first audio packet, TPOT for autoregressive decode,
-E2EL for the complete answer, and RTF/throughput for sustained audio serving.
-Async chunking and streaming primarily reduce TTFP and improve stage overlap;
-batching and CUDA Graphs primarily improve E2EL and throughput. See the
-[Qwen3-Omni recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/Qwen/Qwen3-Omni.md)
-and [async chunk design](feature/async_chunk.md) for the deployment details.
-
-### HunyuanImage-3.0: shared multimodal model, split deployment choices
-
-HunyuanImage-3.0 illustrates a shared multimodal model with flexible AR, DiT,
-and split AR → DiT deployment. The official [technical
-report](https://arxiv.org/abs/2509.23951) provides the model view; the tables
-below map it to vLLM-Omni stages.
 
 <p align="center">
-  <a href="https://github.com/Tencent-Hunyuan/HunyuanImage-3.0/blob/main/assets/framework.png">
+  <picture>
-    <img alt="HunyuanImage-3.0 framework for understanding, language modeling, and image generation" src="https://raw.githubusercontent.com/Tencent-Hunyuan/HunyuanImage-3.0/main/assets/framework.png" width="95%">
+    <source media="(prefers-color-scheme: dark)" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/ar-main-architecture.png">
-  </a>
+    <img alt="Bagel" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/ar-main-architecture.png" width=30%>
+  </picture>
 </p>
 
-#### Model architecture by stage
+**AR+DiT (e.g. Qwen-Omni)**
-
+  A natively end-to-end omni-modal LLM for multimodal inputs (text/image/audio/video...) and outputs (text/audio...).
-| Stage or component | Model component | Stage output |
-| --- | --- | --- |
-| **AR understanding/reasoning** | Understanding and generation encoders feeding the Hunyuan-A13B decoder-only Transformer and text detokenizer | Text responses or image-generation conditioning |
-| **Image generation** | Generation encoder, diffusion prediction path/Gen. Decoder, and the image VAE decode path | Image latents and final images |
-
-The vLLM-Omni deployment may expose the AR path only, the DiT path only, or
-both as an AR → DiT pipeline with a connector between them. That is a runtime
-decomposition of the model's capabilities; it should not be read as a claim
-that the published framework figure contains two unrelated backbones.
-
-#### Representative stage execution
-
-| Stage | Batching | Attention and execution | Parallelism | Quantization |
-| --- | --- | --- | --- | --- |
-| **AR** | Standard vLLM continuous batching when serving understanding/text tasks | KV-cached causal attention | Tensor/expert parallelism follows the selected AR deployment | Checkpoint-specific; do not infer DiT FP8 settings for the AR checkpoint |
-| **DiT + VAE** | Request batching or step-wise batching; Hunyuan step batching with more than one request requires `TORCH_SDPA` | `TORCH_SDPA` is used because the model mixes causal and full attention | Validated profiles include TP4, TP2 + sequence parallelism, TP2 + CFG parallelism, and expert parallelism for MoE weights | Online FP8 and ModelOpt mixed FP8/NVFP4 are documented for the DiT; VAE precision stays separate |
-
-Image generation is therefore measured mainly with per-image E2EL/denoising
-latency, peak memory, and images-per-second throughput. TTFT and TPOT remain
-meaningful for the optional AR understanding path, but they are not the right
-headline metrics for the DiT path. See the
-[HunyuanImage-3.0 recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/Tencent/HunyuanImage-3.0-Instruct.md)
-for the validated batching, attention, and quantization combinations.
-
-### MiniMax-H3: conditioning, denoising, and decode
-
-MiniMax-H3 illustrates logical component and phase boundaries between text
-encoding, task-specific denoising, and media decoding:
-`Text Encoder → DiT → VAE Decoder`. The current registered topology co-locates
-these components in one diffusion stage. These boundaries are useful for
-profiling and offload; independent placement would require a future
-multi-stage `PipelineConfig`. The stage mapping follows the implementation and
-serving recipe; the [release overview](https://minimaxi.com/blog/minimax-h3)
-notes that a detailed technical report is forthcoming.
-
-#### Model architecture by component
-
-| Logical component | Model component | Component output |
-| --- | --- | --- |
-| **Text Encoder** | Tokenizer/processor and Qwen3-VL text encoder; vision/audio references are prepared alongside the text condition | Packed multimodal conditioning for denoising |
-| **DiT** | Task-specific `FL2VA` DiT for text/first-frame generation or `Ref2VA` DiT for mixed references | Video and audio latent tokens |
-| **VAE Decoder** | Video VAE and audio VAE decode the generated latents and assemble the synchronized output | Decoded video frames and stereo waveform, with FPS and audio sample rate metadata |
-
-Both DiT partitions remain behind one task-selection point; `task` chooses
-which partition runs. In the current implementation, the three logical
-components execute inside one diffusion stage. This is different from
-Qwen3-Omni's three independently scheduled stages, even though both models
-produce synchronized audio and video-like outputs.
-
-#### Representative component execution
-
-| Logical component | Batching | Attention and execution | Parallelism | Quantization |
-| --- | --- | --- | --- | --- |
-| **Text Encoder** | The current co-located pipeline follows the diffusion request scheduler; independent prompt/reference batching would require a separate multi-stage topology | Qwen3-VL attention and multimodal preprocessing | `--text-encoder-tp-size N` shards the encoder across the first `N` DiT ranks; independent placement is not part of the current topology | BF16/FP32 baseline; the H3 DiT FP8 path does not quantize the text encoder |
-| **DiT** | The current H3 implementation executes one generation request per diffusion batch; use concurrency for service-level throughput | cuDNN attention for the validated two-GPU consumer profile; TRTLLM attention or FlashAttention-4 on supported Blackwell profiles | TP2 plus text-encoder TP and Ulysses/VAE parallel groups on multi-GPU profiles; DLO/CPU offload trade memory for transfer time | Online FP8 applies to eligible DiT linears and is incompatible with layerwise offload |
-| **VAE Decoder** | Decode follows each generation request; tile/patch work can be distributed even when denoising is not batched | VAE decode kernels rather than DiT attention | VAE patch parallelism and native tiled decode within the diffusion stage | BF16/FP32 baseline; the documented H3 FP8 path leaves both VAEs unchanged |
-
-The primary target is video/audio E2EL and media throughput, with the logical
-component boundaries making prompt encoding, denoising, and VAE decode costs
-separately measurable. RTF is useful when the audio stream is evaluated
-independently. TTFT and TPOT do not describe the main H3 generation path
-because the user-visible output is diffusion media rather than a token stream.
-The
-[MiniMax-H3 recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/MiniMaxAI/MiniMax-H3.md)
-contains the hardware-specific profiles and warmup requirements.
-
-### Cosmos3: unified MoT reasoner and generator
-
-Cosmos3 illustrates a unified Mixture-of-Transformers (MoT) reasoner and
-diffusion generator. The official [technical
-report](https://research.nvidia.com/labs/cosmos-lab/cosmos3/technical-report.pdf)
-and NVIDIA's [technical explanation](https://developer.nvidia.com/blog/develop-physical-ai-reasoning-world-and-action-models-with-nvidia-cosmos-3/)
-provide the two-tower model view used below.
 
 <p align="center">
-  <a href="https://developer.nvidia.com/blog/develop-physical-ai-reasoning-world-and-action-models-with-nvidia-cosmos-3/">
+  <picture>
-    <img alt="Cosmos3 autoregressive reasoner and diffusion generator towers" src="https://developer-blogs.nvidia.com/wp-content/uploads/2026/05/image-11-e1780000686151.webp" width="95%">
+    <source media="(prefers-color-scheme: dark)" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/ar-dit-main-architecture.png">
-  </a>
+    <img alt="Qwen-Omni" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/ar-dit-main-architecture.png" width=30%>
+  </picture>
 </p>
 
-#### Model architecture by stage
+# vLLM-Omni main architecture
 
-| Stage or component | Model component | Stage output |
+<p align="center">
-| --- | --- | --- |
+  <picture>
-| **Reasoner tower** | Autoregressive VLM path with causal attention over language and optional vision/action context; runs once per generation request | Discrete reasoning/context tokens |
+    <source media="(prefers-color-scheme: dark)" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/vllm-omni-main-architecture.png">
-| **Generator tower** | Diffusion path with full attention over the generator tokens and the reasoner K/V context; runs for each denoising step | Image, video, audio, or action tokens |
+    <img alt="vLLM-Omni Main Architecture" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/vllm-omni-main-architecture.png" width=55%>
-| **Shared pipeline** | `Cosmos3OmniDiffusersPipeline` plus modality encoders/decoders and VAE paths | Final image/video/audio or action response |
+  </picture>
+</p>
 
-The reasoner and generator are model-owned components, not two independent
+## Key Components
-vLLM-Omni stages by default. The current Cosmos3 pipeline materializes both
-inside one diffusion stage; model-level CPU offload can swap the reasoner and
-generator components between their phases.
 
-#### Representative stage execution
+| Component         | Description                                                                                                                              |
+| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| **OmniRouter**    | provide an intelligent router for Omni-modality requests dispatch                                                                        |
+| **EntryPoints**   | define the APIs for offline/online serving (APIServer, Omni/AsyncOmni), while `AsyncOmniEngine` and `Orchestrator` coordinate multi-stage AR/DiT execution |
+| **AR**            | adapted for omni-modality models while inheriting efficient features from vLLM, such as cache management                                 |
+| **Diffusion**     | natively implemented and optimized using acceleration components                                                                         |
+| **OmniConnector** | supports fully disaggregation based on E/P/D/G (Encoding/Processing/Decoding/Generation) disaggregation across stages                    |
 
-| Stage | Batching | Attention and execution | Parallelism | Quantization |
+Disaggregated stages are managed through stage configuration. In Qwen3-Omni, Thinker/Talker/Code2wav are declared as separate configured stages, and runtime routing is handled by `Orchestrator` over `StageEngineCoreClient` / `StageDiffusionClient`.
-| --- | --- | --- | --- | --- |
-| **Reasoner + generator pipeline** | Use request batching or step execution only when the selected pipeline advertises that capability; otherwise use `max_num_seqs=1` | Causal attention for reasoner tokens and full attention for diffusion tokens; the validated recipe uses a platform-selected aiter FlashAttention path with `TORCH_SDPA` fallback | Ulysses/context parallelism or tensor parallelism for the transformer; VAE tiling and layerwise/model-level offload address activation and weight memory | Online FP8 is supported for the diffusion pipeline; AutoRound/checkpoint-specific paths and quality validation remain separate from the BF16 baseline |
-
-For Cosmos3, generation E2EL and output throughput are the primary targets.
-Action-policy workloads add a control-loop latency target, while synchronized
-audio workloads add RTF. TTFT/TPOT are appropriate for a reasoner-only service,
-but not for the full diffusion generation path. See the
-[Cosmos3 recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/cosmos3/Cosmos3-Nano.md)
-and [diffusion execution modes](../user_guide/diffusion/execution_modes.md)
-for the current runtime choices.
-
-## Why the stage-based architecture follows from these examples
-
-The four representative pipelines show that omni-modality serving is not one
-execution problem. Autoregressive decoding, diffusion denoising, multimodal
-encoding, and media decoding have different scheduling, attention, parallelism,
-memory, and quantization requirements. The architecture therefore needs a
-unit that can be optimized and resourced independently while remaining part of
-one request pipeline.
-
-| Observation | Design implication | vLLM-Omni response |
-| --- | --- | --- |
-| AR, diffusion, encoder, and decoder components have different execution loops | One scheduler and one execution policy cannot fit every component | Specialized AR, generation, and diffusion stage runtimes |
-| A model can be deployed as AR-only, DiT-only, or AR → DiT | Model structure must be separate from deployment topology | `PipelineConfig` describes logical stages and relationships; `DeployConfig` describes placement and resources |
-| Text encoders, DiTs, and VAE decoders have different batch and memory behavior | Batching, attention, parallelism, and quantization must be stage-local | Each stage carries its own runtime and engine configuration |
-| MiniMax-H3 can co-locate or logically split its text encoder and VAE decoder | A stage boundary should be configurable rather than forcing a process boundary | Logical stages can be co-located or assigned independent runtime placement |
-| Qwen3-Omni transfers hidden states and codec chunks across stages | Large intermediate data needs typed transport and synchronization | `OmniConnector` transports payloads and KV-cache data without owning model routing |
-| Requests span multiple stages and may be cancelled or produce ordered streaming output | Cross-stage request state needs a separate control plane | `Orchestrator` owns correlation, cancellation, routing state, and output ordering |
-| Qwen3-Omni optimizes first-packet latency while image/video models optimize E2EL and throughput | Performance objectives must be model- and stage-aware | TTFT/TPOT/TTFP, E2EL, RTF, and throughput are measured according to the output modality |
-
-This leads to a precise definition of a stage: it is a logical execution unit
-with its own model component, execution policy, resource ownership, and
-performance objectives. A stage is not necessarily a separate process. Cosmos3
-keeps its reasoner and generator inside one diffusion pipeline, while
-MiniMax-H3 exposes useful logical boundaries between text encoding, denoising,
-and VAE decoding. Both are valid mappings of the same abstraction.
-
-The resulting separation can be summarized as:
-
-```text
-Model structure       What is computed and how components are related
-        ↓
-PipelineConfig        Which logical stages exist and how they are connected
-        ↓
-Stage runtime policy  How each stage batches, attends, parallelizes, and quantizes
-        ↓
-DeployConfig           Where stages run, with which devices, replicas, and connectors
-```
-
-`AsyncOmniEngine` and `Orchestrator` coordinate the pipeline, `OmniConnector`
-transports stage outputs, and `StageRuntime` materializes the selected
-placement. This separation lets one logical model support multiple serving
-topologies without coupling model code to process layout or deployment
-resources.
-
-## System architecture
-
-The figure shows the main components of the stage-based runtime: entrypoints,
-the shared `AsyncOmniEngine`, request orchestration, stage lifecycle
-management, AR and diffusion execution modules, model/layer operations,
-connector transport, and multimodal outputs. `AsyncOmniEngine` is the
-composition root between the entrypoints and the orchestrator.
-
-```mermaid
-flowchart TB
-    subgraph omni["vLLM-Omni"]
-        subgraph entry["Entry points"]
-            api["API server"]
-            client["Omni / AsyncOmni"]
-        end
-        engine["AsyncOmniEngine<br/>composition root and background loop"]
-        orchestrator["Orchestrator<br/>request state and cross-stage routing"]
-        runtime["StageRuntime<br/>placement, replicas, readiness, and lifecycle"]
-        ar["AR module<br/>vLLM engine, scheduler, cache, executor, worker, and model runner"]
-        diffusion["Diffusion module<br/>scheduler, worker, model runner, and pipeline"]
-        ops["Model / layer / ops<br/>attention, parallelism, and quantization"]
-        connector["OmniConnector<br/>payload and KV transport plus synchronization"]
-        outputs["Multimodal outputs<br/>streaming chunks and final artifacts"]
-
-        api --> engine
-        client --> engine
-        engine --> orchestrator
-        engine --> runtime
-        orchestrator --> runtime
-        runtime --> ar
-        runtime --> diffusion
-        ar -. uses .-> ops
-        diffusion -. uses .-> ops
-        ar -. transports through .-> connector
-        diffusion -. transports through .-> connector
-        ar --> outputs
-        diffusion --> outputs
-    end
-```
-
-### Key components
-
-| Component | Responsibility |
-| --- | --- |
-| **Entrypoints** | Translate offline, CLI, OpenAI-compatible, and duplex requests into engine operations and render outputs back to public protocols. |
-| **Configuration resolution** | Combines pipeline topology, deployment settings, model metadata, and user overrides into a validated control-plane configuration. |
-| **AsyncOmniEngine** | Owns engine composition, the background event loop, stage initialization, request submission, and output collection. |
-| **Orchestrator** | Owns cross-stage request state, stage-to-stage routing, request correlation, cancellation, and output ordering. It does not own model selection or deployment placement. |
-| **StageRuntime** | Expands logical stages into local or distributed replicas, starts stage clients and processes, and manages readiness, affinity, failure, and shutdown. |
-| **AR runtime** | Extends vLLM's scheduler, KV-cache, worker, and model-runner path for omni-modality inputs and inter-stage outputs. |
-| **Diffusion runtime** | Schedules and executes denoising workloads through diffusion executors, workers, pipelines, acceleration backends, and output materialization. |
-| **OmniConnector** | Transports stage payloads and KV-cache data and provides synchronization. Connectors transport data; they do not choose the next logical stage. |
-| **Multimodal outputs** | `MultimodalPayload` separates tensor content from metadata, while `OmniRequestOutput` carries pipeline and diffusion results through the common output path. |
-
-## Configuration and runtime resolution
-
-The control plane has five conceptual layers. Authoring inputs are resolved
-once into a complete, transport-safe configuration before runtime processes are
-started. This keeps stage topology and model capabilities distinct from
-deployment placement and from process-local engine objects.
-
-The figure shows only the primary hand-off object for each layer; the detailed
-inputs, fields, and ownership rules are described below.
-
-```mermaid
-flowchart TB
-    layer1["Layer 1 · Authoring inputs<br/>PipelineConfig + DeployConfig"]
-    layer2["Layer 2 · Resolve once<br/>StageConfigFactory.create_from_model()<br/>VllmOmniConfig.from_pipeline_config()"]
-    layer3["Layer 3 · Transport-safe control plane<br/>VllmOmniConfig"]
-    layer4["Layer 4 · Runtime launch planning<br/>StageRuntime"]
-    layer5["Layer 5 · Engine materialization<br/>VllmConfig / OmniDiffusionConfig"]
-
-    layer1 --> layer2 --> layer3 --> layer4 --> layer5
-```
-
-The single resolution boundary is implemented by
-`StageConfigFactory.create_from_model()` and
-`VllmOmniConfig.from_pipeline_config()` in
-[`vllm_omni/config`](https://github.com/vllm-project/vllm-omni/tree/main/vllm_omni/config).
-The legacy `stage_args` YAML path remains only for models that have not yet
-migrated to `PipelineConfig` and `DeployConfig`.
-
-In the typed path, each stage configuration derives from
-`BaseVllmOmniStageConfig` and is specialized as
-`VllmOmniARStageConfig`, `VllmOmniGenerationStageConfig`, or
-`VllmOmniDiffusionStageConfig`. The request and engine-spec fields belong to the
-control-plane boundary; the current implementation stores their equivalent
-projections in the structured stage configuration and materializes
-backend-specific engine objects during stage initialization.
-
-The important ownership rules are:
-
-1. `PipelineConfig` is the source of truth for stage topology, execution type,
-   model capabilities, and stage relationships.
-2. `DeployConfig` describes placement, replicas, devices, connectors, and
-   deploy-time defaults; it does not redefine the model graph.
-3. CLI and Python overrides are applied at the resolution boundary, with
-   per-stage overrides taking precedence over global values where supported.
-4. `StageRuntime` owns launch planning and replica lifecycle. `ReplicaInitPlan`
-   is runtime-private state, not a user configuration object.
-5. `VllmConfig` and the enriched `OmniDiffusionConfig` are materialized in the
-   process that owns the corresponding engine.
 
 ## Main features
 
-The feature surface is grouped to match the
+vLLM-Omni aims to be fast, flexible, and easy to use with the following features:
-[feature design documents](index.md#feature-design-documents). This page
-summarizes each feature's architectural role; the linked design document is
-the source for configuration, compatibility, and implementation details.
 
-### Runtime and stage execution
+### Performance and Acceleration
 
-* **Disaggregated inference:** Logical stages can run in separate processes,
+The framework achieves high performance through several optimization techniques:
-  devices, or nodes while the orchestrator preserves their declared
-  relationships. `OmniConnector` implementations transfer stage data and
-  control-plane metadata. See [Disaggregated Inference](feature/disaggregated_inference.md).
-* **Asynchronous stage and output execution:** [Async Chunk](feature/async_chunk.md)
-  forwards partial stage outputs as they become available. [Async Diffusion
-  Output](feature/async_diffusion_output.md) overlaps device-to-host output
-  packing with the next diffusion request, while [Async Omni Output
-  Materialization](feature/omni_async_output_materialization.md) moves
-  CPU-side payload construction off the AR decode critical path.
-* **Automatic prefix caching:** [Automatic Prefix Caching in Omni Models](feature/prefix_caching.md)
-  reuses KV-cache-aligned stage outputs and multimodal tensors for requests
-  with common prefixes.
 
-### Communication
+* **Efficient AR Support:** Leverages efficient KV cache management inherited from vLLM.
+* **Pipelined Execution:** Uses pipelined stage execution overlapping to ensure high throughput.
+* **Full Disaggregation:** Relies on the OmniConnector and dynamic resource allocation across stages.
+* **Diffusion Acceleration:** Includes integrated support for diffusion acceleration. This is managed by the acceleration layer, which handles:
+    * **Cache:** Includes DBCache, TeaCache and third-party integration(e.g., [cache-dit](https://github.com/vipshop/cache-dit)).
+    * **Parallelism:** Supports TP, CP, USP, and CFG.
+    * **Attention:** Provides an interface for third-party integration (e.g., FA3, SAGE, MindIE-SD).
+    * **Quantization:** Supports various quantization implementations including FP8 and AWQ.
+    * **FusedOps:** Allows for custom and third-party integration.
 
-* **OmniConnector transport:** The connector contract carries tensors, KV-cache
+### Classifier-Free Guidance (CFG) Companion Flow
-  data, and transport metadata across stage boundaries. The available
-  implementations cover shared memory and multi-node Mooncake, Mori, and
-  Yuanrong transports; see [Disaggregated Inference](feature/disaggregated_inference.md)
-  for the connector choices and configuration model.
 
-### Diffusion acceleration
+vLLM-Omni natively models Classifier-Free Guidance (CFG) across disaggregated multi-stage setups via a "companion request" paradigm, eliminating redundant textual/multimodal context computation boundaries:
+1. **Prompt Expansion:** In the initial autoregressive (AR) stage, a customized `prompt_expand_func` hook intercepts incoming generation prompts and pairs them directly with negative companion prompts (e.g., a default negative prompt) on the fly, tagging the secondary prompt with a specific internal role (`cfg_text`).
+2. **Synchronized KV Cache Transfer:** The AR stage evaluates both the primary and companion sequence batches concurrently. The `OmniConnector` captures these specific structural dependencies and reliably passes the positive and negative outcome KV caches seamlessly across stage boundaries via shared memory or network protocols.
+3. **KV Cache Collection & Injection:** Upon reaching the downstream Diffusion (DiT) Engine, an assigned `cfg_kv_collect_func` automatically intercepts the mapped companion caches (`cfg_text_past_key_values`). These auxiliary dependencies are natively gathered and seamlessly bound to the primary generation sequence variables, enabling the DiT Engine to cleanly implement cross-attention CFG guidance over accurate conditioning and unconditioning structures in parallel.
 
-* **Request and step batching:** [Diffusion Continuous Batching](feature/diffusion_continuous_batching.md)
+### Flexibility and Usability
-  defines request-batch and step-batch execution, scheduler admission, and the
-  common streaming output path.
-* **Composable parallelism:** Diffusion stages can combine [CFG-Parallel](feature/cfg_parallel.md),
-  [Expert Parallel](feature/expert_parallel.md), [HSDP](feature/hsdp.md),
-  [Pipeline Parallel](feature/pipeline_parallel.md), [Sequence Parallel](feature/sequence_parallel.md),
-  [Tensor Parallel](feature/tensor_parallel.md), and [VAE Parallel](feature/vae_parallel.md)
-  according to the pipeline and hardware topology.
-* **Attention and cache acceleration:** [Skip-Softmax](feature/skip_softmax.md),
-  [Cache-DiT](feature/cache_dit.md), and [TeaCache](feature/teacache.md)
-  provide backend and denoising-step optimizations without changing the
-  stage contract.
-* **Quantization and memory efficiency:** [Quantization](feature/quantization.md)
-  resolves per-pipeline or per-component quantization configurations, while
-  [Distributed Layerwise Offload](feature/distributed_layerwise_offload.md)
-  streams diffusion blocks from host memory within the existing parallel
-  topology.
 
-## Interfaces
+vLLM-Omni is designed to be flexible and straightforward for users:
 
-The public interfaces map onto the same engine and stage boundaries:
+* **Heterogeneous Pipeline Abstraction:** Manages complex model workflows effectively.
+* **Hugging Face Integration:** Offers seamless integration with popular Hugging Face models.
+* **Distributed Inference:** Supports tensor, pipeline, data, and expert parallelism.
+* **Streaming Outputs:** Supports streaming outputs.
+* **Unified API:** Provides a consistent and unified API interface compatible with vLLM.
+* **OpenAI-compatible API Server:** Includes a FastAPI-based server for online serving that is compatible with the OpenAI API.
+
+# Interface design
+
+If you use vLLM, then you know how to use vLLM-Omni from Day 0:
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/vllm-omni-user-interface.png">
+    <img alt="vLLM-Omni interface design" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/docs/source/architecture/vllm-omni-user-interface.png" width=55%>
+  </picture>
+</p>
+
+Taking **Qwen3-Omni** as an example:
+
+## Offline Inference
+The **Omni** class provides a Python interface for offline batched inference. Users initialize the Omni class with a Hugging Face model name and use the generate method, passing inputs that include both text prompts and multi-modal data:
 
-```mermaid
-flowchart LR
-    offline["Offline Python<br/>Omni.generate()"] --> engine["AsyncOmniEngine"]
-    online["OpenAI-compatible serving<br/>vllm serve ... --omni"] --> engine
-    duplex["Experimental duplex WebSocket<br/>/v1/duplex or realtime duplex"] --> engine
-    engine --> stages["Configured AR and diffusion stages"]
-    stages --> result["Streaming or final multimodal output"]
 ```
-
+# Create an omni runtime with HF model name.
-### Offline inference
-
-The **Omni** class provides a Python interface for offline batched inference:
-
-```python
 from vllm_omni.entrypoints.omni import Omni
 
 omni = Omni(model="Qwen/Qwen3-Omni-30B-A3B-Instruct")
 
-om_inputs = {
+# Example prompts.
-    "prompt": prompt,
+om_inputs = {"prompt": prompt,
              "multi_modal_data": {
                  "video": video_frames,
                  "audio": audio_signal,
-    },
+             }}
-}
 
+# Generate texts and audio from the multi-modality inputs.
 outputs = omni.generate(om_inputs, sampling_params_list)
 ```
 
-### Online serving
+## Online Serving
+Similar to vLLM, vLLM-Omni also provides a FastAPI-based server for online serving. Users can launch the server using the vllm serve command with the `--omni` flag:
 
-The OpenAI-compatible server uses the same stage configuration and engine
+```
-boundaries:
-
-```bash
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091
 ```
 
-For example, a Qwen3-Omni chat request can contain text, image, audio, or
+Users can send requests to the server using curl:
-video content and a `sampling_params_list` for its configured stages. See the
-[Qwen3-Omni serving example](../user_guide/examples/online_serving/qwen3_omni.md)
-and the [examples](https://github.com/vllm-project/vllm-omni/tree/main/examples)
-for complete requests.
 
-Some pipelines expose additional OpenAI-compatible endpoints, such as joint
+```
-video/audio generation. Endpoint support remains model-specific; consult the
+# prepare user content
-relevant model guide before assuming that every OpenAI route applies to every
+user_content='[
-pipeline.
+        {
+          "type": "video_url",
+          "video_url": {
+            "url": "'"$SAMPLE_VIDEO_URL"'"
+          }
+        },
+        {
+          "type": "text",
+          "text": "Why is this video funny?"
+        }
+      ]'
+    sampling_params_list='[
+      '"$thinker_sampling_params"',
+      '"$talker_sampling_params"',
+      '"$code2wav_sampling_params"'
+    ]'
+    mm_processor_kwargs="{}"
+
+# send the request
+curl -sS -X POST http://localhost:8091/v1/chat/completions \
+    -H "Content-Type: application/json" \
+    -d @- <<EOF
+{
+  "model": "Qwen/Qwen3-Omni-30B-A3B-Instruct",
+  "sampling_params_list": $sampling_params_list,
+  "mm_processor_kwargs": $mm_processor_kwargs,
+  "messages": [
+    {
+      "role": "system",
+      "content": [
+        {
+          "type": "text",
+          "text": "You are Qwen, a virtual human developed by the Qwen Team, Alibaba Group, capable of perceiving auditory and visual inputs, as well as generating text and speech."
+        }
+      ]
+    },
+    {
+      "role": "user",
+      "content": $user_content
+    }
+  ]
+}
+```
+
+For more usages, please refer to [examples](https://github.com/vllm-project/vllm-omni/tree/main/examples).

docs/design/feature/vae_parallel.md

@@ -1,57 +1,42 @@
-# VAE Parallel
+# VAE Patch Parallelism
 
-This document defines the VAE parallelism strategy contract and describes how to
+This document describes how to add **VAE Patch Parallelism** support to a diffusion model.
-add a strategy to a diffusion model. Tile/patch parallelism is the portable
+We use **Qwen-Image** as the reference implementation for decode parallel, and **Wan2.2** for encode parallel.
-baseline. Spatial-shard parallelism is a model-specific decode strategy that can
-be selected explicitly or through a request-aware policy.
-
-We use **Qwen-Image** as the reference implementation for tile-parallel decode,
-**Wan2.2** for tile-parallel encode, and **Wan2.2** as the first spatial-shard
-decode implementation. Other VAE families can add spatial strategies later
-without changing the public mode meanings defined here.
 
 ---
 
 ## Table of Contents
 
 - [Overview](#overview)
-- [Strategy Selection Contract](#strategy-selection-contract)
+- [Step-by-Step Implementation (Decode)](#step-by-step-implementation-decode)
-- [Tile/Patch Implementation (Decode)](#tilepatch-implementation-decode)
+- [Encode Parallel Implementation](#encode-parallel-implementation)
-- [Tile/Patch Encode Implementation](#tilepatch-encode-implementation)
 - [Testing](#testing)
 - [Reference Implementations](#reference-implementations)
-- [Spatially-Sharded Decode](#spatially-sharded-decode)
-- [Adding Another VAE Strategy](#adding-another-vae-strategy)
 - [Summary](#summary)
 
 ---
 
 ## Overview
 
-### What is VAE parallelism?
+### What is Vae Patch parallel?
 
-VAE parallelism distributes VAE **encoding** or **decoding** across multiple
+**VAE Patch Parallelism** is an acceleration technique for both **encoding** and **decoding**. Instead of processing the entire tensor at once, the tensor is:
-ranks. The implementation currently has two strategy families:
 
-| Strategy | Unit of work | Communication | Current scope |
++ Split into multiple spatial tiles
-|----------|--------------|---------------|---------------|
-| Tile/patch | Independent overlapping tiles | Gather, stitch, and optionally broadcast | Encode and decode across supported distributed VAEs |
-| Spatial shard | One feature map sharded along a spatial axis | Per-layer halo exchange followed by output gather | Wan decode |
 
-Both strategies preserve the model-specific receptive field and reconstruct the
++ Distributed across multiple ranks
-same logical output as single-rank execution. They differ in how work is divided:
-tile parallelism assigns complete overlapping tiles to ranks, while spatial
-sharding keeps one logical feature map partitioned throughout the decoder.
 
-This approach can:
++ Encoded/Decoded in parallel
 
-+ Distribute computation across multiple devices
++ Merged to reconstruct the final output
-+ Reduce peak memory usage per device
-+ Accelerate encoding or decoding latency
 
-The actual benefit depends on shape, topology, communication cost, and VAE
+This approach:
-architecture. A strategy must not become the global default without parity and
+
-performance evidence on its supported models.
++ Distributes computation across multiple devices
+
++ Reduces peak memory usage per device
+
++ Accelerates encoding/decoding latency
 
 ### When to Use Encode vs Decode Parallel
 
@@ -60,16 +45,8 @@ performance evidence on its supported models.
 | **Decode Parallel** | Text-to-Image, Text-to-Video | Latent → Image/Video |
 | **Encode Parallel** | Image-to-Video (I2V) | Image → Latent (for conditioning) |
 
-### Architecture and ownership
+### Architecture
-
+We introduce **DistributedVaeExecutor** as the core component responsible for distributed VAE encoding/decoding.
-`DiffusionParallelConfig.vae_parallel_mode` carries the public strategy request.
-The shared registry forwards that value to the VAE, but each distributed VAE
-adapter owns its supported modes, request-shape selection, topology validation,
-and fallback behavior. Model-specific policy must not be added to the shared
-runner or registry.
-
-**DistributedVaeExecutor** is the model-agnostic core for tile-parallel VAE
-encoding and decoding.
 
 The executor is model-agnostic and accepts three function parameters:
 
@@ -99,11 +76,6 @@ This design separates:
 
 + Model-specific tiling and merging logic
 
-Spatial-shard implementations use the same configured VAE process group but do
-not use the tile task executor. They keep the feature map sharded across decoder
-layers and own their halo-exchange and final-gather contracts inside the model's
-distributed autoencoder implementation.
-
 #### Why split / exec / merge is necessary?
 
 The latent tensor cannot be arbitrarily partitioned.
@@ -120,34 +92,7 @@ Therefore:
 
 + Merge must perform blending to avoid seams
 
-## Strategy Selection Contract
+## Step-by-Step Implementation (Decode)
-
-`vae_parallel_mode="tile"` is the compatibility-preserving global default.
-Other values are stable strategy requests, but support remains model-specific.
-
-| Mode | Meaning | Current implementation | Unsupported or ineligible request |
-|------|---------|------------------------|-----------------------------------|
-| `tile` | Use the existing tile/patch executor | All distributed VAE adapters | Not applicable |
-| `auto` | Let the VAE adapter select a validated strategy for each request | Wan decode selects height or width spatial sharding | Wan uses tile when ineligible; unsupported VAE families reject or document their fallback |
-| `spatial_shard_height` | Force spatial-shard decode along height | Wan decode | Wan warns and uses tile when ineligible; unsupported VAE families reject |
-| `spatial_shard_width` | Force spatial-shard decode along width | Wan decode | Wan warns and uses tile when ineligible; unsupported VAE families reject |
-
-The shared configuration layer validates the mode name. It does not decide
-whether a model supports that mode. A VAE adapter adding a mode must:
-
-1. Keep `tile` as an exact feature-off path.
-2. Select a strategy per request rather than from stale process-global state.
-3. Validate input rank/shape and process-group membership before collectives.
-4. Reject or explicitly fall back from unsupported combinations; never silently
-   reinterpret one forced strategy as another.
-5. Preserve direct encode/decode behavior when Diffusers does not select a tiled
-   path.
-
-`auto` is a policy hook, not a universal heuristic. Each VAE family may select
-from only the strategies it has validated. Adding another family must not change
-Wan's selector or the meanings of the explicit modes.
-
-## Tile/Patch Implementation (Decode)
 
 ### Step 1: Implement DistributedAutoencoderKLQwenImage
 `QwenImagePipeline` use `AutoencoderKLQwenImage` for vae, so implement a distributed version:
@@ -306,7 +251,7 @@ class YourModelPipeline(nn.Module):
 +       ).to(self.device)
 ```
 
-## Tile/Patch Encode Implementation
+## Encode Parallel Implementation
 
 For models that require VAE encoding (e.g., Image-to-Video), you can also parallelize the encode operation. We use **Wan2.2** as the reference implementation.
 
@@ -504,24 +449,18 @@ Complete examples in the codebase:
 
 ---
 
-## Spatially-Sharded Decode
+## Spatially-Sharded Decode (Wan)
 
-The tile-parallel executor above assigns independent spatial **tiles** to ranks.
+The tile-parallel executor above assigns independent spatial **tiles** to ranks. The Wan VAE additionally supports a **spatially-sharded decode** backend, selected through `DiffusionParallelConfig.vae_parallel_mode` (`"spatial_shard_height"` or `"spatial_shard_width"`; default is `"tile"`).
-A spatial-shard backend instead partitions one global decoder feature map along
-height or width. Wan is the first supported implementation.
-
-`DiffusionParallelConfig.vae_parallel_mode="tile"` remains the default. For Wan,
-opt into request-shape selection with `"auto"`, or force an axis with
-`"spatial_shard_height"` or `"spatial_shard_width"`.
 
 ### How it differs from tile parallel
 
-| Aspect | Tile parallel (`"tile"`) | Automatic (`"auto"`) | Spatially-sharded (`"spatial_shard_height"`/`"spatial_shard_width"`) |
+| Aspect | Tile parallel (`"tile"`) | Spatially-sharded (`"spatial_shard_height"`/`"spatial_shard_width"`) |
-|--------|--------------------------|----------------------|-----------------------------------------------|
+|--------|--------------------------|-----------------------------------------------|
-| Unit of work | Independent overlapping tiles | Chooses tile or a spatial shard per request | A single global feature map sharded along H or W |
+| Unit of work | Independent overlapping tiles | A single global feature map sharded along H or W |
-| Cross-rank communication | Gather tiles to rank 0, stitch + blend | Depends on the selected path | Per-conv **halo exchange** of boundary rows/cols (P2P) |
+| Cross-rank communication | Gather tiles to rank 0, stitch + blend | Per-conv **halo exchange** of boundary rows/cols (P2P) |
-| Output assembly | Blend overlapping tiles | Depends on the selected path | All-gather shards on rank 0, trim padding (matches `broadcast_result=False`) |
+| Output assembly | Blend overlapping tiles | All-gather shards on rank 0, trim padding (matches `broadcast_result=False`) |
-| Scope | Decode + encode | Wan decode selection; encode remains tiled | Wan decode only |
+| Scope | Decode + encode | Decode only |
 
 Spatial-shard decode swaps the decoder's spatial convolutions/padding for halo-exchanging variants (`WanDistConv2d`, `WanDistCausalConv3d`, `WanDistZeroPad2d`) so each rank only holds a shard of the activations but still sees the correct receptive field at shard boundaries. Implementation lives in `vllm_omni/diffusion/distributed/autoencoders/wan_spatial_shard.py`.
 
@@ -537,65 +476,21 @@ serve.py (--vae-parallel-mode) / OmniEngineArgs
   -> DistributedAutoencoderKLWan.tiled_decode dispatch
 ```
 
-`DistributedAutoencoderKLWan._spatial_shard_decode_enabled()` gates the path: it
+`DistributedAutoencoderKLWan._spatial_shard_decode_enabled()` gates the path: it requires distributed decode to be enabled, a 5D latent, and `vae_patch_parallel_size == DiT group size`. Otherwise it logs a warning and falls back to tile-parallel decode.
-requires distributed decode to be enabled, a 5D latent, and
-`vae_patch_parallel_size == DiT group size`. The method is reached only after
-Diffusers has selected tiled decode for the request. In `auto` mode the longer
-axis that can cover every rank is selected, with width winning ties. If neither
-axis can cover the group, auto mode uses tile decode. This policy is cached only
-through normal kernel shape caches; it is reevaluated for every request.
 
 ### Notes
 
-- The decoder is patched **in place** the first time spatial-shard decode runs. Its wrappers consult a context-local split dimension and retain an exact direct fallback, allowing later requests to select tile, height, or width safely.
+- The decoder is patched **in place** the first time spatial-shard decode runs and is bound to a single split dimension for the lifetime of the VAE instance.
 - Numerical correctness vs. single-GPU decode is covered by `tests/diffusion/distributed/test_wan_spatial_shard.py::test_spatial_shard_decode_matches_reference` (multi-GPU, nightly `full_model` + `distributed_cuda`).
 
-## Adding Another VAE Strategy
-
-Add future strategies through the distributed autoencoder that owns the model
-semantics. Do not add model-name dispatch to the shared runner, registry, or
-`DistributedVaeExecutor`.
-
-For a new VAE family:
-
-1. **Declare capability**: document which modes, operations, shapes, dtypes, and
-   process-group layouts the adapter supports.
-2. **Implement model-local selection**: keep `auto` policy and explicit-mode
-   dispatch in the distributed autoencoder. The selector may use request shape,
-   but must be deterministic and side-effect free.
-3. **Preserve the baseline**: retain exact tile/direct fallbacks and state-dict
-   compatibility. Structural wrappers must not register duplicate parameters or
-   alter checkpoint names.
-4. **Define communication**: derive shards from the configured VAE group, keep
-   collectives symmetric, specify padding/halo ownership, and return the same
-   output placement as the tile path.
-5. **Bound request state**: make the selected axis and scratch buffers
-   request-scoped, release temporary buffers on success and failure, and support
-   alternating modes in one long-lived worker.
-6. **Validate independently**: compare each explicit strategy against the
-   single-rank reference, then test `auto`, tile fallback, unsupported topology,
-   and a mixed request sequence. Record per-rank peak memory and decode latency
-   before documenting a preferred mode.
-
-Promote a selector into shared infrastructure only after at least two VAE
-families use the same inputs, invariants, fallback behavior, and lifecycle. Until
-then, shared code owns transport and configuration while each model adapter owns
-policy.
-
 ---
 
 ## Summary
 
-Adding VAE parallel support to a diffusion model:
+Adding VAE Patch Parallel support to diffusion model:
 
-1. **Implement the distributed VAE** - Inherit from the base VAE class and
+1. **Implement Distributed VAE** - Inherit from base VAE class and `DistributedVaeMixin`
-   `DistributedVaeMixin`.
+2. **Decode Parallel** - Refactor `tiled_decode` into `tile_split`/`tile_exec`/`tile_merge`
-2. **Keep tile as the baseline** - For tile decode, refactor `tiled_decode` into
+3. **Encode Parallel** (optional) - Implement `encode_tile_split`/`encode_tile_exec`/`encode_tile_merge` for I2V models
-   `tile_split`/`tile_exec`/`tile_merge`.
+4. **Change VAE model in pipeline** - Use the distributed version
-3. **Add encode parallelism when needed** - Implement
+5. **Test** - Verify numerical consistency with `vae_patch_parallel_size=1` vs `N`
-   `encode_tile_split`/`encode_tile_exec`/`encode_tile_merge` for I2V models.
-4. **Add model-specific strategies locally** - Own selectors, topology checks,
-   communication, and fallback in the distributed autoencoder.
-5. **Wire the pipeline** - Replace the pipeline VAE with its distributed version.
-6. **Test strategy and lifecycle parity** - Compare one rank with every supported
-   strategy, including feature-off, fallback, and mixed-request sequences.

docs/design/index.md

@@ -11,10 +11,6 @@ in the active navigation.
 
 ## Feature Design Documents
 
-For user-facing configuration and current compatibility, see the
-[Features overview](../features/README.md). A design document defines an
-implementation contract; it is not, by itself, a general support claim.
-
 ### Runtime and stage execution
 
 - [Disaggregated Inference](feature/disaggregated_inference.md)
@@ -34,10 +30,6 @@ implementation contract; it is not, by itself, a general support claim.
 - [Yuanrong Store Connector](feature/omni_connectors/yuanrong_connector.md)
 - [Yuanrong Transfer Engine Connector](feature/omni_connectors/yuanrong_transfer_engine_connector.md)
 
-### Quantization
-
-- [Quantization](feature/quantization.md)
-
 ### Diffusion acceleration
 
 #### Parallelism
@@ -48,16 +40,16 @@ implementation contract; it is not, by itself, a general support claim.
 - [Pipeline Parallel](feature/pipeline_parallel.md)
 - [Sequence Parallel](feature/sequence_parallel.md)
 - [Tensor Parallel](feature/tensor_parallel.md)
-- [VAE Parallel](feature/vae_parallel.md)
+- [VAE Patch Parallelism](feature/vae_parallel.md)
 
-#### Attention optimization
+#### Attention Backends
-
-The [Diffusion Attention Backends](../user_guide/diffusion/attention_backends.md)
-guide lists all selectable backends and their platform defaults. Skip-Softmax
-is the backend-related optimization with a standalone feature-design contract:
 
 - [Skip-Softmax](feature/skip_softmax.md)
 
+#### Quantization
+
+- [Quantization](feature/quantization.md)
+
 - [Cache-DiT](feature/cache_dit.md)
 - [TeaCache](feature/teacache.md)
 - [Diffusion Continuous Batching](feature/diffusion_continuous_batching.md)

docs/design/metrics.md

@@ -1,6 +1,6 @@
 # Prometheus Metrics Design
 
-This document describes how vLLM-Omni exposes Prometheus metrics for multi-stage pipelines, the constraints that shaped the design, and how the pipeline-level metrics coexist with upstream vLLM per-engine metrics.
+This document describes how vLLM-Omni exposes Prometheus metrics for multi-stage pipelines, the constraints that shaped the design, and how the pipeline-level metrics coexist with upstream vLLM per-engine metrics. This iteration covers the text and audio surface; diffusion / image / video families land in a follow-up.
 
 ## Objectives
 

docs/design/module/ar_runtime.md

@@ -7,7 +7,6 @@ owners:
   - "@yinpeiqi"
   - "@fake0fan"
   - "@Sy0307"
-  - "@Gaohan123"
 primary_code_paths:
   - vllm_omni/core/**
   - vllm_omni/worker/**

docs/design/module/benchmarking.md

@@ -4,7 +4,6 @@ kind: module
 status: draft
 owners:
   - "@alex-jw-brooks"
-  - "@Bounty-hunter"
 primary_code_paths:
   - vllm_omni/benchmarks/**
   - vllm_omni/entrypoints/cli/benchmark/**

docs/design/module/cache_management.md

@@ -5,7 +5,6 @@ status: draft
 owners:
   - "@Isotr0py"
   - "@princepride"
-  - "@SamitHuang"
 primary_code_paths:
   - vllm_omni/diffusion/cache/**
 related_code_paths:

docs/design/module/diffusion/diffusion_model_integration.md

@@ -3,10 +3,9 @@ title: Diffusion Model Integration
 kind: module
 status: draft
 owners:
-  - "@fhfuih"
+  - "@Isotr0py"
-  - "@Bounty-hunter"
   - "@wtomin"
-  - "@RuixiangMa"
+  - "@ZJY0516"
 primary_code_paths:
   - vllm_omni/diffusion/models/**
   - vllm_omni/diffusion/model_loader/**

docs/design/module/diffusion/diffusion_runtime.md

@@ -6,7 +6,6 @@ owners:
   - "@Isotr0py"
   - "@princepride"
   - "@SamitHuang"
-  - "@fhfuih"
 primary_code_paths:
   - vllm_omni/diffusion/sched/**
   - vllm_omni/diffusion/executor/**

docs/design/module/diffusion/offloader.md

@@ -4,8 +4,7 @@ kind: module
 status: draft
 owners:
   - "@yuanheng-zhao"
-  - "@david6666666"
+  - "@Isotr0py"
-  - "@lishunyang12"
 primary_code_paths:
   - vllm_omni/diffusion/offloader/**
 related_code_paths:

docs/design/module/diffusion/parallelism.md

@@ -6,7 +6,6 @@ owners:
   - "@princepride"
   - "@yuanheng-zhao"
   - "@xuechendi"
-  - "@Bounty-hunter"
 primary_code_paths:
   - vllm_omni/diffusion/distributed/**
   - vllm_omni/diffusion/attention/parallel/**

docs/design/module/entrypoints.md

@@ -6,7 +6,6 @@ architecture_state: current-plus-in-flight
 owners:
   - "@alex-jw-brooks"
   - "@linyueqian"
-  - "@NickCao"
 document_stewards:
   - "@hsliuustc0106"
   - "@Gaohan123"

docs/design/module/execution_platforms.md

@@ -8,15 +8,8 @@ owners:
   - "@xuechendi"
 primary_code_paths:
   - vllm_omni/platforms/**
+related_code_paths:
   - vllm_omni/attention/**
-primary_code_path_owners:
-  # Additional owners scoped to attention kernels (quantized/custom attention)
-  - paths:
-      - vllm_omni/attention/**
-    owners:
-      - "@david6666666"
-      - "@lishunyang12"
-related_code_paths: []
 depends_on:
   - ar_runtime.md
   - diffusion/index.md

docs/design/module/input_output_modality_contracts.md

@@ -6,8 +6,6 @@ architecture_state: current
 owners:
   - "@Sy0307"
   - "@amy-why-3459"
-  - "@Gaohan123"
-  - "@alex-jw-brooks"
 document_stewards:
   - "@hsliuustc0106"
   - "@Gaohan123"

docs/design/module/model_integration.md

@@ -9,14 +9,6 @@ primary_code_paths:
   - vllm_omni/model_executor/**
   - vllm_omni/model_extras/**
   - vllm_omni/plugins/**
-primary_code_path_owners:
-  # Additional owners scoped to a sub-path of model_executor/**
-  - paths:
-      - vllm_omni/model_executor/models/**
-    owners:
-      - "@Sy0307"
-      - "@amy-why-3459"
-      - "@linyueqian"
 related_code_paths:
   - vllm_omni/transformers_utils/**
   - vllm_omni/tokenizers/**

docs/design/module/observability.md

@@ -4,7 +4,6 @@ kind: module
 status: draft
 owners:
   - "@lishunyang12"
-  - "@vraiti"
 primary_code_paths:
   - vllm_omni/metrics/**
 related_code_paths:

docs/features/README.md

@@ -1,67 +0,0 @@
-# Features
-
-Use this section to choose and configure vLLM-Omni runtime and optimization
-features. The navigation follows the active
-[Feature Design](../design/index.md#feature-design-documents) taxonomy whenever
-an implementation contract has a user-facing workflow.
-
-!!! note "User guides, design documents, and recipes"
-
-    User guides explain how to enable a feature and where it is supported.
-    Design documents define internal contracts and do not, by themselves,
-    imply general or production support. For model-specific launch flags and
-    hardware requirements, use the linked examples and validated recipes from
-    [Supported Models](../models/supported_models.md).
-
-## Runtime and Stage Execution
-
-| Goal | User guide | Related design contract |
-| --- | --- | --- |
-| Choose serial, batched, step-wise, or streaming diffusion execution | [Execution Modes and Streaming](../user_guide/diffusion/execution_modes.md) | [Diffusion Continuous Batching](../design/feature/diffusion_continuous_batching.md), [Async Diffusion Output](../design/feature/async_diffusion_output.md) |
-| Reclaim stage memory without restarting the server | [Sleep Mode](sleep_mode.md) | Runtime lifecycle behavior is documented in the user guide |
-
-Some runtime designs are deliberately not promoted as standalone User Guide
-features yet:
-
-- [Disaggregated Inference](../design/feature/disaggregated_inference.md) and
-  [OmniConnector implementations](../design/index.md#communication) describe
-  topology and transport contracts. Practical deployment configuration remains
-  under [Pipeline and deploy configurations](../configuration/stage_configs.md).
-- [Async Chunk](../design/feature/async_chunk.md) and
-  [Async Omni Output Materialization](../design/feature/omni_async_output_materialization.md)
-  are model- and pipeline-dependent. Use the selected model's deploy
-  configuration and recipe for the supported settings.
-- [Automatic Prefix Caching](../design/feature/prefix_caching.md) remains a
-  design-level contract until its user-facing configuration and compatibility
-  surface is consolidated.
-
-## Quantization
-
-Quantization is a cross-model feature rather than a diffusion-only
-optimization. The unified [`quantization_config` guide](../user_guide/quantization/overview.md)
-covers diffusion-only models, multi-stage omni/TTS models, and multi-stage
-diffusion models. Its [design contract](../design/feature/quantization.md)
-defines the shared configuration and backend extension points.
-
-## Diffusion Acceleration
-
-| Goal | User guide | Related design contract |
-| --- | --- | --- |
-| Compare acceleration methods and supported combinations | [Overview](../user_guide/diffusion_features.md), [Feature Compatibility](../user_guide/feature_compatibility.md) | [Diffusion acceleration designs](../design/index.md#diffusion-acceleration) |
-| Move weights between host and device memory | [CPU Offloading](../user_guide/diffusion/cpu_offload.md) | [Distributed Layerwise Offload](../design/feature/distributed_layerwise_offload.md) |
-| Reuse denoising computation | [Cache Acceleration](../user_guide/diffusion/cache_acceleration/cache_dit.md) | [Cache-DiT](../design/feature/cache_dit.md), [TeaCache](../design/feature/teacache.md) |
-| Distribute diffusion work across devices | [Parallelism](../user_guide/diffusion/parallelism/overview.md) | [Parallelism designs](../design/index.md#parallelism) |
-| Select dense, sparse, or quantized attention paths | [Attention Backends](../user_guide/diffusion/attention_backends.md) | [Skip-Softmax](../design/feature/skip_softmax.md) |
-| Compile repeated diffusion regions | [Regional Compilation](../user_guide/diffusion/regional_compilation.md) | User-facing optimization guide |
-| Add generated video frames | [Frame Interpolation](../user_guide/diffusion/frame_interpolation.md) | User-facing extension guide |
-| Reduce diffusion model startup time | [Startup and Loading](../user_guide/diffusion/startup_and_loading.md) | User-facing loading guide |
-| Apply diffusion adapters | [LoRA](../user_guide/diffusion/lora.md) | User-facing extension guide |
-
-The [Pipeline Parallelism guide](../user_guide/diffusion/parallelism/pipeline_parallel.md)
-remains available by direct link, but it is not promoted in the primary User
-Guide navigation until its user-facing support and placement are settled.
-
-## Experimental
-
-[Session State Manager](session_state_manager.md) is opt-in and experimental.
-Its APIs and compatibility may change without notice.

docs/features/session_state_manager.md

@@ -20,12 +20,11 @@ extracts it into a shared, typed contract:
   (matching the bespoke caches it replaces), and reports per-device byte usage
   via `stats()` for observability.
 
-Autoregressive generation KV is *not* managed here: for DreamZero it is owned
+Attention KV is *not* managed here: for DreamZero it is owned by the
-by the AR-Diffusion engine's paged KV pool (PR
+AR-Diffusion engine's paged KV pool (PR
-[#4534](https://github.com/vllm-project/vllm-omni/pull/4534)). Cosmos3's fixed,
+[#4534](https://github.com/vllm-project/vllm-omni/pull/4534)). The manager
-encode-once UND conditioning K/V is different and is covered by the dense
+covers the model's non-KV session state; integrating the engine's per-session
-Cosmos3 adapter described below. Integrating the engine's per-session paged KV
+KV handle into the same byte accounting is RFC #4480 Phase 1.
-handle into the same byte accounting is RFC #4480 Phase 1.
 
 ## Enabling
 
@@ -159,62 +158,3 @@ of `num_frame_per_block` frames instead: identical output, bounded memory, and
 the per-step quantisation no longer scales with session length. Asking for more
 frames than the ring retains raises rather than silently returning a shorter
 window. The bespoke path is unchanged.
-
-### Cosmos3
-
-When `enable_session_state_manager` is enabled, the Cosmos3 adapter stores the
-dense, encode-once UND text K/V for every transformer layer and active CFG
-branch, together with that branch's GEN M-RoPE cosine/sine tensors. These are
-GPU-resident tensors and can contribute to CUDA OOM. A useful description of
-the retained storage on one rank is:
-
-```text
-sum_over_branches(
-  sum_over_layers(storage_bytes(K) + storage_bytes(V))
-  + storage_bytes(freqs_gen_cos) + storage_bytes(freqs_gen_sin)
-)
-```
-
-This is not a peak-memory upper bound: construction of the next branch can
-temporarily overlap the already retained branch with UND activations, the new
-full K/V result, RoPE tensors, and generator activations. K/V slices also keep
-their underlying allocation alive, so physical storage can follow the padded
-text length rather than only the exposed trimmed length. The manager's byte
-accounting deliberately measures storage for this reason.
-
-Branch placement changes the per-rank cost:
-
-- no CFG retains one conditional branch;
-- sequential CFG can retain both conditional and unconditional branches on the
-  same GPU;
-- CFG-parallel retains one branch on each CFG rank;
-- UND K/V is replicated across sequence-parallel ranks rather than divided by
-  the SP degree.
-
-Consequently, risk increases with text batch/sequence length, media token count
-(which sizes `freqs_gen`), sequential CFG, dtype width, and concurrent live
-requests. Phase 0 records `nbytes:cuda:*` but does not enforce `byte_budget`, so
-the manager cannot prevent an allocation from exhausting the device. The
-count-based session limit is not an OOM guarantee.
-
-The adapter transfers ownership by tensor reference; it does not clone K/V or
-RoPE tensors. For a normal serial request this should not materially increase
-tensor storage relative to Cosmos3's existing bespoke cond/uncond cache, which
-retains the same branch values. It does add small CPU-side session/object
-metadata. This claim is based on the reference flow in the implementation;
-there is not yet a current-head GPU peak-memory A/B result for this PR.
-
-Request-finally cleanup drops the manager-owned session, so branches do not
-accumulate with completed request IDs. The transformer handoff field still
-references the last loaded branch until `reset_cache()` runs at the start of
-the next generation (or the pipeline is destroyed). Thus this is bounded
-post-request residency, not growth per completed request, but manager
-`stats()` after `drop_session()` no longer includes that last transformer-held
-alias. A profiler that only reads manager statistics can therefore under-report
-live process memory.
-
-For OOM validation, measure complete cache-off and true flag-on generations in
-otherwise identical fresh processes. Synchronize CUDA and report process-level
-peak memory plus PyTorch peak allocated and peak reserved memory. Include the
-period between requests when checking cleanup; do not infer safety from the
-manager byte total, a single denoising step, or an operator-only profile.

docs/mkdocs/hooks/generate_argparse.py

@@ -123,7 +123,6 @@ def extract_omni_serve_subparser_init():
                         "TrackingNamespace": None,  # type annotation only
                         "make_arg_parser": lambda parser: parser,  # no-op for doc
                         "_ensure_vllm_platform": lambda: None,  # no-op for doc
-                        "_nonneg_finite_float": float,
                         "VLLM_SUBCMD_PARSER_EPILOG": "",
                         "logger": logger,
                         "DummySubparsers": DummySubparsers,

docs/mkdocs/hooks/generate_examples.py

@@ -24,23 +24,6 @@ SERVING_MODE_TITLES = {
     "online_serving": "Online serving",
 }
 
-# Keep the Examples navigation focused on reusable modality/task entry points.
-# Model-specific scripts remain available under ``examples/`` and are surfaced
-# from these shared pages instead of getting one page per model.
-GENERAL_EXAMPLE_SLUGS = frozenset(
-    {
-        "image_to_image",
-        "image_to_video",
-        "speech_to_video",
-        "text_to_audio",
-        "text_to_image",
-        "text_to_speech",
-        "text_to_video",
-        "x_to_text",
-        "x_to_video_audio",
-    }
-)
-
 
 def load_model_display_names() -> dict[str, str]:
     try:
@@ -63,13 +46,6 @@ def load_model_display_names() -> dict[str, str]:
 MODEL_DISPLAY_NAMES = load_model_display_names()
 
 
-def is_general_example(example: "Example") -> bool:
-    """Return whether an example should get a generated serving page."""
-    if example.category not in SERVING_MODE_TITLES:
-        return True
-    return example.path.stem in GENERAL_EXAMPLE_SLUGS
-
-
 def fix_case(text: str) -> str:
     subs = {
         "api": "API",
@@ -364,21 +340,22 @@ def update_nav_file(examples: list[Example]):
             examples_by_category[category] = []
         examples_by_category[category].append(example)
 
-    def category_items(category: str) -> list[dict[str, str]]:
+    # Build the new Examples section - start with preserved items
-        items = []
+    examples_section = preserved_items.copy()
-        for example in sorted(examples_by_category[category], key=lambda e: e.path.stem):
+
+    # Add examples grouped by category, sorted by category name
+    for category in sorted(examples_by_category.keys()):
+        category_examples = sorted(examples_by_category[category], key=lambda e: e.path.stem)
+        category_items = []
+        for example in category_examples:
             doc_path = EXAMPLE_DOC_DIR / example.category / f"{example.path.stem}.md"
             rel_path = doc_path.relative_to(ROOT_DIR / "docs")
-            items.append({example.nav_title: rel_path.as_posix()})
+            category_items.append({example.nav_title: rel_path.as_posix()})
-        return items
 
-    # Build the new Examples section - start with preserved items.
+        if category_items:
-    examples_section = preserved_items.copy()
+            # Format category name (e.g., "offline_inference" -> "Offline Inference")
-    for category in sorted(examples_by_category.keys()):
-        items = category_items(category)
-        if items:
             category_title = fix_case(category.replace("_", " ").title())
-            examples_section.append({category_title: items})
+            examples_section.append({category_title: category_items})
 
     # Update the nav structure
     nav_list[user_guide_idx]["User Guide"][examples_idx]["Examples"] = examples_section
@@ -413,8 +390,6 @@ def on_startup(command: Literal["build", "gh-deploy", "serve"], dirty: bool):
         for path in category.glob("*/*.md"):
             examples.append(Example(path.parent, category.stem))
 
-    examples = [example for example in examples if is_general_example(example)]
-
     # Generate the example documentation
     for example in sorted(examples, key=lambda e: e.path.stem):
         example_name = f"{example.path.stem}.md"

docs/models/supported_models.md

@@ -17,101 +17,83 @@ th {
 }
 </style>
 
-| Architecture | Models | Example HF Models | NVIDIA GPU | AMD GPU | Ascend NPU | Intel GPU | Recipe |
+| Architecture | Models | Example HF Models | NVIDIA GPU | AMD GPU | Ascend NPU | Intel GPU |
-|--------------|--------|-------------------|------------|---------|-----|-----------|--------|
+|--------------|--------|-------------------|------------|---------|-----|-----------|
-| `Qwen3OmniMoeForConditionalGeneration` | Qwen3-Omni | `Qwen/Qwen3-Omni-30B-A3B-Instruct` | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/Qwen/Qwen3-Omni.md) |
+| `Qwen3OmniMoeForConditionalGeneration` | Qwen3-Omni | `Qwen/Qwen3-Omni-30B-A3B-Instruct` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `Qwen2_5OmniForConditionalGeneration` | Qwen2.5-Omni | `Qwen/Qwen2.5-Omni-7B`, `Qwen/Qwen2.5-Omni-3B` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `Qwen2_5OmniForConditionalGeneration` | Qwen2.5-Omni | `Qwen/Qwen2.5-Omni-7B`, `Qwen/Qwen2.5-Omni-3B` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `MingFlashOmniForConditionalGeneration` + `MingImagePipeline` | Ming-flash-omni-2.0 (omni-speech + imagegen<sup>1</sup>) | `Jonathan1909/Ming-flash-omni-2.0` | ✅︎ |   |   |   | — |
+| `MingFlashOmniForConditionalGeneration` + `MingImagePipeline` | Ming-flash-omni-2.0 (omni-speech + imagegen<sup>1</sup>) | `Jonathan1909/Ming-flash-omni-2.0` | ✅︎ |   |   |   |
-| `BagelForConditionalGeneration` | BAGEL (DiT-only) | `ByteDance-Seed/BAGEL-7B-MoT` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `BagelForConditionalGeneration` | BAGEL (DiT-only) | `ByteDance-Seed/BAGEL-7B-MoT` | ✅︎ | ✅︎ | | ✅︎ |
-| `InternVLAA1Pipeline` | InternVLA-A1 | `InternRobotics/InternVLA-A1-3B` | ✅︎ | ✅︎ | | | — |
+| `InternVLAA1Pipeline` | InternVLA-A1 | `InternRobotics/InternVLA-A1-3B` | ✅︎ | ✅︎ | | |
-| `Gr00tN1d7Pipeline` | GR00T N1.7 | `nvidia/GR00T-N1.7-3B` | ✅︎ | | | | — |
+| `Gr00tN1d7Pipeline` | GR00T N1.7 | `nvidia/GR00T-N1.7-3B` | ✅︎ | | | |
-| `HunyuanImage3ForCausalMM` | HunyuanImage3.0 (DiT-only) | `tencent/HunyuanImage-3.0`, `tencent/HunyuanImage-3.0-Instruct` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `HunyuanImage3ForCausalMM` | HunyuanImage3.0 (DiT-only) | `tencent/HunyuanImage-3.0`, `tencent/HunyuanImage-3.0-Instruct` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `QwenImagePipeline` | Qwen-Image | `Qwen/Qwen-Image` | ✅︎ | | | | [Published](https://recipes.vllm.ai/Qwen/Qwen-Image) |
+| `QwenImagePipeline` | Qwen-Image | `Qwen/Qwen-Image` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `QwenImagePipeline` | Qwen-Image-2512 | `Qwen/Qwen-Image-2512` | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/Qwen/Qwen-Image-2512.md) |
+| `QwenImagePipeline` | Qwen-Image-2512 | `Qwen/Qwen-Image-2512` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `QwenImageEditPipeline` | Qwen-Image-Edit | `Qwen/Qwen-Image-Edit` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `QwenImageEditPipeline` | Qwen-Image-Edit | `Qwen/Qwen-Image-Edit` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `QwenImageEditPlusPipeline` | Qwen-Image-Edit-2509 | `Qwen/Qwen-Image-Edit-2509` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `QwenImageEditPlusPipeline` | Qwen-Image-Edit-2509 | `Qwen/Qwen-Image-Edit-2509` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `QwenImageLayeredPipeline` | Qwen-Image-Layered | `Qwen/Qwen-Image-Layered` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `QwenImageLayeredPipeline` | Qwen-Image-Layered | `Qwen/Qwen-Image-Layered` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `QwenImageEditPlusPipeline` | Qwen-Image-Edit-2511 | `Qwen/Qwen-Image-Edit-2511` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `QwenImageEditPlusPipeline` | Qwen-Image-Edit-2511 | `Qwen/Qwen-Image-Edit-2511` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `GlmImagePipeline` | GLM-Image | `zai-org/GLM-Image` | ✅︎ | ✅︎ | | | — |
+| `GlmImagePipeline` | GLM-Image | `zai-org/GLM-Image` | ✅︎ | ✅︎ | | |
-| `ZImagePipeline` | Z-Image | `Tongyi-MAI/Z-Image-Turbo` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `ZImagePipeline` | Z-Image | `Tongyi-MAI/Z-Image-Turbo` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `Krea2Pipeline` | Krea 2 (Raw + Turbo) | `krea/Krea-2-Raw`, `krea/Krea-2-Turbo` | ✅︎ | | | | — |
+| `Krea2Pipeline` | Krea 2 (Raw + Turbo) | `krea/Krea-2-Raw`, `krea/Krea-2-Turbo` | ✅︎ | | | |
-| `WanPipeline` | Wan2.1-T2V, Wan2.2-T2V, Wan2.2-TI2V | `Wan-AI/Wan2.1-T2V-1.3B-Diffusers`, `Wan-AI/Wan2.1-T2V-14B-Diffusers`, `Wan-AI/Wan2.2-T2V-A14B-Diffusers`, `Wan-AI/Wan2.2-TI2V-5B-Diffusers` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `WanPipeline` | Wan2.1-T2V, Wan2.2-T2V, Wan2.2-TI2V | `Wan-AI/Wan2.1-T2V-1.3B-Diffusers`, `Wan-AI/Wan2.1-T2V-14B-Diffusers`, `Wan-AI/Wan2.2-T2V-A14B-Diffusers`, `Wan-AI/Wan2.2-TI2V-5B-Diffusers` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `WanImageToVideoPipeline` | Wan2.2-I2V | `Wan-AI/Wan2.2-I2V-A14B-Diffusers` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `WanImageToVideoPipeline` | Wan2.2-I2V | `Wan-AI/Wan2.2-I2V-A14B-Diffusers` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `Cosmos3OmniDiffusersPipeline` | Cosmos3 T2I, T2V, I2V, V2V, T2V with sound, action policy | `nvidia/Cosmos3-Nano`, `nvidia/Cosmos3-Super` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `Cosmos3OmniDiffusersPipeline` | Cosmos3 T2I, T2V, I2V, V2V, T2V with sound, action policy | `nvidia/Cosmos3-Nano`, `nvidia/Cosmos3-Super` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `Wan22S2VPipeline` | Wan2.2-S2V | `Wan-AI/Wan2.2-S2V-14B` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `Wan22S2VPipeline` | Wan2.2-S2V | `Wan-AI/Wan2.2-S2V-14B` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `Wan22VACEPipeline` | Wan2.1-VACE | `Wan-AI/Wan2.1-VACE-1.3B-diffusers`, `Wan-AI/Wan2.1-VACE-14B-diffusers` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `Wan22VACEPipeline` | Wan2.1-VACE | `Wan-AI/Wan2.1-VACE-1.3B-diffusers`, `Wan-AI/Wan2.1-VACE-14B-diffusers` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `Wan22VACEPipeline` | Wan2.2-VACE | `Pyros13/Wan2.2-VACE-Fun-A14B-Diffusers` | ✅︎ |   |   |   | — |
+| `Wan22VACEPipeline` | Wan2.2-VACE | `Pyros13/Wan2.2-VACE-Fun-A14B-Diffusers` | ✅︎ |   |   |   |
-| `LTX2Pipeline` | LTX-2 / LTX-2.3 one-stage T2V and I2V | `Lightricks/LTX-2`, `diffusers/LTX-2.3-Diffusers` | ✅︎ | ✅︎ | | | — |
+| `LTX2Pipeline` | LTX-2 / LTX-2.3 one-stage T2V and I2V | `Lightricks/LTX-2`, `diffusers/LTX-2.3-Diffusers` | ✅︎ | ✅︎ | | |
-| `LTX2DistilledPipeline` | LTX-2 distilled two-stage T2V and I2V | `rootonchair/LTX-2-19b-distilled` | ✅︎ | ✅︎ | | | — |
+| `LTX2DistilledPipeline` | LTX-2 distilled two-stage T2V and I2V | `rootonchair/LTX-2-19b-distilled` | ✅︎ | ✅︎ | | |
-| `LingBotVideoPipeline` | LingBot-Video dense and MoE T2I, T2V, TI2V | `robbyant/lingbot-video-dense-1.3b`, `robbyant/lingbot-video-moe-30b-a3b` | ✅︎ | | | | — |
+| `LingBotVideoPipeline` | LingBot-Video dense and MoE T2V | `robbyant/lingbot-video-dense-1.3b`, `robbyant/lingbot-video-moe-30b-a3b` | ✅︎ | | | |
-| `MiniMaxH3Pipeline` | MiniMax H3 T2VA, first/last-keyframe FL2VA, and mixed-reference Ref2VA | `MiniMaxAI/MiniMax-H3` | ✅︎ | ✅︎ | | | [Published](https://recipes.vllm.ai/MiniMaxAI/MiniMax-H3) |
+| `MiniMaxH3Pipeline` | MiniMax H3 T2VA, first/last-keyframe FL2VA, and mixed-reference Ref2VA | `MiniMaxAI/MiniMax-H3` | ✅︎ | | | |
-| `DreamZeroPipeline` | DreamZero-DROID | `GEAR-Dreams/DreamZero-DROID` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `DreamZeroPipeline` | DreamZero-DROID | `GEAR-Dreams/DreamZero-DROID` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `HeliosPipeline`, `HeliosPyramidPipeline` | Helios | `BestWishYsh/Helios-Base`, `BestWishYsh/Helios-Mid`, `BestWishYsh/Helios-Distilled` | ✅︎ | ✅︎ | ✅︎ | | — |
+| `HeliosPipeline`, `HeliosPyramidPipeline` | Helios | `BestWishYsh/Helios-Base`, `BestWishYsh/Helios-Mid`, `BestWishYsh/Helios-Distilled` | ✅︎ | ✅︎ | ✅︎ | |
-| `MagiHumanPipeline` | MagiHuman | `SII-GAIR/daVinci-MagiHuman-Base-1080p` | ✅︎ | ✅︎ | | | — |
+| `MagiHumanPipeline` | MagiHuman | `SII-GAIR/daVinci-MagiHuman-Base-1080p` | ✅︎ | ✅︎ | | |
-| `OvisImagePipeline` | Ovis-Image | `OvisAI/Ovis-Image` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `OvisImagePipeline` | Ovis-Image | `OvisAI/Ovis-Image` | ✅︎ | ✅︎ | | ✅︎ |
-| `LongcatImagePipeline` | LongCat-Image | `meituan-longcat/LongCat-Image` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `LongcatImagePipeline` | LongCat-Image | `meituan-longcat/LongCat-Image` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `LongCatImageEditPipeline` | LongCat-Image-Edit | `meituan-longcat/LongCat-Image-Edit` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `LongCatImageEditPipeline` | LongCat-Image-Edit | `meituan-longcat/LongCat-Image-Edit` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `LongCatVideoAvatarPipeline` | LongCat-Video-Avatar-1.5 A2V/AI2V (native single-speaker and multi-speaker AI2V/AVC) | `meituan-longcat/LongCat-Video-Avatar-1.5` | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/meituan-longcat/LongCat-Video-Avatar-1.5.md) |
+| `BooguImagePipeline` | Boogu-Image | `Boogu/Boogu-Image-0.1-Base`, `Boogu/Boogu-Image-0.1-Edit` | ✅︎ | | | |
-| `BooguImagePipeline` | Boogu-Image | `Boogu/Boogu-Image-0.1-Base`, `Boogu/Boogu-Image-0.1-Edit` | ✅︎ | | | | — |
+| `StableDiffusionXLPipeline` | Stable-Diffusion-XL | `stabilityai/stable-diffusion-xl-base-1.0` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `StableDiffusionXLPipeline` | Stable-Diffusion-XL | `stabilityai/stable-diffusion-xl-base-1.0` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `StableDiffusion3Pipeline` | Stable-Diffusion-3 | `stabilityai/stable-diffusion-3.5-medium` | ✅︎ | ✅︎ | | ✅︎ |
-| `StableDiffusion3Pipeline` | Stable-Diffusion-3 | `stabilityai/stable-diffusion-3.5-medium` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `CosyVoice3Model` | CosyVoice3 | `FunAudioLLM/Fun-CosyVoice3-0.5B-2512` | ✅︎ | ✅︎ | | ✅︎ |
-| `CosyVoice3Model` | CosyVoice3 | `FunAudioLLM/Fun-CosyVoice3-0.5B-2512` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `OmniVoiceModel` | OmniVoice | `k2-fsa/OmniVoice` | ✅︎ | | | |
-| `OmniVoiceModel` | OmniVoice | `k2-fsa/OmniVoice` | ✅︎ | | | | — |
+| `VoxCPM2TalkerForConditionalGeneration` | VoxCPM2 | `openbmb/VoxCPM2` | ✅︎ | | | |
-| `VoxCPM2TalkerForConditionalGeneration` | VoxCPM2 | `openbmb/VoxCPM2` | ✅︎ | | | | — |
+| `MammothModa2ForConditionalGeneration` | MammothModa2-Preview | `bytedance-research/MammothModa2-Preview` | ✅︎ | ✅︎ | | |
-| `MammothModa2ForConditionalGeneration` | MammothModa2-Preview | `bytedance-research/MammothModa2-Preview` | ✅︎ | ✅︎ | | | — |
+| `MammothModa2ForConditionalGeneration` | MammothModa2-Dev (AR-only image understanding) | `bytedance-research/MammothModa2-Dev` | ✅︎ | | | |
-| `MammothModa2ForConditionalGeneration` | MammothModa2-Dev (AR-only image understanding) | `bytedance-research/MammothModa2-Dev` | ✅︎ | | | | — |
+| `Flux2KleinPipeline` | FLUX.2-klein | `black-forest-labs/FLUX.2-klein-4B`, `black-forest-labs/FLUX.2-klein-9B` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `Flux2KleinPipeline` | FLUX.2-klein | `black-forest-labs/FLUX.2-klein-4B`, `black-forest-labs/FLUX.2-klein-9B` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `FluxKontextPipeline` | FLUX.1-Kontext-dev | `black-forest-labs/FLUX.1-Kontext-dev` | ✅︎ | ✅︎ | | |
-| `FluxKontextPipeline` | FLUX.1-Kontext-dev | `black-forest-labs/FLUX.1-Kontext-dev` | ✅︎ | ✅︎ | | | — |
+| `FluxPipeline` | FLUX.1-dev | `black-forest-labs/FLUX.1-dev` | ✅︎ | ✅︎ | | ✅︎ |
-| `FluxPipeline` | FLUX.1-dev | `black-forest-labs/FLUX.1-dev` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `FluxPipeline` | FLUX.1-schnell | `black-forest-labs/FLUX.1-schnell` | ✅︎ | ✅︎ | | ✅︎ |
-| `FluxPipeline` | FLUX.1-schnell | `black-forest-labs/FLUX.1-schnell` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `OmniGen2Pipeline` | OmniGen2 | `OmniGen2/OmniGen2` | ✅︎ | ✅︎ | | ✅︎ |
-| `OmniGen2Pipeline` | OmniGen2 | `OmniGen2/OmniGen2` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `StableAudioPipeline` | Stable-Audio-Open | `stabilityai/stable-audio-open-1.0` | ✅︎ | ✅︎ | | ✅︎ |
-| `StableAudioPipeline` | Stable-Audio-Open | `stabilityai/stable-audio-open-1.0` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `SoulXSingerPipeline` | SoulX-Singer (SVS) | `Soul-AILab/SoulX-Singer` | ✅︎ | | | |
-| `SoulXSingerPipeline` | SoulX-Singer (SVS) | `Soul-AILab/SoulX-Singer` | ✅︎ | | | | — |
+| `SoulXSingerSVCPipeline` | SoulX-Singer-SVC | `Soul-AILab/SoulX-Singer` (`model-svc.pt`) | ✅︎ | | | |
-| `SoulXSingerSVCPipeline` | SoulX-Singer-SVC | `Soul-AILab/SoulX-Singer` (`model-svc.pt`) | ✅︎ | | | | — |
+| `AudioXPipeline` | AudioX | `zhangj1an/AudioX` | ✅︎ | ✅︎ | | |
-| `AudioXPipeline` | AudioX | `zhangj1an/AudioX` | ✅︎ | ✅︎ | | | — |
+| `Qwen3TTSForConditionalGeneration` | Qwen3-TTS-12Hz-1.7B-CustomVoice | `Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `Qwen3TTSForConditionalGeneration` | Qwen3-TTS-12Hz-1.7B-CustomVoice | `Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice` | ✅︎ | | | | [Published](https://recipes.vllm.ai/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice) |
+| `Qwen3TTSForConditionalGeneration` | Qwen3-TTS-12Hz-1.7B-VoiceDesign | `Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `Qwen3TTSForConditionalGeneration` | Qwen3-TTS-12Hz-1.7B-VoiceDesign | `Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `Qwen3TTSForConditionalGeneration` | Qwen3-TTS-12Hz-1.7B-Base | `Qwen/Qwen3-TTS-12Hz-1.7B-Base` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `Qwen3TTSForConditionalGeneration` | Qwen3-TTS-12Hz-1.7B-Base | `Qwen/Qwen3-TTS-12Hz-1.7B-Base` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
+| `MingTTSForConditionalGeneration` | Ming-omni-tts dense 0.5B | `inclusionAI/Ming-omni-tts-0.5B` | ✅︎ | | | |
-| `MingTTSForConditionalGeneration` | Ming-omni-tts dense 0.5B | `inclusionAI/Ming-omni-tts-0.5B` | ✅︎ | | | | — |
+| `GLMTTSForConditionalGeneration` | GLM-TTS | `zai-org/GLM-TTS` | ✅︎ | | | |
-| `GLMTTSForConditionalGeneration` | GLM-TTS | `zai-org/GLM-TTS` | ✅︎ | | | | — |
+| `MossTTSNanoForCausalLM` | MOSS-TTS-Nano | `OpenMOSS-Team/MOSS-TTS-Nano` | ✅︎ | | | |
-| `MossTTSNanoForCausalLM` | MOSS-TTS-Nano | `OpenMOSS-Team/MOSS-TTS-Nano` | ✅︎ | | | | — |
+| `MossTTSDelayModel` | MOSS-TTS, MOSS-TTSD, MOSS-SoundEffect, MOSS-VoiceGenerator | `OpenMOSS-Team/MOSS-VoiceGenerator` | ✅︎ | | | |
-| `MossTTSDelayModel` | MOSS-TTS, MOSS-TTSD, MOSS-SoundEffect, MOSS-VoiceGenerator | `OpenMOSS-Team/MOSS-VoiceGenerator` | ✅︎ | | | | — |
+| `MossTTSRealtime` | MOSS-TTS-Realtime | `OpenMOSS-Team/MOSS-TTS-Realtime` | ✅︎ | | | |
-| `MossTTSRealtime` | MOSS-TTS-Realtime | `OpenMOSS-Team/MOSS-TTS-Realtime` | ✅︎ | | | | — |
+| `HiggsAudioV2ForConditionalGeneration` | Higgs-Audio v2 | `bosonai/higgs-audio-v2-generation-3B-base` | ✅︎ | | | |
-| `HiggsAudioV2ForConditionalGeneration` | Higgs-Audio v2 | `bosonai/higgs-audio-v2-generation-3B-base` | ✅︎ | | | | — |
+| `HiggsMultimodalQwen3ForConditionalGeneration` | Higgs-Audio v3 (TTS) | `bosonai/higgs-audio-v3-tts-4b` | ✅︎ | | | |
-| `HiggsMultimodalQwen3ForConditionalGeneration` | Higgs-Audio v3 (TTS) | `bosonai/higgs-audio-v3-tts-4b` | ✅︎ | | | | [Published](https://recipes.vllm.ai/bosonai/higgs-audio-v3-tts-4b) |
+| `IndexTTS2TalkerForConditionalGeneration` | IndexTTS-2 | `IndexTeam/IndexTTS-2` | ✅︎ | | | |
-| `IndexTTS2TalkerForConditionalGeneration` | IndexTTS-2 | `IndexTeam/IndexTTS-2` | ✅︎ | | | | — |
+| `NextStep11Pipeline` | NextStep-1.1 | `stepfun-ai/NextStep-1.1` | ✅︎ | ✅︎ | | ✅︎ |
-| `IndexTTS25TalkerForConditionalGeneration` | IndexTTS-2.5 | native `checkpoints/` bundle | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/IndexTeam/IndexTTS-2_5.md) |
+| `MiMoAudioModel` | MiMo-Audio-7B-Instruct | `XiaomiMiMo/MiMo-Audio-7B-Instruct` | ✅︎ | ✅︎ | | |
-| `NextStep11Pipeline` | NextStep-1.1 | `stepfun-ai/NextStep-1.1` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `MiMoV2ASRForCausalLM` | MiMo-V2.5-ASR | `XiaomiMiMo/MiMo-V2.5-ASR` | ✅︎ | ✅︎ | | |
-| `MiMoAudioModel` | MiMo-Audio-7B-Instruct | `XiaomiMiMo/MiMo-Audio-7B-Instruct` | ✅︎ | ✅︎ | | | — |
+| `Flux2Pipeline` | FLUX.2-dev | `black-forest-labs/FLUX.2-dev` | ✅︎ | ✅︎ | | |
-| `MiMoV2ASRForCausalLM` | MiMo-V2.5-ASR | `XiaomiMiMo/MiMo-V2.5-ASR` | ✅︎ | ✅︎ | | | — |
+| `FishSpeechSlowARForConditionalGeneration` | Fish Speech S2 Pro | `fishaudio/s2-pro` | ✅︎ | ✅︎ | | ✅︎ |
-| `Flux2Pipeline` | FLUX.2-dev | `black-forest-labs/FLUX.2-dev` | ✅︎ | ✅︎ | | | — |
+| `DreamIDOmniPipeline` | DreamID-Omni | `XuGuo699/DreamID-Omni` | ✅︎ | ✅︎ | | |
-| `FishSpeechSlowARForConditionalGeneration` | Fish Speech S2 Pro | `fishaudio/s2-pro` | ✅︎ | ✅︎ | | ✅︎ | — |
+| `SenseNovaU1Pipeline` | SenseNova-U1 (DiT-only) | `SenseNova/SenseNova-U1-8B-MoT` | ✅︎ | | | |
-| `DreamIDOmniPipeline` | DreamID-Omni | `XuGuo699/DreamID-Omni` | ✅︎ | ✅︎ | | | — |
+| `LancePipeline` | Lance | `bytedance-research/Lance` | ✅︎ | | | |
-| `SenseNovaU1Pipeline` | SenseNova-U1 (DiT-only) | `SenseNova/SenseNova-U1-8B-MoT` | ✅︎ | | | | — |
+| `HunyuanVideo15Pipeline` | HunyuanVideo-1.5-T2V | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v`, `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v` | ✅︎ | ✅︎ | | |
-| `LancePipeline` | Lance | `bytedance-research/Lance` | ✅︎ | | | | — |
+| `HunyuanVideo15ImageToVideoPipeline` | HunyuanVideo-1.5-I2V | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_i2v`, `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_i2v` | ✅︎ | ✅︎ | | |
-| `HunyuanVideo15Pipeline` | HunyuanVideo-1.5-T2V | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v`, `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v` | ✅︎ | ✅︎ | | | — |
+| `VoxtralTTSForConditionalGeneration` | Voxtral TTS | `mistralai/Voxtral-4B-TTS-2603` | ✅︎ | ✅︎ | | |
-| `HunyuanVideo15ImageToVideoPipeline` | HunyuanVideo-1.5-I2V | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_i2v`, `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_i2v` | ✅︎ | ✅︎ | | | — |
+| `CovoAudioForConditionalGeneration` | Covo-Audio-Chat | `tencent/Covo-Audio-Chat` | ✅︎ | | | |
-| `VoxtralTTSForConditionalGeneration` | Voxtral TTS | `mistralai/Voxtral-4B-TTS-2603` | ✅︎ | ✅︎ | | | — |
+|`DyninOmniForConditionalGeneration` | Dynin-Omni | `snu-aidas/Dynin-Omni` | ✅︎ | | | |
-| `CovoAudioForConditionalGeneration` | Covo-Audio-Chat | `tencent/Covo-Audio-Chat` | ✅︎ | | | | — |
+| `MiniCPMO45OmniForConditionalGeneration` | MiniCPM-o 4.5 | `openbmb/MiniCPM-o-4_5` | ✅︎ | | ✅︎ | |
-|`DyninOmniForConditionalGeneration` | Dynin-Omni | `snu-aidas/Dynin-Omni` | ✅︎ | | | | — |
+| `ErnieImagePipeline` | ERNIE-Image | `baidu/ERNIE-Image`, `baidu/ERNIE-Image-Turbo` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
-| `MiniCPMO45OmniForConditionalGeneration` | MiniCPM-o 4.5 | `openbmb/MiniCPM-o-4_5` | ✅︎ | | ✅︎ | | — |
+|`HiDreamImagePipeline` | HiDream-I1-Full | `HiDream-ai/HiDream-I1-Full` | ✅︎ | ✅︎ | | |
-| `ErnieImagePipeline` | ERNIE-Image | `baidu/ERNIE-Image`, `baidu/ERNIE-Image-Turbo` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-|`HiDreamImagePipeline` | HiDream-I1-Full | `HiDream-ai/HiDream-I1-Full` | ✅︎ | ✅︎ | | | — |
-
-The `Recipe` column links the corresponding deployment recipe. `Published` is
-preferred when a corresponding `recipes.vllm.ai` page exists; otherwise the
-link points to the repository recipe. `—` means that no recipe link has been
-added for that model row yet.
-
-For rows with an audited recipe link, the hardware checkmarks reflect hardware
-explicitly documented in that recipe. Other rows retain the implementation
-support metadata until their recipe is audited.
 
 ✅︎ indicates the model is supported on that backend. Empty cells mean not listed as supported on that backend.
-
-<sup>H3</sup> MiniMax H3 AMD GPU support is validated on gfx942 (MI300X) and
-gfx950 (MI350) in BF16, using the AITER `FLASH_ATTN` diffusion attention backend.
-Other AMD SKUs (e.g. MI325X) are not listed until their
-own validation evidence is added. See the
-[MiniMax H3 recipe](https://recipes.vllm.ai/MiniMaxAI/MiniMax-H3) for
-per-architecture serving commands.

docs/usage/faq.md

@@ -10,12 +10,12 @@ A: Refer to [GPU memory calculation and configuration](../configuration/gpu_memo
 
 > Q: I encounter some bugs or CI problems, which is urgent. How can I solve it?
 
-A: Search the current [issues](https://github.com/vllm-project/vllm-omni/issues) first. If no existing issue matches a bug or CI failure, open a [bug report](https://github.com/vllm-project/vllm-omni/issues/new?template=400-bug-report.yml) with a minimal reproducer, environment details, and relevant logs. For technical or usage questions, use the `sig-omni` channel in [vLLM Slack](https://slack.vllm.ai/) or the [vLLM Forum](https://discuss.vllm.ai/).
+A: At first, you can check current [issues](https://github.com/vllm-project/vllm-omni/issues) to find possible solutions. If none of these satisfy your demand and it is urgent, please find these [volunteers](https://docs.vllm.ai/projects/vllm-omni/en/latest/community/volunteers/) for help.
 
 > Q: Does vLLM-Omni support AWQ or any other quantization?
 
-A: AWQ is available through the inherited vLLM quantization registry, and vLLM-Omni supports several additional methods. Actual support and validation vary by model, component, hardware, and checkpoint. See the [quantization overview](../user_guide/quantization/overview.md) for validated combinations and method-specific guides.
+A: We plan to introduce GGUF FP8 prequantized models and online FP8 quantization in version 0.16.0. Support for other quantization types will follow in future releases. For details, please see our [Q1 quantization roadmap](https://github.com/vllm-project/vllm-omni/issues/1057).
 
 > Q: Does vLLM-Omni support multimodal streaming input and output?
 
-A: Yes, for specific models and serving paths. Current capabilities include [streaming video input](../serving/video_stream_api.md), [streaming diffusion output](../user_guide/diffusion/execution_modes.md#streaming-output), and experimental full-duplex real-time audio described in the [project overview](../README.md). Check the model and API documentation because input and output support is model-specific.
+A: Not yet. We already put it on the [Roadmap](https://github.com/vllm-project/vllm-omni/issues/165). Please stay tuned!

docs/usage/metrics.md

@@ -1,23 +1,23 @@
 # Production Metrics
 
-vLLM-Omni exposes Prometheus metrics via the `/metrics` endpoint on the OpenAI-compatible API server.
+vLLM-Omni exposes Prometheus metrics via the `/metrics` endpoint on the OpenAI-compatible API server. This page covers the text and audio surface; diffusion / image / video metrics are tracked in a follow-up PR.
 
 ```bash
 vllm-omni serve Qwen/Qwen3-Omni-30B-A3B-Instruct --port 8000 --log-stats
 curl http://localhost:8000/metrics
 ```
 
-**`--log-stats` is required to populate metric data.** Without the flag, the endpoint still returns `200 OK` but the upstream `vllm:*` wrap is not registered at all, and the 15 `vllm_omni:*` families are registered as placeholders with no data written to them. This keeps the runtime cost essentially zero for deployments that don't need monitoring. With the flag, all ~80 families populate.
+**`--log-stats` is required to populate metric data.** Without the flag, the endpoint still returns `200 OK` but the upstream `vllm:*` wrap is not registered at all, and the 15 `vllm:omni_*` families are registered as placeholders with no data written to them. This keeps the runtime cost essentially zero for deployments that don't need monitoring. With the flag, all ~80 families populate.
 
 ## Metric Namespaces
 
 | Prefix | Source | Present when |
 |--------|--------|--------------|
-| `vllm_omni:` | vLLM-Omni orchestrator / audio modality / cross-stage transfer | Pipeline-dependent |
+| `vllm:omni_` | vLLM-Omni orchestrator / audio modality / cross-stage transfer | Pipeline-dependent |
 | `vllm:` | Upstream vLLM engine, wrapped by `OmniPrometheusStatLogger` to expose `{stage, replica}` | Pipeline includes an LLM (AR) stage |
 | `http_` / `process_` | Uvicorn / Python runtime | Always |
 
-## Pipeline-Level Metrics (`vllm_omni:`)
+## Pipeline-Level Metrics (`vllm:omni_`)
 
 Defined in `vllm_omni/metrics/prometheus.py`. Track request lifecycle across the full multi-stage pipeline.
 
@@ -25,66 +25,42 @@ Defined in `vllm_omni/metrics/prometheus.py`. Track request lifecycle across the
 
 | Metric | Type | Labels | Description |
 |--------|------|--------|-------------|
-| `vllm_omni:num_requests_running` | Gauge | `model_name` | Pipeline-global in-flight requests (dispatched to engine, not yet finalized) |
+| `vllm:omni_num_requests_running` | Gauge | `model_name` | Pipeline-global in-flight requests (dispatched to engine, not yet finalized) |
-| `vllm_omni:num_requests_waiting` | Gauge | `model_name` | Requests waiting in the Orchestrator queue |
+| `vllm:omni_num_requests_waiting` | Gauge | `model_name` | Requests waiting in the Orchestrator queue |
-| `vllm_omni:requests_success_total` | Counter | `model_name`, `finished_reason` | Total requests by completion reason. `finished_reason` ∈ {`stop`, `length`, `abort`, ...} mirroring upstream `vllm:request_success_total`; aborts cover client disconnect / cancellation paths in addition to upstream `FinishReason.ABORT` |
+| `vllm:omni_requests_success_total` | Counter | `model_name`, `finished_reason` | Total requests by completion reason. `finished_reason` ∈ {`stop`, `length`, `abort`, ...} mirroring upstream `vllm:request_success_total`; aborts cover client disconnect / cancellation paths in addition to upstream `FinishReason.ABORT` |
 
 ### Latency
 
 | Metric | Type | Labels | Description |
 |--------|------|--------|-------------|
-| `vllm_omni:e2e_request_latency_s` | Histogram | `model_name` | Pipeline-global end-to-end request latency in seconds |
+| `vllm:omni_e2e_request_latency_s` | Histogram | `model_name` | Pipeline-global end-to-end request latency in seconds |
 
-## Audio Modality Metrics (`vllm_omni:`)
+## Audio Modality Metrics (`vllm:omni_`)
 
 Emitted at request finalize, except for `audio_ttfp_s` (streaming-hook at the first audio packet) and `audio_underrun_s` / `audio_continuity_ok_total` (streaming finalize, after the chunk stream is exhausted). All carry `{model_name, stage, replica}` plus the listed extra label.
 
 | Metric | Type | Extra label | Description |
 |--------|------|-------------|-------------|
-| `vllm_omni:audio_ttfp_s` | Histogram | — | Time from request arrival to first audio packet/frame |
+| `vllm:omni_audio_ttfp_s` | Histogram | — | Time from request arrival to first audio packet/frame |
-| `vllm_omni:audio_duration_s` | Histogram | — | Audio content duration (`audio_frames / sample_rate`) |
+| `vllm:omni_audio_duration_s` | Histogram | — | Audio content duration (`audio_frames / sample_rate`) |
-| `vllm_omni:audio_rtf` | Histogram | — | Real-time factor (`stage_gen_time_s / audio_duration_s`); streaming TTS SLO red line `< 1`; uses `RTF_BUCKETS` |
+| `vllm:omni_audio_rtf` | Histogram | — | Real-time factor (`stage_gen_time_s / audio_duration_s`); streaming TTS SLO red line `< 1`; uses `RTF_BUCKETS` |
-| `vllm_omni:audio_frames_total` | Counter | — | Cumulative audio frame count; throughput via `rate()` |
+| `vllm:omni_audio_frames_total` | Counter | — | Cumulative audio frame count; throughput via `rate()` |
-| `vllm_omni:audio_underrun_s` | Histogram | — | Per-request worst-case player deficit; `> 0` indicates listener heard silent gaps |
+| `vllm:omni_audio_underrun_s` | Histogram | — | Per-request worst-case player deficit; `> 0` indicates listener heard silent gaps |
-| `vllm_omni:audio_continuity_ok_total` | Counter | `threshold_ms` | Incremented when the request's worst underrun stayed below `threshold_ms` |
+| `vllm:omni_audio_continuity_ok_total` | Counter | `threshold_ms` | Incremented when the request's worst underrun stayed below `threshold_ms` |
-| `vllm_omni:audio_skipped_requests_total` | Counter | `reason` | Silent-loss counter — code2wav rejected malformed codec input and returned `200 OK` with empty audio |
+| `vllm:omni_audio_skipped_requests_total` | Counter | `reason` | Silent-loss counter — code2wav rejected malformed codec input and returned `200 OK` with empty audio |
 
 The continuity math comes from `vllm_omni/benchmarks/audio_continuity.py::compute_continuity_stats` so the server-side observation aligns with the bench-side definition.
 
-## Diffusion Metrics (`vllm_omni:`)
+## Cross-Stage Transfer Metrics (`vllm:omni_`)
-
-Per-request timing breakdowns for diffusion (image/video) stages. Emitted at request finalize when `stage_metrics.diffusion_metrics` is present. All carry `{model_name, stage, replica}`.
-
-| Metric | Type | Description |
-|--------|------|-------------|
-| `vllm_omni:diffusion_exec_s` | Histogram | DiT forward pass execution time per request in seconds |
-| `vllm_omni:diffusion_exec_per_step_s` | Histogram | DiT forward pass execution time per denoising step in seconds (`exec_s / num_inference_steps`) |
-| `vllm_omni:diffusion_preprocess_s` | Histogram | Diffusion input preprocessing time per request in seconds |
-| `vllm_omni:diffusion_postprocess_s` | Histogram | Diffusion output postprocessing (VAE decode) time per request in seconds |
-
-`diffusion_exec_s` uses `SECONDS_BUCKETS` (50 ms → 300 s); the other three use `SECONDS_FAST_BUCKETS` (1 ms → 60 s). `diffusion_exec_per_step_s` is skipped when `num_inference_steps` is not set.
-
-### Example PromQL
-
-```promql
-# P99 DiT exec time by stage
-histogram_quantile(0.99, rate(vllm_omni:diffusion_exec_s_bucket[5m]))
-
-# Ratio of preprocess to total exec wall time
-rate(vllm_omni:diffusion_preprocess_s_sum[5m])
-  / rate(vllm_omni:diffusion_exec_s_sum[5m])
-```
-
-## Cross-Stage Transfer Metrics (`vllm_omni:`)
 
 Per-physical-transfer histograms tracking the data hop between adjacent stages. Labels `{model_name, from_stage, from_replica, to_stage, to_replica}` let dashboards attribute latency to specific replica edges. `from_replica` / `to_replica` are resolved from the orchestrator's sticky-routing binding (`stage_pool.get_bound_replica_id(request_id)`), so no extra plumbing through `TransferEdgeStats` is needed.
 
 | Metric | Type | Description |
 |--------|------|-------------|
-| `vllm_omni:transfer_size_bytes` | Histogram | Per-transfer payload size in bytes |
+| `vllm:omni_transfer_size_bytes` | Histogram | Per-transfer payload size in bytes |
-| `vllm_omni:transfer_tx_s` | Histogram | Sender-side time (serialize + submit to connector) |
+| `vllm:omni_transfer_tx_s` | Histogram | Sender-side time (serialize + submit to connector) |
-| `vllm_omni:transfer_rx_s` | Histogram | Receiver-side time (recv + deserialize) |
+| `vllm:omni_transfer_rx_s` | Histogram | Receiver-side time (recv + deserialize) |
-| `vllm_omni:transfer_in_flight_s` | Histogram | Network in-flight time (TX done → RX recv start) |
+| `vllm:omni_transfer_in_flight_s` | Histogram | Network in-flight time (TX done → RX recv start) |
 
 ## vLLM Engine Metrics (`vllm:`)
 
@@ -107,9 +83,9 @@ For the full list of upstream metrics, see [the vLLM docs](https://github.com/vl
 
 | Metric group | Multi-stage LLM (Qwen3-Omni) |
 |---|---|
-| `vllm_omni:` request tracking + latency | With `--log-stats` |
+| `vllm:omni_` request tracking + latency | With `--log-stats` |
-| `vllm_omni:` audio modality | With `--log-stats`, if pipeline has a talker stage |
+| `vllm:omni_` audio modality | With `--log-stats`, if pipeline has a talker stage |
-| `vllm_omni:` transfer | With `--log-stats`, if pipeline has ≥ 2 stages |
+| `vllm:omni_` transfer | With `--log-stats`, if pipeline has ≥ 2 stages |
 | `vllm:` engine metrics (per `(stage, replica)`) | With `--log-stats` |
 | `vllm:` MFU metrics | With `--log-stats --enable-mfu-metrics` |
 
@@ -118,5 +94,5 @@ For the full list of upstream metrics, see [the vLLM docs](https://github.com/vl
 - All time-bearing metrics use the `_s` suffix (values in seconds). Buckets are `SECONDS_BUCKETS` for e2e / generation-style values and `SECONDS_FAST_BUCKETS` (1 ms → 60 s) for the fine-grained transfer and audio-underrun values.
 - Counters use the `_total` suffix (auto-appended by `prometheus_client`).
 - Sizes use the `_bytes` suffix.
-- All omni-specific families are prefixed `vllm_omni:`. The upstream `unregister_vllm_metrics()` function is monkey-patched (see `vllm_omni/patch.py`) to a scoped version that still strips upstream `vllm:*` collectors so multi-engine init within one process does not crash on duplicate registration, but preserves anything prefixed `vllm_omni:`.
+- All omni-specific families are prefixed `vllm:omni_`. The upstream `unregister_vllm_metrics()` function is monkey-patched (see `vllm_omni/patch.py`) to a scoped version that still strips upstream `vllm:*` collectors so multi-engine init within one process does not crash on duplicate registration, but preserves anything prefixed `vllm:omni_` / `vllm_omni`.
-- Text and audio first-output use distinct families (`vllm:time_to_first_token_seconds` reused from upstream for text; `vllm_omni:audio_ttfp_s` for audio) rather than a single metric with a `modality` label.
+- Text and audio first-output use distinct families (`vllm:time_to_first_token_seconds` reused from upstream for text; `vllm:omni_audio_ttfp_s` for audio) rather than a single metric with a `modality` label.

docs/user_guide/diffusion/attention_backends.md

@@ -17,7 +17,7 @@ The full set of backends and their platform defaults is in the **Backend Options
 | `TRTLLM_ATTN` | FlashInfer's trtllm-gen FMHA (TensorRT-LLM's generated kernels, vendored by FlashInfer). Dense BF16, GQA native, `head_dim=128`. Datacenter Blackwell only (sm_100 / sm_103). Packed paths can provide `cu_seqlens` directly. Supports optional **Skip-Softmax** sparse attention — see below. Requires `flashinfer`. |
 | `FLASH_ATTN` | Wraps FlashAttention 4 on Blackwell when `flash-attn-4` is installed, then falls back to FlashAttention 3/2. Default on Hopper / Ada / Ampere when a compatible FlashAttention package is installed. |
 | `CUDNN_ATTN` | Pins `sdpa_kernel([CUDNN_ATTENTION])`. Default on Blackwell (sm_10x / sm_12x) with cuDNN ≥ 9.5. Wins on mask-heavy DiTs (HunyuanVideo-1.5: 2× e2e vs SDPA). |
-| `FLASHINFER_ATTN` | Uses FlashInfer's batch-prefill wrapper and supports mixed Q/K and V input dtypes through backend-specific configuration. Used as Blackwell fallback when cuDNN is unavailable. Requires `flashinfer` >= 0.6.16rc1 for mixed-dtype configurations. |
+| `FLASHINFER_ATTN` | Calls FlashInfer's dense `single_prefill_with_kv_cache` directly with `custom_mask` for non-causal masked attention. Used as Blackwell fallback when cuDNN is unavailable. Requires `flashinfer`. |
 | `TORCH_SDPA` | PyTorch `scaled_dot_product_attention` with the default backend dispatcher. Most conservative; always available. |
 | `SAGE_ATTN` | SageAttention 2.2 — INT8-quantized attention with FP16 accumulation. Lossy but typically visually indistinguishable on diffusion outputs. Requires `sageattention`. |
 | `SAGE_ATTN_3` | Requires `sageattn3` from `SageAttention/sageattention3_blackwell`. CUDA only, intended for Blackwell GPUs, with GQA/MQA requests falling back to PyTorch SDPA. |
@@ -84,7 +84,7 @@ A backend that needs configuration exposes it as a typed field on the spec:
 When constructing `OmniDiffusionConfig` directly:
 
 ```python
-from vllm_omni.diffusion.data import AttentionConfig, AttentionSpec, AttnQuantSpec, OmniDiffusionConfig
+from vllm_omni.diffusion.data import AttentionConfig, AttentionSpec, OmniDiffusionConfig
 
 config = OmniDiffusionConfig(
     diffusion_attention_config=AttentionConfig(
@@ -99,27 +99,6 @@ config = OmniDiffusionConfig(
 
 A plain dict is also accepted and normalized to `AttentionConfig`.
 
-#### FlashInfer QK16/V8 quantized attention
-
-`FLASHINFER_ATTN` accepts quantization options through `AttentionSpec.quant`. For QK16/V8:
-
-```python
-config = OmniDiffusionConfig(
-    diffusion_attention_config=AttentionConfig(
-        default=AttentionSpec(
-            backend="FLASHINFER_ATTN",
-            quant=AttnQuantSpec(
-                dtype_qk="bfloat16",
-                dtype_vo="fp8_e4m3",
-            ),
-        ),
-    ),
-    ...,
-)
-```
-
-`dtype_qk` configures the Q and K input dtypes. `dtype_vo` configures the V input dtype.
-
 ## Platform Defaults
 
 ### Blackwell (sm_100 / sm_103 / sm_120 / sm_121)
@@ -283,20 +262,23 @@ blocks — use Ulysses SP (`ring_degree=1`).
 
 ### Which geometries run sparse
 
-MindIE-SD rf_v2 handles arbitrary video grids by spatially rearranging video first and, when
+Sparsity is only applied when the video segment is a **multiple of 128 rows**, where the row count
-necessary, promoting a real-video suffix to its always-kept prefix segment. It never pads: rf_v2
+is `latent_t × (height / 32) × (width / 32)`. Otherwise `rf_v2`'s block mask and the kernel's own
-does not consume an attention mask for padded keys. The remaining video rows stay sparse, while the
+tiling disagree on the block count, and the block straddling the seam mixes video and prefix rows
-promoted rows remain visible to every query and key.
+that selection may then drop. Any resolution still runs — an unaligned geometry falls back to dense
+attention and logs `RAINFUSION_ATTN staying dense` with the row count it computed — but it gets no
+speedup, so pick an aligned geometry when you want one.
 
-For example, MiniMax-H3 at 1344x768 has grid `(62, 24, 42)`: its 62496 video rows leave a 32-row
+Alignment is necessary, not sufficient, for good quality. `rf_v2` groups video positions into 8x8
-128-block residue, and its two non-8-wide latent columns form a 2928-row rearranged suffix.
+spatial tiles (two tiles fill one 128-row block), which is what makes a selected block a compact
-MindIE-SD promotes 2976 rows, leaving 59520 sparse rows (`465 × 128`). This keeps the block mask
+patch of the frame. When the latent `h` or `w` is not a multiple of 8, the leftover rows or columns
-and kernel tiling aligned, at the cost of retaining more blocks.
+are peeled off and appended as a flat run instead of being tiled, so they get pooled with spatially
+distant positions and selection can no longer rank them meaningfully. This is silent, and invisible
+to a `sparsity=0` check, because a fully populated mask does not care how blocks are grouped.
 
-8x8-aligned spatial grids remain preferable for performance. A latent `h` or `w` not divisible by 8
+"Multiple of 8" on the latent grid means **width and height that are multiples of 256**. Aligned
-creates an always-kept residual suffix and lowers realized sparsity. "Multiple of 8" on the latent
+resolutions off that grid still run sparse; they just lose more fidelity at the same `sparsity`,
-grid means **width and height that are multiples of 256**. This path requires a MindIE-SD release
+which you can buy back with `start_step`.
-that implements protected video tails for rf_v2.
 
 ## End-to-End Benchmark (BF16, sm_120 RTX Pro 6000 Blackwell)
 

docs/user_guide/diffusion/cache_acceleration/cache_dit.md

@@ -6,7 +6,6 @@
 - [Overview](#overview)
 - [Quick Start](#quick-start)
 - [Example Script](#example-script)
-- [Request-Scoped Quality](#request-scoped-quality-minimax-h3)
 - [Acceleration Methods](#acceleration-methods)
 - [Configuration Parameters](#configuration-parameters)
 - [Best Practices](#best-practices)
@@ -141,43 +140,6 @@ vllm serve Qwen/Qwen-Image --omni --port 8091 \
   --cache-config '{"Fn_compute_blocks": 1, "residual_diff_threshold": 0.12}'
 ```
 
-## Request-Scoped Quality (MiniMax H3)
-
-MiniMax H3 can switch Cache-DiT at the request boundary without enabling a
-cache backend at server startup. Add a quality field to an online request:
-
-```bash
-# Native reference path for this request.
--F 'quality=lossless'
-
-# H3's conservative Cache-DiT profile for this request.
--F 'quality=high'
-```
-
-For offline inference, set the same field on the sampling parameters:
-
-```python
-OmniDiffusionSamplingParams(
-    quality="high",
-    num_inference_steps=50,
-    extra_args={"task": "t2va", "duration": 5.0, "audio_flow_shift": 3.0},
-)
-```
-
-| Server startup | Request quality | Behavior |
-|---|---|---|
-| `--cache-backend cache_dit` | omitted | Use or restore the startup Cache-DiT profile |
-| `--cache-backend cache_dit` | `lossless` | Remove Cache-DiT hooks and run the reference path |
-| `--cache-backend cache_dit` | `high` | Use or install H3's conservative Cache-DiT profile |
-| no Cache-DiT | omitted or `lossless` | Run the reference path |
-| no Cache-DiT | `high` | Install H3's conservative Cache-DiT profile |
-
-The startup option is only needed when omitted-quality requests should use the
-server-configured Cache-DiT profile by default.
-
-See the [MiniMax H3 recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/MiniMaxAI/MiniMax-H3.md#request-scoped-quality)
-for a complete request and measured trade-off.
-
 ---
 
 ## Acceleration Methods