Deployment¶

Install and inspect¶

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

The default topology output keeps GPU model, count, memory and relationship class while redacting PCI bus identifiers. --include-identifiers is for local diagnosis only and must not be pasted into public benchmark records.

Choose the topology¶

Goal	Preferred topology	Measured boundary
lowest latency for one 768p request	one RTX 4090	188.474 s with Sage2 on the controlled Ref Turbo4 case
fit and run on one 20 GB card	one RTX 3080	feasible at 17.9 GiB peak; 353.502 s with Sage2
reduce one request on available 3080s	TP2 RTX 3080	269.621 s; 78.3% parallel efficiency without NVLink
generate multiple candidates	independent workers	two 4090 workers observed 1.893× batch concurrency
15 s rough preview on 20 GB	one RTX 3080, native 124 frames then 8 fps conform	197.542 s warm delivery

The first three rows are single-request latency choices. Replica concurrency is a throughput result and must not be presented as a latency speedup.

One-shot CLI¶

vflash run \
  --model-path /models/minimax-h3 \
  --config configs/h3/turbo4-768p-bf16.json \
  --task t2av \
  --prompt-file prompts/shot.txt \
  --output outputs/shot.mp4 \
  --gpu-devices 0

Tensor-parallel Ref2VA uses two explicitly selected devices:

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/shot.mp4 \
  --gpu-devices 0,1 \
  --world-size 2 \
  --parallel-mode tp

Arguments are passed as an argv vector; prompt text is never evaluated by a shell.

Docker resident API¶

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

The image clones the exact LightX2V revision and applies checked patches, but it does not copy model weights into an image layer. Mount weights at runtime after accepting their license. The worker exposes synchronous and asynchronous video routes and keeps one resident pipeline. A fatal CUDA or OOM event makes readiness fail until restart.

Reproducibility checklist¶

• Pin the Vflash and LightX2V commits.
• Record model revision and profile JSON.
• Record GPU model/count and topology class, never UUID in public data.
• Separate cold initialization, warm generation and post-processing.
• Fix prompt, references, seed, canvas, frame count, fps, NFE and flow shifts.
• Label concurrent runs as contended throughput evidence.
• Probe the final MP4 for frame count, duration, video codec and audio stream.