buqi-minimax-h3-multigpu

buqi-minimax-h3-multigpu

English | 中文 | 日本語

A ComfyUI custom node that runs the MiniMax H3 DiT with Ulysses sequence parallelism across multiple NVIDIA GPUs.

Compatibility and status

• Requires the MiniMax H3 API introduced at or after ComfyUI commit 8d534945; startup uses a runtime capability check instead of a release-version claim.
• Tested against the current ComfyUI 0.37 development commit 7fbcfa8be9a8f47cf905ec47978b5bd754959ea7.
• The old ComfyUI 0.30 integration belongs to older releases; the main branch no longer claims compatibility with it.
• Platform: Linux or WSL2 with PyTorch/NCCL. Native Windows multi-GPU is not supported.
• world_size must divide MiniMax H3's 56 attention heads: 1, 2, 4, 7, or 8.

The CPU suite checks package discovery, current API contracts, fail-fast behavior, patch synchronization, and two-rank Gloo parity. Current-commit GPU execution still requires the manual self-hosted acceptance workflow or the commands below; do not interpret CPU tests as a GPU performance claim.

Install

Clone the repository directly as one ComfyUI custom-node directory:

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/buqi-code/buqi-minimax-h3-multigpu.git

Restart ComfyUI. No extra pip package is required by this node; PyTorch and ComfyUI are intentionally not declared as pip dependencies.

Models and INT8

Current example filenames are:

• DiT: minimax_h3_fl2va_pruned_int8_convrot.safetensors
• Reference DiT: minimax_h3_ref2va_pruned_int8_convrot.safetensors
• Text encoder: qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors
• Video VAE: minimax_h3_video_vae_int8_convrot.safetensors
• Audio VAE: minimax_h3_audio_vae_fp32.safetensors
• Turbo LoRA: minimax_h3_fl2v_turbo_8step_v1.0_comfyui_bf16.safetensors

For a pre-quantized INT8/ConvRot checkpoint, select weight_dtype=default. Its quantization metadata is loaded by ComfyUI; do not force another dtype in the SP loader.

Use the standard VAEDecode node for both official INT8 and FP16 video VAEs. This preserves ComfyUI's quantized metadata, streaming behavior, and memory policy. The old MiniMaxH3SPVAEDecode node ID remains only so existing workflows load: it logs one deprecation warning and calls the same official vae.decode path; it no longer performs parallel VAE decode.

VAE path	Supported behavior
Standard VAEDecode + official INT8 or FP16 video VAE	Recommended; official decode and streaming path
Legacy MiniMaxH3SPVAEDecode node	Compatibility alias for standard vae.decode; deprecated and not parallel
Audio VAE	Standard VAEDecodeAudio; not sharded by this project

Supported workflow surface

Feature	Status
T2V	Supported by the current H3 conditioning path
I2V first frame	Supported
I2V first + last frame	Supported
R2V and chained MiniMaxH3AddGuide	Supported
Denoise masks	Supported
PDD/static model options	Supported
Static Turbo LoRA loaded before execution	Supported; patches are synchronized before denoising
Fun ControlNet	Not supported; rejected before distributed execution
Sparse Attention	Not supported; rejected before distributed execution
Dynamic hooks/patches	Not supported; rejected before distributed execution
Stacking with ComfyUI MultiGPU/threaded MultiGPU	Not supported; rejected before distributed execution

“Supported” describes the capability-checked H3 interface. Run the GPU acceptance tests for the exact hardware, model files, and workflow combination you deploy.

SP versus DP

• Sequence parallelism (this project): one prompt is split across GPUs by sequence/head communication. Every rank holds the full DiT weights. It targets lower latency for one generation; it does not divide model-weight VRAM.
• Data parallelism: each GPU runs a separate prompt. It increases throughput, not the latency of one pr