[Doc] Address README review feedback

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

.buildkite/cuda/test-nightly.yml

@@ -404,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"
@@ -427,12 +427,6 @@ 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 T2VA Accuracy Test"
-        timeout_in_minutes: 180
-        commands:
-          - 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"
         timeout_in_minutes: 180
         commands:
@@ -460,21 +454,6 @@ steps:
             exit $$EXIT2
         mirror_hardwares: h100_2
 
-      - label: ":full_moon: Diffusion X2V · Perf Test · MiniMax-H3"
-        key: nightly-diffusion-x2v-performance-minimax-h3
-        timeout_in_minutes: 180
-        commands:
-          - export DIFFUSION_BENCHMARK_DIR=tests/dfx/perf/results
-          - export DIFFUSION_ATTENTION_BACKEND=FLASH_ATTN
-          - |
-            set +e
-            pytest -s -v tests/dfx/perf/scripts/run_diffusion_benchmark.py --test-config-file tests/dfx/perf/tests/test_minimax_h3_vllm_omni.json
-            EXIT=$$?
-            buildkite-agent artifact upload "tests/dfx/perf/results/diffusion_result_*.json"
-            buildkite-agent artifact upload "tests/dfx/perf/results/logs/*.log"
-            exit $$EXIT
-        mirror_hardwares: h100_4
-
   - group: ":card_index_dividers: Diffusion Test"
     key: nightly-diffusion-test-group
     depends_on: upload-nightly-pipeline
@@ -498,18 +477,12 @@ steps:
           - pytest -sv tests/diffusion/offloader -m "full_model and cuda"
         mirror_hardwares: l4_1
 
-      - label: ":full_moon: Diffusion · Quantization Test with H100 · Single-GPU"
+      - label: ":full_moon: Diffusion · Quantization Test with H100"
         timeout_in_minutes: 60
         commands:
           - pytest -sv tests/diffusion/quantization -m 'full_model and cuda and H100' --run-level "full_model"
         mirror_hardwares: h100_1
 
-      - label: ":full_moon: Diffusion · MiniMax H3 FP8 Quality Test with H100 · 2-GPU"
-        timeout_in_minutes: 60
-        commands:
-          - pytest -sv tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py -m 'full_model and cuda and H100' --run-level "full_model"
-        mirror_hardwares: h100_2
-
       - label: ":full_moon: Diffusion · Quantization Test with L4"
         timeout_in_minutes: 60
         commands:

.buildkite/cuda/test-ready.yml

@@ -47,17 +47,15 @@ steps:
           - timeout 15m pytest -sv tests/diffusion/batching -m 'core_model and cuda' --run-level "core_model"
         mirror_hardwares: l4_1
 
-      - label: "Diffusion · Distributed & Attention Test"
+      - label: "Diffusion · Distributed Test"
         source_file_dependencies:
           - tests/diffusion/distributed/
-          - tests/diffusion/attention/test_attention_sp.py
           - vllm_omni/diffusion/distributed/
-          - vllm_omni/diffusion/attention/
+          - vllm_omni/diffusion/attention/parallel/
           - vllm_omni/diffusion/data.py
           - vllm_omni/diffusion/models/
         commands:
           - timeout 20m pytest -sv tests/diffusion/distributed -m 'core_model and cuda' --run-level "core_model"
-          - timeout 20m pytest -sv tests/diffusion/attention/test_attention_sp.py -m 'core_model and cuda' --run-level "core_model"
         mirror_hardwares: l4_4
 
       - label: "Diffusion · Model Test"

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

@@ -309,7 +309,7 @@ For Omni or custom models, create:
 
 Required updates:
 1. `docs/user_guide/diffusion/parallelism/overview.md` — parallelism support overview/table
-2. `docs/user_guide/diffusion/cpu_offload.md` — if CPU offload supported (add to supported models table)
+2. `docs/user_guide/diffusion/cpu_offload_diffusion.md` — if CPU offload supported (add to supported models table)
 3. `docs/user_guide/diffusion/cache_acceleration/teacache.md` — if TeaCache supported
 4. `docs/user_guide/diffusion/cache_acceleration/cache_dit.md` — if Cache-DiT supported
 5. Offline example docs under `examples/offline_inference/<name>/` (`README.md` or category-specific `.md`)

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

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

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

@@ -1,231 +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. |
-
-### 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.
-
-For each changed value or behavior, trace:
-
-```text
-public ingress -> validation/defaulting -> producer -> transformations
-  -> stage/worker/connector boundary -> final consumer -> terminal cleanup
-```
-
-Cover every applicable offline/online, streaming/non-streaming, sync/async,
-feature-on/off, topology, and compatibility path. Search bounded callers and
-sibling implementations rather than assuming the changed hunk is the only path.
-
-### 5. Apply module and feature contracts
-
-Apply the reference set selected in step 3 and any matching repo-local skill.
-Read the exact module and feature pages in the frozen head, including status,
-ownership boundary, dependencies, candidate invariants, safe-change guide, and
-promotion gate. Candidate or draft rules are questions, not blockers, unless
-current code, tests, or policy enforce them. Inspect both sides of any config,
-registry, serialization, connector, cache, or stage boundary.
-
-When a diff adds or expands a helper, class, fallback, compatibility branch, or
-public behavior, run a subtraction pass: remove out-of-scope behavior and check
-whether each new abstraction can be deleted, merged, moved, or inlined.
-
-### 6. Verify the changed path
-
-Before each validation group, verify the frozen SHA plus the tracked, index,
-untracked, and ignored-file fingerprint, or recreate a pristine snapshot. On a
-trusted head or inside the required sandbox, run an import/version preflight,
-then the narrowest relevant tests and low-cost static checks. Bind every result
-to the head SHA, snapshot fingerprint, and environment fingerprint. Never run
-imports, tests, builds, hooks, or repo-configurable tooling from an untrusted
-head on the reviewer host.
-
-- Treat CI as status evidence; inspect only the first overlapping failure.
-- For docs-only changes, use diff hygiene, links/build checks, and bounded live
-  contract verification instead of dependency setup or pytest.
-- For hardware-dependent paths, run available static/CPU checks and name the
-  exact GPU/NPU gap. Never simulate device evidence.
-- For performance or accuracy claims, require comparable base/head runs with
-  the same environment, workload, warmup, repetitions, and quality criteria.
-
-Stop when each changed semantic path has a supported finding or an explicit
-no-issue conclusion. Do not search further only to increase confidence.
-
-### 7. Consolidate and deliver
-
-Verify each finding against the current diff, deduplicate by root cause, and
-order by severity.
-
-Re-read the remote head and reverify or recreate the pristine validation
-snapshot immediately before delivery. If either changed, mark the review stale
-and restart from the new snapshot.
-
-Return findings first. Use
-[maintainer-style-study.md](references/delivery/maintainer-style-study.md) to keep them
-direct and brief. Each finding must include an exact `path:line`, trigger or
-call path, current behavior, impact, and smallest fix direction. If there are
-no findings, say so briefly and name material validation gaps.
-
-Keep the review read-only unless the user explicitly authorizes posting. Do not
-submit `APPROVE`, `COMMENT`, or `REQUEST_CHANGES`, add labels, edit code, or push
-commits as an implied part of review.
-
-### 8. Optionally request focused owner reviews
-
-Only when the user asks to identify or request reviewers, read
-[review-requests.md](references/delivery/review-requests.md). Rank path-matched
-CODEOWNERS with the frozen module page's owners or required reviewers and
-documented governance expertise; propose one to three focused reviewers with an
-explicit contract rationale.
-
-Identifying or suggesting reviewers is read-only. Requesting reviewers or
-posting `@mention` comments changes external state and requires explicit user
-authorization. When authorized, recheck the head, deduplicate existing
-requests, and post at most one consolidated comment. Do not infer this
-permission from a request to review the code.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

.github/CODEOWNERS

@@ -16,15 +16,15 @@
 /.claude/ @hsliuustc0106
 
 # Tests
-/tests/ @yenuo26 @NickCao
+/tests/ @yenuo26
 
 # CI
-/.buildkite/ @yenuo26 @congw729 @NickCao
+/.buildkite/ @yenuo26 @congw729
 
 # 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/entrypoints/ @tzhouam @yinpeiqi @fake0fan @alex-jw-brooks
 /vllm_omni/model_executor/ @tzhouam @gcanlin
 /vllm_omni/worker/ @tzhouam @gcanlin
 
@@ -37,7 +37,7 @@
 
 # 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
+/vllm_omni/model_executor/models/ @linyueqian @ZeldaHuang @princepride @yuanheng-zhao @amy-why-3459 @Bounty-hunter @Sy0307 @gcanlin
 
 # Benchmarks
 /benchmarks/accuracy/ @david6666666

.pre-commit-config.yaml

@@ -61,13 +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)$
-
     # Keep `suggestion` last
     - id: suggestion
       name: Suggestion

README.md

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

apps/ComfyUI-vLLM-Omni/README.md

@@ -47,7 +47,7 @@ If no, check your shell running the ComfyUI process. There may be some error mes
 This extension offers the following nodes based on the output modalities (at **ComfyUI sidebar -> Node Library**):
 
 - **Generate Image** for text-to-image and image-to-image tasks
-- **Generate Video** for text-to-video, first-frame/image-to-video, and reference-conditioned video
+- **Generate Video** for text-to-video and image-to-video tasks
 - **Multimodality Understanding** for multimodality-to-text and multimodality-to-audio tasks
 - **TTS** and **TTS Voice Clone** for TTS tasks
 
@@ -105,7 +105,7 @@ You can configure per-stage sampling parameters for multi-stage models.
 > [!TIP]
 > The node automatically choose text-to-image or image-to-image API endpoints depending on whether you connect an image input or not.
 
-### Text-to-video and image-to-video generation (e.g., Wan, MiniMax-H3)
+### Text-to-video and image-to-video generation (e.g., Wan)
 
 (Also available at **ComfyUI sidebar->Template->vLLM-Omni->vLLM-Omni Video Generation**)
 
@@ -117,11 +117,7 @@ You can configure per-stage sampling parameters for multi-stage models.
 </p>
 
 > [!TIP]
-> Connect a **frame** image for first-frame / image-to-video (e.g., Wan I2V, MiniMax-H3 FL2VA).
+> The node automatically choose text-to-video or image-to-video API endpoints depending on whether you connect an image input or not.
->
-> For reference-conditioned generation (MiniMax-H3 Ref2VA), connect a **Video References** node instead.
->
-> Do not use `frame` and `references` together. Task routing is automatic from which inputs you connect.
 
 ### TTS (e.g., Qwen TTS series)
 

apps/ComfyUI-vLLM-Omni/__init__.py

@@ -15,13 +15,11 @@ from .comfyui_vllm_omni.nodes import (
     VLLMOmniDiffusionSampling,
     VLLMOmniGenerateImage,
     VLLMOmniGenerateVideo,
-    VLLMOmniMiniMaxH3Params,
     VLLMOmniQwenTTSParams,
     VLLMOmniRemoteLoRA,
     VLLMOmniSamplingParamsList,
     VLLMOmniTTS,
     VLLMOmniUnderstanding,
-    VLLMOmniVideoReferences,
     VLLMOmniVoiceClone,
     VLLMOmniWanParams,
 )
