Nunchaku Lite – Diffusers에서 바로 쓰는 4비트 확산 모델 추론 경로

배경
어떻게 동작하는가
기본 사용법
성능 포인트
하드웨어 제약
언제 쓰면 좋은가
관련 문서
참고 자료

Nunchaku Lite는 Nunchaku의 SVDQuant 계열 4비트 확산 모델 추론을 Hugging Face Diffusers 안에서 직접 로드하게 만든 통합 방식이다. 별도 CUDA 엔진이나 커스텀 파이프라인 없이 from_pretrained()로 양자화된 Diffusers 저장소를 불러오는 것이 핵심이다.

배경

대형 diffusion transformer는 BF16 기준으로 20~30GB 이상의 VRAM을 요구하는 경우가 많다. 일반적인 weight-only 양자화는 모델 저장 공간과 메모리를 줄이지만, 계산 시 다시 고정밀도로 풀어야 해 지연 시간이 크게 줄지 않을 수 있다. Nunchaku 계열의 SVDQuant는 주요 transformer projection에서 weight와 activation을 함께 4비트로 처리해 메모리와 속도를 동시에 겨냥한다.

어떻게 동작하는가

Nunchaku Lite는 원래 Diffusers 모델의 nn.Linear 모듈을 런타임에 양자화 레이어로 교체한다. 모델 저장소의 config.json 안에는 어떤 모듈이 어떤 방식으로 양자화됐는지 나타내는 quantization_config가 들어간다.

레이어	역할
`svdq_w4a4`	attention·MLP projection에 쓰는 4비트 weight/activation 경로
`awq_w4a16`	adaptive normalization, modulation projection처럼 정밀도에 민감한 경로
`kernels` 패키지	필요한 CUDA kernel을 Hugging Face Hub에서 내려받아 실행

기본 사용법

pip install -U diffusers transformers accelerate kernels bitsandbytes

import torch
from diffusers import ErnieImagePipeline

pipe = ErnieImagePipeline.from_pretrained(
    "lite-infer/ERNIE-Image-Turbo-nunchaku-lite-nvfp4_r32-bnb4-text-encoder",
    torch_dtype=torch.bfloat16,
).to("cuda")

image = pipe(
    prompt="A cinematic portrait of a red fox in a misty forest at sunrise",
    height=1024,
    width=1024,
    num_inference_steps=8,
    guidance_scale=1.0,
).images[0]

성능 포인트

Hugging Face 블로그의 ERNIE-Image-Turbo 측정에서는 BF16 baseline 대비 Nunchaku Lite가 peak VRAM을 크게 줄이고, end-to-end latency도 개선했다. torch.compile을 함께 쓰면 kernel launch 오버헤드를 일부 줄여 속도 개선 폭이 더 커진다.

구성	장점
Nunchaku Lite	VRAM 절감, 별도 엔진 없는 Diffusers 로딩
Nunchaku Lite + `torch.compile`	end-to-end latency 추가 개선
NF4 text encoder 병행	transformer 외 text encoder 메모리까지 절감
CPU offload	더 작은 GPU에 맞추는 fallback

하드웨어 제약

NVFP4 checkpoint는 NVIDIA Blackwell 세대 GPU가 필요하다. RTX 30·40, A100, L40S 같은 이전 세대에서는 INT4 variant를 써야 한다. Volta와 Hopper는 현재 4비트 kernel 지원 대상이 아니므로, 배포 전에 GPU 세대를 확인해야 한다.

언제 쓰면 좋은가

FLUX, Qwen-Image, ERNIE-Image 계열처럼 큰 diffusion transformer를 소비자 GPU에서 돌리고 싶다.
기존 Diffusers 파이프라인, scheduler, LoRA, offloading 흐름을 유지하고 싶다.
별도 inference engine을 붙이기보다 Hugging Face Hub 모델 저장소 하나로 배포하고 싶다.

참고 자료

Bringing Nunchaku 4-bit Diffusion Inference to Diffusers — Hugging Face Blog (2026-07-23)
nunchaku-tech/nunchaku — GitHub 공식 저장소
rootonchair/diffuse-compressor — GitHub 공식 저장소

Like?

AI Sparkup