﻿Ultra Qwen Image Editor + PiD
정식 사용 설명서 v1.0.4
============================================================

1. 제품 개요
------------------------------------------------------------
Ultra Qwen Image Editor + PiD는 ComfyUI 안에서 사진이나 참조 이미지를
불러오고 자연어 편집 지시로 수정하는 Qwen 전용 커스텀 노드입니다.

지원 모델 계열
  - Qwen Image Edit 2511: 참조 이미지 최대 3장, 선택적 PiD 업스케일
  - Qwen Image 2.1: 참조 이미지 최대 10장, 일반 및 Turbo 체크포인트

모델 계열에 따라 필요한 확산 모델, 텍스트 인코더, VAE가 다릅니다.
다른 용도의 이미지 생성 전용 체크포인트는 편집 모델을 대신할 수 없습니다.

이 노드에는 이미지 파일 저장 기능이 포함되어 있지 않습니다.
최종 이미지는 반드시 별도의 Save Image 노드 등에 연결하여 저장하세요.

2. 설치
------------------------------------------------------------
(1) ComfyUI를 완전히 종료합니다.
(2) 압축을 풀어 폴더 구조가 다음과 같이 되도록 복사합니다.
    ComfyUI/custom_nodes/comfyui-Ultra-Qwen-Image-Editor/
      __init__.py
      ultra_image_editor.py
      web/ultra_image_editor.js
      pyproject.toml
      requirements.txt
      README.md
      ...
(3) 이전 이름의 같은 Ultra Image Editor 커스텀 노드가 남아 있으면
    중복 로딩을 막기 위해 이전 폴더를 이동하거나 제거합니다.
    다른 노드인 comfyui-Ultra-Image-PiD는 별개입니다.
(4) 사용 모델 파일을 ComfyUI/models/의 해당 폴더에 설치합니다.
(5) ComfyUI를 다시 실행하고 노드 검색에서
    'Ultra Qwen Image Editor + PiD'를 찾아 배치합니다.

이 노드는 별도의 pip 패키지를 추가 설치하지 않습니다.
최신 ComfyUI 코어에 TextEncodeQwenImageEditPlus 및
TextEncodeQwenImage21, KSampler 등의 실행 기능이 있어야 합니다.
PiD 업스케일에는 ComfyUI 코어의 PiD 관련 노드 및 Gemma 2 ELM,
호환되는 QwenImage PiD 체크포인트가 추가로 필요합니다.

3. 필요한 모델 파일과 선택 방법
------------------------------------------------------------
주요 모델 폴더
  - models/diffusion_models : Qwen 편집 확산 모델 / QwenImage PiD 모델
  - models/text_encoders   : Qwen VL 인코더 / PiD용 Gemma 2 ELM
  - models/vae             : 해당 Qwen 계열의 VAE
  - models/loras           : 선택적 LoRA

Qwen Image Edit 2511
  확산 모델 : Qwen Image Edit 2511 호환 파일
  인코더    : Qwen 2.5 VL 7B 계열
  VAE       : Qwen Image VAE

Qwen Image 2.1
  확산 모델 : Qwen Image 2.1 Base 또는 Turbo 호환 파일
  인코더    : Qwen3 VL 호환 파일
  VAE       : Qwen Image 2.1 전용 VAE

실제 파일명은 배포처와 정밀도(BF16/FP8)에 따라 다를 수 있습니다.
잘못된 계열 이름이 명백한 모델은 로드 전에 차단하지만, 파일명이
중립적인 사용자가 만든 모델의 가중치 호환성까지 자동 검증하지는 않습니다.

모델 드롭다운에 <select installed model>이 표시되면
필요한 모델 파일이 설치되지 않았거나 적합한 파일이 없다는 뜻입니다.
올바른 파일을 설치하여 다시 선택한 뒤 실행하세요.

4. 기본 이미지 편집 절차
------------------------------------------------------------
(1) Model Family에서 모델 계열을 선택합니다.
(2) Diffusion Model, Text Encoder, VAE를 지정합니다.
(3) Load Image 등의 IMAGE 출력을 image1에 연결합니다.
(4) Positive Prompt에 원하는 변화를 입력합니다.
(5) 필요하면 Negative Prompt, Steps, CFG, LoRA, 해상도를 조정합니다.
(6) Edited Image 출력을 Save Image 노드에 연결합니다.
(7) ComfyUI에서 Queue Prompt(생성)를 실행합니다.

