MiniMax H3 Inference Engine voor Mac computers

Prompt-to-video/audio, conditioning van het eerste/laatste frame en geordende Ref2VA afbeelding-/video/audioreferenties werken volledig end-to-end. Het huidige werk richt zich op incrementele H3-specifieke Metal-prestaties en geheugenoptimalisatie voor de M3 Max en M5 Max.

Tutorial

1. Het model bouwen en inspecteren

De voorbeelden gaan ervan uit dat de Hugging Face snapshot zich in ./MiniMax-H3 bevindt en dat FFmpeg en FFprobe beschikbaar zijn in de PATH.

make -j8
mkdir -p outputs
./h3 --info -d ./MiniMax-H3

De vlag --info controleert de modelindeling en print het geselecteerde Metal-apparaat zonder alle gewichten te mappen of media te genereren. Gebruik ./h3 --help voor de volledige CLI-referentie.

Zonder -p start hetzelfde binary een interactieve sessie in Iris-stijl:

./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6

Typ een prompt om een genummerde video te genereren. De sessie houdt de exacte BF16 prompt conditioning, de voorbereide DiT en de videodecoder in het geheugen, zodat het herhalen van een prompt met een andere seed voorkomt dat deze opnieuw geladen en gecodeerd moeten worden. Nuttige commando's zijn !status, !seed random, !seconds 2, !show, !save output.mp4 en !cache. Gebruik !help voor de volledige lijst.

Conditioning van het eerste/laatste frame is persistent in de sessie:

h3> !first opening.png
h3> !last ending.png
h3> De camera beweegt langzaam rond het onderwerp.

Gebruik !first clear of !last clear om een anker te verwijderen. Gegenereerde video's worden geschreven naar de sessiemap die bij opstarten wordt getoond.

Voor een algemene Ref2VA conditioning-afbeelding gebruik je !ref-image PAD. Afbeeldingen worden in volgorde toegevoegd en aan het model gepresenteerd als <Picture 1>, <Picture 2>, enzovoort; bestandsnamen hebben geen betekenis voor het model.

h3> !ref-image person.png
h3> Laat de persoon getoond in Picture 1 zwaaien naar de camera.

!refs toont de huidige volgorde, !ref-remove N verwijdert een item, en !refs clear verwijdert ze allemaal. Ref2VA-referenties kunnen niet worden gecombineerd met !first/!last ankers.

2. Een eerste snelle video maken

Begin met het gevalideerde 'balanced' preset. Dit genereert 22 frames bij 24 fps (ongeveer 0,92 seconden), toont het evoluerende middelste videoframe na elke denoising-transitie in een ondersteunde grafische terminal en print de fase-timings:

./h3 --profile \
-d ./MiniMax-H3 \
-p "Een rode vos loopt door verse sneeuw in een dennenbos. Medium tracking shot, natuurlijk winterlicht, realistisch bont, zachte voetstappen en wind." \
--width 512 --height 512 \
--frames 22 --steps 20 \
--layers 45 --reuse 2 \
--show \
-o outputs/fox-fast.mp4

Deze configuratie is bewust niet de meest agressieve:

  • --steps 20 voert de standaard 20 denoising-passes uit.
  • --reuse 2 berekent 11 nieuwe denoiser-snelheden in plaats van alle 20 en extrapoleert de overgeslagen transities.
  • --layers 45 draait 45 van de 50 transformerblocks, wat zowel de tijd als het gebruik van unified memory vermindert.
  • --show is optioneel. Het ondersteunt grafische protocollen van Kitty/Ghostty en iTerm2/WezTerm/Konsole. Er wordt een resident preview VAE geladen die na elke Euler-transitie één representatief middelste videoframe toont, gevolgd door alle finale frames. De weergave-afmetingen zijn standaard 2x voor macOS Retina-schermen; gebruik --zoom 1 op een niet-HiDPI display. Dit voegt preview-decodeertijd en ongeveer 10 GiB tijdelijke modelresidentie toe; runs zonder --show blijven ongewijzigd.
  • --profile is optioneel en verandert het generatiepad niet.

