README_CN.md

---
pipeline_tag: text-to-image
library_name: diffusers
tags:
  - Flux
  - text-to-image
  - quantization
  - svdquant
  - nunchaku
  - fp4
  - int4
base_model: black-forest-labs/FLUX.1-dev
base_model_relation: finetune
license: other
---

# 模型说明（SVDQuant · Nepotism_xii）

![Nepotism_xii 生成示例](Attached_image.png)

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

## 模型名称

- **模型仓库**：`tonera/Nepotism_xii-Nunchaku`
- **源模型（未量化）**：[Nepotism · Civitai](https://civitai.com/models/618792/nepotism)（本量化基于其 **XII** 等 Flux.1 D 系 checkpoint；许可与使用约束亦受上游及 Civitai 条款约束）
- **Diffusers 完整目录（含 VAE、文本编码器、调度器等）**：`{REPO_ID}`
- **量化 Transformer 权重（与 Nunchaku 配套）**：
  - `{REPO_ID}/svdq-fp4_r32-Nepotism_xii-Nunchaku.safetensors`
  - `{REPO_ID}/svdq-int4_r32-Nepotism_xii-Nunchaku.safetensors`

## 量化 / 推理技术

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

Nunchaku 面向 **4-bit（FP4/INT4）** 推理，在控制显存与延迟的同时尽量保持生成质量；本仓库中的 `svdq-*_r32-Nepotism_xii-Nunchaku.safetensors` 为 **SVDQuant** 量化后的 Flux Transformer，需在支持的环境上与 **FluxPipeline** 配合使用。

## 使用前必须安装 Nunchaku

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

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

- **前置条件**：`PyTorch` 版本以 Nunchaku 发布说明为准（通常建议较新版本）。
- **安装**：从 GitHub Releases / Hugging Face / ModelScope 选取与当前 Python、CUDA、PyTorch 匹配的 wheel，例如：

```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）**：在官方支持的前提下可优先尝试 **FP4** 权重，以获得更好的兼容性与性能（具体以 Nunchaku 文档为准）。

## 质量参考（评测样本 N=25）

以下为在当前量化配置下的客观指标摘要（数值越高一般表示越接近参考，**LPIPS 越低越好**）。

### FP4

| 指标 | mean | p50 | p90 | best | worst |
|------|------|-----|-----|------|-------|
| PSNR | 21.8159 | 21.9766 | 29.447 | 30.8016 | 13.0762 |
| SSIM | 0.811984 | 0.835828 | 0.938092 | 0.944179 | 0.582228 |
| LPIPS | 0.209448 | 0.178698 | 0.400699 | 0.0461679 | 0.64835 |

### INT4

| 指标 | mean | p50 | p90 | best | worst |
|------|------|-----|-----|------|-------|
| PSNR | 20.8759 | 20.8797 | 25.5093 | 30.0388 | 14.8672 |
| SSIM | 0.78943 | 0.812346 | 0.890699 | 0.913605 | 0.557165 |
| LPIPS | 0.243332 | 0.203449 | 0.419361 | 0.0868137 | 0.657203 |

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

将 `REPO_ID` 设为 Hugging Face 上的仓库名（或本地模型根路径）。Transformer 使用与本仓库一致的 **`svdq-{precision}_r32-Nepotism_xii-Nunchaku.safetensors`**，完整管线从 **`{REPO_ID}`** 加载（与 `model_index.json`、`transformer/`、`vae/` 等并列）。

```python
import torch
from diffusers import FluxPipeline

from nunchaku import NunchakuFluxTransformer2dModel
from nunchaku.utils import get_precision

REPO_ID = "tonera/Nepotism_xii-Nunchaku"
MODEL_STEM = "Nepotism_xii-Nunchaku"

if __name__ == "__main__":
    precision = get_precision()  # 按 GPU 自动选择 'int4' 或 'fp4'
    transformer = NunchakuFluxTransformer2dModel.from_pretrained(
        f"{REPO_ID}/svdq-{precision}_r32-{MODEL_STEM}.safetensors"
    )
    pipeline = FluxPipeline.from_pretrained(
        f"{REPO_ID}",
        transformer=transformer,
        torch_dtype=torch.bfloat16,
    ).to("cuda")

    image = pipeline(
        "A cat holding a sign that says hello world",
        num_inference_steps=50,
        guidance_scale=3.5,
    ).images[0]
    image.save(f"nepotism_xii-{precision}.png")
```

许可证与使用条款以仓库内 `LICENSE.md` 及上游模型政策为准。

若 Diffusers 权重与 `model_index.json` 等位于子目录（例如本地 `diffusers/`），请将示例中的 `f"{REPO_ID}"` 改为 `f"{REPO_ID}/diffusers"`，Transformer 权重路径相应加上该前缀。