양자화

양자화 (Quantization)

SGLang-Diffusion은 컴포넌트 경로 선택과 양자화 체크포인트 materialization을 별개의 능력으로 취급해요. 로드된 모든 컴포넌트는 독립적인 체크포인트 경로를 사용할 수 있지만, 해당 체크포인트는 선택된 로더가 직렬화 형식을 지원할 때만 양자화돼요. Transformer, 인코더, VAE 정밀도는 독립적으로 해석돼요.

출처: 문서

본문

SGLang-Diffusion은 컴포넌트 경로 선택과 양자화 체크포인트 materialization을 별개의 능력으로 취급해요. 로드된 모든 컴포넌트는 독립적인 체크포인트 경로를 사용할 수 있지만, 그 체크포인트는 선택된 로더가 직렬화 형식을 지원할 때만 양자화돼요. Transformer, 인코더, VAE 정밀도는 독립적으로 해석돼요.

빠른 참조 (Quick Reference)

가지고 있는 소스에서 옵션을 선택해요. 정밀도 이름에서가 아니라요:

소스 또는 연산 CLI 결과
완전한 컴포넌트 repo/디렉터리 --component-paths.<component> <source> 해당 컴포넌트의 구성과 가중치 교체
기존 컴포넌트의 가중치 파일/디렉터리 --component-weights-paths.<component> <source> 기본 컴포넌트 구성 유지, 가중치만 교체
비양자화 가중치의 온라인 양자화 --component-quantizations.<component> <method> 로드 중 지원되는 양자화 구현을 구성. 제외는 --component-quantization-ignored-layers.<component> 사용
기본 DiT 편의 철자 --transformer-path, --transformer-weights-path, --quantization 하나의 기본 DiT가 있는 파이프라인용 별칭. 지원되지만 일반 컴포넌트 이름은 아님
인과 KV-캐시 압축 --kv-cache-quant 체크포인트 가중치가 아닌 완료된 런타임 캐시 청크를 양자화

--model-path는 항상 기본 모델을 선택해요. 컴포넌트 키는 model_index.json 또는 네이티브 파이프라인 레지스트리의 실제 키여야 해요. 예를 들어 transformer, transformer_2, text_encoder, video_vae, audio_vae가 있지만 어떤 이름도 보편적이지 않아요.

사전 양자화 체크포인트의 권장 예시:

sglang generate \
  --model-path black-forest-labs/FLUX.2-dev \
  --component-weights-paths.transformer black-forest-labs/FLUX.2-dev-NVFP4 \
  --prompt "a curious pikachu"

양자화된 transformers 스타일 트랜스포머 컴포넌트 폴더의 경우:

sglang generate \
  --model-path /path/to/base-model \
  --component-paths.transformer /path/to/quantized-transformer \
  --prompt "A Logo With Bold Large Text: SGL Diffusion"

참고: 일부 모델별 통합은 양자화 repo나 로컬 디렉터리를 --model-path로 직접 수용하지만, 이는 호환 경로예요. repo에 여러 후보 체크포인트가 있으면 정확한 컴포넌트 또는 가중치 소스를 명시적으로 선택해요.

사전 양자화 파일은 자체 설명적이에요. 하나의 선택된 파일을 로컬 경로, owner/repo/path/file.safetensors, 또는 직접 Hugging Face 파일 URL로 전달하고 온라인 양자화 옵션을 추가하지 마세요. MiniMax-H3 compatibility table은 H3 컴포넌트 형식과 게시된 예제 소스의 정식 목록이에요. 이 페이지는 백엔드 패밀리와 공유 제약을 정의해요.

양자화 컴포넌트 저장소 (Quantized Component Repositories)

로드된 모든 컴포넌트는 독립 repo를 가리킬 수 있지만, 경로 라우팅이 모든 로더가 모든 양자화 형식을 materialize할 수 있음을 뜻하지는 않아요. SGLang은 다음 세 가지 명시적 경로 중 하나로 양자화 컴포넌트 체크포인트를 해석해요:

  • SGLang 양자화 구현으로 로드
  • 표준 컴포넌트를 Transformers 또는 Diffusers에 위임
  • 형식을 복원할 수 없으면 네이티브 plain-state 로더에서 fail closed
컴포넌트 경로 양자화 체크포인트 동작
transformer, transformer_2, unconditional_transformer, audio_dit, video_dit 아래 문서화된 SGLang 트랜스포머 양자화 어댑터 사용
text_encoder*, image_encoder* 호환 등록 네이티브 인코더 선호. 그 외 설치된 Transformers 버전이 인식하는 표준 최상위 quantization_config는 그 from_pretrained 경로에 위임. 지원되지 않는 형식과 메타데이터 위치는 fail closed
vae, video_vae, audio_vae 표준 최상위 Diffusers quantization_config는 AutoModel.from_pretrained에 위임. 네이티브 전용 VAE와 중첩/압축 메타데이터는 fail closed
라이브러리 관리 Transformers 또는 Diffusers 컴포넌트 상류 from_pretrained 경로에 위임하고 형식 지원·검증 동작 상속. 로컬 PE 모델은 이 경로 사용. 호환 형식은 모델별로 유지
원시 state dict를 로드하는 네이티브 보조 컴포넌트 해당 컴포넌트에 양자화 materialization 구현이 있을 때까지 모델 구성 전에 양자화 체크포인트 거부. 여기에는 connectors, duration heads, bridges, diffusion decoders, sound tokenizers, spatial upsamplers, vocoders 포함

--quantization은 기본 트랜스포머 로더의 명시적 오버라이드이고, --component-quantizations.<component>는 지원되는 한 컴포넌트에 대해 같은 의도를 표현해요. 후자는 --component-quantization-ignored-layers.<component>와 짝지어 일치 레이어를 비양자화로 유지해요. 사전 양자화 컴포넌트 repo는 대신 자체 메타데이터와 선택된 로더의 능력으로 형식을 선택해요. 일치하는 materialization 백엔드가 없는 일반 문자열 오버라이드는 컴포넌트가 가지지 못한 지원을 광고할 것이고, 일치 구성 메타데이터가 없는 양자화 가중치 파일은 일반적으로 식별되거나 복원될 수 없어요.

양자 패밀리 (Quant Families)

여기서 quant_family는 공유 CLI 사용과 로더 동작을 가진 체크포인트 및 로딩 패밀리를 의미해요. 단순한 수치 정밀도나 커널 백엔드가 아니에요.