De eerste procesaanroep bevat ook kosten voor het laden van het model en de filesystem-cache. Vergelijk prestaties via herhaalde runs.

Voor een zeer korte iteratie kun je direct vier denoising-passes aanvragen:

./h3 --profile \
-d ./MiniMax-H3 \
-p "Een rode vos loopt door verse sneeuw in een dennenbos. Medium tracking shot, natuurlijk winterlicht, realistisch bont." \
--width 512 --height 512 --frames 22 \
--steps 4 --layers 50 --reuse 1 \
--show \
-o outputs/fox-four-step.mp4

--steps N betekent altijd exact N denoising-passes. Vier tot zeven passes gebruiken hetzelfde schema dat het beste scoorde in de low-budget vergelijking; een toename van 4 naar 7 verbetert detail en beweging progressief. Houd --reuse 1 bij zulke kleine budgetten zodat elke gevraagde pass het model daadwerkelijk uitvoert.

Op de 512-vierkante, 22-frame vostest had het resultaat met vier passes een SSIM van 0,556 ten opzichte van een referentie met 29 passes; een onafhankelijke surfertest mat 0,547. De four-pass denoise duurde ongeveer 3,5 seconden op M5 Max, tegenover 26,4 seconden voor de referentie.

3. Naar referentiekwaliteit bewegen

Pas één instelling tegelijk aan bij het evalueren van de kwaliteit. Herstel eerst alle layers, dan alle denoiser-evaluaties, en verhoog tot slot het standaard 20-pass schema naar de tragere 50-pass referentie:

./h3 --profile \
-d ./MiniMax-H3 \
-p "Een rode vos loopt door verse sneeuw in een dennenbos. Medium tracking shot, natuurlijk winterlicht, realistisch bont, zachte voetstappen en wind." \
--width 512 --height 512 \
--frames 22 --steps 50 \
--layers 50 --reuse 1 \
-o outputs/fox-close.mp4

De standaardwaarden zijn --steps 20 --layers 50 --reuse 1. De 50-pass route is veel duurder, maar dient als het juiste ijkpunt wanneer een snelle modus het onderwerp, de anatomie, beweging of compositie verandert. Numerieke pixelidentiteit met MLX wordt niet verwacht omdat de random-number en execution engines verschillen; de afgebeelde inhoud en beweging moeten echter overeenstemmen.

4. Kies een snelheid/kwaliteit preset

Deze controls zijn onafhankelijk van elkaar, tenzij anders vermeld:

ControlSlow referenceDefaultAggressiveBelangrijkste impact
Denoising passes--steps 50--steps 20--steps 4..7Aantal werkelijke denoising-passes.
Whole denoiser reuse--reuse 1--reuse 2--reuse 3Bij 20 steps: 20, 11, of 8 nieuwe DiT evaluaties.
Active DiT blocks--layers 50--layers 45--layers 40Minder blokken verminderen compute en resident transformer weights.
Core residual reuse--core-reuse 1--core-reuse 4--core-reuse 6Ververst patch/head werk elke stap, maar draait de dure core minder vaak.
Token reductionoffoptional--token-reductionPaart horizontale video tokens in middelste blokken; sneller, maar kan compositie veranderen.
Internal canvasoutput size384x384 (bij 512 sq)320x320Draait DiT/VAE kleiner, schaalt daarna op met vImage.

Op M5 gebruikt --use-int8-row-fc2 één activatieschaal per FC2-rij en een enkel full-width TensorOps product. Dit is optioneel omdat het minder numeriek conservatief is dan grouped int8. In de interactieve sessie gebruik je !int8-row-fc2 on.

--reuse en --core-reuse sluiten elkaar uit. Layer thinning kan met beide worden gecombineerd.

Om het eerste commando sneller te maken terwijl de outputresolutie behouden blijft, voeg token reduction toe:

./h3 --profile \
-d ./MiniMax-H3 \
-p "Een surfer die in een scherpe blauwe oceaangolf rijdt, één rijder en één wit board, realistisch spray." \
--width 512 --height 512 --frames 22 --steps 20 \
--layers 45 --reuse 2 --token-reduction \
-o outputs/surfer-fast.mp4