예: '이미지1의 인물과 얼굴은 유지하고 의상을 정장으로 바꿔줘.'
영문 예: 'Keep the person in image1 and change the outfit to a suit.'

5. 다중 이미지 연결과 수정 대상
------------------------------------------------------------
처음에는 image1만 표시되며, 연결하면 다음 빈 이미지 단자가 생깁니다.
Qwen 2511은 최대 3장, Qwen 2.1은 최대 10장까지 연결 가능합니다.
image1 → image2 → image3처럼 번호를 건너뛰지 않고 연결하세요.
이미지 단자를 중간에서 분리해도 기존 연결선과 번호를 마음대로
재배치하지 않습니다. 중간 번호가 비면 실행 전 알림이 나옵니다.

Edit Target
  auto   : image1을 수정 대상 이미지로 사용
  imageN : 연결한 해당 이미지가 수정 대상이 됨

여러 장을 연결했을 때 코어 Qwen 인코더는 수정 대상으로 선택한
이미지를 내부 Picture 1로 옮깁니다. 노드는 프롬프트의 영문·한국어
이미지 번호를 함께 재매핑해 실제 참조 이미지가 바뀌지 않게 합니다.

예: image1 = 모자 사진, image2 = 사람 사진일 때
    '이미지1의 모자를 이미지2의 사람에게 씌워줘.'
    Edit Target = image2로 지정해도 모자는 image1의 것을 뜻합니다.

지원되는 참조 표기 예
  image1, image 2, image_2, <image2>, Picture 2:
  이미지1, 이미지 2, 이미지2의, 이미지 2번, 이미지2번째
  사진1, 그림2, 2번 이미지, 2번째 사진

수량 표기는 이미지 번호로 바꾸지 않습니다.
  '이미지 2배 확대', '사진 2매', '그림 2초', '사진 2장'

주의: '이미지 1과 2', 'image 1 and 2'처럼 두 번호를 묶어 쓰면
두 번째 번호는 독립된 이미지 식별자로 파악되지 않을 수 있습니다.
반드시 '이미지1과 이미지2', 'image1 and image2'처럼
각 이미지에 이름을 붙여 명시하세요.

연결하지 않은 imageN을 프롬프트에 적으면 문장 자체는 유지되지만
그 참조 사진의 시각 정보는 모델에 전달되지 않습니다.

6. 해상도 설정
------------------------------------------------------------
Resolution Selection의 선택값
  auto_1mp : 기본값. 원본 가로세로 비율 유지, 약 1메가픽셀
  0.5MP    : 약 0.5메가픽셀
  1.5MP    : 약 1.5메가픽셀
  2MP      : 약 2메가픽셀
  original : 수정 대상 이미지의 원래 크기 사용
  custom   : Width / Height를 직접 설정

custom에서 가로 또는 세로가 0이면 해당 변은 원본 비율에
맞춰 자동 계산합니다. 두 변을 모두 지정해 원본 비율과 다르면
사진을 억지로 늘리거나 잘라 내지 않고 맞춤 크기 및 패딩을 사용합니다.

Qwen 2511은 내부 해상도를 16의 배수, Qwen 2.1은 32의 배수로
근사 정렬할 수 있습니다. Qwen 2.1의 original/custom 모드에서
수정 대상이 아닌 다른 참조 사진은 과도한 인코딩 부하를 막기 위해
약 1MP 이내로 조정될 수 있습니다.

original 또는 2MP와 같은 큰 크기는 VRAM과 처리 시간이 증가합니다.
PiD를 함께 사용하려면 내부 x4 해상도의 긴 변이 8192px 이하여야 합니다.

7. 샘플링과 Turbo 동작
------------------------------------------------------------
일반적인 최초 권장값
  Qwen Image Edit 2511 : Steps 20 / CFG 4 / KSampler
  Qwen Image 2.1 Base  : Steps 25 / CFG 1 / KSampler
  Qwen Image 2.1 Turbo : Steps 8  / CFG 1

Qwen Image 2.1 Turbo에서 파일명에 'turbo'가 포함되고 Steps=8이면
내장 8구간 ManualSigmas 시그마 스케줄로 샘플링합니다.
이때 사용자가 선택한 Sampler 및 CFG는 반영되지만
Scheduler 옵션은 사용하지 않습니다.

