---
pipeline_tag: image-to-image
library_name: diffusers
tags:
  - FLUX
  - FLUX.2
  - Klein
  - quantization
  - svdquant
  - nunchaku
  - fp4
  - int4
base_model: black-forest-labs/FLUX.2-klein-4B
base_model_relation: quantized
license: apache-2.0
---

# 模型说明（SVDQuant / Nunchaku）

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

## 模型与上游

- **量化权重仓库**：[`tonera/FLUX.2-klein-4B-Nunchaku`](https://huggingface.co/tonera/FLUX.2-klein-4B-Nunchaku)
- **官方全精度源模型**：[`black-forest-labs/FLUX.2-klein-4B`](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B)
- **本仓库中的量化 Transformer**：`svdq-<precision>_r32-FLUX.2-klein-4B-Nunchaku.safetensors`；`<precision>` 请按环境与 Nunchaku 构建使用 `nunchaku.utils.get_precision()`（常见为 `fp4` 或 `int4`）拼入文件名

## 用法一（适合有编程经验用户）

- **引擎**：[vitoom-nunchaku](https://huggingface.co/tonera/vitoom-nunchaku) — 社区维护的 Nunchaku 扩展版，已内置 **FLUX.2 Klein** 推理支持（FP4/INT4 SVDQuant）
- **框架**：需支持 `Flux2KleinPipeline` 的 Diffusers（官方示例为从源码安装）：

```bash
pip install "git+https://github.com/huggingface/diffusers.git"
```

### 安装 vitoom-nunchaku（推荐）

上游 [Nunchaku](https://github.com/nunchaku-ai/nunchaku) 长期未合并 FLUX.2 Klein 相关改动（[PR #926](https://github.com/nunchaku-ai/nunchaku/pull/926) 仍在等待）。**无需再手动复制补丁文件。** 请直接安装与平台、Python、CUDA 匹配的预编译 wheel：

1. 先安装对应版本的 **PyTorch 2.11**（cu128 或 cu130）。
2. 从 **[tonera/vitoom-nunchaku](https://huggingface.co/tonera/vitoom-nunchaku)** 下载并安装 wheel。

示例（x86_64、Python 3.11、CUDA 13.0）：

```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 NunchakuFlux2Transformer2DModel; print(nunchaku.__version__)"
```

## 使用示例（图生图 + 量化 Transformer）

以下示例假设已安装 **vitoom-nunchaku**，且权重在本地或通过 `tonera/FLUX.2-klein-4B-Nunchaku` 可访问；请将 `REPO` 换成你的本地目录或 Hugging Face ID。

```python
import torch
from diffusers import Flux2KleinPipeline
from diffusers.utils import load_image

from nunchaku import NunchakuFlux2Transformer2DModel
from nunchaku.utils import get_precision

REPO = "tonera/FLUX.2-klein-4B-Nunchaku"  # 或本地绝对路径
NAME = "FLUX.2-klein-4B-Nunchaku"

transformer = NunchakuFlux2Transformer2DModel.from_pretrained(
    f"{REPO}/svdq-{get_precision()}_r32-{NAME}.safetensors",
    torch_dtype=torch.bfloat16,
)
pipe = Flux2KleinPipeline.from_pretrained(
    REPO, torch_dtype=torch.bfloat16, transformer=transformer
)

pipe.to("cuda")

ref = load_image("https://example.com/your_ref.png").convert("RGB")
image = pipe(
    prompt="按你的编辑意图写英文提示…",
    image=ref,
    guidance_scale=1.0,  # 与官方 Klein 示例一致，可按需调整
    num_inference_steps=4,  # 蒸馏模型常用 4 步；非蒸馏设定见 Diffusers 文档
    generator=torch.Generator("cpu").manual_seed(1),
).images[0]
image.save("flux2_klein_4b_nunchaku.png")
```

纯文生图时可省略 `image` 参数（行为以当前 Diffusers `Flux2KleinPipeline` 文档为准）。显存紧张时可按需使用 `pipe.enable_model_cpu_offload()` 等策略。

## 推荐推理参数

| 参数 | 建议值 | 说明 |
|------|--------|------|
| `num_inference_steps` | 4 | Klein 蒸馏模型常用步数 |
| `guidance_scale` | 1.0 | 与官方 Klein 示例一致 |

### 如果以上操作对你来说难度过高，建议你直接安装 vitoom 平台（见下方文档）使用。

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

推荐通过 [vitoom](https://github.com/tonera/vitoom) 部署与推理：内置完整 **vitoom-nunchaku** runtime、Web UI、多图编辑与 LoRA 管理，无需手动安装 wheel 或拷贝补丁文件。安装与启动详见 [vitoom 仓库](https://github.com/tonera/vitoom) 及中文文档 [docker-usage-cn.md](https://github.com/tonera/vitoom/blob/main/docker-usage-cn.md)。

### 1. 环境准备

需要 Docker、Docker Compose，以及用于推理的 NVIDIA GPU（驱动需支持 **CUDA 13.0**，与 vitoom `cu130` 推理镜像一致）。确认 GPU 可用：

```bash
docker run --rm --gpus all nvidia/cuda:13.0.0-base-ubuntu24.04 nvidia-smi
```

### 2. 生成配置并拉取镜像

在 vitoom 仓库根目录执行安装向导（推荐）：

```bash
git clone https://github.com/tonera/vitoom.git
cd vitoom
python scripts/setup_vitoom.py
```

或手动复制 `.env.example` 为 `.env` 并填写必填项（`VITOOM_BACKEND_URL`、`VITOOM_WS_URL`、`VITOOM_INFERENCE_UPLOAD_AUTH_SECRET` 等），然后拉取镜像：

```bash
python scripts/load_vitoom_images.py --components backend,visual
```

### 3. 启动服务

启动 Backend：

```bash
docker compose up -d backend
```

浏览器访问 `http://127.0.0.1:8888`（端口以 `.env` 中 `VITOOM_SERVER_PORT` 为准）。

启动 Visual 推理服务（FLUX.2 Klein 属于图片模型，需此 profile）：

```bash
docker compose -f docker-compose.inference.release.yml --profile visual up -d
```

可选：运行 `python scripts/download_initial_models.py` 批量下载常用模型；或将权重放入宿主机 `resources/models`（路径可在 `.env` 中通过 `VITOOM_MODELS_HOST_DIR` 自定义）。

### 4. 在 Web UI 中使用本模型

1. 登录 vitoom Web UI，进入 **Models**，下载并激活 **`tonera/FLUX.2-klein-4B-Nunchaku`**
2. 进入 **Image** 工作区，选择已激活的 FLUX.2 Klein 4B 模型，进行文生图或图片编辑（支持多参考图编辑）

也可在 vitoom Visual 推理容器内直接运行上文 Python 示例脚本。

## 关于 LoRA 使用

FLUX.2 Klein 系列已支持在量化 Transformer 上叠加 LoRA。使用 **vitoom-nunchaku**（wheel 或 vitoom Visual 镜像）即可，**无需手动复制任何文件**：

```python
lora_path = "/path/to/your_lora.safetensors"
transformer.update_lora_params(lora_path)
transformer.set_lora_strength(0.8)
```

## 许可与合规

量化权重衍生于 **FLUX.2-klein-4B**。上游模型遵循 [Apache 2.0](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B)；商用或再分发前请自行确认上游许可条款及 Black Forest Labs 的可接受使用政策。