ussoewwin-ComfyUI-QwenImageLoraLoader/zhmd

ComfyUI-Nunchaku QwenImage/ZImageTurboLoraStack&Multi ControlNet Loader

<td align="center" bgcolor="#e5e7eb" width="88" height="36"><a href="../README.md"><font color="#4b5563"><b>EN</b></font></a></td>

<td align="center" bgcolor="#d4465e" width="88" height="36"><font color="#ffffff"><b>中文</b></font></td>

用于 Nunchaku Qwen Image 和 Z-ImageTurbo 模型的 ComfyUI 自定义节点，支持加载和应用 LoRA（低秩适配），以及 Krea2 depth/openpose ControlNet LoRA 加载器。兼容 ComfyUI Nodes 2.0。v4 功能需要 Nunchaku 1.2.0+ 和 ComfyUI-Nunchaku 1.2.0+。

⚠️ 开发状态

目前正在开发和测试中。正在大量输出调试日志。这不影响功能。

最新版本: v2.6.0 发行说明

来源

此 LoRA 加载器从 GavChap 的分支中提取并修改：

• 原始分支: GavChap/ComfyUI-nunchaku (qwen-lora-suport-standalone 分支)

• 提取: 从完整分支中提取 LoRA 功能，创建独立的自定义节点

• 集成: 修改为与官方 ComfyUI-nunchaku 插件一起工作

🎉 重大更新: v2.2.0 - 新增 Nunchaku Z Image Turbo LoRA 支持！

详细技术说明，请参阅 v2.2.0 发行说明

🎉 重大更新: v1.60 - 简化安装（无需集成！）

有关安装说明、功能和要求，请参阅 安装指南。

v1.57 及更早版本用户的升级指南

若您已安装 v1.57 或更早版本，且曾在 ComfyUI-nunchaku 的 __init__.py 中使用过集成代码，请参阅 v1.57 升级指南 了解详细升级说明。

使用方法

调试日志（可选）

默认情况下，详细的调试日志是静音的。如果您需要详细的调试输出（密钥扩散/密钥映射检查、[APPLY]、[AWQ_MOD] 等），请在启动 ComfyUI 之前设置环境变量 nunchaku_log=1。

可用节点

• NunchakuQwenImageLoraLoader: 单 LoRA 加载器

• NunchakuQwenImageLoraStackV1: 多 LoRA 堆叠器，rgthree 风格 UI

  • 简洁、极简的设计，灵感来自 Power Lora Loader (rgthree-comfy)。每行包含切换、LoRA 名称和强度。

  • ⚠️ 注意: 无法与 ComfyUI Nodes 2.0 正常工作。请使用标准 (LiteGraph) 画布。

  • ⚠️ 与 ComfyUI Nodes 2.0 一起使用时，按 F5 刷新将反映更改。

• NunchakuQwenImageLoraStackV2: 多 LoRA 堆叠器，带动态 UI - 兼容 ComfyUI Nodes 2.0 (Beta)

  • AWQ 调制层支持: 包含通过 "Apply AWQ Mod" 切换将 LoRA 应用于 AWQ 量化调制层 (img_mod.1 / txt_mod.1) 的实验性支持。此功能使用运行时猴子补丁和手动平面注入来修复噪声问题。⚠️ 警告: 这是一个实验性功能，目前仅在 V2 节点中实现。 如果没有发现问题，此功能也将应用于 V1 和 V3 节点。

• NunchakuQwenImageLoraStackV3: 多 LoRA 堆叠器，带动态 UI - 兼容 ComfyUI Nodes 2.0 (Beta)

  • AWQ 调制层支持: AWQ 量化调制层 (img_mod.1 / txt_mod.1) LoRA 应用始终启用（无需切换）。此功能使用运行时猴子补丁和手动平面注入来修复噪声问题。✅ V3 节点默认始终应用 AWQ 调制层 LoRA。

• NunchakuZImageTurboLoraStackV1: Z-Image-Turbo LoRA 堆叠器，rgthree 风格 UI

  • 简洁、极简的设计，灵感来自 Power Lora Loader (rgthree-comfy)。每行包含切换、LoRA 名称和强度。仅用于官方 Nunchaku Z-Image 加载器。使用 compose_loras_v2。

  • ⚠️ 注意: 无法与 ComfyUI Nodes 2.0 正常工作。请使用标准 (LiteGraph) 画布。

  • ⚠️ 与 ComfyUI Nodes 2.0 一起使用时，按 F5 刷新将反映更改。

