docs(usage): the H3 recipe that actually renders — required --partition, the task trap, and what is verified - #200
Merged
Merged
Conversation
…on, the task trap, and what is verified 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]
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three defects in the MiniMax-H3 section, each of which costs a multi-hour render to discover.
1. The documented command no longer runs
--partitionbecame required when the task/partition guard landed (#84, mirroring upstream's_resolve_taskraise). The worked example predates it and fails at the CLI. Added, and marked 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 servest2va+fl2va, notref2va. 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 worsens with canvas size. Measured on one prompt and canvas as a period-16 seam ratio (1.15 == clean):
At 864x480 the same mismatch measures 1.15 and looks acceptable — which is why it survives casual testing and only bites at the resolution you actually want.
3. "Verified" and "available" read alike
Added a status table, because a render costs hours before it tells you anything:
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 real 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 iterating on a prompt first.Docs only; no code change.