Turbo에서 Steps를 7, 10, 12 등 8 이외의 값으로 변경하면
일반 KSampler가 선택한 Steps/Sampler/Scheduler/CFG를 사용합니다.
일반 Qwen 2.1과 Qwen 2511은 Steps 값에 따라 항상 KSampler로
실행합니다. 사용자가 지정한 Steps·CFG는 모델별로 복원됩니다.

Zero Conditioning
  OFF : Negative Prompt를 인코딩합니다.
  ON  : 부정 컨디셔닝을 0으로 만듭니다.
CFG=1에서는 부정 프롬프트의 유도 효과가 거의 없을 수 있으며,
CFG를 올리면 결과가 달라질 수 있습니다. 지나친 증가는 주의하세요.

8. LoRA 추가 및 관리
------------------------------------------------------------
노드 하단의 '+ LoRA 추가'를 눌러 LoRA 목록을 선택합니다.
LoRA 파일은 models/loras 아래의 설치된 파일에서 가져옵니다.

LoRA 각 행의 기능
  ● / ○       : 개별 ON/OFF
  파일 이름   : LoRA 파일 다시 선택
  강도 숫자   : 강도 변경 (허용 범위 -100 ~ 100)
  우클릭 메뉴 : 위/아래 이동, 삭제, 강도 및 파일 변경, 목록 새로고침

표시된 LoRA 순서가 실제 적용 순서이며, 꺼 둔 행은 적용되지 않습니다.
동일한 Qwen 계열의 서로 다른 정밀도 모델은 LoRA 구성을 공유할 수
있지만, 모델별로 마지막 생성 설정과 현재 세션의 임시 수정 내용이
구분됩니다. 다른 계열의 LoRA가 자동으로 호환되는 것은 아닙니다.

9. PiD 업스케일 (Qwen 2511 전용)
------------------------------------------------------------
PiD Upscale을 ON으로 설정하면 편집이 끝난 잠재 공간 결과에 대해
별도의 QwenImage 호환 PiD 패스를 진행합니다.
Qwen Image 2.1에서는 PiD 옵션이 비활성화됩니다.

주요 옵션
  PiD Scene Prompt : 별도 장면 설명 (빈 값은 편집 프롬프트 사용)
  PiD Model        : 자동 또는 수동 PiD 체크포인트 선택
  PiD Sampler      : PiD 단계 샘플러
  PiD Scheduler    : PiD 단계 스케줄러
  PiD Steps        : PiD 샘플링 횟수
  PiD Output Scale : x4 / x2 (내부 x4 처리 후 x2는 축소)
  PiD Color Match  : 편집 이미지 색감에 맞춘 보정 ON/OFF

출력 단자
  Edited Image : PiD 이전의 편집 결과
  PiD Image    : PiD 확대 결과. PiD OFF 시에는 Edited Image와 동일

PiD 실행에는 qwenimage 호환 PiD 모델과 Gemma 2 ELM 텍스트
인코더가 필요합니다. ComfyUI 코어에 해당 PiD 기능이 없다면
관련 코어 노드가 없다는 오류가 나올 수 있습니다.

10. RAM 캐시 / Reuse Models
------------------------------------------------------------
기본 ON. 변경되지 않은 원본 확산 모델, 텍스트 인코더, VAE,
필요한 PiD 모델을 시스템 RAM에 가능한 범위에서 재사용합니다.
LoRA가 적용된 모델과 샘플링 결과는 캐시하지 않습니다.

캐시 정책은 원본 파일의 크기와 시스템 RAM 여유를 기준으로
보수적으로 판단하며, GPU VRAM 관리 기능을 대신하지 않습니다.
메모리 여유가 부족하거나 모델 파일을 교체한 경우에는
Reuse Models (RAM)을 OFF로 하고 한 번 실행하면 이 노드가
보관 중인 RAM 참조를 해제할 수 있습니다.

11. 모델별 설정 저장 및 워크플로
------------------------------------------------------------
모델별 저장 항목
  모델 파일, 인코더, VAE, Steps, CFG, Sampler, Scheduler,
  Zero Conditioning, PiD 및 모델 재사용 옵션, LoRA 설정

확정 프로필은 생성 명령이 성공적으로 큐에 등록됐을 때 저장됩니다.
GPU 생성의 성공/실패를 완료까지 확인한 시점과는 다릅니다.
생성 전에 조절한 Steps·CFG·LoRA 등은 모델을 왕복하더라도
같은 ComfyUI 편집 세션에서 임시로 되살릴 수 있습니다.

