docs: address architecture review feedback

Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>
docs: remove architecture source attribution
2026-08-09 09:14:46 +08:00 · 2026-08-08 22:22:18 +08:00 · 2026-08-08 22:08:42 +08:00 · 2026-08-08 21:59:17 +08:00 · 2026-08-08 21:47:01 +08:00 · 2026-08-08 21:36:05 +08:00
565 changed files with 6083 additions and 51040 deletions
@@ -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:
@@ -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:
@@ -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:
@@ -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"
@@ -128,21 +128,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 +172,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 +183,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 +192,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 +210,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
-
-      - 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
+        mirror_hardwares: h100_2

      - label: "TTS · VoxCPM2 Test"
        source_file_dependencies:
@@ -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
@@ -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
@@ -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
@@ -3,29 +3,22 @@ steps:
    key: ready-omni-group
    depends_on: upload-ready-pipeline
    steps:
-      - label: "Omni · MiniCPM-o 4.5 Test"
-        mirror_hardwares: a3_npu_2
+      - label: ":robot: Omni · MiniCPM-o 4.5 Test"
+        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'
-      - 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'
+          - 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'

  - group: ":card_index_dividers: TTS Model Test"
    key: ready-tts-group
@@ -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:
@@ -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"
@@ -1,87 +1,50 @@
 #!/bin/bash
 # SPDX-License-Identifier: Apache-2.0
 #
-# Publish Docker images from ECR staging to DockerHub.
-#
-# Usage:
-#   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>
+# Publish release Docker images from ECR to DockerHub.
+# Pulls per-arch images, tags with `latest` and versioned tags, pushes them,
+# then creates and pushes a multi-arch manifest.

 set -euo pipefail

-MODE="${1:-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

+COMMIT="$BUILDKITE_COMMIT"
 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 "Publishing release images v${RELEASE_VERSION}"
 echo "  Commit: ${COMMIT}"
-echo "  Primary tags: ${PRIMARY_TAGS[*]}"
-if [ ${#EXTRA_MANIFEST_TAGS[@]} -gt 0 ]; then
-  echo "  Extra manifests: ${EXTRA_MANIFEST_TAGS[*]}"
-fi
 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"
-SRC_ARM="${ECR_REPO}:${COMMIT}-aarch64"
+docker pull "${ECR_REPO}:${COMMIT}-x86_64"
+docker pull "${ECR_REPO}:${COMMIT}-aarch64"

-docker pull "${SRC_X86}"
-docker pull "${SRC_ARM}"
+docker tag "${ECR_REPO}:${COMMIT}-x86_64" "${DOCKERHUB_REPO}:latest-x86_64"
+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() {
-  local tag="$1"
-  local arch_tag_base="$2"
-  docker manifest rm "${DOCKERHUB_REPO}:${tag}" || true
-  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}"
-}
+docker tag "${ECR_REPO}:${COMMIT}-aarch64" "${DOCKERHUB_REPO}:latest-aarch64"
+docker tag "${ECR_REPO}:${COMMIT}-aarch64" "${DOCKERHUB_REPO}:v${RELEASE_VERSION}-aarch64"
+docker push "${DOCKERHUB_REPO}:latest-aarch64"
+docker push "${DOCKERHUB_REPO}:v${RELEASE_VERSION}-aarch64"

-for tag in "${PRIMARY_TAGS[@]}"; do
-  docker tag "${SRC_X86}" "${DOCKERHUB_REPO}:${tag}-x86_64"
-  docker tag "${SRC_ARM}" "${DOCKERHUB_REPO}:${tag}-aarch64"
-  docker push "${DOCKERHUB_REPO}:${tag}-x86_64"
-  docker push "${DOCKERHUB_REPO}:${tag}-aarch64"
-  publish_manifest "${tag}" "${tag}"
-done
-
-ARCH_BASE="${PRIMARY_TAGS[0]}"
-for tag in "${EXTRA_MANIFEST_TAGS[@]}"; do
-  publish_manifest "${tag}" "${ARCH_BASE}"
-done
+docker manifest rm "${DOCKERHUB_REPO}:latest" || true
+docker manifest rm "${DOCKERHUB_REPO}:v${RELEASE_VERSION}" || true
+docker manifest create "${DOCKERHUB_REPO}:latest" "${DOCKERHUB_REPO}:latest-x86_64" "${DOCKERHUB_REPO}:latest-aarch64"
+docker manifest create "${DOCKERHUB_REPO}:v${RELEASE_VERSION}" "${DOCKERHUB_REPO}:v${RELEASE_VERSION}-x86_64" "${DOCKERHUB_REPO}:v${RELEASE_VERSION}-aarch64"
+docker manifest push "${DOCKERHUB_REPO}:latest"
+docker manifest push "${DOCKERHUB_REPO}:v${RELEASE_VERSION}"

 echo ""
-echo "Successfully published ${MODE} images"
+echo "Successfully published release images for v${RELEASE_VERSION}"
@@ -220,70 +220,65 @@ See `plan/voxcpm2_native_ar_design.md`.

 ### Steps

-1. **Write one adapter** under `vllm_omni/entrypoints/openai/tts_adapters/`.
-   `serving_speech.py` should not need an edit — detection, stage discovery and
-   dispatch are all derived from what the adapter declares.
+1. **Register in `serving_speech.py`** — add all 5 points in a **single commit**;
+   partial integration causes hard-to-debug failures. This file is modified by every
+   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
-   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:
-           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):
-           params = {"text": [request.input]}
-           if request.voice is not None:
-               params["voice"] = [request.voice]
-           return PreparedRequest(
-               prompt={"prompt": request.input},
-               tts_params=params,
-               model_type=self.name,
-           )
+   _YOUR_MODEL_TTS_MODEL_STAGES = {"your_stage_key"}
   ```

-   Then add the module to the import block at the bottom of
-   `tts_adapters/__init__.py` so it registers. That import line is the only shared
-   file a new model touches — which is also why the old rebase-conflict hotspot is
-   gone.
+   **Point 2** — union into `_TTS_MODEL_STAGES`:
+   ```python
+   _TTS_MODEL_STAGES: set[str] = (
+       ...
+       | _YOUR_MODEL_TTS_MODEL_STAGES
+   )
+   ```

-   > **Pure-diffusion TTS does not go through adapters yet.** Under
-   > `for_diffusion()`, `create_speech()` routes straight to
-   > `_create_diffusion_speech()` and never calls `validate()`/`build()`.
-   > `DiffusionTTSAdapter` is scaffolding with no production subclass, so logic
-   > placed in one would silently never run. Diffusion-engine models follow the
-   > existing diffusion path; wiring it through adapters is open work (#4855).
+   **Point 3** — model type detection in `_detect_tts_model_type()`:
+   ```python
+   if model_stage in _YOUR_MODEL_TTS_MODEL_STAGES:
+       return "your_model"
+   ```

-   **If a stage key alone cannot identify the model**, declare
-   `model_archs = frozenset({"YourModelForConditionalGeneration"})`; add
-   `arch_identifies_entry_stage = True` when the model owns no stage key at all
-   (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`).
+   **Point 4** — validation dispatch in `_validate_tts_request()`:
+   ```python
+   if self._tts_model_type == "your_model":
+       return self._validate_your_model_request(request)
+   ```

-   **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).
+   **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

-   > **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.
+   def _build_your_model_params(self, request) -> dict:
+       params = {"text": [request.input]}
+       if request.voice is not None:
+           params["voice"] = [request.voice]
+       return params
+   ```
+   Wire `_build_your_model_params` into `_create_tts_request()` alongside the other
+   model-specific param builders.

-   > **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.
+   > **Two dispatch patterns coexist**: Fish Speech uses a `self._is_fish_speech` boolean
+   > instance attribute checked before `elif self._is_tts`, while all newer models
+   > (CosyVoice3, MOSS-TTS-Nano) use the `_tts_model_type` string returned by
+   > `_detect_tts_model_type()`. For new models, always use the `_tts_model_type` string
+   > pattern — do not add new `_is_*` flags.
+
+   > **Unused variable rule**: only extract fields in `_build_your_model_params` 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 param builder and verify they reach the model call.
+
+   **Rebase conflict note**: when rebasing onto `main` after another model was merged,
+   `serving_speech.py` will conflict. Resolution: always keep *both* the upstream
+   model's additions and your own — never discard either side.

 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
- [ ] Only extract params in `build()` that are forwarded to the model call (ruff F841)
+- [ ] All 5 `serving_speech.py` integration points added in one commit
+- [ ] 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)
@@ -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
@@ -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:
@@ -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.
@@ -1,9 +1,9 @@
-# Repository Skills for vLLM-Omni
+# Claude Skills for vLLM-Omni

-This directory contains repository-scale skills maintained for `vllm-omni`.
-They capture repeatable workflows for common contributor and maintainer tasks
-such as model integration, CI-aligned testing, performance optimization, and
-pull request review.
+This directory contains Claude Code skills maintained for the `vllm-omni`
+repository. These skills capture repeatable workflows for common contributor
+tasks such as model integration, pull request review, and release note
+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
-  a new diffusion model into `vllm-omni`
- [`add-tts-model`](add-tts-model/SKILL.md): covers integration of new TTS
-  models and related serving workflows
- [`diffusion-perf-opt`](diffusion-perf-opt/SKILL.md): guides diffusion model
-  performance optimization, including profiling traces, parallel strategies,
-  stage timing analysis, and benchmark-driven tuning
- [`precheck-pr`](precheck-pr/SKILL.md): self-checks a branch before creating a
-  PR by validating title format, dead code, accuracy and performance claims,
-  and merge readiness
- [`quantization`](quantization/SKILL.md): guides quantization method selection,
-  model integration, checkpoint loading, and quality/performance validation
-  for vLLM-Omni
- [`review-pr`](review-pr/SKILL.md): provides a frozen-snapshot, contract-aware
-  workflow for maintainers and reviewers; contributors should use
-  `precheck-pr` for self-review
- [`vllm-omni-npu-model-runner-upgrade`](vllm-omni-npu-upgrade/SKILL.md):
-  upgrades NPU model runners to align with the latest vllm-ascend
-  `NPUModelRunner`
- [`vllm-omni-test`](vllm-omni-test/SKILL.md): guides generation and execution
-  of CI-aligned tests (L1–L4), pytest marker selection (`core_model` /
-  `advanced_model` / `full_model`, `omni` / `tts` / `diffusion`), Buildkite
-  wiring (`test-ready.yml`, `test-merge.yml`, `test-nightly.yml`,
-  `test-weekly.yml`), and copy-paste local plus CI-like `pytest` commands; see
-  `references/test-routing.md` for level-to-command mapping
+- `add-diffusion-model`: guides integration of a new diffusion model into
+  `vllm-omni`
+- `diffusion-perf-opt`: guides diffusion model performance optimization,
+  including profiling traces, parallel strategies, stage timing analysis, and
+  benchmark-driven tuning
+- `quantization`: guides quantization method selection, model integration,
+  checkpoint loading, and quality/performance validation for vLLM-Omni
+- `add-omni-model`: covers addition of new omni-modality model support
+- `add-tts-model`: covers integration of new TTS models and related serving
+  workflows
+- `generate-release-note`: helps prepare release notes for repository changes
+- `precheck-pr`: self-check a branch before creating a PR — validates PR title
+  format, catches dead code, verifies accuracy/perf claims, and confirms merge
+  readiness
+- `vllm-omni-test`: guides generation and execution of CI-aligned tests (L1–L4),
+  pytest marker selection (`core_model` / `advanced_model` / `full_model`,
+  `omni` / `tts` / `diffusion`), Buildkite wiring (`test-ready.yml`,
+  `test-merge.yml`, `test-nightly.yml`, `test-weekly.yml`), and copy-paste
+  local plus CI-like `pytest` commands; see `references/test-routing.md` for
+  level-to-command mapping
+- `review-pr`: provides a structured workflow for reviewing pull requests
+- `vllm-omni-npu-model-runner-upgrade`: upgrades NPU model runners to align with the
+  latest vllm-ascend NPUModelRunner

 ## Maintenance Guidelines

@@ -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.
@@ -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."
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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
-/apps/ @fhfuih @alex-jw-brooks
+# Engine and model_executor
+/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

-# =====================================================================
-# Module design ownership (docs/design/module/*.md)
-# Each section header cites the source design doc.
-# =====================================================================
-
-# 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
+# Usability and Observability
+/vllm_omni/deploy/ @tzhouam @lishunyang12
+/vllm_omni/metrics/ @lishunyang12
 /vllm_omni/profiler/ @gcanlin

-# Benchmarking (in-tree) — docs/design/module/benchmarking.md
-/vllm_omni/benchmarks/ @alex-jw-brooks @Bounty-hunter
+# ComfyUI
+/apps/ @fhfuih @alex-jw-brooks

-# LoRA (no dedicated design doc; ownership intentionally narrowed)
-/vllm_omni/lora/ @SamitHuang @wtomin
+# Large Scale Serving
+/vllm_omni/distributed/ @princepride @yuanheng-zhao @xuechendi @natureofnature @fake0fan

-# Transformers utils (related path only in design docs; preserves prior ownership)
-/vllm_omni/transformers_utils/ @tzhouam @yuanheng-zhao
+# Quantization and configuration
+/vllm_omni/config/ @lishunyang12 @alex-jw-brooks
+/vllm_omni/quantization/ @david6666666 @Isotr0py @lishunyang12

-# =====================================================================
-# Diffusion module family — docs/design/module/diffusion/
-# 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
+# Hardware plugins and accelerators
+/vllm_omni/platforms/ @gcanlin @tjtanaa @xuechendi
@@ -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
@@ -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):
-        first = outputs
-    else:
-        raise ValueError("Could not extract video frames from output.")
-
-    if hasattr(first, "images"):
-        frames = first.images[0] if first.images else None
+    first = outputs[0]
+    if hasattr(first, "request_output") and isinstance(first.request_output, list):
+        inner = first.request_output[0]
+        if isinstance(inner, OmniRequestOutput) and hasattr(inner, "images"):
+            frames = inner.images[0] if inner.images else None
+        else:
+            frames = inner
+    elif hasattr(first, "images") and first.images:
+        frames = first.images[0]
    else:
        raise ValueError("Could not extract video frames from output.")

@@ -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", [])
@@ -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
@@ -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 {})
-    if request_seed is not None:
-        task_extra_body["seed"] = request_seed
+    task_extra_body: dict[str, Any] = (model_cfg.get("task_extra_body") or {}).get(task) or {}

    # 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 += passthrough
+    cmd += extra_cli_args
    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:
@@ -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.
@@ -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
@@ -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 && \
@@ -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 && \
@@ -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 install triton-xpu==3.7.2 --reinstall
+    uv pip uninstall triton oneccl oneccl-devel && \
+    uv pip install triton-xpu==3.7.1 --reinstall

 FROM vllm-omni AS vllm-omni-openai

@@ -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
-      - Text-To-Image: user_guide/examples/online_serving/text_to_image.md
+      - MiMo-Audio: user_guide/examples/online_serving/mimo_audio.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,30 +50,16 @@ 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
-    - Quantization:
-      - Overview: 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
-      - Int8 W8A8: user_guide/quantization/int8.md
-      - BitsAndBytes W4: user_guide/quantization/bitsandbytes.md
-      - MXFP8 W8A8: user_guide/quantization/mxfp8.md
-      - MXFP4 W4A4: user_guide/quantization/mxfp4.md
-      - ModelOpt: user_guide/quantization/modelopt.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
+    - 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
@@ -72,15 +68,23 @@ nav:
        - 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
-      - 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
+      - CPU Offloading: user_guide/diffusion/cpu_offload.md
      - LoRA: user_guide/diffusion/lora.md
-    - Experimental:
-      - Session State Manager: features/session_state_manager.md
-  - Integrations:
-    - Custom Diffusion Pipeline: features/custom_pipeline.md
+      - Custom Pipeline: features/custom_pipeline.md
+      - Execution Modes: user_guide/diffusion/execution_modes.md
+    - Quantization:
+      - 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
+      - Int8 W8A8: user_guide/quantization/int8.md
+      - BitsAndBytes W4: user_guide/quantization/bitsandbytes.md
+      - 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
    - 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
@@ -124,8 +127,9 @@ nav:
          - Sequence Parallel: design/feature/sequence_parallel.md
          - Tensor Parallel: design/feature/tensor_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
@@ -76,47 +76,6 @@ 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.
@@ -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
-one adapter under `vllm_omni/entrypoints/openai/tts_adapters/`. The adapter declares
-how your model is recognized and owns its request handling; `serving_speech.py` should
-not need an edit.
+To expose your model through the `/v1/audio/speech` OpenAI-compatible endpoint, add
+**all five** of the following integration points to
+`vllm_omni/entrypoints/openai/serving_speech.py` in a **single commit**. Adding them
+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
-"""YourModel serving adapter."""
-
-from typing import TYPE_CHECKING
-
-from vllm_omni.entrypoints.openai.tts_adapters import register_tts_adapter
-from vllm_omni.entrypoints.openai.tts_adapters.base import ARTTSAdapter, PreparedRequest
-
-if TYPE_CHECKING:
-    from vllm_omni.entrypoints.openai.protocol.audio import OpenAICreateSpeechRequest
-
-
-@register_tts_adapter
-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:
-        """Return an error string, or None if the request is valid."""
-        if not request.input or not request.input.strip():
-            return "Input text cannot be empty"
-        return None
-
-    async def build(
-        self,
-        request: "OpenAICreateSpeechRequest",
-        sampling_params_list: list,
-        has_inline_ref_audio: bool,
-    ) -> 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(
-            prompt={"prompt": request.input},
-            tts_params=params,
-            model_type=self.name,
-        )
+_YOUR_MODEL_TTS_MODEL_STAGES = {"your_model_stage_key"}
 ```

