README_CN.md

---
pipeline_tag: text-to-image
library_name: diffusers
tags:
  - Chroma
  - quantization
  - svdquant
  - nunchaku
  - fp4
  - int4
base_model: tonera/Chroma1-HD-SVDQ
base_model_relation: quantized
license: apache-2.0
---

# 模型说明（SVDQuant）

> **文档语言**：中文｜[English](README.md)

![Chroma1-HD](chroma1-hd.png)


## 模型名称

- **模型仓库**：`tonera/Chroma1-HD-SVDQ`
- **Base（Diffusers 权重路径）**：`tonera/Chroma1-HD-SVDQ`（本仓库根目录）
- **量化 Transformer 权重**：`tonera/Chroma1-HD-SVDQ/svdq-<precision>_r32-Chroma1-HD.safetensors`

## 量化 / 推理技术

- **推理引擎**：[vitoom-nunchaku](https://huggingface.co/tonera/vitoom-nunchaku) — 社区维护的 Nunchaku 扩展版，已内置 **Chroma** 支持

Nunchaku 是面向 **4-bit（FP4/INT4）低比特神经网络** 的高性能推理引擎，实现 **SVDQuant** 等后训练量化方案。本仓库 Chroma1-HD 量化权重需配合 **vitoom-nunchaku** 在支持的 GPU 上推理。

上游 [Nunchaku](https://github.com/nunchaku-ai/nunchaku) 长期未合并 Chroma 相关改动（[PR #928](https://github.com/nunchaku-ai/nunchaku/pull/928) 仍在等待）。**无需再手动复制 `transformer_chroma.py`。**

## 安装 vitoom-nunchaku（用法一：自建 Python 环境）

从 **[tonera/vitoom-nunchaku](https://huggingface.co/tonera/vitoom-nunchaku)** 安装与平台、Python、CUDA 匹配的预编译 wheel：

```bash
pip install torch==2.11.* torchvision==0.26.* torchaudio==2.11.* \
  --index-url https://download.pytorch.org/whl/cu130

hf download tonera/vitoom-nunchaku \
  nunchaku-1.3.0.dev20260622+cu13.0torch2.11-cp311-cp311-linux_x86_64.whl \
  --local-dir ./wheels

pip install ./wheels/nunchaku-1.3.0.dev20260622+cu13.0torch2.11-cp311-cp311-linux_x86_64.whl
```

cu128、cp310、ARM64 aarch64 等 wheel 见 [vitoom-nunchaku 说明](https://huggingface.co/tonera/vitoom-nunchaku)。

验证安装：

```bash
python -c "import nunchaku; from nunchaku import NunchakuChromaTransformer2dModel; print(nunchaku.__version__)"
```

## 使用示例（Diffusers + Nunchaku Transformer）

以下示例假设已安装 **vitoom-nunchaku**：


```python
import torch
from diffusers import ChromaPipeline

from nunchaku import NunchakuChromaTransformer2dModel
from nunchaku.utils import get_precision

MODEL = "Chroma1-HD-SVDQ" 
REPO_ID = f"tonera/{MODEL}"

if __name__ == "__main__":
    transformer = NunchakuChromaTransformer2dModel.from_pretrained(
        f"{REPO_ID}/svdq-{get_precision()}_r32-{MODEL}.safetensors"
    )

    pipe = ChromaPipeline.from_pretrained(
        f"{REPO_ID}",
        transformer=transformer,
        torch_dtype=torch.bfloat16,
        use_safetensors=True,
    ).to("cuda")

    prompt = "Make Pikachu hold a sign that says 'Nunchaku is awesome', yarn art style, detailed, vibrant colors"
    image = pipe(prompt=prompt, guidance_scale=2.5, num_inference_steps=40).images[0]
    image.save("Chroma1.png")
```

## 用法二（推荐：vitoom 平台）

若希望开箱即用的 Web UI、无需手动安装 wheel，可部署 [vitoom](https://github.com/tonera/vitoom)。其 **visual** 模块已内置含 Chroma 支持的 **vitoom-nunchaku**。详见 [docker-usage-cn.md](https://github.com/tonera/vitoom/blob/main/docker-usage-cn.md)。

```bash
git clone https://github.com/tonera/vitoom.git
cd vitoom
python scripts/setup_vitoom.py
python scripts/load_vitoom_images.py --components backend,visual
docker compose up -d backend
docker compose -f docker-compose.inference.release.yml --profile visual up -d
```

Web UI：**Models** → 下载并激活 **`tonera/Chroma1-HD-SVDQ`** → 在 **Image** 工作区推理。