긍정·부정 프롬프트, PiD 장면 프롬프트, 수정 대상, 해상도,
Width/Height 및 Seed는 모델을 바꿔도 현재 작업값을 유지합니다.

새 브라우저 세션에서도 작업을 보존하려면 워크플로를 직접 저장하세요.
오래된 워크플로는 위젯 순서가 다를 수 있으므로, 맞지 않는 형식을
감지하면 설정을 안전한 기본값으로 초기화하고 안내할 수 있습니다.
과거 위젯 순서와 LoRA 값을 억지로 변환하지 않습니다.

12. 한글 / 영문 UI
------------------------------------------------------------
ComfyUI의 언어 설정(Comfy.Locale)이 한국어이면 한글,
영어이면 영문 표시 이름과 도움말을 적용합니다.
모델 선택, 프롬프트, 해상도, 시드, Steps, CFG, LoRA, PiD 등의
위젯 이름과 주요 툴팁·메뉴·알림에 적용됩니다.

모델 파일명, LoRA 파일명, 연결 단자 imageN, 내부 설정값
(auto_1mp, randomize, sampler 명칭 등)은 워크플로 호환을 위해
번역하지 않습니다. Python 백엔드 오류는 언어 설정과 관계없이
한국어로 나타날 수 있습니다.

13. 자주 발생하는 문제
------------------------------------------------------------
• '이미지가 연결되지 않았습니다'
  → image1에 이미지 1장을 연결하세요.

• '중간에 빈 IMAGE 번호' 알림
  → image1부터 순서대로 연결했는지 확인하세요.

• '<select installed model>' 표시 / 모델 누락
  → 선택한 Qwen 모델 계열과 맞는 확산 모델, 인코더, VAE를
    정확히 설치하고 다시 선택하세요.

• Qwen 2.1에서 PiD가 켜지지 않음
  → PiD는 Qwen 2511 전용입니다. 고장이 아닙니다.

• PiD Gemma 또는 체크포인트 오류
  → QwenImage PiD 체크포인트와 Gemma 2 ELM 인코더를 설치하세요.

• VRAM 부족 또는 생성 속도가 지나치게 느림
  → 해상도 또는 동시 참조 이미지 수를 줄이고 PiD 사용을 점검하세요.
    RAM 캐시 설정이 VRAM 한도를 늘려 주지는 않습니다.

• LoRA 파일이 목록에 보이지 않음
  → models/loras 아래 파일을 확인하고 목록을 새로고침하세요.

• 저장한 워크플로에서 설정이 초기화됨
  → 호환되지 않는 이전 위젯 순서가 감지될 수 있습니다.
    현재 노드를 새로 배치한 뒤 새 워크플로로 저장하세요.

• 서브그래프 일부만 선택 실행
  → 내부 출력만 선택했을 때 서브그래프 경계를 넘어선 외부
    상위 편집 노드의 프로필 저장 범위는 정확히 포함되지 않을 수
    있습니다. 확실한 모델별 프로필 저장이 필요하면 전체 출력
    경로를 큐에 등록하세요.

14. 개인 정보·메타데이터·삭제
------------------------------------------------------------
ComfyUI가 출력 이미지에 워크플로 메타데이터를 저장할 수 있고,
현재 입력한 편집 프롬프트 등이 그 데이터에 포함될 수 있습니다.
이미지를 공유하기 전 메타데이터 공개 여부를 확인하세요.

v1.0.4부터는 노드가 실제로 모델에 넣은 최종 긍정/부정 프롬프트를
이미지 메타데이터의 "ultra_generation_prompts" 항목에 함께 기록합니다.
번역기·LLM 노드 등을 거쳐 연결선으로 들어온 프롬프트도
변환 후의 실제 문장(image1/image2 번호 변환 포함)이 남습니다.
Ultra Exif Reader v4.12 이상에서 Final CLIP 프롬프트로 표시됩니다.
같은 설정으로 다시 실행해 노드 실행이 생략(캐시)된 경우에도 직전
기록을 다시 넣으며, 기록에 실패해도 이미지 생성은 계속 진행됩니다.

노드를 제거하려면 ComfyUI 종료 후 해당 custom_nodes 폴더를
삭제하면 됩니다. 이미 저장된 워크플로는 이 노드가 없으면
누락된 노드로 표시될 수 있습니다.

15. 라이선스
------------------------------------------------------------
GPL-3.0-or-later. 자세한 내용은 함께 제공된 LICENSE 파일 참고.

