README: link the ComfyUI-GGUF PR
Browse files
README.md
CHANGED
|
@@ -1,128 +1,130 @@
|
|
| 1 |
-
---
|
| 2 |
-
license: other
|
| 3 |
-
license_name: minimax-h3-image-community-license-agreement
|
| 4 |
-
license_link: LICENSE
|
| 5 |
-
base_model:
|
| 6 |
-
- MiniMaxAI/MiniMax-H3-Image
|
| 7 |
-
base_model_relation: quantized
|
| 8 |
-
pipeline_tag: text-to-image
|
| 9 |
-
tags:
|
| 10 |
-
- comfyui
|
| 11 |
-
- gguf
|
| 12 |
-
- minimax-h3
|
| 13 |
-
- text-to-image
|
| 14 |
-
- image-editing
|
| 15 |
-
---
|
| 16 |
-
|
| 17 |
-
# MiniMax-H3-Image GGUF (ComfyUI)
|
| 18 |
-
|
| 19 |
-
GGUF quantizations of the MiniMax-H3-Image diffusion transformer for
|
| 20 |
-
[ComfyUI-GGUF](https://github.com/city96/ComfyUI-GGUF). The bf16, int8 ConvRot
|
| 21 |
-
and w4a8 versions, the text encoders and the VAE are in
|
| 22 |
-
[Comfy-Org/MiniMax-H3-Image](https://huggingface.co/Comfy-Org/MiniMax-H3-Image);
|
| 23 |
-
fp8 scaled and NVFP4 are in
|
| 24 |
-
[LSDJesus/MiniMax-H3-Image-fp8-nvfp4](https://huggingface.co/LSDJesus/MiniMax-H3-Image-fp8-nvfp4).
|
| 25 |
-
|
| 26 |
-
> **Modified files.** These are quantized versions of MiniMax-H3-Image, made
|
| 27 |
-
> from Comfy-Org's `minimax_h3_image_pruned_bf16.safetensors`.
|
| 28 |
-
> MiniMax-H3-Image is licensed under the MiniMax-H3-Image Community License
|
| 29 |
-
> Agreement, Copyright © 2026 MiniMax. All Rights Reserved. See `LICENSE` and
|
| 30 |
-
> `NOTICE`. Among other terms, the license grants rights only outside the
|
| 31 |
-
> European Union, the United Kingdom, South Korea and the United States
|
| 32 |
-
> (sections I.5 and II), and it includes an acceptable use policy. Read it
|
| 33 |
-
> before downloading.
|
| 34 |
-
|
| 35 |
-
## Files
|
| 36 |
-
|
| 37 |
-
| File | Quantization | Size | Notes |
|
| 38 |
-
| --- | --- | --- | --- |
|
| 39 |
-
| `minimax_h3_image_pruned_Q6_K.gguf` | Q6_K | 17.5 GB | Closest to the 8-bit versions |
|
| 40 |
-
| `minimax_h3_image_pruned_Q4_K_imat.gguf` | Q4_K, importance matrix | 12.5 GB | |
|
| 41 |
-
| `minimax_h3_image_pruned_Q3_K_imat.gguf` | Q3_K, importance matrix | 10.0 GB | Smallest that holds up well |
|
| 42 |
-
| `minimax_h3_image_pruned_Q2_K_mix_imat.gguf` | Q2_K / Q3_K / Q4_K mix, importance matrix | 9.25 GB | **Experimental.** Coherent, but visibly softer: fine texture smears and small text can break |
|
| 43 |
-
|
| 44 |
-
All files run on any GPU ComfyUI-GGUF supports. GGUF weights are dequantized
|
| 45 |
-
on the fly, so they are slower than the safetensors formats: about 1 step/s at
|
| 46 |
-
2048×2048 on an RTX PRO 6000, against 2.1 to 3.4 steps/s for fp8, int8, w4a8
|
| 47 |
-
and NVFP4 on the same card. If your card runs Comfy-Org's w4a8 (RTX 30 or
|
| 48 |
-
newer) or int8 ConvRot (RTX 20 or newer), those are faster at a similar size:
|
| 49 |
-
w4a8 is 12.5 GB, like Q4_K.
|
| 50 |
-
|
| 51 |
-
## Requirements
|
| 52 |
-
|
| 53 |
-
- **ComfyUI with MiniMax-H3-Image support**, merged on 10 November 2026
|
| 54 |
-
(ComfyUI 0.44). Older versions do not know the model.
|
| 55 |
-
- **ComfyUI-GGUF that accepts the `minimax_h3` architecture.** Without it the
|
| 56 |
-
loader stops with `Unexpected architecture type in GGUF file: 'minimax_h3'`.
|
| 57 |
-
Until the upstream change
|
| 58 |
-
|
| 59 |
-
|
| 60 |
-
|
| 61 |
-
|
| 62 |
-
|
| 63 |
-
|
| 64 |
-
|
| 65 |
-
|
| 66 |
-
|
| 67 |
-
|
| 68 |
-
|
| 69 |
-
``
|
| 70 |
-
|
| 71 |
-
```
|
| 72 |
-
|
| 73 |
-
|
| 74 |
-
|
| 75 |
-
|
| 76 |
-
|
| 77 |
-
-
|
| 78 |
-
the
|
| 79 |
-
|
| 80 |
-
|
| 81 |
-
|
| 82 |
-
|
| 83 |
-
|
| 84 |
-
|
| 85 |
-
|
| 86 |
-
|
| 87 |
-
|
| 88 |
-
|
| 89 |
-
|
| 90 |
-
|
| 91 |
-
|
| 92 |
-
|
| 93 |
-
|
| 94 |
-
|
| 95 |
-
|
| 96 |
-
|
| 97 |
-
kept
|
| 98 |
-
|
| 99 |
-
|
| 100 |
-
|
| 101 |
-
|
| 102 |
-
|
| 103 |
-
|
| 104 |
-
|
| 105 |
-
|
| 106 |
-
|
| 107 |
-
|
| 108 |
-
|
| 109 |
-
|
| 110 |
-
|
| 111 |
-
|
| 112 |
-
|
| 113 |
-
|
| 114 |
-
|
| 115 |
-
|
| 116 |
-
|
| 117 |
-
|
| 118 |
-
|
| 119 |
-
|
| 120 |
-
|
| 121 |
-
|
| 122 |
-
|
| 123 |
-
|
| 124 |
-
|
| 125 |
-
|
| 126 |
-
|
| 127 |
-
|
| 128 |
-
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
license: other
|
| 3 |
+
license_name: minimax-h3-image-community-license-agreement
|
| 4 |
+
license_link: LICENSE
|
| 5 |
+
base_model:
|
| 6 |
+
- MiniMaxAI/MiniMax-H3-Image
|
| 7 |
+
base_model_relation: quantized
|
| 8 |
+
pipeline_tag: text-to-image
|
| 9 |
+
tags:
|
| 10 |
+
- comfyui
|
| 11 |
+
- gguf
|
| 12 |
+
- minimax-h3
|
| 13 |
+
- text-to-image
|
| 14 |
+
- image-editing
|
| 15 |
+
---
|
| 16 |
+
|
| 17 |
+
# MiniMax-H3-Image GGUF (ComfyUI)
|
| 18 |
+
|
| 19 |
+
GGUF quantizations of the MiniMax-H3-Image diffusion transformer for
|
| 20 |
+
[ComfyUI-GGUF](https://github.com/city96/ComfyUI-GGUF). The bf16, int8 ConvRot
|
| 21 |
+
and w4a8 versions, the text encoders and the VAE are in
|
| 22 |
+
[Comfy-Org/MiniMax-H3-Image](https://huggingface.co/Comfy-Org/MiniMax-H3-Image);
|
| 23 |
+
fp8 scaled and NVFP4 are in
|
| 24 |
+
[LSDJesus/MiniMax-H3-Image-fp8-nvfp4](https://huggingface.co/LSDJesus/MiniMax-H3-Image-fp8-nvfp4).
|
| 25 |
+
|
| 26 |
+
> **Modified files.** These are quantized versions of MiniMax-H3-Image, made
|
| 27 |
+
> from Comfy-Org's `minimax_h3_image_pruned_bf16.safetensors`.
|
| 28 |
+
> MiniMax-H3-Image is licensed under the MiniMax-H3-Image Community License
|
| 29 |
+
> Agreement, Copyright © 2026 MiniMax. All Rights Reserved. See `LICENSE` and
|
| 30 |
+
> `NOTICE`. Among other terms, the license grants rights only outside the
|
| 31 |
+
> European Union, the United Kingdom, South Korea and the United States
|
| 32 |
+
> (sections I.5 and II), and it includes an acceptable use policy. Read it
|
| 33 |
+
> before downloading.
|
| 34 |
+
|
| 35 |
+
## Files
|
| 36 |
+
|
| 37 |
+
| File | Quantization | Size | Notes |
|
| 38 |
+
| --- | --- | --- | --- |
|
| 39 |
+
| `minimax_h3_image_pruned_Q6_K.gguf` | Q6_K | 17.5 GB | Closest to the 8-bit versions |
|
| 40 |
+
| `minimax_h3_image_pruned_Q4_K_imat.gguf` | Q4_K, importance matrix | 12.5 GB | |
|
| 41 |
+
| `minimax_h3_image_pruned_Q3_K_imat.gguf` | Q3_K, importance matrix | 10.0 GB | Smallest that holds up well |
|
| 42 |
+
| `minimax_h3_image_pruned_Q2_K_mix_imat.gguf` | Q2_K / Q3_K / Q4_K mix, importance matrix | 9.25 GB | **Experimental.** Coherent, but visibly softer: fine texture smears and small text can break |
|
| 43 |
+
|
| 44 |
+
All files run on any GPU ComfyUI-GGUF supports. GGUF weights are dequantized
|
| 45 |
+
on the fly, so they are slower than the safetensors formats: about 1 step/s at
|
| 46 |
+
2048×2048 on an RTX PRO 6000, against 2.1 to 3.4 steps/s for fp8, int8, w4a8
|
| 47 |
+
and NVFP4 on the same card. If your card runs Comfy-Org's w4a8 (RTX 30 or
|
| 48 |
+
newer) or int8 ConvRot (RTX 20 or newer), those are faster at a similar size:
|
| 49 |
+
w4a8 is 12.5 GB, like Q4_K.
|
| 50 |
+
|
| 51 |
+
## Requirements
|
| 52 |
+
|
| 53 |
+
- **ComfyUI with MiniMax-H3-Image support**, merged on 10 November 2026
|
| 54 |
+
(ComfyUI 0.44). Older versions do not know the model.
|
| 55 |
+
- **ComfyUI-GGUF that accepts the `minimax_h3` architecture.** Without it the
|
| 56 |
+
loader stops with `Unexpected architecture type in GGUF file: 'minimax_h3'`.
|
| 57 |
+
Until the upstream change
|
| 58 |
+
([city96/ComfyUI-GGUF#493](https://github.com/city96/ComfyUI-GGUF/pull/493))
|
| 59 |
+
is merged, either run the patch script from this
|
| 60 |
+
repo with the Python that runs your ComfyUI, then restart ComfyUI:
|
| 61 |
+
|
| 62 |
+
```
|
| 63 |
+
python patch_comfyui_gguf.py PATH/TO/ComfyUI
|
| 64 |
+
python_embeded\python.exe patch_comfyui_gguf.py ComfyUI (Windows portable)
|
| 65 |
+
```
|
| 66 |
+
|
| 67 |
+
or make the same one-word edit yourself: add `"minimax_h3"` to
|
| 68 |
+
`IMG_ARCH_LIST` near the top of `custom_nodes/ComfyUI-GGUF/loader.py`
|
| 69 |
+
(the folder may be called `comfyui-gguf`):
|
| 70 |
+
|
| 71 |
+
```python
|
| 72 |
+
IMG_ARCH_LIST = {"flux", "sd1", "sdxl", "sd3", "aura", "hidream", "cosmos", "ltxv", "hyvid", "wan", "lumina2", "qwen_image", "minimax_h3"}
|
| 73 |
+
```
|
| 74 |
+
|
| 75 |
+
The script finds the node under any folder name, changes only that line,
|
| 76 |
+
keeps a `loader.py.bak`, and does nothing if the line is already there. If a
|
| 77 |
+
later ComfyUI-GGUF update complains about local changes to `loader.py`,
|
| 78 |
+
restore the original, update, and run it again.
|
| 79 |
+
- The text encoder (`qwen3vl_32b_minimax_h3_nvfp4_awq` or `_int8_convrot`) and
|
| 80 |
+
the VAE (`minimax_h3_image_vae_fp16`) from
|
| 81 |
+
[Comfy-Org/MiniMax-H3-Image](https://huggingface.co/Comfy-Org/MiniMax-H3-Image).
|
| 82 |
+
|
| 83 |
+
## Use
|
| 84 |
+
|
| 85 |
+
Put the `.gguf` in `models/diffusion_models/` (or `models/unet/`). Open
|
| 86 |
+
ComfyUI's **MiniMax H3 Image** template and replace its Load Diffusion Model
|
| 87 |
+
node with **Unet Loader (GGUF)**. Everything else stays as in the template:
|
| 88 |
+
6 steps, euler, simple, cfg 1. The model is made for 4 to 20 megapixels; the
|
| 89 |
+
template starts at 4.
|
| 90 |
+
|
| 91 |
+
## What is quantized
|
| 92 |
+
|
| 93 |
+
The same 200 layers that Comfy-Org quantizes in its int8 and w4a8 files: the
|
| 94 |
+
fused `qkv_proj`, `out_proj`, `mlp.fc1` and `mlp.fc2` of the 50 transformer
|
| 95 |
+
blocks, 95.8% of the weights. The token refiner, the condition projection,
|
| 96 |
+
the adaLN time-curve basis, the patch and output projections and all norms
|
| 97 |
+
are kept as in the bf16 source (BF16, F32 for 1-D tensors, F16 for the adaLN
|
| 98 |
+
basis). The per-block int8 attention setting that Comfy-Org's files carry is
|
| 99 |
+
kept, and so is the `config` metadata with the 6-step PDD schedule, which
|
| 100 |
+
ComfyUI needs to load the model.
|
| 101 |
+
|
| 102 |
+
- **Importance matrix** (`_imat`): per input column of each quantized layer,
|
| 103 |
+
the mean squared activation over about 300,000 tokens per layer, collected
|
| 104 |
+
from 12 calibration images (portrait, street, landscape, product, anime,
|
| 105 |
+
oil painting, 3D, infographic text, macro, interior, fantasy, food) at
|
| 106 |
+
around 4 megapixels and all 6 steps. The K-quant search then weights each
|
| 107 |
+
column's error by it, as llama.cpp does. Neither test image below is in
|
| 108 |
+
the calibration set.
|
| 109 |
+
- **Q2_K mix**: blocks 0 to 3 and 46 to 49 at Q4_K, `out_proj` and `fc2` at
|
| 110 |
+
Q3_K, everything else at Q2_K. Plain Q2_K on all 200 layers breaks the
|
| 111 |
+
image down to noise, even with the importance matrix.
|
| 112 |
+
|
| 113 |
+
The quantization is ggml's own code (`ggml_quantize_chunk` from an unmodified
|
| 114 |
+
llama.cpp build), written to GGUF with gguf-py.
|
| 115 |
+
|
| 116 |
+
## Quality
|
| 117 |
+
|
| 118 |
+
One render per file, seed 42, 2048×2048, 6 steps, compared with Comfy-Org's
|
| 119 |
+
int8 ConvRot render (int8 ConvRot was the most faithful format in our tests
|
| 120 |
+
of other models). Left: whole image; right: a 1:1 crop. A 6-step model
|
| 121 |
+
changes its composition a little with any change to the weights, so
|
| 122 |
+
differences in pose and layout are normal; look for broken texture and text.
|
| 123 |
+
|
| 124 |
+
The template's own prompt:
|
| 125 |
+
|
| 126 |
+

|
| 127 |
+
|
| 128 |
+
A held-out photographic prompt (a fruit market with signs):
|
| 129 |
+
|
| 130 |
+

|