LSDJesus commited on
Commit
b7a16d7
·
verified ·
1 Parent(s): 7d2ed44

README: link the ComfyUI-GGUF PR

Browse files
Files changed (1) hide show
  1. README.md +130 -128
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 is merged, either run the patch script from this
58
- repo with the Python that runs your ComfyUI, then restart ComfyUI:
59
-
60
- ```
61
- python patch_comfyui_gguf.py PATH/TO/ComfyUI
62
- python_embeded\python.exe patch_comfyui_gguf.py ComfyUI (Windows portable)
63
- ```
64
-
65
- or make the same one-word edit yourself: add `"minimax_h3"` to
66
- `IMG_ARCH_LIST` near the top of `custom_nodes/ComfyUI-GGUF/loader.py`
67
- (the folder may be called `comfyui-gguf`):
68
-
69
- ```python
70
- IMG_ARCH_LIST = {"flux", "sd1", "sdxl", "sd3", "aura", "hidream", "cosmos", "ltxv", "hyvid", "wan", "lumina2", "qwen_image", "minimax_h3"}
71
- ```
72
-
73
- The script finds the node under any folder name, changes only that line,
74
- keeps a `loader.py.bak`, and does nothing if the line is already there. If a
75
- later ComfyUI-GGUF update complains about local changes to `loader.py`,
76
- restore the original, update, and run it again.
77
- - The text encoder (`qwen3vl_32b_minimax_h3_nvfp4_awq` or `_int8_convrot`) and
78
- the VAE (`minimax_h3_image_vae_fp16`) from
79
- [Comfy-Org/MiniMax-H3-Image](https://huggingface.co/Comfy-Org/MiniMax-H3-Image).
80
-
81
- ## Use
82
-
83
- Put the `.gguf` in `models/diffusion_models/` (or `models/unet/`). Open
84
- ComfyUI's **MiniMax H3 Image** template and replace its Load Diffusion Model
85
- node with **Unet Loader (GGUF)**. Everything else stays as in the template:
86
- 6 steps, euler, simple, cfg 1. The model is made for 4 to 20 megapixels; the
87
- template starts at 4.
88
-
89
- ## What is quantized
90
-
91
- The same 200 layers that Comfy-Org quantizes in its int8 and w4a8 files: the
92
- fused `qkv_proj`, `out_proj`, `mlp.fc1` and `mlp.fc2` of the 50 transformer
93
- blocks, 95.8% of the weights. The token refiner, the condition projection,
94
- the adaLN time-curve basis, the patch and output projections and all norms
95
- are kept as in the bf16 source (BF16, F32 for 1-D tensors, F16 for the adaLN
96
- basis). The per-block int8 attention setting that Comfy-Org's files carry is
97
- kept, and so is the `config` metadata with the 6-step PDD schedule, which
98
- ComfyUI needs to load the model.
99
-
100
- - **Importance matrix** (`_imat`): per input column of each quantized layer,
101
- the mean squared activation over about 300,000 tokens per layer, collected
102
- from 12 calibration images (portrait, street, landscape, product, anime,
103
- oil painting, 3D, infographic text, macro, interior, fantasy, food) at
104
- around 4 megapixels and all 6 steps. The K-quant search then weights each
105
- column's error by it, as llama.cpp does. Neither test image below is in
106
- the calibration set.
107
- - **Q2_K mix**: blocks 0 to 3 and 46 to 49 at Q4_K, `out_proj` and `fc2` at
108
- Q3_K, everything else at Q2_K. Plain Q2_K on all 200 layers breaks the
109
- image down to noise, even with the importance matrix.
110
-
111
- The quantization is ggml's own code (`ggml_quantize_chunk` from an unmodified
112
- llama.cpp build), written to GGUF with gguf-py.
113
-
114
- ## Quality
115
-
116
- One render per file, seed 42, 2048×2048, 6 steps, compared with Comfy-Org's
117
- int8 ConvRot render (int8 ConvRot was the most faithful format in our tests
118
- of other models). Left: whole image; right: a 1:1 crop. A 6-step model
119
- changes its composition a little with any change to the weights, so
120
- differences in pose and layout are normal; look for broken texture and text.
121
-
122
- The template's own prompt:
123
-
124
- ![Comparison on the template prompt](assets/compare_fox.jpg)
125
-
126
- A held-out photographic prompt (a fruit market with signs):
127
-
128
- ![Comparison on a market prompt](assets/compare_market.jpg)
 
 
 
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
+ ![Comparison on the template prompt](assets/compare_fox.jpg)
127
+
128
+ A held-out photographic prompt (a fruit market with signs):
129
+
130
+ ![Comparison on a market prompt](assets/compare_market.jpg)