Nunchaku：高效运行FLUX.1 和 SANA 4位量化模型的推理工具

Nunchaku 是由 MIT HAN Lab 开发的一个开源推理引擎，专注于高效运行4位量化的扩散模型。它通过 SVDQuant 技术，将模型的权重和激活量化为4位，显著降低内存占用和推理延迟。Nunchaku 支持 FLUX 和 SANA 等扩散模型，适用于图像生成、编辑和转换等任务。它与 ComfyUI 集成，提供用户友好的操作界面，适合研究人员和开发者在低资源设备上运行复杂模型。项目在 GitHub 上开源，社区活跃，提供详细文档和示例脚本，方便用户快速上手。

功能列表

• 支持4位量化扩散模型推理，内存占用降低3.6倍，速度提升最高8.7倍。
• 兼容 FLUX.1 系列模型，包括 FLUX.1-dev、FLUX.1-schnell 和 FLUX.1-tools。
• 提供文本到图像、草图到图像、深度图/边缘图到图像、图像修复等多种生成任务。
• 支持 LoRA 加载，允许用户加载自定义模型以增强生成效果。
• 集成 ComfyUI，提供节点式操作界面，简化工作流配置。
• 支持自然语言图像编辑，通过 FLUX.1-Kontext-dev 实现文本驱动的图像修改。
• 提供 FP16 精度支持，优化模型性能和生成质量。
• 提供 PuLID v0.9.1 集成，支持自定义模型路径和 timestep 控制。

使用帮助

安装流程

Nunchaku 的安装需要确保系统满足基本要求，包括 PyTorch、CUDA 和特定编译器。以下是详细的安装步骤，适用于 Linux 和 Windows 系统。

环境准备

1. 安装 PyTorch：确保安装 PyTorch 2.6 或更高版本。例如，使用以下命令安装 PyTorch 2.6：

   pip install torch==2.6 torchvision==0.21 torchaudio==2.6
   

   如果使用 Blackwell GPU（如 RTX 50 系列），需要 PyTorch 2.7 及 CUDA 12.8 或更高版本。

2. 检查 CUDA 版本：Linux 需要 CUDA 12.2 及以上，Windows 需要 CUDA 12.6 及以上。
3. 安装编译器：
   • Linux：确保安装 gcc/g++ 11 或更高版本，可通过 Conda 安装：

     conda install -c conda-forge gcc gxx
     

   • Windows：安装最新版本的 Visual Studio，确保包含 C++ 开发组件。
4. 安装依赖：安装必要的 Python 包：

   pip install ninja wheel diffusers transformers accelerate sentencepiece protobuf huggingface_hub
   

   如果需要运行 Gradio 演示，额外安装：

   pip install peft opencv-python gradio spaces
   

安装 Nunchaku

1. 从 Hugging Face 安装：根据 Python 和 PyTorch 版本选择合适的 wheel 文件。例如，Python 3.11 和 PyTorch 2.6：

   pip install https://huggingface.co/mit-han-lab/nunchaku/resolve/main/nunchaku-0.2.0+torch2.6-cp311-cp311-linux_x86_64.whl
   

   Windows 用户可使用：

   pip install https://huggingface.co/mit-han-lab/nunchaku/resolve/main/nunchaku-0.1.4+torch2.6-cp312-cp312-win_amd64.whl
   

2. 从源码安装（可选）：

   git clone https://github.com/mit-han-lab/nunchaku.git
   cd nunchaku
   git submodule init
   git submodule update
   export NUNCHAKU_INSTALL_MODE=ALL
   python setup.py develop
   

   注意：设置 NUNCHAKU_INSTALL_MODE=ALL 确保生成的 wheel 文件兼容不同 GPU 架构。

ComfyUI 集成

1. 安装 ComfyUI：如果尚未安装 ComfyUI，可通过以下命令安装：

   git clone https://github.com/comfyanonymous/ComfyUI.git
   cd ComfyUI
   pip install -r requirements.txt
   

2. 安装 ComfyUI-nunchaku 插件：

   pip install comfy-cli
   comfy install
   comfy node registry-install ComfyUI-nunchaku
   

   或者通过 ComfyUI 的 Custom Nodes Manager 搜索并安装 ComfyUI-nunchaku。