quant_family 체크포인트 형태 체크포인트 셀렉터 지원 모델 추가 의존성 플랫폼 / 참고
fp8 / mxfp4 (온라인 양자화) 비양자화 체크포인트 (곧 AMD Quark로 오프라인) --component-quantizations.\<component> \{fp8,mxfp4} Z-Image-Turbo (검증됨), 다른 것도 작동할 가능성. 곧 추가 지원 MXFP4: ROCm의 aiter MXFP4는 ROCm 및 MI350+ (gfx95x) 필요. 가중치는 로드 시 양자화, 활성화는 동적으로 fp8 / mxfp4로 양자화
kitchen\_int8 (온라인 양자화) 비양자화 BF16/FP16 체크포인트 --component-quantizations.\<component> kitchen\_int8 MiniMax-H3 (1× RTX 4090 24 GB에서 검증) comfy-kitchen 로드 시 comfy\_kitchen.int8\_linear로 데이터 없는 INT8 ConvRot. 입력 차원이 그룹 크기로 나누어지지 않는 레이어는 BF16 유지. Turing+ (SM75) 필요
fp8 (오프라인 양자화) 양자화 트랜스포머 컴포넌트 폴더, 또는 quantization\_config 메타데이터가 있는 safetensors --component-paths.\<component> 또는 --component-weights-paths.\<component> 선형 레이어가 선택된 FP8 방법을 지원하는 네이티브 DiT. 모델별 품질 검증 없음 컴포넌트 폴더와 단일 파일 흐름 모두 지원
modelopt-fp8 config.json이 있는 변환 ModelOpt FP8 트랜스포머 디렉터리 또는 repo --component-paths.\<component> FLUX.1, FLUX.2, Wan2.2, HunyuanVideo, Qwen Image, Qwen Image Edit 없음 직렬화 구성은 quant\_method=modelopt + quant\_algo=FP8 유지. dit\_layerwise\_offload 지원, dit\_cpu\_offload 비활성 유지
auto-round W4A16 자체 설명 quantization\_config 및 auto\_round:auto\_gptq 패킹이 있는 트랜스포머 컴포넌트 repo --component-paths.\<component> 호환 컴포넌트 파라미터 매핑을 가진 네이티브 dense DiT. MiniMax-H3 Diffusers 컴포넌트 지원 없음 자동 감지. SRT GPTQ/Marlin 백엔드 재사용. --quantization 플래그 불필요. FSDP 대신 TP/시퀀스 병렬 처리 사용
modelopt-nvfp4 config.json이 있는 혼합 트랜스포머 디렉터리/repo, 원시 또는 Comfy 레이어 마크 NVFP4 safetensors, 또는 전체 ModelOpt Diffusers repo 컴포넌트 repo용 --component-paths.\<component>; 원시 파일용 --component-weights-paths.\<component>; 전체 repo용 --model-path FLUX.1, FLUX.2, Wan2.2, Qwen Image, Qwen Image 2512, Qwen Image Edit, Qwen Image Edit 2511, MiniMax-H3 없음 혼합 오버라이드 repo는 기본 모델을 분리 유지. 전체 Qwen Image export는 --model-path로 직접 로드. black-forest-labs/FLUX.2-dev-NVFP4 같은 원시 export는 weights-path 흐름 사용. Comfy 마커는 NVFP4 + INT8 또는 FP8 동반 linear를 자동 선택. --quantization 생략
gguf 하나의 선택된 GGUF DiT 또는 네이티브 인코더 파일 --component-weights-paths.\<component> MiniMax-H3 원본 또는 pruned FL2VA / Ref2VA DiT 및 그 Qwen3-VL 텍스트 인코더 없음 CUDA 전용 및 자동 감지. 표준 및 K-quant GGML 유형 지원. TP는 정렬된 GGML 블록 필요. 컴포넌트/layerwise offload 지원, FSDP 아님
comfy-fp8 레이어별 comfy\_quant 메타데이터가 있는 하나의 선택된 Comfy safetensors 파일 --component-weights-paths.\<component> MiniMax-H3 pruned FL2VA / Ref2VA DiT 없음 CUDA, 자동 감지. TP, 시퀀스 병렬 처리, 컴포넌트/layerwise offload 지원, FSDP 아님. 체크포인트 마크 fc2 레이어는 FP8 저장소 유지, compute-dtype matmul 사용
comfy-int8-convrot 레이어별 int8\_tensorwise 및 ConvRot 메타데이터가 있는 하나의 선택된 safetensors 파일 --component-weights-paths.\<component> 파라미터 매핑이 각 마크 linear를 보존하는 네이티브 DiT와 인코더. MiniMax-H3 DiT 및 Qwen3-VL 인코더 체크포인트가 검증된 텐서 계약 보유 comfy-kitchen CUDA, 자동 감지. 융합 Kitchen INT8 커널 사용, 모델 구성 전 가중치/스케일 레이아웃 검증. TP는 모든 row-parallel 입력 샤드가 체크포인트의 ConvRot 그룹 경계를 보존해야 함. H3 256-그룹 DiT는 TP1/2/4 지원, TP8 아님. Qwen3-VL 인코더는 비호환 row projection만 복제해 TP8 유지. Offload 지원, FSDP 아님
mxfp8 자체 설명 직렬화 가중치, 또는 온라인 양자화용 BF16/FP16 가중치 --component-weights-paths.\<component>, 또는 온라인으로 --component-quantizations.\<component> mxfp8 네이티브 확산 linear. 혼합 MiniMax-H3 체크포인트는 레이어별 선택 SRT의 플랫폼 MXFP8 백엔드 직렬화 메타데이터는 자동 감지. NVIDIA와 ROCm은 SRT의 dense MXFP8 커널 재사용. Ascend는 네이티브 온라인 경로 유지. 혼합 레이어별 체크포인트는 FSDP 미지원
comfy-w4a8-convrot 직렬화 asym\_w4a8\_int8 레이어 메타데이터와 패킹 가중치가 있는 safetensors --component-weights-paths.\<component> MiniMax-H3 FL2VA / Ref2VA DiT 및 네이티브 Qwen3-VL 인코더 comfy-kitchen>=0.2.27 자동 감지. --quantization 생략. SM80+ 필요. 모델 구성 전 패킹 가중치, 그룹/채널 스케일, 선택 코드북 검증. 혼합 인코더 파일은 임베딩 tensorwise INT8을 유지할 수 있음. TP는 ConvRot 그룹 경계 보존 필요. offload 지원, FSDP 아님
comfy-w4a4-convrot 직렬화 convrot\_w4a4 메타데이터, 선택적으로 int8\_tensorwise 레이어와 혼합된 safetensors --component-weights-paths.\<component> 일치 파라미터 매핑이 있는 네이티브 DiT와 인코더. MiniMax-H3 FL2VA / Ref2VA DiT 및 Qwen3-VL 인코더 레이아웃 인식 comfy-kitchen 자동 감지. --quantization 생략. 각 레이어는 직렬화된 W4A4 또는 INT8 ConvRot 커널로 디스패치. CUDA는 SM75+ 필요. TP는 각 형식의 양자화 및 ConvRot 그룹 경계 보존 필요. offload 지원, FSDP 아님
comfy-nvfp4 직렬화 nvfp4 및 선택 스칼라/행 단위 int8\_tensorwise 레이어 메타데이터가 있는 safetensors --component-weights-paths.text\_encoder MiniMax-H3 네이티브 Qwen3-VL 인코더 NVFP4 matmul용 comfy-kitchen 자동 감지. 명시적 양자화 생략. 고니블 우선 가중치, swizzled 블록 스케일, 선택 AWQ 입력 프리스케일 보존. full\_precision\_matrix\_mult 선언 레이어는 패킹 저장소로 BF16/FP16 계산 사용. 다른 NVFP4 레이어는 NVIDIA SM100+에서 동적 활성화 양자화 및 NVFP4 matmul 사용. 동반 INT8 임베딩은 전체 테이블 확장 없이 스칼라 또는 행별 스케일 지원
quanto-int8 임베디드 Quanto 양자화 맵이 있는 하나의 네이티브 인코더 safetensors 파일 --component-weights-paths.\<component> 매핑된 linear 레이어가 모든 선언된 qint8 항목을 소비하는 네이티브 인코더. MiniMax-H3의 Qwen3-VL 인코더 지원 없음 자동 감지 weight-only qint8 저장소. 각 활성 행렬은 일반 linear 연산을 위해 compute dtype으로 역양자화되므로 INT8 GEMM 속도를 약속하는 대신 저장/상주 가중치 메모리를 줄임. TP 및 offload 지원, FSDP 아님
qvg-kv 런타임 인과 KV-캐시 압축이 있는 비양자화 모델 --kv-cache-quant \{int4,int2} LingBot World 실시간 인과 경로 quant-videogen CUDA 전용. 모델 가중치가 아닌 완료된 캐시 청크 압축. 손실, 기본 비활성
nunchaku-svdq 사전 양자화 Nunchaku 트랜스포머 가중치, 보통 `svdq-{int4 fp4}_r{rank}-...`로 명명 --transformer-weights-path Qwen-Image, FLUX, Z-Image 같은 모델별 지원 nunchaku
msmodelslim 사전 양자화 msmodelslim 트랜스포머 가중치 --model-path Wan2.2 family 없음 현재 Ascend NPU family와만 호환. mxfp8, mxfp4, w8a8, w4a4 지원