-Then add it to the import block at the bottom of
-`vllm_omni/entrypoints/openai/tts_adapters/__init__.py` so it registers on import.
-That import line is the only shared file a new model has to touch.
+### 2. Union into `_TTS_MODEL_STAGES`

-> **Pure-diffusion TTS does not go through adapters yet.** When the server is built
-> by `OmniOpenAIServingSpeech.for_diffusion()`, `create_speech()` routes straight to
-> `_create_diffusion_speech()` and never calls `validate()` or `build()`.
-> `DiffusionTTSAdapter` is scaffolding for that migration and has no production
-> 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
-
-Two escape hatches, in order of preference:
+Add to the `_TTS_MODEL_STAGES` set union:

 ```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
+_TTS_MODEL_STAGES: set[str] = (
+    ...
+    | _YOUR_MODEL_TTS_MODEL_STAGES
+)
 ```

-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:
+### 3. Model type detection
+
+In `_detect_tts_model_type()`, add before the final `return None`:

 ```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 model_stage in _YOUR_MODEL_TTS_MODEL_STAGES:
+    return "your_model"
 ```

-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.
+### 4. Request validation dispatch

-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.
+In `_validate_tts_request()`, add before the fallback `return`:

-### 3. Reuse the shared helpers
+```python
+if self._tts_model_type == "your_model":
+    return self._validate_your_model_request(request)
+```

-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.
+### 5. Validation and parameter-builder methods

-### 4. Test it
+Add two new methods:

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

