论文 | 文档 | 官网 | 博客 | 演示 | Hugging Face | ModelScope | ComfyUI

Nunchaku 是一款针对 4 位神经网络优化的高性能推理引擎，如我们在论文 SVDQuant 中所介绍。有关底层量化库，请查看 DeepCompressor。

欢迎加入我们的用户群组——Discord 和 WeChat，与社区成员一起交流讨论！更多详情请参阅 这里。如果您有任何问题、遇到任何困难，或有意参与贡献，请随时联系我们！

新闻

• [2026-01-12] 🚀 v1.2.0 发布！ 享受 Z-Image 性能提升 20–30%，无缝支持 LoRA 并配备原生 ComfyUI 节点，新增 20 系列显卡的 INT4 支持，以及 与 ComfyUI 0.7 的兼容性！
• [2025-12-20] 🔥 推出 4 位 Tongyi-MAI/Z-Image-Turbo！您可以在 Hugging Face 或 ModelScope 上下载，并使用我们的示例脚本 [examples/v1/z-image-turbo.py] 进行体验。
• [2025-09-25] 🔥 推出 4 位 4/8 步闪电版 Qwen-Image-Edit-2509！您可以在 Hugging Face 或 ModelScope 上下载，并使用我们的示例脚本 [examples/v1/qwen-image-edit-2509-lightning.py] 进行尝试。
• [2025-09-24] 🔥 发布了 4 位 Qwen-Image-Edit-2509！相关模型已在 Hugging Face 上架。您可以使用我们的示例脚本 [examples/v1/qwen-image-edit-2509.py] 来体验。闪电版本也将随后推出！

更多

