---
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`

## 量化 / 推理技术

- **推理引擎**：Nunchaku（`https://github.com/nunchaku-ai/nunchaku`）

Nunchaku 是一个面向 **4-bit（FP4/INT4）低比特神经网络**的高性能推理引擎，核心目标是在尽量保持生成质量的同时显著降低显存占用并提升推理速度。它实现并工程化了 **SVDQuant** 等后训练量化方案，并通过算子/内核融合等优化减少低秩分支带来的额外开销。

本模型仓库中的 Chroma1-HD 量化权重（例如 `svdq-*_r32-*.safetensors`）用于配合 Nunchaku，在支持的 GPU 上进行高效推理。


## 使用前必须安装 Nunchaku

- **官方安装文档**（建议以此为准）：`https://nunchaku.tech/docs/nunchaku/installation/installation.html`

### （推荐）方式：安装官方预编译 Wheel

- **前置条件**：安装 `PyTorch >= 2.5`（实际以对应 wheel 的要求为准）
- **安装 nunchaku wheel**：从 GitHub Releases / HuggingFace / ModelScope 选择与你环境匹配的 wheel（注意 `cp311` 表示 Python 3.11）：
  - `https://github.com/nunchaku-ai/nunchaku/releases`

```bash
# 示例（请按你的 torch/cuda/python 版本选择正确的 wheel URL）
pip install https://github.com/nunchaku-ai/nunchaku/releases/download/vX.Y.Z/nunchaku-X.Y.Z+torch2.9-cp311-cp311-linux_x86_64.whl
```

- **提示（50 系 GPU）**：通常建议 `CUDA >= 12.8`，并优先使用 FP4 模型以获得更好的兼容性与性能（以官方文档为准）。

## 使用示例（Diffusers + Nunchaku Transformer）
- 注意：我正在推动Nunchaku官方合并此PR:https://github.com/nunchaku-ai/nunchaku/pull/928
在此之前，如果您想体验，可将仓库中transformer_chroma.py
拷贝到nunchaku/models/transformers/transformer_chroma.py中这样使用
```
from nunchaku.models.transformers.transformer_chroma import NunchakuChromaTransformer2dModel
```


```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")
```