• NunchakuZImageTurboLoraStackV4: Z-Image-Turbo LoRA 堆叠器，带动态 UI - 标准 ComfyUI LoRA 加载器格式 (CLIP 输入/输出) - 兼容 ComfyUI Nodes 2.0

• Nunchaku ZI Diffsynth Controlnet&Krea2 LoRA ControlNet（类名: NunchakuQwenImageDiffsynthControlnet）: DiffSynth ControlNet 支持节点。
  • Z-Image-Turbo（ZI 路由）：支持 Nunchaku（量化）以及所有非量化 / 量化 Z-Image 模型。
  • Qwen Image（QI 路由）：支持所有非 Nunchaku 的 Qwen Image 模型（非量化与量化，如 HSWQ ConvRot INT8 均支持）。Nunchaku Qwen Image 不受支持（量化后的 hidden-state 尺度不匹配会导致输出损坏）。
  • Krea2（depth / openpose）：Krea2 控制支持。
• Krea2ControlNetLoraLoader: Krea2 controlnet-lora 加载器（depth & openpose）
  • 根据 LoRA 文件自动检测 Krea2 控制子类型：depth（first.weight 扩展投影路由）或 openpose（纯块 LoRA + 原生参考潜变量路由）。路由严格互斥。

基本用法

对于 Nunchaku Qwen Image 模型：

1. 使用 Nunchaku Qwen Image DiT Loader 加载您的 Nunchaku Qwen Image 模型

2. 添加 NunchakuQwenImageLoraLoader 或 NunchakuQwenImageLoraStackV1 / V2 / V3 节点

3. 选择您的 LoRA 文件并设置强度

4. 连接到您的工作流

对于 Nunchaku Z-Image-Turbo 模型：

1. 使用 Nunchaku Z-Image DiT Loader (官方 ComfyUI-Nunchaku) 加载您的 Nunchaku Z-Image-Turbo 模型

2. 添加 Nunchaku Z-Image-Turbo LoRA Stack V4 节点

3. 连接 CLIP 输入 (v4 中必需)

4. 选择您的 LoRA 文件并设置强度

5. 连接到您的工作流

Diffsynth ControlNet 使用方法

1. 使用 ComfyUI-NunchakuFluxLoraStacker 中的 Model Patch Loader 加载您的 diffsynth ControlNet 模型补丁

2. Model Patch Loader（即 ModelPatchLoaderCustom 节点）支持 CPU 卸载，允许您将 ControlNet 补丁加载到 CPU 内存以节省 VRAM

3. 将 MODEL_PATCH 输出连接到 Nunchaku ZI Diffsynth Controlnet&Krea2 LoRA ControlNet 节点的 model_patch 输入端

4. 连接您的 Nunchaku Qwen Image 模型、VAE 和控制图像

5. 设置 ControlNet 强度并连接到您的工作流

6. Krea2 控制支持（depth & openpose）：添加 Krea2ControlNetLoraLoader，选择你的 Krea2 controlnet-lora 文件，然后将其 MODEL_PATCH 输出连接到 Nunchaku ZI Diffsynth Controlnet&Krea2 LoRA ControlNet 的 model_patch 输入端。节点会自动检测 Krea2 子类型：

   • Depth（例如 krea2-depth-control-lora.safetensors）：扩展 first 投影路由 + 控制潜变量 注入。这是原有的 Krea2 depth 行为，完全未改动。
   • OpenPose（例如 krea2_turbo_openpose_controlnet.safetensors）：纯块 LoRA 路由，作用于 diffusion_model.blocks 与 diffusion_model.txtfusion（layerwise/refiner），并将姿态图 以原生 Krea2 参考潜变量（index_timestep_zero）注入。建议保持 use_kv_cache 开启 （默认值）——这与该 openpose 控制 LoRA 训练时使用的 ai-toolkit kv_cache 约定一致。

Krea2 控制（Depth & OpenPose）

Nunchaku ZI Diffsynth Controlnet&Krea2 LoRA ControlNet 会根据加载的 LoRA 文件自动检测 Krea2 控制子类型，并应用 独立、自包含的路由——无需任何外部节点。

Krea2 Depth 控制

1. 使用 Krea2ControlNetLoraLoader 加载 depth 控制 LoRA（例如 krea2-depth-control-lora.safetensors）
2. 将其 MODEL_PATCH 输出连接到 Nunchaku ZI Diffsynth Controlnet&Krea2 LoRA ControlNet 的 model_patch 输入端
3. 连接你的 Krea2 模型、VAE 与深度图，并设置 strength

工作原理：

