From ef87116f64a0b1a1eb29f291a148cc9410d4c0c8 Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Sun, 9 Aug 2026 14:01:19 +0000 Subject: [PATCH] =?UTF-8?q?docs(usage):=20the=20H3=20recipe=20that=20actua?= =?UTF-8?q?lly=20renders=20=E2=80=94=20required=20--partition,=20the=20tas?= =?UTF-8?q?k=20trap,=20and=20what=20is=20verified?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three defects, all of which cost a real render to discover. 1. THE DOCUMENTED COMMAND NO LONGER RUNS. `--partition` became REQUIRED when the task/partition guard landed (#84, mirroring upstream's `_resolve_task` raise); the worked example predates it and fails at the CLI. Added, and called out as required. 2. THE TRAP WAS UNDOCUMENTED. `MiniMax-H3-FL2VA-Q4_K_M.gguf` — the file this doc tells people to download — is the FL2VA partition and serves t2va + fl2va, NOT ref2va. Yet `--ref-image ... (ref2va)` sat in the options list directly beneath it with no warning. The mismatch does not fail loudly: it RENDERS, and the render carries a coloured lattice that gets worse with canvas size. Measured on one prompt/canvas as a period-16 seam ratio (1.15 == clean): ref2va-on-FL2VA 2.28, t2va 1.19. At 864x480 the same mismatch reads 1.15 and looks fine, which is why it survives casual testing and only bites at the resolution you want. 3. VERIFIED vs MERELY AVAILABLE was not distinguished. Added a status table: Q4_K_M verified end to end; Q3_K_M verified bad; bf16 loader + streamer implemented but CPU-ONLY verification, no e2e GPU render; NVFP4 exists with non-drop-in pruned variants; no Q8 GGUF known or tested. A render costs hours before it tells you anything, so "exists" and "works" must not read alike. Also records the recipe every render in the doc was produced with (Q4_K_M DiT + encoder, --dequant-bf16, t2va, 1344x768, 124 frames, 50 steps) and its cost: ~176 s/step at that canvas (~2.5 h for 50 steps plus ~30 min load), against ~15 s/step at 512x512 (~13 min) for prompt iteration. FOLLOWING_AGENTS_PROTOCOL Assisted-by: Claude Code:claude-opus-5 [ClaudeCode] --- docs/USAGE.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 57 insertions(+), 2 deletions(-) diff --git a/docs/USAGE.md b/docs/USAGE.md index c750bccf..6701b543 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -197,6 +197,47 @@ Higher-precision arms that exist but are not the default: NVFP4 note the pruned variants restructure AdaLN into a timestep lookup table and are NOT drop-in), and the original bf16 weights under `FL2VA/transformer/`. +**What is actually verified, and what merely exists.** The distinction matters +because a render takes hours before it tells you anything: + +| arm | status | +|---|---| +| **Q4_K_M** | **VERIFIED end to end** — every render in this doc. Use this. | +| Q3_K_M | verified BAD (the A/B above): murky silhouette under a lattice | +| bf16 (66.3 GB, 13 shards) | loader + device streamer implemented and gated, but **CPU-only** verification — no end-to-end GPU render has been done | +| NVFP4 | exists; pruned variants are NOT drop-in (see above) | +| Q8 | no published GGUF is known and none has been tested | + +### The trap: this checkpoint does not serve every task + +**`MiniMax-H3-FL2VA-Q4_K_M.gguf` is the FL2VA partition. It serves `t2va` and +`fl2va` — NOT `ref2va`.** H3 ships two independently-served DiT partitions and +the task must match the one you loaded; upstream's `_resolve_task` raises on the +mismatch. + +Pass a reference image against this file and you get a task/partition mismatch. +It does not fail loudly — it renders, and the render is *wrong*: a coloured +diagonal lattice over the whole frame, worse the larger the canvas. Measured on +one prompt and canvas (1344x768 / 124f), as a period-16 seam ratio where 1.15 is +clean: + +| configuration | seam ratio | +|---|---| +| ref2va against FL2VA (the mismatch) | 2.28 | +| t2va against FL2VA (correct) | **1.19** | + +The small-canvas case is what makes this expensive to spot: at 864x480 the same +mismatch measures 1.15 and looks acceptable, so the bug only becomes obvious at +the resolution you actually want. + +Pass `--partition fl2va` explicitly. The driver mirrors upstream's raise, so a +mismatch is rejected at the CLI rather than silently rendered. + +For a reference-image render you need the **Ref2VA** partition instead +(`minimax_h3_ref2va_nvfp4_full`, or a REF2VA GGUF). Note that the encoder vision +tower is not yet ported, so image-conditioned renders are not clean even on the +matching partition. + ### Writing the prompt (read this first) Two things decide whether you get what you asked for, and neither is obvious. @@ -453,20 +494,34 @@ encoder, and both VAEs. ```sh build/examples/minimax-h3-gen \ - --dit MiniMax-H3-FL2VA-Q4_K_M.gguf --dequant-bf16 \ + --dit MiniMax-H3-FL2VA-Q4_K_M.gguf --dequant-bf16 --partition fl2va \ --encoder qwen3vl-32B-MiniMax-H3-Q4_K_M.gguf --tokenizer tokenizer.json \ --prompt "A golden retriever runs across a sunlit beach, waves crashing behind it" \ --video-vae video_vae.safetensors --video-vae-config video_vae_config.json \ --audio-vae audio_vae.safetensors --audio-vae-config audio_vae_config.json \ - --frames 124 --height 480 --width 864 --steps 50 \ + --frames 124 --height 768 --width 1344 --steps 50 \ --device cuda --out out.mp4 --workdir /tmp/h3 ``` +`--partition` is REQUIRED and names the partition the checkpoint you passed +actually serves — see the trap above. This is the command every render in this +document was produced with: Q4_K_M DiT and encoder, `--dequant-bf16`, task +**t2va** (no reference image), the 1344x768 default canvas, 124 frames, 50 steps. + +Cost, so you can plan: **~176 s per step** at 1344x768 / 124f on a 20-SM sm_110 +device, so a 50-step render is about **2.5 hours** plus roughly 30 minutes of +weight loading. Dropping to 512x512 costs ~15 s/step (~13 minutes end to end), +which is the right canvas for iterating on a prompt before committing to a full +render. `--dequant-bf16` holds the DiT as bf16 (~66 GB resident); `--keep-quant` +is the low-memory arm. + Conditioning modes, all optional and mutually exclusive where noted: ```sh --first-frame start.ppm --last-frame end.ppm # pin the first and/or last frame (fl2va) --ref-image subject.ppm # reference image, repeatable (ref2va) + # NOT served by the FL2VA checkpoint above -- + # needs a Ref2VA partition (see the trap) --ref-video prev_workdir/ # reference clip, reads frame_%06d.ppm --ref-audio voice.wav # reference audio --noise-aug 0.9 # how hard a keyframe is pinned (1.0 = exact)