cards/modelscope.md

---
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:
  - zh
  - en
tags:
  - diffusers
  - bitsandbytes
  - int8
  - image-generation
  - image-editing
  - rgba
---

# Image21-INT8

**Built with Qwen。** 由 **iximbox** 制作的
[Qwen-Image-2.1](https://modelscope.cn/models/Qwen/Qwen-Image-2.1)
社区 INT8 量化衍生版本，面向 Diffusers / Python 推理，不属于 Qwen 官方发布。

## 量化说明

基模型固定版本：`b3179ad355be050328e483a9dfdd9e60cd62adfa`（Hugging Face）。
两平台官方权重经过 SHA256 一致性核验。

生成 Transformer 与 Qwen3-VL 文本编码器中适用的线性层采用
**bitsandbytes LLM.int8**，离群值阈值为 **6.0**。这属于混合精度推理：
离群值计算使用浮点精度，VAE、归一化、嵌入、视觉编码器、输出头及排除的
条件投影层保留浮点精度。具体覆盖范围见两个组件的量化 JSON 报告。
未进行微调，无需校准数据集。此模型不是全链路 W8A8、FP8 或 GGUF 模型。
体积减小不等于推理加速，速度以实际测评为准。

## 安装与使用

测试环境为 Python 3.13、PyTorch 2.10.0+cu128 和 RTX 5090。
`requirements.txt` 固定了本次验证使用的官方 Diffusers 提交及主要依赖。

```bash
pip install torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu128
pip install -r requirements.txt
```

```python
import torch
import sys
from modelscope import snapshot_download

model_dir = snapshot_download("iximbox/Image21-INT8")
sys.path.insert(0, model_dir)  # 仓库附带、可查看的 scripts/runtime.py
from scripts.runtime import load_int8_pipeline
pipe = load_int8_pipeline(model_dir, local_files_only=True)
image = pipe(
    prompt='一张咖啡馆海报，清晰写着“慢下来，喝杯咖啡”，暖色摄影',
    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")
```

加载时会自动读取已保存的量化配置，无需再次指定量化参数。
图像编辑请使用与源图独立的种子（如源图为 42 时编辑用 1000042），
从 `output_resolution=1024` 起步。下文 2048px 部分为历史证据，不是通用推荐。
透明图生成使用官方 RGBA 提示词格式，并保存为 PNG 以保留透明通道。

在固定版本环境下请使用仓库附带的加载函数：它依次加载并卸载两个 INT8 组件，
同时在 CPU 卸载时移动量化层的辅助张量。仅调用 `enable_model_cpu_offload()`
会在本次测试的软件组合中留下 INT8 CUDA 张量。该加载函数不修改权重或量化方式。

## 可视化 Web 应用

另行开源的 [IMGEN](https://github.com/iXimNet/IMGEN) 支持使用 BF16、INT8 和 INT4 模型进行生图与改图。安装与使用说明见其 GitHub 仓库。

## 随模型发布的非正式测评报告

**本次测评由社区发布者自行开展，仅供参考，不代表 Qwen、Hugging Face、ModelScope 及其团队的任何官方评价。** 结果来自单一软硬件配置下的少量自选样本，不属于标准榜单成绩，也不构成质量、速度或显存需求的保证。

{{EVALUATION_ZH}}

**观察到的限制：** 两种精度的 1024px 毛衣改色均有明显过度锐化和对比度变化，所检查的中文海报均添加了多余页脚文字，2048px 雪林背景替换在两种精度中也均未达到目标。下文保留这些失败结果。像素差异仅反映偏移，不能等同于语义质量；本次不提供官方分数、盲测偏好、OCR、CLIP 或 FID 成绩。大量多图参考、其他显卡／注意力后端及 ComfyUI 兼容性不在本次测评范围内。

{{SAMPLES_ZH}}

{{AUDIT_ZH}}

### 测量方法与指标详情

1024px 主评测包含七类用例，每类两个种子；成年女性肖像专项与 2048px 改图组单独统计。每种精度使用独立进程，前一进程退出后再启动下一进程，并记录 PID、GPU 进程列表、启动时零分配及逐图 CUDA 基线。两种精度均使用仓库附带的 CPU 卸载辅助函数。

成对调用采用相同输入、提示词、CPU 随机数生成器、种子、尺寸、40 步、CFG=1 和 KV 缓存。计时组各执行一次完整设置预热，不计入结果；先运行 BF16，再运行 INT8，每个用例／种子计时一次，未估计置信区间；桌面后台活动未严格控制，单次耗时仅供参考。耗时包含编码、去噪、解码和 CPU 传输，不包含模型加载及图片写盘。显存为进程内 PyTorch CUDA 已分配／保留峰值，不是整卡占用，也不能等同于最低显卡容量；仅在 RTX 5090 上实测。

{{EVALUATION_DETAILS_ZH}}

## 许可证与修改声明

权重沿用 [Qwen Research License Agreement](LICENSE)，仅用于非商业研究与评测；
商业使用需向原许可方另行申请。再分发须保留原协议、归属及修改说明。
详见 [Notice](Notice) 和 [CHANGES.md](CHANGES.md)。

原始模型：[ModelScope](https://modelscope.cn/models/Qwen/Qwen-Image-2.1) |
[Hugging Face](https://huggingface.co/Qwen/Qwen-Image-2.1)。