• depth LoRA 提供扩展的 first 投影（2 倍输入通道），通过运行时 _Krea2FirstProjection 垫片注入， 并按 strength 缩放
• 对 DiT 块应用块 LoRA 补丁（rank 64）
• 深度图经 VAE 编码后送入扩展的 first 投影，使深度从第一层就开始条件化生成

Krea2 OpenPose 控制

krea2_turbo_openpose_controlnet.safetensors 控制 LoRA 通过 Nunchaku ZI Diffsynth Controlnet&Krea2 LoRA ControlNet 中独立、自包含的路由应用：

1. 使用 Krea2ControlNetLoraLoader 加载 openpose 控制 LoRA
2. 将其 MODEL_PATCH 输出连接到 Nunchaku ZI Diffsynth Controlnet&Krea2 LoRA ControlNet 的 model_patch 输入端
3. 连接你的 Krea2 模型、VAE 与姿态图，并设置 strength
4. 保持 use_kv_cache = True（默认值）以启用隔离参考 K/V 模式

工作原理：

• 256 个块 LoRA 补丁（rank 32）应用于全部 28 个 DiT 块以及 txtfusion 的 layerwise/refiner 块
• 姿态图经 VAE 编码后，以原生 Krea2 参考潜变量（index_timestep_zero）注入——这正是该控制 LoRA 训练时所采用的条件通路
• use_kv_cache 在 t=0 时执行一次参考前向，预先计算每个块的 K/V，并在每个采样步将其作为 额外 attention key 注入（序列中不携带逐步 ref token）

互斥性： Krea2 路由严格子分类（depth vs openpose），整个 Krea2 分支与 Qwen Image / Z-Image / Nunchaku 路由完全隔离——使用这些路由的现有工作流不受任何影响。

参考：ostris 的 comfyui-krea2-ostris-edit TextEncode 节点与 pysssss 的 krea2_controlnet_pose.json 工作流仅作参考；本仓库已独立实现相同的姿态控制效果。

功能

• 易于安装: 简单的 git clone 安装

• 独立运行: 无需集成代码 (v1.60+)

• 自动节点发现: ComfyUI 自动加载自定义节点

• 错误处理: 全面的错误检查和用户反馈

• 问题 #1 已修复: 通过改进的路径检测解决了 ComfyUI\custom_nodes not found 错误（感谢 @mcv1234 的解决方案）

• 问题 #2 已修复: 通过使用专用 Python 脚本进行正确的 UTF-8 编码，修复了导致 SyntaxError: (unicode error) 的 UTF-8 编码错误（感谢 @AHEKOT 的错误报告）

• 问题 #3 已修复 (v1.4.0): 通过实现带有基于哈希的更改检测的正确 IS_CHANGED 方法，解决了 节点中断缓存进度错误（感谢 @AHEKOT 的错误报告）

• 问题 #10 已修复: 添加了便携式 ComfyUI 支持，包括嵌入式 Python 检测 (问题 #10) - 特别感谢: 这一关键功能是由 @vvhitevvizard 提出的，他识别了便携式 ComfyUI 安装中对嵌入式 Python 支持的需求。如果没有这个建议，便携式 ComfyUI 用户将无法使用此 LoRA 加载器。

• PR #48 已合并 (v2.3.8): 改进了 PEFT 格式 LoRA 检测并添加了安全跳过日志 (PR #48) - 特别感谢: 我们非常感谢 @avan06 识别并修复了一个关键的映射缺陷，该缺陷导致 PEFT 格式 LoRA 被错误地跳过。此修复显著提高了 LoRA 格式兼容性，并确保正确检测使用 Hugging Face PEFT 库创建的 LoRA 文件。

• PR #49 已合并 (v2.4.0): 添加了 Nunchaku Qwen Image LoRA Stack V1，rgthree 风格 UI (PR #49) - 特别感谢: 我们非常感谢 @avan06 提出了受 Power Lora Loader (rgthree-comfy) 启发的简洁、极简界面。此贡献带来了优雅的 LoRA 行布局，包含切换、LoRA 名称和强度控制。我们长期以来一直感觉到需要这样的 UI，但由于技术能力无法实现；此 PR 满足了这一需求。

要求

• ComfyUI

• ComfyUI-nunchaku 插件 (官方版本，无需修改)

• PyTorch

• Python 3.11+

兼容性

此节点设计用于：

• ComfyUI-nunchaku 插件 (官方版本)

• Nunchaku Qwen Image 模型

• 标准 ComfyUI 工作流

AMD / ROCm 兼容性