Voor een agressieve preview kun je intern renderen op 320 vierkant en upscalen naar de gevraagde 512 vierkante output:

./h3 --profile \
-d ./MiniMax-H3 \
-p "Een rode vos die door de sneeuw loopt, realistisch, tracking shot." \
--width 512 --height 512 \
--render-width 320 --render-height 320 \
--frames 22 --steps 20 --layers 40 --reuse 3 \
-o outputs/fox-aggressive.mp4

Als alternatief voor whole-velocity reuse, houdt dit de timestep-afhankelijke patch en output heads vers bij elke transitie:

./h3 --profile \
-d ./MiniMax-H3 \
-p "Een surfer die op een blauwe oceaangolf rijdt." \
--width 512 --height 512 --frames 22 --steps 20 \
--layers 45 --core-reuse 4 \
-o outputs/surfer-core-reuse.mp4

5. Kies resolutie en duur

Breedte en hoogte moeten veelvouden van 32 zijn, minimaal 32, en hun product mag 768 * 1344 pixels niet overschrijden. H3-Base is een 768p model.

CanvasRichtlijn
512x512Veiligste ontwikkelingsformaat; herhaaldelijk gevalideerd met meerdere prompts.
768x768Gevalideerde close-quality vierkante output; aanzienlijk duurder.
1344x768, 768x1344Released 768p-klasse landscape/portrait limiet.
1024x768, 768x1024Geldige 4:3 en 3:4 768p-klasse canvases.
384x384 → 512x512Gevalideerd fast-quality schaalpunt (intern).
320x320 → 512x512Gevalideerd aggressive schaalpunt (intern).
256x256Native fast-preview canvas met automatische low-resolution RoPE adaptatie.

Voor een snelle native 256-vierkante preview:

./h3 -d ./MiniMax-H3 \
-p "Een rode vos loopt door verse sneeuw in een dennenbos." \
--width 256 --height 256 \
--frames 22 --steps 20 \
--layers 50 --reuse 1 \
-o outputs/fox-256.mp4

Bij 256 vierkant heeft H3 slechts een 8x8 effectief spatial-token grid. H3 halveert automatisch de spatial RoPE-coördinaten bij exact 256 vierkant om lattice-artefacten te verwijderen.

--render-width en --render-height moeten samen worden ingesteld, dezelfde aspectratio hebben als de output, en de outputdimensies niet overschrijden.

H3 produceert 24 fps en rondt frame-aanvragen naar boven af naar $5 + 17*n$: Gebruik --seconds N voor een duurgerichte aanvraag, of --frames N voor directe framecontrole. Seconden worden omgezet bij 24 fps en naar boven afgerond (bijv. --seconds 10 produceert 243 frames).

FramesBenaderde videoduur
220,917 seconden
391,625 seconden
562,333 seconden
1074,458 seconden
24310,125 seconden
36215,083 seconden

6. De prompt verbeteren

Een korte prompt werkt, maar het systeem verwacht een Context-IR-achtige beschrijving. SpecificeerHet onderwerp, de actie, de omgeving, de camera, belichting/stijl en het gewenste geluid. Voorbeeld:

  • Scene: een enkele rode vos in een met sneeuw bedekt dennenbos bij dageraad.
  • Action: de vos loopt gestaag van links naar rechts en kijkt één keer naar de camera.
  • Camera: medium-height lateral tracking shot, 50 mm lens, stabiele framing.
  • Look: fotorealistisch bont, koud blauw omgevingslicht, warm rim light van de zonsopgang.
  • Audio: zachte voetstappen in de sneeuw, lichte wind door dennentakken, geen muziek.

--seed N controleert de native random stream; de standaardwaarde is 42.

7. Frames bekijken en prestaties diagnosticeren

--show toont een representatief frame na elke denoising-transitie, gevolgd door alle frames van de voltooide video. --zoom N verandert de weergavefactor voor Retina terminals zonder de gegenereerde video aan te passen.

