Extensions/ComfyUI-W4A8-Loader
ComfyUI Extension

ComfyUI-W4A8-Loader

A ComfyUI extension with 1 custom node.

By starsFriday·Created 20 days ago·Updated 20 days ago· 2
starsFriday/ComfyUI-W4A8-Loader
Nodes1
On cloudLocal install
Categoryadvanced/loaders
Stars2
Updated20 days ago

Nodes (1)

Load Experimental W4A8 Diffusion Model
advanced/loaders
Readme

ComfyUI W4A8 Loader

English | 简体中文

Experimental AsymW4A8Int8Layout checkpoint loader and calibration-free converter for MiniMax H3 in ComfyUI.

This node pack keeps the W4A8 integration outside ComfyUI core. It provides a custom diffusion-model loader, a MiniMax H3 converter, and a reproducible installer for the native comfy-kitchen CUDA implementation.

[!WARNING] W4A8 quantization is lossy and the required comfy-kitchen support is based on an open experimental pull request. Keep the original BF16 checkpoint and compare important outputs before relying on the converted model.

What is included

  • Load Experimental W4A8 Diffusion Model loads checkpoints with the asym_w4a8_int8 metadata used by this project.
  • convert_minimax_h3.py converts the 200 main attention and MLP weights in a compatible MiniMax H3 checkpoint to packed W4A8 storage. Other weights remain in their original dtype, so the result is a mixed-precision checkpoint.
  • install_comfy_kitchen_w4a8.py builds the pinned comfy-kitchen W4A8 implementation for the GPU architectures visible in the active Python environment, installs the wheel, and runs a real CUDA operation test.

No ComfyUI core file is modified. Model weights are not included or downloaded by this repository.

Current compatibility

| Component | Status | |---|---| | MiniMax H3 Ref2VA and FL2VA pruned BF16 single-file checkpoints | Tested | | ComfyUI | Tested on v0.30.0 | | Python | 3.10+; tested on 3.12.9 | | PyTorch | CUDA build with CUDA 12.8+; tested on 2.9.1+cu130 | | CUDA Toolkit | 12.8+ with nvcc; tested on 13.1 | | NVIDIA GPU | SM 80 or newer; tested on RTX 4090 / SM 89 | | Linux | Tested | | Windows, AMD/ROCm, Apple Silicon and CPU-only execution | Not supported by the installer |

The loader may work with another model converted to the same format, but the bundled converter validates the MiniMax H3 50-block state-dict structure.

Installation

Stop ComfyUI first, then activate the same Python environment used to run ComfyUI.

cd ComfyUI/custom_nodes
git clone https://github.com/starsFriday/ComfyUI-W4A8-Loader.git
cd ComfyUI-W4A8-Loader
python install_comfy_kitchen_w4a8.py

The installer uses sys.executable, so python must point to the ComfyUI environment. It does not contain a hard-coded virtual-environment path.

The installer will:

  1. Check Python, PyTorch, CUDA, nvcc, the GPU compute capability, git, and g++.
  2. Install the Python build requirements (setuptools, wheel, nanobind, cmake, and ninja).
  3. Fetch pinned comfy-kitchen main and W4A8 PR commits and verify the merged source tree.
  4. Initialize CUTLASS and compile only the detected GPU architectures.
  5. Force-install the resulting wheel into the active environment.
  6. Quantize a small BF16 matrix and execute a W4A8 CUDA linear operation.

Check an existing installation without rebuilding:

python install_comfy_kitchen_w4a8.py --check

Keep the temporary source and wheel after a build for debugging:

python install_comfy_kitchen_w4a8.py --keep-build

Restart ComfyUI after installing or replacing comfy-kitchen.

Native code notice

The installer downloads and compiles the experimental W4A8 implementation from Comfy-Org/comfy-kitchen. The exact source commits and the expected merged tree are pinned in the installer so an upstream branch change cannot silently alter the build.

Download converted checkpoints

Preconverted MiniMax H3 Ref2VA and FL2VA checkpoints are available from starsfriday/MiniMax-H3-w4a8:

| File | Variant | |---|---| | minimax_h3_ref2va_pruned_w4a8_mixed.safetensors | Ref2VA reference image, video, and audio workflows | | minimax_h3_fl2va_pruned_w4a8_mixed.safetensors | FL2VA text/image and first/last-frame workflows |

Place the selected file in ComfyUI/models/unet/ or ComfyUI/models/diffusion_models/, then install this node pack before loading it.

Prepare a model

Obtain a compatible single-file, pruned BF16 MiniMax H3 checkpoint in ComfyUI state-dict format. The converter does not directly consume the original multi-file Diffusers/sharded model directory.

Upstream model pages:

Convert the checkpoint after comfy-kitchen is installed:

python convert_minimax_h3.py \
  /path/to/minimax_h3_ref2va_pruned_bf16.safetensors \
  /path/to/ComfyUI/models/unet/minimax_h3_ref2va_pruned_w4a8_mixed.safetensors

Use the corresponding FL2VA filenames to convert the FL2VA pruned checkpoint; the quantization layout is identical for both variants.

ComfyUI/models/diffusion_models/ can be used instead of ComfyUI/models/unet/.

