该储存库为Nunchaku提供了ComfyUI节点，这是一个用于使用SVDQuant量化的 4 位神经网络的高效推理引擎。有关量化库，请查看 DeepCompressor.

加入我们，在Slack, Discord 和 微信 上的社区群组进行讨论———详情点击这里. 如果您有任何问题、遇到问题或有兴趣做出贡献，请随时与我们分享您的想法！

• [2025-06-01] 🚀 发布 v0.3.0 版本！ 本次更新新增了对多批次推理的支持，集成了 ControlNet-Union-Pro 2.0 并初步整合了 PuLID。您现在可以将 Nunchaku FLUX 模型作为单个文件加载，而我们升级后的 4位 T5 编码器 在质量上已可媲美 FP8 T5！
• [2025-04-16] 🎥 发布了英文和中文教程视频，协助安装和使用Nunchaku。
• [2025-04-09] 📢 发布了 4月更新计划和常见问题解答来帮助社区朋友快速入门并及时了解Nunchaku的发展情况。
• [2025-04-05] 🚀 v0.2.0发布! 这个版本支持了多LoRA和ControlNet，并且使用FP16 attention和First-Block Cache来增强性能. 我们添加了对Invidia20系显卡的支持，并制作了FLUX.1-redux的官方工作流。

我们提供了在 Windows 上安装和使用 Nunchaku 的教学视频，支持英文和中文两个版本。同时，你也可以参考对应的图文教程 docs/setup_windows.md。如果在安装过程中遇到问题，建议优先查阅这些资源。

请先参阅README.md来安装 nunchaku。

您可以使用comfy-cli在ComfyUI中运行Nunchaku：

pip install comfy-cli  # Install ComfyUI CLI
comfy install          # Install ComfyUI
comfy node registry-install ComfyUI-nunchaku  # Install Nunchaku

1. 首先使用以下指令安装ComfyUI

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

2. 使用以下命令安装ComfyUI-Manager（这是一个节点管理插件）

   cd custom_nodes
   git clone https://github.com/ltdrdata/ComfyUI-Manager comfyui-manager
   

3. 启动ComfyUI

   cd ..  # Return to the ComfyUI root directory
   python main.py
   

4. 打开Manager后, 在Custom Nodes Manager中搜索ComfyUI-nunchaku节点并且下载它then install it.

1. 使用以下命令设置ComfyUI

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

2. 将此仓库克隆到 ComfyUI 中的目录中：custom_nodes

   cd custom_nodes
   git clone https://github.com/mit-han-lab/ComfyUI-nunchaku nunchaku_nodes
   