nunchaku 仅支持 NVIDIA CUDA，在 AMD/ROCm 系统上不可用。

在 AMD/ROCm（或任何无法导入 nunchaku 包的机器）上，本自定义节点会自动检测缺失的依赖并适配：

• 已禁用：所有依赖 nunchaku 的节点将不再注册，不会出现在节点列表中：

  • NunchakuQwenImageLoraLoader

  • NunchakuQwenImageLoraStackV1 / V2 / V3

  • NunchakuZImageTurboLoraStackV1 / V4

• 仍可使用：不依赖 nunchaku 的 Krea2 ControlNet 节点保持完整功能：

  • Krea2ControlNetLoraLoader — 将 Krea2 ControlNet LoRA 加载为 MODEL_PATCH

  • NunchakuQwenImageDiffsynthControlnet — 应用控制（该节点的 Krea2 路由不需要 nunchaku；Z-Image / Nunchaku-QwenImage 路由仅在安装 nunchaku 时可用）

启动时若缺少依赖，会输出 [ROCm/AMD] nunchaku is not available... 警告日志。如果旧工作流仍引用已禁用的节点，会收到清晰的 RuntimeError（"nunchaku is required..."），而非曲折的导入失败。

故障排除

错误: "ModuleNotFoundError: No module named 'nunchaku'"

问题: nunchaku 包未安装。

解决方案:

1. 从官方仓库安装 ComfyUI-nunchaku 插件

2. 按照 nunchaku 安装说明安装 nunchaku wheel

3. 重启 ComfyUI

问题 #25: ComfyUI 0.4.0+ 模型管理错误

• 状态: ⚠️ 取决于环境 - 可能需要 ComfyUI 核心修复

详细信息，请参阅 COMFYUI_0.4.0_MODEL_MANAGEMENT_ERRORS.md。

• 相关问题:

  • 问题 #25 - AttributeError: 'NunchakuModelPatcher' object has no attribute 'pinned' 和 model_config 的深拷贝错误

  • 问题 #33 - to_safely 方法中的 AttributeError: 'NoneType' object has no attribute 'to' (已在 v2.1.0 中修复)

  • ComfyUI 问题 #6590 - 'NoneType' object has no attribute 'shape'

  • ComfyUI 问题 #6600 - 'NoneType' object is not callable (与加载器相关)

  • ComfyUI 问题 #6532 - 模型卸载后引用模型导致崩溃

错误: "No module named 'diffusers.models.transformers.transformer_z_image'"

问题: 使用 Qwen-Edit 模型或 Z-Image-Turbo 模型时，diffusers 库版本过旧会出现此错误。

错误信息: ModuleNotFoundError: No module named 'diffusers.models.transformers.transformer_z_image'

根本原因: 最可能的原因是 diffusers 库版本太旧，不包含 Z-Image-Turbo 模型支持所需的 transformer_z_image 模块。当 ComfyUI-nunchaku 的模型加载器尝试加载 Z-Image-Turbo 模型（或可能被检测为 Z-Image 格式的 Qwen-Edit 模型）时，它会尝试导入此模块，但它在旧版本的 diffusers 中不存在。此模块是在更高版本的 diffusers 中添加的，以支持 Z-Image-Turbo 模型。

解决方案: 将 diffusers 库更新到最新版本：

如果使用虚拟环境 (venv)：

pip install --upgrade diffusers

如果使用 ComfyUI 的嵌入式 Python：

ComfyUI\python_embeded\python.exe -m pip install --upgrade diffusers

如何验证: 更新后，重启 ComfyUI 并再次尝试加载您的模型。错误应该已解决。

相关问题: 问题 #38, 问题 #40

已知限制

LoKR (Lycoris) LoRA 支持

• 状态: ❌ 不支持

• 问题: 不支持 Lycoris 创建的 LoKR 格式 LoRA。

  • 重要说明: 此限制特别适用于 Nunchaku 量化模型。LoKR 格式 LoRA 可能适用于标准（非量化）Qwen Image 模型，但此节点专为 Nunchaku 模型设计。

  • ⚠️ 开发历史: 我们花费了大量时间分析 LoKR 格式的内部结构并进行广泛的映射测试。尽管付出了这些努力，我们仍未找到将 LoKR 权重成功应用于 Nunchaku 量化模型的方法。 实验性转换代码已测试，但由于不兼容问题最终被禁用。

  • 检测到 LoKR 权重时会自动跳过（实验性转换代码已禁用）。

  • 使用 SVD 近似（通过外部工具或脚本）转换为标准 LoRA 也已测试，发现应用于 Nunchaku 量化模型时会产生噪声/伪影。

