MiniMax H3 for ComfyUI

I have noticed the significant speed drop when VRAM becomes tight, so this release(nodepack 1.3.1) focuses on making VRAM planning more automatic and reducing the need for manual tuning.

Download / Install

The package is published on the Comfy Registry as minimax-h3.

ComfyUI Manager

Open ComfyUI Manager, search for ComfyUI-MiniMaxH3, install it, and restart ComfyUI.

Manual Install

git clone https://github.com/xiaolibai-sys/ComfyUI-MiniMaxH3.git ComfyUI/custom_nodes/ComfyUI-MiniMaxH3
pip install -r ComfyUI/custom_nodes/ComfyUI-MiniMaxH3/requirements.txt

Restart ComfyUI.

Repository

https://github.com/xiaolibai-sys/ComfyUI-MiniMaxH3

v1.3.1 Updates

• Added an Auto VRAM switch to the BlockSwap Args node, enabled by default.

• Auto mode estimates activation memory, ComfyUI overhead, and runtime LoRA footprint before allocating the GPU block pool.

• When VRAM is tight, auto mode reduces prefetch_count, then window, while preserving hot blocks where possible.

• Fixed VRAM measurement timing so freed encoder, VAE, and pre-bake memory is actually returned to the allocator before BlockSwap plans the window.

• BlockSwap now flushes CUDA allocator caches before reading available VRAM and logs the measured free VRAM.

• Improved NVFP4 pool alignment, preventing cuBLAS error 15 caused by misaligned block_scale pointers.

• Added runtime LoRA VRAM estimation with support for stacked LoRA and DoRA inputs.

• Reduced unnecessary q/k/v contiguous copies for SageAttention and PyTorch SDPA paths.

• Corrected FlashAttention layout handling for [B, S, H, D].

• Added regression coverage for Auto VRAM and manual BlockSwap planning.

v1.3 Updates

• Fixed AdaLN pre-bake and LoRA compatibility, including precision differences that caused pre-bake cache misses and slower sampling.

• Reworked BlockSwap pinning: contiguous pinned home pool, direct H2D/D2H DMA, and no RAM-to-RAM staging copies.

• Improved text encoding speed:

  • Positive and negative prompts share streamed encoder groups.

  • Disk reads run concurrently.

  • Quantized encoder weights are prefetched instead of synchronously loaded.

• Improved Storyboard UI and prompt workflow.

• After selecting a shot, use the left and right arrow keys to adjust its timeline position.

• Added negative prompt input to MiniMax H3 Simple Prompt.

• Unified LoRA folding logic across backbone, AdaLN bake, and runtime AdaLN deltas.

Core Features

Structured Storyboard

Create multi-shot video plans with per-shot duration, visual prompt, camera movement, dialogue, sound, and music.

• Define global subjects once and reuse them by name across shots.

• Text inside <d>...</d> is protected from subject replacement.

• Speaker IDs such as (S1) and (S2) can be written manually or generated by the connected refiner.

• Maps directly to MiniMax H3 official fields: subject_definitions, summary, retention_analysis, detailed_description, overall_soundscape, and non_diegetic_music.

Prompt Refiners

• Official MiniMax H3 Context IR Refiner support.

• OpenAI-compatible Refiner for DeepSeek, Kimi, and similar services.

• PackageData supplies image, video, and audio references.

• Built-in preview shows the refined prompt before Conditioning.

AdaLN Cache

• Pre-bakes AdaLN modulations before sampling to reduce per-step AdaLN work and memory pressure.

• Works alongside BlockSwap for limited VRAM.

• Do not use dpm_adaptive with AdaLN pre-bake enabled. Adaptive samplers determine their sigma schedule at runtime, so the pre-baked cache cannot cover the schedule reliably.

Low-VRAM Sampling

• Streaming model loading and BlockSwap with a CPU home pool and optional disk prefetch.

• Supports bf16, fp16, fp8, int8, nvfp4, and convrot checkpoints.

• Includes TeaCache arguments, attention backend selection, and sampler statistics.

• Built for low-RAM Windows systems.

Performance Reference

On a Windows machine with 24GB RAM and an RTX 5070 Ti 16GB, with AdaLN pre-bake enabled:

• Model: int8 non-pruned

• Resolution: 1024 x 640 @ 5s

• Pinning: disabled

• Result: approximately 15s/iter

BlockSwap PIN Rework

• Allocates the CPU home pool as one contiguous pinned buffer.

• Uses direct H2D/D2H DMA from the pinned buffer.

• Removes the previous RAM-to-RAM staging copy.

• If cudaHostRegister cannot allocate the requested memory, BlockSwap falls back to a pageable transfer path with a warning.

• On Windows, the practical pinned-memory ceiling is approximately 0.4 x system RAM.

• When the requested home pool exceeds that limit, pin registration fails and pageable fallback is used automatically.

Requirements

• ComfyUI

• MiniMax H3 custom node package: minimax-h3

• CUDA-compatible GPU

• Optional API keys for Refiner nodes

Important

Avoid dpm_adaptive when AdaLN pre-bake is enabled. dpm_adaptive continuously adjusts its step sizes during sampling, so the pre-baked AdaLN cache can almost never match the actual schedule and will almost always miss.

For node pack 1.4.0, the next step is to improve the first/last-frame UI and add rolling sampling to support multi-frame constraints in first/last-frame generation. Right now the focus is on finding bugs first. Since this package has roughly 13.1k lines of code, local testing cannot cover every path, so bug reports and suggestions from the community are appreciated.