--frames-dir DIR schrijft finale callback-frames als PPM-bestanden. -o '' schakelt MP4-codering uit; combineer dit met --frames-dir als FFmpeg niet beschikbaar is. --profile rapporteert fase-wall time, Metal encoding/wait time, peak live tensor storage, cumulatieve allocatie en dispatch counts.

8. Afbeeldingen, video's en audio-referenties toevoegen

First/last-frame ankers selecteren het FL2VA pad:

./h3 -d ./MiniMax-H3 -p "De vos blijft door de sneeuw lopen." \
--width 512 --height 512 --frames 22 --steps 20 \
--layers 45 --reuse 2 \
--first-frame fox.png --last-frame fox-later.png \
-o outputs/fox-anchored.mp4

Geordende referenties selecteren het aparte Ref2VA checkpoint:

  • Eén afbeeldingsreferentie:

./h3 ... --ref-image fox.png -o outputs/fox-reference.mp4

  • Clip voortzetten maar soundtrack negeren:

./h3 ... --ref-silent-video fox.mp4 -o outputs/fox-video-reference.mp4

  • Embedded audio van de clip behouden:

./h3 ... --ref-video fox-with-audio.mp4 -o outputs/fox-video-audio.mp4

  • Soundtrack van een video expliciet vervangen:

./h3 ... --ref-video-audio silent-fox.mp4 replacement.wav -o outputs/fox-replaced-audio.mp4

  • Geordende afbeelding plus standalone audio referentie:

./h3 ... --ref-image fox.png --ref-audio music.wav -o outputs/fox-image-audio.mp4

Referentie-vlaggen kunnen worden herhaald en hun volgorde op de commandline wordt behouden. Standalone audio moet gepaard gaan met een afbeelding of video referentie. Audio-inputs moeten 2–15 seconden zijn; maximaal drie audio-inputs worden geaccepteerd en hun totale duur is beperkt tot 15 seconden.

Tests en runtime vereisten

  • make test: Draait de deterministische host suite en controleert (indien MLX fixture aanwezig is) een complete toy H3 block tegen MLX outputs.
  • make parity: Voert alleen de Metal/MLX checks uit.

FFmpeg en FFprobe moeten beschikbaar zijn in de PATH voor media-inputs en MP4-output. Er worden geen tussenliggende ongecomprimeerde mediabestanden aangemaakt; RGB24 en 32 kHz stereo F32 PCM worden via concurrent pipes gevoed.

Implementatie en prestatie-opmerkingen

Sampler en DiT controls

De standaard sampler gebruikt het released shifted video/audio schema. Whole-denoiser reuse evalueert de eerste en laatste pass plus elk gevraagd interval, en extrapoleert vervolgens overgeslagen video- en audio-snelheden. Bij zeer lage step counts dient --reuse 1 te worden gebruikt.

Layer thinning rangschikt de AdaLN gates van het checkpoint terwijl structureel belangrijke eerste en finale blokken worden beschermd. Ongebruikte gewichten worden niet behouden, waardoor --layers 45 en --layers 40 zowel transformer-tijd als unified memory verminderen. Core reuse houdt de vorige volledige transformer residual vast terwijl de patch projection en timestep-aware head worden ververst; dit sluit whole-velocity reuse uit.

Exacte DiT fusions

Elk actief DiT-blok fuseert zijn attention residual gate met de volgende MLP AdaLN. De geronde BF16 residual wordt exact geschreven, maar dezelfde rij blijft in threadgroup memory voor normalisatie, wat één dispatch en één globale reread elimineert.

De finale audio/video AdaLN kernels binden direct aan offsets in de residual stream, wat slice blits en scratch-geheugen bespaart (bijv. 18.8 MiB bij 512x512). BF16 final heads passen AdaLN toe tijdens het laden van hun 16x16 projection tiles.

Token-reduction internals

--token-reduction is een agressieve DiT-modus. Na blok 3 paart het aangrenzende horizontale target-video tokens, terwijl tekst, audio en referentie-tokens exact blijven. De volledige resolutie staat wordt als bypass bewaard. Gedurende de eerste tien noisy evaluaties herstelt het dit voor blok 40; daarna voor blok 30.

