Upload README.md

README.md

@@ -2,4 +2,120 @@
 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 & Benchmarks
+
+### `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.
+
+### Verified Benchmark (vs `int8_convrot` on RTX 4060 Ti 16 GB)
+
+| Metric | `int8_convrot` (`27.14 GB`) | `int4_convrot` (`13.30 GB`) |
+| :--- | :---: | :---: |
+| **VRAM Peak (Multimodal)** | `14.04 GiB` | **`13.25 GiB`** (`13.20 GiB` text-only) |
+| **Encode Latency (Text / MM)** | `23.74 s` / `2.89 s` | **`15.82 s` / `2.14 s`** |
+| **50L Text-Only Cosine Sim** | `1.000` (baseline) | **`0.9981`** (`rel_err = 0.0641`) |
+| **50L Multimodal Cosine Sim** | `1.000` (baseline) | `0.3600` |
+
+> *Usage note:* **Text-to-Image** prompts track the INT8 baseline closely (`0.9981` cosine similarity) at under half the disk size. For **multi-reference Image Editing** requiring maximum vision-encoder accuracy, consider a higher-precision variant (`nvfp4_awq` / `w4a8` / `int8_convrot`).
+
+### `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)