Vflash

Vflash turns measured video-model inference optimizations into a clean, reproducible runtime for other teams. It separates reusable inference, benchmarking, and Docker deployment from the product UI, backend, machine inventory, and private experiment history that produced the results.

The first runtime targets MiniMax H3 on a pinned LightX2V revision and provides:

• one-shot T2VA, I2VA, L2VA, FL2VA, and Ref2VA inference;
• a resident HTTP worker for single-GPU production;
• explicit single-GPU and TP2 launch contracts;
• measured BF16, SageAttention2, strict Triton RoPE, Base24/40/50, and request-scoped Cache-DiT profiles;
• public-safe NVIDIA topology snapshots and reproducible Docker deployment.

Measured headline results for the same 1344×768, 124-frame, Ref Turbo4 contract:

Hardware	Generation	Relative to one 3080
RTX 3080 20 GB, one GPU, FA3	422.366 s	1.000×
RTX 3080 20 GB, TP2, FA3	269.621 s	1.567×
RTX 4090 48 GB, one GPU, FA3	210.669 s	2.005×
RTX 4090 48 GB, one GPU, Sage2	188.474 s	2.241×

One 3080 also completed the historical 15-second, 8 fps preview contract in 197.542 s warm or 277.830 s cold. See the full measured catalog for workload, topology, quality and rejected-route boundaries.

Work in progress: most Base24/40/50, cache, quantization, TP2, and operator-level quality evidence currently comes from Ref2VA. T2VA and FL2VA have production Turbo measurements, but not yet the same optimization depth. The primary eight-case matrix therefore remains Ref2VA-only. T2VA and FL2VA are separate next-step qualification tracks that will apply the same native-vs-LightX2V-vs-Vflash, single-3080/TP2/4090 speed-and-quality protocol before either mode can join a future primary leaderboard. Ref2VA results are not silently generalized to T2VA or FL2VA.

Code is Apache-2.0; model weights are never bundled in this Git repository and retain their own upstream terms. Read MODEL-LICENSES.md before downloading, serving, quantizing, or redistributing a model. A separately hosted, experimental H3 Ref2VA INT8-SGL component is published on Hugging Face. Its verified payload is 34,023,112,968 bytes with SHA-256 d10f8b6e6bf93bf1a76a7160901568be6394d6f7e4e26ed4a1a20bba03c6f246; BF16 remains the quality-master path.

Documentation and examples

The GitHub Pages site explains why LightX2V is fast, deployment choices, bottlenecks, 30 measured optimization routes and the quality protocol.

Curated example	What it shows	View policy
Official T2VA	reproducible 768p text-to-audio-video	official source link
Official FL2VA	first/last-frame control	official source link
Official Ref2VA	multimodal identity and dialogue	official source link
Community road movie	15-second cinematic consistency	creator source link
Community animation study	style breadth and audio	creator source link
Raw / skill / Qwen3.8 A/B	same-seed prompt-treatment test	metrics and prompts public; video withheld

The repository never mirrors those third-party videos. Large rights-cleared media is designed to live in a versioned Hugging Face video Dataset, while Git contains only a validated manifest and optional small owned previews. Current locally generated H3 samples are not uploaded because the model license restricts global display of Outputs; the measured result was three blind ties, not a demonstrated Qwen/skill quality gain.

Quick start

Create a local environment for validation and command construction:

python -m venv .venv
.venv/bin/pip install -e '.[dev,runtime]'
.venv/bin/vflash --version
.venv/bin/vflash topology

vflash topology redacts PCI identifiers by default so its JSON can be used in public benchmark records. --include-identifiers is only for local diagnosis.

Validate a single-GPU request without loading H3:

.venv/bin/vflash run \
  --model-path /models/minimax-h3 \
  --config configs/h3/turbo4-768p-bf16.json \
  --task t2av \
  --prompt 'A cinematic fox walks through fresh snow.' \
  --output outputs/fox.mp4 \
  --gpu-devices 0 \
  --dry-run

Remove --dry-run inside a LightX2V environment after mounting accepted H3 weights and the Turbo LoRA under /models. Vflash passes arguments directly to the process; prompts are never evaluated by a shell.

For the measured two-GPU tensor-parallel Ref2VA contract:

.venv/bin/vflash run \
  --model-path /models/minimax-h3 \
  --config configs/h3/ref-turbo4-768p-bf16-tp2.json \
  --task ref2av \
  --prompt-file prompts/shot.txt \
  --image references/subject.png \
  --output outputs/ref.mp4 \
  --gpu-devices 0,1 \
  --world-size 2 \
  --parallel-mode tp

Use --prompt-file for long structured H3 prompts so shell history contains only a path; --prompt is convenient for short smoke tests.

Docker API

The image fetches the exact LightX2V revision in configs/upstreams.toml, checks and applies the qualified H3 patches, then installs Vflash without copying model weights into an image layer.

docker compose -f docker/compose.yaml build h3-api
VFLASH_MODEL_DIR=/models \
VFLASH_GPU_DEVICES=0 \
docker compose -f docker/compose.yaml up h3-api
curl --fail http://127.0.0.1:8000/health

The HTTP worker serializes requests on one resident pipeline and exposes POST /v1/videos, POST /v1/videos/sync, status, content, and deletion routes. Reference profiles use the same image with explicit VFLASH_PARTITION, config, canvas, NFE, and flow-shift environment values. A fatal CUDA/OOM state fails closed so a container restart can rebuild the resident pipeline.

Profiles

Profile	Contract	Status
turbo4-768p-bf16	T2VA/FL2VA, 1344×768, 4 NFE	production
ref-turbo4-544p-bf16	Ref2VA, up to 960×544, 4 NFE	production
ref-turbo4-768p-bf16-tp2	Ref2VA, 1344×768, TP2, 4 NFE	measured
ref-base24-544p-bf16	Ref2VA, 24 NFE	fast quality tradeoff
ref-base40-544p-bf16	Ref2VA, 40 NFE	balanced baseline
ref-base50-544p-bf16	Ref2VA, 50 NFE	full baseline
ref-base40-int8-hybrid-544p	selective BF16 overlay on INT8	experimental

The experimental profile is intentionally outside configs/h3. Full global INT8 was faster but failed motion/audio qualification; Vflash does not present it as a default.

Development

.venv/bin/pre-commit install
.venv/bin/pre-commit run --all-files
.venv/bin/pytest
.venv/bin/vflash validate-catalog --root .
.venv/bin/python scripts/render_catalog_docs.py --check
npm ci
npm run docs:build

No secret, model payload, generated media, user prompt, machine UUID, or raw experiment directory belongs in this repository. Rights-cleared comparison videos will be versioned outside Git and referenced by a public manifest.