-### Do not add branches to `serving_speech.py`
+def _build_your_model_params(
+    self, request: OpenAICreateSpeechRequest
+) -> dict[str, Any]:
+    """Build additional_information dict for YourModel."""
+    params: dict[str, Any] = {"text": [request.input]}
+    if request.voice is not None:
+        params["voice"] = [request.voice]
+    # Add any other model-specific fields here
+    return params
+```

-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.
+Then wire `_build_your_model_params` into the request-dispatch block in
+`_create_tts_request()` (search for the equivalent `_build_*_params` call for an
+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.

-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.
+> **Two dispatch patterns coexist:** Fish Speech uses a `self._is_fish_speech` boolean
+> checked *before* `elif self._is_tts`. All newer models use the `_tts_model_type`
+> string pattern shown above. For new models, always use the string pattern — do not
+> add new `_is_*` boolean flags.
+
+> **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
+> a variable without forwarding it will trigger a `ruff F841` pre-commit failure.

 ### Merge conflicts

-Your adapter is a new file, so it cannot conflict. The one shared line is your entry
-in the import block at the bottom of `tts_adapters/__init__.py`, which conflicts only
-when another model lands at the same time. The resolution is always to **keep both**
-imports — never discard either side. After resolving:
+`serving_speech.py` is modified by every new model PR and is the most common source of
+rebase conflicts. When rebasing onto `main` and a conflict appears here, the resolution
+is always to **keep both** the upstream model's additions and your own — never discard
+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
@@ -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
@@ -50,14 +42,14 @@ implementation contract; it is not, by itself, a general support claim.
 - [Tensor Parallel](feature/tensor_parallel.md)
 - [VAE Patch Parallelism](feature/vae_parallel.md)

-#### Attention optimization
-
-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:
+#### Attention Backends

 - [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)
@@ -7,7 +7,6 @@ owners:
  - "@yinpeiqi"
  - "@fake0fan"
  - "@Sy0307"
-  - "@Gaohan123"
 primary_code_paths:
  - vllm_omni/core/**
  - vllm_omni/worker/**
@@ -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/**
@@ -5,7 +5,6 @@ status: draft
 owners:
  - "@Isotr0py"
  - "@princepride"
-  - "@SamitHuang"
 primary_code_paths:
  - vllm_omni/diffusion/cache/**
 related_code_paths:
@@ -3,10 +3,9 @@ title: Diffusion Model Integration
 kind: module
 status: draft
 owners:
-  - "@fhfuih"
-  - "@Bounty-hunter"
+  - "@Isotr0py"
  - "@wtomin"
-  - "@RuixiangMa"
+  - "@ZJY0516"
 primary_code_paths:
  - vllm_omni/diffusion/models/**
  - vllm_omni/diffusion/model_loader/**
@@ -6,7 +6,6 @@ owners:
  - "@Isotr0py"
  - "@princepride"
  - "@SamitHuang"
-  - "@fhfuih"
 primary_code_paths:
  - vllm_omni/diffusion/sched/**
  - vllm_omni/diffusion/executor/**
@@ -4,8 +4,7 @@ kind: module
 status: draft
 owners:
  - "@yuanheng-zhao"
-  - "@david6666666"
-  - "@lishunyang12"
+  - "@Isotr0py"
 primary_code_paths:
  - vllm_omni/diffusion/offloader/**
 related_code_paths:
@@ -6,7 +6,6 @@ owners:
  - "@princepride"
  - "@yuanheng-zhao"
  - "@xuechendi"
-  - "@Bounty-hunter"
 primary_code_paths:
  - vllm_omni/diffusion/distributed/**
  - vllm_omni/diffusion/attention/parallel/**
@@ -6,7 +6,6 @@ architecture_state: current-plus-in-flight
 owners:
  - "@alex-jw-brooks"
  - "@linyueqian"
-  - "@NickCao"
 document_stewards:
  - "@hsliuustc0106"
  - "@Gaohan123"
@@ -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
@@ -6,8 +6,6 @@ architecture_state: current
 owners:
  - "@Sy0307"
  - "@amy-why-3459"
-  - "@Gaohan123"
-  - "@alex-jw-brooks"
 document_stewards:
  - "@hsliuustc0106"
  - "@Gaohan123"
@@ -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/**
@@ -4,7 +4,6 @@ kind: module
 status: draft
 owners:
  - "@lishunyang12"
-  - "@vraiti"
 primary_code_paths:
  - vllm_omni/metrics/**
 related_code_paths:
@@ -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.
@@ -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
-by the AR-Diffusion engine's paged KV pool (PR
-[#4534](https://github.com/vllm-project/vllm-omni/pull/4534)). Cosmos3's fixed,
-encode-once UND conditioning K/V is different and is covered by the dense
-Cosmos3 adapter described below. Integrating the engine's per-session paged KV
-handle into the same byte accounting is RFC #4480 Phase 1.
+Attention KV is *not* managed here: for DreamZero it is owned by the
+AR-Diffusion engine's paged KV pool (PR
+[#4534](https://github.com/vllm-project/vllm-omni/pull/4534)). The manager
+covers the model's non-KV session state; integrating the engine's per-session
+KV 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.
@@ -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,
@@ -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]]:
-        items = []
-        for example in sorted(examples_by_category[category], key=lambda e: e.path.stem):
+    # Build the new Examples section - start with preserved items
+    examples_section = preserved_items.copy()
+
+    # 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()})
-        return items
+            category_items.append({example.nav_title: rel_path.as_posix()})

-    # Build the new Examples section - start with preserved items.
-    examples_section = preserved_items.copy()
-    for category in sorted(examples_by_category.keys()):
-        items = category_items(category)
-        if items:
+        if category_items:
+            # Format category name (e.g., "offline_inference" -> "Offline Inference")
            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"
@@ -17,101 +17,83 @@ th {
 }
 </style>

-| Architecture | Models | Example HF Models | NVIDIA GPU | AMD GPU | Ascend NPU | Intel GPU | Recipe |
-|--------------|--------|-------------------|------------|---------|-----|-----------|--------|
-| `Qwen3OmniMoeForConditionalGeneration` | Qwen3-Omni | `Qwen/Qwen3-Omni-30B-A3B-Instruct` | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/Qwen/Qwen3-Omni.md) |
-| `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` | ✅︎ |   |   |   | — |
-| `BagelForConditionalGeneration` | BAGEL (DiT-only) | `ByteDance-Seed/BAGEL-7B-MoT` | ✅︎ | ✅︎ | | ✅︎ | — |
-| `InternVLAA1Pipeline` | InternVLA-A1 | `InternRobotics/InternVLA-A1-3B` | ✅︎ | ✅︎ | | | — |
-| `Gr00tN1d7Pipeline` | GR00T N1.7 | `nvidia/GR00T-N1.7-3B` | ✅︎ | | | | — |
-| `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-2512 | `Qwen/Qwen-Image-2512` | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/Qwen/Qwen-Image-2512.md) |
-| `QwenImageEditPipeline` | Qwen-Image-Edit | `Qwen/Qwen-Image-Edit` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `QwenImageEditPlusPipeline` | Qwen-Image-Edit-2509 | `Qwen/Qwen-Image-Edit-2509` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `QwenImageLayeredPipeline` | Qwen-Image-Layered | `Qwen/Qwen-Image-Layered` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `QwenImageEditPlusPipeline` | Qwen-Image-Edit-2511 | `Qwen/Qwen-Image-Edit-2511` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `GlmImagePipeline` | GLM-Image | `zai-org/GLM-Image` | ✅︎ | ✅︎ | | | — |
-| `ZImagePipeline` | Z-Image | `Tongyi-MAI/Z-Image-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` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `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` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `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.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` | ✅︎ | ✅︎ | | | — |
-| `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` | ✅︎ | | | | — |
-| `MiniMaxH3Pipeline` | MiniMax H3 T2VA, first/last-keyframe FL2VA, and mixed-reference Ref2VA | `MiniMaxAI/MiniMax-H3` | ✅︎ | ✅︎ | | | [Published](https://recipes.vllm.ai/MiniMaxAI/MiniMax-H3) |
-| `DreamZeroPipeline` | DreamZero-DROID | `GEAR-Dreams/DreamZero-DROID` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `HeliosPipeline`, `HeliosPyramidPipeline` | Helios | `BestWishYsh/Helios-Base`, `BestWishYsh/Helios-Mid`, `BestWishYsh/Helios-Distilled` | ✅︎ | ✅︎ | ✅︎ | | — |
-| `MagiHumanPipeline` | MagiHuman | `SII-GAIR/daVinci-MagiHuman-Base-1080p` | ✅︎ | ✅︎ | | | — |
-| `OvisImagePipeline` | Ovis-Image | `OvisAI/Ovis-Image` | ✅︎ | ✅︎ | | ✅︎ | — |
-| `LongcatImagePipeline` | LongCat-Image | `meituan-longcat/LongCat-Image` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `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` | ✅︎ | | | | — |
-| `StableDiffusionXLPipeline` | Stable-Diffusion-XL | `stabilityai/stable-diffusion-xl-base-1.0` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `StableDiffusion3Pipeline` | Stable-Diffusion-3 | `stabilityai/stable-diffusion-3.5-medium` | ✅︎ | ✅︎ | | ✅︎ | — |
-| `CosyVoice3Model` | CosyVoice3 | `FunAudioLLM/Fun-CosyVoice3-0.5B-2512` | ✅︎ | ✅︎ | | ✅︎ | — |
-| `OmniVoiceModel` | OmniVoice | `k2-fsa/OmniVoice` | ✅︎ | | | | — |
-| `VoxCPM2TalkerForConditionalGeneration` | VoxCPM2 | `openbmb/VoxCPM2` | ✅︎ | | | | — |
-| `MammothModa2ForConditionalGeneration` | MammothModa2-Preview | `bytedance-research/MammothModa2-Preview` | ✅︎ | ✅︎ | | | — |
-| `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` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `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-schnell | `black-forest-labs/FLUX.1-schnell` | ✅︎ | ✅︎ | | ✅︎ | — |
-| `OmniGen2Pipeline` | OmniGen2 | `OmniGen2/OmniGen2` | ✅︎ | ✅︎ | | ✅︎ | — |
-| `StableAudioPipeline` | Stable-Audio-Open | `stabilityai/stable-audio-open-1.0` | ✅︎ | ✅︎ | | ✅︎ | — |
-| `SoulXSingerPipeline` | SoulX-Singer (SVS) | `Soul-AILab/SoulX-Singer` | ✅︎ | | | | — |
-| `SoulXSingerSVCPipeline` | SoulX-Singer-SVC | `Soul-AILab/SoulX-Singer` (`model-svc.pt`) | ✅︎ | | | | — |
-| `AudioXPipeline` | AudioX | `zhangj1an/AudioX` | ✅︎ | ✅︎ | | | — |
-| `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-Base | `Qwen/Qwen3-TTS-12Hz-1.7B-Base` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
-| `MingTTSForConditionalGeneration` | Ming-omni-tts dense 0.5B | `inclusionAI/Ming-omni-tts-0.5B` | ✅︎ | | | | — |
-| `GLMTTSForConditionalGeneration` | GLM-TTS | `zai-org/GLM-TTS` | ✅︎ | | | | — |
-| `MossTTSNanoForCausalLM` | MOSS-TTS-Nano | `OpenMOSS-Team/MOSS-TTS-Nano` | ✅︎ | | | | — |
-| `MossTTSDelayModel` | MOSS-TTS, MOSS-TTSD, MOSS-SoundEffect, MOSS-VoiceGenerator | `OpenMOSS-Team/MOSS-VoiceGenerator` | ✅︎ | | | | — |
-| `MossTTSRealtime` | MOSS-TTS-Realtime | `OpenMOSS-Team/MOSS-TTS-Realtime` | ✅︎ | | | | — |
-| `HiggsAudioV2ForConditionalGeneration` | Higgs-Audio v2 | `bosonai/higgs-audio-v2-generation-3B-base` | ✅︎ | | | | — |
-| `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` | ✅︎ | | | | — |
-| `IndexTTS25TalkerForConditionalGeneration` | IndexTTS-2.5 | native `checkpoints/` bundle | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/IndexTeam/IndexTTS-2_5.md) |
-| `NextStep11Pipeline` | NextStep-1.1 | `stepfun-ai/NextStep-1.1` | ✅︎ | ✅︎ | | ✅︎ | — |
-| `MiMoAudioModel` | MiMo-Audio-7B-Instruct | `XiaomiMiMo/MiMo-Audio-7B-Instruct` | ✅︎ | ✅︎ | | | — |
-| `MiMoV2ASRForCausalLM` | MiMo-V2.5-ASR | `XiaomiMiMo/MiMo-V2.5-ASR` | ✅︎ | ✅︎ | | | — |
-| `Flux2Pipeline` | FLUX.2-dev | `black-forest-labs/FLUX.2-dev` | ✅︎ | ✅︎ | | | — |
-| `FishSpeechSlowARForConditionalGeneration` | Fish Speech S2 Pro | `fishaudio/s2-pro` | ✅︎ | ✅︎ | | ✅︎ | — |
-| `DreamIDOmniPipeline` | DreamID-Omni | `XuGuo699/DreamID-Omni` | ✅︎ | ✅︎ | | | — |
-| `SenseNovaU1Pipeline` | SenseNova-U1 (DiT-only) | `SenseNova/SenseNova-U1-8B-MoT` | ✅︎ | | | | — |
-| `LancePipeline` | Lance | `bytedance-research/Lance` | ✅︎ | | | | — |
-| `HunyuanVideo15Pipeline` | HunyuanVideo-1.5-T2V | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v`, `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v` | ✅︎ | ✅︎ | | | — |
-| `HunyuanVideo15ImageToVideoPipeline` | HunyuanVideo-1.5-I2V | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_i2v`, `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_i2v` | ✅︎ | ✅︎ | | | — |
-| `VoxtralTTSForConditionalGeneration` | Voxtral TTS | `mistralai/Voxtral-4B-TTS-2603` | ✅︎ | ✅︎ | | | — |
-| `CovoAudioForConditionalGeneration` | Covo-Audio-Chat | `tencent/Covo-Audio-Chat` | ✅︎ | | | | — |
-|`DyninOmniForConditionalGeneration` | Dynin-Omni | `snu-aidas/Dynin-Omni` | ✅︎ | | | | — |
-| `MiniCPMO45OmniForConditionalGeneration` | MiniCPM-o 4.5 | `openbmb/MiniCPM-o-4_5` | ✅︎ | | ✅︎ | | — |
-| `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.
+| Architecture | Models | Example HF Models | NVIDIA GPU | AMD GPU | Ascend NPU | Intel GPU |
+|--------------|--------|-------------------|------------|---------|-----|-----------|
+| `Qwen3OmniMoeForConditionalGeneration` | Qwen3-Omni | `Qwen/Qwen3-Omni-30B-A3B-Instruct` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `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` | ✅︎ |   |   |   |
+| `BagelForConditionalGeneration` | BAGEL (DiT-only) | `ByteDance-Seed/BAGEL-7B-MoT` | ✅︎ | ✅︎ | | ✅︎ |
+| `InternVLAA1Pipeline` | InternVLA-A1 | `InternRobotics/InternVLA-A1-3B` | ✅︎ | ✅︎ | | |
+| `Gr00tN1d7Pipeline` | GR00T N1.7 | `nvidia/GR00T-N1.7-3B` | ✅︎ | | | |
+| `HunyuanImage3ForCausalMM` | HunyuanImage3.0 (DiT-only) | `tencent/HunyuanImage-3.0`, `tencent/HunyuanImage-3.0-Instruct` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `QwenImagePipeline` | Qwen-Image | `Qwen/Qwen-Image` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `QwenImagePipeline` | Qwen-Image-2512 | `Qwen/Qwen-Image-2512` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `QwenImageEditPipeline` | Qwen-Image-Edit | `Qwen/Qwen-Image-Edit` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `QwenImageEditPlusPipeline` | Qwen-Image-Edit-2509 | `Qwen/Qwen-Image-Edit-2509` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `QwenImageLayeredPipeline` | Qwen-Image-Layered | `Qwen/Qwen-Image-Layered` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `QwenImageEditPlusPipeline` | Qwen-Image-Edit-2511 | `Qwen/Qwen-Image-Edit-2511` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `GlmImagePipeline` | GLM-Image | `zai-org/GLM-Image` | ✅︎ | ✅︎ | | |
+| `ZImagePipeline` | Z-Image | `Tongyi-MAI/Z-Image-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` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `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` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `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.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` | ✅︎ | ✅︎ | | |
+| `LTX2DistilledPipeline` | LTX-2 distilled two-stage T2V and I2V | `rootonchair/LTX-2-19b-distilled` | ✅︎ | ✅︎ | | |
+| `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` | ✅︎ | | | |
+| `DreamZeroPipeline` | DreamZero-DROID | `GEAR-Dreams/DreamZero-DROID` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `HeliosPipeline`, `HeliosPyramidPipeline` | Helios | `BestWishYsh/Helios-Base`, `BestWishYsh/Helios-Mid`, `BestWishYsh/Helios-Distilled` | ✅︎ | ✅︎ | ✅︎ | |
+| `MagiHumanPipeline` | MagiHuman | `SII-GAIR/daVinci-MagiHuman-Base-1080p` | ✅︎ | ✅︎ | | |
+| `OvisImagePipeline` | Ovis-Image | `OvisAI/Ovis-Image` | ✅︎ | ✅︎ | | ✅︎ |
+| `LongcatImagePipeline` | LongCat-Image | `meituan-longcat/LongCat-Image` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `LongCatImageEditPipeline` | LongCat-Image-Edit | `meituan-longcat/LongCat-Image-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` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `StableDiffusion3Pipeline` | Stable-Diffusion-3 | `stabilityai/stable-diffusion-3.5-medium` | ✅︎ | ✅︎ | | ✅︎ |
+| `CosyVoice3Model` | CosyVoice3 | `FunAudioLLM/Fun-CosyVoice3-0.5B-2512` | ✅︎ | ✅︎ | | ✅︎ |
+| `OmniVoiceModel` | OmniVoice | `k2-fsa/OmniVoice` | ✅︎ | | | |
+| `VoxCPM2TalkerForConditionalGeneration` | VoxCPM2 | `openbmb/VoxCPM2` | ✅︎ | | | |
+| `MammothModa2ForConditionalGeneration` | MammothModa2-Preview | `bytedance-research/MammothModa2-Preview` | ✅︎ | ✅︎ | | |
+| `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` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `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-schnell | `black-forest-labs/FLUX.1-schnell` | ✅︎ | ✅︎ | | ✅︎ |
+| `OmniGen2Pipeline` | OmniGen2 | `OmniGen2/OmniGen2` | ✅︎ | ✅︎ | | ✅︎ |
+| `StableAudioPipeline` | Stable-Audio-Open | `stabilityai/stable-audio-open-1.0` | ✅︎ | ✅︎ | | ✅︎ |
+| `SoulXSingerPipeline` | SoulX-Singer (SVS) | `Soul-AILab/SoulX-Singer` | ✅︎ | | | |
+| `SoulXSingerSVCPipeline` | SoulX-Singer-SVC | `Soul-AILab/SoulX-Singer` (`model-svc.pt`) | ✅︎ | | | |
+| `AudioXPipeline` | AudioX | `zhangj1an/AudioX` | ✅︎ | ✅︎ | | |
+| `Qwen3TTSForConditionalGeneration` | Qwen3-TTS-12Hz-1.7B-CustomVoice | `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-Base | `Qwen/Qwen3-TTS-12Hz-1.7B-Base` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+| `MingTTSForConditionalGeneration` | Ming-omni-tts dense 0.5B | `inclusionAI/Ming-omni-tts-0.5B` | ✅︎ | | | |
+| `GLMTTSForConditionalGeneration` | GLM-TTS | `zai-org/GLM-TTS` | ✅︎ | | | |
+| `MossTTSNanoForCausalLM` | MOSS-TTS-Nano | `OpenMOSS-Team/MOSS-TTS-Nano` | ✅︎ | | | |
+| `MossTTSDelayModel` | MOSS-TTS, MOSS-TTSD, MOSS-SoundEffect, MOSS-VoiceGenerator | `OpenMOSS-Team/MOSS-VoiceGenerator` | ✅︎ | | | |
+| `MossTTSRealtime` | MOSS-TTS-Realtime | `OpenMOSS-Team/MOSS-TTS-Realtime` | ✅︎ | | | |
+| `HiggsAudioV2ForConditionalGeneration` | Higgs-Audio v2 | `bosonai/higgs-audio-v2-generation-3B-base` | ✅︎ | | | |
+| `HiggsMultimodalQwen3ForConditionalGeneration` | Higgs-Audio v3 (TTS) | `bosonai/higgs-audio-v3-tts-4b` | ✅︎ | | | |
+| `IndexTTS2TalkerForConditionalGeneration` | IndexTTS-2 | `IndexTeam/IndexTTS-2` | ✅︎ | | | |
+| `NextStep11Pipeline` | NextStep-1.1 | `stepfun-ai/NextStep-1.1` | ✅︎ | ✅︎ | | ✅︎ |
+| `MiMoAudioModel` | MiMo-Audio-7B-Instruct | `XiaomiMiMo/MiMo-Audio-7B-Instruct` | ✅︎ | ✅︎ | | |
+| `MiMoV2ASRForCausalLM` | MiMo-V2.5-ASR | `XiaomiMiMo/MiMo-V2.5-ASR` | ✅︎ | ✅︎ | | |
+| `Flux2Pipeline` | FLUX.2-dev | `black-forest-labs/FLUX.2-dev` | ✅︎ | ✅︎ | | |
+| `FishSpeechSlowARForConditionalGeneration` | Fish Speech S2 Pro | `fishaudio/s2-pro` | ✅︎ | ✅︎ | | ✅︎ |
+| `DreamIDOmniPipeline` | DreamID-Omni | `XuGuo699/DreamID-Omni` | ✅︎ | ✅︎ | | |
+| `SenseNovaU1Pipeline` | SenseNova-U1 (DiT-only) | `SenseNova/SenseNova-U1-8B-MoT` | ✅︎ | | | |
+| `LancePipeline` | Lance | `bytedance-research/Lance` | ✅︎ | | | |
+| `HunyuanVideo15Pipeline` | HunyuanVideo-1.5-T2V | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v`, `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_t2v` | ✅︎ | ✅︎ | | |
+| `HunyuanVideo15ImageToVideoPipeline` | HunyuanVideo-1.5-I2V | `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_i2v`, `hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-720p_i2v` | ✅︎ | ✅︎ | | |
+| `VoxtralTTSForConditionalGeneration` | Voxtral TTS | `mistralai/Voxtral-4B-TTS-2603` | ✅︎ | ✅︎ | | |
+| `CovoAudioForConditionalGeneration` | Covo-Audio-Chat | `tencent/Covo-Audio-Chat` | ✅︎ | | | |
+|`DyninOmniForConditionalGeneration` | Dynin-Omni | `snu-aidas/Dynin-Omni` | ✅︎ | | | |
+| `MiniCPMO45OmniForConditionalGeneration` | MiniCPM-o 4.5 | `openbmb/MiniCPM-o-4_5` | ✅︎ | | ✅︎ | |
+| `ErnieImagePipeline` | ERNIE-Image | `baidu/ERNIE-Image`, `baidu/ERNIE-Image-Turbo` | ✅︎ | ✅︎ | ✅︎ | ✅︎ |
+|`HiDreamImagePipeline` | HiDream-I1-Full | `HiDream-ai/HiDream-I1-Full` | ✅︎ | ✅︎ | | |

 ✅︎ 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.
