Qwen-Image-2.1용 Heretic 텍스트 인코더와 ComfyUI GGUF 로더 패치

AI 요약

이 저장소는 Qwen-Image-2.1에서 쓰는 Qwen3-VL-8B 텍스트 인코더의 Heretic 파생 모델과 ComfyUI용 GGUF 로딩 패치를 제공합니다. 문서의 중심은 두 가지 오류 해결입니다. 텍스트 인코더에서 [1, 512, 12288] 크기 입력으로 정규화 오류가 나거나, 일부 Qwen-Image-2.1 DiT GGUF에서 Unknown model architecture!가 발생하는 문제입니다.

GGUF 로딩 오류와 패치

ComfyUI-GGUF는 기존에 Qwen2-VL 비전 타워만 불러오고 Qwen3-VL 비전 타워는 처리하지 않았습니다. 그 결과 인코더를 Qwen3-VL로 인식하지 못해 12288차원 hidden state를 만들고, 4096차원을 기대하는 계층에서 오류가 발생합니다. ComfyUI-GGUF-Qwen3VL-TE 패치는 같은 폴더의 mmproj 파일에서 비전 타워를 읽고 텐서 이름을 ComfyUI의 Qwen3-VL 형식인 model.visual.*로 맞춥니다. 참조 이미지를 쓰는 이미지 편집에서도 비전 타워를 활용합니다.

두 번째 수정은 아키텍처 메타데이터가 없는 DiT GGUF를 처리합니다. general.architecture 정보가 없는 파일은 텐서 이름을 기준으로 판별하지만, ComfyUI-GGUF가 Qwen-Image 항목을 지원하지 않아 로드에 실패할 수 있습니다. 패치는 img_in, txt_in.in_layer, txt_in.text_norm 이름을 찾아 qwen_image 아키텍처로 판별합니다. 이미 메타데이터가 있는 파일에는 이 수정이 필요하지 않으며, 향후 ComfyUI-GGUF가 해당 사례를 직접 처리하면 패치는 아무 작업도 하지 않습니다.

설치와 모델 선택

GGUF 텍스트 인코더를 쓰려면 ComfyUI-GGUF와 저장소의 패치 노드를 설치하고, qwen3vl_8b_heretic-Q4_K_M.gguf 및 비전 타워 파일인 mmproj-qwen3vl_8b_heretic-f16.gguf를 ComfyUI/models/text_encoders/에 둡니다. 두 파일은 이름을 바꾸지 않아야 합니다. ComfyUI를 다시 시작한 뒤 CLIPLoaderGGUF에서 qwen_image를 선택하고 TextEncodeQwenImage21로 연결합니다. 콘솔에 mmproj에서 Qwen3-VL 비전 텐서 351개를 추가했다는 메시지가 표시되는지 확인합니다.

선택지는 세 가지입니다. GGUF Q4_K_M 텍스트 인코더는 5.03GB이고 비전 타워는 1.16GB입니다. NVIDIA GPU에서는 FP8 safetensors 9.34GB를 기본 CLIPLoader로 불러올 수 있습니다. Mac을 포함한 비CUDA 환경에는 BF16 safetensors 17.53GB를 안내합니다. 저장소에는 각 설정에서 쓸 파일과 로더가 정리돼 있습니다. 전체 파이프라인은 선택형 PE-T2I 프롬프트 재작성기, 텍스트 인코더, Qwen-Image-2.1 DiT, 공식 VAE로 구성합니다.

생성 설정과 검증

문서는 Qwen-Image-2.1이 distillation을 거치지 않은 모델이라며 25 sampling steps를 권합니다. 더 많은 단계가 이미지 속 글자를 선명하게 만들지는 않으며 하이라이트가 과하게 표현될 수 있다고 설명합니다. 이미지에 글자가 필요 없다면 CFG 1.0의 일반 KSampler를 씁니다. 간판이나 포스터처럼 글자가 필요한 경우에는 KSamplerAdvanced 두 개를 연결합니다. 첫 절반에서 3분의 2까지 CFG 1.0으로 구도와 재질을 잡고, 남은 단계는 CFG 3.0과 negative prompt로 글자를 다시 그립니다. 25단계 기준 분할 지점은 12~17단계이며, 늦게 나눌수록 CFG 1.0의 표현을 더 유지하고 일찍 나눌수록 글자가 또렷해집니다.

제작자는 2026년 9월 23일 ComfyUI 0.36.0과 ComfyUI-GGUF에서 NVIDIA GPU로 텍스트-이미지 생성과 참조 이미지 편집을 확인했다고 적었습니다. 같은 seed에서 BF16 인코더 출력과 비교했을 때 차이는 Q4 양자화 노이즈 수준이었다고 보고했으며, Mac에서는 시험하지 않았다고 밝혔습니다.

Heretic 파생 모델의 수치

저장소는 이 계열을 Heretic directional ablation으로 만들었다고 설명합니다. o_proj와 down_proj를 대상으로 200회 실험과 60회의 초기 실험을 거쳐 Pareto front의 knee point를 골랐다고 합니다. 제작자 측 측정에서 기본 Qwen-Image-2.1 텍스트 인코더는 100회 중 100회 거부했고, 파생 모델은 100회 중 5회 거부했습니다. KL divergence는 0.0220으로 기재돼 있습니다. BF16 원본을 별도로 확인한 결과도 20회 중 거부 0회, 무해한 질문 4개 중 정답 4개라고 보고합니다. 이는 저장소가 제시한 자체 평가 수치입니다.

원문: Hugging Face / 번역·요약: Trawling