File size: 15,258 Bytes
9116984 aaae9b0 9116984 aaae9b0 9116984 aaae9b0 9116984 aaae9b0 9116984 aaae9b0 9116984 aaae9b0 9116984 | 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 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 | ---
license: other
license_name: qwen-research
license_link: LICENSE
base_model: Qwen/Qwen-Image-2.1
base_model_relation: quantized
library_name: diffusers
pipeline_tag: text-to-image
language:
- en
- zh
tags:
- diffusers
- sdnq
- int4
- uint4
- image-generation
- image-editing
- apple-silicon
---
# Image21-INT4
**Built with Qwen.** An independent 4-bit derivative of
[Qwen-Image-2.1](https://huggingface.co/Qwen/Qwen-Image-2.1), prepared by **ixim**.
This is a community conversion, not an official Qwen release.
The stored weights are **SDNQ UINT4** (unsigned 4-bit integers) plus a rank-32 SVD
residual. "INT4" in the repository name means this 4-bit integer checkpoint. It is
not bitsandbytes NF4, GPTQ, or a pure integer pipeline. Quantized matmul is left
off, so the CUDA and Apple Silicon paths dequantize with ordinary PyTorch operators.
## What runs where
- **CUDA, 8GB VRAM:** the author has also run this INT4 checkpoint on a Windows
laptop with 8GB of GPU memory. Group offload keeps one transformer block or one
text-encoder linear layer on the GPU at a time. VAE encode and decode run on CPU
to reduce GPU memory use. The separate 1024×1024, 40-step measurement below used
a 7.2 GiB PyTorch allocator cap on a 32GB RTX 5090; its timing and memory figures
are from that capped test, not the laptop. The installed PyTorch build must support
the laptop GPU.
- **Larger CUDA GPUs:** the loader uses model CPU offload, one pipeline component
at a time. The paired comparison below used this path.
- **Apple Silicon:** the author has also run this INT4 checkpoint through MPS on
an M4 MacBook. No MPS timing, peak memory, or minimum unified-memory requirement
is reported here. Set `IMAGE21_DTYPE=float16` if an MPS operator rejects bfloat16.
## Quantization
Base revision: `b3179ad355be050328e483a9dfdd9e60cd62adfa`.
Eligible linear layers in the transformer and the Qwen3-VL text encoder are UINT4.
Sensitive projections, normalization, embeddings, the vision tower, the output head,
and the VAE stay in floating point. Exact module names are in the component
quantization JSON files. No calibration set and no fine-tuning were used.
## Installation
```bash
pip install torch torchvision
pip install -r requirements.txt
```
On NVIDIA machines, install a CUDA wheel of PyTorch 2.10 that matches the GPU
before `requirements.txt`. The conversion was made with torch 2.10.0+cu128.
```python
import torch
import sys
from huggingface_hub import snapshot_download
model_dir = snapshot_download("ixim/Image21-INT4")
sys.path.insert(0, model_dir)
from scripts.runtime import load_pipeline
pipe = load_pipeline(model_dir, local_files_only=True)
image = pipe(
prompt='A neon sign reading "CREATE WITH LIGHT", rainy night',
width=1024, height=1024, num_inference_steps=40,
true_cfg_scale=1.0, use_kv_cache=True,
generator=torch.Generator("cpu").manual_seed(42),
).images[0]
image.save("output.png")
```
`load_pipeline` selects CUDA, MPS, or CPU. On an 8GB-class CUDA board it selects
group offload by itself. Do not re-quantize these files at load time.
For an edit, keep the edit seed different from the seed that created the source
image. The published edit pairs use source seed 42 and edit seeds 1000042 and
1000123. Save PNG when you need the alpha channel.
For a visual interface, [IMGEN](https://github.com/iXimNet/IMGEN) is a separate
open-source web app for image generation and editing with BF16, INT8, and INT4
model options. See its repository for setup instructions.
## Informal evaluation
The comparison below uses a small, selected set of images on an RTX 5090. Its
timings and CUDA memory figures do not describe the separate laptop or MPS runs.
### Measured comparison
14 pairs, 1024×1024, 40 steps, CFG 1, KV cache on, model CPU offload, one excluded warmup. Host: NVIDIA GeForce RTX 5090.
| | BF16 | INT4 |
|---|---|---|
| Weight files (decimal GB) | 33.116 | 13.441 |
| Mean call latency (s) | 26.98 | 29.40 |
| Maximum allocated CUDA memory (GiB) | 19.08 | 9.99 |
| Case | Seed | BF16 s | INT4 s | BF16 GiB | INT4 GiB | RGB MAE |
|---|---|---|---|---|---|---|
| chinese_text | 42 | 25.55 | 28.67 | 16.41 | 7.71 | 0.0791 |
| chinese_text | 123 | 25.61 | 28.79 | 16.41 | 7.71 | 0.0819 |
| composition | 42 | 25.21 | 28.72 | 16.41 | 7.71 | 0.0297 |
| composition | 123 | 25.51 | 28.67 | 16.41 | 7.71 | 0.0594 |
| edit | 1000042 | 38.67 | 33.81 | 19.08 | 9.99 | 0.0112 |
| edit | 1000123 | 31.10 | 33.51 | 19.08 | 9.99 | 0.0107 |
| english_text | 42 | 25.40 | 28.35 | 16.41 | 7.71 | 0.0839 |
| english_text | 123 | 25.23 | 28.67 | 16.41 | 7.71 | 0.0547 |
| portrait | 42 | 28.05 | 29.41 | 16.40 | 7.71 | 0.0528 |
| portrait | 123 | 26.06 | 28.21 | 16.40 | 7.71 | 0.0639 |
| rgba | 42 | 25.02 | 28.55 | 16.40 | 7.70 | 0.0444 |
| rgba | 123 | 25.76 | 28.54 | 16.40 | 7.70 | 0.0760 |
| texture | 42 | 25.40 | 28.98 | 16.40 | 7.70 | 0.0775 |
| texture | 123 | 25.13 | 28.76 | 16.40 | 7.70 | 0.0489 |
### Package versions
| Package | Version |
|---|---|
| torch | 2.10.0+cu128 |
| diffusers | 0.41.0.dev0 |
| transformers | 5.17.0 |
| accelerate | 1.15.0 |
| sdnq | 0.2.7 |
| safetensors | 0.8.0 |
| huggingface-hub | 1.32.0 |
| tokenizers | 0.23.2 |
| numpy | 2.2.6 |
| pillow | 12.2.0 |
| psutil | 7.0.0 |
### Visual inspection
# Visual inspection
These notes describe images I looked at. They are not a score, and they do not cover every seed. Pixel drift for all 14 pairs is in comparison.csv.
portrait, seed 42: Both are waist-up photographs of an older woman in a blue wool sweater beside a window. The face, the hair, and how much of the window is in frame differ. Skin and knit texture stay photographic in both.
english_text, seed 42: Both render the headline CREATE WITH LIGHT and the subtitle September 2026. The orange lamp, books, and notebook are arranged differently. I did not see an extra headline.
chinese_text, seed 42: Both render 慢下来，喝杯咖啡 and 小店今日营业 above a latte. Both also add a footer of unwanted, partly illegible text, so neither follows “不添加其他文字” completely.
composition, seed 42: Both show exactly three cups, red then blue then yellow, and one green apple in front of the blue cup. Cup shape and spacing differ. The INT4 cups have handles; the BF16 cups do not.
texture, seed 42: Both are plausible kingfishers on a mossy branch over water. The INT4 bird faces left and the BF16 bird faces right. Feather and bark detail are visible in both.
rgba, seed 42: Both are full-body green cartoon dragons with orange wings, saved as RGBA. Measured alpha runs from 0 to 255. Pixels with alpha at or below 5 are 63.5% of the BF16 image and 73.0% of the INT4 image. The BF16 dragon has a white sticker outline.
edit, seed 1000042: The input is the BF16 portrait from seed 42, and the edit seed is not 42. Both change the sweater from blue to red and keep the same face, window light, and pose. This pair is not visibly oversharpened. That does not show that every edit will preserve identity.
The 8GB-cap portrait (group offload, CPU VAE encode and decode) is a separate run from this paired set. On that image the woman, blue sweater, and window are all present. The same cap also completed both edit seeds, 1000042 and 1000123, at 1024 for 40 steps. Allocated peaks were 3.48 GiB and reserved peaks were 4.08 and 4.24 GiB.
# 目视记录
下面只记录看过的图，不是评分，也没有逐张覆盖第二个种子。14 对的像素差在 comparison.csv。
portrait，种子 42：两种精度都是窗边、蓝毛衣、半身的老年女性照片。脸、头发和窗户入画的多少不同。皮肤和针织纹理都还像照片。
english_text，种子 42：两种精度都写出了 CREATE WITH LIGHT 和 September 2026。橙色台灯、书和笔记本的摆放不同。没有看到多出来的主标题。
chinese_text，种子 42：两种精度都写出了“慢下来，喝杯咖啡”和“小店今日营业”，中间是拿铁。两种精度的页脚都出现了多余且部分无法辨认的文字，都没有完全遵守“不添加其他文字”。
composition，种子 42：两种精度都是左红、中蓝、右黄三个杯子，蓝杯前有一个青苹果。杯子形状和间距不同。INT4 的杯子有把手，BF16 没有。
texture，种子 42：两种精度都是水边苔枝上的翠鸟。INT4 的鸟朝左，BF16 的鸟朝右。羽毛和树皮细节都还在。
rgba，种子 42：两种精度都是全身、绿鳞、橙翼的卡通龙，文件为 RGBA。alpha 范围是 0 到 255。alpha 小于等于 5 的像素，BF16 占 63.5%，INT4 占 73.0%。BF16 的龙有一圈白色贴纸描边。
edit，种子 1000042：输入是 BF16 种子 42 的肖像，编辑种子不是 42。两种精度都把蓝毛衣改成了红毛衣，脸、窗光和姿态还在。这一对没有明显过锐。这不能说明每次编辑都会保住身份。
8GB 分配上限下的肖像是另一次运行（分组卸载，VAE 的编码和解码都在 CPU）。那张图里仍有人物、蓝毛衣和窗户。同一次上限设置也完成了两个编辑种子 1000042 和 1000123，1024、40 步。已分配峰值都是 3.48 GiB，保留峰值分别是 4.08 GiB 和 4.24 GiB。
### CUDA allocator-cap measurement
The saved INT4 checkpoint generated portrait seed 42 at 1024×1024 for 40 steps while PyTorch's caching allocator was limited to 7.2 GiB on this NVIDIA GeForce RTX 5090. Offload mode: group: one transformer block or one text-encoder leaf on GPU, VAE encode and decode on CPU. Allocated peak 1.22 GiB, reserved peak 2.37 GiB, call 84.32s after an excluded warmup. These measurements were recorded on the RTX 5090, not on the 8GB laptop described above.
## Paired images
### chinese_text / seed 42
设计一张现代咖啡馆海报，米白背景，中央一杯拉花拿铁。顶部准确写上中文大标题“慢下来，喝杯咖啡”，下方准确写上“小店今日营业”。文字清晰，留白充分，暖色摄影，不添加其他文字。
| BF16 | INT4 |
|---|---|
|  |  |
### chinese_text / seed 123
设计一张现代咖啡馆海报，米白背景，中央一杯拉花拿铁。顶部准确写上中文大标题“慢下来，喝杯咖啡”，下方准确写上“小店今日营业”。文字清晰，留白充分，暖色摄影，不添加其他文字。
| BF16 | INT4 |
|---|---|
|  |  |
### composition / seed 42
A studio photograph on a light gray tabletop: exactly three ceramic cups in a row, a red cup on the left, a blue cup in the middle, and a yellow cup on the right. A single green apple sits in front of the blue cup. Soft shadows, no text.
| BF16 | INT4 |
|---|---|
|  |  |
### composition / seed 123
A studio photograph on a light gray tabletop: exactly three ceramic cups in a row, a red cup on the left, a blue cup in the middle, and a yellow cup on the right. A single green apple sits in front of the blue cup. Soft shadows, no text.
| BF16 | INT4 |
|---|---|
|  |  |
### edit / seed 1000042
Change only the blue sweater to a red sweater. Preserve the same person, face, pose, lighting and background.
| BF16 | INT4 |
|---|---|
|  |  |
### edit / seed 1000123
Change only the blue sweater to a red sweater. Preserve the same person, face, pose, lighting and background.
| BF16 | INT4 |
|---|---|
|  |  |
### english_text / seed 42
A clean editorial poster with a deep blue background. Large exact headline at the top: "CREATE WITH LIGHT". Smaller exact subtitle: "September 2026". A realistic orange desk lamp occupies the lower half. Elegant balanced typography, no additional text.
| BF16 | INT4 |
|---|---|
|  |  |
### english_text / seed 123
A clean editorial poster with a deep blue background. Large exact headline at the top: "CREATE WITH LIGHT". Smaller exact subtitle: "September 2026". A realistic orange desk lamp occupies the lower half. Elegant balanced typography, no additional text.
| BF16 | INT4 |
|---|---|
|  |  |
### portrait / seed 42
A natural documentary portrait of an elderly woman with silver hair and freckles, wearing a blue wool sweater, standing beside a window in soft morning light. Realistic skin texture, gentle expression, waist-up composition.
| BF16 | INT4 |
|---|---|
|  |  |
### portrait / seed 123
A natural documentary portrait of an elderly woman with silver hair and freckles, wearing a blue wool sweater, standing beside a window in soft morning light. Realistic skin texture, gentle expression, waist-up composition.
| BF16 | INT4 |
|---|---|
|  |  |
### rgba / seed 42
This is an RGBA image with transparency. A cute cartoon dragon sticker, full body, green scales and small orange wings. The image has alpha channel and the background is transparent.
| BF16 | INT4 |
|---|---|
|  |  |
### rgba / seed 123
This is an RGBA image with transparency. A cute cartoon dragon sticker, full body, green scales and small orange wings. The image has alpha channel and the background is transparent.
| BF16 | INT4 |
|---|---|
|  |  |
### texture / seed 42
Macro photography of a small kingfisher perched on a mossy branch beside clear water, detailed blue feathers, droplets, natural sunlight, softly blurred forest background, realistic textures.
| BF16 | INT4 |
|---|---|
|  |  |
### texture / seed 123
Macro photography of a small kingfisher perched on a mossy branch beside clear water, detailed blue feathers, droplets, natural sunlight, softly blurred forest background, realistic textures.
| BF16 | INT4 |
|---|---|
|  |  |
The Qwen Research License keeps this derivative limited to non-commercial research
and evaluation. License, Notice, and CHANGES.md are in the repository.
|