File size: 5,862 Bytes
43ce74b 576a92b 43ce74b 576a92b cae2a73 576a92b | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 | ---
license: other
license_name: minimax-h3-image-community-license-agreement
license_link: https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE
pipeline_tag: text-to-image
language:
- en
base_model:
- MiniMaxAI/MiniMax-H3-Image
- MiniMaxAI/MiniMax-H3
- Comfy-Org/MiniMax-H3-Image
base_model_relation: quantized
tags:
- comfyui
- minimax-h3
- minimax-h3-image
- text-encoder
- qwen3-vl
- qwen3.5
- quantized
- int4
- convrot
- 4-bit
- comfy-kitchen
- text-to-image
- image-editing
---
<div align="center">
<img width="100%" src="cover.jpg" alt="MiniMax H3 image - Text Encoder · INT4 ConvRot">
</div>
<h1 align="center">MiniMax-H3-Image — Text Encoder (INT4 ConvRot)</h1>
<p align="center">
<strong>Ultra-compact 4-bit ConvRot text encoder & prompt enhancer weights for ComfyUI</strong>
</p>
<p align="center">
<a href="https://huggingface.co/MiniMaxAI/MiniMax-H3-Image"><img src="https://img.shields.io/badge/Base%20Model-MiniMax--H3--Image-FF6C37" alt="Base Model"></a>
<a href="https://github.com/Comfy-Org/ComfyUI"><img src="https://img.shields.io/badge/ComfyUI-Single%20File-007ACC" alt="ComfyUI"></a>
<img src="https://img.shields.io/badge/Quantization-INT4%20ConvRot%20(W4A4)-6F42C1" alt="Quantization">
<img src="https://img.shields.io/badge/VRAM%20Peak-13.25%20GiB-2EA44F" alt="VRAM Peak">
<a href="https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MiniMax%20H3%20Community-4CAF50" alt="License"></a>
</p>
---
## Overview
Ultra-compact **INT4 ConvRot** single-file `.safetensors` weights for **[MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image)** in **ComfyUI**. Built to minimize download size and GPU memory footprint while keeping native **`comfy_kitchen`** compatibility — shrinking the 32B text encoder to **13.30 GB** (`-51.0%` vs `int8_convrot`, `-15.2%` vs `nvfp4_awq`, and `-80%` vs the 66.7 GB BF16 original).
---
## Files & Comparison
| File | Role | Precision / Format | Size | vs Comfy-Org Baseline |
| :--- | :--- | :--- | :---: | :--- |
| **`qwen3vl_32b_minimax_h3_int4_convrot.safetensors`** | **Main Text Encoder** (`Qwen3-VL-32B`, 50 layers) | `convrot_w4a4` + `nvfp4` / `int8` / `bf16` | **13.30 GB** (`12.39 GiB`) | **`-51.0%`** vs `int8_convrot` (`27.14 GB`)<br>**`-15.2%`** vs `nvfp4_awq` (`15.69 GB`) |
| **`qwen3.5_9b_int4_convrot.safetensors`** | **Prompt Enhancer** (`Qwen3.5-9B`, optional) | `convrot_w4a4` + `int8` / `bf16` | **5.42 GB** (`5.05 GiB`) | **`-26.2%`** vs `qwen3.5_9b_w4a8_gptq` (`7.34 GB`) |
---
## ComfyUI Usage
### 1. Installation
Download the desired `.safetensors` file(s) and place them inside `ComfyUI/models/text_encoders/`:
```text
📂 ComfyUI/
└── 📂 models/
└── 📂 text_encoders/
├── qwen3vl_32b_minimax_h3_int4_convrot.safetensors # Main Text Encoder (required)
└── qwen3.5_9b_int4_convrot.safetensors # Prompt Enhancer (optional)
```
### 2. Workflow Setup
1. **Text Encoder:** In **CLIPLoader**, select `qwen3vl_32b_minimax_h3_int4_convrot.safetensors` with **`type = minimax`** and connect it to **MiniMaxH3ImageConditioning**.
2. **Prompt Enhancer *(optional)*:** In **CLIPLoader**, select `qwen3.5_9b_int4_convrot.safetensors` with **`type = minimax`** and connect it to **Generate Text** (`TextGenerateV2`).
3. **Templates:** Works as a direct drop-in replacement inside ComfyUI's official MiniMax-H3-Image [Text-to-Image](https://github.com/Comfy-Org/workflow_templates/blob/main/templates/image_minimax_h3_image_t2i.json) and [Image Edit](https://github.com/Comfy-Org/workflow_templates/blob/main/templates/image_minimax_h3_image_edit.json) workflows.
> **Requirements:** Up-to-date **ComfyUI** with **`comfy_kitchen`** kernels supporting `convrot_w4a4` and `nvfp4` on CUDA GPUs.
---
## Quantization Details
### `qwen3vl_32b_minimax_h3_int4_convrot.safetensors` (`727` tensors)
Formatted to MiniMax-H3-Image's exact 50-layer extraction spec (`minimax_h3_te: {"num_hidden_layers": 50, "output": "unnormalized_hidden_after_layer_50"}`):
- **LM & Merger Linears (`358` layers):** `convrot_w4a4` (`convrot_groupsize=256`, `quant_group_size=64`).
- **Vision Projections (`81` layers):** `convrot_w4a4` (`convrot_groupsize=64`).
- **Vision MLP Down (`fc2`, `27` layers):** `nvfp4` fallback (`K = 4304` is not divisible by `64` for `convrot_w4a4`).
- **Embeddings & Sensitive Layers:** `embed_tokens` in ConvRot `int8_tensorwise` (`gs=256`); RMSNorms, vision biases, `patch_embed`, and `pos_embed` preserved in `BF16`.
> **Why viewers show `I8` on 4-bit layers:** Safetensors has no native `int4` tensor dtype, so two 4-bit weights are packed per byte in `I8` (`int8`) containers. ComfyUI reads actual 4-bit precision and scales from each layer's `.comfy_quant` and `.weight_scale` tensors.
### `qwen3.5_9b_int4_convrot.safetensors` (`1,511` tensors)
Quantized 32-layer **Qwen3.5-9B** multimodal prompt enhancer (`5.42 GB`) using `convrot_w4a4` across language-model, `lm_head`, and compatible vision projections (`gs=256` / `gs=64`), ConvRot `int8_tensorwise` on `embed_tokens` and ViT `mlp.linear_fc2`, and `BF16` norms/biases.
---
## License & Credits
- **License:** Governed by the **[MiniMax H3 Image Community License Agreement](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE)**. Commercial use exceeding 1 Million USD in annualized revenue or providing hosted services to third parties requires separate written authorization via [platform.minimax.io/license](https://platform.minimax.io/license).
- **Upstream Repositories:** [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image) · [MiniMaxAI/MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3) · [Comfy-Org/MiniMax-H3-Image](https://huggingface.co/Comfy-Org/MiniMax-H3-Image)
|