인과 KV-캐시 양자화 (Causal KV-Cache Quantization)

Quant-VideoGen KV-캐시 양자화는 인과 self-attention 캐시가 모델 가중치와 비슷해질 수 있는 장기 실행 autoregressive 비디오 세션을 대상으로 해요. 체크포인트 가중치를 변경하거나 양자화하지 않아요.

세션 수명 주기, 지원 파이프라인, 실시간과 요청 기반 인과 생성의 차이는 Realtime and Causal Video Models 참고.

선택 의존성을 설치하되 오래된 Torch 요구사항이 SGLang의 고정 Torch 버전을 대체하지 않게 하고, 지원되는 LingBot World 실시간 파이프라인을 서빙할 때 int4 압축을 활성화해요:

pip install "sglang[diffusion,diffusion-qvg]"
pip install --no-deps quant-videogen==0.1.0

sglang serve \
  --model-path robbyant/lingbot-world-fast-diffusers \
  --pipeline-class-name LingBotWorldCausalDMDPipeline \
  --num-gpus 4 \
  --ulysses-degree 4 \
  --kv-cache-quant int4 \
  --dit-cpu-offload false \
  --text-encoder-cpu-offload false

저장소 정책 (Storage Policy)

현재 청크는 매 디노이징 스텝마다 다시 작성되므로 BF16으로 유지돼요. 가장 최근 --kv-cache-quant-keep-recent 완료 청크도 BF16으로 유지돼요. 더 오래된 완료 청크는 안정적이고 Progressive Residual Quantization (PRQ)으로 한 번 패킹되며, 그 dense BF16 텐서는 해제돼요.

트랜스포머 레이어가 attention을 실행하면 패킹된 보이는 청크를 역양자화하고 최근 BF16 청크와 연결해요. 이는 모든 트랜스포머 레이어에 dense 윈도우를 상주시키는 대신 한 레이어의 dense 어텐션 뷰를 한 번에 만들어요.

PRQ 작동 방식 (How PRQ Works)

각 K 또는 V 벡터에 대해 PRQ는 k-means로 중심을 선택한 다음 나머지 오차를 양자화해요:

x = centroid_1 + residual_1
residual_1 = centroid_2 + residual_2
...
x_hat = centroid_1 + centroid_2 + ... + dequantize(low_bit_residual)

각 추가 단계는 이전 단계의 잔차에 또 다른 중심 조회를 적용해요. SGLang 기본은 한 단계, 128 중심, int4 또는 int2 블록 양자화 잔차를 사용해요. 더 많은 단계나 중심은 재구성 오차를 줄일 수 있지만 코드북 저장소와 패킹 작업을 추가해요.

PRQ는 압축 알고리즘이고, 더 오래된 완료 청크를 선택하는 것은 이를 실용적으로 만드는 런타임 저장소 정책이에요. 안정적인 청크는 한 번 압축되고, 변경 가능하거나 최근 청크는 반복 패킹을 피하고 더 높은 정밀도를 유지해요.

품질 및 성능 (Quality And Performance)

Warning KV-캐시 양자화는 손실이에요. 비활성화하면 원본 dense BF16 캐시를 사용하고 수정되지 않은 경로와 비트 정확해요. int4 또는 int2를 활성화하면 K와 V의 근사치를 재구성하므로 고정 시드 생성 프레임이 BF16과 픽셀 동일할 것으로 기대하지 마세요.

초기 LingBot 측정에서 int4는 24-프레임 창에 대해 dense 상주 KV-캐시 메모리의 약 47%를 사용했고 청크당 지연 시간을 약 18% 추가했어요. Int2는 dense 상주 KV-캐시 메모리의 약 37%를 사용하지만 더 많은 양자화 오차를 만들었어요. 이 측정은 구성별이에요. 의도된 세션 길이에서 메모리, 지연 시간, 시간적 일관성, 정체성 안정성, 모션 품질을 벤치마크해요. 용량에 int2가 필요하지 않으면 int4로 시작해요.

현재 구현은 LingBot 실시간 sliding-window-and-sink 경로( Ulysses 시퀀스 샤딩 포함)로 제한돼요. LongLive2 pinned sinks, global sinks, 동적으로 성장하는 캐시는 지원하지 않아요.

튜닝 옵션 (Tuning Options)

옵션 기본값 효과
--kv-cache-quant {off,int4,int2} off QVG KV-캐시 압축 활성화 및 잔차 정밀도 선택
--kv-cache-quant-stages 1 진행 중심-잔차 단계 수
--kv-cache-quant-centroids 128 단계당 k-means 중심 수
--kv-cache-quant-block-size 64 최종 잔차 양자화에 사용되는 블록 크기
--kv-cache-quant-iters 2 청크 패킹 중 사용되는 k-means 반복
--kv-cache-quant-asymmetric disabled 비대칭 잔차 양자화 사용
--kv-cache-quant-keep-recent 1 BF16으로 유지되는 가장 최근 완료 청크 수
--kv-cache-quant-sink {0,1} 1 완료된 sink 청크 양자화 여부
--kv-cache-quant-sink-keep 0 BF16으로 유지되는 선행 sink 청크 수

온라인 양자화 (Online Quantization)

이 섹션은 트랜스포머 로더가 현재 구현한 온라인 방법을 설명해요. 사전 양자화 트랜스포머 체크포인트를 사용할 수 없을 때 유용해요. 인코더, VAE, 보조 컴포넌트는 독립적이에요. 그들의 저장소는 여전히 직렬화된 양자화 가중치를 운반할 수 있고, 선택된 컴포넌트 로더가 그 형식을 지원하면 복원돼요.

FP8 온라인 양자화 (FP8 Online Quantization)

지원되는 비양자화 DiT 체크포인트에 FP8 양자화를 적용해요:

sglang generate \
  --model-path Tongyi-MAI/Z-Image-Turbo \
  --component-quantizations.transformer fp8 \
  --prompt "a beautiful sunset" \
  --save-output

기본 DiT가 transformer로 명명된 파이프라인의 경우 더 짧은 --quantization fp8 철자가 동일해요.

MiniMax-H3는 필요한 FP32 패치, timestep, 출력 projection을 보존하면서 이 경로를 지원해요. 분산 서빙 레시피는 MiniMax-H3 cookbook 참고.

MXFP4 온라인 양자화 (MXFP4 Online Quantization)

MXFP4는 온라인 양자화로 공격적인 4비트 압축을 제공해요. 참고: ROCm 및 MI350+ (gfx95x) GPU 필요.

sglang generate \
  --model-path Tongyi-MAI/Z-Image-Turbo \
  --component-quantizations.transformer mxfp4 \
  --prompt "a beautiful sunset" \
  --save-output

참고: MXFP4 커널 지원이 있는 aiter 패키지 필요

Kitchen INT8

직렬화 Comfy ConvRot INT8 DiT 및 호환 네이티브 인코더는 --component-weights-paths.<component>를 사용해요. 둘 다 레이어별 마커에서 자동 감지되고 INT8 가중치와 행 스케일을 직접 로드해요. 온라인 양자화는 생략하세요. --transformer-weights-path는 기본-DiT 편의 철자로 유지돼요.

BF16 체크포인트의 경우 대신 --component-quantizations.transformer kitchen_int8이 로드 후 온라인 양자화를 수행해요.

kitchen_int8은 표준 BF16 체크포인트에서 DiT linear 가중치를 온라인으로 양자화해요. Forward는 융합 comfy_kitchen.int8_linear 연산(회전, 동적 행별 활성화 양자화, INT8 GEMM, 역양자화, 바이어스)을 사용해요. 먼저 선택 의존성을 설치해요:

pip install comfy-kitchen

sglang generate \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --component-quantizations.transformer kitchen_int8 \
  --attention-backend fa \
  --performance-mode memory \
  --layerwise-offload-components dit,text_encoder \
  --dit-offload-prefetch-size 1 \
  --dit-layerwise-resident-layers 0 \
  --enable-torch-compile false \
  --prompt "A cat walking on a sunny beach, gentle waves." \
  --save-output

양자화는 모델 가중치 로더 후 실행되므로 MiniMax-H3의 그룹 qkv 재정렬이 이미 적용돼요. 입력 차원이 그룹 크기(256)로 나누어지지 않는 레이어는 로드를 실패하는 대신 BF16으로 유지돼요. H3의 AdaLN projection이 그 경로를 취해요.

Warning kitchen_int8은 근사이며 일관성 ground-truth 모드가 아니에요. comfy-kitchen이 설치되지 않으면 BF16 경로는 변경되지 않아요. vae가 --layerwise-offload-components에 있어서는 안 되는 이유를 포함한 24 GB offload 레시피는 MiniMax-H3 cookbook 참고.

Large-M GEMM(rows > 8192 및 out_features >= 8192)은 융합 커널이 data-parallel CUTLASS 구성에 유지되도록 행으로 분할돼요. 임계값은 SGLANG_KITCHEN_INT8_MAX_ROWS와 SGLANG_KITCHEN_INT8_MIN_SPLIT_N으로 오버라이드해요.

레이어 건너뛰기 (Skipping Layers)

기본적으로 트랜스포머 온라인 양자화는 해당 컴포넌트의 모든 지원 linear 레이어를 양자화해요. 그러나 --quantization-ignored-layers는 특정 트랜스포머 레이어를 원래 정밀도로 유지할 수 있어요:

sglang generate \
  --model-path Tongyi-MAI/Z-Image-Turbo \
  --quantization fp8 \
  --quantization-ignored-layers attention.to_ \
  --prompt "a beautiful sunset" \
  --save-output

sglang generate \
  --model-path Tongyi-MAI/Z-Image-Turbo \
  --quantization mxfp4 \
  --quantization-ignored-layers attention.to_ \
  --prompt "a beautiful sunset" \
  --save-output

각 패턴은 전체 레이어 프리픽스(예: layers.0.attention.to_q)와 일치해요. 프리픽스에 주어진 패턴 중 하나라도 포함되면 레이어는 건너뛰고 비양자화로 남아요.

Transformers-관리 양자화 컴포넌트 (Transformers-managed Quantized Components)

이미 네이티브 Transformers 로딩 경로가 있는 모델 컴포넌트는 설치된 Transformers 버전이 인식하는 표준 최상위 quantization_config를 가진 자체 설명 체크포인트를 위임해요. 성공적인 로딩은 여전히 그 백엔드의 선택 의존성, 플랫폼, 모델/체크포인트 호환성에 달려 있어요. 사용 가능한 네이티브 SGLang 구현은 같은 형식을 복원할 수 있으면 여전히 선호돼요. 예를 들어 FLUX의 T5 컴포넌트를 공식 BitsAndBytes 체크포인트로 교체해요:

sglang serve \
  --model-path black-forest-labs/FLUX.1-dev \
  --component-paths.text_encoder_2 \
    diffusers/FLUX.1-dev-bnb-4bit/text_encoder_2

Transformers가 형식 검증을 소유하고 양자화 컴포넌트를 상주 디바이스에 직접 배치해요. SGLang은 체크포인트 계약을 조용히 바꾸는 대신 컴포넌트/layerwise offload, FSDP, 비표준 메타데이터 위치, 지원되지 않는 상류 형식, 네이티브 전용 폴백을 거부해요. Diffusers 라이브러리 아래 선언된 Diffusion DiT 컴포넌트는 위에 문서화된 별도의 양자화 백엔드를 사용해요.

검증된 ModelOpt 체크포인트 (Validated ModelOpt Checkpoints)

이 섹션은 SGLang 문서와 검증 범위에서 현재 연결된 열세 개의 게시된 diffusion ModelOpt 체크포인트의 정식 지원 매트릭스예요.

게시된 체크포인트는 직렬화 양자화 구성을 quant_method=modelopt로 유지해요. 아래 FP8 vs NVFP4 분할은 quant_algo에서 파생된 문서 라벨이에요.