3. 下载模型：将必要的模型文件下载到指定目录。例如：

   huggingface-cli download comfyanonymous/flux_text_encoders clip_l.safetensors --local-dir models/text_encoders
   huggingface-cli download comfyanonymous/flux_text_encoders t5xxl_fp16.safetensors --local-dir models/text_encoders
   huggingface-cli download black-forest-labs/FLUX.1-schnell ae.safetensors --local-dir models/vae
   

4. 复制工作流：将示例工作流复制到 ComfyUI 目录：

   mkdir -p user/default/example_workflows
   cp custom_nodes/nunchaku_nodes/example_workflows/* user/default/example_workflows/
   

5. 运行 ComfyUI：

   cd ComfyUI
   python main.py
   

主要功能操作

Nunchaku 提供多种图像生成和编辑功能，以下是具体操作方法。

文本到图像生成

1. 打开 ComfyUI，加载 Nunchaku 工作流（如 nunchaku-flux.1-dev-pulid.json）。
2. 在工作流中选择 Nunchaku Text Encoder Loader，设置 use_4bit_t5=True 以使用 4 位量化的 T5 文本编码器，节省内存。
3. 指定 t5_min_length=512 以提高图像质量。
4. 输入文本提示，例如“a futuristic city at sunset”，调整生成参数（如采样步数、引导尺度）。
5. 运行工作流，生成图像。

图像编辑（FLUX.1-Kontext-dev）

1. 加载 FLUX.1-Kontext-dev 模型，启用自然语言图像编辑功能。
2. 上传需要编辑的图像，输入编辑指令，例如“add a bright moon in the sky”。
3. 调整 start_timestep 和 end_timestep 参数，控制编辑的强度和范围。
4. 执行生成，查看编辑后的图像。

草图到图像

1. 在 ComfyUI 中选择 Sketch-to-Image 工作流。
2. 上传草图图像，设置生成参数。
3. 运行工作流，生成基于草图的图像。

LoRA 加载

1. 下载或训练自定义 LoRA 模型，保存到 models/lora 目录。
2. 在 ComfyUI 工作流中添加 LoRA Loader 节点，指定 LoRA 模型路径。
3. 运行工作流，应用 LoRA 增强的生成效果。

注意事项

• 确保 GPU 架构兼容（支持 Turing、Ampere、Ada、A100 等架构）。
• 检查日志输出以确认 Python 可执行文件路径，特别是在 ComfyUI 便携版中。
• 如果遇到安装问题，可参考官方文档 docs/setup_windows.md 或教程视频。

应用场景

1. AI 艺术创作
   艺术家使用 Nunchaku 生成高质量的艺术图像。用户输入文本描述或上传草图，快速生成符合创意的图像，适合概念设计和艺术探索。
2. 研究与开发
   研究人员利用 Nunchaku 在低资源设备上测试 4 位量化模型。它的低内存占用和高推理速度适合学术实验和模型优化。
3. 图像编辑与修复
   摄影师或设计师通过自然语言指令编辑图像，例如修复瑕疵或添加元素，简化后期处理流程。
4. 教育与学习
   学生和初学者使用 Nunchaku 学习扩散模型的推理过程。ComfyUI 的节点式界面直观易懂，适合教学和实践。

QA

1. Nunchaku 支持哪些 GPU？
   Nunchaku 支持 NVIDIA GPU，包括 Turing（RTX 2080）、Ampere（RTX 3090, A6000）、Ada（RTX 4090）和 A100 架构。Blackwell GPU 需要 CUDA 12.8 及 PyTorch 2.7。
2. 如何在 Windows 上安装？
   安装 Visual Studio 和 CUDA 12.6 以上，使用 Hugging Face 的 Windows wheel 文件直接安装，或参考 docs/setup_windows.md。
3. 4位量化会影响图像质量吗？
   SVDQuant 技术通过低秩组件吸收异常值，保持视觉保真度。在 FLUX.1-dev 上，4位量化的图像质量接近 16 位模型。
4. 如何解决 ComfyUI 安装失败？
   确保 Python 环境与 ComfyUI 一致，检查日志中的 Python 可执行文件路径。使用 comfy-cli 或手动安装 ComfyUI-nunchaku。

应用示例

nunchaku-flux.1-kontext-dev AI生图一键整合包 最低4G 显卡可运行 30秒出图 v20250630

FLUX.1-Kontext-dev 整合包

此处内容已经被作者隐藏，请输入验证码查看内容

验证码：

请关注本站微信公众号，回复“验证码”，获取验证码。在微信里搜索“AI生产力应用”或者“Artificial9527”或者微信扫描右侧二维码都可以关注本站微信公众号。