README_CN.md

metadata

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

模型与上游

• 量化权重仓库：tonera/FLUX.2-klein-9B-kv-Nunchaku
• 官方全精度源模型：black-forest-labs/FLUX.2-klein-9b-kv
• 本仓库中的量化 Transformer：svdq-<precision>_r32-FLUX.2-klein-9B-kv-Nunchaku.safetensors；<precision> 请按环境与 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 使用

与非 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（FP4/INT4 等低比特推理与 SVDQuant 权重）
• 框架：需支持 Flux2KleinKVPipeline 的 Diffusers（官方示例为从源码安装）：

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

Nunchaku 安装请优先遵循官方文档：安装说明（按 Python / PyTorch / CUDA 选择对应 wheel）。

FLUX.2 Klein 与 Nunchaku 合并状态（截至 2026-03-30）

该架构的 Nunchaku 支持尚在合并流程中，跟踪 PR：**nunchaku-ai/nunchaku#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。

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

限制、硬件与合规

• 限制：上游模型卡指出，该模型不用于提供事实信息；生成文字可能失真；输出可能反映训练数据中的偏差；提示词跟随能力也会受到提示风格影响
• 超出许可范围的用途：不得用于非法、欺诈、诽谤、骚扰等违反使用政策的场景
• 硬件参考：上游模型卡给出的原始 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 及 Black Forest Labs 的可接受使用政策；商用请单独确认授权。

模型卡 YAML 中的 license: other 仅因 Hugging Face 元数据许可证字段为固定枚举，未单独列出 FLUX 非商用许可；具有约束力的是上文链接的协议条款，而非 other 这一占位标签本身。