• [2025-09-09] 🔥 发布了 4-bit Qwen-Image-Edit，同时推出了 4/8-step Lightning 变体！模型已在 Hugging Face 上架。请使用我们的 示例脚本 体验。
• [2025-09-04] 🚀 正式发布 Nunchaku v1.0.0！Qwen-Image 现已支持 异步卸载，在不损失性能的情况下，显存占用可低至 3 GiB。请查看 教程 以开始使用。
• [2025-08-27] 🔥 发布了 4-bit 4/8-step lightning Qwen-Image！可在 Hugging Face 或 ModelScope 下载，并使用我们的 示例脚本 进行尝试。
• [2025-08-15] 🔥 我们的 4-bit Qwen-Image 模型现已上线 Hugging Face！请使用我们的 示例脚本 开始体验。ComfyUI、LoRA 和 CPU 卸载支持即将推出！
• [2025-08-15] 🚀 Python 后端现已可用！请在此处探索我们的 Python 风格 FLUX 模型 [nunchaku/models/transformers/transformer_flux_v2.py]，并查看模块化的 4-bit 线性层 [nunchaku/models/linear.py]。
• [2025-07-31] 🚀 FLUX.1-Krea-dev 现已支持！ 请查看我们的新 示例脚本 以开始使用。
• [2025-07-13] 🚀 官方 Nunchaku 文档 现已上线！探索全面的指南和资源，帮助您快速入门。
• [2025-06-29] 🔥 支持 FLUX.1-Kontext！请尝试我们的 示例脚本 来体验其效果！演示链接为：[https://svdquant.mit.edu/kontext/]！
• [2025-06-01] 🚀 发布 v0.3.0！ 此次更新新增多批次推理支持、ControlNet-Union-Pro 2.0、初步集成 PuLID，并引入了 双 FB 缓存。现在您可以将 Nunchaku FLUX 模型加载为单个文件，而我们升级的 4-bit T5 编码器 在质量上已与 FP8 T5 相当！
• [2025-04-16] 🎥 发布了教学视频，分别提供 英语 和 中文 版本，帮助用户完成安装和使用。
• [2025-04-09] 📢 发布了 四月路线图 和 常见问题解答，以帮助社区快速上手并及时了解 Nunchaku 的开发进展。
• [2025-04-05] 🚀 Nunchaku v0.2.0 发布！ 本次版本带来了 多 LoRA 和 ControlNet 支持，并借助 FP16 注意力机制 和 首块缓存 实现更快速的性能。此外，我们还增加了对 20 系列 GPU 的兼容性——Nunchaku 如今比以往更加易用！
• [2025-03-07] 🚀 Nunchaku v0.1.4 发布！ 我们新增了 4-bit 文本编码器及逐层 CPU 卸载 功能，使 FLUX 的最低内存需求降至仅 4 GiB，同时保持 2–3 倍加速。此次更新还修复了与分辨率、LoRA、固定内存及运行稳定性相关的多项问题。详情请参阅发行说明！
• [2025-02-20] 🚀 支持 NVIDIA RTX 5090 上的 NVFP4 精度！ 与 INT4 相比，NVFP4 能提供更优质的图像质量，在 RTX 5090 上相比 BF16 可实现 约 3 倍加速。更多信息请参阅我们的 博客，并查看 examples 了解使用方法，或在线试用我们的 演示！
• [2025-02-18] 🔥 自定义 LoRA 转换 和 模型量化 指南现已发布！ComfyUI 工作流现已支持 自定义 LoRA，并兼容 FLUX.1-Tools！
• [2025-02-11] 🎉 SVDQuant 被选为 ICLR 2025 Spotlight！FLUX.1-tools Gradio 演示现已上线！ 请参阅 此处 获取使用详情！我们全新的 深度转图像演示 也已上线——快来试试吧！
• [2025-02-04] 🚀 4-bit FLUX.1-tools 已发布！ 相较于原版模型，速度提升 2–3 倍。请查看 examples 了解使用方法。ComfyUI 集成即将推出！
• [2025-01-23] 🚀 4-bit SANA 支持现已上线！ 相比 16 位模型，速度提升 2–3 倍。请查看 使用示例 和 部署指南，了解更多细节。欢迎访问 svdquant.mit.edu 观看我们的实时演示！
• [2025-01-22] 🎉 SVDQuant 已被 ICLR 2025 接受！
• [2024-12-08] 支持 ComfyUI。请查阅 ComfyUI-nunchaku 了解使用方法。
• [2024-11-07] 🔥 我们的最新 W4A4 扩散模型量化工作 SVDQuant 已公开发布！量化库请参阅 DeepCompressor。

概述

Nunchaku 是一款面向低比特神经网络的高性能推理引擎。它实现了 SVDQuant，这是一种针对 4 位权重和激活的训练后量化技术，能够很好地保持视觉保真度。在 12B FLUX.1-dev 上，与 BF16 模型相比，内存占用减少了 3.6 倍。通过消除 CPU 数据交换，Nunchaku 在配备 16GB 显存的笔记本电脑 RTX 4090 GPU 上运行时，相比 16 位模型提速 8.7 倍，比 NF4 W4A16 基线快 3 倍。在 PixArt-∑ 上，Nunchaku 展现出显著优于其他 W4A4 甚至 W4A8 基线的视觉质量。“E2E”表示包括文本编码器和 VAE 解码器在内的端到端延迟。

SVDQuant：通过低秩组件吸收异常值以实现 4 位扩散模型量化
Muyang Li*, Yujun Lin*, Zhekai Zhang*, Tianle Cai, Xiuyu Li, Junxian Guo, Enze Xie, Chenlin Meng, Jun-Yan Zhu，以及 Song Han
MIT、NVIDIA、CMU、普林斯顿大学、加州大学伯克利分校、上海交通大学及 Pika Labs

https://github.com/user-attachments/assets/fdd4ab68-6489-4c65-8768-259bd866e8f8

方法

量化方法——SVDQuant

SVDQuant 的概述。阶段 1：原本，激活 $\boldsymbol{X}$ 和权重 $\boldsymbol{W}$ 中都存在异常值，这使得 4 位量化颇具挑战性。阶段 2：我们将激活中的异常值迁移到权重中，从而得到更新后的激活 $\hat{\boldsymbol{X}}$ 和权重 $\hat{\boldsymbol{W}}$。此时，$\hat{\boldsymbol{X}}$ 更容易量化，而 $\hat{\boldsymbol{W}}$ 则变得更加困难。阶段 3：SVDQuant 进一步利用奇异值分解（SVD）将 $\hat{\boldsymbol{W}}$ 分解为低秩分量 $\boldsymbol{L}_1\boldsymbol{L}_2$ 和残差 $\hat{\boldsymbol{W}}-\boldsymbol{L}_1\boldsymbol{L}_2$。由此，低秩分支以 16 位精度运行，缓解了量化难度。

Nunchaku 引擎设计

(a) 如果天真地以秩 32 运行低秩分支，由于 Down Projection 中额外读取 16 位输入以及 Up Projection 中额外写入 16 位输出，将会引入 57% 的延迟开销。Nunchaku 通过内核融合优化了这一开销。(b) Down Projection 和 Quantize 内核使用相同的输入，而 Up Projection 和 4-Bit Compute 内核共享相同的输出。为了减少数据移动开销，我们将前两个内核和后两个内核分别融合在一起。

性能

SVDQuant 将 12B FLUX.1 模型大小压缩至原来的 1/3.6，并使 16 位模型的内存占用降低 3.5 倍。借助 Nunchaku，我们的 INT4 模型在台式机和笔记本电脑上的 NVIDIA RTX 4090 GPU 上均比 NF4 W4A16 基线快 3.0 倍。值得注意的是，在笔记本电脑 RTX 4090 上，通过消除 CPU 数据交换，总加速高达 10.1 倍。我们的 NVFP4 模型在 RTX 5090 GPU 上也比 BF16 和 NF4 快 3.1 倍。

开始使用

• 安装指南
• 使用教程
• ComfyUI 插件：ComfyUI-nunchaku
• 自定义模型量化：DeepCompressor
• Gradio 演示应用
• 重现 SVDQuant 论文结果
• API 参考
• 贡献指南
• 常见问题解答

联系我们

对于有意采用 SVDQuant 或 Nunchaku 的企业，包括技术咨询、赞助机会或合作洽谈，请通过 muyangli@nunchaku.tech 与我们联系。

相关项目

• 用于条件 GAN 和扩散模型的高效空间稀疏推理，NeurIPS 2022 & T-PAMI 2023
• SmoothQuant：大型语言模型的准确且高效的训练后量化，ICML 2023
• Q-Diffusion：扩散模型量化，ICCV 2023
• AWQ：面向 LLM 压缩与加速的激活感知权重量化，MLSys 2024
• DistriFusion：高分辨率扩散模型的分布式并行推理，CVPR 2024
• QServe：W4A8KV4 量化与系统协同设计，用于高效 LLM 推理，MLSys 2025
• SANA：基于线性扩散 Transformer 的高效高分辨率图像合成，ICLR 2025
• Sparse VideoGen：利用时空稀疏性加速视频扩散 Transformer，ICML 2025
• Radial Attention：具有能量衰减的 $O(n \log n)$ 稀疏注意力，用于长视频生成，NeurIPS 2025
• Sparse VideoGen2：通过语义感知置换结合稀疏注意力加速视频生成，NeurIPS 2025

引用

如果您认为 nunchaku 对您的研究有用或相关，请引用我们的论文：

@inproceedings{
  li2024svdquant,
  title={SVDQuant: Absorbing Outliers by Low-Rank Components for 4-Bit Diffusion Models},
  author={Li*, Muyang and Lin*, Yujun and Zhang*, Zhekai and Cai, Tianle and Li, Xiuyu and Guo, Junxian and Xie, Enze and Meng, Chenlin and Zhu, Jun-Yan and Han, Song},
  booktitle={The Thirteenth International Conference on Learning Representations},
  year={2025}
}

致谢

我们感谢麻省理工-IBM沃森人工智能实验室、麻省理工学院和亚马逊科学中心、麻省理工学院人工智能硬件项目、美国国家科学基金会、帕卡德基金会、戴尔、LG、现代汽车以及三星对本研究的支持。同时，我们也感谢英伟达捐赠的DGX服务器。此外，我们还要感谢First Intelligence和Yotta Labs慷慨赞助我们的计算资源。

我们使用img2img-turbo来训练草图到图像的LoRA模型。我们的文本到图像和图像到图像用户界面分别基于playground-v.25和img2img-turbo构建。我们的安全检查器则借鉴自hart。

Nunchaku也受到众多开源库的启发，其中包括（但不限于）TensorRT-LLM、vLLM、QServe、AWQ、FlashAttention-2以及Atom。

星标历史

Nunchaku 快速上手指南

Nunchaku 是一个专为 4-bit 神经网络设计的高性能推理引擎，基于 SVDQuant 量化技术。它能在显著降低显存占用（如 FLUX.1-dev 模型减少 3.6 倍）的同时，提供比原始 16-bit 模型快 2-3 倍甚至更高的推理速度，并保持良好的图像生成质量。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04+) 或 Windows (WSL2 支持)
• GPU: NVIDIA GPU (推荐 RTX 30/40/50 系列)
  • 支持 20 系列显卡（需 INT4 模式）
  • 5090 等新款显卡支持 NVFP4 精度以获得更佳性能
