<h1 id="minimax-h3-for-comfyui">MiniMax H3 for ComfyUI</h1><h3 id="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."><strong><em>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.</em></strong></h3><h2 id="download-install">Download / Install</h2><p>The package is published on the Comfy Registry as <strong>minimax-h3</strong>.</p><h3 id="comfyui-manager">ComfyUI Manager</h3><p>Open ComfyUI Manager, search for <strong>ComfyUI-MiniMaxH3</strong>, install it, and restart ComfyUI.</p><h3 id="manual-install">Manual Install</h3><pre><code>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</code></pre><p>Restart ComfyUI.</p><h3 id="repository">Repository</h3><p><a target="_blank" rel="ugc" href="https://github.com/xiaolibai-sys/ComfyUI-MiniMaxH3">https://github.com/xiaolibai-sys/ComfyUI-MiniMaxH3</a></p><h2 id="v1.3.1-updates">v1.3.1 Updates</h2><ul><li><p>Added an <code>Auto VRAM</code> switch to the BlockSwap Args node, enabled by default.</p></li><li><p>Auto mode estimates activation memory, ComfyUI overhead, and runtime LoRA footprint before allocating the GPU block pool.</p></li><li><p>When VRAM is tight, auto mode reduces <code>prefetch_count</code>, then <code>window</code>, while preserving <code>hot</code> blocks where possible.</p></li><li><p>Fixed VRAM measurement timing so freed encoder, VAE, and pre-bake memory is actually returned to the allocator before BlockSwap plans the window.</p></li><li><p>BlockSwap now flushes CUDA allocator caches before reading available VRAM and logs the measured free VRAM.</p></li><li><p>Improved NVFP4 pool alignment, preventing <code>cuBLAS error 15</code> caused by misaligned <code>block_scale</code> pointers.</p></li><li><p>Added runtime LoRA VRAM estimation with support for stacked LoRA and DoRA inputs.</p></li><li><p>Reduced unnecessary <code>q/k/v</code> contiguous copies for SageAttention and PyTorch SDPA paths.</p></li><li><p>Corrected FlashAttention layout handling for <code>[B, S, H, D]</code>.</p></li><li><p>Added regression coverage for Auto VRAM and manual BlockSwap planning.</p></li></ul><h2 id="v1.3-updates">v1.3 Updates</h2><ul><li><p>Fixed AdaLN pre-bake and LoRA compatibility, including precision differences that caused pre-bake cache misses and slower sampling.</p></li><li><p>Reworked BlockSwap pinning: contiguous pinned home pool, direct H2D/D2H DMA, and no RAM-to-RAM staging copies.</p></li><li><p>Improved text encoding speed:</p><ul><li><p>Positive and negative prompts share streamed encoder groups.</p></li><li><p>Disk reads run concurrently.</p></li><li><p>Quantized encoder weights are prefetched instead of synchronously loaded.</p></li></ul></li><li><p>Improved Storyboard UI and prompt workflow.</p></li><li><p>After selecting a shot, use the left and right arrow keys to adjust its timeline position.</p></li><li><p>Added negative prompt input to MiniMax H3 Simple Prompt.</p></li><li><p>Unified LoRA folding logic across backbone, AdaLN bake, and runtime AdaLN deltas.</p></li></ul><h2 id="core-features">Core Features</h2><h3 id="structured-storyboard">Structured Storyboard</h3><p>Create multi-shot video plans with per-shot duration, visual prompt, camera movement, dialogue, sound, and music.</p><ul><li><p>Define global subjects once and reuse them by name across shots.</p></li><li><p>Text inside <code>&lt;d&gt;...&lt;/d&gt;</code> is protected from subject replacement.</p></li><li><p>Speaker IDs such as <code>(S1)</code> and <code>(S2)</code> can be written manually or generated by the connected refiner.</p></li><li><p>Maps directly to MiniMax H3 official fields: <code>subject_definitions</code>, <code>summary</code>, <code>retention_analysis</code>, <code>detailed_description</code>, <code>overall_soundscape</code>, and <code>non_diegetic_music</code>.</p></li></ul><h3 id="prompt-refiners">Prompt Refiners</h3><ul><li><p>Official MiniMax H3 Context IR Refiner support.</p></li><li><p>OpenAI-compatible Refiner for DeepSeek, Kimi, and similar services.</p></li><li><p>PackageData supplies image, video, and audio references.</p></li><li><p>Built-in preview shows the refined prompt before Conditioning.</p></li></ul><h3 id="adaln-cache">AdaLN Cache</h3><ul><li><p>Pre-bakes AdaLN modulations before sampling to reduce per-step AdaLN work and memory pressure.</p></li><li><p>Works alongside BlockSwap for limited VRAM.</p></li><li><p>Do not use <code>dpm_adaptive</code> with AdaLN pre-bake enabled. Adaptive samplers determine their sigma schedule at runtime, so the pre-baked cache cannot cover the schedule reliably.</p></li></ul><h3 id="low-vram-sampling">Low-VRAM Sampling</h3><ul><li><p>Streaming model loading and BlockSwap with a CPU home pool and optional disk prefetch.</p></li><li><p>Supports bf16, fp16, fp8, int8, nvfp4, and convrot checkpoints.</p></li><li><p>Includes TeaCache arguments, attention backend selection, and sampler statistics.</p></li><li><p>Built for low-RAM Windows systems.</p></li></ul><h2 id="performance-reference">Performance Reference</h2><p>On a Windows machine with 24GB RAM and an RTX 5070 Ti 16GB, with AdaLN pre-bake enabled:</p><ul><li><p>Model: int8 non-pruned</p></li><li><p>Resolution: 1024 x 640 @ 5s</p></li><li><p>Pinning: disabled</p></li><li><p>Result: approximately 15s/iter</p></li></ul><h2 id="blockswap-pin-rework">BlockSwap PIN Rework</h2><ul><li><p>Allocates the CPU home pool as one contiguous pinned buffer.</p></li><li><p>Uses direct H2D/D2H DMA from the pinned buffer.</p></li><li><p>Removes the previous RAM-to-RAM staging copy.</p></li><li><p>If <code>cudaHostRegister</code> cannot allocate the requested memory, BlockSwap falls back to a pageable transfer path with a warning.</p></li><li><p>On Windows, the practical pinned-memory ceiling is approximately <code>0.4 x system RAM</code>.</p></li><li><p>When the requested home pool exceeds that limit, pin registration fails and pageable fallback is used automatically.</p></li></ul><h2 id="requirements">Requirements</h2><ul><li><p>ComfyUI</p></li><li><p>MiniMax H3 custom node package: <code>minimax-h3</code></p></li><li><p>CUDA-compatible GPU</p></li><li><p>Optional API keys for Refiner nodes</p></li></ul><h2 id="important">Important</h2><p>Avoid <code>dpm_adaptive</code> when AdaLN pre-bake is enabled. <code>dpm_adaptive</code> 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.</p><p>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.</p>

MiniMax H3 workflow with StoryBoard and Official/Third-party IR Refiner(With turbo lora)

<ul><li><p>Fix AdaLN pre-bake and LoRA compatibility, including precision differences that caused pre-bake cache misses and slower sampling.</p></li><li><p>Speed up selected paths: positive/negative text encoding now shares streamed groups, disk reads are concurrent, and quantized encoder weights are prefetched.</p></li><li><p>Rework the ring-buffer PIN logic: keep the contiguous pinned home pool, remove RAM-to-RAM staging copies, and fall back cleanly to pageable transfers when cudaHostRegister fails.</p></li><li><p>Improve the Storyboard frontend UI.</p></li><li><p>Add a negative prompt input to Simple Prompt and shared text encoding for positive/negative conditioning.</p></li></ul>

Files with SHA256: fce9700d02412f68ff57c432772795332de5f0ee6a0cc6ebac4429765a16a3a0