[skip ci][Misc] LVSA showcase (training-free block-sparse attention)

[gglorian]

What

A self-contained showcase app for LVSA (Long-Video Sparse Attention) on vLLM-Omni. LVSA is a training-free, drop-in sparse-attention path for video diffusion transformers, each query frame attends to a few global anchors + a local window instead of full O(N²), so long-video generation gets much faster at competitive quality, with no fine-tuning and no changes to vLLM-Omni core. Plugs in via the public vllm_omni.general_plugins entry point, enabled per-server with LVSA_* env vars. Pairs with #3115.

Results (published, single A100 80 GB, 50 steps)

Model	Horizon	Dense	LVSA	Speedup
HunyuanVideo 1.5	1×	2476 s	932 s	2.66×
HunyuanVideo 1.5	1.5×	5191 s	1361 s	3.81×
HunyuanVideo 1.5	2×	OOM	1617 s	capability
Wan 2.1-1.3B	4×	1610 s	700 s	2.30×
Wan 2.1-1.3B	6×	3369 s	1072 s	3.14×

Plus a Wan-14B 4× dense vs LVSA-SDPA vs LVSA-FlashInfer side-by-side in assets/.

Scope

• Models: Wan 2.1 (1.3B/14B) and HunyuanVideo 1.5 — both stable, 480p-native.
• serve_lvsa.sh (sets plugin env) + generate.py (async /v1/videos client).
• Requires a CUDA-13-capable driver (≥580) or Docker on a data-center GPU.

LVSA is Apache-2.0; uses vLLM-Omni's standard serving API and modifies nothing in core.

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

[gglorian]

Thanks for the feedback during the vLLM-Omni community meeting, we have pushed the requested changes:

Changes

• Removed requirements.txt. The single runtime dependency (requests) and the vLLM-Omni 0.22.0 version pairing are now explained in prose in the README.md quickstart instead.
• Slimmed the README.md (~147 → ~78 lines): dropped the duplicated env-var/config table and the second benchmark table, linking instead to the upstream LVSA repo for the living reference (env vars, multi-GPU support, tuning). Keeps a single source of truth for content that evolves.
• serve_lvsa.sh now enables LVSA purely via the attention backend (--diffusion-attention-config), dropping the LVSA_*_HOOK env vars. The backend engages under tensor-parallel too, whereas the hook path falls back to dense under sequence-parallel — verified end-to-end (server log shows [LVSA] Geometry detected … -> SPARSE and produces the video).
• Pinned vLLM-Omni to the stable v0.22.0 (was v0.22.0rc1).

The app stays a thin, plugin-only showcase (serve_lvsa.sh + generate.py) with no changes to vLLM-Omni core.

Visual result

Here is a dense-vs-LVSA comparison on Wan 2.2 14B at 4× the training horizon (321 frames, single A100). Beyond its training length, dense attention degrades into looping/static output; LVSA's rotating-keyframe pattern keeps coherent motion — at ~2.4× the speed:

Dense (base):

plugin__wan14b__dense__4x__dog_forest.mp4

LVSA:

plugin__wan14b__flashinfer__4x__dog_forest.mp4

Across the full sweep (5 prompts × 6 horizons, scored with VQeval + VBench-Long), LVSA runs ~1.4× faster at 2× → up to 3.5× at 6× (Wan 1.3B), with quality improving at extension — for this clip, VQeval composite 63.8 → 67.3 and loop-quality 45 → 65. Full numbers and methodology live in the upstream repo's benchmarks/.

@zzhang-fr @Gaohan123 @gcanlin

[zzhang-fr]

@Gaohan123 @hsliuustc0106 could you please review this PR, thanks!

[hsliuustc0106]

This installs the plugin without FlashInfer, but the script defaults to LVSA_BACKEND=flashinfer and the README reports LVSA-FlashInfer results. Please install the FlashInfer wheels here or default the script/docs to SDPA.

[hsliuustc0106]

The backend path logs [LVSA] Geometry detected, not [LVSA] engaged. This verification hint should match the path this script enables.

[gglorian]

Thanks @hsliuustc0106 — both good catches, fixed.

1. FlashInfer install (README). Worth flagging, but FlashInfer is actually already present after the quickstart: vllm==0.22.0 pins flashinfer-python==0.6.11.post2 + flashinfer-cubin==0.6.11.post2 as hard dependencies, so step 1 installs them and the default flashinfer backend works out of the box (the LVSA backend only needs flashinfer.BlockSparseAttentionWrapper). I've added a note to the README making that explicit, plus an optional JIT-cache step (faster startup) and an LVSA_BACKEND=sdpa fallback for environments without FlashInfer. If you hit an actual runtime failure (rather than inferring it from the missing install line), send the error — that'd be a different issue (e.g. a CUDA/cubin mismatch) and I'll dig in.

2. [LVSA] engaged → [LVSA] Geometry detected. Correct. This script enables the backend path, which logs [LVSA] Geometry detected:; [LVSA] engaged is only emitted by the hook path, which the script deliberately doesn't use. Fixed — the same stale hint was also in the header comment (line 6), so I corrected both occurrences.

While here I self-audited the rest of the showcase against our sweep data and tightened a few things: corrected the Wan-1.3B loop-quality range (≥3× is ~+27 to +34), scoped the dense-OOM note to the specific models that actually OOM (HunyuanVideo ≥2×, Wan2.1-14B and Cosmos at 6× — Wan-1.3B itself runs dense fine at 6×, as the speedup row implies), and fixed two stale comments in serve_lvsa.sh (activation is via --diffusion-attention-config; DIFFUSION_ATTENTION_BACKEND is a precedence fallback, not removed). Update pushed.

[hsliuustc0106]

lgtm