• 显存:
  • 最低 4 GiB (开启 CPU Offloading 模式)
  • 推荐 12 GiB+ 以获得最佳无卸载性能
• Python: 3.9 - 3.11

前置依赖

确保已安装以下基础依赖：

• CUDA Toolkit (版本需与 PyTorch 匹配，推荐 12.1+)
• Git
• pip

安装步骤

1. 创建虚拟环境（推荐）

python -m venv nunchaku-env
source nunchaku-env/bin/activate  # Linux/Mac
# 或
nunchaku-env\Scripts\activate     # Windows

2. 安装 PyTorch

请根据你的 CUDA 版本安装对应的 PyTorch。以下为 CUDA 12.1 示例：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

国内加速建议：如遇下载缓慢，可使用清华源或阿里源镜像安装 PyTorch，或直接访问 PyTorch 官网 获取对应命令。

3. 安装 Nunchaku

通过 pip 直接安装最新稳定版：

pip install nunchaku

若需使用 ComfyUI 集成，请额外安装专用插件：

git clone https://github.com/nunchaku-ai/ComfyUI-nunchaku.git
cp -r ComfyUI-nunchaku/custom_nodes/* <Your_ComfyUI_Path>/custom_nodes/

4. 验证安装

运行以下命令检查是否安装成功（以 Python 为例）：

import nunchaku
print(nunchaku.__version__)

基本使用

以下是一个最简单的 4-bit FLUX.1 模型推理示例。该脚本会自动从 Hugging Face 下载量化后的模型权重。

示例：生成一张图片

创建一个名为 generate.py 的文件，写入以下内容：

from nunchaku.models.transformers.transformer_flux_v2 import FluxTransformer2DModel
from diffusers import AutoencoderKL, FlowMatchEulerDiscreteScheduler
from transformers import T5EncoderModel, T5Tokenizer
import torch

# 配置设备
device = "cuda" if torch.cuda.is_available() else "cpu"
dtype = torch.bfloat16

# 加载 4-bit 量化模型 (自动处理量化逻辑)
transformer = FluxTransformer2DModel.from_pretrained(
    "nunchaku-ai/nunchaku-flux-dev", 
    torch_dtype=dtype,
    device_map=device
)

# 加载其他必要组件 (VAE, Scheduler, Text Encoder)
vae = AutoencoderKL.from_pretrained("black-forest-labs/FLUX.1-dev", subfolder="vae", torch_dtype=dtype).to(device)
scheduler = FlowMatchEulerDiscreteScheduler.from_pretrained("black-forest-labs/FLUX.1-dev", subfolder="scheduler")
tokenizer = T5Tokenizer.from_pretrained("google/t5-v1_1-xxl", torch_dtype=dtype)
text_encoder = T5EncoderModel.from_pretrained("google/t5-v1_1-xxl", torch_dtype=dtype).to(device)

# 提示词
prompt = "A cute cat sitting on a futuristic cyberpunk street, neon lights, highly detailed, 8k"
negative_prompt = ""

# 简单的推理循环 (伪代码示意，具体采样步骤需参考官方 examples/v1/qwen-image.py 或 flux 示例)
# 注意：实际使用时建议直接运行官方提供的完整示例脚本
input_ids = tokenizer(prompt, return_tensors="pt").input_ids.to(device)
hidden_states = text_encoder(input_ids)[0]

# 执行推理 (此处仅为示意，完整流程请参考官方示例脚本)
# noise = torch.randn((1, 4, 64, 64), device=device, dtype=dtype)
# ... (调度器步进逻辑)
# image = transformer(noise, timestep, hidden_states, ...) 
# decoded_image = vae.decode(image / vae.config.scaling_factor).sample

print("模型加载成功，就绪进行推理。请参考 examples/ 目录下的完整脚本运行生成任务。")

运行官方示例（推荐）

为了获得最稳定的体验，建议直接运行仓库中提供的经过测试的示例脚本。例如运行 Qwen-Image 或 FLUX 的 4-bit 推理：

# 克隆仓库获取示例脚本
git clone https://github.com/nunchaku-ai/nunchaku.git
cd nunchaku

# 运行 FLUX.1-dev 示例 (需确保已安装依赖)
python examples/v1/flux.1-dev.py \
    --prompt "Astronaut in a jungle, cold color palette, muted colors, detailed, 8k" \
    --model_path "nunchaku-ai/nunchaku-flux-dev"

提示：更多模型（如 Qwen-Image-Edit, SANA, Z-Image-Turbo）的示例脚本可在 examples/ 目录下找到。对于低显存用户，可查阅文档开启 CPU Offloading 模式以将显存占用降至 3-4 GiB。