ClipProj: ComfyUI에서 MiniMax H3의 32B 텍스트 인코더를 4B로 교체하기

ComfyUI-ClipProj는 MiniMax H3의 Qwen3-VL-32B 텍스트 인코더를 훨씬 작은 Qwen3-VL-4B와 학습된 선형 투영으로 대체하는 새로운 커스텀 노드입니다. 조건화 VRAM 사용량을 15.7GB에서 4.5GB로 줄입니다(Hugging Face의 투영 행렬). DiT, VAE, 샘플러는 그대로 유지됩니다. 노드는 공식 CLIP처럼 동작하는 객체를 반환하므로 기존 clip 입력에 그대로 연결할 수 있으며, 별도의 재연결이 필요 없습니다.

전체 파이프라인: 인코더, 투영, 조건화, 샘플링, 디코딩, 비디오 출력 (examples/minimax_h3_clipproj.json).

VRAM을 크게 절약하는 이유

MiniMax H3는 프롬프트를 [seq, 5120] 조건화 텐서로 변환하기 위해서만 50개 레이어로 잘린 Qwen3-VL-32B(NVFP4 기준 15.7GB)를 사용합니다. ClipProj는 이를 Qwen3-VL-4B(2560차원)와 DiT가 기대하는 5120차원 공간으로 매핑하는 학습된 선형 매핑으로 대체합니다.

cond = ((h - mean_in) / std_in) @ W * std_out + mean_out

측정된 인코더 메모리:

투영 학습 방식

4B와 32B 인코더는 동일한 토크나이저(151,936개 토큰)를 공유하므로, 동일한 프롬프트는 두 모델 모두에서 동일한 위치에 동일한 토큰을 생성합니다. 따라서 위치별 매핑을 학습할 수 있습니다. 캘리브레이션은 학습이 아닌 **릿지 회귀(ridge regression)**입니다. 두 모델로 N개의 프롬프트를 인코딩하고 XᵀX와 XᵀY를 스트리밍 방식(일정한 메모리)으로 누적한 다음 해를 구합니다. 그래디언트, 에포크, 학습률이 전혀 필요 없습니다.

작성자의 측정 결과(MEASUREMENTS.md)에 따르면 2,000개 프롬프트 코퍼스에서 프롬프트 간 코사인 유사도는 약 0.71입니다. 실제 생성에서 투영은 단순 프롬프트, 구조화된 멀티샷 프롬프트(subject_definitions, 타임코드가 지정된 샷, overall_soundscape), 첫 번째 및 마지막 프레임을 사용하는 fl2va에서도 잘 작동합니다. 또한 인코더 가중치 교체에도 강건합니다. bf16으로 캘리브레이션된 투영은 abliterated fp8 변형과 int8_convrot에서도 그대로 작동합니다.

ComfyUI 사용법

노드를 설치합니다:

cd ComfyUI/custom_nodes
git clone https://github.com/nicolab28/ComfyUI-ClipProj

ComfyUI를 재시작합니다. requirements.txt는 없습니다. 노드는 torch와 ComfyUI 자체 모듈만 가져옵니다. 첫 실행 시 ComfyUI/models/clip_projections/ 폴더가 생성됩니다. 투영 행렬(mmh3-4b-ClipProj*.safetensors, mmh3-8b-ClipProj*.safetensors)을 해당 폴더에 넣으세요. 예제 워크플로는 examples/에 있습니다. minimax_h3_clipproj.json을 캔버스로 끌어다 놓으세요.

소형 인코더와 구조화된 H3 프롬프트 재작성을 함께 사용하는 예제 워크플로 (examples/rewrite_h3_prompt.json).

상태

노드 버전 0.1.4에서는 대체 인코더를 로딩하기 전에 GPU 카드를 해제하고(두 인코더가 동시에 상주할 때 발생하는 OOM 급증을 수정), 재로드 시 투영 캐시를 해제하며, 잔차 네트워크를 저장된 정밀도로 유지합니다. -mlp 행렬은 이제 fp16이며 크기가 절반으로 줄었습니다(4B 기준 240MB, 8B 기준 288MB).

이 프로젝트는 명시적으로 **개념 증명(proof of concept)**입니다. 단일 환경(Windows 11, NVIDIA RTX 3090 / 4070 / 3060, ComfyUI 0.31.0)에서 의도적으로 탐색 범위를 제한하여 구축 및 테스트되었습니다. 다듬어지지 않은 부분과 호환성을 깨는 변경이 있을 수 있습니다.

다운로드

• 커스텀 노드: nicolab28/ComfyUI-ClipProj
• 투영 행렬: Hugging Face의 NicoLab28/ClipProj-MiniMax-H3(4B 및 8B 변형, celeb 및 -mlp 옵션 포함)