@@ -283,20 +283,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
-necessary, promoting a real-video suffix to its always-kept prefix segment. It never pads: rf_v2
-does not consume an attention mask for padded keys. The remaining video rows stay sparse, while the
-promoted rows remain visible to every query and key.
+Sparsity is only applied when the video segment is a **multiple of 128 rows**, where the row count
+is `latent_t × (height / 32) × (width / 32)`. Otherwise `rf_v2`'s block mask and the kernel's own
+tiling disagree on the block count, and the block straddling the seam mixes video and prefix rows
+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
-128-block residue, and its two non-8-wide latent columns form a 2928-row rearranged suffix.
-MindIE-SD promotes 2976 rows, leaving 59520 sparse rows (`465 × 128`). This keeps the block mask
-and kernel tiling aligned, at the cost of retaining more blocks.
+Alignment is necessary, not sufficient, for good quality. `rf_v2` groups video positions into 8x8
+spatial tiles (two tiles fill one 128-row block), which is what makes a selected block a compact
+patch of the frame. When the latent `h` or `w` is not a multiple of 8, the leftover rows or columns
+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
-creates an always-kept residual suffix and lowers realized sparsity. "Multiple of 8" on the latent
-grid means **width and height that are multiples of 256**. This path requires a MindIE-SD release
-that implements protected video tails for rf_v2.
+"Multiple of 8" on the latent grid means **width and height that are multiples of 256**. Aligned
+resolutions off that grid still run sparse; they just lose more fidelity at the same `sparsity`,
+which you can buy back with `start_step`.

 ## End-to-End Benchmark (BF16, sm_120 RTX Pro 6000 Blackwell)

@@ -1,18 +1,14 @@
 # LoRA (Low-Rank Adaptation) Guide

-LoRA (Low-Rank Adaptation) enables fine-tuning diffusion models by adding trainable low-rank matrices to existing model weights. vLLM-Omni supports two LoRA backends: **PEFT** for PEFT-style adapters, and **Distill** usually for few-steps inference. **PEFT** backend allows you to customize model behavior without modifying the base model weights. **Distill** backend fuses LoRA weights into the base model at initialization.
+LoRA (Low-Rank Adaptation) enables fine-tuning diffusion models by adding trainable low-rank matrices to existing model weights. vLLM-Omni currently supports PEFT-style LoRA adapters, allowing you to customize model behavior without modifying the base model weights.

 ## Overview

-LoRA adapters are lightweight, model-specific fine-tuning weights that can be applied to diffusion models in two ways:
-
- **PEFT backend** (`--lora-backend peft`, default): Loads a PEFT-format adapter folder via `DiffusionLoRAManager`. Adapters are cached (LRU) and activated per request via `LoRARequest`. It uses a unified LoRA handling mechanisms similar to vLLM with LRU cache management.
- **Distill backend** (`--lora-backend distill`): Calls `pipeline.load_lora_weights` once at initialization to fuse one or more concrete checkpoint files directly into the base weights. Typically used for distilled few-step LoRAs (e.g. Lightning, LightX2V).
+LoRA adapters are lightweight, model-specific fine-tuning weights that can be dynamically loaded and applied to diffusion models. vLLM-Omni uses a unified LoRA handling mechanism similar to vLLM with LRU cache management.

 ## LoRA Adapter Format

-### PEFT (Parameter-Efficient Fine-Tuning) format (default)
-A typical PEFT-format LoRA adapter directory structure:
+LoRA adapters must be in **PEFT (Parameter-Efficient Fine-Tuning)** format. A typical LoRA adapter directory structure:

 ```
 lora_adapter/
@@ -29,20 +25,19 @@ The `adapter_config.json` file contains metadata about the LoRA adapter, includi

 ### Offline Inference

-#### PEFT backend: pre-loaded LoRA
+#### Pre-loaded LoRA

-Load a PEFT-format LoRA adapter at initialization. The adapter is pre-loaded into the cache and can be activated per request:
+Load a LoRA adapter at initialization. This adapter is pre-loaded into the cache and can be activated by requests:

 ```python
 from vllm_omni import Omni
 from vllm_omni.lora.request import LoRARequest

