ComfyUI-QwenImageLoraLoader：专为 Nunchaku Qwen 与 Z-ImageTurbo 设计的 LoRA 加载器

在 ComfyUI 中使用 Nunchaku 量化的 Qwen 图像模型 或 Z-ImageTurbo 模型？想要加载 LoRA 微调，甚至结合 Diffsynth ControlNet 实现条件控制生成？

ComfyUI-QwenImageLoraLoader 正是为此打造的专用自定义节点。它从 GavChap 的 ComfyUI-nunchaku 分支中提取 LoRA 功能，独立封装，并持续优化以支持最新模型与 ComfyUI 生态。

项目地址：https://github.com/ussoewwin/ComfyUI-QwenImageLoraLoader
最新版本：v2.2.3

核心能力

✅ 专为量化模型优化

• 完整支持 Nunchaku Qwen Image 与 Z-ImageTurbo BF16 / INT8 量化模型
• ⚠️ 注意：不支持 LoKR / LoHa / IA3 等非标准 LoRA 格式（仅支持 lora_up/down、lora_A/B 等标准结构）

✅ 完整 LoRA 支持

• 单 LoRA 加载：NunchakuQwenImageLoraLoader
• 多 LoRA 堆叠：
  • NunchakuQwenImageLoraStack（旧版）
  • NunchakuQwenImageLoraStackV2（ComfyUI 节点 2.0 兼容）
  • NunchakuZImageTurboLoraStackV3（Z-ImageTurbo 专用，支持开关控制）

✅ Diffsynth ControlNet 集成（v2.0+）

• 新增节点：NunchakuQI&ZITDiffsynthControlnet
• 支持将 ControlNet 条件注入 Qwen 图像 / Z-ImageTurbo 的前向传播流程
• 可配合 Model Patch Loader（来自 ComfyUI-NunchakuFluxLoraStacker）加载 ControlNet 补丁，并支持 CPU 卸载节省显存

✅ 安装极简（v1.60 起）

• 无需修改 __init__.py
• 无需运行批处理脚本
• 仅需 git clone 到 custom_nodes/，重启 ComfyUI 即可
• 自动注册，向后兼容

使用流程

加载 Qwen 图像模型 + LoRA

1. 用 Nunchaku Qwen Image DiT Loader 加载模型
2. 添加 NunchakuQwenImageLoraLoader 或 LoraStackV2
3. 选择 LoRA 文件，设置强度
4. 接入 KSampler 工作流

加载 Z-ImageTurbo + LoRA + ControlNet

1. 用 Nunchaku Z-Image DiT Loader 加载模型
2. 添加 NunchakuZImageTurboLoraStackV3
3. 用 Model Patch Loader 加载 Diffsynth ControlNet 补丁
4. 将 MODEL_PATCH 输出连至 NunchakuQI&ZITDiffsynthControlnet
5. 输入控制图、模型、VAE，设置 ControlNet 强度

动态 UI：LoraStack 节点支持 lora_count（1–10），自动调整槽位数量

兼容性要求

• ComfyUI（最新稳定版）
• ComfyUI-nunchaku（官方版本，无需修改）
• Python 3.11+、PyTorch

与 kjai、RES4LYF 等采样器兼容（需 nunchaku ≥ v1.0.2）

重要限制与注意事项

❌ 不支持非标准 LoRA 格式

• LoKR（Lycoris）、LoHa、IA3 均无法加载
• 即使通过工具转换为标准 LoRA，在 Nunchaku 量化模型上仍可能产生噪点或伪影
• 仅推荐使用标准 LoRA（Kohya-ss / Diffusers 训练格式）

⚠️ v2.0+ 的 guidance 参数冲突问题

部分用户在使用 v2.0 - v2.2.3 时仍可能遇到：

TypeError: got multiple values for argument 'guidance'

原因：ControlNet、调度器、模型前向传播间的参数传递存在边缘情况。

临时解决方案：
如无需 ControlNet，降级至 v1.72（最后一个无 ControlNet 的稳定版）。

项目维护者已多次修复（v2.0.2 → v2.0.8），但因环境差异，问题未完全根除。

⚠️ ComfyUI 0.4.0+ 模型管理兼容性

某些 ComfyUI 核心版本（如 0.4.0）存在 pinned 属性缺失、深拷贝错误等问题。
建议使用 ComfyUI 官方最新版 或关注项目 COMFYUI_0.4.0_MODEL_MANAGEMENT_ERRORS.md 文档。

故障排查速查

版本演进亮点

• v1.60：告别手动集成，真正独立节点
• v1.70：支持 ComfyUI 节点 2.0，动态 UI
• v2.0：引入 Diffsynth ControlNet 支持
• v2.2.0：新增 Z-ImageTurbo LoRA 堆叠器
• v2.2.2：Z-ImageTurbo 模型支持 ControlNet
• v2.2.3：LoRA 槽位可单独启用/禁用（实验性）