The converter:

  • requires CUDA;
  • expects exactly 200 matching MiniMax H3 block weights;
  • quantizes one weight at a time on the GPU;
  • never deletes or overwrites the source checkpoint;
  • refuses to overwrite an existing output file; and
  • writes to a temporary file before atomically placing the completed output.

Conversion uses significant system RAM and disk space. Leave enough free space for the original checkpoint and the new checkpoint at the same time.

Use the node

After restarting ComfyUI, add:

advanced/loaders → Load Experimental W4A8 Diffusion Model

Select the converted .safetensors file and connect its MODEL output wherever the normal diffusion-model loader was connected:

Load Experimental W4A8 Diffusion Model → model patches (optional) → sampler

For an existing MiniMax H3 Ref2VA or FL2VA workflow, replace only the standard diffusion-model loader. The VAE, text encoder, conditioning, sampler, reference inputs, and output nodes can remain unchanged.

[!IMPORTANT] Do not load this checkpoint with ComfyUI's standard Load Diffusion Model node. ComfyUI core does not currently register this experimental format, and the standard loader may fail with KeyError: 'asym_w4a8_int8'. Use Load Experimental W4A8 Diffusion Model from this node pack.

Quantization format

The converter quantizes these weights in each of the 50 MiniMax H3 transformer blocks:

  • attn.qkv_proj.weight
  • attn.out_proj.weight
  • mlp.fc1.weight
  • mlp.fc2.weight

The generated format uses:

  • packed 4-bit ConvRot-rotated weights;
  • group size 16;
  • ConvRot group size 256;
  • a learned, calibration-free 16-value codebook;
  • FP8 E4M3 relative group scales and per-channel scales; and
  • runtime INT8 activation quantization and INT8 GEMM on the optimized CUDA path.

All non-targeted tensors stay in their source dtype. This is why the output filename uses w4a8_mixed rather than claiming that every tensor is 4-bit.

Measured checkpoint size

Both tested MiniMax H3 Ref2VA and FL2VA pruned checkpoints have the following sizes. Other source revisions may differ.

| Checkpoint | Exact bytes | Decimal size | |---|---:|---:| | BF16 source | 40,225,724,176 | 40.23 GB | | Mixed W4A8 output | 12,540,858,008 | 12.54 GB |

That is a 68.8% checkpoint-size reduction, or a 3.21× smaller file. These are storage measurements, not a promise of the same reduction in peak VRAM or total workflow time. Actual memory usage depends on ComfyUI offloading, resolution, frame count, attention backend, VAE, and other models in the workflow.

The installer smoke test on an RTX 4090 produced a relative L2 error of approximately 0.0716 for a random 512 × 1024 BF16 weight matrix. This verifies the installed quantization and CUDA execution path; it is not an end-to-end video-quality benchmark.

Runtime speed is hardware- and shape-dependent. W4A8 primarily targets lower model storage and memory traffic. Benchmark it against BF16, INT8, or other supported formats using identical workflow settings before drawing speed conclusions.

Troubleshooting

KeyError: 'asym_w4a8_int8'

The checkpoint was sent through ComfyUI's standard loader. Replace that node with Load Experimental W4A8 Diffusion Model and restart ComfyUI.

AsymW4A8Int8Layout is unavailable

comfy-kitchen was not installed into the environment running ComfyUI, or an ordinary comfy-kitchen package replaced the W4A8 build.

which python
python install_comfy_kitchen_w4a8.py
python install_comfy_kitchen_w4a8.py --check

Then fully restart ComfyUI.

CUDA toolkit or nvcc was not found

Install a CUDA 12.8+ toolkit and expose it with CUDA_HOME, for example:

export CUDA_HOME=/usr/local/cuda-13.1
python install_comfy_kitchen_w4a8.py

The installer prefers a toolkit matching the major version of the active PyTorch CUDA runtime.

The model is missing from the node dropdown

Place the converted checkpoint in one of these directories, then refresh or restart ComfyUI:

ComfyUI/models/unet/
ComfyUI/models/diffusion_models/

Expected 200 MiniMax H3 block weights

The input is not the compatible single-file MiniMax H3 state dict expected by this converter. Do not pass a shard, Diffusers directory, VAE, text encoder, or a different model family.

Output already exists

The converter intentionally avoids destructive overwrites. Choose a new output filename or move the old output yourself after confirming it is no longer needed.

Known limitations

  • The W4A8 comfy-kitchen implementation and its corresponding ComfyUI integration are still experimental upstream work.
  • Quantization is lossy and can change fine detail, motion, faces, hands, lip synchronization, or audio/video behavior.
  • MiniMax H3 Ref2VA and FL2VA pruned BF16 single-file sources are tested; other model families and H3 revisions are not.
  • The installer currently targets Linux, NVIDIA CUDA, and SM 80+ GPUs.
  • Conversion parameters are intentionally fixed; there is no calibration dataset or quality/speed preset.
  • Updating comfy-kitchen from PyPI may replace the experimental build. Rerun the installer if the W4A8 check stops working.

Acknowledgements

This is an independent experimental integration. It is not an official MiniMaxAI, ComfyUI, or comfy-kitchen release. Model weights remain subject to their original licenses and terms.