-lora_path = "/path/to/lora_adapter"
+lora_path="/path/to/lora_adapter"

 omni = Omni(
    model="stabilityai/stable-diffusion-3.5-medium",
-    lora_path=lora_path,
-    lora_backend="peft",  # default, can be omitted
+    lora_path=lora_path
 )

 lora_request = LoRARequest(
@@ -58,98 +53,6 @@ outputs = omni.generate(
 )
 ```

-#### Distill backend: fuse distilled LoRA at init
-
-For distilled few-step LoRAs, pass `lora_backend="distill"` together with one or more concrete `.safetensors` files. The weights are fused into the base model once at init; subsequent `generate()` calls do not need a `LoRARequest`.
-
-##### Supported pipelines
-
-For Qwen-Image and Wan pipelines, the distill backend calls `pipeline.load_lora_weights(...)` during worker initialization.
-
-| Pipeline | Supported distilled LoRA repo | Notes |
-|----------|--------------------------------|-------|
-| `QwenImagePipeline` | `lightx2v/Qwen-Image-2512-Lightning` | Used with Qwen-Image-2512 Lightning-style few-step inference. |
-| `Wan22Pipeline` | `lightx2v/Wan2.1-Distill-Loras`, `lightx2v/Wan2.2-Distill-Loras` | Wan2.1 uses one LoRA file. For dual-transformer Wan2.2 MoE, pass high-noise then low-noise LoRA files. |
-| `Wan22I2VPipeline` | `lightx2v/Wan2.2-Distill-Loras` | For dual-transformer Wan2.2 MoE, pass high-noise then low-noise LoRA files. |
-
-Other diffusion pipelines are not currently listed as supporting distilled LoRA. Use the PEFT backend for request-time adapters, or bake converted weights into a local Diffusers directory before serving.
-
-Single-file example (Qwen-Image-Lightning):
-
-```python
-from vllm_omni import Omni
-
-omni = Omni(
-    model="Qwen/Qwen-Image-2512",
-    lora_path="/path/to/Qwen-Image-2512-Lightning.safetensors",
-    lora_backend="distill",
-)
-
-outputs = omni.generate(prompt="A piece of cheesecake")
-```
-
-Multi-file example (Wan2.2 MoE, high + low noise):
-
-```python
-from vllm_omni import Omni
-
-omni = Omni(
-    model="Wan-AI/Wan2.2-T2V-A14B-Diffusers",
-    lora_path=[
-        "/path/to/wan2.2_high_noise_lora.safetensors",   # -> transformer
-        "/path/to/wan2.2_low_noise_lora.safetensors",    # -> transformer_2
-    ],
-    lora_backend="distill",
-)
-```
-
-The CLI examples under `examples/offline_inference/` accept the same flags, e.g.:
-
-```bash
-python examples/offline_inference/text_to_video/text_to_video.py \
-  --model Wan-AI/Wan2.2-T2V-A14B-Diffusers \
-  --lora-backend distill \
-  --lora-path /path/to/high.safetensors /path/to/low.safetensors \
-  --prompt "A cat playing with yarn"
-```
-
-##### Online serving
-
-Distilled LoRAs can also be fused when an online diffusion server starts. The
-adapter remains active for the lifetime of that server, so requests do not pass
-a per-request `lora` field.
-
-```bash
-vllm serve Qwen/Qwen-Image-2512 \
-  --omni \
-  --port 8091 \
-  --lora-backend distill \
-  --lora-path /path/to/Qwen-Image-2512-Lightning-4steps.safetensors
-```
-
-Then send a normal generation request with the sampling settings expected by
-the distilled checkpoint:
-
-```bash
-curl -s http://localhost:8091/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{
-    "messages": [
-      {"role": "user", "content": "A Chinese female college student, around 20 years old, with a very short haircut that conveys a gentle, artistic vibe. Her hair naturally falls to partially cover her cheeks, projecting a tomboyish yet charming demeanor. She has cool-toned fair skin and delicate features, with a slightly shy yet subtly confident expression—her mouth crooked in a playful, youthful smirk. She wears an off-shoulder top, revealing one shoulder, with a well-proportioned figure. The image is framed as a close-up selfie: she dominates the foreground, while the background clearly shows her dormitory—a neatly made bed with white linens on the top bunk, a tidy study desk with organized stationery, and wooden cabinets and drawers. The photo is captured on a smartphone under soft, even ambient lighting, with natural tones, high clarity, and a bright, lively atmosphere full of youthful, everyday energy."}
-    ],
-    "extra_body": {
-      "height": 1024,
-      "width": 1024,
-      "num_inference_steps": 4,
-      "true_cfg_scale": 1.0,
-      "seed": 42
-    }
-  }' | jq -r '.choices[0].message.content[0].image_url.url' | cut -d',' -f2 | base64 -d > qwen_image_distill_lora_output.png
-```
-
-For Wan2.2 MoE serving, pass the high-noise checkpoint first and the low-noise
-checkpoint second to `--lora-path`.
-
 !!! note "Server-side Path Requirement"
    The LoRA adapter path (`local_path`) must be readable on the **server** machine. If your client and server are on different machines, ensure the LoRA adapter is accessible via a shared mount or copied to the server.

@@ -238,7 +141,6 @@ Notes:

 - This route avoids runtime LoRA loading changes in vLLM-Omni when you choose to bake converted weights into a local Diffusers directory.
 - Output quality and speed depend on the replacement checkpoints and sampling params you choose.
- If you only need to fuse distilled LoRAs into a Wan2.2 checkpoint at load time (without the full LightX2V convert + assemble pipeline), you can instead pass them directly via `--lora-backend distill --lora-path <high>.safetensors <low>.safetensors`. See the [Distill backend](#distill-backend-fuse-distilled-lora-at-init) section above.


 ## See Also
@@ -164,12 +164,10 @@ In `DiffusionParallelConfig`:
 | `ulysses_degree` | int | 1 | Number of GPUs for Ulysses-SP. Uses all-to-all communication. |
 | `ring_degree` | int | 1 | Number of GPUs for Ring-Attention. Uses P2P ring communication. |
 | `ulysses_mode` | str | `"default"` | Ulysses attention mode. Set to `"advanced_uaa"` to handle arbitrary sequence lengths and head counts without padding. |
-| `mask_sp_padding` | bool | `False` | When the sequence length is not divisible by the SP size, tokens are auto-padded with zeros. Set to `True` to mask those padding tokens (strict, but uses the slower varlen attention path); the default `False` leaves them unmasked, keeping the fast path with negligible numerical impact. |

 **Notes:**
 - Total sequence parallel size equals to `ulysses_degree × ring_degree`
 - Degrees must evenly divide the sequence length for optimal performance (or use `ulysses_mode="advanced_uaa"` for Ulysses-SP)
- `mask_sp_padding` is an experimental feature, currently only supported by `Wan2.2`, `Wan2.2 Vace`, `Qwen-Image`, `Flux 2`, and `HunyuanVideo 1.5`


 ## Best Practices
@@ -1,60 +0,0 @@
-# Diffusion Startup and Loading
-
-Large diffusion models can take several minutes to load at startup. vLLM-Omni
-loads safetensors shards in parallel to reduce this initialization time.
-
-Multi-thread weight loading is enabled by default with four threads. No
-configuration is needed for the default behavior.
-
-## Configuration
-
-| Parameter | CLI flag | Default | Description |
-| --- | --- | --- | --- |
-| `enable_multithread_weight_load` | `--disable-multithread-weight-load` | `True` | Pass the flag to disable multi-thread loading |
-| `num_weight_load_threads` | `--num-weight-load-threads` | `4` | Number of parallel weight-loading threads |
-
-!!! tip
-
-    The default balances startup speed and disk I/O contention. Fast NVMe
-    storage may benefit from more threads, while network storage or hard disks
-    may not.
-
-## Online Serving
-
-```bash
-# Default: multi-thread loading with four threads
-vllm serve Qwen/Qwen-Image --omni --port 8091
-
-# Increase the thread count
-vllm serve Wan-AI/Wan2.2-I2V-A14B-Diffusers --omni \
-  --num-weight-load-threads 8
-
-# Disable multi-thread loading
-vllm serve Qwen/Qwen-Image --omni --disable-multithread-weight-load
-```
-
-## Offline Inference
-
-```python
-from vllm_omni import Omni
-
-# Default: multi-thread loading with four threads
-omni = Omni(model="Qwen/Qwen-Image")
-
-# Increase the thread count
-omni = Omni(
-    model="Wan-AI/Wan2.2-I2V-A14B-Diffusers",
-    num_weight_load_threads=8,
-)
-```
-
-## Reference Benchmarks
-
-The following measurements were collected on NVIDIA H800 hardware. Treat them
-as reference results rather than a guarantee for other storage or hardware
-configurations.
-
-| Model | Sequential loading | Multi-thread loading | Speedup |
-| --- | ---: | ---: | ---: |
-| **Qwen/Qwen-Image** (53.7 GiB) | 168 s | 27 s | **6.2x** |
-| **Wan-AI/Wan2.2-I2V-A14B-Diffusers** (64.5 GiB) | 283 s | 56 s | **5.1x** |
@@ -49,7 +49,7 @@ Parallelism methods distribute computation across GPUs without quality loss (mat

 | Method | Description | Best For |
 |--------|-------------|----------|
-| **[Multi-Thread Weight Loading](diffusion/startup_and_loading.md)** | Loads safetensors shards in parallel using a thread pool | All diffusion models; reduces startup from minutes to seconds |
+| **[Multi-Thread Weight Loading](#multi-thread-weight-loading)** | Loads safetensors shards in parallel using a thread pool | All diffusion models; reduces startup from minutes to seconds |

 **Note:** Some acceleration methods can be combined together for optimized performance. See [Feature Compatibility Table](#feature-compatibility) and [Feature Compatibility Tutorial](feature_compatibility.md) for detailed configuration examples.

@@ -100,9 +100,7 @@ The following tables show which models support each feature:

 - **🔀SP (Ulysses & Ring)**: Includes both Ulysses-SP and Ring-Attention methods
 - ✅ = Fully supported
- ✅* = Supported with the constraint listed below the table
 - ❌ = Not supported
- ❓ = Not verified; not recommended

 > Notes:

@@ -121,7 +119,7 @@ The following tables show which models support each feature:
 | **FLUX.2-dev**           |     ✅     |     ✅      |           ✅           |       ✅        |         ✅         |          ❌          |   ✅    |             ✅             |          ✅           |       ❌        |        ❌         |
 | **GLM-Image**            |     ❌     |     ❌      |           ❌           |       ✅        |         ✅         |          ❌          |   ✅    |             ❌             |          ❌           |       ❌        |        ❌         |
 | **Hidream-I1-Full**        |     ❌     |     ❌      |           ❌           |       ❌        |         ✅         |          ❌          |   ❌    |             ❌             |          ❌           |       ❌        |        ❌         |
-| **HunyuanImage3**        |     ❌     |     ✅      |           ❌           |       ❌        |         ✅         |          ❌          |   ❌    |             ❌             |          ❌           |       ✅        |        ✅*        |
+| **HunyuanImage3**        |     ❌     |     ✅      |           ❌           |       ❌        |         ✅         |          ❌          |   ❌    |             ❌             |          ❌           |       ✅        |        ❌         |
 | **Krea 2**               |     ❌     |     ✅      |           ❌           |       ❌        |         ❌         |          ❌          |   ✅    |             ✅             |      ✅ (decode)      |       ❌        |        ❌         |
 | **LongCat-Image**        |     ✅     |     ✅      |           ✅           |       ✅        |         ✅         |          ❌          |   ❌    |             ✅             |          ❌           |       ❌        |        ❌         |
 | **LongCat-Image-Edit**   |     ✅     |     ✅      |           ✅           |       ✅        |         ✅         |          ❌          |   ❌    |             ✅             |          ❌           |       ❌        |        ❌         |
@@ -147,7 +145,6 @@ The following tables show which models support each feature:
 > 2. `Tongyi-MAI/Z-Image-Turbo` and `SII-GAIR/daVinci-MagiHuman-Base-1080p` are distilled models with minimal NFEs; CFG-Parallel is not necessary.
 > 3. Cosmos3 T2I uses `Cosmos3OmniDiffusersPipeline` with `modalities=["image"]`. Model-level CPU offload swaps the nested UND reasoner and GEN generator pathways; layerwise offload remains available for blockwise GEN/UND offload.
 > 4. Krea 2 currently supports single-GPU inference plus LoRA, Cache-DiT, HSDP, CPU/layerwise offload, and VAE-patch-parallel (decode). TP/SP/CFG-Parallel are not yet wired. The few-step distilled (Turbo) checkpoint uses `is_distilled=true` (fixed timestep shift `mu=1.15`); generate at 2048x2048 by default with `num_inference_steps≈8` and `guidance_scale=0`. The Raw checkpoint uses 1024x1024, `num_inference_steps=28`, and `guidance_scale=4.5`.
-> 5. HunyuanImage3 supports step execution. Multi-request step execution requires `TORCH_SDPA`; see [Diffusion Execution Modes](diffusion/execution_modes.md#step-execution).

 ### VideoGen

@@ -158,15 +155,11 @@ The following tables show which models support each feature:
 | **Wan2.1-VACE**              |     ❌     |     ✅      |           ✅           |       ✅        |         ✅         |         ❌         |   ✅    |             ✅             |      ✅ (decode)      |       ❌        |        ❌         |
 | **LTX-2**                    |     ❌     |     ✅      |           ✅           |       ✅        |         ✅         |         ❌         |   ✅    |             ✅             |      ✅ (decode)      |       ❌        |        ❌         |
 | **LTX-2.3**                  |     ❌     |     ✅      |           ✅           |       ✅        |         ✅         |         ❌         |   ✅    |             ✅             |      ✅ (decode)      |       ❌        |        ❌         |
-| **Helios**                   |     ❌     |     ✅      |           ✅           |       ✅        |         ✅         |         ❌         |   ✅    |             ✅             |          ❌           |       ❌        |        ✅*        |
+| **Helios**                   |     ❌     |     ✅      |           ✅           |       ✅        |         ✅         |         ❌         |   ✅    |             ✅             |          ❌           |       ❌        |        ❌         |
 | **HunyuanVideo-1.5 T2V I2V** |     ❌     |     ✅      |           ✅           |       ✅        |         ✅         |         ❌         |   ✅    |             ✅             |  ✅ (encode/decode)   |       ✅        |        ❌         |
 | **DreamID-Omni**             |     ❌     |     ❌      |           ❌           |       ✅        |         ❌         |         ❌         |   ✅    |             ✅             |          ❌           |       ❌        |        ❌         |
 | **Cosmos3**                  |     ❌     |     ✅      |           ✅           |       ✅        |         ✅         |         ❌         |   ✅    |             ✅             |  ✅ (encode/decode)   |       ✅        |        ❌         |
-| **LongCat-Video-Avatar-1.5** |     ❌     |     ❌      |           ❌           |       ❌        |         ❌         |         ❌         |   ❌    |             ❌             |          ❌           |       ❌        |        ❌         |
-| **MiniMax-H3**               | ✅ (FL2VA) |     ✅      |           ✅           |       ❌        |       ✅ (DiT/TE)  |         ❌         |   ✅    |             ✅             |       ✅ (tile)       |      ✅ (DiT)      |        ❌         |
-
-> **Step execution note:** Helios supports single-request step execution only;
-> use `max_num_seqs=1`.
+| **MiniMax-H3**               |     ❌     |     ✅      |           ✅           |       ❌        |       ✅ (DiT/TE)  |         ❌         |   ✅    |             ✅             |       ✅ (tile)       |      ✅ (DiT)      |        ❌         |

 **Frame Interpolation Support**

@@ -196,7 +189,7 @@ The following tables show which models support each feature:
 | **🔀Ring-Attn** | ✅ | ✅ | ✅ | | | | | | | | | | | |
 | **🔀CFG-Parallel** | ✅ | ✅ | ✅ | ✅ | | | | | | | | | | |
 | **🔀Tensor Parallel** | ✅ | ✅ | ✅ | ✅ | ✅ | | | | | | | | | |
-| **🔀HSDP** | ❓ | ❓ | ✅ | ❓ | ✅ | ❌ | | | | | | | | |
+| **🔀HSDP** | ❓ | ❓ | ❓ | ❓ | ❓ | ❌ | | | | | | | | |
 | **🔀Expert Parallel** | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | | | | | | | |
 | **💾CPU Offloading (Layerwise)** | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | | | | | |
 | **💾CPU Offloading (Module-wise)** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❓ | ❓ | ❌ | | | | | |
@@ -207,43 +200,97 @@ The following tables show which models support each feature:

 !!! info

-    1. HSDP can be combined with Ulysses-SP or CFG-Parallel. Tensor Parallel
-       and HSDP are not compatible; other HSDP combinations in the table
-       remain unverified.
+    1. Tensor Parallel and HSDP are not compatible.
    2. TeaCache and Cache-DiT are not compatible.
    3. CPU Offloading (Layerwise) and CPU Offloading (Module-wise) are not compatible.
-    4. The CPU Offloading (Layerwise) row describes local layerwise offload.
-       Multi-device Distributed Layerwise Offload has a separate topology and
-       compatibility matrix in the [CPU Offloading guide](diffusion/cpu_offload.md#distributed-layerwise-offloading).
-    5. The compatibility matrix uses FP8 as the representative quantization method.
+    4. CPU Offloading (Layerwise) supports single-card for now.
+    5. Using FP8-Quant as an example of qunatization methods.
    6. Step Execution is not compatible with any diffusion cache backend. LoRA is supported, but each scheduled batch must use a single adapter (requests with different `lora_request` or `lora_scale` are kept in separate batches).


 ## Multi-Thread Weight Loading

-The loading guide now lives at [Diffusion Startup and
-Loading](diffusion/startup_and_loading.md). This heading remains so existing
-links to this section continue to work.
+Large diffusion models can take several minutes to load weights at startup (e.g., ~3 min for Qwen-Image, ~5 min for Wan2.2 I2V 14B). Multi-thread weight loading speeds up this process by loading safetensors shards in parallel using a thread pool instead of sequentially.
+
+This optimization is **enabled by default** with 4 threads. No configuration is needed for the default behavior.
+
+### Configuration
+
+| Parameter | CLI Flag | Default | Description |
+|-----------|----------|---------|-------------|
+| `enable_multithread_weight_load` | `--disable-multithread-weight-load` | `True` (enabled) | Pass the flag to disable multi-thread loading |
+| `num_weight_load_threads` | `--num-weight-load-threads` | `4` | Number of threads for parallel weight loading |
+
+!!! tip
+    The default of 4 threads balances speed and disk I/O contention. On fast NVMe storage you may benefit from more threads (e.g., 8). On HDD or network storage, the default of 4 avoids saturating I/O bandwidth.
+
+### Online Serving
+
+```bash
+# Default (multi-thread enabled, 4 threads)
+vllm serve Qwen/Qwen-Image --omni --port 8091
+
+# Custom thread count
+vllm serve Wan-AI/Wan2.2-I2V-A14B-Diffusers --omni --num-weight-load-threads 8
+
+# Disable multi-thread loading
+vllm serve Qwen/Qwen-Image --omni --disable-multithread-weight-load
+```
+
+### Offline Inference
+
+```python
+from vllm_omni import Omni
+
+# Default (multi-thread enabled, 4 threads)
+omni = Omni(model="Qwen/Qwen-Image")
+
+# Custom thread count
+omni = Omni(
+    model="Wan-AI/Wan2.2-I2V-A14B-Diffusers",
+    num_weight_load_threads=8,
+)
+```
+
+### Benchmarks
+
+Measured on NVIDIA H800:
+
+| Model | Before | After | Speedup |
+|-------|--------|-------|---------|
+| **Qwen/Qwen-Image** (53.7 GiB) | 168s | 27s | **6.2x** |
+| **Wan-AI/Wan2.2-I2V-A14B-Diffusers** (64.5 GiB) | 283s | 56s | **5.1x** |

 ## Learn More

-The Diffusion Acceleration navigation groups the remaining guides as follows:
+**Cache Acceleration:**

-| Area | Guide |
-| --- | --- |
-| Compatibility | [Feature Compatibility](feature_compatibility.md) |
-| CPU offloading | [CPU Offloading](diffusion/cpu_offload.md) |
-| Cache acceleration | [TeaCache](diffusion/cache_acceleration/teacache.md), [Cache-DiT](diffusion/cache_acceleration/cache_dit.md) |
-| Parallelism | [Parallelism Overview](diffusion/parallelism/overview.md) |
-| Attention | [Attention Backends](diffusion/attention_backends.md) |
-| Compilation | [Regional Compilation](diffusion/regional_compilation.md) |
-| Video extension | [Frame Interpolation](diffusion/frame_interpolation.md) |
-| Startup | [Startup and Loading](diffusion/startup_and_loading.md) |
-| Adapters | [LoRA](diffusion/lora.md) |
+- **[TeaCache Configuration Guide](diffusion/cache_acceleration/teacache.md)** - Parameter tuning, performance tips, troubleshooting
+- **[Cache-DiT Advanced Guide](diffusion/cache_acceleration/cache_dit.md)** - DBCache, TaylorSeer, SCM techniques and optimization

-Related cross-model and runtime features are documented separately:
+**Parallelism Methods:**

- [Quantization](quantization/overview.md) covers diffusion-only models,
-  multi-stage omni/TTS models, and multi-stage diffusion models.
- [Execution Modes and Streaming](diffusion/execution_modes.md) covers the
-  diffusion runtime, including batching, step execution, and streaming output.
+- **[Parallelism Overview](diffusion/parallelism/overview.md)** - Tensor Parallelism, Sequence Parallelism, CFG Parallelism, Pipeline Parallelism, HSDP, and Expert Parallelism
+
+**Memory Optimization:**
+
+- **[CPU Offload Guide](diffusion/cpu_offload.md)** - Offload model components to CPU, reduce GPU memory usage
+- **[VAE Parallelism Guide](diffusion/parallelism/vae_parallelism.md)** - Distribute VAE decode work across GPUs for high-resolution images and videos
+- **[Quantization](quantization/overview.md)** - Quantization methods for diffusion, multi-stage omni/TTS, and multi-stage diffusion models
+
+**Extensions:**
+
+- **[LoRA Inference Guide](diffusion/lora.md)** - Low-Rank Adaptation for style customization and fine-tuning
+- **[Frame Interpolation Guide](diffusion/frame_interpolation.md)** - Worker-side post-generation video frame interpolation for smoother motion
+
+**Execution Modes:**
+
+- **[Diffusion Execution Modes](diffusion/execution_modes.md)** - Configure request batching, step execution, continuous batching, and streaming output
+
+**Startup Optimization:**
+
+- **[Multi-Thread Weight Loading](#multi-thread-weight-loading)** - Speed up model startup by loading safetensors shards in parallel
+
+**Advanced Topics:**
+
+- **[Feature Compatibility](feature_compatibility.md)** - How to combine multiple features for maximum performance
@@ -88,9 +88,8 @@ python text_to_image.py \
 | `--vae-use-tiling` | flag | off | Enable VAE tiling for memory optimization |
 | `--cfg-parallel-size` | int | `1` | Set to `2` to enable CFG Parallel |
 | `--enable-cpu-offload` | flag | off | Enable CPU offloading for diffusion models |
-| `--lora-path` | str | — | Path to PEFT LoRA adapter folder or checkpoint file |
+| `--lora-path` | str | — | Path to PEFT LoRA adapter folder |
 | `--lora-scale` | float | `1.0` | Scale factor for LoRA weights |
-| `--lora-backend` | str |`"peft"`| LoRA backend for loading LoRA adapters. Default: peft. Available options: peft, distill |

 **NextStep-1.1 specific arguments:**

@@ -125,9 +125,6 @@ python text_to_video.py \
 - `--audio-sample-rate`: fallback audio sample rate when the pipeline returns audio.
 - `--quantization`: quantization method (`fp8` for FP8, `gguf` for GGUF).
 - `--flow-shift`: scheduler flow_shift parameter.
- `--lora-path`: path to PEFT LoRA adapter folder or checkpoint file.
- `--lora-scale`: scale factor for LoRA weights.
- `--lora-backend`: backend for loading LoRA adapters. Default: peft. Available options: peft, distill.

 ### Wan2.2-specific

@@ -99,7 +99,7 @@ a native vLLM-Omni pipeline for those cases.
 ### Attention Backends

 The diffusers backend converts
-[vLLM-Omni standard of attention backend setting](../../diffusion/attention_backends.md)
+[vLLM-Omni standard of attention backend setting](../../../docs/user_guide/diffusion/attention_backends.md)
 to [diffusers standard](https://huggingface.co/docs/diffusers/optimization/attention_backends#available-backends).

 Specifically for `FLASH_ATTN`, it will first attempt to use FlashAttention-3 and then FlashAttention-2.
@@ -12,20 +12,20 @@ For the internal architecture and backend extension points, see the

 | Mode | Guide | Description | Methods |
 |------|-------|-------------|---------|
-| Online quantization | [Online Quantization](online.md) | vLLM-Omni computes quantized weights and scales while loading the model. | FP8 W8A8, Int8 W8A8, BitsAndBytes W4, MXFP8 W8A8, MXFP4 W4A4 |
+| Online quantization | [Online Quantization](online.md) | vLLM-Omni computes quantized weights and scales while loading the model. | FP8 W8A8, Int8 W8A8, MXFP8 W8A8, MXFP4 W4A4 |
 | Runtime attention quantization | [Quantized KV Cache](quantized_kvcache.md) | vLLM-Omni dynamically quantizes eligible diffusion Flash Attention tensors during inference. | FP8 FA |
-| Pre-quantized checkpoints | Method-specific guides | The checkpoint or an offline quantizer provides quantized weights and scales before serving. | ModelOpt, AutoRound, msModelSlim, serialized Int8, offline MXFP8, offline MXFP4 DualScale |
+| Pre-quantized checkpoints | Method-specific guides | The checkpoint or an offline quantizer provides quantized weights and scales before serving. | ModelOpt, GGUF, AutoRound, msModelSlim, serialized Int8, offline MXFP8, offline MXFP4 DualScale |

 ## Hardware Support

-| Device | FP8 W8A8 | Int8 W8A8 | BitsAndBytes W4 | ModelOpt | MXFP8 W8A8 | MXFP4 W4A4 | AutoRound | msModelSlim |
-|--------|----------|-----------|------------------|----------|------------|------------|-----------|-------------|
-| NVIDIA Blackwell GPU (SM 100+) | ✅ | ✅ | ✅ | ✅ | ⭕ | ⭕ | ✅ | ❌ |
-| NVIDIA Ada/Hopper GPU (SM 89+) | ✅ | ✅ | ✅ | ✅ | ⭕ | ⭕ | ✅ | ❌ |
-| NVIDIA Ampere GPU (SM 80+) | ✅ | ✅ | ✅ | ⭕ | ⭕ | ⭕ | ✅ | ❌ |
-| AMD ROCm | ⭕ | ⭕ | ❌ | ⭕ | ⭕ | ✅ | ⭕ | ❌ |
-| Intel XPU | ⭕ | ⭕ | ❌ | ⭕ | ⭕ | ⭕ | ✅ | ❌ |
-| Ascend NPU | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | ✅ |
+| Device | FP8 W8A8 | Int8 W8A8 | ModelOpt | MXFP8 W8A8 | MXFP4 W4A4 | GGUF | AutoRound | msModelSlim |
+|--------|----------|-----------|----------|------------|------------|------|-----------|-------------|
+| NVIDIA Blackwell GPU (SM 100+) | ✅ | ✅ | ✅ | ⭕ | ⭕ | ✅ | ✅ | ❌ |
+| NVIDIA Ada/Hopper GPU (SM 89+) | ✅ | ✅ | ✅ | ⭕ | ⭕ | ✅ | ✅ | ❌ |
+| NVIDIA Ampere GPU (SM 80+) | ✅ | ✅ | ⭕ | ⭕ | ⭕ | ✅ | ✅ | ❌ |
+| AMD ROCm | ⭕ | ⭕ | ⭕ | ⭕ | ✅ | ⭕ | ⭕ | ❌ |
+| Intel XPU | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ⭕ | ✅ | ❌ |
+| Ascend NPU | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ | ❌ | ✅ |

 Legend: `✅` supported, `❌` unsupported, `⭕` not verified in this
 guide. FP8 on Ampere may use a weight-only path where available.
@@ -43,10 +43,10 @@ otherwise.
 |--------|-------|------|----------------|--------|
 | FP8 W8A8 | [FP8](fp8.md) | Online W8A8 or checkpoint FP8 | Qwen-Image; Wan2.2 is not validated | Validated for Qwen-Image family and other DiT models |
 | Int8 W8A8 | [Int8](int8.md) | Online or serialized W8A8 | Qwen-Image; Wan2.2 is not validated | Validated for Qwen-Image and Z-Image |
-| BitsAndBytes W4 | [BitsAndBytes](bitsandbytes.md) | Online W4 weight-only | Z-Image-Turbo; Qwen-Image/Wan2.2 not validated | Validated for Z-Image-Turbo |
 | ModelOpt | [ModelOpt](modelopt.md) | Pre-quantized FP8 checkpoints | Qwen-Image, Z-Image, FLUX.2, HunyuanImage-3.0 | Validated for ModelOpt FP8 diffusion checkpoints |
 | MXFP8 W8A8 | [MXFP8](mxfp8.md) | Online W8A8 or offline pre-quantized | Wan2.2-T2V-A14B, I2V-A14B, TI2V-5B | Ascend NPU only; validated for Wan2.2 |
 | MXFP4 W4A4 | [MXFP4](mxfp4.md) | `mxfp4`: online single-scale only; `mxfp4_dualscale`: online or offline dual-scale (offline recommended) | Wan2.2-T2V-A14B, I2V-A14B | Ascend NPU only; validated for Wan2.2 A14B cascade models; TI2V-5B not supported; offline `mxfp4_dualscale` uses calibrated `mul_scale` for best accuracy |
+| GGUF | [GGUF](gguf.md) | Pre-quantized transformer weights | Qwen-Image | Validated where a model-specific GGUF adapter exists |
 | AutoRound | [AutoRound](autoround.md) | Pre-quantized W4A16 checkpoints | FLUX.1-dev; Qwen-Image/Wan2.2 not validated | Checkpoint-driven |
 | msModelSlim | [msModelSlim](msmodelslim.md) | Pre-quantized Ascend checkpoints | Wan2.2 recipe; HunyuanImage-3.0 inference target | Ascend/NPU path |

@@ -61,9 +61,9 @@ in BF16 unless the model guide explicitly adds support.
 |--------|-------|-------|----------------|--------|
 | ModelOpt | [ModelOpt](modelopt.md) | Thinker or language-model checkpoint config | Qwen3-Omni thinker | ModelOpt checkpoint path |
 | Int8 | [Int8](int8.md) | Not currently validated for omni/TTS stages | Qwen3-Omni, Qwen3-TTS | Not validated |
-| BitsAndBytes | [BitsAndBytes](bitsandbytes.md) | Not currently validated for omni/TTS stages | Qwen3-Omni, Qwen3-TTS | Not validated |
 | MXFP8 | [MXFP8](mxfp8.md) | Not currently validated for omni/TTS stages | Qwen3-Omni, Qwen3-TTS | Not validated |
 | MXFP4 | [MXFP4](mxfp4.md) | Not currently validated for omni/TTS stages | Qwen3-Omni, Qwen3-TTS | Not validated |
+| GGUF | [GGUF](gguf.md) | Not currently validated for omni/TTS stages | Qwen3-Omni, Qwen3-TTS | Not validated |
 | AutoRound | [AutoRound](autoround.md) | Thinker or language-model checkpoint config | Qwen2.5-Omni, Qwen3-Omni | Supported through AutoRound checkpoints |
 | msModelSlim | [msModelSlim](msmodelslim.md) | Not currently validated for omni/TTS stages | Qwen3-Omni, Qwen3-TTS | Not validated |

@@ -76,10 +76,10 @@ attached to the intended stage rather than applied globally.
 |--------|-------|-------|----------------|--------|
 | FP8 | [FP8](fp8.md) | Stage-specific DiT or transformer module | BAGEL, GLM-Image | Requires model-specific validation |
 | Int8 | [Int8](int8.md) | Stage-specific DiT or transformer module | BAGEL, GLM-Image | Requires model-specific validation |
-| BitsAndBytes | [BitsAndBytes](bitsandbytes.md) | Stage-specific transformer or DiT module | BAGEL, GLM-Image | Not validated |
 | ModelOpt | [ModelOpt](modelopt.md) | Checkpoint-defined diffusion stage | BAGEL, GLM-Image | Requires model-specific validation |
 | MXFP8 | [MXFP8](mxfp8.md) | Stage-specific DiT or transformer module | BAGEL, GLM-Image | Not validated |
 | MXFP4 | [MXFP4](mxfp4.md) | Stage-specific DiT or transformer module | BAGEL, GLM-Image | Not validated |
+| GGUF | [GGUF](gguf.md) | Stage-specific transformer weights | BAGEL, GLM-Image | No validated adapter listed |
 | AutoRound | [AutoRound](autoround.md) | Checkpoint-defined stage | BAGEL, GLM-Image | No validated checkpoint listed |
 | msModelSlim | [msModelSlim](msmodelslim.md) | Ascend-generated stage weights | GLM-Image | Requires model-specific adaptation |

@@ -106,7 +106,7 @@ config = build_quant_config({

 | Component | Default quantized? | Notes |
 |-----------|--------------------|-------|
-| Diffusion transformer | Yes | Primary target for FP8, Int8, BitsAndBytes, ModelOpt, MXFP8, MXFP4, AutoRound, and msModelSlim |
+| Diffusion transformer | Yes | Primary target for FP8, Int8, ModelOpt, MXFP8, MXFP4, GGUF, AutoRound, and msModelSlim |
 | Text encoder | No | Keep BF16 unless a method-specific guide documents support |
 | VAE | No | Keep BF16; storage-only paths are method-specific |
 | Scheduler/tokenizer | No | Loaded from the base model repository |
@@ -139,8 +139,8 @@ from vllm_omni.quantization import build_quant_config

 build_quant_config("fp8")
 build_quant_config({"method": "fp8", "activation_scheme": "static"})
-build_quant_config("bitsandbytes")
 build_quant_config("auto-round", bits=4, group_size=128)
+build_quant_config({"method": "gguf", "gguf_model": "/path/to/model.gguf"})
 build_quant_config({"transformer": {"method": "fp8"}, "vae": None})
 build_quant_config(None)
 ```