열세 개의 repo 중 12개는 lmsys/* 아래 있어요. FLUX.2 NVFP4 항목은 공식 black-forest-labs/FLUX.2-dev-NVFP4 repo를 유지해요.

Quant Algo 기본 모델 선호 CLI HF Repo 현재 범위 참고
FP8 black-forest-labs/FLUX.1-dev --transformer-path lmsys/flux1-dev-modelopt-fp8-sglang-transformer 단일 트랜스포머 오버라이드, 결정적 latent/이미지 비교, H100 벤치마크, torch-profiler 트레이스 SGLang 변환기는 modulation 및 FF projection 레이어에 검증된 BF16 폴백 세트 유지. 로컬 미러에는 --model-id FLUX.1-dev 사용
FP8 black-forest-labs/FLUX.2-dev --transformer-path lmsys/flux2-dev-modelopt-fp8-sglang-transformer 단일 트랜스포머 오버라이드 로드 및 생성 경로 게시된 SGLang 준비 트랜스포머 오버라이드
FP8 Wan-AI/Wan2.2-T2V-A14B-Diffusers --transformer-path lmsys/wan22-t2v-a14b-modelopt-fp8-sglang-transformer 기본 transformer 양자화, transformer\_2 BF16 유지 기본 트랜스포머 전용 경로. transformer\_2는 기본 체크포인트에 유지하고, 별도 검증 없이는 듀얼 트랜스포머 전체 모델 FP8로 설명하지 말 것
FP8 hunyuanvideo-community/HunyuanVideo --transformer-path lmsys/hunyuanvideo-modelopt-fp8-sglang-transformer 단일 트랜스포머 오버라이드, BF16-vs-FP8 비디오 비교, H100 벤치마크, torch-profiler 트레이스 HunyuanVideo는 다른 ModelOpt/diffusers 및 SGLang 런타임 모듈 이름 사용. 변환기는 FP8 스케일 텐서와 BF16 폴백 ignores 작성 전에 그 이름을 매핑
FP8 Qwen/Qwen-Image --transformer-path lmsys/qwen-image-modelopt-fp8-sglang-transformer 단일 트랜스포머 오버라이드, BF16-vs-FP8 이미지 비교, H100 벤치마크, torch-profiler 트레이스 Qwen Image FP8 폴백 프리셋 공유. img\_in, txt\_in, timestep embedder, norm\_out.linear, proj\_out, img\_mod/txt\_mod, img\_mlp.net.2를 BF16으로 유지
FP8 Qwen/Qwen-Image-Edit-2511 --transformer-path lmsys/qwen-image-edit-modelopt-fp8-sglang-transformer TI2I 편집 경로, BF16-vs-FP8 이미지 비교, H100 벤치마크 Qwen Image와 QwenImageTransformer2DModel 공유, 같은 Qwen Image FP8 폴백 프리셋 사용
NVFP4 black-forest-labs/FLUX.1-dev --transformer-path lmsys/flux1-dev-modelopt-nvfp4-sglang-transformer 혼합 BF16+NVFP4 트랜스포머 오버라이드, 정확성 검증, 4x RTX 5090 벤치마크, torch-profiler 트레이스 build\_modelopt\_nvfp4\_transformer.py 사용. 검증된 빌더는 선택된 FLUX.1 모듈을 BF16으로 유지하고 swap\_weight\_nibbles=false 설정
NVFP4 black-forest-labs/FLUX.2-dev --transformer-weights-path black-forest-labs/FLUX.2-dev-NVFP4 packed-QKV 로드 경로 공식 원시 export repo. 검증된 packed export 감지 및 런타임 레이아웃 처리
NVFP4 Wan-AI/Wan2.2-T2V-A14B-Diffusers --transformer-path lmsys/wan22-t2v-a14b-modelopt-nvfp4-sglang-transformer ModelOpt NVFP4로 기본 transformer 양자화, transformer\_2 BF16 유지 기본 트랜스포머 전용 경로. transformer\_2는 기본 체크포인트에 유지. 기본 FP4 GEMM 백엔드는 flashinfer\_trtllm
NVFP4 Qwen/Qwen-Image --model-path lmsys/qwen-image-modelopt-nvfp4-sglang 전체 ModelOpt NVFP4 Diffusers repo, BF16-vs-NVFP4 B200 이미지 비교 전체 repo 직접 로드. ModelOpt PR #1706 SVDQuant NVFP4(--format fp4, 최대 캘리브레이션, 블록 크기 16) 및 어텐션 민감 모듈 + 첫/마지막 트랜스포머 블록의 BF16 폴백으로 export
NVFP4 Qwen/Qwen-Image-2512 --model-path lmsys/qwen-image-2512-modelopt-nvfp4-sglang 전체 ModelOpt NVFP4 Diffusers repo, BF16-vs-NVFP4 B200 이미지 비교, B200 CI 케이스 Qwen Image와 같은 전체 repo 로더 경로. multimodal-gen-test-1-b200의 Qwen Image NVFP4 대표
NVFP4 Qwen/Qwen-Image-Edit --model-path lmsys/qwen-image-edit-modelopt-nvfp4-sglang TI2I 편집 전체 ModelOpt NVFP4 Diffusers repo, BF16-vs-NVFP4 B200 이미지 비교 일반 image-edit 입력으로 전체 repo 직접 로드. 같은 ModelOpt PR #1706 NVFP4 레시피로 export
NVFP4 Qwen/Qwen-Image-Edit-2511 --model-path lmsys/qwen-image-edit-2511-modelopt-nvfp4-sglang TI2I 편집 전체 ModelOpt NVFP4 Diffusers repo, BF16-vs-NVFP4 B200 이미지 비교 일반 image-edit 입력으로 전체 repo 직접 로드. 같은 ModelOpt PR #1706 NVFP4 레시피로 export

이 열세 개 체크포인트는 의도된 ModelOpt 문서 지원 세트예요. B200 diffusion CI 작업(multimodal-gen-test-1-b200)은 대표적인 NVFP4 부분집합을 사용하고 Qwen Image 범위에 lmsys/qwen-image-2512-modelopt-nvfp4-sglang을 포함해요.

ModelOpt FP8

사용 예시 (Usage Examples)

변환된 ModelOpt FP8 트랜스포머 repo는 트랜스포머 컴포넌트 오버라이드로 로드해야 해요. repo나 로컬 디렉터리가 이미 config.json을 포함하면 --transformer-path를 사용해요. NVIDIA Wan2.2 FP8 체크포인트 같은 전체 Diffusers repo는 --model-path로 직접 전달할 수 있어요.

sglang generate \
  --model-path black-forest-labs/FLUX.2-dev \
  --transformer-path lmsys/flux2-dev-modelopt-fp8-sglang-transformer \
  --prompt "A Logo With Bold Large Text: SGL Diffusion" \
  --save-output

sglang generate \
  --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers \
  --transformer-path lmsys/wan22-t2v-a14b-modelopt-fp8-sglang-transformer \
  --prompt "a fox walking through neon rain" \
  --save-output

sglang generate \
  --model-path hunyuanvideo-community/HunyuanVideo \
  --transformer-path lmsys/hunyuanvideo-modelopt-fp8-sglang-transformer \
  --height 544 --width 960 --num-frames 17 \
  --prompt "A cinematic shot of a red sports car driving through rain at night" \
  --save-output

sglang generate \
  --model-path Qwen/Qwen-Image \
  --transformer-path lmsys/qwen-image-modelopt-fp8-sglang-transformer \
  --prompt "A tiny astronaut reading a book under a glass greenhouse" \
  --save-output

sglang generate \
  --model-path Qwen/Qwen-Image-Edit-2511 \
  --transformer-path lmsys/qwen-image-edit-modelopt-fp8-sglang-transformer \
  --image-path /path/to/input.png \
  --prompt "Turn the scene into a warm watercolor illustration" \
  --save-output

참고 (Notes)

  • --transformer-path는 이미 config.json을 운반하는 변환 ModelOpt FP8 컴포넌트 repo 또는 디렉터리의 기본-DiT 편의 철자예요.
  • 오버라이드 repo나 로컬 디렉터리에 자체 config.json이 있으면 SGLang은 기본 모델 구성에 의존하는 대신 그 오버라이드에서 양자화 구성을 읽어요.
  • 원시 가중치 파일이나 먼저 가중치로 메타데이터 프로브해야 하는 디렉터리를 의도적으로 가리킬 때 --transformer-weights-path도 여전히 작동해요.
  • dit_layerwise_offload는 ModelOpt FP8 체크포인트에서 지원돼요.
  • dit_cpu_offload는 ModelOpt FP8 체크포인트에서 여전히 비활성으로 유지돼요.
  • layerwise offload 경로는 이제 런타임 FP8 GEMM 경로가 기대하는 비연속 FP8 가중치 스트라이드를 보존해요.
  • 디스크에서 양자화 구성은 quant_method=modelopt + quant_algo=FP8로 유지. 이 문서의 modelopt-fp8 라벨은 직렬화 구성 키가 아닌 지원 패밀리 이름이에요.
  • ModelOpt diffusers export에서 변환 체크포인트를 직접 구축하려면 python -m sglang.multimodal_gen.tools.build_modelopt_fp8_transformer를 사용해요.

ModelOpt NVFP4

사용 예시 (Usage Examples)

이미 config.json을 포함하는 혼합 ModelOpt NVFP4 트랜스포머 오버라이드의 경우 기본 모델과 양자화 트랜스포머를 분리 유지하고 --transformer-path를 사용해요:

sglang generate \
  --model-path black-forest-labs/FLUX.1-dev \
  --transformer-path lmsys/flux1-dev-modelopt-nvfp4-sglang-transformer \
  --prompt "A Logo With Bold Large Text: SGL Diffusion" \
  --save-output

공식 FLUX.2 릴리스 같은 원시 NVFP4 export의 경우 --transformer-weights-path를 사용해요:

sglang generate \
  --model-path black-forest-labs/FLUX.2-dev \
  --transformer-weights-path black-forest-labs/FLUX.2-dev-NVFP4 \
  --prompt "A Logo With Bold Large Text: SGL Diffusion" \
  --save-output

SGLang은 NVFP4 repo나 로컬 디렉터리를 --model-path로 직접 전달하는 것도 지원해요:

sglang generate \
  --model-path black-forest-labs/FLUX.2-dev-NVFP4 \
  --prompt "A Logo With Bold Large Text: SGL Diffusion" \
  --save-output

기본 transformer만 양자화된 듀얼 트랜스포머 Wan2.2 export의 경우:

sglang generate \
  --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers \
  --transformer-path lmsys/wan22-t2v-a14b-modelopt-nvfp4-sglang-transformer \
  --prompt "a fox walking through neon rain" \
  --save-output

전체 Qwen Image NVFP4 export의 경우 게시된 repo를 직접 로드해요:

sglang generate \
  --model-path lmsys/qwen-image-2512-modelopt-nvfp4-sglang \
  --prompt "A tiny astronaut reading a book under a glass greenhouse" \
  --save-output

B200에서 고해상도 Qwen-Image-family 생성의 경우 FlashInfer CUTLASS FP4 GEMM 백엔드가 기본 TensorRT-LLM 백엔드보다 빠를 수 있어요:

SGLANG_DIFFUSION_FLASHINFER_FP4_GEMM_BACKEND=cutlass \
sglang generate \
  --model-path lmsys/qwen-image-2512-modelopt-nvfp4-sglang \
  --width 2048 --height 2048 \
  --prompt "A tiny astronaut reading a book under a glass greenhouse" \
  --save-output

Qwen-Image 2.1은 --component-paths.transformer와 --component-paths.text_encoder를 통해 독립 NVFP4 DiT 및 네이티브 언어 인코더 컴포넌트 디렉터리도 지원해요. 비공개 최대 캘리브레이션 export는 B200 생성, 편집, 투명 RGBA, offload, TP2 검사를 통과했어요. 이 검사는 임의 export나 RTX 5090을 다루지 않아요. 컴포넌트 로딩 지침과 하드웨어 요구사항은 그 cookbook 참고.

참고 (Notes)

  • 이미 config.json을 포함하는 혼합 ModelOpt NVFP4 트랜스포머 repo나 로컬 디렉터리에는 --transformer-path를 사용해요.
  • 원시 NVFP4 export, 개별 safetensors 파일, 먼저 가중치로 취급해야 하는 repo 레이아웃에는 --transformer-weights-path를 사용해요.
  • Wan2.2-T2V-A14B-Diffusers 같은 듀얼 트랜스포머 파이프라인에서 기본 --transformer-path 오버라이드는 transformer만 대상으로 해요. 의도적으로 비기본 transformer_2를 원할 때만 --transformer-2-path 같은 컴포넌트별 오버라이드를 사용해요.
  • B200에서 diffusion ModelOpt NVFP4 경로는 기본적으로 FlashInfer TensorRT-LLM FP4 GEMM(flashinfer_trtllm)을 사용해요. SM120(RTX 5090 포함)에서 기본값은 auto예요. TensorRT-LLM FP4 GEMM은 그 아키텍처를 지원하지 않아요.
  • 게시된 Qwen Image NVFP4 export는 img_mod/txt_mod modulation projection과 첫/마지막 트랜스포머 블록을 BF16으로 유지해요.
  • Qwen-Image NVFP4는 1024x1024에서 항상 지연 시간을 개선하지 않아요. B200에서 검증된 ModelOpt export는 SGLANG_DIFFUSION_FLASHINFER_FP4_GEMM_BACKEND=cutlass로 2048x2048에서 BF16보다 빨랐지만 1024x1024는 BF16이 더 빨랐어요.
  • 직접 --model-path 로딩은 전체 Qwen Image ModelOpt NVFP4 repo의 정식 경로이고 FLUX.2 NVFP4 스타일 repo나 로컬 디렉터리의 호환 경로예요.
  • --transformer-weights-path가 명시적으로 제공되면 호환 --model-path 흐름보다 우선해요.
  • 로컬 디렉터리의 경우 SGLang은 먼저 *-mixed.safetensors를 찾고 그 다음 디렉터리에서 로딩으로 폴백해요.
  • diffusion ModelOpt FP4 경로를 다른 FlashInfer 백엔드로 강제하려면 SGLANG_DIFFUSION_FLASHINFER_FP4_GEMM_BACKEND를 설정해요. 지원 값은 flashinfer_cudnn, flashinfer_cutlass, flashinfer_trtllm 포함.
  • 디스크에서 양자화 구성은 quant_method=modelopt + quant_algo=NVFP4로 유지. 여기 modelopt-nvfp4 라벨은 다시 직렬화 구성 키가 아닌 문서 패밀리 이름이에요.

GGUF

GGUF는 단일 .gguf 파일에서 커뮤니티 양자화 트랜스포머를 로드하고 나머지 파이프라인 — VAE, 텍스트 인코더, 스케줄러, 토크나이저 — 은 기본 모델에서 계속 로드해요.

GGUF는 주로 체크포인트, 호스트 메모리, 상주 가중치 크기를 줄여요. 예를 들어 MiniMax-H3 트랜스포머는 Q4_K_M으로 17.5 GiB인 반면 BF16은 61.7 GiB예요. 전체 layerwise offload에서 VAE 디코드와 offload 버퍼가 여전히 피크 GPU 메모리를 지배할 수 있지만, 각 스트리밍 DiT 레이어도 더 적은 바이트를 전송해요.

패킹된 linear는 SRT의 GGUF 유형 정의와 CUDA 역양자화를 재사용한 다음 네이티브 GEMM을 실행해요. SRT의 융합 MMVQ/MMQ 커널은 저토큰 LLM 영역을 대상으로 하고 확산 시퀀스 길이에서는 더 느려요. GGUF는 용량 지향 옵션으로 유지돼요. 지연 시간은 양자화 유형, 활성화 형태, 배치 정책에 따라 달라져요.

체크포인트가 비양자화로 저장하는 레이어(F32/F16/BF16)는 패킹 경로 대신 일반 linear 경로를 취해요. 그들의 정밀도는 모델이 그 레이어에 선언하는 것과 같아요. safetensors 경로와 정확히 동일하게 — 체크포인트는 더 넓게 저장해 모델 자체 dtype 위로 레이어를 올릴 수 없어요. MiniMax-H3의 경우 둘이 일치해요. FP32로 고정하는 레이어가 검증된 체크포인트가 비양자화로 남기는 레이어이고, post_load_weights는 그 중 하나라도 더 좁아지면 로드를 실패시켜요.

사용 (Usage)

추가 설치 불필요: gguf는 이미 SGLang 핵심 의존성이에요.

--model-path는 기본 모델로 유지되고, --component-weights-paths.<component>가 GGUF를 취해요. 로컬 경로, owner/repo/file.gguf, 또는 owner/repo:QUANT_TYPE 모두 작동해요. quant-type 축약은 정확히 하나의 repo 파일이 그것과 일치할 때만 수용되고, 그 외 SGLang은 후보를 나열하고 전체 경로를 요청해요.

sglang serve \
  --model-path MiniMaxAI/MiniMax-H3 \
  --model-variant fl2va \
  --component-weights-paths.transformer \
    leejet/MiniMax-H3-GGUF/minimax_h3_fl2va-Q4_K_M.gguf \
  --num-gpus 1 \
  --attention-backend fa \
  --performance-mode memory \
  --layerwise-offload-components dit,text_encoder \
  --dit-offload-prefetch-size 1 \
  --dit-layerwise-resident-layers 0 \
  --enable-torch-compile false \
  --port 30010

여기 transformer는 H3의 등록 DiT 컴포넌트 이름이에요. --transformer-weights-path 별칭이 같은 결과를 내요. --quantization gguf는 셀렉터가 아니라는 점에 주의하세요. 양자화는 파일 자체에서 읽으므로, 파일을 전달하는 것이 경로를 활성화하는 것이에요.

MiniMax-H3 GGUF 체크포인트는 원본 timestep MLP 또는 pruned AdaLN curve 아키텍처를 사용할 수 있어요. 저장소는 종종 FL2VA와 Ref2VA 파일을 모두 포함하므로 모호한 owner/repo:QUANT_TYPE 셀렉터 대신 전체 Hub 파일 참조를 사용해요. H3 compatibility table은 여기서 명령을 중복하지 않고 두 게시 레이아웃을 연결해요.

pruned 아키텍처는 샘플링된 curve와 축소된 AdaLN projection을 FP32로 유지해 게시된 체크포인트 구현과 일치해요. 이 정밀도 섬은 의도적으로 BF16 전용 융합 modulation 커널을 우회해요.

VAE offload 여부 (Whether to offload the VAE)

vae를 --layerwise-offload-components에 추가하는 것은 일부 피크 VRAM을 위해 많은 지연 시간을 교환해요. 비디오 VAE 디코더가 디코드 타일마다 다시 스트리밍되기 때문이에요. 이 체크포인트로 1× RTX 5090에서 측정, 1344×768 × 107 프레임:

--layerwise-offload-components 피크 VRAM Denoise VAE decode
dit,text_encoder 26.3 GiB 39.0 s 9.5 s
dit,text_encoder,vae 19.6 GiB 39.0 s 57.2 s

Denoise는 영향받지 않고 출력은 어느 쪽이든 비트 동일해요. 6.7 GiB가 중요하지 않으면 VAE를 상주로 남겨두세요. 이 측정에 따르면 24 GB 카드에서는 중요하고, 6× 느린 디코드는 맞는 대가예요.

제약 (Constraints)

제약 이유
TP 샤드 경계가 GGML 블록에 정렬되어야 함 Column-parallel 행이 직접 샤드. Row-parallel 패킹 열은 각 로컬 입력 파티션이 전체 양자화 블록을 포함해야 함
--use-fsdp-inference 없음 FSDP는 GGUF 패킹 블록 레이아웃을 보존하지 않음
CUDA 전용 재사용된 SRT GGML 역양자화 커널이 현재 CUDA용으로 제공
네이티브 바이트 순서만 양자화 블록이 스케일을 임베드하므로 비네이티브 파일은 전체로 바이트 스왑할 수 없음
LoRA 없음, H3 AdaLN 캐시 플래그 없음 어댑터는 패킹 블록에 병합할 수 없고, AdaLN 경로는 트랜스포머 safetensors를 읽음
--quantization 없음 체크포인트가 양자화를 고정. 플래그는 두 번째 충돌 셀렉터가 될 것

위의 모든 제약은 조용히 잘못된 출력을 내는 대신 설명 오류와 함께 시작 시 실패해요.

시퀀스 병렬 처리(--ulysses-degree / --ring-degree)는 패킹 가중치가 아닌 활성화를 샤딩하므로 계속 사용할 수 있어요. TP도 사용 가능하고, 시작 시 GGML 블록 안에서 row-parallel 행렬을 자르는 정도를 거부해요.

검증된 범위 (Validated scope)

모델 체크포인트 하드웨어 결과
MiniMax-H3 fl2va leejet/MiniMax-H3-GGUF minimax_h3_fl2va-Q4_K_M.gguf (17.5 GiB) 1x RTX 5090 (32 GiB) t2va 1344x768, 107 프레임, 비디오 + 오디오; VAE offload에 따라 19.6-26.3 GiB 피크
MiniMax-H3 fl2va minimax_h3_fl2va-Q4_K_M.gguf (17.5 GiB) 1x H200 (141 GiB) 2-step t2va 1344x768, 107 프레임, H.264 + AAC; 10.13 s 및 17.17 GiB 피크
MiniMax-H3 fl2va, pruned AdaLN curve unsloth/MiniMax-H3-GGUF minimax_h3_fl2va_pruned-Q4_K.gguf (로드 DiT 10.7 GiB) 1x H200 (141 GiB) 2-step t2va 1344x768, 107 프레임, H.264 + AAC
MiniMax-H3 fl2va, pruned AdaLN curve minimax_h3_fl2va_pruned-Q4_K.gguf 1x GB300 (CUDA 13, PyTorch 2.13) 50-step t2va 1344x768, 107 프레임, H.264 + AAC; 105.38 s 및 80.88 GB 피크
MiniMax-H3 fl2va, pruned AdaLN curve minimax_h3_fl2va_pruned-Q4_K.gguf 2x GB300, TP2 (CUDA 13, PyTorch 2.13) 2-step t2va 1344x768, 107 프레임, H.264 + AAC; rank당 7.55 s 및 51.90 GB 피크
Qwen-Image 2.1 비공개 네이티브 이름 Q4_0 export; DiT 3.91 GiB, 인코더 7.03 GiB 1x B200; 별도 TP2 체크 1024px/40-step 생성, 편집, 투명 RGBA; 각 컴포넌트와 둘 다; 결합 offload가 상주 픽셀과 일치

unpruned MiniMax-H3 DiT는 BF16 체크포인트의 61.7 GiB 대비 17.5 GiB로 로드돼요. 가중치 충실도는 BF16 참조에 대해 텐서별로 확인됐어요. F32/BF16 텐서는 cosine 1.00000, Q4_K/Q4_0은 0.9973.

MiniMax-H3 측정은 다른 양자화 유형, ref2va 파티션, BF16-vs-GGUF 출력 비교를 검증하지 않아요.

Qwen-Image 2.1의 Q4_0 export는 기본 컴포넌트 구성과 네이티브 텐서 이름을 사용해요. 그 cookbook이 호환 컴포넌트 파일을 로드하고 정밀도 설정을 선택하는 방법을 설명해요. 이 비공개 export는 로딩 및 실행 호환성을 확립하며 일반 출력 품질이나 다른 GGUF export와의 호환성은 아니에요.

Nunchaku (SVDQuant)

설치 (Install)

먼저 런타임 의존성을 설치해요:

pip install nunchaku

플랫폼별 설치 방법과 문제 해결은 Nunchaku installation guide 참고.

파일 명명 및 자동 감지 (File Naming and Auto-Detection)

Nunchaku 체크포인트의 경우 --model-path는 여전히 원래 기본 모델을 가리키고, --transformer-weights-path는 양자화 트랜스포머 가중치를 가리켜요.

--transformer-weights-path의 기본 이름이 svdq-(int4|fp4)_r{rank} 패턴을 포함하면 SGLang은 자동으로:

  • SVDQuant 활성화
  • --quantization-precision 추론
  • --quantization-rank 추론

예시:

체크포인트 이름 조각 추론 정밀도 추론 rank 참고
svdq-int4\_r32 int4 32 표준 INT4 체크포인트
svdq-int4\_r128 int4 128 고품질 INT4 체크포인트
svdq-fp4\_r32 nvfp4 32 파일명의 fp4는 CLI 값 nvfp4로 매핑
svdq-fp4\_r128 nvfp4 128 고품질 NVFP4 체크포인트

일반 파일명:

파일명 정밀도 rank 일반 사용
svdq-int4\_r32-qwen-image.safetensors int4 32 균형 기본값
svdq-int4\_r128-qwen-image.safetensors int4 128 품질 중심
svdq-fp4\_r32-qwen-image.safetensors nvfp4 32 RTX 50 시리즈 / NVFP4 경로
svdq-fp4\_r128-qwen-image.safetensors nvfp4 128 품질 중심 NVFP4
svdq-int4\_r32-qwen-image-lightningv1.0-4steps.safetensors int4 32 Lightning 4-step
svdq-int4\_r128-qwen-image-lightningv1.1-8steps.safetensors int4 128 Lightning 8-step

체크포인트 이름이 이 관례를 따르지 않으면 --enable-svdquant, --quantization-precision, --quantization-rank를 명시적으로 전달해요.

사용 예시 (Usage Examples)

권장 자동 감지 흐름:

sglang generate \
  --model-path Qwen/Qwen-Image \
  --transformer-weights-path /path/to/svdq-int4_r32-qwen-image.safetensors \
  --prompt "a beautiful sunset" \
  --save-output

파일명이 양자화 설정을 인코딩하지 않을 때 수동 오버라이드:

sglang generate \
  --model-path Qwen/Qwen-Image \
  --transformer-weights-path /path/to/custom_nunchaku_checkpoint.safetensors \
  --enable-svdquant \
  --quantization-precision int4 \
  --quantization-rank 128 \
  --prompt "a beautiful sunset" \
  --save-output

참고 (Notes)

  • --transformer-weights-path는 Nunchaku 예시가 사용하는 기본-DiT 편의 철자예요. quantized_model_path 같은 이전 구성 이름은 호환 별칭으로 취급돼요.
  • 자동 감지는 체크포인트 기본 이름이 svdq-(int4|fp4)_r{rank}와 일치할 때만 발생해요.
  • CLI 값은 int4와 nvfp4예요. 파일명에서 NVFP4 변형은 fp4로 작성돼요.
  • Lightning 체크포인트는 보통 일치 --num-inference-steps(예: 4 또는 8)를 기대해요.
  • 현재 런타임 검증은 NVIDIA CUDA Ampere (SM8x) 또는 SM12x GPU에서만 Nunchaku를 허용해요. Hopper (SM90)는 현재 거부돼요.

ModelSlim

MindStudio-ModelSlim (msModelSlim)은 MindStudio가 출시하고 Ascend 하드웨어에 최적화된 모델 오프라인 양자화 압축 도구예요.

  • 설치 (Installation)

    # Clone repo and install msmodelslim:
git clone https://gitcode.com/Ascend/msmodelslim.git
cd msmodelslim
bash install.sh

  • Multimodal_sd 양자화 큰 모델의 원본 부동소수점 가중치를 내려받아요. Wan2.2-T2V-A14B를 예로 들면, Wan2.2-T2V-A14B에서 원본 모델 가중치를 얻을 수 있어요. 그런 다음 다른 의존성을 설치해요 (모델 관련, modelscope 모델 카드 참고).

    Note: 사전 양자화 검증 모델은 modelscope/Eco-Tech에서 찾을 수 있어요.

    원클릭 양자화(권장)로 양자화를 실행해요:

    msmodelslim quant \
  --model_path /path/to/wan2_2_float_weights \
  --save_path /path/to/wan2_2_quantized_weights \
  --device npu \
  --model_type Wan2_2 \
  --quant_type w8a8 \
  --trust_remote_code True

    모델 양자화의 더 자세한 예시와 지원 정보는 ModelSLim repo의 examples 섹션 참고.

    Note: SGLang은 양자화 embedding을 지원하지 않으므로 msmodelslim으로 양자화할 때 이 옵션을 비활성화해요.

  • 자동 감지 및 다양한 형식 (Auto-Detection and different formats) msmodelslim 체크포인트의 경우 --model-path만 지정하면 충분해요. 양자화 감지는 quant_model_description.json 구성 파싱으로 레이어마다 자동 발생해요.

    Wan2.2의 경우 Diffusers 가중치 저장소 형식만 지원되는 반면, modelslim은 양자화 모델을 원본 Wan2.2 형식으로 저장해요. 변환에는 원스텝 wan_repack.py 스크립트를 사용해요:

    python wan_repack.py \
  --model-type Wan2.2-TI2V-5B \
  --original-model-path {path_to_original_diffusers_model} \
  --quant-path {path_to_quantized_model} \
  --output-path {path_to_converted_model}

    지원 --model-type 값: Wan2.2-TI2V-5B (단일 트랜스포머), Wan2.2-T2V-A14B 및 Wan2.2-I2V-A14B (Cascade 듀얼 트랜스포머). 스크립트가 자동으로 처리해요: 기본 모델 복사, 양자화 가중치를 Diffusers 형식으로 변환, config.json 복원.

  • 사용 예시 (Usage Example) 자동 감지 흐름:

    sglang generate \
  --model-path Eco-Tech/Wan2.2-T2V-A14B-Diffusers-w8a8 \
  --prompt "a beautiful sunset" \
  --save-output

  • 사용 가능한 양자화 방법 (Available Quantization Methods):

    • W4A4_DYNAMIC 활성화의 온라인 양자화가 있는 linear
    • W8A8 활성화의 오프라인 양자화가 있는 linear
    • W8A8_DYNAMIC 활성화의 온라인 양자화가 있는 linear
    • W8A8_MXFP8 오프라인 양자화가 있는 linear (msmodelslim 사전 양자화 가중치)
    • mxfp8 온라인 양자화가 있는 linear (--quantization mxfp8)
    • W4A4_MXFP4 / W4A4_MXFP4_DUALSCALE 오프라인 양자화가 있는 linear (msmodelslim 사전 양자화 가중치)
    • mxfp4_npu 온라인 양자화가 있는 linear (--quantization mxfp4_npu)

MXFP8 양자화

자체 설명 직렬화 MXFP8 트랜스포머는 체크포인트 메타데이터에서 추론돼요. 온라인 MXFP8 양자화의 경우 원래 FP16/BF16 모델을 로드하고 --quantization mxfp8을 추가해요. NVIDIA와 ROCm은 SRT의 dense MXFP8 구현을 재사용하고, Ascend는 블록 크기 32로 npu_dynamic_mx_quant과 npu_quant_matmul을 사용해요.

sglang generate \
  --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers \
  --quantization mxfp8 \
  --prompt "a fox walking through neon rain" \
  --save-output

선택된 SRT 백엔드는 NVIDIA 또는 ROCm에서 MXFP8 커널을 제공해야 해요. Ascend에서 하드웨어 요구사항은 여전히 950PR/DT Series 이상이고, npu_dynamic_mx_quant는 A2/A3 Series에서 사용할 수 없어요.

MXFP8 오프라인 양자화 (msmodelslim)

msmodelslim이 export한 사전 양자화 MXFP8 가중치는 quant_model_description.json(W8A8_MXFP8 스킴)을 통해 자동 감지돼요. wan_repack.py로 양자화 가중치를 Diffusers 형식으로 변환한 다음 --model-path로 변환 모델을 로드해요:

sglang generate \
  --model-path Eco-Tech/Wan2.2-T2V-A14B-Diffusers-mxfp8 \
  --prompt "a beautiful sunset" \
  --save-output

MXFP4 온라인 양자화

Ascend NPU에서 온라인 MXFP4 양자화를 위해 원래 FP16/BF16 모델을 로드하고 --quantization mxfp4_npu를 추가해요. mxfp4는 ROCm/aiter 백엔드용으로 예약되어 있으므로 mxfp4_npu 키는 Ascend용으로 사용돼요.

가중치는 npu_dynamic_dual_level_mx_quant로 로드 시 양자화되고, 활성화는 npu_dual_level_quant_matmul 전에 추론 중 토큰별로 양자화돼요. MXFP4는 L1 블록 크기 32와 L0 블록 크기 512의 이중 수준 블록 스케일을 사용해요.

sglang generate \
  --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers \
  --quantization mxfp4_npu \
  --prompt "a fox walking through neon rain" \
  --save-output

하드웨어 요구사항: Ascend 950PR/DT Series 이상. npu_dynamic_dual_level_mx_quant와 npu_dual_level_quant_matmul은 A2/A3 Series에서 사용할 수 없어요.

참고: 온라인 MXFP4 가중치 양자화는 실험적이에요. 오프라인 msmodelslim 흐름은 사전 양자화 가중치를 사용하고 다른 수치 결과를 만들 수 있어요.

MXFP4 오프라인 양자화 (msmodelslim)

msmodelslim이 export한 사전 양자화 MXFP4 가중치는 quant_model_description.json(W4A4_MXFP4 / W4A4_MXFP4_DUALSCALE 스킴)을 통해 자동 감지돼요. wan_repack.py로 양자화 가중치를 Diffusers 형식으로 변환한 다음 --model-path로 변환 모델을 로드해요:

sglang generate \
  --model-path {path_to_converted_mxfp4_model} \
  --prompt "a beautiful sunset" \
  --save-output

오프라인 MXFP4 체크포인트는 FP8 컨테이너에 가중치를 저장하고 이중 수준 스케일(weight_scale, weight_dual_scale)을 포함해요. smooth quantization으로 export하면 mul_scale이 로드되어 활성화 양자화 전에 적용되고 활성화를 캘리브레이션된 가중치와 정렬해요.

더 알아보기