[Refactor] Unify the LTX-2 and LTX-2.3 pipeline runtime

[mglyn]

Purpose

This PR consolidates the duplicated LTX-2 and LTX-2.3 implementations into a shared runtime while preserving each version's existing numerical behavior and public registry keys and package-level exports.

User-facing invocation is unchanged: LTX2Pipeline, LTX2ImageToVideoPipeline, LTX23Pipeline, and LTX23ImageToVideoPipeline remain the --model-class-name and registry entry names. The refactor only consolidates their internal module ownership under the shared LTX runtime; Python callers should use package-level imports such as from vllm_omni.diffusion.models.ltx2 import LTX23Pipeline rather than import the former implementation modules directly.

Follow-up guidance, official-precision alignment, two-stage/HQ support, and subsequent LTX runtime work are tracked continuously in #4985.

The previous implementation maintained separate T2V/I2V pipelines for each model version, including duplicated request parsing, prompt conditioning, latent preparation, denoising, decoding, and output handling. That made fixes and runtime features easy to apply to one variant but miss on another.

The new structure provides:

• shared component profiles and component discovery for LTX-2/LTX-2.3;
• shared request parsing, prompt conditioning, AV latent operations, phase execution, denoising, decoding, and request-batch output splitting;
• one common one-stage forward template with thin LTX-2/LTX-2.3 T2V/I2V public entry classes;
• preservation of the existing distilled-only LTX-2 two-stage compatibility path, with its two denoise phases reusing the shared phase runtime and prompt context;
• version-specific guidance and scheduler policies where floating-point order or existing behavior still differs;
• the same request batching, TP/SP/CFG parallel, HSDP, compile, offload, and distributed VAE decode contracts across the applicable one-stage LTX entries;
• updated LTX-2.3 documentation to use the official diffusers/LTX-2.3-Diffusers checkpoint.

Test Plan

• Run the consolidated LTX unit suite.
• Run adjacent DMD2, pipeline-registry, and Diffusers-loader regressions.
• Run an end-to-end feature smoke on 4x NVIDIA A100 80GB across:
  • LTX-2 one-stage T2V/I2V;
  • LTX-2.3 one-stage T2V/I2V;
  • eager, compile, Cache-DiT, CFG parallel, Ulysses, Ring, TP, HSDP, combined parallelism, VAE patch decode, layerwise offload, and request batching.
• Run base eager E2E compatibility smokes for the existing distilled-only LTX-2 two-stage T2V/I2V entries. Full two-stage feature integration is deferred to the dedicated two-stage implementation.

vLLM Version: 0.24.0

vLLM-Omni Commit: 807e006c55d40d87f323c4930723f0ab4a1fa8f7

Test Result

tests/diffusion/models/ltx2: 69 passed
LTX + DMD2 + pipeline registry + Diffusers loader: 203 passed
changed-file pre-commit: passed
git diff --check: passed

Unit-test consolidation

Tests now follow shared LTX responsibilities rather than duplicating a test
tree for each model version.

Metric	Before consolidation	Consolidation commit	Current HEAD
Test files	8	6	6
Test LOC	1,923	1,777	1,915
Pytest collected cases	66	55	69

The consolidation removed 10 import/inheritance/layout assertions and one duplicate latent-padding case. Current HEAD then added 14 collected cases for shared request batching, every public post-process entry, distributed decode, LTX-2/LTX-2.3 parity, and two-stage phase compatibility.