@@ -131,7 +131,7 @@ def build_sampling_params() -> list[SamplingParams]:


 def save_stage_output(stage_outputs, output_dir: str) -> None:
-    output = stage_outputs
+    output = stage_outputs.request_output
    request_id = output.request_id
    if stage_outputs.final_output_type == "text":
        text_output = output.outputs[0].text
@@ -104,7 +104,7 @@ def main(args):
    os.makedirs(output_dir, exist_ok=True)

    for stage_outputs in omni_outputs:
-        output = stage_outputs
+        output = stage_outputs.request_output
        if stage_outputs.final_output_type == "text":
            request_id = output.request_id
            text_output = output.outputs[0].text
@@ -228,7 +228,7 @@ async def main():
    if not outputs:
        raise ValueError("No output produced from omni.generate()")

-    first_out = outputs[0]
+    first_out = outputs[0].request_output
    req_out: OmniRequestOutput = first_out

    # Verify trajectory data (from custom pipeline)
@@ -741,7 +741,7 @@ def make_mmu_prompt(

 def iter_mm_outputs(outputs: list[Any]):
    for omni_out in outputs:
-        req_out = omni_out
+        req_out = getattr(omni_out, "request_output", None)
        req_list = req_out if isinstance(req_out, list) else [req_out]
        for item in req_list:
            if item is None:
@@ -303,7 +303,7 @@ def main():
    )
    img_idx = 0
    for req_output in omni_outputs:
-        ro = req_output
+        ro = getattr(req_output, "request_output", None)
        stage_id = getattr(req_output, "stage_id", None)

        # AR stage text — each CompletionOutput.text is already a delta when
@@ -621,7 +621,7 @@ def main():
        images = getattr(output, "images", None)
        if images:
            break
-        req_out = output
+        req_out = getattr(output, "request_output", None)
        images = getattr(req_out, "images", None) if req_out is not None else None
        if images:
            break
@@ -33,25 +33,6 @@ This folder provides a unified CLI script for image-to-video generation using vL

 Default model: `Wan-AI/Wan2.2-I2V-A14B-Diffusers`.

-### LingBot-Video TI2V
-
-LingBot-Video accepts exactly one first-frame image and uses the same dense or
-MoE checkpoint as its T2I and T2V modes:
-
-```bash
-python examples/offline_inference/image_to_video/image_to_video.py \
-  --model robbyant/lingbot-video-dense-1.3b \
-  --model-class-name LingBotVideoPipeline \
-  --image /path/to/input.png \
-  --prompt "the fox looks toward the camera" \
-  --height 192 --width 320 --num-frames 9 --num-inference-steps 2 \
-  --guidance-scale 3.0 --flow-shift 3.0 --fps 24 \
-  --output lingbot_ti2v.mp4
-```
-
-The input image keeps its original geometry until the LingBot pipeline applies
-its model-specific resize and center crop.
-
 ## Prerequisites

 Download the example image used in the snippets below:
@@ -60,12 +60,8 @@ from vllm_omni.diffusion.data import DiffusionParallelConfig
 from vllm_omni.diffusion.utils.param_utils import apply_declared_extra_args
 from vllm_omni.entrypoints.omni import Omni
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
-from vllm_omni.lora.request import LoRARequest
-from vllm_omni.lora.utils import stable_lora_int_id
-from vllm_omni.model_extras import (
-    build_image_to_video_prompt as build_model_image_to_video_prompt,
-)
 from vllm_omni.model_extras import (
+    build_image_to_video_prompt,
    get_extra_body_params,
    get_model_class_name,
 )
@@ -87,22 +83,6 @@ def parse_json_object(value: str, flag_name: str = "argument") -> dict[str, Any]
 parse_profiler_config = functools.partial(parse_json_object, flag_name="--profiler-config")