@@ -34,7 +32,6 @@ NODE_CLASS_MAPPINGS = {
     "VLLMOmniUnderstanding": VLLMOmniUnderstanding,
     "VLLMOmniTTS": VLLMOmniTTS,
     "VLLMOmniVoiceClone": VLLMOmniVoiceClone,
-    "VLLMOmniVideoReferences": VLLMOmniVideoReferences,
     # === Params ===
     "VLLMOmniARSampling": VLLMOmniARSampling,
     "VLLMOmniDiffusionSampling": VLLMOmniDiffusionSampling,
@@ -42,7 +39,6 @@ NODE_CLASS_MAPPINGS = {
     "VLLMOmniRemoteLoRA": VLLMOmniRemoteLoRA,
     "VLLMOmniQwenTTSParams": VLLMOmniQwenTTSParams,
     "VLLMOmniWanParams": VLLMOmniWanParams,
-    "VLLMOmniMiniMaxH3Params": VLLMOmniMiniMaxH3Params,
 }
 
 # A dictionary that contains the friendly/humanly readable titles for the nodes
@@ -53,7 +49,6 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "VLLMOmniUnderstanding": "Multimodality Understanding",
     "VLLMOmniTTS": "TTS (Text to Speech)",
     "VLLMOmniVoiceClone": "TTS Voice Cloning",
-    "VLLMOmniVideoReferences": "Video References",
     # === Params ===
     "VLLMOmniARSampling": "AR Sampling Params",
     "VLLMOmniDiffusionSampling": "Diffusion Sampling Params",
@@ -61,7 +56,6 @@ NODE_DISPLAY_NAME_MAPPINGS = {
     "VLLMOmniRemoteLoRA": "LoRA",
     "VLLMOmniQwenTTSParams": "Qwen TTS Params",
     "VLLMOmniWanParams": "Wan Video Params",
-    "VLLMOmniMiniMaxH3Params": "MiniMax-H3 Video Params",
 }
 
 WEB_DIRECTORY = "./web"

apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/nodes.py

@@ -10,9 +10,7 @@ from .utils.types import (
     AudioFormat,
     AutoregressionSamplingParams,
     DiffusionSamplingParams,
-    MiniMaxH3ModelSpecificParams,
     QwenTTSModelSpecificParams,
-    VideoReferences,
     WanModelSpecificParams,
 )
 from .utils.validators import (
@@ -165,8 +163,7 @@ class VLLMOmniGenerateVideo(_VLLMOmniGenerateBase):
                 "num_frames": ("INT", {"default": 41, "min": 1}),
             },
             "optional": {
-                "frame": ("IMAGE",),
+                "image": ("IMAGE",),
-                "references": ("VIDEO_REFERENCES",),
                 "sampling_params": ("SAMPLING_PARAMS",),
                 "lora": ("REMOTE_LORA",),
                 "model_params": ("VIDEO_PARAMS",),
@@ -177,15 +174,6 @@ class VLLMOmniGenerateVideo(_VLLMOmniGenerateBase):
     RETURN_NAMES = ("video",)
     FUNCTION = "generate"
 
-    @classmethod
-    def VALIDATE_INPUTS(cls, url, model, frame=None, references=None, **_kwargs) -> str | Literal[True]:
-        base = super().VALIDATE_INPUTS(url, model)
-        if base is not True:
-            return base
-        if frame is not None and references is not None:
-            return "Provide only one of frame or references, not both."
-        return True
-
     async def generate(
         self,
         url: str,
@@ -196,8 +184,7 @@ class VLLMOmniGenerateVideo(_VLLMOmniGenerateBase):
         fps: int,
         num_frames: int,
         negative_prompt: str | None = None,
-        frame: torch.Tensor | None = None,
+        image: torch.Tensor | None = None,
-        references: dict | None = None,
         sampling_params: dict | list[dict] | None = None,
         model_params: dict | None = None,
         lora: dict | None = None,
@@ -220,16 +207,14 @@ class VLLMOmniGenerateVideo(_VLLMOmniGenerateBase):
 
         if sampling_params is not None:
             sampling_params.pop("type", None)  # internal fields
-        # model_params["type"] is also an internal field, but is used in api_client
+        if model_params is not None:
-        # if model_params is not None:
+            model_params.pop("type", None)  # internal fields
-        #     model_params.pop("type", None)  # internal fields
 
         client = VLLMOmniClient(url)
         output = await client.generate_video(
             model=model,
             prompt=prompt,
-            frame=frame,  # frame present => fl2va / Wan I2V
+            image=image,  # image present => i2v, absent => t2v
-            references=references,
             width=width,
             height=height,
             num_frames=num_frames,
@@ -749,78 +734,3 @@ class VLLMOmniWanParams:
 
     def get_params(self, **kwargs):
         return (WanModelSpecificParams(kwargs),)
-
-
-class VLLMOmniMiniMaxH3Params:
-    @classmethod
-    def INPUT_TYPES(cls):
-        return {
-            "required": {
-                "audio_flow_shift": (
-                    "FLOAT",
-                    {"default": 3.0, "min": 0.0, "max": 100.0, "step": 0.1},
-                ),
-                "flow_shift": (
-                    "FLOAT",
-                    {"default": 12.0, "min": 0.0, "max": 100.0, "step": 0.1},
-                ),
-            }
-        }
-
-    RETURN_TYPES = ("VIDEO_PARAMS",)
-    RETURN_NAMES = ("MiniMax-H3 video params",)
-    FUNCTION = "get_params"
-    CATEGORY = "vLLM-Omni/Video Params"
-
-    def get_params(self, **kwargs):
-        params = MiniMaxH3ModelSpecificParams(kwargs)
-        params["type"] = "minimax_h3"
-        return (params,)
-
-
-class VLLMOmniVideoReferences:
-    @classmethod
-    def INPUT_TYPES(cls):
-        return {
-            "required": {},
-            "optional": {
-                "image_1": ("IMAGE",),
-                "image_2": ("IMAGE",),
-                "audio_1": ("AUDIO",),
-                "audio_2": ("AUDIO",),
-                "video_1": ("VIDEO",),
-                "video_2": ("VIDEO",),
-            },
-        }
-
-    RETURN_TYPES = ("VIDEO_REFERENCES",)
-    RETURN_NAMES = ("references",)
-    FUNCTION = "get_references"
-    CATEGORY = "vLLM-Omni"
-
-    def get_references(
-        self,
-        image_1: torch.Tensor | None = None,
-        image_2: torch.Tensor | None = None,
-        audio_1: AudioInput | None = None,
-        audio_2: AudioInput | None = None,
-        video_1: VideoInput | None = None,
-        video_2: VideoInput | None = None,
-        **kwargs,
-    ):
-        if kwargs:
-            logger.info("Uncaught kwargs: %s", kwargs)
-        refs = VideoReferences()
-        if image_1 is not None:
-            refs["image_1"] = image_1
-        if image_2 is not None:
-            refs["image_2"] = image_2
-        if audio_1 is not None:
-            refs["audio_1"] = audio_1
-        if audio_2 is not None:
-            refs["audio_2"] = audio_2
-        if video_1 is not None:
-            refs["video_1"] = video_1
-        if video_2 is not None:
-            refs["video_2"] = video_2
-        return (refs,)

apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/api_client.py

@@ -24,7 +24,6 @@ from .format import (
     image_tensor_to_base64,
     image_tensor_to_png_bytes,
     video_to_base64,
-    video_to_bytes,
 )
 from .logger import get_logger, pretty_printer
 from .models import lookup_model_spec
@@ -64,11 +63,7 @@ async def url_bytes(session: aiohttp.ClientSession, url: str, verb: str = "get",
 
 class VLLMOmniClient:
     def __init__(
-        self,
+        self, base_url: str, timeout: float | None = None, poll_interval: float = 5.0, max_poll_duration: float = 60 * 5
-        base_url: str,
-        timeout: float | None = None,
-        poll_interval: float = 5.0,
-        max_poll_duration: float = 60 * 30,
     ):
         self.base_url = base_url
         self.timeout = aiohttp.ClientTimeout(total=timeout)
@@ -266,17 +261,12 @@ class VLLMOmniClient:
         num_frames: int,
         fps: int,
         negative_prompt: str | None = None,
-        frame: torch.Tensor | None = None,
+        image: torch.Tensor | None = None,
-        references: dict | None = None,
         sampling_params: dict | None = None,
         model_params: dict | None = None,
         lora: dict | None = None,
-        **extra_params,
+        **extra_body,
     ) -> VideoInput:
-        if frame is not None and references is not None:
-            raise ValueError("Provide only one of frame or references, not both.")
-
-        # === regular payload fields ===
         form = aiohttp.FormData()
         form.add_field("model", model)
         form.add_field("prompt", prompt)
@@ -289,90 +279,22 @@ class VLLMOmniClient:
         if sampling_params is not None:
             for k, v in sampling_params.items():
                 form.add_field(k, str(v))
-        if lora is not None:
-            form.add_field("lora", json.dumps(lora, ensure_ascii=False))
-
-        # === multimodal inputs (first-last-frames, references, etc.) ===
-        input_reference_image: torch.Tensor | None = None
-        audio_reference: AudioInput | None = None
-        reference_videos: list[VideoInput] = []
-        video_task: str | None = None
-
-        if frame is not None:
-            input_reference_image = frame
-            video_task = "fl2va"
-        elif references is not None:
-            images = [references[k] for k in ("image_1", "image_2") if k in references and references[k] is not None]
-            audios = [references[k] for k in ("audio_1", "audio_2") if k in references and references[k] is not None]
-            videos = [references[k] for k in ("video_1", "video_2") if k in references and references[k] is not None]
-
-            if not images and not audios and not videos:
-                raise ValueError("references is empty; connect at least one image/audio/video.")
-
-            if videos:
-                if images or audios:
-                    raise ValueError(
-                        "Video references cannot be combined with image or audio references. "
-                        "Connect only video_1/video_2 for multi-video Ref2VA."
-                    )
-                reference_videos = videos
-                video_task = "ref2va"
-            elif len(images) == 1 and len(audios) == 1:
-                input_reference_image = images[0]
-                audio_reference = audios[0]
-                video_task = "ref2va"
-            else:
-                raise ValueError(
-                    "Invalid references combination. Supported modes: "
-                    "(1) one or more videos only, or (2) exactly one image and one audio."
-                )
-        else:
-            video_task = "t2va"
-
-        if input_reference_image is not None:
-            image_filename = "image.png"  # Required for multipart form
-            form.add_field(
-                "input_reference",
-                image_tensor_to_png_bytes(input_reference_image, image_filename),
-                filename=image_filename,
-                content_type="image/png",
-            )
-
-        if audio_reference is not None:
-            form.add_field(
-                "audio_reference",
-                json.dumps({"audio_url": audio_to_base64(audio_reference)}, ensure_ascii=False),
-            )
-
-        for idx, video in enumerate(reference_videos, start=1):
-            video_filename = f"reference_{idx}.mp4"
-            form.add_field(
-                "input_references",
-                video_to_bytes(video, video_filename),
-                filename=video_filename,
-                content_type="video/mp4",
-            )
-
-        # === model specific params. Either use a specialized builder, or add flattened fields as-is ===
-        if model_params is not None:
-            model_params = dict(model_params)
-            model_params.pop("type", None)
-
-        spec, _ = lookup_model_spec(model)
-        params_builder = spec.get("params_builder") if spec else None
-        if params_builder is not None:
-            form_fields = params_builder(
-                model_params or {},
-                extra_params={**extra_params, "task": video_task},
-            )
-            for k, v in form_fields.items():
-                form.add_field(k, v if isinstance(v, str) else str(v))
-        else:
         if model_params is not None:
             for k, v in model_params.items():
                 form.add_field(k, str(v))
-            if extra_params:
+        if lora is not None:
-                form.add_field("extra_params", json.dumps(extra_params, ensure_ascii=False))
+            form.add_field("lora", json.dumps(lora, ensure_ascii=False))
+        if extra_body:
+            form.add_field("extra_body", json.dumps(extra_body, ensure_ascii=False))
+
+        if image is not None:
+            image_filename = "image.png"  # Required for multipart form
+            form.add_field(
+                "input_reference",
+                image_tensor_to_png_bytes(image, image_filename),
+                filename=image_filename,
+                content_type="image/png",
+            )
 
         async with aiohttp.ClientSession(timeout=self.timeout) as session:
             # Start the video generation job

apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/models.py

@@ -1,12 +1,7 @@
-import json
 import re
-from typing import Any
 
-from .logger import get_logger
 from .types import Modality, ModelMode, Spec
 
-logger = get_logger(__name__)
-
 
 def _bagel_payload_preprocessor(payload: dict) -> dict:
     try:
@@ -34,30 +29,6 @@ def _qwen25_payload_preprocessor(payload: dict) -> dict:
     return payload
 
 
-def _minimaxh3_params_builder(
-    model_params: dict[str, Any],
-    *,
-    extra_params: dict[str, Any],
-) -> dict[str, Any]:
-    """Build multipart form fields for MiniMax-H3 from model_params + routed task."""
-    params = dict(model_params)
-    params.pop("type", None)
-    form_fields: dict[str, Any] = {}
-    merged_extra_params: dict[str, Any] = dict(extra_params or {})
-
-    if "flow_shift" in params:
-        form_fields["flow_shift"] = params.pop("flow_shift")
-    for key in ("audio_flow_shift",):
-        if key in params:
-            merged_extra_params[key] = params.pop(key)
-    if params:
-        logger.warning("Unused MiniMax-H3 model params ignored: %s", sorted(params))
-
-    if merged_extra_params:
-        form_fields["extra_params"] = json.dumps(merged_extra_params, ensure_ascii=False)
-    return form_fields
-
-
 _MODEL_PIPELINE_SPECS: dict[str, Spec] = {
     r"BAGEL-7B-MoT": {
         "stages": [
@@ -100,21 +71,6 @@ _MODEL_PIPELINE_SPECS: dict[str, Spec] = {
             }
         ],
     },
-    r"MiniMax-H3(/FL2VA|/Ref2VA)?": {
-        "stages": ["diffusion"],
-        "modes": [
-            {
-                "mode": ModelMode.VIDEO_GENERATION,
-                "input_modalities": [
-                    Modality.TEXT,
-                    Modality.IMAGE,
-                    Modality.VIDEO,
-                    Modality.AUDIO,
-                ],
-            }
-        ],
-        "params_builder": _minimaxh3_params_builder,
-    },
 }
 # Convert dict keys to regex patterns
 MODEL_PIPELINE_SPECS: dict[re.Pattern, Spec] = {}
@@ -124,10 +80,12 @@ del _MODEL_PIPELINE_SPECS
 
 
 def lookup_model_spec(model: str) -> tuple[Spec | None, str | None]:
-    normalized = model.rstrip("/").lstrip("/")
+    try:
-    lookup_key = normalized.split("/", 1)[-1]
+        last_component = model.rstrip("/").rsplit("/", 1)[-1]
+    except IndexError:
+        last_component = model
     for pattern, spec in MODEL_PIPELINE_SPECS.items():
-        if pattern.search(lookup_key):
+        if pattern.search(last_component):
             return spec, pattern.pattern
     return None, None
 
@@ -143,9 +101,6 @@ if __name__ == "__main__":
         "Qwen/Qwen3-Omni-30B-A3B-Instruct",
         "Custom/Path/UnknownModel-Instruct",
         "Not/Matching/Anything",
-        "/path/to/MiniMax-H3/FL2VA",
-        "/path/to/MiniMax-H3/Ref2VA",
-        "MiniMaxAI/MiniMax-H3",
     ]
 
     test_payload = {"messages": [{"role": "user", "content": "prompt"}]}
@@ -157,13 +112,7 @@ if __name__ == "__main__":
             if preprocessor := spec.get("payload_preprocessor"):
                 result = preprocessor(test_payload)
                 print(f"✓ {path:<40} → {result}")
-            elif params_builder := spec.get("params_builder"):
-                result = params_builder(
-                    {"audio_flow_shift": 3.0, "flow_shift": 12.0, "type": "minimax_h3"},
-                    extra_params={"task": "t2va"},
-                )
-                print(f"✓ {path:<40} → {result}")
             else:
-                print(f"✓ {path:<40} → No preprocessor/params_builder")
+                print(f"✓ {path:<40} → No preprocessor")
         else:
             print(f"✗ {path:<40} → No match")

apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/types.py

@@ -23,14 +23,6 @@ class WanModelSpecificParams(dict):
     pass
 
 
-class MiniMaxH3ModelSpecificParams(dict):
-    pass
-
-
-class VideoReferences(dict):
-    pass
-
-
 class ModelMode(Enum):
     IMAGE_GENERATION = auto()
     VIDEO_GENERATION = auto()
@@ -51,11 +43,9 @@ class ModelModeSpec(TypedDict):
 
 
 PayloadPreprocessor: TypeAlias = Callable[[dict[str, Any]], dict[str, Any]]
-ParamsBuilder: TypeAlias = Callable[..., dict[str, Any]]
 
 
 class Spec(TypedDict):
     stages: list[Literal["diffusion", "autoregression"]]
     modes: list[ModelModeSpec]
     payload_preprocessor: NotRequired[PayloadPreprocessor]
-    params_builder: NotRequired[ParamsBuilder]

apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni Video Generation.json

@@ -1 +1,513 @@
-{"id":"3aea1d08-7de5-4997-ba71-b2f66ad72a21","revision":0,"last_node_id":24,"last_link_id":35,"nodes":[{"id":13,"type":"SaveVideo","pos":[1315.729153459605,-137.92038948394355],"size":[374,313.7692307692308],"flags":{},"order":9,"mode":0,"inputs":[{"localized_name":"video","name":"video","type":"VIDEO","link":32},{"localized_name":"filename_prefix","name":"filename_prefix","type":"STRING","widget":{"name":"filename_prefix"},"link":null},{"localized_name":"format","name":"format","type":"COMBO","widget":{"name":"format"},"link":null},{"localized_name":"codec","name":"codec","type":"COMFY_DYNAMICCOMBO_V3","widget":{"name":"codec"},"link":null}],"outputs":[{"localized_name":"video","name":"video","type":"VIDEO","links":null}],"properties":{},"widgets_values":["video/ComfyUI","auto","auto"]},{"id":10,"type":"MarkdownNote","pos":[183.74636797766794,-571.2529158046766],"size":[240.3326478922474,136.3505820791881],"flags":{},"order":0,"mode":0,"inputs":[],"outputs":[],"title":"Note: Task and Input","properties":{},"widgets_values":["vLLM-Omni nodes are categorized based on the output modality. The \"Generate Video\" node supports both *text-to-video*, *frame-to-video*, and *reference-to-video* generation. The node will create corresponding payload depending on whether an input image is present or not."],"color":"#432","bgcolor":"#000"},{"id":4,"type":"LoadImage","pos":[452.07189605801125,-569.7242536425791],"size":[270,314],"flags":{},"order":1,"mode":0,"inputs":[{"localized_name":"image","name":"image","type":"COMBO","widget":{"name":"image"},"link":null},{"localized_name":"choose file to upload","name":"upload","type":"IMAGEUPLOAD","widget":{"name":"upload"},"link":null}],"outputs":[{"localized_name":"IMAGE","name":"IMAGE","type":"IMAGE","links":[29]},{"localized_name":"MASK","name":"MASK","type":"MASK","links":null}],"properties":{"Node name for S&R":"LoadImage"},"widgets_values":["rap.png","image"]},{"id":23,"type":"LoadImage","pos":[9.206110246057657,-7.6955291509170785],"size":[270,314],"flags":{},"order":2,"mode":0,"inputs":[{"localized_name":"image","name":"image","type":"COMBO","widget":{"name":"image"},"link":null},{"localized_name":"choose file to upload","name":"upload","type":"IMAGEUPLOAD","widget":{"name":"upload"},"link":null}],"outputs":[{"localized_name":"IMAGE","name":"IMAGE","type":"IMAGE","links":[34]},{"localized_name":"MASK","name":"MASK","type":"MASK","links":null}],"properties":{"Node name for S&R":"LoadImage"},"widgets_values":["white-cat.jpg","image"]},{"id":22,"type":"MarkdownNote","pos":[-9.783113411416666,-148.8790300038605],"size":[297.3012007349086,88],"flags":{},"order":3,"mode":0,"inputs":[],"outputs":[],"title":"Note: Reference to video (r2v)","properties":{},"widgets_values":["For r2v tasks, connect this Video Reference block to the main Generate Video block. Then disconnect the \"frame\" input above."],"color":"#432","bgcolor":"#000"},{"id":24,"type":"LoadAudio","pos":[317.9929742385805,-141.44821500065095],"size":[282.798828125,136],"flags":{},"order":4,"mode":0,"inputs":[{"localized_name":"audio","name":"audio","type":"COMBO","widget":{"name":"audio"},"link":null},{"localized_name":"audioUI","name":"audioUI","type":"AUDIO_UI","widget":{"name":"audioUI"},"link":null},{"localized_name":"choose file to upload","name":"upload","type":"AUDIOUPLOAD","widget":{"name":"upload"},"link":null}],"outputs":[{"localized_name":"AUDIO","name":"AUDIO","type":"AUDIO","links":[35]}],"properties":{"Node name for S&R":"LoadAudio"},"widgets_values":["nothing-beats-a-jet2-holiday.mp3",null,""]},{"id":21,"type":"VLLMOmniVideoReferences","pos":[376.6129172897595,105.41557277556292],"size":[156.9380859375,126],"flags":{},"order":7,"mode":0,"inputs":[{"localized_name":"image_1","name":"image_1","shape":7,"type":"IMAGE","link":34},{"localized_name":"image_2","name":"image_2","shape":7,"type":"IMAGE","link":null},{"localized_name":"audio_1","name":"audio_1","shape":7,"type":"AUDIO","link":35},{"localized_name":"audio_2","name":"audio_2","shape":7,"type":"AUDIO","link":null},{"localized_name":"video_1","name":"video_1","shape":7,"type":"VIDEO","link":null},{"localized_name":"video_2","name":"video_2","shape":7,"type":"VIDEO","link":null}],"outputs":[{"localized_name":"references","name":"references","type":"VIDEO_REFERENCES","links":null}],"properties":{"Node name for S&R":"VLLMOmniVideoReferences"},"widgets_values":[]},{"id":8,"type":"VLLMOmniDiffusionSampling","pos":[83.24620208113915,422.08543477542605],"size":[284.205078125,226],"flags":{},"order":5,"mode":0,"inputs":[{"localized_name":"n","name":"n","type":"INT","widget":{"name":"n"},"link":null},{"localized_name":"num_inference_steps","name":"num_inference_steps","type":"INT","widget":{"name":"num_inference_steps"},"link":null},{"localized_name":"guidance_scale","name":"guidance_scale","type":"FLOAT","widget":{"name":"guidance_scale"},"link":null},{"localized_name":"true_cfg_scale","name":"true_cfg_scale","type":"FLOAT","widget":{"name":"true_cfg_scLine truncated
+{
+    "id": "3aea1d08-7de5-4997-ba71-b2f66ad72a21",
+    "revision": 0,
+    "last_node_id": 14,
+    "last_link_id": 28,
+    "nodes": [
+        {
+            "id": 10,
+            "type": "MarkdownNote",
+            "pos": [
+                227.99306819575278,
+                -231.24143306069843
+            ],
+            "size": [
+                240.3326478922474,
+                136.3505820791881
+            ],
+            "flags": {},
+            "order": 0,
+            "mode": 0,
+            "inputs": [],
+            "outputs": [],
+            "title": "Note: Task and Input",
+            "properties": {},
+            "widgets_values": [
+                "vLLM-Omni nodes are categorized based on the output modality. The \"Generate Video\" node supports both text-to-video generation and image-to-video generation. The node will create corresponding payload depending on whether an input image is present or not."
+            ],
+            "color": "#432",
+            "bgcolor": "#000"
+        },
+        {
+            "id": 4,
+            "type": "LoadImage",
+            "pos": [
+                496.31859627609606,
+                -229.71277089860084
+            ],
+            "size": [
+                270,
+                314
+            ],
+            "flags": {},
+            "order": 1,
+            "mode": 0,
+            "inputs": [
+                {
+                    "localized_name": "image",
+                    "name": "image",
+                    "type": "COMBO",
+                    "widget": {
+                        "name": "image"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "choose file to upload",
+                    "name": "upload",
+                    "type": "IMAGEUPLOAD",
+                    "widget": {
+                        "name": "upload"
+                    },
+                    "link": null
+                }
+            ],
+            "outputs": [
+                {
+                    "localized_name": "IMAGE",
+                    "name": "IMAGE",
+                    "type": "IMAGE",
+                    "links": [
+                        25
+                    ]
+                },
+                {
+                    "localized_name": "MASK",
+                    "name": "MASK",
+                    "type": "MASK",
+                    "links": null
+                }
+            ],
+            "properties": {
+                "Node name for S&R": "LoadImage"
+            },
+            "widgets_values": [
+                "cute-cat.jpg",
+                "image"
+            ]
+        },
+        {
+            "id": 8,
+            "type": "VLLMOmniDiffusionSampling",
+            "pos": [
+                465.5140218220927,
+                148.80072646828987
+            ],
+            "size": [
+                284.205078125,
+                226
+            ],
+            "flags": {},
+            "order": 2,
+            "mode": 0,
+            "inputs": [
+                {
+                    "localized_name": "n",
+                    "name": "n",
+                    "type": "INT",
+                    "widget": {
+                        "name": "n"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "num_inference_steps",
+                    "name": "num_inference_steps",
+                    "type": "INT",
+                    "widget": {
+                        "name": "num_inference_steps"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "guidance_scale",
+                    "name": "guidance_scale",
+                    "type": "FLOAT",
+                    "widget": {
+                        "name": "guidance_scale"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "true_cfg_scale",
+                    "name": "true_cfg_scale",
+                    "type": "FLOAT",
+                    "widget": {
+                        "name": "true_cfg_scale"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "vae_use_slicing",
+                    "name": "vae_use_slicing",
+                    "type": "BOOLEAN",
+                    "widget": {
+                        "name": "vae_use_slicing"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "vae_use_tiling",
+                    "name": "vae_use_tiling",
+                    "type": "BOOLEAN",
+                    "widget": {
+                        "name": "vae_use_tiling"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "seed",
+                    "name": "seed",
+                    "type": "INT",
+                    "widget": {
+                        "name": "seed"
+                    },
+                    "link": null
+                }
+            ],
+            "outputs": [
+                {
+                    "localized_name": "diffusion sampling params",
+                    "name": "diffusion sampling params",
+                    "type": "SAMPLING_PARAMS",
+                    "links": [
+                        27
+                    ]
+                }
+            ],
+            "properties": {
+                "Node name for S&R": "VLLMOmniDiffusionSampling"
+            },
+            "widgets_values": [
+                1,
+                50,
+                1,
+                1,
+                false,
+                false,
+                1992,
+                "randomize"
+            ]
+        },
+        {
+            "id": 14,
+            "type": "VLLMOmniWanParams",
+            "pos": [
+                518.6005521845747,
+                428.4455663719664
+            ],
+            "size": [
+                270,
+                106
+            ],
+            "flags": {},
+            "order": 3,
+            "mode": 0,
+            "inputs": [
+                {
+                    "localized_name": "guidance_scale_2",
+                    "name": "guidance_scale_2",
+                    "type": "FLOAT",
+                    "widget": {
+                        "name": "guidance_scale_2"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "boundary_ratio",
+                    "name": "boundary_ratio",
+                    "type": "FLOAT",
+                    "widget": {
+                        "name": "boundary_ratio"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "flow_shift",
+                    "name": "flow_shift",
+                    "type": "FLOAT",
+                    "widget": {
+                        "name": "flow_shift"
+                    },
+                    "link": null
+                }
+            ],
+            "outputs": [
+                {
+                    "localized_name": "Wan video params",
+                    "name": "Wan video params",
+                    "type": "VIDEO_PARAMS",
+                    "links": [
+                        28
+                    ]
+                }
+            ],
+            "properties": {
+                "Node name for S&R": "VLLMOmniWanParams"
+            },
+            "widgets_values": [
+                4,
+                0.875,
+                5
+            ]
+        },
+        {
+            "id": 12,
+            "type": "VLLMOmniGenerateVideo",
+            "pos": [
+                827.2566336087867,
+                -73.77449831827545
+            ],
+            "size": [
+                400,
+                346
+            ],
+            "flags": {},
+            "order": 4,
+            "mode": 0,
+            "inputs": [
+                {
+                    "localized_name": "image",
+                    "name": "image",
+                    "shape": 7,
+                    "type": "IMAGE",
+                    "link": 25
+                },
+                {
+                    "localized_name": "sampling_params",
+                    "name": "sampling_params",
+                    "shape": 7,
+                    "type": "SAMPLING_PARAMS",
+                    "link": 27
+                },
+                {
+                    "localized_name": "lora",
+                    "name": "lora",
+                    "shape": 7,
+                    "type": "REMOTE_LORA",
+                    "link": null
+                },
+                {
+                    "localized_name": "model_params",
+                    "name": "model_params",
+                    "shape": 7,
+                    "type": "VIDEO_PARAMS",
+                    "link": 28
+                },
+                {
+                    "localized_name": "url",
+                    "name": "url",
+                    "type": "STRING",
+                    "widget": {
+                        "name": "url"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "model",
+                    "name": "model",
+                    "type": "STRING",
+                    "widget": {
+                        "name": "model"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "prompt",
+                    "name": "prompt",
+                    "type": "STRING",
+                    "widget": {
+                        "name": "prompt"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "negative_prompt",
+                    "name": "negative_prompt",
+                    "type": "STRING",
+                    "widget": {
+                        "name": "negative_prompt"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "width",
+                    "name": "width",
+                    "type": "INT",
+                    "widget": {
+                        "name": "width"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "height",
+                    "name": "height",
+                    "type": "INT",
+                    "widget": {
+                        "name": "height"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "fps",
+                    "name": "fps",
+                    "type": "INT",
+                    "widget": {
+                        "name": "fps"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "num_frames",
+                    "name": "num_frames",
+                    "type": "INT",
+                    "widget": {
+                        "name": "num_frames"
+                    },
+                    "link": null
+                }
+            ],
+            "outputs": [
+                {
+                    "localized_name": "video",
+                    "name": "video",
+                    "type": "VIDEO",
+                    "links": [
+                        26
+                    ]
+                }
+            ],
+            "properties": {
+                "Node name for S&R": "VLLMOmniGenerateVideo"
+            },
+            "widgets_values": [
+                "http://localhost:8000/v1",
+                "Wan-AI/Wan2.2-TI2V-5B-Diffusers",
+                "Make the cat in the attached video yawning. Eye closed and mouth wide open. Keep the original realistic style.",
+                "Cartoonish",
+                900,
+                1200,
+                12,
+                41
+            ]
+        },
+        {
+            "id": 13,
+            "type": "SaveVideo",
+            "pos": [
+                1257.5441369501657,
+                -44.12956394419863
+            ],
+            "size": [
+                374,
+                372.34896826553796
+            ],
+            "flags": {},
+            "order": 5,
+            "mode": 0,
+            "inputs": [
+                {
+                    "localized_name": "video",
+                    "name": "video",
+                    "type": "VIDEO",
+                    "link": 26
+                },
+                {
+                    "localized_name": "filename_prefix",
+                    "name": "filename_prefix",
+                    "type": "STRING",
+                    "widget": {
+                        "name": "filename_prefix"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "format",
+                    "name": "format",
+                    "type": "COMBO",
+                    "widget": {
+                        "name": "format"
+                    },
+                    "link": null
+                },
+                {
+                    "localized_name": "codec",
+                    "name": "codec",
+                    "type": "COMBO",
+                    "widget": {
+                        "name": "codec"
+                    },
+                    "link": null
+                }
+            ],
+            "outputs": [],
+            "properties": {},
+            "widgets_values": [
+                "video/ComfyUI",
+                "auto",
+                "auto"
+            ]
+        }
+    ],
+    "links": [
+        [
+            25,
+            4,
+            0,
+            12,
+            0,
+            "IMAGE"
+        ],
+        [
+            26,
+            12,
+            0,
+            13,
+            0,
+            "VIDEO"
+        ],
+        [
+            27,
+            8,
+            0,
+            12,
+            1,
+            "SAMPLING_PARAMS"
+        ],
+        [
+            28,
+            14,
+            0,
+            12,
+            3,
+            "VIDEO_PARAMS"
+        ]
+    ],
+    "groups": [
+        {
+            "id": 1,
+            "title": "Input",
+            "bounding": [
+                213.1706010087147,
+                -313.20095750667554,
+                560.8246471437027,
+                407.4246532472182
+            ],
+            "color": "#3f789e",
+            "font_size": 24,
+            "flags": {}
+        }
+    ],
+    "config": {},
+    "extra": {
+        "workflowRendererVersion": "LG",
+        "ds": {
+            "scale": 1.1469075819486894,
+            "offset": [
+                101.7632950847089,
+                492.29121889347806
+            ]
+        }
+    },
+    "version": 0.4
+}

benchmarks/diffusion/backends.py

@@ -1,6 +1,5 @@
 import asyncio
 import base64
-import json
 import mimetypes
 import os
 import time
@@ -14,17 +13,6 @@ from tqdm import tqdm
 DEFAULT_EDITS_BOT_TASK = "think"
 
 
-def _is_minimax_h3_mixed_reference(model: str) -> bool:
-    """MiniMax-H3 Ref2VA consumes reference videos as file paths.
-
-    Its reference preparer ffprobes / ffmpegs the reference file, so single
-    ``video_reference`` uploads are sent as a base64 data URL: the server
-    persists them to disk and keeps ``source_path``, handing the pipeline a
-    real file path instead of a decoded frame list.
-    """
-    return "MiniMax-H3" in (model or "")
-
-
 @dataclass
 class RequestFuncInput:
     prompt: str
@@ -367,14 +355,6 @@ async def async_request_v1_videos(
         )
     elif input.video_paths and len(input.video_paths) > 0:
         video_path = input.video_paths[0]
-        if _is_minimax_h3_mixed_reference(input.model):
-            with open(video_path, "rb") as reference_file:
-                video_b64 = base64.b64encode(reference_file.read()).decode("ascii")
-            form.add_field(
-                "video_reference",
-                json.dumps([{"video_url": f"data:video/mp4;base64,{video_b64}"}]),
-            )
-        else:
         image_file = open(video_path, "rb")
         form.add_field(
             "input_reference",

benchmarks/diffusion/diffusion_benchmark_serving.py

@@ -858,12 +858,7 @@ class RandomDataset(BaseDataset):
             height = int(self.args.height or profile.get("height") or 720)
             num_frames = int(self.args.num_frames or profile.get("num_frames") or 16)
             fps = float(self.args.fps or profile.get("fps") or 8)
-            # cv2 typically writes MPEG-4 Part 2 (``mp4v``), which pipelines such
+            writer = cv2.VideoWriter(video_path, cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height))
-            # as MiniMax-H3 Ref2VA reject because they require H.264/H.265
-            # reference videos. Write the synthetic clip first, then re-encode
-            # it to H.264 when ffmpeg is available; otherwise keep ``mp4v``.
-            raw_path = video_path + ".raw.mp4"
-            writer = cv2.VideoWriter(raw_path, cv2.VideoWriter_fourcc(*"mp4v"), fps, (width, height))
             if not writer.isOpened():
                 raise RuntimeError("cv2.VideoWriter failed to open")
             for frame_idx in range(num_frames):
@@ -876,10 +871,6 @@ class RandomDataset(BaseDataset):
                 frame[max(y - 36, 0) : min(y + 36, height), x : min(x + 96, width), :] = (64, 128, 220)
                 writer.write(frame)
             writer.release()
-            if _reencode_video_to_h264(raw_path, video_path):
-                os.unlink(raw_path)
-            else:
-                os.replace(raw_path, video_path)
             return [video_path]
         except Exception as e:
             raise RuntimeError(
@@ -887,40 +878,6 @@ class RandomDataset(BaseDataset):
             ) from e
 
 
-def _reencode_video_to_h264(source: str, destination: str) -> bool:
-    """Re-encode a video to H.264/MP4 using ffmpeg when available.
-
-    Returns False when ffmpeg is missing or the re-encode fails so callers can
-    fall back to the original container/codec.
-    """
-    import shutil
-    import subprocess
-
-    if shutil.which("ffmpeg") is None:
-        return False
-    try:
-        result = subprocess.run(
-            [
-                "ffmpeg",
-                "-y",
-                "-loglevel",
-                "error",
-                "-i",
-                source,
-                "-c:v",
-                "libx264",
-                "-pix_fmt",
-                "yuv420p",
-                destination,
-            ],
-            capture_output=True,
-            text=True,
-        )
-        return result.returncode == 0 and os.path.exists(destination)
-    except Exception:
-        return False
-
-
 def _compute_expected_latency_ms_from_base(req: RequestFuncInput, args, base_time_ms: float | None) -> float | None:
     """Compute expected execution time (ms) based on a base per-step-per-frame unit time.
 

docs/.nav.yml

@@ -16,21 +16,31 @@ nav:
   - Examples:
     - examples/README.md
     - Offline Inference:
+      - GLM-Image Multistage End-to-End Inference: user_guide/examples/offline_inference/glm_image.md
+      - HunyuanImage-3.0 Image-to-Text Inference: user_guide/examples/offline_inference/hunyuan_image3.md
       - Image-To-Image: user_guide/examples/offline_inference/image_to_image.md
       - Image-To-Video: user_guide/examples/offline_inference/image_to_video.md
-      - Speech-To-Video: user_guide/examples/offline_inference/speech_to_video.md
+      - InternVLA-A1: user_guide/examples/offline_inference/internvla_a1.md
+      - MiMo-Audio: user_guide/examples/offline_inference/mimo_audio.md
+      - Qwen2.5-Omni: user_guide/examples/offline_inference/qwen2_5_omni.md
+      - Qwen3-Omni: user_guide/examples/offline_inference/qwen3_omni.md
       - Text-To-Audio: user_guide/examples/offline_inference/text_to_audio.md
       - Text-To-Image: user_guide/examples/offline_inference/text_to_image.md
       - Text-To-Speech: user_guide/examples/offline_inference/text_to_speech.md
       - Text-To-Video: user_guide/examples/offline_inference/text_to_video.md
-      - X-To-Text: user_guide/examples/offline_inference/x_to_text.md
       - X-To-Video-Audio: user_guide/examples/offline_inference/x_to_video_audio.md
     - Online Serving:
+      - BAGEL-7B-MoT: user_guide/examples/online_serving/bagel.md
+      - vLLM-Omni Helm Chart: user_guide/examples/online_serving/chart-helm.md
+      - Diffusers Backend Adapter: user_guide/examples/online_serving/diffusers_pipeline_adapter.md
+      - GLM-Image Online Serving: user_guide/examples/online_serving/glm_image.md
       - Image-To-Image: user_guide/examples/online_serving/image_to_image.md
       - Image-To-Video: user_guide/examples/online_serving/image_to_video.md
-      - Speech-To-Video: user_guide/examples/online_serving/speech_to_video.md
+      - MiMo-Audio: user_guide/examples/online_serving/mimo_audio.md
-      - Text-To-Image: user_guide/examples/online_serving/text_to_image.md
+      - Qwen2.5-Omni: user_guide/examples/online_serving/qwen2_5_omni.md
+      - Qwen3-Omni: user_guide/examples/online_serving/qwen3_omni.md
       - Text-To-Speech: user_guide/examples/online_serving/text_to_speech.md
+      - Text-To-Image: user_guide/examples/online_serving/text_to_image.md
       - Text-To-Video: user_guide/examples/online_serving/text_to_video.md
   - General:
     - usage/*
@@ -58,12 +68,13 @@ 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
-      - CPU Offloading: user_guide/diffusion/cpu_offload.md
+      - CPU Offloading: user_guide/diffusion/cpu_offload_diffusion.md
       - LoRA: user_guide/diffusion/lora.md
       - Custom Pipeline: features/custom_pipeline.md
-      - Execution Modes: user_guide/diffusion/execution_modes.md
+      - Request-Level Batching: user_guide/diffusion/request_batching.md
+      - Step Execution: user_guide/diffusion/step_execution.md
     - Quantization:
-      - Quantization: user_guide/quantization/overview.md
+      - 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
@@ -91,65 +102,31 @@ nav:
   - CI: contributing/ci
   - Design Documents:
     - design/index.md
-    - Architecture Documents:
+    - design/architecture_overview.md
-      - Architecture Overview: design/architecture_overview.md
     - Feature Design:
-      - Runtime and Stage Execution:
+      - design/feature/disaggregated_inference.md
-        - Disaggregated Inference: design/feature/disaggregated_inference.md
+      - design/feature/ray_based_execution.md
-        - Async Chunk: design/feature/async_chunk.md
+      - design/feature/omni_connectors/
-        - Async Diffusion Output: design/feature/async_diffusion_output.md
+      - design/feature/prefix_caching.md
-        - Async Omni Output Materialization: design/feature/omni_async_output_materialization.md
+      - design/feature/cfg_parallel.md
-        - Automatic Prefix Caching: design/feature/prefix_caching.md
+      - design/feature/expert_parallel.md
-      - Communication:
+      - design/feature/sequence_parallel.md
-        - OmniConnector Implementations:
+      - design/feature/tensor_parallel.md
-          - Mooncake Store Connector: design/feature/omni_connectors/mooncake_store_connector.md
+      - design/feature/vae_parallel.md
-          - Mooncake Transfer Engine Connector: design/feature/omni_connectors/mooncake_transfer_engine_connector.md
+      - design/feature/hsdp.md
-          - Mori Transfer Engine Connector: design/feature/omni_connectors/mori_transfer_engine_connector.md
+      - design/feature/cache_dit.md
-          - Shared Memory Connector: design/feature/omni_connectors/shared_memory_connector.md
+      - design/feature/teacache.md
-          - Yuanrong Store Connector: design/feature/omni_connectors/yuanrong_connector.md
+      - design/feature/skip_softmax.md
-          - Yuanrong Transfer Engine Connector: design/feature/omni_connectors/yuanrong_transfer_engine_connector.md
+      - design/feature/async_chunk.md
-      - Diffusion Acceleration:
+      - design/feature/vae_parallel.md
-        - Parallelism:
+      - design/feature/diffusion_step_execution.md
-          - CFG-Parallel: design/feature/cfg_parallel.md
+      - design/feature/diffusion_request_level_batching.md
-          - Expert Parallel: design/feature/expert_parallel.md
+      - design/feature/diffusion_continuous_batching.md
-          - Hybrid Sharded Data Parallel (HSDP): design/feature/hsdp.md
-          - Pipeline Parallel: design/feature/pipeline_parallel.md
-          - Sequence Parallel: design/feature/sequence_parallel.md
-          - Tensor Parallel: design/feature/tensor_parallel.md
-          - VAE Patch Parallelism: design/feature/vae_parallel.md
-        - 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
-        - Distributed Layerwise Offload: design/feature/distributed_layerwise_offload.md
-    - Infrastructure and Performance:
-      - Prometheus Metrics: design/metrics.md
-      - Speech Generation Performance Optimizations: design/qwen3_omni_tts_performance_optimization.md
     - Module Design:
-      - Entrypoints: design/module/entrypoints.md
+      - design/module/ar_module.md
-      - vLLM-Omni Configuration: design/module/vllm_omni_config.md
+      - design/module/dit_module.md
-      - Input, Output, and Modality Contracts: design/module/input_output_modality_contracts.md
+      - design/module/entrypoint_module.md
-      - Error Contracts: design/module/error_contracts.md
+      - design/module/async_omni_architecture.md
-      - Engine Orchestration: design/module/engine_orchestration.md
-      - Stage Runtime: design/module/stage_runtime.md
-      - OmniConnector: design/module/omni_connector.md
-      - Model Integration: design/module/model_integration.md
-      - Autoregressive Runtime: design/module/ar_runtime.md
-      - Diffusion:
-        - Overview: design/module/diffusion/index.md
-        - Runtime: design/module/diffusion/diffusion_runtime.md
-        - Model Integration: design/module/diffusion/diffusion_model_integration.md
-        - Continuous Batching: design/module/diffusion/continuous_batching.md
-        - Parallelism: design/module/diffusion/parallelism.md
-        - Offloader: design/module/diffusion/offloader.md
-      - Execution Platforms: design/module/execution_platforms.md
-      - Cache Management: design/module/cache_management.md
-      - Quantization: design/module/quantization.md
-      - Observability: design/module/observability.md
-      - Profiling: design/module/profiling.md
-      - Benchmarking: design/module/benchmarking.md
   - Docs Guide: contributing/DOCS_GUIDE.md
 - API Reference:
   - api/README.md

docs/README.md

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

docs/community/governance.md

@@ -40,7 +40,6 @@ Committers have write access and merge rights. They typically have deep expertis
 - [@Isotr0py](https://github.com/Isotr0py): Diffusion and Quantization
 - [@linyueqian](https://github.com/linyueqian): TTS and Omni Support
 - [@lishunyang12](https://github.com/lishunyang12): Quantization and Configuration
-- [@NickCao](https://github.com/NickCao): CI, Tests, Entrypoint, and TTS Model Support
 - [@princepride](https://github.com/princepride): Diffusion and Omni Support
 - [@RuixiangMa](https://github.com/RuixiangMa): Diffusion models, parallel, cache, and docs
 - [@SamitHuang](https://github.com/SamitHuang): RL, Diffusion, and cache

docs/configuration/stage_configs.md

@@ -387,8 +387,8 @@ that support request-level batching with `step_execution` disabled.
 
 Use this together with `max_num_seqs > 1` for bursty serving traffic. `0`
 disables admission waiting and preserves the lowest first-request latency.
-For diffusion execution and batching tuning, see
+For diffusion request-level batching tuning, see
-[Diffusion Execution Modes](../user_guide/diffusion/execution_modes.md).
+[Request-Level Batching](../user_guide/diffusion/request_batching.md).
 
 Default: `0.0`
 

docs/contributing/ci/test_examples/l4_functionality_tests.inc.md

@@ -1,6 +1,6 @@
 **Scope**
 
-For diffusion models, the L4 functionality test covers all or common *diffusion features* that are supported by this model, including several [parallelism acceleration methods](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/parallelism_acceleration/), [CPU offloading](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/cpu_offload/), [TeaCache](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/teacache/) and [Cache-DiT](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/cache_dit_acceleration/) cache backends, [quantization methods](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/quantization/overview/).
+For diffusion models, the L4 functionality test covers all or common *diffusion features* that are supported by this model, including several [parallelism acceleration methods](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/parallelism_acceleration/), [CPU offloading](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/cpu_offload_diffusion/), [TeaCache](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/teacache/) and [Cache-DiT](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/diffusion/cache_dit_acceleration/) cache backends, [quantization methods](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/quantization/overview/).
 
 **Test Case Design**
 

docs/contributing/ci/test_examples/l4_performance_tests.inc.md

@@ -44,13 +44,11 @@ Pass **`--test-config-file`** to run one JSON file as-is, or omit it for the bul
             "ignore_eos": true,
             "percentile-metrics": "ttft,tpot,itl,e2el,audio_rtf,audio_ttfp,audio_duration",
             "baseline": {
-                "H100": {
                 "mean_ttft_ms": [500, 800],
                 "mean_audio_ttfp_ms": [2000, 3500],
                 "mean_audio_rtf": [0.25, 0.35]
             }
         }
-        }
     ]
 }
 ```
@@ -144,6 +142,10 @@ pytest -s -v tests/dfx/perf/scripts/run_diffusion_benchmark.py \
   --test-config-file tests/dfx/perf/tests/test_bagel_vllm_omni.json
 pytest -s -v tests/dfx/perf/scripts/run_benchmark.py \
   --test-config-file tests/dfx/perf/tests/test_qwen3_omni_async_chunk.json
+
+# Optional baseline assertion (default off)
+pytest -sv tests/dfx/perf/scripts/run_diffusion_benchmark.py --assert-baseline \
+  --test-config-file tests/dfx/perf/tests/test_qwen_image_vllm_omni.json
 ```
 
 See also [Markers for Tests](#markers-for-tests) for registered hardware markers (`H100`, `L4`, `cuda`, `distributed_cuda`, …).
@@ -200,4 +202,4 @@ You can add any benchmark running parameters you need here. For all optional par
 | num_prompts     | int / array | Yes      | 10,[10, 20, 30] | Number of requests. Supports single values or arrays. If a single value is used, it will be automatically expanded to match the number of qps or max_concurrency, e.g., [10,10,10]. If an array is used, its length must match the number of qps or max_concurrency. |
 | request_rate    | float / array | No  | 0.5, [0.5, 1, inf] | Queries per second. Supports single values or arrays. If a single value is used, it will be automatically expanded to match the number of num_prompts, e.g., [1,1,1]. If an array is used, its length must match the number of num_prompts.                          |
 | max_concurrency | int / array | No       | 1, [1, 2, 3]    | Maximum concurrent in-flight requests. Same array / expansion rules as `request_rate` (mutually exclusive with QPS mode).                                                                                                                                                                                                             |
-| baseline        | object      | No       | see below       | Optional thresholds. **Hardware-nested only**: top-level keys must be `[hardware-resource]` pytest markers from `pyproject.toml` (`get_hardware_mark_list()`). Under each hardware key, metric names are free-form; values are scalars or sweep-aligned lists. Example: `{"H100": {"throughput_qps": […], "custom_stage_ms": 1.0}, "A3": {…}}`. Runtime filename aliases (`_RUNTIME_DEVICE_ALIASES`) are separate and do not expand this allowlist. |
+| baseline        | object      | No       | see above       | Optional per-metric thresholds; keys must match benchmark output fields. Scalar, list (per sweep step), or object (keyed by concurrency or QPS string).  

docs/contributing/model/adding_diffusion_model.md

@@ -755,8 +755,7 @@ omni = Omni(model="your-model", ulysses_degree=2, ring_degree=2)
 
 ### Step Execution
 
-See the detailed
+See detailed design guide: [How to add step execution support](../../design/feature/diffusion_step_execution.md)
-[Diffusion Continuous Batching design guide](../../design/feature/diffusion_continuous_batching.md).
 
 Use this only when your pipeline can be split into stable request-scoped and
 step-scoped phases. The reference implementation is
@@ -770,8 +769,9 @@ step-scoped phases. The reference implementation is
 Do not enable `step_execution=True` until those four methods are implemented
 and validated against the request-level path.
 
-The same design guide covers the experimental batched step-wise path used when
+If you want the pipeline to work with the experimental batched step-wise path
-`max_num_seqs > 1`.
+(`max_num_seqs > 1`), also see:
+[Continuous Batching for Step-Wise Diffusion](../../design/feature/diffusion_continuous_batching.md).
 
 If you expose this in example scripts or recipes, keep it opt-in. Surface
 runtime features like `step_execution` as optional flags instead of silently
@@ -824,7 +824,7 @@ omni = Omni(model="your-model",
 
 ### CPU Offload
 
-See detailed guide: [CPU Offloading for Diffusion Models](../../user_guide/diffusion/cpu_offload.md)
+See detailed guide: [CPU Offloading for Diffusion Models](../../user_guide/diffusion/cpu_offload_diffusion.md)
 
 vLLM-Omni provides two offloading strategies to reduce GPU memory usage:
 

docs/contributing/model/adding_tts_model.md

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

docs/design/architecture_overview.md

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

docs/design/feature/diffusion_continuous_batching.md

@@ -1,232 +1,165 @@
-# Diffusion Continuous Batching
+# Continuous Batching for Step-Wise Diffusion
 
-This document describes the unified diffusion execution architecture, including
+!!! warning "Experimental Feature"
-request execution, request-level batching, step execution, continuous batching,
+    This feature is experimental. It currently applies only to native
-and output delivery. For user-facing configuration and CLI examples, see
+    diffusion pipelines running with `step_execution=True`.
-[Diffusion Execution Modes](../../user_guide/diffusion/execution_modes.md).
+
+This document describes the batching extension built on top of
+[Diffusion Step Execution](diffusion_step_execution.md). The base
+step-execution contract is unchanged. The batching work is mainly in the
+scheduler and runner layers.
+
+## Why It Helps
+
+Step-wise execution breaks a long denoise loop into scheduler-visible units.
+That gives the runtime a place to admit other compatible requests between
+steps instead of waiting for an entire request to finish.
+
+This matters most in low-MFU or bursty serving scenarios:
+
+- one request's denoise step may not fully saturate the GPU
+- several compatible requests can share the same denoise forward pass
+- throughput and device utilization can improve without changing request-local
+  scheduler state
+
+This is **not** a guaranteed single-request latency win. The main benefit is
+usually higher utilization and better throughput when the workload contains
+multiple in-flight compatible requests.
 
 ## Overview
 
-`DiffusionEngine` selects an execution mode from `step_execution` and uses
+With continuous batching enabled:
-`max_num_seqs` as that mode's scheduler capacity:
 
-| Configuration | Engine mode | Scheduler | Execution |
+- the scheduler may keep multiple compatible requests active at the same time
-|---|---|---|---|
+- the runner packs request-local step state into one `InputBatch`
-| `step_execution=False`, `max_num_seqs=1` | `REQUEST_BATCH` | `RequestScheduler` | One complete request-level `forward()` |
+- `denoise_step()` runs on that batch
-| `step_execution=False`, `max_num_seqs>1` | `REQUEST_BATCH` | `RequestScheduler` | One fused `forward()` over compatible requests |
+- `step_scheduler()` and `post_decode()` still run per request
-| `step_execution=True`, `max_num_seqs=1` | `STEP_BATCH` | `StepScheduler` | One request advanced one denoise step per scheduler tick |
-| `step_execution=True`, `max_num_seqs>1` | `STEP_BATCH` | `StepScheduler` | Compatible requests advanced together in step waves |
 
-Serial request execution is handled inside `REQUEST_BATCH`; it is not a
+The current implementation is conservative:
-separate engine mode. Similarly, continuous batching is the multi-request
-configuration of `STEP_BATCH`, not an independent execution mode.
 
-The engine performs the following initialization:
+- only compatible requests are batched together
+- per-request progress and completion remain independent
 
-1. Resolve model-specific pre- and post-processing hooks.
+Here, "continuous batching" means the step-wise path enabled by
-2. Select `REQUEST_BATCH` or `STEP_BATCH`.
+`step_execution=True`. Request-mode `DiffusionRequestBatch` is static
-3. Construct the configured `DiffusionExecutor`.
+request-level batching for one full pipeline `forward()` call; it does not
-4. Construct `RequestScheduler` or `StepScheduler`, unless a scheduler was
+admit or remove requests between denoise steps.
-   explicitly injected.
-5. Bind `execute_batch` or `execute_step`.
 
-`DiffusionEngine.make_engine()` owns startup warmup after engine construction.
+## Enablement
-This keeps construction, backend selection, and warmup failure cleanup in one
-lifecycle.
 
-## Unified Output Stream
+Use `--step-execution` as the feature gate, then increase `--max-num-seqs`
+above `1` if you want batching:
 
-All asynchronous diffusion requests use the same per-request output stream,
+```bash
-regardless of whether the caller exposes streaming results to the user.
+vllm serve Qwen/Qwen-Image --omni \
-
+  --port 8091 \
-```python
+  --step-execution \
-async for output in engine.step_streaming(request):
+  --max-num-seqs 8
-    ...
 ```
 
-When a request is admitted, the engine creates an
+`--max-num-seqs 1` keeps the step-wise path without enabling batching.
-`asyncio.Queue[DiffusionOutput]` keyed by its request ID. The busy loop sends
-both intermediate chunks and final results through that queue:
 
-```text
+For a reproducible replay flow using the bundled serving benchmark, see the
-request
+Qwen-Image replay commands in
-  -> scheduler.add_request()
+[`benchmarks/diffusion/README.md`](gh-file:benchmarks/diffusion/README.md)
-  -> scheduler.schedule()
+and
-  -> execute_batch() or execute_step()
+[`benchmarks/diffusion/performance_dashboard/qwen_image_serving_performance.md`](gh-file:benchmarks/diffusion/performance_dashboard/qwen_image_serving_performance.md).
-  -> scheduler.update_from_output()
-  -> per-request output queue
-  -> step_streaming()
-```
 
-Streaming callers forward every yielded output. Non-streaming callers consume
+## Scheduler
-the same generator to completion and return only its final output. This avoids
-maintaining separate future-based and queue-based result paths.
 
-`DiffusionEngine.step()` and
+The scheduler derives its batch capacity from `max_num_seqs` through
-`async_add_req_and_wait_for_response()` remain deprecated compatibility
+`max_num_running_reqs`.
-wrappers. New integrations should consume `step_streaming()` or
-`async_add_req_and_stream_response()`.
 
-### Completion and Cancellation
+Batch admission is gated by
+[`StepBatchSamplingParamsKey`](gh-file:vllm_omni/diffusion/sched/interface.py),
+which is built from shape-sensitive and CFG-sensitive sampling fields. This is
+the core correctness rule for batching: requests are only co-batched when they
+share the same denoise tensor contract.
 
-Output delivery and scheduler lifecycle are related but separate:
+There are three important details:
 
-- A terminal scheduler result always finalizes request state.
+- `num_inference_steps` is not part of the key, so requests with different
-- A disconnected or cancelled consumer removes only its delivery queue.
+  total step counts can still share a batch
-- The scheduler may still finish and clean up the request after its queue has
+- requests also do not need to be at the same current denoise progress; active
-  been removed.
+  requests can continue batching even when their current step indices diverge
-- Engine shutdown sends an error output to all remaining streams.
+- admission is still FIFO, so an incompatible request at the head of the
+  waiting queue blocks later compatible requests
 
-This separation prevents cancelled consumers from leaving active request IDs in
+Today that compatibility rule is still shape-sensitive. `height`, `width`,
-the scheduler.
+`num_frames`, and CFG-related fields remain part of the key, so different
+resolutions or incompatible guidance settings do **not** co-batch yet. The
+key also covers LoRA identity (`lora_int_id`, `lora_scale`), so requests
+targeting different adapters or scales run in separate batches and the
+worker can activate exactly one adapter per step.
 
-## Request-Batch Execution
+The scheduler batching unit is one logical `OmniDiffusionRequest`. In the
+step-wise path, runtime tensor batching is represented as `StepInputBatch`. For
+request-mode prompt semantics, see
+[Request-Level Batching](../../user_guide/diffusion/request_batching.md).
 
-Request-batch execution runs the complete diffusion pipeline for each scheduler
+## Runner
-wave. Each `OmniDiffusionRequest` remains an independent logical request with
-its own prompt, sampling parameters, seed, request ID, output, error, and abort
-state.
 
-With `max_num_seqs=1`, `execute_batch()` handles the serial request path. With a
+The runner keeps persistent per-request execution state in
-larger value, a pipeline can opt into fused execution by declaring:
+[`StepRequestState`](gh-file:vllm_omni/diffusion/worker/utils.py),
+while the scheduler owns a separate lightweight
+[`SchedulerRequestState`](gh-file:vllm_omni/diffusion/sched/interface.py)
+for queueing and lifecycle tracking.
 
-```python
+For each step, the runner builds an
-supports_request_batch = True
+[`InputBatch`](gh-file:vllm_omni/diffusion/worker/input_batch.py) from the
-```
+active request states:
 
-Its `forward()` method must accept `DiffusionRequestBatch` and return one
+- prompt embeddings and masks are normalized and padded
-`DiffusionOutput` per request. The runner validates the result count and maps
+- dynamic tensors such as `latents` and `timesteps` are gathered each step
-outputs back to their original request IDs with `BatchRunnerOutput`.
+- buffers are reused when batch composition stays the same
 
-Current in-tree request-batch implementations include the Flux, LTX-2, SD3, and
+The step-wise batched path is:
-Qwen-Image pipelines. Treat the pipeline capability flag in the source as
-authoritative because support continues to expand.
 
-### Request-Batch Data Flow
+1. Run `prepare_encode()` for newly admitted requests.
-
-- `DiffusionSchedulerOutput` carries scheduled request IDs and payloads.
-- `DiffusionRequestBatch` provides the pipeline-facing static batch.
-- `BatchRunnerOutput` carries per-request results back to the engine.
-
-Request-local setup, such as seed handling and output/error mapping, remains
-per request. Cache refresh, homogeneous LoRA activation, and
-`pipeline.forward(req_batch)` can be shared by the batch.
-
-### Compatibility and Admission
-
-`RequestBatchSamplingParamsKey` contains fields that affect the tensor contract,
-including shape, guidance, output count, and LoRA identity. Only compatible
-requests can share a fused forward call.
-
-Admission is FIFO and conservative. An incompatible request at the front of the
-waiting queue can prevent later compatible requests from joining the current
-wave.
-
-`request_batch_max_wait_ms` optionally delays the first schedule operation of a
-new wave so bursty arrivals can accumulate. It applies only when:
-
-- the pipeline supports request batching;
-- step execution is disabled;
-- no requests are currently running; and
-- the configured wait is greater than zero.
-
-The wait ends when the queue reaches capacity, stabilizes briefly, reaches its
-deadline, or the engine stops.
-
-## Step-Batch Execution
-
-Step execution exposes denoising progress to the scheduler. A supporting
-pipeline implements four stateful operations:
-
-| Operation | Responsibility |
-|---|---|
-| `prepare_encode(state)` | Validate input, encode prompts, initialize latents and timesteps, and create request-local scheduler state |
-| `denoise_step(input_batch, *, states=...)` | Run one denoise forward for the scheduler-provided request states |
-| `step_scheduler(state, noise_pred)` | Update latents and advance request progress |
-| `post_decode(state)` | Decode and postprocess a completed request or output boundary |
-
-Persistent request state lives in `StepRequestState`. Pipeline-specific fields
-that do not belong in the shared contract should be stored in `state.extra`.
-Queueing and lifecycle metadata remain in the scheduler's request state.
-
-Current native pipelines that explicitly enable step execution include
-Qwen-Image, HunyuanImage3, and Helios. Step execution alone does not imply
-continuous-batching support: Qwen-Image accepts batched step states.
-HunyuanImage3 accepts batched step states only when its resolved self-attention
-backend is `TORCH_SDPA`; otherwise it rejects groups larger than one request.
-Configure `DIFFUSION_ATTENTION_BACKEND=TORCH_SDPA` or
-`diffusion_attention_config.default.backend=TORCH_SDPA` when
-`max_num_seqs>1`. See the
-[HunyuanImage-3.0 recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/Tencent/HunyuanImage-3.0-Instruct.md)
-for its validated configuration. Helios supports only a single active step
-request and must use `max_num_seqs=1`.
-
-### Continuous Batching
-
-When `max_num_seqs>1`, `StepScheduler` can keep multiple compatible requests
-active. The runner gathers their state into `InputBatch`, performs one batched
-denoise forward, then applies scheduler updates per request:
-
-1. Receive transferred KV payloads, then run `prepare_encode()` for newly
-   admitted requests.
 2. Build or refresh `InputBatch`.
-3. Run one batched `denoise_step(input_batch, states=states)`.
+3. Run one batched `denoise_step(input_batch)`.
-4. Slice noise predictions back to each request.
+4. Slice the batched `noise_pred` back per request.
-5. Run each request's `step_scheduler()`.
+5. Run per-request `step_scheduler()`.
-6. Run `post_decode()` at a chunk boundary or request completion.
+6. Run `post_decode()` only for requests that finished denoising.
-7. Scatter updated latents back into persistent request state.
+7. Scatter updated latents back into persistent request state with
+   [`scatter_latents()`](gh-file:vllm_omni/diffusion/worker/input_batch.py).
 
-`StepBatchSamplingParamsKey` protects the batched tensor contract. Requests can
+This keeps the shared work limited to the denoise forward pass while preserving
-have different total step counts and current step indices, but shape-sensitive,
+request-local scheduler state and outputs.
-CFG-sensitive, and LoRA fields must be compatible. FIFO head-of-line blocking
-also applies here.
 
-Chunk-capable pipelines may emit intermediate results. Final-only step
+## Engine
-pipelines emit when the request finishes even if `streaming_output=True`.
 
-## Model Author Guidelines
+[`DiffusionEngine`](gh-file:vllm_omni/diffusion/diffusion_engine.py) provides
+the background loop and async add-request path needed for multiple requests to
+accumulate in the scheduler.
 
-When converting a request-level pipeline:
+When `step_execution=True`, the engine routes work through the step-wise
+executor path. The continuous batching behavior is defined by scheduler-side
+compatibility gating and runner-side `StepInputBatch` packing.
 
-- Reuse the same helpers as `forward()` to avoid behavior drift.
+## Current Limitations
-- Copy request-scoped scheduler state into `state.scheduler`.
-- Advance `state.step_index` only in `step_scheduler()`.
-- Keep model forward work in `denoise_step()`.
-- Keep latent mutation in `step_scheduler()`.
-- Keep final decoding equivalent to the tail of `forward()`.
-- Store masks, condition latents, and other request-local tensors in the
-  request state rather than on the shared pipeline.
 
-Before setting `supports_step_execution = True`, validate output parity for the
+- Experimental feature; use `max_num_seqs=1` for the conservative single-request
-same seed and sampling parameters, scheduler isolation across concurrent
+  step path.
-requests, abort cleanup, progress reporting, and all supported CFG paths.
+- Only native pipelines that already support `step_execution=True`.
+- Only homogeneous batches keyed by `StepBatchSamplingParamsKey` are supported.
+- `cache_backend`, KV transfer, and other request-mode extras are not wired
+  into the batched step-wise path yet.
+- Future work can relax the current same-shape restriction with richer
+  heterogeneous batching policies such as bucketing or padded execution for
+  different resolutions.
 
-Before setting `supports_request_batch = True`, validate the batch input
+## Related Files
-contract, one-output-per-request result shape, request identity and error
-mapping, seeded concurrency, LoRA compatibility, and tensor IPC.
 
-## Limitations
+- Scheduler base:
-
+  [`vllm_omni/diffusion/sched/base_scheduler.py`](gh-file:vllm_omni/diffusion/sched/base_scheduler.py)
-- Request batching requires an explicit pipeline capability when
+- Scheduler interface:
-  `max_num_seqs>1`.
+  [`vllm_omni/diffusion/sched/interface.py`](gh-file:vllm_omni/diffusion/sched/interface.py)
-- Step execution requires the four-method stateful pipeline contract.
+- Step scheduler:
-- Both batching paths currently require homogeneous compatibility keys.
+  [`vllm_omni/diffusion/sched/step_scheduler.py`](gh-file:vllm_omni/diffusion/sched/step_scheduler.py)
-- FIFO scheduling can reduce batching opportunities.
+- Runner:
-- `request_batch_max_wait_ms` trades first-request latency for burst
+  [`vllm_omni/diffusion/worker/diffusion_model_runner.py`](gh-file:vllm_omni/diffusion/worker/diffusion_model_runner.py)
-  coalescing.
+- Input batch:
-- All diffusion cache backends are currently unsupported in step mode.
+  [`vllm_omni/diffusion/worker/input_batch.py`](gh-file:vllm_omni/diffusion/worker/input_batch.py)
-- KV transfer is supported for newly admitted step requests; some other
+- Tests:
-  request-mode extras remain unsupported.
+  [`tests/diffusion/test_diffusion_scheduler.py`](gh-file:tests/diffusion/test_diffusion_scheduler.py)
-- Step continuous batching remains experimental; use `max_num_seqs=1` for the
-  conservative step path.
-
-## Related Implementation
-
-- Engine: [`vllm_omni/diffusion/diffusion_engine.py`](gh-file:vllm_omni/diffusion/diffusion_engine.py)
-- Model contract: [`vllm_omni/diffusion/models/interface.py`](gh-file:vllm_omni/diffusion/models/interface.py)
-- Scheduler interface: [`vllm_omni/diffusion/sched/interface.py`](gh-file:vllm_omni/diffusion/sched/interface.py)
-- Request scheduler: [`vllm_omni/diffusion/sched/request_scheduler.py`](gh-file:vllm_omni/diffusion/sched/request_scheduler.py)
-- Step scheduler: [`vllm_omni/diffusion/sched/step_scheduler.py`](gh-file:vllm_omni/diffusion/sched/step_scheduler.py)
-- Runner: [`vllm_omni/diffusion/worker/diffusion_model_runner.py`](gh-file:vllm_omni/diffusion/worker/diffusion_model_runner.py)
-- Request batch: [`vllm_omni/diffusion/worker/request_batch.py`](gh-file:vllm_omni/diffusion/worker/request_batch.py)
-- Step input batch: [`vllm_omni/diffusion/worker/input_batch.py`](gh-file:vllm_omni/diffusion/worker/input_batch.py)

docs/design/feature/diffusion_request_level_batching.md

@@ -0,0 +1,175 @@
+# Request-Level Batching for Diffusion
+
+This document describes the request-mode batching path for diffusion pipelines.
+For end-user enablement and tuning, see
+[Request-Level Batching](../../user_guide/diffusion/request_batching.md).
+
+This is separate from
+[Continuous Batching for Step-Wise Diffusion](diffusion_continuous_batching.md).
+Request-level batching runs one full pipeline `forward()` over a static batch of
+compatible requests. Step-wise continuous batching admits work between denoise
+steps when `step_execution=True`.
+
+## Why It Helps
+
+The request-level design avoids coupling several logical requests to one request
+object. This keeps request identity, abort/error handling, and per-request
+metadata unambiguous while still allowing one fused pipeline forward pass for
+bursty or concurrent traffic.
+
+## Overview
+
+With request-level batching enabled:
+
+- each `OmniDiffusionRequest` contains one `prompt` and one `request_id`
+- the scheduler groups compatible waiting requests into one scheduler wave
+- `DiffusionRequestBatch` wraps the scheduled requests for pipeline `forward()`
+- batch-capable pipelines return `list[DiffusionOutput]`, one output per
+  request
+- `BatchRunnerOutput` maps each result back to its original `request_id`
+
+Pipelines opt in with `supports_request_batch = True` and a `forward()` method
+that accepts `DiffusionRequestBatch` and returns `list[DiffusionOutput]`.
+Pipelines that do not opt in keep the existing per-request execution path.
+
+## Enablement
+
+Request-level batching is the request-mode path, so `step_execution` must remain
+disabled. Increase `max_num_seqs` above `1` to let the scheduler keep multiple
+compatible requests active:
+
+```bash
+vllm serve Qwen/Qwen-Image --omni \
+  --port 8091 \
+  --max-num-seqs 4
+```
+
+For bursty online ingress, `request_batch_max_wait_ms` can add a bounded
+admission wait before the first `schedule()` of a scheduler wave:
+
+```bash
+vllm serve Qwen/Qwen-Image --omni \
+  --port 8091 \
+  --max-num-seqs 4 \
+  --request-batch-max-wait-ms 20
+```
+
+`request_batch_max_wait_ms=0` disables this wait and is the default.
+
+## Request Contract
+
+`OmniDiffusionRequest` represents one logical request. It owns one prompt,
+sampling parameters, request id, and request-local metadata. Runtime batches are
+formed by the scheduler and represented separately from the request payload.
+
+Runtime batching is represented by:
+
+- [`DiffusionSchedulerOutput`](gh-file:vllm_omni/diffusion/sched/interface.py)
+  for scheduled request ids and request payloads
+- [`DiffusionRequestBatch`](gh-file:vllm_omni/diffusion/worker/request_batch.py)
+  for the pipeline-facing request batch
+- [`BatchRunnerOutput`](gh-file:vllm_omni/diffusion/worker/utils.py) for
+  per-request results
+
+`DiffusionRequestBatch` intentionally exposes compatibility properties such as
+`prompts`, `sampling_params`, `request_id`, and `kv_sender_info` so migrated
+pipelines can stay close to upstream code while using a batch-aware contract.
+
+## Scheduler
+
+The scheduler derives its capacity from `max_num_seqs` through
+`max_num_running_reqs`. It exposes waiting/running queue counters so the engine
+can decide whether admission wait is useful before scheduling a new wave.
+
+Batch compatibility is controlled by
+[`RequestBatchSamplingParamsKey`](gh-file:vllm_omni/diffusion/sched/interface.py). The key
+contains shape-sensitive and guidance-sensitive fields, including output count
+and LoRA identity. Requests with incompatible shapes, CFG settings, output
+counts, LoRA adapters, or LoRA scales are kept in separate batches.
+
+Admission is conservative:
+
+- the scheduler only batches compatible requests
+- FIFO ordering is preserved
+- an incompatible request at the head of the waiting queue blocks later
+  compatible requests
+
+## Engine
+
+[`DiffusionEngine`](gh-file:vllm_omni/diffusion/diffusion_engine.py) resolves
+request-batch capability during initialization from the configured pipeline
+class, including custom pipeline classes.
+
+The capability check uses the pipeline class attribute
+`supports_request_batch = True`. Pipelines that set this attribute must implement
+a request-batch-compatible `forward()` contract and return one
+`DiffusionOutput` per request; the runner validates that return shape at runtime.
+
+When the selected pipeline is batch-capable and `step_execution=False`, request
+mode routes scheduler waves through the batch executor path. Otherwise it keeps
+the per-request executor path.
+
+The optional admission wait runs only when:
+
+- request batching is supported
+- `step_execution=False`
+- `request_batch_max_wait_ms > 0`
+- no requests are currently running
+
+The wait exits early when the waiting queue reaches capacity, when the queue is
+stable for a short window, when the deadline expires, or when the engine stops.
+
+## Executor And Runner
+
+The executor exposes two request-mode entries:
+
+- `execute_request`: one worker call per scheduled request
+- `execute_batch`: one worker call for the whole `DiffusionSchedulerOutput`
+
+On the batch path, the worker builds a `DiffusionRequestBatch` and runs the
+pipeline once. Request-local setup remains per request:
+
+- KV transfer metadata
+- random generator and seed handling
+- request output/error/abort mapping
+
+Shared batch setup happens once per batch when possible:
+
+- cache refresh
+- LoRA activation for the homogeneous adapter key
+- pipeline `forward(req_batch)`
+
+Large tensor IPC still uses the shared-memory packing path. The packer traverses
+both normal `RunnerOutput.result` wrappers and nested batch results so batched
+outputs do not fall back to pickle IPC for tensor payloads.
+
+## Current Limitations
+
+- Only pipelines that declare the request-batch contract use fused batch
+  execution.
+- Batches are homogeneous under `RequestBatchSamplingParamsKey`; heterogeneous resolution or
+  incompatible guidance settings do not co-batch yet.
+- FIFO scheduling can reduce batching opportunities when an incompatible
+  request is at the front of the queue.
+- `request_batch_max_wait_ms` improves burst coalescing but can add latency to
+  the first request in a scheduler wave. Keep it small for latency-sensitive
+  serving.
+- Step-wise continuous batching is documented separately and only applies when
+  `step_execution=True`.
+
+## Related Files
+
+- Request object and request batch:
+  [`vllm_omni/diffusion/request.py`](gh-file:vllm_omni/diffusion/request.py)
+- Scheduler interface:
+  [`vllm_omni/diffusion/sched/interface.py`](gh-file:vllm_omni/diffusion/sched/interface.py)
+- Scheduler base:
+  [`vllm_omni/diffusion/sched/base_scheduler.py`](gh-file:vllm_omni/diffusion/sched/base_scheduler.py)
+- Engine:
+  [`vllm_omni/diffusion/diffusion_engine.py`](gh-file:vllm_omni/diffusion/diffusion_engine.py)
+- Worker runner:
+  [`vllm_omni/diffusion/worker/diffusion_model_runner.py`](gh-file:vllm_omni/diffusion/worker/diffusion_model_runner.py)
+- Executor interface:
+  [`vllm_omni/diffusion/executor/abstract.py`](gh-file:vllm_omni/diffusion/executor/abstract.py)
+- Tests:
+  [`tests/diffusion/test_diffusion_engine.py`](gh-file:tests/diffusion/test_diffusion_engine.py)

docs/design/feature/diffusion_step_execution.md

@@ -0,0 +1,131 @@
+# Adding Step Execution Support for Diffusion Pipelines
+
+This guide documents vLLM-Omni's stepwise diffusion contract for model authors
+and contributors implementing `step_execution=True` support for a diffusion
+pipeline.
+
+For end-user enablement, supported models, and current limitations, see
+[Step Execution](../../user_guide/diffusion/step_execution.md).
+
+This document describes the base step-execution contract only. For the
+experimental batching policy layered on top of the step-wise path, see
+[Continuous Batching for Step-Wise Diffusion](diffusion_continuous_batching.md).
+
+## Current Support Scope
+
+`step_execution` is **not** a generic diffusion toggle. It only works for
+pipelines that implement the segmented stateful contract in
+[`vllm_omni/diffusion/models/interface.py`](gh-file:vllm_omni/diffusion/models/interface.py).
+
+This page is intentionally author-facing. Treat runtime enablement
+(`step_execution=True` in Python or `--step-execution` in serving) as an
+opt-in user knob layered on top of the implementation contract below.
+
+Current in-tree support:
+
+| Pipeline | Example models | Step execution |
+|----------|----------------|----------------|
+| `QwenImagePipeline` | `Qwen/Qwen-Image`, `Qwen/Qwen-Image-2512` | Yes |
+| All other diffusion pipelines | `QwenImageEditPipeline`, `QwenImageEditPlusPipeline`, `QwenImageLayeredPipeline`, GLM-Image, Wan, Flux, etc. | No |
+
+Current engine/runtime limitations:
+
+- Continuous batching with `max_num_seqs > 1` is experimental and documented in
+  [Continuous Batching for Step-Wise Diffusion](diffusion_continuous_batching.md).
+  Keep `max_num_seqs=1` for the conservative single-request step path.
+- `cache_backend` is not supported in step mode.
+- Request-mode extras such as KV transfer are not wired into step mode yet.
+- Unsupported pipelines now fail early during model loading instead of failing on the first request.
+
+## Execution Contract
+
+Step mode is driven by four pipeline methods plus the shared mutable request
+state object:
+
+- `prepare_encode(state)`: one-time request preparation.
+- `denoise_step(state)`: compute the noise prediction for the current step.
+- `step_scheduler(state, noise_pred)`: mutate latents and advance step state.
+- `post_decode(state)`: decode the final output after denoising is complete.
+
+The state lives in
+[`vllm_omni/diffusion/worker/utils.py`](gh-file:vllm_omni/diffusion/worker/utils.py)
+as `StepRequestState`. Store request-scoped tensors there, or use
+`state.extra` for model-specific fields that do not justify extending the core
+dataclass.
+
+The worker-side step loop lives in
+[`vllm_omni/diffusion/worker/diffusion_model_runner.py`](gh-file:vllm_omni/diffusion/worker/diffusion_model_runner.py):
+
+1. `prepare_encode()` runs once for a new request.
+2. `denoise_step()` runs every scheduler tick.
+3. `step_scheduler()` mutates `state.latents` and advances `state.step_index`.
+4. `post_decode()` runs exactly once after `state.denoise_completed` becomes true.
+
+## Recommended Split
+
+When converting an existing request-level `forward()` pipeline, keep the split
+strict and mechanical:
+
+| Request-level phase | Stepwise method | What belongs there |
+|---------------------|-----------------|--------------------|
+| Input validation, prompt encoding, latent init, timestep prep, per-request scheduler creation | `prepare_encode()` | Anything that should happen once per request |
+| Transformer forward / noise prediction | `denoise_step()` | Pure denoise computation for the current timestep |
+| `scheduler.step(...)` and `step_index += 1` | `step_scheduler()` | Only latent/state mutation for one step |
+| VAE decode / postprocess | `post_decode()` | Final decode only |
+
+Keep the stepwise path reusing the same helpers as the request-level path
+whenever possible. Reimplementing the denoise loop from scratch is the easiest
+way to introduce behavioral drift.
+
+## Qwen-Image Reference
+
+[`pipeline_qwen_image.py`](gh-file:vllm_omni/diffusion/models/qwen_image/pipeline_qwen_image.py)
+is the reference implementation and is split correctly for the current
+contract:
+
+- `prepare_encode()` reuses `_prepare_generation_context()` so prompt encoding,
+  latent init, timestep creation, CFG setup, and shape bookkeeping stay aligned
+  with `forward()`.
+- `prepare_encode()` deep-copies `self.scheduler` **after**
+  `prepare_timesteps()` so request-specific scheduler state is isolated.
+- `denoise_step()` reuses `_build_denoise_kwargs()` plus
+  `predict_noise_maybe_with_cfg()`, so sequential CFG, CFG-parallel, and
+  non-CFG behavior stay identical to the request-level path.
+- `step_scheduler()` only calls
+  `scheduler_step_maybe_with_cfg(..., per_request_scheduler=state.scheduler)`
+  and increments `state.step_index`.
+- `post_decode()` reuses `_decode_latents()`, so the final image decode matches
+  the normal `forward()` path.
+
+That decomposition is the target pattern for future models.
+
+## Rules For New Pipelines
+
+- Do not keep request-scoped scheduler state on `self.scheduler`. Copy it into
+  `state.scheduler` during `prepare_encode()`.
+- Do not mutate `state.step_index` inside `denoise_step()`. Only
+  `step_scheduler()` should advance the step.
+- Do not decode partial outputs in `denoise_step()` or `step_scheduler()`.
+- If the request-level pipeline has condition latents, masks, or edit-specific
+  tensors, store them in `state` or `state.extra`, not in global pipeline
+  attributes.
+- Preserve CFG behavior by sharing the same helper path used by `forward()`.
+- Keep `post_decode()` equivalent to the tail of `forward()`.
+
+## Validation Checklist
+
+Before marking a pipeline as `supports_step_execution = True`, verify:
+
+- Stepwise output matches request-level output for the same seed and sampling params.
+- Per-request scheduler state is isolated across concurrent requests.
+- Abort during denoise does not leak cached state.
+- `step_index` reported by `RunnerOutput` matches the scheduler progress.
+- CFG-parallel and non-CFG paths both work if the request-level pipeline supports them.
+
+## Related Files
+
+- Contract: [`vllm_omni/diffusion/models/interface.py`](gh-file:vllm_omni/diffusion/models/interface.py)
+- State: [`vllm_omni/diffusion/worker/utils.py`](gh-file:vllm_omni/diffusion/worker/utils.py)
+- Runner loop: [`vllm_omni/diffusion/worker/diffusion_model_runner.py`](gh-file:vllm_omni/diffusion/worker/diffusion_model_runner.py)
+- Scheduler transport: [`vllm_omni/diffusion/sched/interface.py`](gh-file:vllm_omni/diffusion/sched/interface.py)
+- Reference pipeline: [`vllm_omni/diffusion/models/qwen_image/pipeline_qwen_image.py`](gh-file:vllm_omni/diffusion/models/qwen_image/pipeline_qwen_image.py)

docs/design/feature/distributed_layerwise_offload.md

@@ -1,156 +0,0 @@
-# Distributed Layerwise Offload
-
-This document describes distributed layerwise offload (DLO) for diffusion
-models. DLO keeps only a small number of DiT blocks on the accelerator and
-streams the remaining blocks from host memory. The distributed backend can
-either shard those host-side weights across an existing parallel group or keep
-the standard loader's rank-local weights and avoid an additional collective.
-
-For user-facing commands, see the
-[distributed layerwise offloading guide](../../user_guide/diffusion/cpu_offload.md)
-and the [Cosmos3 recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/cosmos3/Cosmos3-DistOffload.md).
-
-## Status
-
-DLO is implemented for multi-device diffusion execution. The default
-AllGather path is the primary path for DP and SP deployments. The
-`--dlo-no-use-allgather` path is a rank-local compatibility mode: it is useful
-for standard-loader sharding, workstation bring-up, and systems where an
-additional DLO collective is undesirable, but it does not reduce host weight
-storage across ranks.
-
-The compatibility matrix below describes the current implementation. The
-unit-level guards are covered, but not every parallelism combination has a
-full model-and-hardware end-to-end test.
-
-## Design
-
-### DLO consumes the existing parallel topology
-
-DLO does not create a new DP, TP, or SP topology. It reads the configured
-`DiffusionParallelConfig` and attaches offload hooks to the DiT blocks after the
-standard distributed groups have been initialized.
-
-The DLO weight-sharding group is selected as follows:
-
-1. Use the existing DP group when `data_parallel_size > 1`.
-2. When DP is one and SP is greater than one, use the SP group.
-3. Otherwise, run rank-locally without a DLO process group.
-
-TP is deliberately not used as DLO's AllGather group. HSDP has its own
-parameter-sharding lifecycle and is not allowed to be sharded a second time by
-DLO's AllGather path.
-
-### AllGather path
-
-With the default `dlo_use_allgather=True`, each rank stores approximately
-`1 / group_size` of each streamable block in pinned host memory. The next
-block's shard is copied to a device buffer and reconstructed with
-`all_gather_into_tensor` on a communication stream while the current block is
-executing.
-
-```text
-Compute:    [Block N]             [Block N+1]          [Block N+2]
-H2D:                      [shard N+1]           [shard N+2]
-AllGather:                [full N+1]             [full N+2]
-Buffers:    [current slot]       [prefetch slot]       [current slot]
-```
-
-![DLO double-buffer prefetch pipeline](../figures/dlo/dlo_pipeline.gif)
-
-The backend uses two shared device buffers, so accelerator weight residency is
-bounded by the largest streamed blocks rather than the complete model.
-
-When DP is greater than one, the engine can process one request per DP rank in
-the same denoising wave. Because AllGather is a collective, all participating
-requests must take the same execution path at every denoising step.
-
-### Rank-local path without DLO AllGather
-
-With `--dlo-no-use-allgather`, DLO forces its internal offload shard size to
-one. The regular model loader remains responsible for preparing each rank's
-weights, including TP-local tensors or HSDP-managed parameters. DLO then
-streams those rank-local tensors block by block using H2D copies only.
-
-This mode means:
-
-- DP still provides independent replicas, but DLO does not shard weights
-  across DP ranks.
-- SP still performs its normal activation/attention collectives, but DLO does
-  not shard weights across SP ranks.
-- TP/HSDP/SP collectives, if configured, are not disabled by this flag; only
-  DLO's additional weight AllGather is disabled.
-- Pure DP deployments keep a full host-side model copy per rank, subject to
-  shared OS page-cache behavior.
-- The scheduler does not require a synchronized DP request wave for DLO.
-
-This path is intentionally not implemented by reusing the AllGather mmap
-loader. It relies on the standard loader so model-specific TP/HSDP transforms
-remain intact.
-
-## Parallelism compatibility
-
-| Parallelism | DLO + AllGather | DLO without AllGather |
-|---|---|---|
-| **DP** | Supported primary path. DLO shards host weights across the DP group and can run DP multi-concurrency. | Supported rank-local path. DP replicas remain independent; no DLO weight sharding or cross-DP DLO collective. |
-| **SP** | Supported in the implementation. With DP=1, DLO uses the SP group for host-weight sharding; SP still shards sequence/activation work. | SP remains active, but DLO keeps standard-loader rank-local weights and adds no SP weight collective. |
-| **TP > 1** | Unsupported in the DLO mmap path. TP-aware loader callbacks are bypassed, so the backend rejects this configuration when it enters that path. | Standard loading is retained and TP-local tensors can be streamed. This is the intended compatibility path, but it still needs broader model and hardware validation. |
-| **HSDP** | Rejected. HSDP has already sharded parameters, so DLO AllGather would double-shard them. | Accepted by configuration. HSDP owns parameter sharding and its own gathers; DLO only stages rank-local parameters. End-to-end coverage is limited. |
-
-### Combined dimensions
-
-- **DP + SP:** DLO uses the DP group for weight sharding when DP is greater
-  than one; SP continues to use its own sequence-parallel group. If DP is one,
-  the SP group becomes DLO's sharding group in AllGather mode.
-- **DP + TP/SP without AllGather:** standard model loading defines the
-  rank-local tensor layout. DLO adds no cross-DP, cross-TP, or cross-SP weight
-  collective.
-- **HSDP + SP:** the general parallel configuration permits HSDP over SP, but
-  DLO must use `--dlo-no-use-allgather`. HSDP remains responsible for weight
-  materialization and synchronization.
-- **HSDP + DP or TP:** rejected independently by the diffusion parallel
-  configuration.
-
-## Request and loading constraints
-
-AllGather DP multi-concurrency requires:
-
-- explicit `num_inference_steps`;
-- the same `num_inference_steps` for all requests in a wave; and
-- identical request arguments that affect the collective execution path.
-
-The no-AllGather path does not impose these DLO-specific synchronized-wave
-requirements.
-
-The mmap loader is used only by the supported DLO+AllGather path when the
-model has a compatible checkpoint layout. Online quantization is incompatible
-with that sharded mmap path; use `--dlo-no-use-allgather` or disable online
-quantization. Models that do not meet the mmap requirements use the regular
-loader path.
-
-## Validation coverage
-
-Current source-level validation includes:
-
-- HSDP + DLO + AllGather rejection;
-- HSDP + DLO without AllGather acceptance at configuration level;
-- TP rejection in the DLO+AllGather mmap path;
-- resident-layer requests requiring no-AllGather;
-- DP request-wave validation for denoising-step compatibility;
-- sharding, double-buffer, AllGather-size, and heterogeneous-block regression
-  tests.
-
-The highest-value missing coverage is end-to-end numerical comparison against
-ordinary layerwise offload for DP+SP, TP+no-AllGather, and HSDP+SP+no-AllGather
-on the target CUDA/NCCL or CANN/HCCL hardware.
-
-## Recommendations
-
-- Use **DP + DLO AllGather** for the supported throughput and host-memory
-  scaling path.
-- Use **SP + DLO AllGather** for long-sequence workloads when DP concurrency is
-  not the goal.
-- Use **no-AllGather** to bring up TP or workstation PCIe configurations, with
-  the expectation of higher host-memory use and lower validation confidence.
-- Prefer **HSDP alone** for production HSDP deployments until the combined
-  HSDP + DLO no-AllGather path has broader end-to-end coverage.

docs/design/feature/omni_async_output_materialization.md

@@ -1,386 +0,0 @@
-# Async Omni Output Materialization
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Performance](#performance)
-3. [Architecture](#architecture)
-4. [Enabling the Feature](#enabling-the-feature)
-5. [Compatibility and Fallbacks](#compatibility-and-fallbacks)
-6. [Related Files](#related-files)
-
-## Overview
-
-Async Omni output materialization moves CPU-side construction of
-`OmniModelRunnerOutput` out of the autoregressive (AR) decode critical path.
-It complements [Async Chunk](async_chunk.md): async chunk pipelines partial
-outputs between stages, while async output materialization prevents the
-construction of those partial outputs from blocking the next decode step.
-
-An AR stage must return sampled token IDs quickly because the scheduler needs
-them for the next decode step. However, an Omni stage can also produce hidden
-states, multimodal tensors, streaming inter-stage payloads, and connector
-metadata. Building these payloads can require device-to-host (D2H) copies,
-tensor slicing, flattening, and Python object construction.
-
-Without this feature, all of that work runs inline in `sample_tokens()`:
-
-```text
-sample tokens
-  -> update decode state
-  -> copy hidden and multimodal outputs to CPU
-  -> build per-request payloads
-  -> build the streaming wire payload
-  -> collect connector signals
-  -> return sampled tokens
-  -> launch the next decode step
-```
-
-With async output materialization, only work required by the next decode step
-stays on the critical path:
-
-```text
-sample tokens
-  -> update decode state
-  -> snapshot output state and start asynchronous D2H copies
-  -> register sampled tokens
-  -> launch the next decode step
-
-background output path
-  -> wait for the payload snapshot
-  -> build per-request payloads
-  -> build the streaming wire payload
-  -> collect connector signals
-  -> construct OmniModelRunnerOutput
-```
-
-This allows payload construction for step `N` to overlap with GPU decode work
-for step `N + 1`. It does not change model computation or generated output.
-
-!!! note "Platform and validation scope"
-    The performance and correctness validation in this document covers CUDA
-    and ROCm. This is a validation scope, not a runtime platform guard: XPU
-    inherits `GPUARModelRunner`, and MUSA selects `GPUARWorker`, so those
-    backends may enter the asynchronous path when its other guards pass. XPU
-    and MUSA have not been validated for this optimization. Ascend NPU uses a
-    separate `NPUARModelRunner` path that still constructs
-    `OmniModelRunnerOutput` and drains connector output synchronously before
-    wrapping the result as an asynchronous runner output.
-
-<p align="center">
-  <img
-    alt="Decode step gap before and after async output materialization"
-    src="../../../source/architecture/qwen3-omni-async-output-step-gap.svg"
-    width="100%"
-  >
-</p>
-
-<p align="center">
-  <em>
-    Figure 1: Moving payload construction off the decode path reduces the
-    observed gap between consecutive Talker steps from about 2.8 ms to 41 µs.
-    Adapted from the
-    <a href="https://vllm.ai/blog/2026-07-01-qwen3-omni-optimization">
-      Qwen3-Omni optimization blog
-    </a>.
-  </em>
-</p>
-
-For Qwen3-Omni, the feature is enabled for both AR stages:
-
-- **Thinker**: Defers hidden-state and multimodal payload materialization.
-- **Talker**: Runs its decode-state postprocess eagerly, then defers codec
-  payload materialization. Because Code2Wav consumes codec codes rather than
-  Talker hidden states, the Talker also skips unnecessary hidden-state D2H.
-- **Code2Wav**: Does not use this path because it is a generation stage rather
-  than an AR stage.
-
-Qwen3-TTS uses the same mechanism in its AR Talker stage. The Talker updates
-the decode state it needs for the next step before returning, then constructs
-the codec payload for Code2Wav in the background.
-
-## Performance
-
-In the controlled Qwen3-Omni optimization sweep, enabling async output
-materialization on top of CUDA Graph and async chunk produced the following
-results at concurrency 64:
-
-| Configuration | Request throughput | Mean audio TTFP | Mean audio RTF |
-|---|---:|---:|---:|
-| CUDA Graph + async chunk | 9.3 req/s | 655 ms | 0.63 |
-| + async output materialization | 11.3 req/s | 631 ms | 0.47 |
-| Change | **+22%** | **-4%** | **-25%** |
-
-The sweep used `Qwen/Qwen3-Omni-30B-A3B-Instruct`, 640 Seed-TTS English
-prompts, and one replica each for Thinker, Talker, and Code2Wav. Async output
-materialization recovers throughput by removing CPU payload construction from
-the decode critical path without regressing time to first audio packet (TTFP).
-See the
-[Qwen3-Omni optimization blog](https://vllm.ai/blog/2026-07-01-qwen3-omni-optimization)
-for the complete benchmark methodology and results.
-
-The implementation was also validated against the synchronous safe-copy path.
-The text and audio output hashes matched, confirming that overlap does not
-change the generated result. See
-[PR #4476](https://github.com/vllm-project/vllm-omni/pull/4476) for the
-correctness and profiling details.
-
-## Architecture
-
-### Output Lifecycle
-
-`OmniAsyncGPUModelRunnerOutput` extends vLLM's
-`AsyncGPUModelRunnerOutput`. It preserves the existing asynchronous
-sampled-token feedback while adding a background builder for the complete Omni
-output.
-
-The output lifecycle is:
-
-1. `GPUARModelRunner.sample_tokens()` samples tokens and performs the
-   bookkeeping required by the next decode step.
-2. The runner snapshots step-local metadata such as request IDs, token spans,
-   scheduler output, and query start locations.
-3. CUDA payload tensors are cloned before reusable model or CUDA Graph buffers
-   can be overwritten.
-4. The cloned payload is copied to pinned CPU memory on a dedicated CUDA
-   stream. A CUDA event records when the copy is ready.
-5. `OmniAsyncGPUModelRunnerOutput` starts a background thread that waits for
-   the payload event and builds `OmniModelRunnerOutput`.
-6. The AR runner immediately registers the sampled-token CPU copy with the
-   input batch and returns, allowing async scheduling to advance.
-7. When the engine calls `get_output()`, it joins the background builder,
-   propagates any builder exception, and finalizes sampled tokens and logprobs
-   through the upstream output implementation.
-
-```text
-GPU / decode path                         Background output path
-
-forward + sample
-      |
-      +-- clone output tensors
-      +-- enqueue D2H copy --------------> wait for D2H event
-      +-- register sampled tokens               |
-      +-- return async output                    +-- slice per request
-      |                                         +-- build multimodal payloads
-next decode step                                +-- partition streaming payloads
-                                                +-- build the wire payload
-                                                +-- drain connector signals
-                                                +-- build OmniModelRunnerOutput
-```
-
-### Safe State Snapshots
-
-The next scheduler step can mutate runner state while the background builder is
-still active. Most step-local builder inputs are therefore detached snapshots.
-The snapshotted state includes:
-
-- scheduler token counts and speculative-token metadata
-- request IDs and request-to-batch-index mappings
-- sampled token IDs, logprobs, and prompt logprobs
-- query start locations and scheduled-token spans
-- hidden states and multimodal output tensors
-- KV-connector and encoder-cache outputs captured for the step
-
-CUDA tensor cloning is required because CUDA Graph and model output buffers can
-be reused by the next forward pass. The dedicated copy stream and pinned host
-buffers make the D2H transfer asynchronous; the snapshot retains its cloned
-CUDA sources until the transfer event completes.
-
-### Live Runner State and Ownership
-
-The complete builder input is not a detached snapshot. Connector output state
-remains runner-owned: `get_omni_connector_output()` drains live, per-cycle
-connector signals after the streaming payload is built. Correctness therefore
-depends on that builder being the only consumer that drains connector signals
-for its output cycle. Receive-side connector state written by the background
-receiver is coordinated by the connector mixin's `_lock`.
-`OmniAsyncGPUModelRunnerOutput.get_output()` joins the builder and is the
-completion and exception boundary before the materialized output is consumed.
-
-The shared output builder also contains a full-payload accumulation branch
-that reads `self.requests`. That branch is not reachable when async Omni output
-materialization is enabled: this feature requires `async_chunk`, while
-`should_accumulate_full_payload_output()` returns `False` whenever
-`async_chunk` is enabled. The feature path partitions each step's payload into
-streaming inter-stage and client handoffs instead.
-
-### Output Builder
-
-The background builder performs the work that previously ran inline:
-
-- resolves which requests need downstream payloads
-- converts hidden and multimodal tensors into per-request CPU payloads
-- applies model-specific payload processing
-- partitions per-step payloads into inter-stage and client streams
-- creates the tensor-only `multimodal_outputs` wire payload
-- drains live connector readiness signals after building the streaming payload
-- constructs the final `OmniModelRunnerOutput`
-
-Input-side connector operations remain synchronous with model execution. In
-particular, receiving inputs and flushing previously completed connector
-outputs are not deferred because they affect scheduler-visible request state.
-
-### Qwen3-Omni Stage Behavior
-
-| Stage | Async output behavior | Reason |
-|---|---|---|
-| Thinker | Snapshots hidden states and multimodal outputs; builds the downstream payload in the background | The Talker needs the payload, but the next Thinker decode step only needs sampled-token feedback |
-| Talker | Runs lightweight postprocess eagerly; snapshots codec outputs; omits hidden states from the downstream payload | `hidden_states.last` is needed by the next Talker step, while Code2Wav only needs codec codes |
-| Code2Wav | Uses the normal generation-stage output path | Code2Wav is not executed by `GPUARModelRunner` |
-
-The Qwen3-TTS Talker follows the same pattern as the Qwen3-Omni Talker:
-postprocess runs eagerly because the next decode step needs its updated state,
-while codec payload construction runs asynchronously. Its Code2Wav stage also
-uses the normal generation-stage path.
-
-## Enabling the Feature
-
-There is no separate `async_omni_output` command-line or YAML option. The
-feature is selected automatically for model stages that opt in when the runtime
-conditions are safe. On the validated CUDA and ROCm configurations, using the
-bundled deployment profile is enough to turn it on for the supported
-Qwen3-Omni and Qwen3-TTS pipelines. The selection logic has no CUDA/ROCm-only
-guard; see [Compatibility and Fallbacks](#compatibility-and-fallbacks) for the
-other platform paths. The same profile does not enable background Omni
-materialization on Ascend NPU.
-
-### Example 1: Qwen3-Omni
-
-Start the full Qwen3-Omni pipeline:
-
-```bash
-vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct \
-  --omni \
-  --port 8091
-```
-
-The model registry automatically loads
-`vllm_omni/deploy/qwen3_omni_moe.yaml`. Its relevant settings are:
-
-```yaml
-async_chunk: true
-
-stages:
-  - stage_id: 0  # Thinker
-    enable_prefix_caching: false
-    # async_scheduling defaults to true for AR stages
-
-  - stage_id: 1  # Talker
-    enable_prefix_caching: false
-    # async_scheduling defaults to true for AR stages
-
-  - stage_id: 2  # Code2Wav
-    enable_prefix_caching: false
-    async_scheduling: false
-```
-
-With this profile, async output materialization activates automatically for:
-
-- **Stage 0, Thinker**: Defers hidden-state and multimodal payload
-  construction.
-- **Stage 1, Talker**: Defers codec payload construction after eagerly
-  updating its decode state.
-
-Stage 2 does not use this feature because Code2Wav is not an AR stage.
-
-### Example 2: Qwen3-TTS
-
-Start Qwen3-TTS with any checkpoint that uses the Qwen3-TTS Talker pipeline.
-For example:
-
-```bash
-vllm serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \
-  --omni \
-  --port 8091
-```
-
-The model registry automatically loads `vllm_omni/deploy/qwen3_tts.yaml`. Its
-relevant settings are:
-
-```yaml
-async_chunk: true
-
-stages:
-  - stage_id: 0  # Talker
-    async_scheduling: true
-    enable_prefix_caching: false
-
-  - stage_id: 1  # Code2Wav
-    enable_prefix_caching: false
-```
-
-Async output materialization activates only for Stage 0, the AR Talker. The
-Talker keeps the state required by its next decode step on the GPU, skips an
-unnecessary hidden-state D2H copy, and builds the codec payload for Code2Wav in
-the background. Stage 1 uses the generation-stage output path.
-
-The same behavior applies to the Base and VoiceDesign Qwen3-TTS checkpoints
-because they use the same Talker implementation.
-
-!!! warning
-    Do not pass `--no-async-chunk` or enable prefix caching when you want this
-    optimization. Either change causes the runner to fall back to synchronous
-    output construction. Enabling async chunk alone cannot activate the feature
-    for a model that has not opted into async Omni output.
-
-!!! note "Prefix cache compatibility"
-    Async Omni output materialization and Omni prefix caching cannot currently
-    run together. `_should_use_async_omni_output()` returns `False` whenever
-    `self.omni_prefix_cache` is present, so prefix caching selects synchronous
-    output materialization. Supporting both features requires snapshotting or
-    otherwise synchronizing prefix-cache merge and update state before the
-    background output path can consume it safely.
-
-## Compatibility and Fallbacks
-
-`GPUARModelRunner` uses the async output path only when all of the following
-runtime conditions hold:
-
-| Requirement | Reason |
-|---|---|
-| AR async scheduling is enabled | The optimization relies on the scheduler advancing while the prior output is materialized |
-| `async_chunk` is enabled | The feature targets incremental downstream Omni payloads |
-| The model stage opts in with `use_async_omni_output` | Models must declare that their output lifecycle is safe to defer |
-| Omni prefix cache is disabled | Prefix-cache merge and update ordering currently requires synchronous materialization |
-| Speculative decoding is disabled | Speculative output state is not included in this deferred path |
-| Routed-expert output is disabled | Routed-expert extraction currently requires the synchronous path |
-| Postprocess is absent or explicitly runs eagerly | State needed by the next decode step must be updated before the runner returns |
-
-These checks are evaluated per stage on runners based on `GPUARModelRunner`.
-An unsupported combination does not prevent serving; it only falls back to
-synchronous output construction for that stage. CUDA and ROCm are the validated
-platforms. XPU inherits `GPUARModelRunner`, and MUSA selects `GPUARWorker`, so
-they may select the async path when these checks pass, but this optimization is
-not yet validated on either backend.
-
-Ascend NPU does not use this selection path. `NPUARModelRunner.sample_tokens()`
-fully constructs `OmniModelRunnerOutput`, calls
-`get_omni_connector_output()`, and only then creates the asynchronous wrapper,
-so Omni payload materialization remains synchronous.
-
-!!! note
-    `use_async_omni_output`,
-    `eager_omni_postprocess_before_async_output`, and
-    `omni_pooler_payload_include_hidden` are model implementation contracts,
-    not user-facing configuration fields.
-
-## Related Files
-
-- `vllm_omni/worker/gpu_ar_model_runner.py`: Async output object, safe tensor
-  snapshots, compatibility guards, and deferred Omni output builder.
-- `vllm_omni/platforms/npu/worker/npu_ar_model_runner.py`: Separate Ascend NPU
-  runner, where Omni output materialization remains synchronous.
-- `vllm_omni/model_executor/models/qwen3_omni/qwen3_omni.py`: Thinker and
-  Talker opt-in behavior.
-- `vllm_omni/deploy/qwen3_omni_moe.yaml`: Default Qwen3-Omni deployment
-  settings.
-- `vllm_omni/model_executor/models/qwen3_tts/qwen3_tts_talker.py`: Qwen3-TTS
-  Talker opt-in and eager postprocess behavior.
-- `vllm_omni/deploy/qwen3_tts.yaml`: Default Qwen3-TTS deployment settings.
-- `tests/worker/test_gpu_ar_model_runner.py`: Snapshot, guard, connector
-  ordering, and background error-propagation tests.
-- [Async Chunk](async_chunk.md): Inter-stage chunking and scheduling design.
-- [Qwen3-Omni optimization blog](https://vllm.ai/blog/2026-07-01-qwen3-omni-optimization):
-  Optimization context and controlled performance results.
-- [PR #4476](https://github.com/vllm-project/vllm-omni/pull/4476): Feature
-  implementation, validation, and review history.

docs/design/feature/quantization.md

@@ -1,249 +0,0 @@
-# Quantization
-
-This document describes the quantization architecture in vLLM-Omni and the
-extension points for contributors. For user-facing configuration, supported
-hardware, and method-specific instructions, see the
-[quantization user guide](../../user_guide/quantization/overview.md).
-
-## Goals and scope
-
-The design has four goals:
-
-1. Provide one `quantization_config` entry point for diffusion-only,
-   multi-stage omni/TTS, and multi-stage diffusion models.
-2. Reuse vLLM's quantization registry and `QuantizationConfig` contract where
-   a vLLM backend already provides the required behavior.
-3. Allow different components of one pipeline to use different quantization
-   configurations.
-4. Preserve the distinction between online quantization of a BF16/FP16
-   checkpoint and loading a pre-quantized checkpoint with serialized scales.
-
-This document covers configuration resolution, component routing, model
-integration, backend extension, and validation. Kernel implementations and
-user-facing support matrices are outside its scope.
-
-## Architecture
-
-The quantization path is split across the following layers:
-
-| Layer | Responsibility | Source |
-| --- | --- | --- |
-| Public API | Exposes `build_quant_config`, component routing, and backend registration | `vllm_omni/quantization/__init__.py` |
-| Factory | Normalizes method names, selects Omni overrides or vLLM registry backends, detects ModelOpt configs, and reconciles checkpoint metadata | `vllm_omni/quantization/factory.py` |
-| Component router | Resolves a quantization config from a layer prefix using longest-prefix matching | `vllm_omni/quantization/component_config.py` |
-| Method configs | Implement `QuantizationConfig` and select the platform-specific linear method | `vllm_omni/quantization/*_config.py` |
-| Diffusion configuration | Stores the canonical runtime config and propagates checkpoint configuration | `vllm_omni/diffusion/data.py` |
-| Worker and model integration | Passes the resolved config into vLLM's model configuration and model layers | `vllm_omni/diffusion/worker/diffusion_worker.py` and `vllm_omni/diffusion/models/` |
-
-The runtime contract remains vLLM's `QuantizationConfig`:
-
-```text
-user/CLI or model config
-          |
-          v
-OmniDiffusionConfig.quantization_config
-          |
-          +--> build_quant_config()
-          |        |
-          |        +--> Omni override
-          |        +--> vLLM registry backend
-          |        +--> ComponentQuantizationConfig
-          |
-          +--> checkpoint metadata reconciliation
-          |
-          +--> diffusion worker / vLLM config
-          |
-          +--> model layers call get_quant_method(layer, prefix)
-```
-
-The model layer receives either a method implementation or `None`. Returning
-`None` leaves that layer unquantized.
-
-## Configuration resolution
-
-`build_quant_config()` accepts the following forms:
-
-| Input | Resolution |
-| --- | --- |
-| `None` or `"none"` | Disable quantization. |
-| Method string, such as `"fp8"` | Resolve an Omni override first, then the vLLM quantization registry. |
-| Flat dictionary with `method` or `quant_method` | Normalize the method and construct its `QuantizationConfig`. |
-| Per-component dictionary | Construct a `ComponentQuantizationConfig`. |
-| Existing `QuantizationConfig` | Pass through without rebuilding it. |
-
-Method aliases are normalized case-insensitively, with `-` and `_` treated as
-equivalent. `auto-round` and `auto_round` use the Omni INC/AutoRound adapter.
-ModelOpt checkpoint metadata is detected from its method, producer metadata, or
-`quant_algo`, then mapped to the corresponding vLLM ModelOpt configuration.
-
-The factory uses Omni-specific overrides for methods whose diffusion behavior
-or platform dispatch is not provided by the vLLM registry. The current override
-set includes INT8, BitsAndBytes, MXFP8, MXFP4, MXFP4 dual-scale, and INC/
-AutoRound. Other methods, such as FP8, GGUF, and ModelOpt, are resolved through
-vLLM's registry when their configuration is compatible.
-
-## Per-component routing
-
-Multi-stage models do not necessarily want one quantization policy for every
-module. A component map expresses that policy without requiring each pipeline
-to construct separate vLLM configurations:
-
-```python
-quantization_config = {
-    "transformer": {"method": "fp8"},
-    "vae": None,
-    "default": None,
-}
-```
-
-`ComponentQuantizationConfig` applies the following rules:
-
-1. Component keys are interpreted as runtime layer-prefixes.
-2. The longest matching prefix wins.
-3. `None` disables quantization for the matching component.
-4. `default`, when present, handles prefixes with no explicit match.
-5. A matching child config delegates to its normal
-   `get_quant_method(layer, prefix)` implementation.
-
-Prefix matching happens after the model's weight-name mapping. New model
-integrations must verify the actual runtime prefixes, especially when a
-`WeightsMapper` changes checkpoint names. A prefix mismatch can silently route
-a layer to the default configuration, so component-routing tests should cover
-both positive matches and fall-through behavior.
-
-## Online and pre-quantized checkpoints
-
-The same method name can represent two different loading paths:
-
-- **Online**: the source checkpoint contains BF16/FP16 weights; the method
-  creates quantized weights or scales while the model is loaded.
-- **Pre-quantized**: the checkpoint contains quantized weights and the metadata
-  required by the method; the loader consumes those serialized tensors.
-
-Method configuration owns the mode flag, for example
-`is_checkpoint_int8_serialized` or `is_checkpoint_mxfp8_serialized`. The
-configuration's `get_quant_method()` selects the corresponding linear method.
-
-For pipelines with transformer-specific `config.json` files, such as cascade
-models, `resolve_quant_config_from_disk()` reconciles the active configuration
-with each transformer's checkpoint metadata. Its invariants are:
-
-- If no active configuration exists, valid checkpoint metadata can be used for
-  auto-detection.
-- A method mismatch is an error rather than an implicit conversion.
-- Serialized-checkpoint flags rebuild an online configuration into the
-  matching offline configuration.
-- Checkpoint-specific `ignored_layers` are preserved by rebuilding the active
-  configuration when they differ.
-- AutoRound MXFP8 metadata (`data_type="mx_fp"`) selects its offline path.
-
-This prevents a model from interpreting serialized weights with an online
-loader or silently applying the wrong method to one transformer in a
-multi-transformer pipeline.
-
-## Model and layer integration
-
-Diffusion model constructors receive the resolved configuration and pass it to
-quantizable vLLM layers. Each method configuration is responsible for:
-
-- identifying supported layers in `get_quant_method()`;
-- creating the correct parameter shapes and loaders;
-- processing weights after loading when conversion is required; and
-- applying the platform-specific quantized operation at runtime.
-
-Model code must keep precision-sensitive or unsupported modules unquantized.
-The shared `safe_quant_config()` helper is used by model integrations for
-normalization and modulation layers where a generic FP8 configuration would be
-unsafe. Text encoders, audio/vision encoders, VAEs, schedulers, and tokenizers
-are not implicitly quantized just because the main transformer is quantized;
-they require explicit component routing and method support.
-
-Weight quantization and quantized KV cache are separate paths. The former is
-resolved through `quantization_config`; runtime attention/KV-cache quantization
-is configured by the diffusion attention configuration and must be validated
-independently.
-
-## Platform and parallelism boundaries
-
-Platform checks belong in the method implementation rather than in the common
-factory. This keeps configuration parsing portable while allowing CUDA, NPU,
-and XPU methods to select different kernels or reject unsupported execution at
-model construction time. The user guide is the source of truth for the current
-hardware support matrix.
-
-Quantization methods must also respect the weight layout produced by the
-configured parallelism strategy:
-
-- Tensor-parallel layers may receive partitioned weight shapes and loaders.
-- Sequence-parallel execution changes activation movement but does not by
-  itself change the quantization configuration.
-- Data-parallel replicas build their own method state; quantization metadata
-  must be available consistently on every rank.
-- `WeightsMapper` transformations must be applied before matching ignored-layer
-  lists or component prefixes.
-
-Distributed layerwise offload has an additional boundary: its sharded mmap
-AllGather path is not compatible with online quantization because the path
-expects already materialized checkpoint weights. Use the rank-local
-`--dlo-no-use-allgather` path or a compatible pre-quantized checkpoint when
-combining these features. See the [DLO design document](distributed_layerwise_offload.md)
-for the full compatibility matrix.
-
-## Adding a quantization backend
-
-Contributors should follow this sequence:
-
-1. Check whether an existing vLLM backend can provide the required weight
-   format and kernel behavior. Prefer reuse over a duplicate Omni backend.
-2. If Omni-specific behavior is required, implement a `QuantizationConfig` and
-   its `QuantizeMethodBase`/linear method in `vllm_omni/quantization/`.
-3. Implement `get_name()`, supported activation dtypes, minimum capability,
-   checkpoint parsing, ignored-layer handling, and `get_quant_method()`.
-4. Add a lazy factory override in `factory.py`. Keep optional platform
-   dependencies out of package import paths and normalize aliases to one
-   canonical method name.
-5. If the method is pre-quantized, define the checkpoint metadata and the
-   serialized loading path before adding an online path.
-6. Add model-specific component routing only when the model contains stages
-   that must use different policies.
-7. Document user-visible configuration in the quantization user guide and keep
-   implementation rationale here.
-
-The public factory registration hook,
-`register_quantization_override(method, builder)`, is intended for integrations
-that need to register an Omni-compatible builder without changing the vLLM
-registry.
-
-## Validation
-
-Validation should cover the complete path, not only whether a config object can
-be instantiated:
-
-| Area | Required checks |
-| --- | --- |
-| Factory | Strings, aliases, flat dictionaries, invalid inputs, passthrough, and component maps |
-| Method config | Online/offline selection, ignored layers, platform guards, and weight loading |
-| Checkpoint metadata | Auto-detection, method mismatch errors, serialized flags, and per-transformer metadata |
-| Model integration | Correct quantization scope, unquantized components, and parallel weight layouts |
-| Numerical quality | Same-seed BF16 versus quantized output comparison at representative resolutions and step counts |
-| Performance | Peak device memory, generation latency, and any backend-specific throughput metric |
-
-The unit tests live under `tests/diffusion/quantization/`. The trajectory
-similarity tool in
-`vllm_omni/quantization/tools/compare_diffusion_trajectory_similarity.py`
-provides a repeatable quality and memory comparison for diffusion models.
-Method support and feature combinations remain model- and hardware-dependent;
-passing factory tests alone does not establish production support.
-
-## Design invariants
-
-- `quantization_config` is the single runtime source of truth after config
-  normalization.
-- A checkpoint method mismatch fails loudly instead of risking weight
-  corruption.
-- Components without an explicit supported quantization path remain in their
-  original precision.
-- Optional backend dependencies are imported lazily.
-- Method implementations own platform-specific capability checks and kernels.
-- User-facing support claims require model, hardware, numerical, and memory
-  validation in addition to configuration-level tests.

docs/design/feature/ray_based_execution.md

@@ -0,0 +1,59 @@
+# Distributed utils
+
+This directory (vllm_omni/distributed/ray_utils) contains utilities for distributed execution in vllm-omni, supporting both **Ray** and **Multiprocessing** backends.
+## 1. Installation
+```bash
+pip install "ray[default]"
+```
+## 2. Ray Utils
+
+The `ray_utils` module provides helper functions for managing Ray clusters and actors, which is essential for:
+*   **Multi-node deployment**: Running pipeline stages across different physical machines.
+*   **Resource management**: Efficient GPU/CPU allocation.
+
+### 2.1 Basic Usage
+
+To use the Ray backend, specify `worker_backend="ray"` when initializing the engine.
+
+**Command Line Example:**
+```bash
+vllm serve Qwen/Qwen2.5-Omni-7B \
+  --omni \
+  --port 8091 \
+  --worker-backend ray \
+  --ray-address auto
+```
+
+### 2.2 Cluster Setup
+
+**Step 1: Start Head Node**
+Run this on your primary machine:
+```bash
+ray start --head --port=6399
+```
+
+**Step 2: Connect Worker Nodes**
+Run this on each worker machine:
+```bash
+ray start --address=<HEAD_NODE_IP>:6399
+```
+
+> **Tip**: For a complete cluster setup script, refer to the vLLM example:
+> [run_cluster.sh](https://github.com/vllm-project/vllm/blob/main/examples/online_serving/run_cluster.sh)
+
+### 2.3 Distributed Connector Support
+
+When running on Ray, the system automatically adapts its communication strategy:
+
+*   **Cross-Node**: Recommended to use `MooncakeTransferEngineConnector` (RDMA, fastest) or `MooncakeStoreConnector` (TCP fallback).
+*   **Same-Node**: Can still use `SharedMemoryConnector` for efficiency, or Ray's native object store (plasma).
+*   **SHM payload routing**: `SharedMemoryConnector` always stores payloads in `/dev/shm`.
+
+### 2.4 Internal Helpers
+
+*   **`initialize_ray_cluster`**: Connects to an existing Ray cluster or starts a local one.
+
+## 3. Troubleshooting
+
+*   **Connection Issues**: Ensure the Ray head node is accessible and ports (default 6399 in this example) are open.
+*   **Version Mismatch**: Ensure all nodes run the same version of Ray and Python.

docs/design/index.md

@@ -1,9 +1,6 @@
 # Design Documents
 
-This section contains design documents and architecture specifications for
+This section contains design documents and architecture specifications for vLLM-Omni.
-vLLM-Omni. The sidebar groups documents by the system concern they describe;
-retired module pages are preserved in the legacy archive instead of remaining
-in the active navigation.
 
 ## Architecture Documents
 
@@ -11,80 +8,18 @@ in the active navigation.
 
 ## Feature Design Documents
 
-### Runtime and stage execution
-
 - [Disaggregated Inference](feature/disaggregated_inference.md)
-- [Async Chunk](feature/async_chunk.md)
+- [Ray-based Execution](feature/ray_based_execution.md)
-- [Async Diffusion Output](feature/async_diffusion_output.md)
+- [Adding Step Execution Support for Diffusion Pipelines](feature/diffusion_step_execution.md)
-- [Async Omni Output Materialization](feature/omni_async_output_materialization.md)
+- [Request-Level Batching for Diffusion](feature/diffusion_request_level_batching.md)
-- [Automatic Prefix Caching in Omni Models](feature/prefix_caching.md)
+- [Continuous Batching for Step-Wise Diffusion](feature/diffusion_continuous_batching.md)
 
-### Communication
+## Infrastructure Design Documents
-
-#### OmniConnector implementations
-
-- [Mooncake Store Connector](feature/omni_connectors/mooncake_store_connector.md)
-- [Mooncake Transfer Engine Connector](feature/omni_connectors/mooncake_transfer_engine_connector.md)
-- [Mori Transfer Engine Connector](feature/omni_connectors/mori_transfer_engine_connector.md)
-- [Shared Memory Connector](feature/omni_connectors/shared_memory_connector.md)
-- [Yuanrong Store Connector](feature/omni_connectors/yuanrong_connector.md)
-- [Yuanrong Transfer Engine Connector](feature/omni_connectors/yuanrong_transfer_engine_connector.md)
-
-### Diffusion acceleration
-
-#### Parallelism
-
-- [CFG-Parallel](feature/cfg_parallel.md)
-- [Expert Parallel](feature/expert_parallel.md)
-- [Hybrid Sharded Data Parallel (HSDP)](feature/hsdp.md)
-- [Pipeline Parallel](feature/pipeline_parallel.md)
-- [Sequence Parallel](feature/sequence_parallel.md)
-- [Tensor Parallel](feature/tensor_parallel.md)
-- [VAE Patch Parallelism](feature/vae_parallel.md)
-
-#### 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)
-- [Distributed Layerwise Offload](feature/distributed_layerwise_offload.md)
-
-## Infrastructure and Performance
 
 - [Prometheus Metrics](metrics.md)
-- [Speech Generation Performance Optimizations](qwen3_omni_tts_performance_optimization.md)
 
 ## Module Design Documents
 
-- [Entrypoints and Serving Boundaries](module/entrypoints.md)
+- [AR Module](module/ar_module.md)
-- [vLLM-Omni Configuration](module/vllm_omni_config.md)
+- [DIT Module](module/dit_module.md)
-- [Input, Output, and Modality Contracts](module/input_output_modality_contracts.md)
+- [Entrypoint Module](module/entrypoint_module.md)
-- [Error Classification, Propagation, and Rendering](module/error_contracts.md)
-- [Engine Orchestration](module/engine_orchestration.md)
-- [Stage Runtime and Replica Lifecycle](module/stage_runtime.md)
-- [OmniConnector](module/omni_connector.md)
-- [Model Integration](module/model_integration.md)
-- [Autoregressive Runtime](module/ar_runtime.md)
-- Diffusion
-  - [Overview](module/diffusion/index.md)
-  - [Runtime](module/diffusion/diffusion_runtime.md)
-  - [Model Integration](module/diffusion/diffusion_model_integration.md)
-  - [Continuous Batching](module/diffusion/continuous_batching.md)
-  - [Parallelism](module/diffusion/parallelism.md)
-  - [Offloader](module/diffusion/offloader.md)
-- [Execution Platforms](module/execution_platforms.md)
-- [Cache Management](module/cache_management.md)
-- [Quantization](module/quantization.md)
-- [Observability](module/observability.md)
-- [Profiling](module/profiling.md)
-- [Benchmarking](module/benchmarking.md)
-
-The pre-#5137 pages are preserved in the
-[legacy module archive](module/archive/README.md) for historical reference and
-are not active design contracts.

docs/design/module/ar_module.md

@@ -12,7 +12,7 @@ The AR module of vLLM-Omni extends vLLM's core components to support:
 - **Hidden state exposure**: Exposing per-request hidden representations for downstream stages
 - **Basic generator support**: Support some basic heterogeneous architecture such as Convolution, LSTM, etc.
 
-As shown in the [end2end example](../../../user_guide/examples/offline_inference/qwen3_omni.md), AR module can be widely applied across multiple stages, generating text tokens in thinker(AR), audio latent tokens in talker(AR) and audio wave in code2wav(Convolution).
+As shown in the [end2end example](../../user_guide/examples/offline_inference/qwen3_omni.md), AR module can be widely applied across multiple stages, generating text tokens in thinker(AR), audio latent tokens in talker(AR) and audio wave in code2wav(Convolution).
 
 ## 2. Relationship with vLLM
 

docs/design/module/ar_runtime.md

@@ -1,52 +0,0 @@
----
-title: Autoregressive Runtime
-kind: module
-status: draft
-owners:
-  - "@tzhouam"
-  - "@yinpeiqi"
-  - "@fake0fan"
-  - "@Sy0307"
-primary_code_paths:
-  - vllm_omni/core/**
-  - vllm_omni/worker/**
-related_code_paths:
-  - vllm_omni/model_executor/**
-depends_on:
-  - engine_orchestration.md
-  - model_integration.md
-  - input_output_modality_contracts.md
-validation_paths:
-  - tests/core/**
-  - tests/worker/**
-upstream_refs:
-  - vllm.v1.core
-  - vllm.v1.worker
-last_reviewed: 2026-07-16
----
-
-# Autoregressive runtime
-
-The AR runtime extends vLLM scheduling and worker execution for omni-stage
-inputs and outputs while preserving vLLM scheduling and cache semantics.
-
-## Candidate invariants
-
-### AR-INV-001: vLLM owns base scheduling semantics
-
-**Rule:** Omni schedulers MUST preserve upstream request-state and cache
-transitions unless an Omni-specific difference is documented and tested.
-
-### AR-INV-002: Omni data crosses explicit adapters
-
-**Rule:** Modality-specific stage data MUST be converted at an input or output
-adapter, not injected through unrelated scheduler state.
-
-### AR-INV-003: Workers execute assigned work
-
-**Rule:** Workers and model runners MUST NOT implement cross-stage routing.
-
-## Safe-change guide
-
-Test request lifecycle, abort, cache state, and every affected worker execution
-mode against the supported upstream vLLM contract.

docs/design/module/archive/README.md

@@ -1,18 +0,0 @@
-# Archived module design pages
-
-This directory preserves module-design pages that predate the structure
-proposed in [issue #5137](https://github.com/vllm-project/vllm-omni/issues/5137).
-They are historical snapshots, not active architectural contracts, and are
-intentionally excluded from the documentation navigation.
-
-| Archived page | Active destination |
-| --- | --- |
-| [AR Module](ar_module.md) | [Autoregressive Runtime](../ar_runtime.md) |
-| [AsyncOmni Architecture](async_omni_architecture.md) | [Engine Orchestration](../engine_orchestration.md) and [Stage Runtime](../stage_runtime.md) |
-| [DiT Module](dit_module.md) | [Diffusion module overview](../diffusion/index.md) |
-| [Entrypoint Module](entrypoint_module.md) | [Entrypoints and Serving Boundaries](../entrypoints.md) |
-
-Do not update these pages with current design guidance. Move still-useful
-material into the active destination and review it against current code and
-tests instead. No compatibility redirect pages are provided at the former
-paths.

docs/design/module/benchmarking.md

@@ -1,47 +0,0 @@
----
-title: Benchmarking
-kind: module
-status: draft
-owners:
-  - "@alex-jw-brooks"
-primary_code_paths:
-  - vllm_omni/benchmarks/**
-  - vllm_omni/entrypoints/cli/benchmark/**
-related_code_paths:
-  - benchmarks/**
-depends_on:
-  - entrypoints.md
-  - profiling.md
-validation_paths:
-  - tests/benchmarks/**
-  - tests/dfx/perf/**
-upstream_refs:
-  - vllm.benchmarks
-last_reviewed: 2026-07-16
----
-
-# Benchmarking
-
-Benchmarking defines reproducible workloads, metrics, warm-up, measurement,
-and result metadata for comparing vLLM-Omni performance.
-
-## Candidate invariants
-
-### BENCH-INV-001: Results are reproducible
-
-**Rule:** Results MUST identify the model, revision, commit, hardware,
-configuration, workload, concurrency, warm-up, and measurement window.
-
-### BENCH-INV-002: Correctness precedes performance
-
-**Rule:** A benchmark MUST validate successful and semantically acceptable
-outputs before using timings as performance evidence.
-
-### BENCH-INV-003: Metric definitions are explicit
-
-**Rule:** Metrics MUST state their unit, population, and aggregation.
-
-## Safe-change guide
-
-Test workload parsing and metric calculations with deterministic fixtures. Do
-not compare materially different workloads or runtime settings.

docs/design/module/cache_management.md

@@ -1,47 +0,0 @@
----
-title: Cache Management
-kind: module
-status: draft
-owners:
-  - "@Isotr0py"
-  - "@princepride"
-primary_code_paths:
-  - vllm_omni/diffusion/cache/**
-related_code_paths:
-  - vllm_omni/experimental/ar_diffusion/kv_cache/**
-  - vllm_omni/core/**
-depends_on:
-  - ar_runtime.md
-  - diffusion/diffusion_runtime.md
-validation_paths:
-  - tests/diffusion/cache/**
-upstream_refs:
-  - vllm.v1.core.kv_cache_manager
-last_reviewed: 2026-07-16
----
-
-# Cache management
-
-Cache management defines reusable state, cache identity, validity, lifecycle,
-and eviction across AR and diffusion execution.
-
-## Candidate invariants
-
-### CACHE-INV-001: Cache identity is complete
-
-**Rule:** A cache key MUST include every input and execution property that can
-change the reused value.
-
-### CACHE-INV-002: Reuse preserves correctness
-
-**Rule:** A cache optimization MUST provide a disabled path and MUST NOT reuse
-state after its validity conditions change.
-
-### CACHE-INV-003: Ownership has an end
-
-**Rule:** Request-scoped and model-scoped cache entries MUST have explicit
-reset, eviction, or teardown behavior.
-
-## Safe-change guide
-
-Test hit, miss, invalidation, disabled, concurrent-request, and teardown paths.

docs/design/module/diffusion/continuous_batching.md

@@ -1,51 +0,0 @@
----
-title: Diffusion Continuous Batching
-kind: module
-status: draft
-owners:
-  - "@Isotr0py"
-  - "@princepride"
-primary_code_paths:
-  - vllm_omni/diffusion/sched/**
-related_code_paths:
-  - vllm_omni/diffusion/executor/**
-depends_on:
-  - diffusion_runtime.md
-validation_paths:
-  - tests/diffusion/batching/**
-upstream_refs: []
-last_reviewed: 2026-07-16
----
-
-# Diffusion continuous batching
-
-Continuous batching defines when diffusion requests are compatible, how they
-share an execution step, and how each request advances independently.
-
-## Candidate invariants
-
-### BATCH-INV-001: Compatibility is explicit
-
-**Rule:** Requests MAY share a batch only when all properties required by the
-selected pipeline, scheduler step, shape, precision, and execution features are
-compatible.
-
-### BATCH-INV-002: Per-request state remains isolated
-
-**Rule:** Batch assembly MUST preserve each request's random generator, progress,
-conditioning, outputs, cancellation, and errors.
-
-### BATCH-INV-003: Admission is bounded
-
-**Rule:** Admission MUST respect configured capacity and MUST NOT rely on an
-unbounded waiting or active-request collection.
-
-### BATCH-INV-004: Batch order is not completion order
-
-**Rule:** Output association MUST use stable request identity rather than batch
-position across execution steps.
-
-## Safe-change guide
-
-Test heterogeneous requests, partial completion, cancellation, deterministic
-seeds, capacity limits, and batch sizes of one and many.

docs/design/module/diffusion/diffusion_model_integration.md

@@ -1,58 +0,0 @@
----
-title: Diffusion Model Integration
-kind: module
-status: draft
-owners:
-  - "@Isotr0py"
-  - "@wtomin"
-  - "@ZJY0516"
-primary_code_paths:
-  - vllm_omni/diffusion/models/**
-  - vllm_omni/diffusion/model_loader/**
-related_code_paths:
-  - vllm_omni/diffusion/layers/**
-  - vllm_omni/diffusion/lora/**
-  - vllm_omni/diffusion/utils/**
-depends_on:
-  - diffusion_runtime.md
-  - ../input_output_modality_contracts.md
-validation_paths:
-  - tests/diffusion/models/**
-  - tests/diffusion/model_loader/**
-  - tests/diffusion/layers/**
-  - tests/diffusion/lora/**
-upstream_refs:
-  - diffusers.DiffusionPipeline
-last_reviewed: 2026-07-16
----
-
-# Diffusion model integration
-
-Diffusion model integration owns pipeline contracts, registration, checkpoint
-loading, adapters, shared layers, and model-specific processing.
-
-## Candidate invariants
-
-### DIFF-MODEL-INV-001: Pipelines implement one runtime contract
-
-**Rule:** A pipeline MUST declare its supported modalities, configuration,
-inputs, outputs, loading path, and runtime capabilities.
-
-### DIFF-MODEL-INV-002: Registration is the selection boundary
-
-**Rule:** Runtime code MUST select model implementations through the registry or
-loader contract rather than scattered model-name conditionals.
-
-### DIFF-MODEL-INV-003: Model code does not schedule requests
-
-**Rule:** Pipeline code MUST NOT own admission, batching, cancellation, or
-cross-stage routing.
-
-### DIFF-MODEL-INV-004: Shared behavior stays shared
-
-**Rule:** Model directories SHOULD contain only genuine model differences.
-
-## Safe-change guide
-
-Test registry selection, checkpoint loading, minimal inference, input and output
-contracts, and every declared optional capability.

docs/design/module/diffusion/diffusion_runtime.md

@@ -1,58 +0,0 @@
----
-title: Diffusion Runtime
-kind: module
-status: draft
-owners:
-  - "@Isotr0py"
-  - "@princepride"
-  - "@SamitHuang"
-primary_code_paths:
-  - vllm_omni/diffusion/sched/**
-  - vllm_omni/diffusion/executor/**
-  - vllm_omni/diffusion/worker/**
-related_code_paths:
-  - vllm_omni/diffusion/hooks/**
-  - vllm_omni/diffusion/postprocess/**
-depends_on:
-  - ../engine_orchestration.md
-  - ../input_output_modality_contracts.md
-  - diffusion_model_integration.md
-validation_paths:
-  - tests/diffusion/diffusion_backend/**
-  - tests/diffusion/hooks/**
-upstream_refs:
-  - diffusers.DiffusionPipeline
-last_reviewed: 2026-07-16
----
-
-# Diffusion runtime
-
-The diffusion runtime owns request admission, scheduling, execution, progress,
-output, cancellation, and cleanup inside a diffusion stage.
-
-## Candidate invariants
-
-### DIFF-RUNTIME-INV-001: One lifecycle owner
-
-**Rule:** Every admitted request MUST have exactly one scheduler-owned lifecycle
-until completion, cancellation, or failure.
-
-### DIFF-RUNTIME-INV-002: Execution follows scheduler output
-
-**Rule:** Executors and workers MUST execute scheduler decisions without
-admitting, reordering, or forwarding requests independently.
-
-### DIFF-RUNTIME-INV-003: Terminal cleanup is complete
-
-**Rule:** Every terminal path MUST release request state, temporary tensors,
-hooks, and runtime-owned resources.
-
-### DIFF-RUNTIME-INV-004: Optional features use runtime hooks
-
-**Rule:** Cache, profiling, offload, and parallel features SHOULD integrate at
-defined hooks instead of creating another request lifecycle.
-
-## Safe-change guide
-
-Test success, cancellation, failure, shutdown, multiple requests, and resource
-cleanup.

docs/design/module/diffusion/index.md

@@ -1,42 +0,0 @@
----
-title: Diffusion Modules
-kind: module-index
-status: draft
-owners:
-  - "@Isotr0py"
-  - "@princepride"
-  - "@SamitHuang"
-  - "@wtomin"
-  - "@ZJY0516"
-  - "@RuixiangMa"
-  - "@david6666666"
-  - "@xuechendi"
-primary_code_paths:
-  - vllm_omni/diffusion/**
-related_code_paths:
-  - vllm_omni/platforms/**
-depends_on:
-  - ../engine_orchestration.md
-  - ../input_output_modality_contracts.md
-validation_paths:
-  - tests/diffusion/**
-upstream_refs:
-  - diffusers
-last_reviewed: 2026-07-16
----
-
-# Diffusion modules
-
-Diffusion is a module family containing runtime, model integration, batching,
-distributed execution, and memory-management subsystems.
-
-## Module documents
-
-- [Diffusion runtime](diffusion_runtime.md)
-- [Diffusion model integration](diffusion_model_integration.md)
-- [Continuous batching](continuous_batching.md)
-- [Parallelism](parallelism.md)
-- [Offloader](offloader.md)
-
-Cache, quantization, profiling, and benchmarking follow their top-level module
-documents.

docs/design/module/diffusion/offloader.md

@@ -1,53 +0,0 @@
----
-title: Diffusion Offloader
-kind: module
-status: draft
-owners:
-  - "@yuanheng-zhao"
-  - "@Isotr0py"
-primary_code_paths:
-  - vllm_omni/diffusion/offloader/**
-related_code_paths:
-  - vllm_omni/diffusion/models/**
-  - vllm_omni/diffusion/worker/**
-depends_on:
-  - diffusion_runtime.md
-  - ../execution_platforms.md
-validation_paths:
-  - tests/diffusion/offloader/**
-upstream_refs:
-  - torch.nn.Module.to
-last_reviewed: 2026-07-16
----
-
-# Diffusion offloader
-
-The offloader owns component residency, transfer scheduling, memory accounting,
-prefetch, and teardown for diffusion execution.
-
-## Candidate invariants
-
-### OFFLOAD-INV-001: Residency is explicit
-
-**Rule:** Each managed component MUST have one known residency state and one
-owner responsible for transitions.
-
-### OFFLOAD-INV-002: Use follows readiness
-
-**Rule:** Runtime execution MUST NOT consume a component until its transfer to
-the required device is complete.
-
-### OFFLOAD-INV-003: Transfers preserve model state
-
-**Rule:** Offloading MUST preserve parameter and buffer identity, dtype, device,
-and correctness required by the selected execution mode.
-
-### OFFLOAD-INV-004: Memory is bounded and released
-
-**Rule:** Retained host and device copies MUST respect configured limits and
-provide deterministic teardown.
-
-## Safe-change guide
-
-Test enabled and disabled paths, repeated execution, asynchronous transfer,
-memory limits, failure, teardown, and numerical equivalence.

docs/design/module/diffusion/parallelism.md

@@ -1,56 +0,0 @@
----
-title: Diffusion Parallelism
-kind: module
-status: draft
-owners:
-  - "@princepride"
-  - "@yuanheng-zhao"
-  - "@xuechendi"
-primary_code_paths:
-  - vllm_omni/diffusion/distributed/**
-  - vllm_omni/diffusion/attention/parallel/**
-related_code_paths:
-  - vllm_omni/distributed/**
-  - vllm_omni/config/composable_parallel/**
-depends_on:
-  - diffusion_runtime.md
-  - ../vllm_omni_config.md
-validation_paths:
-  - tests/diffusion/distributed/**
-  - tests/diffusion/attention/**
-upstream_refs:
-  - torch.distributed
-last_reviewed: 2026-07-16
----
-
-# Diffusion parallelism
-
-Parallelism owns diffusion rank topology, process groups, tensor and sequence
-sharding, collectives, and distributed execution.
-
-## Candidate invariants
-
-### PARALLEL-INV-001: Topology has one source of truth
-
-**Rule:** Rank coordinates, group membership, and parallel dimensions MUST be
-derived from validated configuration.
-
-### PARALLEL-INV-002: Sharding contracts are explicit
-
-**Rule:** Every distributed boundary MUST define tensor shape, sharded
-dimension, placement, dtype, producer, and consumer.
-
-### PARALLEL-INV-003: Collectives are symmetric
-
-**Rule:** Process-group members MUST invoke compatible collectives in the same
-logical order.
-
-### PARALLEL-INV-004: Single-rank behavior remains valid
-
-**Rule:** Distributed implementations SHOULD preserve a supported single-rank
-path without distributed initialization.
-
-## Safe-change guide
-
-Test topology validation, single-rank execution, affected parallel modes,
-combined modes, invalid shapes, and orderly teardown.

docs/design/module/dit_module.md

@@ -252,7 +252,8 @@ while True:
   batch of compatible independent requests for one full pipeline forward when
   the pipeline supports request-level batching; the step-wise path can also
   admit or remove compatible requests between denoise steps. See
-  [Diffusion Continuous Batching](../../feature/diffusion_continuous_batching.md).
+  [Request-Level Batching](../feature/diffusion_request_level_batching.md) and
+  [Continuous Batching for Step-Wise Diffusion](../feature/diffusion_continuous_batching.md).
 
 ---
 
@@ -539,9 +540,9 @@ def get_attn_backend_for_role(role, head_size, attention_config=None, role_categ
 
 4. **Platform default** — `current_omni_platform.get_diffusion_attn_backend_cls(...)` picks the best-available kernel for the hardware.
 
-A backend that needs configuration exposes it as a typed field on `AttentionSpec`; `AttentionSpec.backend_kwargs()` serializes it into the `backend_kwargs` the impl consumes. Today those fields are `skip_softmax` (TRTLLM_ATTN) and `block_sparse` (any block-sparse backend, currently RAINFUSION_ATTN), so e.g. `target_sparsity` or `sparsity` can be set without changing model code.
+A backend that needs configuration exposes it as a typed field on `AttentionSpec`; `AttentionSpec.backend_kwargs()` serializes it into the `backend_kwargs` the impl consumes. Today the only such field is `skip_softmax` (TRTLLM_ATTN), so e.g. `target_sparsity` can be set without changing model code.
 
-For the user-facing CLI surface, see [Diffusion Attention Backends](../../../user_guide/diffusion/attention_backends.md). For the role declaration contract on the model side, see [Adding a Diffusion Model](../../../contributing/model/adding_diffusion_model.md).
+For the user-facing CLI surface, see [Diffusion Attention Backends](../../user_guide/diffusion/attention_backends.md). For the role declaration contract on the model side, see [Adding a Diffusion Model](../../contributing/model/adding_diffusion_model.md).
 
 **Backend Availability**:
 

docs/design/module/engine_orchestration.md

@@ -1,122 +0,0 @@
----
-title: Engine Orchestration
-kind: module
-status: draft
-architecture_state: current-plus-in-flight
-owners:
-  - "@tzhouam"
-  - "@fake0fan"
-document_stewards:
-  - "@hsliuustc0106"
-  - "@Gaohan123"
-  - "@david6666666"
-required_reviewers:
-  - "@yinpeiqi"
-  - "@Sy0307"
-  - "@yenuo26"
-  - "@NickCao"
-primary_code_paths:
-  - vllm_omni/engine/async_omni_engine.py
-  - vllm_omni/engine/async_engine_utils.py
-  - vllm_omni/engine/orchestrator.py
-  - vllm_omni/engine/cfg_companion_tracker.py
-  - vllm_omni/engine/rpc_result_router.py
-related_code_paths:
-  - vllm_omni/engine/messages.py
-  - vllm_omni/engine/orchestrator_monitor.py
-  - vllm_omni/engine/stage_client.py
-  - vllm_omni/engine/stage_pool.py
-  - vllm_omni/outputs/output_processor.py
-  - vllm_omni/distributed/omni_coordinator/**
-depends_on:
-  - input_output_modality_contracts.md
-  - error_contracts.md
-  - stage_runtime.md
-  - omni_connector.md
-validation_paths:
-  - tests/engine/test_async_omni_engine_input.py
-  - tests/engine/test_async_omni_engine_outputs.py
-  - tests/engine/test_async_omni_engine_abort.py
-  - tests/engine/test_async_omni_engine_stage_init.py
-  - tests/engine/test_orchestrator.py
-  - tests/engine/test_orchestrator_error_handling.py
-  - tests/engine/test_orchestrator_stage_input_bridge.py
-  - tests/engine/test_cfg_companion_lifecycle.py
-  - tests/engine/test_rpc_result_router.py
-  - tests/e2e/features/fullduplex/engine/**
-upstream_refs:
-  - vllm.v1.engine.EngineCoreRequest
-  - vllm.v1.engine.EngineCoreOutputs
-  - vllm.v1.engine.exceptions.EngineDeadError
-  - vllm.outputs.RequestOutput
-invariant_namespace: ORCH-INV
-last_reviewed: 2026-08-07
-last_verified_commit: 3d7fc3b9ba3cac88d579d4dc35b78b0b641675fc
----
-
-# Engine orchestration
-
-Engine orchestration coordinates configured AR and diffusion stages while
-keeping public clients independent from stage processes and transports.
-
-## Contract status
-
-This document is a draft description of current behavior. It also identifies
-the boundary affected by the in-flight stage client/process refactor in
-[#5441](https://github.com/vllm-project/vllm-omni/pull/5441). Names and
-responsibilities proposed only by that PR are not current contracts.
-
-## Ownership boundary
-
-This document owns `AsyncOmniEngine`, `Orchestrator`, request-state creation,
-cross-stage routing, output ordering, companion tracking, control/RPC
-correlation, cancellation propagation, and terminal-state convergence.
-
-It does not own stage placement, replica selection, stage-process startup,
-payload schemas, public protocol rendering, connector transport, or semantic
-error classification. Those responsibilities belong to the stage runtime,
-I/O, entrypoint, connector, and error contracts.
-
-## Candidate invariants
-
-These identifiers are proposals while the document is `draft`.
-
-### ORCH-INV-001: The orchestrator owns cross-stage routing
-
-**Rule:** Entrypoints and stage clients MUST NOT independently forward a
-request to a downstream logical stage.
-
-### ORCH-INV-002: Stage clients do not own routing policy
-
-**Rule:** Stage clients MUST implement communication and lifecycle operations
-without selecting the next logical stage.
-
-### ORCH-INV-100: Terminal state is monotonic
-
-**Rule:** Once a request reaches a terminal state, orchestration MUST NOT
-forward new work for that request.
-
-## Invariant namespace
-
-`ORCH-INV` reserves `001-099` for dependency direction, `100-199` for
-request state and ordering, `200-299` for failure/cancellation/cleanup, and
-`300-399` for extension points, shutdown ordering, and upstream alignment.
-Numbers become append-only after normative promotion.
-
-## Safe-change guide
-
-Test routing, output ordering, queue correlation, cancellation, failure
-propagation, shutdown ordering, and representative multi-stage execution.
-Changes that cross into stage runtime or public error behavior require review
-from that contract's owners.
-
-## Promotion gate
-
-- Reconcile current names and boundaries after #5441 merges, closes, or is
-  replaced.
-- Demonstrate one terminal outcome per request across success, abort,
-  request-scoped failure, and fatal engine failure.
-- Verify queue correlation and orchestrator-before-runtime shutdown ordering
-  in the cited validation paths.
-- Obtain approval from a technical owner and an independent validation
-  reviewer.

docs/design/module/entrypoints.md

@@ -1,134 +0,0 @@
----
-title: Entrypoints and Serving Boundaries
-kind: module
-status: draft
-architecture_state: current-plus-in-flight
-owners:
-  - "@alex-jw-brooks"
-  - "@linyueqian"
-document_stewards:
-  - "@hsliuustc0106"
-  - "@Gaohan123"
-  - "@david6666666"
-required_reviewers:
-  - "@tzhouam"
-  - "@herotai214"
-  - "@yenuo26"
-  - "@NickCao"
-primary_code_paths:
-  - vllm_omni/entrypoints/omni.py
-  - vllm_omni/entrypoints/async_omni.py
-  - vllm_omni/entrypoints/omni_base.py
-  - vllm_omni/entrypoints/cli/**
-  - vllm_omni/entrypoints/openai/**
-  - vllm_omni/entrypoints/openpi/**
-  - vllm_omni/entrypoints/client_request_state.py
-  - vllm_omni/entrypoints/stage_utils.py
-  - vllm_omni/entrypoints/utils.py
-primary_path_exceptions:
-  - path: vllm_omni/entrypoints/openai/errors.py
-    owner: error_contracts.md
-related_code_paths:
-  - vllm_omni/errors.py
-  - vllm_omni/inputs/**
-  - vllm_omni/outputs/**
-  - vllm_omni/engine/async_omni_engine.py
-  - vllm_omni/config/**
-  - vllm_omni/deploy/**
-depends_on:
-  - input_output_modality_contracts.md
-  - error_contracts.md
-  - engine_orchestration.md
-validation_paths:
-  - tests/entrypoints/test_omni_entrypoints.py
-  - tests/entrypoints/test_async_omni.py
-  - tests/entrypoints/test_async_omni_duplex.py
-  - tests/entrypoints/test_serve.py
-  - tests/entrypoints/test_stream_finish_reason.py
-  - tests/entrypoints/openai/**
-  - tests/entrypoints/openai_api/**
-  - tests/e2e/online_serving/**
-upstream_refs:
-  - vllm.engine.protocol.EngineClient
-  - vllm.entrypoints.openai/**
-  - vllm.entrypoints.serve/**
-  - vllm.renderers/**
-  - vllm.v1.engine.exceptions/**
-invariant_namespace: ENTRY-INV
-last_reviewed: 2026-08-07
-last_verified_commit: 3d7fc3b9ba3cac88d579d4dc35b78b0b641675fc
----
-
-# Entrypoints and serving boundaries
-
-Entrypoints translate offline, CLI, and serving requests into stable engine
-operations and translate engine outputs into public responses.
-
-## Contract status
-
-This document describes current entrypoint responsibilities plus the boundary
-under review in the open roadmap
-[#5227](https://github.com/vllm-project/vllm-omni/issues/5227) and helper-move
-PR [#5453](https://github.com/vllm-project/vllm-omni/pull/5453). In-flight
-helper locations are not treated as current paths.
-
-## Ownership boundary
-
-This document owns offline API semantics, CLI and serve composition,
-supported OpenAI-compatible routes, request validation and normalization,
-response conversion, streaming/session behavior, and engine handoff.
-
-It does not own configuration precedence, cross-stage routing, stage
-placement, payload implementation, or semantic error classification.
-`entrypoints/openai/errors.py` is an explicit primary-path exception owned by
-`error_contracts.md`.
-
-## Candidate invariants
-
-These identifiers are proposals while the document is `draft`.
-
-### ENTRY-INV-001: Entrypoints adapt but do not orchestrate
-
-**Rule:** Entrypoints MUST NOT implement cross-stage routing or stage lifecycle
-policy.
-
-### ENTRY-INV-100: Public requests are normalized once
-
-**Rule:** Public protocol values MUST be validated and converted to internal
-request contracts before engine submission.
-
-### ENTRY-INV-101: Streaming preserves request identity
-
-**Rule:** Every streamed response MUST remain associated with the request and
-output modality that produced it.
-
-The reviewer-proposed rule that model-specific behavior should stay behind a
-common adapter or processor abstraction remains an unnumbered candidate until
-the entrypoint refactor makes that boundary enforceable.
-
-## Invariant namespace
-
-`ENTRY-INV` reserves `001-099` for boundary and dependency direction,
-`100-199` for normalization, sessions, and streaming, `200-299` for
-disconnect, cancellation, rendering, and cleanup, and `300-399` for upstream
-route and renderer compatibility. Numbers become append-only after normative
-promotion.
-
-## Safe-change guide
-
-Test request validation, protocol conversion, model-adapter routing,
-streaming, session identity, disconnect/cancellation, and error mapping for
-each affected offline or serving entrypoint.
-
-## Promotion gate
-
-- Reconcile the page after #5227's P0 ownership work and #5453's final
-  disposition.
-- Publish a supported route/transport matrix rather than claiming blanket
-  OpenAI parity.
-- Verify one normalization and handoff path per route family and one terminal
-  outcome per streaming transport.
-- Promote the `api_server.py` composition-root rule only after helper moves and
-  import boundaries enforce it.
-- Obtain approval from a technical owner and an independent validation
-  reviewer.

docs/design/module/error_contracts.md

@@ -1,109 +0,0 @@
----
-title: Error Classification, Propagation, and Rendering
-kind: module
-status: draft
-architecture_state: current-plus-rfc
-owners:
-  - "@alex-jw-brooks"
-  - "@NickCao"
-document_stewards:
-  - "@hsliuustc0106"
-  - "@Gaohan123"
-  - "@david6666666"
-required_reviewers:
-  - "@yinpeiqi"
-  - "@tzhouam"
-  - "@yenuo26"
-primary_code_paths:
-  - vllm_omni/errors.py
-  - vllm_omni/entrypoints/openai/errors.py
-related_code_paths:
-  - vllm_omni/engine/messages.py
-  - vllm_omni/engine/orchestrator.py
-  - vllm_omni/entrypoints/omni_base.py
-  - vllm_omni/entrypoints/async_omni.py
-  - vllm_omni/entrypoints/openai/api_server.py
-  - vllm_omni/entrypoints/openai/serving_chat.py
-  - vllm_omni/entrypoints/openai/serving_speech.py
-  - vllm_omni/entrypoints/openai/serving_audio_generate.py
-  - vllm_omni/entrypoints/openai/protocol/images.py
-  - vllm_omni/entrypoints/openai/protocol/videos.py
-depends_on: []
-validation_paths:
-  - tests/engine/test_orchestrator_error_handling.py
-  - tests/engine/test_async_omni_engine_outputs.py
-  - tests/entrypoints/test_omni_entrypoints.py
-  - tests/entrypoints/test_stream_finish_reason.py
-  - tests/entrypoints/openai_api/test_image_server.py
-  - tests/entrypoints/openai_api/test_video_server.py
-  - tests/entrypoints/openai_api/test_serving_audio_generate.py
-  - tests/entrypoints/openai_api/test_serving_speech.py
-  - tests/metrics/test_prometheus.py
-upstream_refs:
-  - vllm.v1.engine.exceptions.EngineDeadError
-  - vllm.v1.engine.exceptions.EngineGenerateError
-  - vllm.entrypoints.serve.utils.error_response
-  - vLLM RFC #48227
-  - vLLM PR #49665
-invariant_namespace: ERR-INV
-last_reviewed: 2026-08-07
-last_verified_commit: 3d7fc3b9ba3cac88d579d4dc35b78b0b641675fc
----
-
-# Error classification, propagation, and rendering
-
-This contract separates the meaning of a failure from the transport used to
-carry it and the public protocol used to render it.
-
-## Contract status
-
-Current behavior is distributed across engine, message, and entrypoint code.
-The semantic hierarchy proposed by
-[#5570](https://github.com/vllm-project/vllm-omni/issues/5570) remains an open
-RFC. Proposed types and wire records from that RFC are not current contracts.
-
-## Ownership boundary
-
-This document owns semantic classification, fatal versus request-scoped
-failure, cross-process error context, compatibility policy, sanitization, and
-offline, HTTP, SSE, WebSocket, and asynchronous-job rendering rules.
-
-`engine/messages.py` remains primarily owned by the I/O contract; this page
-owns the semantics of its error fields. Route and serving files remain
-primarily owned by `entrypoints.md`; this page owns their rendering
-constraints.
-
-## Candidate invariants
-
-The following topics require owner review before receiving stable IDs:
-
-- A request-scoped failure terminates only the affected request unless the
-  underlying engine is no longer usable.
-- Every public rendering path preserves a stable classification while
-  removing sensitive internal context.
-- Cancellation remains distinguishable from internal failure across process
-  and protocol boundaries.
-
-## Invariant namespace
-
-`ERR-INV` reserves `001-099` for classification ownership, `100-199` for wire
-context and compatibility, `200-299` for fatality, termination, sanitization,
-and rendering, and `300-399` for upstream alignment and transport extension
-points. Numbers become append-only after normative promotion.
-
-## Safe-change guide
-
-Exercise exception classification, stage wire round trips, fatal and
-request-scoped propagation, cancellation, sanitization, offline exceptions,
-HTTP status/body consistency, streaming terminal events, asynchronous-job
-persistence, and metrics classification.
-
-## Promotion gate
-
-- Resolve #5570's hierarchy, wire record, sanitization, and mixed-version
-  questions.
-- Add table-driven exception/status/type tests and stage wire round trips.
-- Verify all public transports terminate once and do not leak sensitive
-  payload data.
-- Obtain approval from both technical owners and an independent validation
-  reviewer.

docs/design/module/execution_platforms.md

@@ -1,48 +0,0 @@
----
-title: Execution Platforms
-kind: module
-status: draft
-owners:
-  - "@gcanlin"
-  - "@tjtanaa"
-  - "@xuechendi"
-primary_code_paths:
-  - vllm_omni/platforms/**
-related_code_paths:
-  - vllm_omni/attention/**
-depends_on:
-  - ar_runtime.md
-  - diffusion/index.md
-validation_paths:
-  - tests/platforms/**
-upstream_refs:
-  - vllm.platforms
-last_reviewed: 2026-07-16
----
-
-# Execution platforms
-
-Execution platforms isolate hardware-specific capability detection, worker
-selection, patches, kernels, and configuration adjustments.
-
-## Candidate invariants
-
-### PLATFORM-INV-001: Capabilities are explicit
-
-**Rule:** Hardware-dependent behavior MUST be guarded by platform selection or
-capability detection and MUST fail clearly when unsupported.
-
-### PLATFORM-INV-002: Portable code remains portable
-
-**Rule:** Platform-neutral modules MUST NOT import a vendor implementation
-directly when a common selection interface exists.
-
-### PLATFORM-INV-003: Overrides are minimal
-
-**Rule:** A platform implementation SHOULD override only behavior that differs
-from the common or upstream implementation.
-
-## Safe-change guide
-
-Validate common import paths without the target accelerator and run focused
-tests in a fresh `uv` environment on every affected device platform.

docs/design/module/input_output_modality_contracts.md

@@ -1,133 +0,0 @@
----
-title: Input, Output, and Modality Contracts
-kind: module
-status: draft
-architecture_state: current
-owners:
-  - "@Sy0307"
-  - "@amy-why-3459"
-document_stewards:
-  - "@hsliuustc0106"
-  - "@Gaohan123"
-  - "@david6666666"
-required_reviewers:
-  - "@tzhouam"
-  - "@linyueqian"
-  - "@david6666666"
-  - "@yenuo26"
-  - "@NickCao"
-primary_code_paths:
-  - vllm_omni/inputs/**
-  - vllm_omni/outputs/**
-  - vllm_omni/request.py
-  - vllm_omni/data_entry_keys.py
-  - vllm_omni/engine/messages.py
-  - vllm_omni/engine/serialization.py
-  - vllm_omni/engine/mm_outputs.py
-  - vllm_omni/engine/output_modality.py
-  - vllm_omni/engine/output_processor.py
-related_code_paths:
-  - vllm_omni/model_executor/stage_input_processors/**
-  - vllm_omni/core/sched/**
-  - vllm_omni/distributed/omni_connectors/**
-  - vllm_omni/diffusion/request.py
-  - vllm_omni/diffusion/worker/request_batch.py
-  - vllm_omni/errors.py
-depends_on:
-  - error_contracts.md
-validation_paths:
-  - tests/inputs/**
-  - tests/engine/test_data_entry_keys.py
-  - tests/engine/test_omni_request.py
-  - tests/engine/test_omni_request_output.py
-  - tests/engine/test_multimodal_accumulation.py
-  - tests/engine/test_output_modality.py
-  - tests/engine/test_output_processor.py
-  - tests/engine/test_wire_multimodal_output.py
-  - tests/utils/test_mm_outputs.py
-  - tests/utils/test_mm_outputs_partition.py
-  - tests/diffusion/test_diffusion_output_metadata.py
-upstream_refs:
-  - vllm.inputs/**
-  - vllm.outputs/**
-  - vllm.v1.request.Request
-  - vllm.v1.engine.EngineCoreRequest
-  - vllm.v1.engine.EngineCoreOutput
-  - vllm.v1.engine.output_processor.OutputProcessor
-invariant_namespace: IO-INV
-last_reviewed: 2026-08-07
-last_verified_commit: 3d7fc3b9ba3cac88d579d4dc35b78b0b641675fc
----
-
-# Input, output, and modality contracts
-
-These contracts define the data that may cross entrypoint, orchestration,
-stage, connector, and model boundaries.
-
-## Contract status
-
-This document is a draft description of the current request, message,
-serialization, modality, accumulation, and output types. It does not assign
-semantic error ownership to the wire schema.
-
-## Ownership boundary
-
-This document owns request identity, prompt/input types, modality keys and
-metadata, queue and wire message schemas, serialization, output types,
-accumulation, completion semantics, and compatibility shims.
-
-It does not own route-specific validation or rendering, model-specific
-interpretation, connector transport mechanics, scheduling policy, or semantic
-error classification. The `ErrorMessage` schema belongs here; the meaning and
-public rendering of its error fields belong to `error_contracts.md`.
-
-## Candidate invariants
-
-These identifiers are proposals while the document is `draft`.
-
-### IO-INV-001: Boundary data has an explicit modality
-
-**Rule:** Data crossing a module or stage boundary MUST identify its modality
-and use the corresponding validated contract.
-
-### IO-INV-100: Request identity is stable
-
-**Rule:** Request identity MUST be preserved across conversions, stages,
-streaming updates, cancellation, and errors.
-
-### IO-INV-101: Completion is explicit
-
-**Rule:** Producers MUST distinguish partial updates from the terminal update
-for every output modality.
-
-### IO-INV-300: Internal objects do not leak into public protocols
-
-**Rule:** Entrypoints MUST explicitly translate internal output objects into
-public response types.
-
-## Invariant namespace
-
-`IO-INV` reserves `001-099` for schema ownership and dependency direction,
-`100-199` for identity, modality, accumulation, ordering, and completion,
-`200-299` for serialization failure and payload cleanup, and `300-399` for
-upstream extension, deprecation, and compatibility. Numbers become
-append-only after normative promotion.
-
-## Safe-change guide
-
-Test construction, validation, serialization, round trips, streaming,
-accumulation, completion, optional fields, unknown fields, and compatibility
-at every affected producer-consumer boundary.
-
-## Promotion gate
-
-- Add explicit CODEOWNERS for the primary I/O paths or confirm that fallback
-  ownership is intentional.
-- Document the compatibility window for deprecated `vllm_omni.engine`
-  I/O-related imports.
-- Verify wire round trips and rejection of unknown or incompatible schema
-  fields.
-- Define payload-versus-metadata rules and completion semantics for streaming
-  and batched outputs.
-- Obtain approval from a technical owner and independent AR, diffusion,
-  connector, entrypoint, and validation reviewers as applicable.

docs/design/module/model_integration.md

@@ -1,51 +0,0 @@
----
-title: Model Integration
-kind: module
-status: draft
-owners:
-  - "@tzhouam"
-  - "@gcanlin"
-primary_code_paths:
-  - vllm_omni/model_executor/**
-  - vllm_omni/model_extras/**
-  - vllm_omni/plugins/**
-related_code_paths:
-  - vllm_omni/transformers_utils/**
-  - vllm_omni/tokenizers/**
-depends_on:
-  - input_output_modality_contracts.md
-  - ar_runtime.md
-validation_paths:
-  - tests/model_executor/**
-  - tests/model_extras/**
-  - tests/plugin/**
-upstream_refs:
-  - vllm.model_executor
-last_reviewed: 2026-07-16
----
-
-# Model integration
-
-Model integration adapts model-specific configuration, preprocessing, loading,
-and execution behavior to stable runtime contracts.
-
-## Candidate invariants
-
-### MODEL-INV-001: Registration is explicit
-
-**Rule:** A model integration MUST declare how its model class, loader, input
-processor, and stage configuration are selected.
-
-### MODEL-INV-002: Model code does not route stages
-
-**Rule:** Model-specific code MUST NOT select or invoke a downstream omni stage.
-
-### MODEL-INV-003: Upstream behavior is reused deliberately
-
-**Rule:** An upstream vLLM implementation SHOULD be reused when its contract is
-sufficient; an override MUST document the behavioral difference.
-
-## Safe-change guide
-
-Test registration, checkpoint loading, input conversion, and representative
-model execution. Test shared utilities against more than one integration.

docs/design/module/observability.md

@@ -1,46 +0,0 @@
----
-title: Observability
-kind: module
-status: draft
-owners:
-  - "@lishunyang12"
-primary_code_paths:
-  - vllm_omni/metrics/**
-related_code_paths:
-  - vllm_omni/engine/**
-  - vllm_omni/entrypoints/**
-depends_on:
-  - engine_orchestration.md
-validation_paths:
-  - tests/metrics/**
-upstream_refs:
-  - vllm.v1.metrics
-last_reviewed: 2026-07-16
----
-
-# Observability
-
-Observability defines stable metrics, logs, and correlation fields for tracing a
-request across entrypoints, orchestration, stages, and workers.
-
-## Candidate invariants
-
-### OBS-INV-001: Request correlation survives stage boundaries
-
-**Rule:** Logs and metrics for the same request SHOULD carry a stable request
-identifier and stage identity.
-
-### OBS-INV-002: Metric meaning is stable
-
-**Rule:** A metric's unit, labels, aggregation, and lifecycle MUST be documented;
-changing any of them is a contract change.
-
-### OBS-INV-003: Labels are bounded
-
-**Rule:** Metrics MUST NOT use request IDs, prompts, outputs, or other unbounded
-values as labels.
-
-## Safe-change guide
-
-Test registration, label sets, units, lifecycle resets, and representative
-multi-stage emission.

docs/design/module/omni_connector.md

@@ -1,50 +0,0 @@
----
-title: OmniConnector
-kind: module
-status: draft
-owners:
-  - "@princepride"
-  - "@yuanheng-zhao"
-  - "@xuechendi"
-  - "@natureofnature"
-  - "@fake0fan"
-primary_code_paths:
-  - vllm_omni/distributed/omni_connectors/**
-related_code_paths:
-  - vllm_omni/platforms/*/omni_connectors/**
-depends_on:
-  - input_output_modality_contracts.md
-  - vllm_omni_config.md
-validation_paths:
-  - tests/distributed/omni_connectors/**
-upstream_refs:
-  - vllm.distributed
-last_reviewed: 2026-07-16
----
-
-# OmniConnector
-
-OmniConnector defines model-agnostic transport and synchronization contracts
-for data exchanged across stages, processes, devices, and nodes.
-
-## Candidate invariants
-
-### CONNECTOR-INV-001: Connectors transport but do not route
-
-**Rule:** A connector MUST NOT select the next stage or implement model-specific
-execution policy.
-
-### CONNECTOR-INV-002: Producer and consumer contracts agree
-
-**Rule:** Both ends MUST agree on data identity, shape, dtype, placement,
-ownership, and completion semantics.
-
-### CONNECTOR-INV-003: Resources have deterministic cleanup
-
-**Rule:** Connections, buffers, handles, and background work MUST be released on
-normal completion, cancellation, failure, and shutdown.
-
-## Safe-change guide
-
-Test setup, transfer, synchronization, timeout, cancellation, failure, and
-cleanup across every affected backend.

docs/design/module/profiling.md

@@ -1,46 +0,0 @@
----
-title: Profiling
-kind: module
-status: draft
-owners:
-  - "@gcanlin"
-primary_code_paths:
-  - vllm_omni/profiler/**
-  - vllm_omni/diffusion/profiler/**
-related_code_paths:
-  - vllm_omni/entrypoints/**
-depends_on:
-  - observability.md
-validation_paths:
-  - tests/profile/**
-upstream_refs:
-  - vllm.profiler
-last_reviewed: 2026-07-16
----
-
-# Profiling
-
-Profiling owns opt-in instrumentation and trace collection used to locate
-runtime bottlenecks without changing model results or execution policy.
-
-## Candidate invariants
-
-### PROFILE-INV-001: Profiling is opt-in
-
-**Rule:** Expensive trace collection MUST be disabled by default and bounded by
-an explicit start and stop lifecycle.
-
-### PROFILE-INV-002: Instrumentation preserves semantics
-
-**Rule:** Profiling MUST NOT change scheduling decisions, generated outputs, or
-resource ownership beyond documented synchronization overhead.
-
-### PROFILE-INV-003: Trace context is sufficient
-
-**Rule:** Trace events SHOULD identify stage, rank, worker, operation, and
-request where available without embedding user payloads.
-
-## Safe-change guide
-
-Test disabled overhead, repeated start and stop, cleanup, multi-rank trace
-naming, and each supported profiler backend.

docs/design/module/quantization.md

@@ -1,50 +0,0 @@
----
-title: Quantization
-kind: module
-status: draft
-owners:
-  - "@david6666666"
-  - "@Isotr0py"
-  - "@lishunyang12"
-primary_code_paths:
-  - vllm_omni/quantization/**
-  - vllm_omni/diffusion/quantization/**
-related_code_paths:
-  - vllm_omni/platforms/*/quant/**
-depends_on:
-  - model_integration.md
-  - diffusion/diffusion_model_integration.md
-validation_paths:
-  - tests/quantization/**
-  - tests/diffusion/quantization/**
-upstream_refs:
-  - vllm.model_executor.layers.quantization
-last_reviewed: 2026-07-16
----
-
-# Quantization
-
-Quantization owns method registration, checkpoint interpretation, layer
-replacement, and runtime constraints for reduced-precision execution.
-
-## Candidate invariants
-
-### QUANT-INV-001: Checkpoint and runtime methods agree
-
-**Rule:** The selected method MUST validate checkpoint metadata, supported
-layers, device capabilities, and required dependencies before use.
-
-### QUANT-INV-002: Unsupported combinations fail clearly
-
-**Rule:** Quantization MUST NOT silently fall back to a different precision or
-method when a requested combination is unsupported.
-
-### QUANT-INV-003: Numerical validation is required
-
-**Rule:** A new method or layer mapping MUST include correctness comparison
-against a defined reference result.
-
-## Safe-change guide
-
-Test loading, representative layers, metadata, platform guards, and numerical
-tolerances separately from performance.

docs/design/module/stage_runtime.md

@@ -1,126 +0,0 @@
----
-title: Stage Runtime and Replica Lifecycle
-kind: module
-status: draft
-architecture_state: current-plus-in-flight
-owners:
-  - "@tzhouam"
-  - "@fake0fan"
-document_stewards:
-  - "@hsliuustc0106"
-  - "@Gaohan123"
-  - "@david6666666"
-required_reviewers:
-  - "@Sy0307"
-  - "@princepride"
-  - "@chickeyton"
-  - "@yenuo26"
-  - "@NickCao"
-primary_code_paths:
-  - vllm_omni/engine/stage_runtime.py
-  - vllm_omni/engine/stage_pool.py
-  - vllm_omni/engine/stage_client.py
-  - vllm_omni/engine/membership_controller.py
-  - vllm_omni/engine/stage_engine_startup.py
-  - vllm_omni/engine/stage_engine_core_client.py
-  - vllm_omni/engine/stage_engine_core_proc.py
-  - vllm_omni/engine/stage_engine_core_proc_manager.py
-  - vllm_omni/engine/stage_init_utils.py
-related_code_paths:
-  - vllm_omni/distributed/omni_coordinator/**
-  - vllm_omni/distributed/ray_utils/**
-  - vllm_omni/diffusion/inline_stage_diffusion_client.py
-  - vllm_omni/diffusion/stage_diffusion_client.py
-  - vllm_omni/diffusion/stage_diffusion_proc.py
-  - vllm_omni/config/**
-depends_on:
-  - input_output_modality_contracts.md
-  - error_contracts.md
-  - omni_connector.md
-validation_paths:
-  - tests/engine/test_async_omni_engine_stage_init.py
-  - tests/engine/test_membership_controller.py
-  - tests/engine/test_single_stage_mode.py
-  - tests/engine/test_stage_engine_core_client.py
-  - tests/engine/test_stage_engine_core_proc.py
-  - tests/diffusion/test_inline_stage_diffusion_client.py
-  - tests/diffusion/test_stage_diffusion_proc.py
-  - tests/distributed/omni_coordinator/**
-upstream_refs:
-  - vllm.v1.engine.core_client.AsyncMPClient
-  - vllm.v1.engine.core_client.DPLBAsyncMPClient
-  - vllm.v1.engine.core.EngineCoreProc
-  - vllm.v1.engine.utils.CoreEngineProcManager
-  - vllm.v1.engine.coordinator.DPCoordinator
-invariant_namespace: STAGE-INV
-last_reviewed: 2026-08-07
-last_verified_commit: 3d7fc3b9ba3cac88d579d4dc35b78b0b641675fc
----
-
-# Stage runtime and replica lifecycle
-
-The stage runtime turns a logical stage definition into ready local or
-distributed replicas and provides the lifecycle boundary used by the
-orchestrator.
-
-## Contract status
-
-This document describes the current `StageRuntime`, `StagePool`, stage-client,
-and stage-process layout. The unified LLM/diffusion direction in
-[#5441](https://github.com/vllm-project/vllm-omni/pull/5441) remains in flight
-and is not presented as current behavior.
-
-## Ownership boundary
-
-This document owns local and distributed stage placement, startup and
-readiness, one pool per logical stage, replica identity and membership,
-selection and affinity, stage-client/process lifecycle, liveness, draining,
-and shutdown.
-
-It does not own cross-stage request policy, model scheduler policy, connector
-transfer semantics, configuration precedence, or public error rendering.
-
-## Candidate invariants
-
-These identifiers are proposals while the document is `draft`.
-
-### STAGE-INV-001: The runtime owns replica lifecycle
-
-**Rule:** Orchestration MUST acquire stage capacity through the stage runtime
-and MUST NOT construct or retire backend replicas directly.
-
-### STAGE-INV-100: Affinity uses stable replica identity
-
-**Rule:** Follow-up operations for a request with replica affinity MUST resolve
-the same logical replica until the request terminates or the replica is
-declared lost.
-
-### STAGE-INV-200: Shutdown is idempotent
-
-**Rule:** Repeated shutdown or cleanup signals MUST NOT leak stage clients,
-process managers, or membership registrations.
-
-## Invariant namespace
-
-`STAGE-INV` reserves `001-099` for placement and ownership, `100-199` for
-replica identity/readiness/affinity, `200-299` for liveness loss, draining and
-cleanup, and `300-399` for local/distributed and upstream compatibility.
-Numbers become append-only after normative promotion.
-
-## Safe-change guide
-
-Exercise local and distributed startup, readiness, replica selection,
-affinity, membership changes, abort routing, process failure, draining, and
-repeated shutdown. Cross-stage policy changes belong in
-`engine_orchestration.md`.
-
-## Promotion gate
-
-- Reconcile terminology and ownership after #5441 reaches a final state.
-- Add or identify a dedicated StageRuntime/StagePool lifecycle suite; current
-  evidence is distributed across the cited tests.
-- Demonstrate affinity preservation for update, interaction, and abort paths.
-- Demonstrate membership loss and repeated shutdown without leaked clients or
-  processes.
-- Obtain approval from a technical owner and an independent validation
-  reviewer.

docs/design/module/vllm_omni_config.md

@@ -1,56 +0,0 @@
----
-title: vLLM-Omni Configuration
-kind: module
-status: draft
-architecture_state: deferred-pending-refactor
-ownership_status: provisional
-owners:
-  - "@lishunyang12"
-  - "@alex-jw-brooks"
-primary_code_paths:
-  - vllm_omni/config/**
-  - vllm_omni/deploy/**
-  - vllm_omni/model_executor/stage_configs/**
-related_code_paths:
-  - vllm_omni/platforms/*/stage_configs/**
-depends_on: []
-validation_paths:
-  - tests/config/**
-upstream_refs:
-  - vllm.config
-last_reviewed: 2026-08-07
-last_verified_commit: 3d7fc3b9ba3cac88d579d4dc35b78b0b641675fc
----
-
-# vLLM-Omni configuration
-
-This page intentionally records discovery paths only. Substantive
-configuration ownership and contract work is deferred until the active
-configuration refactoring has settled.
-
-## Deferred contract scope
-
-The current code and tests remain authoritative for parsing, defaults,
-overrides, deployment topology, stage construction, and runtime projection.
-This draft does not define a stable precedence model, environment-variable
-capture rule, canonical configuration object, or invariant namespace.
-
-The PR review proposal to capture environment-derived values in configuration
-objects at initialization is an open design question, not a current
-invariant.
-
-## Safe-change guide while deferred
-
-Changes should trace every affected producer to its runtime consumer and test
-the structured, legacy, CLI, and deployment paths that are actually supported.
-Do not infer a stable contract from this placeholder page.
-
-## Promotion gate
-
-- Finish or stabilize the configuration refactor and identify the canonical
-  runtime configuration representation.
-- Confirm technical owners, primary path exceptions, and validation owners.
-- Document parsing and override precedence, including when environment values
-  are captured.
-- Allocate an invariant namespace only after those behaviors are enforced and
-  owner-approved.

docs/features/session_state_manager.md

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

docs/getting_started/quickstart.md

@@ -87,8 +87,9 @@ if __name__ == "__main__":
 
 !!! info
 
-    For diffusion request batching, step execution, and streaming controls, see
+    For diffusion request-level batching controls such as `max_num_seqs` and
-    [Diffusion Execution Modes](../user_guide/diffusion/execution_modes.md).
+    `request_batch_max_wait_ms`, see
+    [Request-Level Batching](../user_guide/diffusion/request_batching.md).
 
 For more usages, please refer to [offline inference](../user_guide/examples/offline_inference/qwen2_5_omni.md)
 

docs/mkdocs/hooks/generate_argparse.py

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

docs/mkdocs/hooks/generate_examples.py

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

docs/models/supported_models.md

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