ussoewwin/ComfyUI-QwenImageLoraLoader

概要

ComfyUI‑QwenImageLoraLoader は、ComfyUI 用のカスタムノードパッケージです。ComfyUI は、Stable Diffusion スタイルの画像生成パイプラインを構築するための視覚的なノードベースのインターフェースです。このリポジトリのノードを使用すると、Nunchaku プラグインが提供する Qwen‑Image および Z‑Image‑Turbo モデルに LoRA（Low‑Rank Adaptation）重みをロードして適用できます。さらに、このパッケージには Krea2 深度/オープンポーズ ControlNet LoRA 用のローダーと、DiffSynth スタイルの ControlNet ノードも含まれています。

重要な理由

• LoRA サポート – LoRA ファイルは、モデル全体を再トレーニングすることなく、大規模な拡散モデル（例：Qwen‑Image）を新しいスタイルや被写体に適応させることができる、小さなファインチューニングされた重みの差分です。このパッケージを使用すると、ファイルをノードにドロップして強度スライダーを設定するだけで、これらの LoRA を簡単に追加できます。
• マルチ LoRA スタッキング – 「スタック」ノードを使用すると、各 LoRA に独自の有効/無効トグルと強度を設定して、1 つのワークフローで複数の LoRA を組み合わせることができます。これは、人気の rgthree Power LoRA Loader UI を反映しています。
• AWQ 量子化処理 – AWQ 量子化された変調レイヤー（img_mod.1 / txt_mod.1）に LoRA を適用するための実験的サポートが組み込まれており、低 VRAM 環境で役立ちます。
• ControlNet 統合 – 専用ノードが Krea2 深度/オープンポーズ ControlNet LoRA と DiffSynth ControlNet ルートをロードし、コンディショニングオプションの範囲を広げます。
• 互換性 – 公式の ComfyUI‑nunchaku プラグイン（v1.2.0+）で動作し、新しい ComfyUI Nodes 2.0 UI（ベータ版）をサポートし、nunchaku パッケージが利用できない AMD/ROCm システムでは自動的に無効になります。

主な機能

機能	説明
単一 LoRA ローダー	NunchakuQwenImageLoraLoader – 1 つの LoRA をロードし、その強度を設定します。
スタック V1	rgthree スタイルの UI。クラシックな LiteGraph キャンバスで動作します（Nodes 2.0 では動作しません）。
スタック V2	動的 UI、Nodes 2.0 のベータサポート。AWQ 変調レイヤーに LoRA を適用するためのトグルが含まれています。
スタック 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 によるオプションの詳細ログ。
インストール	ComfyUI の custom_nodes フォルダーへの簡単な git clone。v1.60 以降、追加の統合コードは不要です。
エラーハンドリング	不足している nunchaku 依存関係を検出し、明確なランタイムエラーを提供し、一般的な UTF‑8、パス検出、モデル管理の問題の修正を含みます。

対象ユーザー

• アーティスト＆ホビイスト – Qwen‑Image または Z‑Image‑Turbo モデルで ComfyUI ワークフローを構築し、LoRA ベースのスタイルや被写体の適応を試したい方。
• 研究者 – 低 VRAM の量子化モデル（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 サポート – AWQ 変調レイヤーへの LoRA の適用はまだ実験的であり、将来のリリースで変更される可能性があります。

---

上記のすべての情報は、リポジトリの README から直接取得したものです。追加の機能は推測されていません。