-def build_image_to_video_prompt(
-    prompt: str,
-    negative_prompt: str | None,
-    media_inputs: dict[str, Any],
-) -> dict[str, Any]:
-    """Build the canonical request envelope for the shared I2V example."""
-    result: dict[str, Any] = {
-        "prompt": prompt,
-        "modalities": ["video"],
-        "multi_modal_data": media_inputs,
-    }
-    if negative_prompt is not None:
-        result["negative_prompt"] = negative_prompt
-    return result
-
-
 def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(
        description=(
@@ -314,30 +294,6 @@ def parse_args() -> argparse.Namespace:
        default=None,
        help='JSON profiler config for torch/cuda profiling, e.g. \'{"profiler":"torch","torch_profiler_dir":"./perf"}\'.',
    )
-    parser.add_argument(
-        "--lora-path",
-        type=str,
-        nargs="+",
-        default=None,
-        help="Path to a LoRA adapter folder (PEFT format) or concrete LoRA checkpoint files. "
-        "For Wan2.2 MoE models, pass the high-noise checkpoint first and the low-noise checkpoint second.",
-    )
-    parser.add_argument(
-        "--lora-scale",
-        type=float,
-        default=1.0,
-        help="Scale factor for PEFT LoRA weights (default: 1.0).",
-    )
-    parser.add_argument(
-        "--lora-backend",
-        type=str,
-        default="peft",
-        choices=["peft", "distill"],
-        help=(
-            "LoRA backend. 'peft' loads a PEFT-format adapter for request-time activation; "
-            "'distill' fuses one or more concrete LoRA checkpoint files at initialization."
-        ),
-    )
    parser.add_argument(
        "--extra-body",
        type=functools.partial(parse_json_object, flag_name="--extra-body"),
@@ -531,12 +487,6 @@ def main():
        omni_kwargs["flow_shift"] = flow_shift
    if args.quantization is not None:
        omni_kwargs["quantization"] = args.quantization
-    if args.lora_path is not None:
-        lora_path = args.lora_path
-        if len(lora_path) == 1:
-            lora_path = lora_path[0]
-        omni_kwargs["lora_path"] = lora_path
-        omni_kwargs["lora_backend"] = args.lora_backend
    # Cosmos3 loads its (gated) guardrail models at build time, so the guardrails
    # gate is an engine-level config (offline analog of the server's --no-guardrails).
    if args.extra_body and "guardrails" in args.extra_body:
@@ -567,39 +517,19 @@ def main():
    print(f"  Video size: {width}x{height}")
    print(f"{'=' * 60}\n")

-    lora_request = None
-    if args.lora_path and args.lora_backend == "peft":
-        if len(args.lora_path) != 1:
-            raise ValueError("Only one LoRA path is expected for PEFT backend.")
-
-        lora_path = args.lora_path[0]
-        lora_request = LoRARequest(
-            lora_name=Path(lora_path).stem,
-            lora_int_id=stable_lora_int_id(lora_path),
-            lora_path=lora_path,
-        )
-
    negative_prompt = args.negative_prompt
    if negative_prompt is None and not is_ltx2:
        # Preserve the historical empty-prompt behavior for non-LTX examples.
        negative_prompt = ""
    prompt_dict = build_image_to_video_prompt(
+        model_class_name=model_class_name,
        prompt=args.prompt,
        negative_prompt=negative_prompt,
        media_inputs=media_inputs,
-    )
-    prompt_dict = build_model_image_to_video_prompt(
-        model_class_name=model_class_name,
-        prompt=prompt_dict,
        height=height,
        width=width,
        num_frames=num_frames,
    )
-    sampling_extra_args = {"sample_solver": args.sample_solver}
-    if lora_request is not None:
-        sampling_extra_args["lora_request"] = lora_request
-        sampling_extra_args["lora_scale"] = args.lora_scale
-
    sampling_params = OmniDiffusionSamplingParams(
        height=height,
        width=width,
@@ -610,7 +540,7 @@ def main():
        num_inference_steps=num_inference_steps,
        num_frames=num_frames,
        frame_rate=frame_rate,
-        extra_args=sampling_extra_args,
+        extra_args={"sample_solver": args.sample_solver},
    )
    if flow_shift is not None:
        sampling_params.extra_args["flow_shift"] = flow_shift
@@ -646,8 +576,8 @@ def main():
        if frames.multimodal_output and "audio" in frames.multimodal_output:
            audio = frames.multimodal_output["audio"]
            audio_sample_rate = frames.multimodal_output.get("audio_sample_rate", audio_sample_rate)
-        if frames.is_pipeline_output and frames is not None:
-            inner_output = frames
+        if frames.is_pipeline_output and frames.request_output is not None:
+            inner_output = frames.request_output
            if isinstance(inner_output, OmniRequestOutput):
                if inner_output.multimodal_output and "audio" in inner_output.multimodal_output:
                    audio = inner_output.multimodal_output["audio"]
@@ -1,319 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-
-import argparse
-import json
-import re
-import subprocess
-import tempfile
-import wave
-from functools import lru_cache
-from pathlib import Path
-from typing import Any
-
-import imageio
-import numpy as np
-import torch
-
-from vllm_omni.diffusion.data import DiffusionParallelConfig
-from vllm_omni.diffusion.models.longcat_video.pipeline_longcat_video_avatar import (
-    prepare_longcat_video_avatar_model_for_omni,
-)
-from vllm_omni.entrypoints.omni import Omni
-from vllm_omni.inputs.data import OmniDiffusionSamplingParams
-from vllm_omni.outputs import OmniRequestOutput
-from vllm_omni.platforms import current_omni_platform
-
-
-def parse_args():
-    parser = argparse.ArgumentParser(description="Generate LongCat-Video-Avatar A2V/AI2V video.")
-    parser.add_argument("--model", default="meituan-longcat/LongCat-Video-Avatar-1.5")
-    parser.add_argument("--base-model-dir", default=None, help="Optional local LongCat-Video base model directory.")
-    parser.add_argument("--stage", choices=["at2v", "ai2v"], default="at2v")
-    parser.add_argument("--prompt", default="A person speaks calmly while facing the camera.")
-    parser.add_argument("--negative-prompt", default="low quality, blurry, watermark, text")
-    parser.add_argument("--audio", default=None, help="Input speech audio path.")
-    parser.add_argument("--image", default=None, help="Input reference image path for AI2V.")
-    parser.add_argument("--input-json", default=None, help="Official LongCat Avatar JSON case for AI2V.")
-    parser.add_argument("--output", default="longcat_avatar_output.mp4")
-    parser.add_argument("--resolution", choices=["480p", "720p"], default="480p")
-    parser.add_argument("--num-frames", type=int, default=93)
-    parser.add_argument("--num-segments", default="1", help="Number of AVC segments, or 'auto' to cover full audio.")
-    parser.add_argument("--num-cond-frames", type=int, default=13)
-    parser.add_argument("--ref-img-index", type=int, default=10)
-    parser.add_argument("--mask-frame-range", type=int, default=3)
-    parser.add_argument("--fps", type=int, default=25)
-    parser.add_argument("--num-inference-steps", type=int, default=8)
-    parser.add_argument("--seed", type=int, default=42)
-    parser.add_argument("--use-distill", action=argparse.BooleanOptionalAction, default=True)
-    parser.add_argument("--use-int8", action=argparse.BooleanOptionalAction, default=True)
-    parser.add_argument(
-        "--build-components-on-gpu",
-        action="store_true",
-        default=False,
-        help="Build large Avatar components directly on GPU for faster startup. Requires more peak VRAM.",
-    )
-    parser.add_argument("--use-kv-cache", action=argparse.BooleanOptionalAction, default=True)
-    parser.add_argument("--offload-kv-cache", action=argparse.BooleanOptionalAction, default=False)
-    parser.add_argument("--enforce-eager", action="store_true")
-    return parser.parse_args()
-
-
-def _extract_frames(output: Any):
-    if isinstance(output, list):
-        output = output[0] if output else None
-    if isinstance(output, OmniRequestOutput):
-        if not output.images:
-            raise ValueError("No video frames found in OmniRequestOutput.")
-        frames = output.images[0] if len(output.images) == 1 else output.images
-        if isinstance(frames, tuple) and len(frames) == 2:
-            frames = frames[0]
-        if isinstance(frames, dict):
-            frames = frames.get("frames") or frames.get("video")
-    else:
-        frames = output
-    if frames is None:
-        raise ValueError("No video frames found in output.")
-    return frames
-
-
-def _frames_to_uint8(frames):
-    frames_np = np.asarray([np.asarray(frame) for frame in frames])
-    if frames_np.ndim == 5:
-        frames_np = frames_np[0]
-    if np.issubdtype(frames_np.dtype, np.floating):
-        frames_np = (np.clip(frames_np, 0.0, 1.0) * 255).round()
-    return np.clip(frames_np, 0, 255).astype(np.uint8)
-
-
-@lru_cache(maxsize=1)
-def _ffmpeg_exe() -> str:
-    try:
-        import imageio_ffmpeg
-
-        return imageio_ffmpeg.get_ffmpeg_exe()
-    except Exception as exc:
-        raise RuntimeError("LongCat Avatar example requires the Python imageio[ffmpeg] dependency.") from exc
-
-
-def _wav_duration(path: Path) -> float:
-    with wave.open(str(path), "rb") as audio:
-        return audio.getnframes() / float(audio.getframerate())
-
-
-def _save_video_with_audio(frames, output_path: Path, audio_path: str, fps: int) -> None:
-    frames_np = _frames_to_uint8(frames)
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    with tempfile.TemporaryDirectory(prefix="longcat_avatar_export_") as tmp:
-        tmp_dir = Path(tmp)
-        temp_video = tmp_dir / "video.mp4"
-        crop_audio = tmp_dir / "audio.wav"
-        crop_video = tmp_dir / "video_cropped.mp4"
-        writer = imageio.get_writer(str(temp_video), fps=fps, quality=5)
-        try:
-            for frame in frames_np:
-                writer.append_data(frame)
-        finally:
-            writer.close()
-
-        duration = len(frames_np) / fps
-        ffmpeg = _ffmpeg_exe()
-        subprocess.run([ffmpeg, "-y", "-i", audio_path, "-t", f"{duration}", str(crop_audio)], check=True)
-        audio_duration = _wav_duration(crop_audio)
-        subprocess.run(
-            [
-                ffmpeg,
-                "-y",
-                "-i",
-                str(temp_video),
-                "-t",
-                f"{audio_duration}",
-                "-c:v",
-                "copy",
-                str(crop_video),
-            ],
-            check=True,
-        )
-        subprocess.run(
-            [
-                ffmpeg,
-                "-y",
-                "-i",
-                str(crop_video),
-                "-i",
-                str(crop_audio),
-                "-c:v",
-                "libx264",
-                "-c:a",
-                "aac",
-                "-shortest",
-                str(output_path),
-            ],
-            check=True,
-        )
-
-
-def _infer_asset_root_from_input_json(input_json: Path) -> Path:
-    resolved = input_json.resolve()
-    parts = resolved.parts
-    if "assets" not in parts:
-        return resolved.parent
-    asset_idx = parts.index("assets")
-    return Path(*parts[:asset_idx])
-
-
-def _resolve_case_path(path: str, asset_root: Path) -> str:
-    raw_path = Path(path)
-    if raw_path.is_absolute():
-        return str(raw_path)
-    candidate = asset_root / raw_path
-    return str(candidate if candidate.exists() else raw_path)
-
-
-def _speaker_sort_key(name: str) -> tuple[int, str]:
-    match = re.search(r"(\d+)$", str(name))
-    return (int(match.group(1)) if match else 10_000, str(name))
-
-
-def _load_input_case(input_json: str) -> tuple[dict[str, Any], Path]:
-    input_json_path = Path(input_json)
-    with input_json_path.open("r", encoding="utf-8") as f:
-        case = json.load(f)
-    return case, _infer_asset_root_from_input_json(input_json_path)
-
-
-def _create_merged_audio_for_case(
-    audio_paths: dict[str, str],
-    audio_type: str,
-    output_path: Path,
-) -> str:
-    sorted_paths = [path for _, path in sorted(audio_paths.items(), key=lambda item: _speaker_sort_key(str(item[0])))]
-    if len(sorted_paths) == 1:
-        return sorted_paths[0]
-    inputs = [arg for path in sorted_paths for arg in ("-i", path)]
-    audio_type = audio_type.lower()
-    if audio_type == "para":
-        filter_complex = f"amix=inputs={len(sorted_paths)}:duration=longest:normalize=0"
-    elif audio_type == "add":
-        filter_complex = "".join(f"[{idx}:a]" for idx in range(len(sorted_paths)))
-        filter_complex += f"concat=n={len(sorted_paths)}:v=0:a=1"
-    else:
-        raise NotImplementedError(f"Unsupported LongCat Avatar audio_type {audio_type!r}.")
-    subprocess.run([_ffmpeg_exe(), "-y", *inputs, "-filter_complex", filter_complex, str(output_path)], check=True)
-    return str(output_path)
-
-
-def main():
-    args = parse_args()
-    input_case = None
-    input_asset_root = None
-    audio_for_mux = args.audio
-    if args.input_json:
-        input_case, input_asset_root = _load_input_case(args.input_json)
-        args.stage = "ai2v"
-        args.prompt = input_case.get("prompt") or args.prompt
-        args.image = _resolve_case_path(input_case["cond_image"], input_asset_root)
-        args.audio = None
-    if not args.input_json and not args.audio:
-        raise ValueError("--audio is required unless --input-json is provided.")
-    if args.stage == "ai2v" and not args.image:
-        raise ValueError("--image is required when --stage=ai2v.")
-    model_for_omni = prepare_longcat_video_avatar_model_for_omni(args.model, args.use_int8)
-
-    additional_config = {
-        "model_type": "avatar-v1.5",
-        "resolution": args.resolution,
-        "use_distill": args.use_distill,
-        "use_int8": args.use_int8,
-        "build_components_on_gpu": args.build_components_on_gpu,
-    }
-    if args.base_model_dir:
-        additional_config["base_model_dir"] = args.base_model_dir
-
-    omni = Omni(
-        model=model_for_omni,
-        model_class_name="LongCatVideoAvatarPipeline",
-        dtype="bfloat16",
-        enforce_eager=args.enforce_eager,
-        additional_config=additional_config,
-        parallel_config=DiffusionParallelConfig(
-            ulysses_degree=1,
-            ring_degree=1,
-            cfg_parallel_size=1,
-            tensor_parallel_size=1,
-            vae_patch_parallel_size=1,
-            pipeline_parallel_size=1,
-        ),
-    )
-
-    audio_input: str | dict[str, str] | None = args.audio
-    additional_information = {"stage": args.stage, "resolution": args.resolution}
-    if input_case is not None and input_asset_root is not None:
-        audio_input = {
-            speaker: _resolve_case_path(path, input_asset_root)
-            for speaker, path in sorted(
-                input_case["cond_audio"].items(),
-                key=lambda item: _speaker_sort_key(str(item[0])),
-            )
-        }
-        additional_information.update(
-            {
-                "input_json": args.input_json,
-                "audio_type": input_case.get("audio_type", "para"),
-                "bbox": input_case.get("bbox", {}),
-            }
-        )
-
-    prompt = {
-        "prompt": args.prompt,
-        "negative_prompt": args.negative_prompt,
-        "multi_modal_data": {"audio": audio_input},
-        "additional_information": additional_information,
-    }
-    if args.stage == "ai2v":
-        prompt["multi_modal_data"]["image"] = args.image
-
-    try:
-        output = omni.generate(
-            prompt,
-            OmniDiffusionSamplingParams(
-                generator=torch.Generator(device=current_omni_platform.device_type).manual_seed(args.seed),
-                seed=args.seed,
-                guidance_scale=1.0 if args.use_distill else 4.0,
-                guidance_scale_2=1.0 if args.use_distill else 4.0,
-                num_inference_steps=args.num_inference_steps,
-                num_frames=args.num_frames,
-                fps=args.fps,
-                extra_args={
-                    "stage": args.stage,
-                    "resolution": args.resolution,
-                    "save_fps": args.fps,
-                    "use_distill": args.use_distill,
-                    "use_int8": args.use_int8,
-                    "input_json": args.input_json,
-                    "num_segments": args.num_segments,
-                    "num_cond_frames": args.num_cond_frames,
-                    "ref_img_index": args.ref_img_index,
-                    "mask_frame_range": args.mask_frame_range,
-                    "use_kv_cache": args.use_kv_cache,
-                    "offload_kv_cache": args.offload_kv_cache,
-                },
-            ),
-            use_tqdm=True,
-        )
-    finally:
-        omni.close()
-
-    with tempfile.TemporaryDirectory(prefix="longcat_avatar_audio_mux_") as tmp:
-        if input_case is not None and isinstance(audio_input, dict):
-            audio_for_mux = _create_merged_audio_for_case(
-                audio_input,
-                input_case.get("audio_type", "para"),
-                Path(tmp) / "merged_audio.wav",
-            )
-        _save_video_with_audio(_extract_frames(output), Path(args.output), audio_for_mux, args.fps)
-    print(f"Saved video to {args.output}")
-
-
-if __name__ == "__main__":
-    main()
Author	SHA1	Message	Date
Hongsheng Liu	c2a3511972	docs: address architecture review feedback Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-09 09:14:46 +08:00
Hongsheng Liu	52b5df9a28	docs: remove architecture source attribution Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 22:22:18 +08:00
Hongsheng Liu	b520064a54	Revert "docs: add user guide information architecture RFC" This reverts commit `4aa71a04a3`. Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 22:08:42 +08:00
Hongsheng Liu	4aa71a04a3	docs: add user guide information architecture RFC Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 21:59:17 +08:00
Hongsheng Liu	d338df2b80	docs: add general architecture overview Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 21:47:01 +08:00
Hongsheng Liu	cb3c84094f	docs: streamline model execution overview Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 21:36:05 +08:00
Hongsheng Liu	a08bcf875e	docs: explain the stage-based architecture Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 17:25:05 +08:00
Hongsheng Liu	f7e1f018cd	docs: split MiniMax H3 execution components Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 17:19:41 +08:00
Hongsheng Liu	606d7f08b6	docs: clarify model execution architectures Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 16:53:23 +08:00
Hongsheng Liu	5ac0008e97	docs: generalize orchestrator responsibilities Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 16:24:42 +08:00
Hongsheng Liu	f62b725610	docs: align main features with design docs Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 16:21:30 +08:00
Hongsheng Liu	e9a833d82d	docs: simplify configuration resolution diagram Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 15:59:41 +08:00
Hongsheng Liu	0104d4599c	docs: update architecture slide links Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 15:42:24 +08:00
Hongsheng Liu	7d0ecd082f	docs: update architecture overview Signed-off-by: Hongsheng Liu <liuhongsheng4@huawei.com>	2026-08-08 13:13:00 +08:00