1. 设置ComfyUI和Nunchaku:

   • Nunchaku的工作流可以在workflows找到。想要找到它们，请将文件复制到ComfyUI的根目录中： user/default/workflows

     cd ComfyUI
     
     # Create the example_workflows directory if it doesn't exist
     mkdir -p user/default/example_workflows
     
     # Copy workflow configurations
     cp custom_nodes/nunchaku_nodes/example_workflows/* user/default/example_workflows/
     

   • 按照本教程.安装所有缺失节点 (例如 comfyui-inpainteasy)

2. 下载必要模型: 按照本教程把必要的模型下载到对应的目录中。或者使用以下命令：

   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
   

3. 运行ComfyUI： 要启动 ComfyUI,请导航到其根目录并运行：python main.py。如果您使用的是 comfy-cli, 请运行 comfy launch.

4. 选择Nunchaku工作流：选择一个Nunchaku工作流开始使用(文件名以nunchaku-为开头的工作流)。在使用flux.1-fill的工作流时, 可以使用ComfyUI内置的MaskEditor工具来涂抹遮罩。

5.所有四位模型都可以在HuggingFace或者ModelScope中找到。除了svdq-flux.1-t5，请将整个模型文件夹下载并放入到models/diffusion_models文件夹中。

• Nunchaku Flux DiT Loader节点：用于加载Flux扩散模型的节点

  • model_path：指定模型的位置。您需要从我们的Hugging Face或者ModelScope中手动下载模型文件夹。例如：运行

    注意：旧版模型文件夹仍然受支持，但将在 v0.4 中弃用。要迁移，请使用我们的 merge_safetensors.json 工作流程将旧版文件夹合并为单个 .safetensors 文件，或从上述集合中重新下载模型。

  • cache_threshold：控制First-Block Cache的容差，类似于WaveSpeed中的residual_diff_threshold。增加此值可以提高速度，但可能会降低质量。典型值为 0.12。将其设置为 0 将禁用该效果。

  • attention：定义 attention 的实现方法. 您可以在flash-attention2或nunchaku-fp16之间进行选择。我们的nunchaku-fp16在不影响精度的情况下大约比flash-attention2快1.2x倍。对于Turing架构的显卡(20系), 如果不支持flash-attention2，则必须使用 nunchaku-fp16。

  • cpu_offload：为transformer模型启用CPU卸载。虽然这减少了GPU内存的使用，但它可能会减慢推理速度。

    • 当设置为auto的时候，它将自动检测您的可用 GPU 内存。如果您的GPU内存超过14GiB，则将禁用卸载。否则，它将启用。
    • 将来将在节点中进一步优化内存使用。

  • device_id：模型运行时使用的GPU ID。

  • data_type：定义去量子化张量的数据类型。Turing架构的GPU(20系)不支持bfloat16，只能只用float16.

  • i2f_mode：对于Turing架构的GPU(20系)，此选项控制GEMM的实现模式。enabled和always模式的差异细微。在其他架构的GPU上可以忽略这个选项。

• Nunchaku FLUX LoRA Loader：用于加载SVDQuant FLUX模型的LoRA模型的节点

  • 将LoRA Checkpints文件放在models/loras目录中。这些LoRA模型将在lora_name下显示为可选选项。
  • lora_strength：控制LoRA模型的强度。
  • 您可以将多个multiple LoRA nodes模型连接使用
  • 注：从0.2.0版本开始，不需要转换LoRA了。可以在加载器中加载原始的LoRA文件

• Nunchaku Text Encoder Loader V2：用于加载文本编码器的节点。

• 选择 CLIP 和 T5 模型作为 text_encoder1 和 text_encoder2，遵循与 DualCLIPLoader 相同的方式。此外，您可以选择使用我们增强的 4 位 T5XXL 模型，以节省更多 GPU 内存。

• t5_min_length：设置 T5 文本嵌入的最小序列长度。DualCLIPLoader 中的默认值硬编码为 256，但为了获得更好的图像质量，此处请使用 512。

• Nunchaku Text Encoder Loader (将在v0.4版本弃用)：用于加载文本编码器的节点。

  • 对于FLUX，请使用以下文件：

    • text_encoder1: t5xxl_fp16.safetensors（或 T5 编码器的 FP8/GGUF 版本）。
    • text_encoder2: clip_l.safetensors

  • t5_min_length：设置 T5 文本嵌入的最小序列长度。在DualCLIPLoader中的默认硬编码为256，但为了获得更好的图像质量，请在此处使用 512。

  • use_4bit_t5：指定您是否需要使用我们的量化4位T5来节省GPU内存

  • int4_model：指定INT4 T5的位置。这个选项仅在use_4bit_t5启用时使用。您可以从HuggingFace或ModelScope下载模型到models/text_encoders文件夹。例如，您可以使用以下命令：

    huggingface-cli download mit-han-lab/svdq-flux.1-t5 --local-dir models/text_encoders/svdq-flux.1-t5
    

    After downloading, specify the corresponding folder name as the int4_model.

• FLUX.1 Depth Preprocessor (将在v0.4版本弃用)：一个用于加载depth模型并生成相应深度图的旧节点。model_path参数指定checkpoint模型的位置。您可以从Hugging Face 下载模型并放在models/checkpoints目录中。或者，使用以下CLI命令：

  huggingface-cli download LiheYoung/depth-anything-large-hf --local-dir models/checkpoints/depth-anything-large-hf
  

  注意：此节点已弃用，并将在未来发行版中删除。请改用更新后的 "Depth Anything" 节点来替代加载depth_anything_vitl14.pth。