• 结论: 目前，我们尚未找到将 LoKR 权重成功应用于 Nunchaku 模型的方法。请使用标准 LoRA 格式。

• 支持的格式:

  • ✅ 标准 LoRA (秩分解):

    • 支持的权重键：

      • lora_up.weight / lora_down.weight

      • lora.up.weight / lora.down.weight

      • lora_A.weight / lora_B.weight

      • lora.A.weight / lora.B.weight

    • 这些是 Kohya-ss、Diffusers 和大多数训练脚本生成的标准格式。

  • ✅ PEFT 格式 LoRA (v2.3.8+):

    • 支持的权重键（示例）：

      • lora_A.default.weight / lora_B.default.weight

      • lora.up.default.weight / lora.down.default.weight

    • 支持 lora_A/lora_B 和 .weight 之间的附加标签（例如 .default）。

    • 这些格式由 Hugging Face PEFT 库生成。v2.3.8 (PR #48) 中添加了对它们的支持。

  • ❌ LoKR (Lycoris): 不支持 (键如 lokr_w1, lokr_w2)

  • ❌ LoHa: 不支持 (键如 hada_w1, hada_w2)

  • ❌ IA3: 不支持

• 相关问题:

  • 问题 #29 - LyCORIS / LoKr Qwen Image LoRA 未被 ComfyUI 识别

  • 问题 #44 - [MISS] 找到模块但不支持/缺少 proj_down/proj_up (性能缓慢问题已在 v2.2.8 中修复)

context_refiner 和 noise_refiner 层支持

• 状态: ❌ 当前不支持

• 问题: 当前不支持 context_refiner 和 noise_refiner 层的 LoRA 键。这些是 Z-Image-Turbo 模型中用于细化功能的专用层。

• 详细信息:

  • ⚠️ 测试限制: 我们尚未使用实际模型测试包含 context_refiner 和 noise_refiner 层的 LoRA。我们无法测试它们的原因是 我们不知道哪些 LoRA 是这种格式。如果我们能识别出包含这些层的特定 LoRA，我们就可以进行测试。

  • 在没有测试的情况下，我们无法确定这些层的正确密钥映射是否可行。当前的密钥映射系统不包含这些层的映射，它们目前无法工作。

• 结论: 由于我们未能测试包含这些层的 LoRA，因此未实现对 context_refiner 和 noise_refiner 层的支持。即使我们测试了它们，也无法确定是否可以确定正确的密钥映射。请仅使用针对标准转换器层的 LoRA。

• 相关问题:

  • #41 - 无法加载context_refiner和noise_refiner层的参数

RES4LYF Sampler 兼容性问题

• 状态: ✅ 已在 ComfyUI-nunchaku v1.0.2 中修复

• 问题: 将 RES4LYF sampler 与 LoRA 一起使用时发生设备不匹配错误 (问题 #7, 问题 #8)

• 修复: 该问题已在 ComfyUI-nunchaku v1.0.2 中由 @devgdovg 在 PR #600 中修复。此修复是在 ComfyUI-nunchaku 的代码库中实现的，而不是在此 LoRA 加载器中。

• 要求: 更新到 ComfyUI-nunchaku v1.0.2 或更高版本，以将 RES4LYF sampler 与 LoRA 一起使用

• 相关问题:

  • 问题 #7 - RES4LYF sampler 设备不匹配错误

  • 问题 #8 - RES4LYF sampler 兼容性问题

更新日志

有关最新更新和详细发行说明（v2.4.0 起），请参阅 changelogzh.md。

先前版本 (v2.3.0 到 v2.3.9)

有关 v2.3.0 到 v2.3.9 的详细发行说明，请参阅 RELEASE_NOTES_V2.3.0_TO_V2.3.9.md。

此文档包含有关这些版本的所有错误修复、功能和技术细节的全面信息。

先前版本 (v1.6.0 到 v2.2.8)

有关 v1.6.0 到 v2.2.8 的详细发行说明，请参阅 RELEASE_NOTES_V1.6.0_TO_V2.2.8.md。

此文档包含有关这些版本的所有错误修复、功能和技术细节的全面信息。

先前版本 (v1.0.0 到 v1.57)

有关 v1.0.0 到 v1.57 的详细发行说明，请参阅 RELEASE_NOTES_V1.0.0_TO_V1.57.md。

此文档包含有关这些版本的所有错误修复、功能和技术细节的全面信息。

许可证

本项目根据 MIT 许可证获得许可。