Previous file	Previous cases	Consolidated target	Treatment
test_ltx2_shared_pipeline.py	8	test_ltx2_pipeline.py	Merged shared runtime/phase contracts; removed the old file
test_ltx2_3_pipeline.py	26	test_ltx2_pipeline.py, test_ltx2_latents.py	Kept behavioral coverage; moved five latent cases; removed six layout-only assertions
test_ltx2_3_image2video_pipeline.py	11	test_ltx2_conditioning.py	Kept eight I2V behavior cases; removed three import/export assertions
test_ltx2_3_forward_parallel.py	9	test_ltx2_parallel.py, test_ltx2_transformer.py	Kept CFG behavior and moved transformer capability coverage
test_ltx2_cfg_parallel_adaptation.py	2	test_ltx2_latents.py	Kept unpadding; deduplicated the identical padding case
test_ltx2_3_vae_tiling.py	7	test_ltx2_vae.py	Preserved all distributed VAE behavior under the family-level file
test_ltx2_hsdp.py	1	test_ltx2_transformer.py	Moved the HSDP transformer contract; removed the old file
test_ltx2_transformer.py	2	test_ltx2_transformer.py	Preserved and extended transformer capability coverage

Commands:

python -m pytest tests/diffusion/models/ltx2 -q

python -m pytest -q \
  tests/diffusion/models/ltx2 \
  tests/diffusion/models/dmd2/test_dmd2_request_sanitization.py \
  tests/diffusion/models/dmd2/test_dmd2_scheduler.py \
  tests/config/test_pipeline_registry.py \
  tests/diffusion/model_loader/test_diffusers_loader.py

4x A100 80GB family feature sweep

Configuration:

• one-stage shape: 512x384, 25 frames;
• 3 denoise steps and 3 saved requests per cell;
• no benchmark warmup request;
• four GPUs for Ulysses, Ring, TP, HSDP, TP2+Ulysses2,
  HSDP4+Ulysses4, and TP4+VAE-patch4;
• CFG remains two-way because the current LTX CFG path has positive/negative
  branches only.

Mean stage_0_gen_ms per request:

Feature	LTX-2 T2V (ms)	LTX-2 I2V (ms)	LTX-2.3 T2V (ms)	LTX-2.3 I2V (ms)
Base eager	7,568.7	7,777.2	6,649.5	7,125.3
torch.compile	7,102.8	7,182.6	15,253.0	16,108.5
Cache-DiT	6,049.0	5,983.4	6,796.6	7,226.1
CFG parallel 2	4,303.7	4,574.6	4,703.3	4,980.7
Ulysses 4	9,481.1	9,598.8	5,995.1	6,127.0
Ring 4	13,819.6	13,929.5	7,824.1	7,990.3
TP 4	9,995.3	10,318.7	5,918.3	6,203.9
HSDP shard 4	14,571.7	14,702.9	9,946.0	10,207.0
TP 2 + Ulysses 2	12,381.9	12,548.0	7,367.9	7,584.0
HSDP 4 + Ulysses 4	17,395.2	17,569.5	9,996.0	10,338.1
TP 4 + VAE patch 4	9,932.5	10,138.0	5,990.7	6,232.4
Layerwise offload	30,424.7	30,642.6	15,823.5	16,003.7
Request batch 2	11,756.9	12,395.4	11,741.3	13,199.6

Every cell completed all three requests and saved three videos. Compile cells
include first-request compilation because this smoke intentionally uses no
benchmark warmup.

Legacy LTX-2 distilled two-stage compatibility smoke

This PR preserves the pre-existing LTX-2 two-stage behavior: it accepts only a componentized distilled checkpoint and runs the existing latent-upsample flow. It does not claim general dev+LoRA, LTX-2.3, HQ, or two-stage feature-backend support. Those capabilities and their full feature matrix are deferred to the dedicated two-stage implementation.

Completed on one NVIDIA L20 with eager execution and layerwise offload. Both entries use the componentized distilled checkpoint, 256x192 input, 25 frames, and x2 spatial latent upsample to 512x384.

Entry	Result	Generation time
LTX-2 two-stage T2V	PASS	35.20 s
LTX-2 two-stage I2V	PASS	34.66 s

ltx23_i2v_cfg_only512x768.mp4

[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.

[mglyn]

@TaffyOfficial @lishunyang12 please take a look. And also take a look at this #5148

[david6666666]

LGTM now