--- pipeline_tag: image-to-image library_name: diffusers tags: - FLUX - FLUX.2 - Klein - kv-cache - quantization - svdquant - nunchaku - fp4 - int4 base_model: black-forest-labs/FLUX.2-klein-9b-kv base_model_relation: quantized license: other --- # 模型说明（SVDQuant / Nunchaku / KV-Cache） > **文档语言**：中文｜[English](README.md) ![Teaser](./editing.jpg) ## 模型与上游 - **量化权重仓库**：[`tonera/FLUX.2-klein-9B-kv-Nunchaku`](https://huggingface.co/tonera/FLUX.2-klein-9b-kv-Nunchaku) - **官方全精度源模型**：[`black-forest-labs/FLUX.2-klein-9b-kv`](https://huggingface.co/black-forest-labs/FLUX.2-klein-9b-kv) - **本仓库中的量化 Transformer**：`svdq-_r32-FLUX.2-klein-9B-kv-Nunchaku.safetensors`；`` 请按环境与 Nunchaku 构建使用 `nunchaku.utils.get_precision()`（常见为 `fp4` 或 `int4`）拼入文件名 - **Diffusers 侧配套文件**（VAE、text encoder 等）：与 Hugging Face 仓库根目录保持一致，加载 pipeline 时使用同一 `from_pretrained` 路径即可 `FLUX.2 [klein] 9B-KV` 是 `FLUX.2 [klein] 9B` 的 KV-cache 优化变体，重点面向**多参考图编辑**与**重复使用同一参考图的交互式工作流**。它在首个去噪步骤中缓存参考图 token 的 key-value 对，在后续步骤中复用缓存，从而避免重复计算；上游模型卡给出的加速收益在多参考编辑场景中最高可达 **2.5x**。 ## 上游模型卡关键信息 - **能力范围**：保留 FLUX.2 klein 9B 的核心能力，支持文生图、图生图和多参考编辑 - **KV-Cache 机制**： - `Step 0`：完整前向，处理参考图 token 并抽取 KV cache - `Step 1-3`：直接复用缓存，跳过重复的参考图计算 - **适用场景**：多参考编辑、基于同一参考图反复生成变体、低延迟交互式图像编辑应用 - **模型形态**：9B flow model，搭配 8B Qwen3 text embedder，蒸馏为常用 **4 步推理** - **官方推理栈**：Diffusers 中使用 `Flux2KleinKVPipeline` - **API 可用性**：上游模型卡说明可通过 [BFL API](https://bfl.ai/) 使用与非 KV 版本相比，这个变体的主要区别不是“更换任务类型”，而是在**参考图重复参与去噪**时减少冗余计算。因此，当你的工作流会反复复用相同参考图时，KV 版通常更合适。 ## 量化质量（本仓库评测摘录） | 指标 | 均值 | 中位数 p50 | p90 | |------|------|------------|-----| | PSNR | 22.10 | 22.35 | 25.58 | | SSIM | 0.876 | 0.877 | 0.933 | | LPIPS | 0.0734 | 0.0714 | 0.114 | ## 性能测试（RTX 5090 32GB，8 steps，guidance scale = 1.0）以下测试结果与 `FLUX.2-klein-9B-Nunchaku` 共用，可作为这两个模型的统一性能参考。 - `Base` = `black-forest-labs/FLUX.2-klein-9B` - `TE` = `svdq-int4-Qwen3-text-Nunchaku.safetensors` - `TR` = `svdq-{precision}_r32-FLUX.2-klein-9B-Nunchaku.safetensors` - `MCO` = `enable-model-cpu-offload` - `SCO` = `enable-sequential-cpu-offload` ### 图片编辑（1024x1024） | 方案 | 运行方式 | 峰值显存 | 吞吐 | 出图时间 | 吞吐变化（相对原生） | 显存变化（相对原生） | |---|---|---:|---:|---:|---:|---:| | `Base` | `CUDA` | OOM | - | - | 基线不可用 | 基线不可用 | | `Base` | `MCO` | 20.18 GB | 0.62 it/s | 12 s | 基线 | 基线 | | `Base` | `SCO` | 2.55 GB | 0.48 it/s | 16 s | 基线 | 基线 | | `Base + TE` | `CUDA` | 25.60 GB | 1.28 it/s | 6 s | N/A（原生 OOM） | N/A | | `Base + TE` | `MCO` | 20.16 GB | 0.83 it/s | 9 s | +33.9% | -0.1% | | `Base + TE` | `SCO` | 6.08 GB | 0.48 it/s | 16 s | -0.5% | +138.4% | | `Base + TR` | `CUDA` | 24.51 GB | 3.79 it/s | 2 s | N/A（原生 OOM） | N/A | | `Base + TR` | `MCO` | 17.39 GB | 1.08 it/s | 7 s | +75.0% | -13.8% | | `Base + TR` | `SCO` | 4.35 GB | 2.70 it/s | 2 s | +461.6% | +70.6% | | `Base + TR + TE` | `CUDA` | 14.00 GB | 3.81 it/s | 2 s | N/A（原生 OOM） | N/A | | `Base + TR + TE` | `MCO` | 7.52 GB | 1.88 it/s | 4 s | +204.6% | -62.7% | | `Base + TR + TE` | `SCO` | 7.69 GB | 2.68 it/s | 2 s | +457.4% | +201.6% | ### 文生图（1024x1024） | 方案 | 运行方式 | 峰值显存 | 吞吐 | 出图时间 | 吞吐变化（相对原生） | 显存变化（相对原生） | |---|---|---:|---:|---:|---:|---:| | `Base` | `CUDA` | OOM | - | - | 基线不可用 | 基线不可用 | | `Base` | `MCO` | 18.53 GB | 0.83 it/s | 9 s | 基线 | 基线 | | `Base` | `SCO` | 2.55 GB | 0.62 it/s | 12 s | 基线 | 基线 | | `Base + TR + TE` | `CUDA` | 15.21 GB | 8.91 it/s | <1 s | N/A（原生 OOM） | N/A | | `Base + TR + TE` | `MCO` | 6.42 GB | 2.60 it/s | 3 s | +214.5% | -65.4% | | `Base + TR + TE` | `SCO` | 7.72 GB | 3.00 it/s | 2 s | +383.0% | +202.7% | 在 `MCO` 下，`Base + TR + TE` 仍然是速度与显存更均衡的方案：图片编辑时显存从 20.18 GB 降到 7.52 GB，吞吐提升到原生的约 3.05 倍；文生图时显存从 18.53 GB 降到 6.42 GB，吞吐提升到原生的约 3.15 倍。`SCO` 下量化通常也能显著提速，但峰值显存不一定继续下降，因为原生 `SCO` 基线已经非常激进地压缩了显存占用。 ## 推理栈 - **引擎**：[Nunchaku](https://github.com/nunchaku-ai/nunchaku)（FP4/INT4 等低比特推理与 SVDQuant 权重） - **框架**：需支持 `Flux2KleinKVPipeline` 的 Diffusers（官方示例为从源码安装）： ```bash pip install "git+https://github.com/huggingface/diffusers.git" ``` Nunchaku 安装请优先遵循官方文档：[安装说明](https://nunchaku.tech/docs/nunchaku/installation/installation.html)（按 Python / PyTorch / CUDA 选择对应 wheel）。 ## FLUX.2 Klein 与 Nunchaku 合并状态（截至 2026-03-30）该架构的 Nunchaku 支持尚在合并流程中，跟踪 PR：**[nunchaku-ai/nunchaku#926](https://github.com/nunchaku-ai/nunchaku/pull/926)**。当前 published 的 Nunchaku 发行版可能尚未包含 `NunchakuFlux2Transformer2DModel`。 **在 PR 合并前想本地试用**：从本仓库（或 PR 分支）取得源码后： 1. 将 **`torch_transfer_utils.py`** 放到已安装包内的 **`nunchaku/`** 目录； 2. 将 **`transformer_flux2.py`** 放到 **`nunchaku/models/transformers/`** 目录；然后通过子模块路径导入（合并后一般可改为 `from nunchaku import NunchakuFlux2Transformer2DModel`）。如果你是 **ComfyUI** 用户，通常也需要从上述 **PR 分支**拉取代码并自行编译后再使用。 ## 最小示例（KV Pipeline + 量化 Transformer）以下示例假设已按需拷贝上述文件，且权重在本地或通过 `tonera/FLUX.2-klein-9B-kv-Nunchaku` 可访问；请将 `REPO` 换成你的本地目录或 Hugging Face ID。 ```python import torch from diffusers import Flux2KleinKVPipeline from diffusers.utils import load_image from nunchaku.models.transformers.transformer_flux2 import NunchakuFlux2Transformer2DModel from nunchaku.utils import get_precision REPO = "tonera/FLUX.2-klein-9B-kv-Nunchaku" # 或本地绝对路径 NAME = "FLUX.2-klein-9B-kv-Nunchaku" transformer = NunchakuFlux2Transformer2DModel.from_pretrained( f"{REPO}/svdq-{get_precision()}_r32-{NAME}.safetensors", torch_dtype=torch.bfloat16, ) pipe = Flux2KleinKVPipeline.from_pretrained( REPO, torch_dtype=torch.bfloat16, transformer=transformer ) pipe.to("cuda") # transformer.set_offload( # True, use_pin_memory=False, num_blocks_on_gpu=1 # ) # pipeline._exclude_from_cpu_offload.append("transformer") # pipeline.enable_sequential_cpu_offload() # 文生图（不传 image） image = pipe( prompt="A cat holding a sign that says hello world", height=1024, width=1024, num_inference_steps=4, generator=torch.Generator(device="cuda").manual_seed(0), ).images[0] image.save("t2i_output.png") # 图生图 / 参考图编辑（KV cache 生效的典型场景） ref = load_image("https://example.com/your_ref.png").convert("RGB") image_kv = pipe( prompt="A cat dressed like a wizard", image=ref, height=1024, width=1024, num_inference_steps=4, generator=torch.Generator(device="cuda").manual_seed(0), ).images[0] image_kv.save("kv_output.png") ``` 如果你会对**同一张参考图连续生成多个变体**，KV 版的优势通常会更明显。显存紧张时可按需使用 `pipe.enable_model_cpu_offload()` 等策略。 ## 你也可以直接在本地docker安装[vitoom](https://github.com/tonera/vitoom)体验更强大能力 ``` https://github.com/tonera/vitoom ``` ## 限制、硬件与合规 - **限制**：上游模型卡指出，该模型不用于提供事实信息；生成文字可能失真；输出可能反映训练数据中的偏差；提示词跟随能力也会受到提示风格影响 - **超出许可范围的用途**：不得用于非法、欺诈、诽谤、骚扰等违反使用政策的场景 - **硬件参考**：上游模型卡给出的原始 KV 版本参考需求约为 **29GB VRAM**，面向 **RTX 5090 及以上**；量化后实际显存占用约为 **17GB**。如果配合**tonera/Qwen3-text-Nunchaku**，显存占用将进一步大幅度下降。 - **责任 AI**：Black Forest Labs 在发布前进行了包括 CSAM 和 NCII 在内的风险评估与缓解，详情见其安全说明；安全问题可联系 `safety@blackforestlabs.ai` ## 许可与说明量化权重衍生于 **FLUX.2-klein-9b-kv**，使用须遵守 [FLUX Non-Commercial License](https://huggingface.co/black-forest-labs/FLUX.2-klein-9b-kv-fp8/blob/main/LICENSE) 及 Black Forest Labs 的可接受使用政策；商用请单独确认授权。模型卡 YAML 中的 `license: other` 仅因 Hugging Face 元数据许可证字段为固定枚举，未单独列出 FLUX 非商用许可；**具有约束力的是上文链接的协议条款**，而非 `other` 这一占位标签本身。