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에 고유한 활성화 토글과 강도를 설정하여 하나의 워크플로우에서 여러 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 – 하나의 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 – 숨은 상태 스케일링 불일치로 인해 W4A4 양자화 Qwen Image 모델에서 내장 DiffSynth ControlNet을 사용할 수 없습니다(“알려진 제한 사항” 섹션 참조).
• AMD/ROCm – nunchaku 패키지를 가져올 수 없으면 Nunchaku에 종속된 핵심 노드가 비활성화됩니다. Krea2 관련 노드만 작동합니다.
• 실험적 AWQ 지원 – AWQ 변조 레이어에 LoRA를 적용하는 것은 아직 실험적이며 향후 릴리스에서 변경될 수 있습니다.

---

위의 모든 정보는 저장소의 README에서 직접 가져온 것입니다. 추가 기능은 추측되지 않았습니다.