[ComfyUI]Nunchaku双截棍-V1.0.1正式版上线,速度起飞！仅需10秒生图！

comfyui-nunchaku v1.0.1 更新
• 修复 Qwen-Image ControlNet 不生效的问题。
• 新增Qwen-Image 节点参数：
* num_block_on_gpus：在启用 cpu_offload 时，增大该值可降低 CPU 内存消耗，但会增加显存消耗。
* use_pin_memory：在启用 cpu_offload 时，打开该选项会增加内存消耗，但能加快速度。
👉 对于之前遇到**爆显存/爆内存/运行极慢**的用户，可以尝试关闭 use_pin_memory 并将 num_block_on_gpus 调整到 10–30。
• 修复之前安装节点不联网无法使用的问题。现在安装节点可以自动抓取版本库。自动抓取失败可以去https://nunchaku.tech/cdn/nunchaku_versions.json下载放到custom_nodes/ComfyUI-nunchaku里！

一、nunchaku介绍

Nunchaku 是由 MIT Han Lab 开发的 4位扩散模型高效推理引擎，专为优化生成式模型（如Stable Diffusion）的推理速度和显存占用设计。结合 SVDQuant量化技术，通过量化手段显著减少模型大小，同时保持视觉质量，并提供加速的推理性能。——更小的显存占用，更快的生成速度，带来很小的图片质量损失。nunchaku项目9月5日迎来更新

“双节棍v1.0.0正式发布！Qwen-Image现在支持异步卸载，将Transformer VRAM的使用量减少到3 GiB，而不会降低性能。”

「关键能力」

SVDQuant量化技术：通过低秩分解和核融合技术，将模型权重与激活值压缩至4位，显存占用减少3.6倍（如16GB显存可运行原需50GB的Flux.1-dev模型）。

多模态生态兼容：支持Flux模型生态、Redux、Lora、ControlNet及多显卡架构（NVIDIA Ampere/Ada/A100）。文生图、ControlNet重绘、修复等，速度提升8.7倍。

硬件级优化：针对NVIDIA CUDA架构优化，支持FP16/FP8混合精度计算，16G显卡实现3秒生成。

无损生成：通过低秩分解和核融合技术，解决传统4位量化图像模糊问题，LPIPS质量指标仅0.326（接近原版0.573），肉眼无差异。

更新记录：

[2025-08-22] 🚀 v1.0.0 新增对Qwen-Image的支持！查看示例工作流即可快速上手。LoRA支持即将推出。
[2025-07-17] 🚀 ComfyUI-nunchaku 官方文档上线！提供详细的入门指南和资源。
[2025-06-29] 📘 v0.3.3 现已支持 FLUX.1-Kontext-dev！可从 Hugging Face 或 魔搭社区 下载量化模型，并参考此 工作流 快速上手。
[2025-06-11] 自 v0.3.2 起，您可以通过此 工作流 轻松安装或升级 Nunchaku wheel 包！
[2025-06-07] 🚀 v0.3.1 补丁发布！ 恢复了 FB Cache 支持，修复了 4-bit 文本编码器加载问题。PuLID 节点现为可选，不会影响其他节点。新增 NunchakuWheelInstaller 节点，帮助您安装正确的 Nunchaku wheel。

二、相关安装（文末下载）

1、更新nunchaku V1.0.0节点：

https://github.com/nunchaku-tech/comfyui-nunchaku

自动安装：（网盘）

1.安装插件后，即可通过官方自动安装程序实现自动下载nunchaku轮子

网盘工作流-install_wheel.json拖入comfyui，选择对应的nunchaku版本，运行即可

手动安装：

2、安装轮子：

首先，需要看下自己的安装包中pytorch和python的版本是多少。

查看的方法是在启动的时候，后台页面中最顶部有python版本和pytorch的版本号，如下图，我的python版本就是3.12.7，pytorch版本就是2.5.1。

如果pytorch版本是小于2.5版本，那么需要先升级。（秋叶启动器：高级选项->环境维护->安装pythorch）

https://github.com/nunchaku-tech/nunchaku/releases/

找到适配你电脑环境版本相关轮子下载，轮子下载建议路径(示例路径)：  ComfyUI-aki-v1.7\ComfyUI\python
python文件夹中打开终端:

输入安装轮子命令：

python.exe -m pip install 拖入轮子文件 后回车

打开的页面里边输入：

python -m pip install "nunchaku-0.2.0+torch2.5-cp312-cp312-win_amd64.whl"

也可以指定：D:ComfyUI-aki-v1.6pythonpython.exe --m pip install "nunchaku-0.2.0+torch2.5-cp312-cp312-win_amd64.whl"

注意，引号里边要替换成你下载的版本的文件名称。

然后回车。重启运行nunchaku官方流。

如果爆显存。需要按第4步修改代码：

修改文件路径：

custom_nodes/comfyUI-nunchaku/models

调整默认值 ：
将 use_pin_memory 默认值从 True 改为 False（禁用 pinned memory）
将 num_blocks_on_gpu 默认值从 1 改为 4（增加 GPU 上保留的块数量）

正确设置 num_blocks_on_gpu 的方法
需根据 GPU 显存大小、模型总块数以及实际运行场景调整：

基本原则：
显存越小 → 数值越小（避免 OOM）。
显存越大 → 数值越大（提升速度）。

具体建议：
≤ 8GB 显存：建议设为 1~2（优先保证不溢出，例如你的 8GB 显存可尝试 2）。
10~16GB 显存：建议设为 4~8（平衡显存与速度）。
≥ 24GB 显存：可设为 8~16（最大化计算效率，减少数据传输）。
像我8G显存，1~4都可以。保证不溢出就设置成1。禁用 pinned memory

重启，运行就行了。

专用模型下载

模型下载地址：https://huggingface.co/mit-han-lab

除50系显卡外，所有显卡均使用INT4 模型（如果你是50系显卡，则需要下载标注有FP4的模型）；

模型文件安装路径：

..\ComfyUI\models\diffusion_models\

目前支持的模型已经比较全面，除基础的flux.1-dev外，还包括canny、depth、Fill、kontext模型。该模型下载界面显示模型较多，大家优先按照功能进入对应nunchaku开头的链接可以看到两个版本的模型直接进行下载，进入svdq-fp4或int4的链接下载的模型则需要自行重命名。

三、工作流及体验

一个典型的Nunchaku Flux工作流包含以下关键节点：

1. NunchakuModelLoader：加载Nunchaku优化的模型
2. CLIPTextEncode：输入提示词
3. EmptyLatentImage：设置图像尺寸
4. NunchakuSampler：Nunchaku优化的采样器
5. VAEDecode：解码最终图像

关键参数设置：

• steps：Nunchaku优化后，可以使用更少的步数（10-15步即可获得高质量结果）
• cfg：建议使用1-3之间的值，Nunchaku对高cfg值不太敏感
• sampler：推荐使用euler或euler_ancestral
• scheduler：simple或normal都可以

核心节点：

以nunchaku来运行FLUX.1基础文生图工作流为例，主要有三个模型加载器：

• Nunchaku FLUX DiT Loader 替代 UNET加载器；
• Nunchaku Text Encoder Loader (Deprecated) 替代 双CLIP加载器；
• Nunchaku FLUX.1 LoRA Loader 替代 loRA加载器；

模型文件已进行整理，网盘内包含工作流获取方式，适合不方便科学上网的的小伙伴下载使用。模型文件数量较多且尺寸较大，为避免下载中断等问题，可先转存再下载。