Dit vermindert op een M5 Max de denoise-tijd van 39,13 naar 28,06 seconden (28,3%) bij 512x512x22. Het verandert echter de compositie en is daarom opt-in.

Intern canvas en video VAE

--render-width en --render-height draaien het model en de VAE op een kleiner intern canvas met dezelfde aspectratio, waarna vImage-scaling wordt gebruikt voor de output. Dit is een tradeoff tussen kwaliteit en snelheid: een 384-naar-512 render vermindert de M5 DiT-tijd met 33% en de video-VAE tijd met 18%.

De video VAE kiest automatisch een spatial tile van 256-320 pixels om overlap-werk te minimaliseren en peak storage te begrenzen.

Weight residency en gestroomlijnde prompt encoding

Op M5 GPU's worden persistente transformer weights direct gemapt vanuit hun safetensor shards in plaats van gekopieerd naar shared buffers. Dit houdt het 37 GiB modelbestand reclaimable. M3 gebruikt de snellere copied-buffer path.

De gestroomlijnde Qwen text encoder preallocateert een ring van toekomstige layer buffers en vult deze via acht I/O workers terwijl Metal de huidige laag uitvoert.

Metal 4 en TensorOps pads

M5 GPU's gebruiken native BF16 Metal 4/TensorOps voor DiT QKV en attention-output projecties bij sequentielengtes tot 2,048. De compacte Morton schedule routeert Q/K/V direct naar head-major attention inputs en voorkomt drie MPSGraph input transposes.

H3NAX=1 forceert het bredere native BF16 linear path, maar is opt-in omdat microbenchmarks favoriseren dat MPSGraph scheduling wordt gebruikt voor volledige DiT runs. H3NAX=mlp selecteert een gespecialiseerd Metal 4 pad voor SwiGLU in threadgroup memory.

Gespecialiseerde projectie kernels

De smalle DiT audio/video output heads converteren F32 gewichten naar BF16 en gebruiken direct de Iris-afgeleide 16x16 tiled linear op BF16 activaties. Dit is significant sneller (bijv. 2.30x op M3 Max) met minimaal kwaliteitsverlies.

F32 patch projecties gebruiken een dedicated 16x16 cooperative tile die resultaten direct naar BF16 rondt. Het fuseren van de finale cast en het direct binden aan de packed hidden stream bespaart aanzienlijk geheugen (scratch) en tijd.

Scheduling en activatiegeheugen

De DiT core is gesplitst in twee Metal command buffers zodat GPU-executie van het eerste deel overlapt met CPU-encoding van het tweede deel. M5 gebruikt een split-depth van 60%.

Activatiebuffers volgen hun intra-block levensduur: de QKV projection arena wordt hergebruikt voor attention heads en daarna voor de genormaliseerde MLP input. Dit bespaart tot 99.63 MiB bij 864-klasse geometrie.

Checkpoint layout en media pipeline

Het checkpoint bewaart DiT QKV rows interleaved per attention head, wat direct door Metal wordt geconsumeerd in de fused QK-normalization/RoPE kernel.

De generatie-path decodeert audio latents met een native BigVGAN/AudioVAE en schrijft gesynchroniseerde H.264 plus 32 kHz stereo AAC. Audio referenties worden gedecodeerd als 32 kHz stereo F32 en verwerkt via de AudioVAE posterior-mean path.

Profiling en diagnostische pads

--profile rapporteert elke Metal-backed fase: wall time, CPU encoding, commit-to-fence wait, GPU timestamps, peak live tensor storage, cumulatieve allocatie en dispatch counts.

De DiT fast path evalueert elk BF16 fc1 → SwiGLU → fc2 blok als één cached graph. Op M5 is de native int8 MLP engine de standaard, wat de denoise-tijd op een M5 Max vermindert van 36,30 (BF16) naar 25,80 seconden (int8).

De snelste M5 route kwantiseert ook DiT QKV projecties en schrijft tiles direct in head-major attention layout, wat de tijd verder reduceert naar 19,32 seconden.