ussoewwin/ComfyUI-QwenImageLoraLoader

是什么

ComfyUI‑QwenImageLoraLoader 是 ComfyUI 的自定义节点包。ComfyUI 是一个可视化、基于节点的界面，用于构建 Stable Diffusion 风格的图像生成流水线。此仓库中的节点可让您加载并将 LoRA（低秩自适应）权重应用于 Nunchaku 插件提供的 Qwen‑Image 和 Z‑Image‑Turbo 模型。此外，该包还包含 Krea2 深度/开放姿态 ControlNet LoRA 的加载器和一个 DiffSynth 风格的 ControlNet 节点。

为什么重要

• LoRA 支持 – LoRA 文件是微小的微调权重增量，可让您在不重新训练整个模型的情况下，将大型扩散模型（例如 Qwen‑Image）适应新的风格或主题。此包使添加这些 LoRA 变得非常简单，只需将文件放入节点并设置强度滑块即可。
• 多 LoRA 堆叠 – “堆叠”节点允许您在一个工作流中组合多个 LoRA，每个 LoRA 都有自己的启用开关和强度，模仿了流行的 rgthree Power LoRA Loader UI。
• AWQ 量化处理 – 内置了将 LoRA 应用于 AWQ 量化调制层（img_mod.1 / txt_mod.1）的实验性支持，这对于低显存设置非常有用。
• ControlNet 集成 – 专用节点加载 Krea2 深度/开放姿态 ControlNet LoRA 和 DiffSynth ControlNet 路径，扩展了条件设置选项的范围。
• 兼容性 – 适用于官方 ComfyUI‑nunchaku 插件（v1.2.0+），支持较新的 ComfyUI Nodes 2.0 UI（测试版），并在 nunchaku 包不可用的 AMD/ROCm 系统上自动禁用自身。

核心功能

功能	描述
单 LoRA 加载器	NunchakuQwenImageLoraLoader – 加载一个 LoRA 并设置其强度。
堆叠 V1	rgthree 风格 UI，适用于经典 LiteGraph 画布（不适用于 Nodes 2.0）。
堆叠 V2	动态 UI，对 Nodes 2.0 提供测试版支持，包含将 LoRA 应用于 AWQ 调制层的开关。
堆叠 V3	与 V2 相同，但始终应用 AWQ 调制层 LoRA。
Z‑Image Turbo 堆叠 V1 / V4	用于 Z‑Image‑Turbo 模型系列的 LoRA 堆叠；V4 使用标准 CLIP 输入/输出 LoRA 格式，并且兼容 Nodes 2.0。
DiffSynth ControlNet 和 Krea2	NunchakuQwenImageDiffsynthControlnet 加载 DiffSynth 风格 ControlNet 补丁；Krea2ControlNetLoraLoader 自动检测深度 LoRA 与开放姿态 LoRA 并适当路由。
调试日志	通过 nunchaku_log=1 实现可选的详细日志。
安装	简单地 git clone 到 ComfyUI 的 custom_nodes 文件夹；从 v1.60 起无需额外集成代码。
错误处理	检测缺失的 nunchaku 依赖项，提供清晰的运行时错误，并包括常见 UTF‑8、路径检测和模型管理问题的修复。

适用人群

• 艺术家和爱好者 – 使用 Qwen‑Image 或 Z‑Image‑Turbo 模型构建 ComfyUI 工作流，并想尝试基于 LoRA 的风格或主题适应的用户。
• 研究人员 – 探索低显存量化模型（AWQ）并需要在其上应用 LoRA 方法的用户。
• 开发者 – 使用自定义 ControlNet 条件设置（深度、姿态）扩展 ComfyUI，并需要能自动检测 LoRA 类型的现成加载器的用户。

快速开始（快速步骤）

1. 安装先决条件 – ComfyUI、官方 ComfyUI‑nunchaku 插件（≥ 1.2.0）、PyTorch、Python 3.12+。
2. 添加节点包：

   cd path/to/ComfyUI/custom_nodes
   git clone https://github.com/ussoewwin/ComfyUI-QwenImageLoraLoader.git
   

3. 重启 ComfyUI – 新节点会出现在节点调色板中。
4. 加载模型 – 使用现有的 Nunchaku Qwen Image DiT Loader 或 Nunchaku Z‑Image DiT Loader 节点。
5. 添加 LoRA 加载器 – 将 NunchakuQwenImageLoraStackV2（或任何堆叠版本）拖入工作流，指向 .safetensors LoRA 文件，设置强度，并将其输出连接到模型输入。
6. （可选）添加 ControlNet – 使用 Krea2ControlNetLoraLoader 加载 Krea2 深度/开放姿态 LoRA，并将其连接到 DiffSynth ControlNet 节点。
7. 运行 – 使用组合的模型 + LoRA + ControlNet 条件设置生成图像。

局限性与未解决的问题

• Nodes 2.0 兼容性 – V1 堆叠节点不适用于新 UI；只有 V2/V3/V4 具有测试版兼容性。
• Nunchaku 量化 Qwen Image 上的 ControlNet – 由于隐藏状态缩放不匹配，内置 DiffSynth ControlNet 无法与 W4A4 量化 Qwen Image 模型一起使用（请参阅“已知局限性”部分）。
• AMD/ROCm – 当无法导入 nunchaku 包时，核心 Nunchaku 依赖节点会被禁用；只有 Krea2 相关节点保持功能。
• 实验性 AWQ 支持 – 将 LoRA 应用于 AWQ 调制层仍是实验性的，可能在未来版本中更改。

---

以上所有信息均直接取自仓库的 README；未推断任何额外功能。