양자화

양자화 (Quantization)

LLM을 서빙할 때 메모리는 늘 첫 번째 병목이에요. SGLang은 이 문제를 풀기 위해 다양한 양자화 기법을 지원하는데, 크게 오프라인 양자화와 온라인(동적) 양자화 두 갈래로 나뉘어요.

오프라인 vs 온라인 양자화

오프라인 양자화는 이미 양자화가 끝난 모델 가중치를 추론 때 그대로 로드하는 방식이에요. GPTQ나 AWQ처럼 교정(calibration) 데이터셋을 이용해 원본 가중치의 통계를 미리 수집하고 계산해야 하는 기법은 반드시 이 방식이 필요해요.

반면 온라인 양자화는 실행 중에 스케일링 파라미터(가중치의 최대·최소값 같은 것)를 동적으로 계산해요. NVIDIA FP8 학습의 지연 스케일링(delayed scaling) 메커니즘처럼, 고정밀 가중치를 저정밀 포맷으로 바꿀 적절한 스케일 팩터를 그때그때 계산하는 방식이죠.

성능·사용성·편의성 관점에서 온라인 양자화보다 오프라인 양자화를 권장해요.

이미 양자화된 모델을 쓴다면 동시에 --quantization으로 온라인 양자화를 켜지 마세요. 널리 쓰이는 사전 양자화 모델은 Unsloth, NVIDIA ModelOpt, NeuralMagic 컬렉션에서 찾을 수 있어요. 단, 양자화된 모델은 비정상적인 손실 회귀(regression)를 막기 위해 반드시 양자화 후 벤치마크로 검증해야 해요.

플랫폼 호환성

아래 표는 NVIDIA/AMD GPU와 Ascend NPU에서 지원하는 양자화 기법을 정리한 거예요.

기법	NVIDIA GPU	AMD GPU (MI300X/MI325X/MI350X)	Ascend NPU (A2/A3/A5)	비고
`fp8`	예	예	WIP	AMD에선 Aiter 또는 Triton 백엔드
`mxfp4`	예	예	예 (A5)	GPU에선 MXFP 지원 CDNA3/CDNA4 필요(Aiter 사용). Ascend NPU(A5)에선 Qwen3 dense·MoE LLM용 W4A4 MXFP4(가중치+활성화). dense 모델은 온라인 이중 레벨 MXFP4 지원, 오프라인 `W4A4_MXFP4` dense·MoE 체크포인트(단일 레벨)는 `modelslim`으로 자동 감지. Intel GPU(XPU)에선 Xe2/BMG에서 `sgl-kernel-xpu`로 W4A16 MoE expert 지원, `--device xpu`면 자동 활성화(Intel GPU(XPU) 참조)
`mxfp8`	아니요	아니요	예 (A5, Diffusion·LLM Dense Linear·LLM MoE용)	Ascend NPU 전용. A5 시리즈에서 Diffusion(예: Wan2.2), LLM Dense Linear, LLM MoE(예: Qwen3-30B-A3B, FusedMoE)용 온라인+오프라인 MXFP8. CANN `npu_dynamic_mx_quant`/`npu_quant_matmul`(dense), `npu_grouped_matmul_swiglu_quant_v2`/`npu_grouped_matmul`(MoE) 커널 사용
`mxfp_w4a8`	아니요	아니요	예 (A5)	Ascend NPU 전용. A5 시리즈에서 Qwen3 dense LLM용 온라인 W4A8(MXFP4 가중치 + MXFP8 활성화). 오프라인 `W4A8_MXFP` dense·MoE 체크포인트는 `modelslim`으로 자동 감지
`blockwise_int8`	예	예	아니요	Triton 기반, 두 플랫폼 모두 동작
`w8a8_int8`	예	예	아니요
`w8a8_fp8`	예	예	아니요	AMD에선 Aiter 또는 Triton FP8
`awq`	예	예	예	NVIDIA에선 JIT 컴파일 CUDA 커널, AMD에선 Triton dequantize, Ascend에선 CANN 커널
`gptq`	아니요	아니요	예	NVIDIA·AMD GPU에선 제거됨 — `gptq_marlin` 사용. Ascend에선 CANN 커널. Intel AMX CPU에선 여전히 지원
`compressed-tensors`	예	예	일부	AMD FP8/MoE용 Aiter 경로. Ascend에선 CANN 커널, `FP8`은 아직 미지원
`quark`	예	예	아니요	AMD Quark 양자화; AMD에서 Aiter GEMM 경로
`auto-round`	예	예	일부	플랫폼 무관(Intel auto-round). Ascend에선 CANN 커널
`quark_int4fp8_moe`	아니요	예	아니요	AMD 전용; 온라인 INT4→FP8 MoE 양자화(CDNA3/CDNA4)
`awq_marlin`	예	아니요	아니요	Marlin 커널은 CUDA 전용
`gptq_marlin`	예	아니요	아니요	Marlin 커널은 CUDA 전용
`gguf`	예	아니요	예	sgl-kernel의 CUDA 커널; Ascend는 로드 시점에 CPU 사전-역양자화
`modelopt` / `modelopt_fp8`	예 (Hopper/SM90+)	아니요	아니요	NVIDIA ModelOpt; NVIDIA 하드웨어 필요
`modelopt_fp4`	예 (SM80-SM90은 Marlin, SM100+는 네이티브 FP4)	아니요	아니요	NVIDIA ModelOpt; Ampere/Hopper는 Marlin W4A16 폴백, Blackwell은 네이티브 FP4 백엔드. 로드 시 BF16/FP16/FP8 MoE 변환 + per-tensor FP32 활성화 스케일 지원
`nvfp4_online`	예 (Blackwell/SM100 또는 SM103)	아니요	아니요	BF16/FP16/FP8 체크포인트의 온라인 MoE 전용 NVFP4 가중치 양자화 + per-token FP32 활성화 스케일. per-tensor FP32 활성화 스케일은 `modelopt_fp4` 사용. `flashinfer_trtllm` 또는 `flashinfer_trtllm_routed` 필요
`petit_nvfp4`	아니요	예 (MI250/MI300X/MI325X)	아니요	Petit로 ROCm에서 NVFP4 활성화. NVIDIA Blackwell에선 `modelopt_fp4` 사용. AMD에서 NVFP4 모델 로드 시 자동 선택. LMSYS 블로그와 AMD ROCm 블로그 참조
`bitsandbytes`	예	실험적	아니요	bitsandbytes ROCm 지원에 따라
`modelslim`	아니요	아니요	예	Ascend 양자화; CANN 커널 사용

AMD에서 일부 기법은 Aiter로 가속하는데, 표에 표시된 곳에 SGLANG_USE_AITER=1을 설정하면 돼요. 설치·설정은 AMD GPU 설정을 참고하세요. Ascend는 다양한 레이어별 양자화 설정을 지원하는데, 자세한 내용은 Ascend NPU 양자화 문서를 보세요.

FP4/FP8 양자화용 GEMM 백엔드

백엔드 선택은 blockwise FP8, MXFP8(dense linear), NVFP4 GEMM에 적용돼요. 오프라인·온라인 FP8 또는 FP4 양자화 모델을 돌릴 때 --fp8-gemm-backend와 --fp4-gemm-backend로 GEMM 백엔드를 고를 수 있어요.

`--fp8-gemm-backend` (Blockwise FP8 GEMM)

백엔드	하드웨어	설명
`auto`	전체	하드웨어에 따라 자동 선택
`deep_gemm`	SM90, SM100	JIT 컴파일; DeepGEMM 설치 시 활성화
`flashinfer_trtllm`	SM100	FlashInfer TensorRT-LLM 백엔드; 저지연에 최적
`flashinfer_cutlass`	SM100/120	FlashInfer CUTLASS groupwise FP8 GEMM
`flashinfer_deepgemm`	SM90	디코딩 시 작은 M 차원에 swapAB 최적화 사용
`cutlass`	SM120	sgl-kernel CUTLASS
`triton`	전체	폴백; 호환성 높음
`aiter`	ROCm	AMD AITER 백엔드

auto 선택 순서: 1) DeepGEMM (SM90/SM100, 설치됨) → 2) FlashInfer TRTLLM (SM100, FlashInfer 가능) → 3) CUTLASS (SM120) → 4) AITER (AMD) → 5) Triton (폴백).

MXFP8 dense linear: auto는 SM100에서 flashinfer_cutlass 사용(그 외엔 triton). flashinfer_cutlass는 대부분의 형태에서 가장 빠르고, flashinfer_trtllm은 작은 M에서만 더 빨라요.

`--fp4-gemm-backend` (NVFP4 GEMM)

백엔드	하드웨어	설명
`auto`	SM80+	자동 선택: SM100은 `flashinfer_cutedsl`, SM80-SM90은 `marlin`, 그 외(SM120 포함)는 `flashinfer_cutlass`
`flashinfer_cutlass`	SM100/120	FlashInfer CUTLASS 백엔드
`flashinfer_cudnn`	SM100/120 (CUDA 13+, cuDNN 9.15+)	FlashInfer cuDNN 백엔드
`flashinfer_cutedsl`	SM100	FlashInfer CuTe DSL 백엔드
`flashinfer_trtllm`	SM100	FlashInfer TensorRT-LLM 백엔드
`marlin`	SM80-SM90	NVFP4 체크포인트용 weight-only W4A16 폴백

SM80-SM90에서 auto는 NVFP4에 Marlin을 선택해요. NVFP4 GEMM은 FlashInfer 설치가 필요해요.

오프라인 양자화

이미 양자화된 모델을 쓰려면 그냥 모델 가중치와 설정을 로드하면 돼요. 다시 강조하지만, 모델이 이미 오프라인 양자화돼 있다면 엔진을 시작할 때 --quantization 인자를 추가할 필요가 없어요. 양자화 기법은 다운로드한 Hugging Face 또는 msModelSlim 설정에서 자동으로 파싱돼요. 예를 들어 DeepSeek V3/R1은 이미 FP8이라 중복 파라미터를 넣으면 안 돼요.

python3 -m sglang.launch_server \
    --model-path hugging-quants/Meta-Llama-3.1-8B-Instruct-AWQ-INT4 \
    --port 30000 --host 0.0.0.0

만약 모델이 per-token 동적 양자화 활성화를 쓰는 per-channel 양자화(INT8 또는 FP8) 라면, --quantization w8a8_int8 또는 --quantization w8a8_fp8을 포함해 sgl-kernel의 해당 CUTLASS int8_kernel/fp8_kernel을 호출할 수 있어요. 이 옵션은 Hugging Face 설정의 양자화 설정을 무시해요. 예를 들어 neuralmagic/Meta-Llama-3.1-8B-Instruct-FP8-dynamic을 --quantization w8a8_fp8로 실행하면, SGLang의 W8A8Fp8Config로 sgl-kernel을 호출하지 vLLM 커널용 CompressedTensorsConfig를 쓰지 않아요.

python3 -m sglang.launch_server \
    --model-path neuralmagic/Meta-Llama-3.1-8B-Instruct-FP8-dynamic \
    --quantization w8a8_fp8 \
    --port 30000 --host 0.0.0.0

오프라인 모델 양자화 예시

Unsloth 사용

모델 양자화와 로드는 Unsloth를 강력히 권장해요. Unsloth와 함께하는 SGLang 배포·추론 가이드를 참고하세요.

auto-round 사용

# 설치
pip install auto-round

LLM 양자화

# for LLM
from auto_round import AutoRound
model_id = "meta-llama/Llama-3.2-1B-Instruct"
quant_path = "Llama-3.2-1B-Instruct-autoround-4bit"
# Scheme 예: "W2A16", "W3A16", "W4A16", "W8A16", "NVFP4", "MXFP4" (실제 커널 없음), "GGUF:Q4_K_M" 등
scheme = "W4A16"
format = "auto_round"
autoround = AutoRound(model_id, scheme=scheme)
autoround.quantize_and_save(quant_path, format=format) # 양자화 후 저장

VLM 양자화

# VLMs용
from auto_round import AutoRoundMLLM
model_name = "Qwen/Qwen2-VL-2B-Instruct"
quant_path = "Qwen2-VL-2B-Instruct-autoround-4bit"
scheme = "W4A16"
format = "auto_round"
autoround = AutoRoundMLLM(model_name, scheme)
autoround.quantize_and_save(quant_path, format=format) # 양자화 후 저장

커맨드라인 사용 (Gaudi/CPU/Intel GPU/CUDA)

auto-round \
    --model meta-llama/Llama-3.2-1B-Instruct \
    --bits 4 \
    --group_size 128 \
    --format "auto_round" \
    --output_dir ./tmp_autoround

SGLang API 사용 (CPU/CUDA)

from sglang.srt.configs.load_config import LoadConfig
from sglang.srt.configs.model_config import ModelConfig
from sglang.srt.model_loader.loader import get_model_loader
from sglang.srt.configs.device_config import DeviceConfig

# inc 양자화 및 저장으로 모델 설정
model_config = ModelConfig(
    model_path="meta-llama/Llama-3.2-3B-Instruct",
    quantization="auto-round-int8",
    trust_remote_code=True,
)

load_config = LoadConfig(
    inc_save_path="./quantized_model",
)
device_config = DeviceConfig(device="cpu")

# 모델 로드 및 양자화
model_loader = get_model_loader(load_config, model_config)
quantized_model = model_loader.load_model(
    model_config=model_config,
    device_config=device_config,
)

알려진 제약

현재 sglang의 오프라인 양자화 모델 로딩에는 몇 가지 제한이 있어요. 이 문제들은 향후 sglang 업데이트에서 해결될 수도 있어요. 문제가 생기면 Hugging Face Transformers를 대안으로 고려해 보세요.

혼합 비트 양자화 제한 — 혼합 비트 양자화는 완전히 지원되지 않아요. vLLM의 레이어 융합(예: QKV 융합) 때문에, 같은 융합 레이어 안의 구성요소에 서로 다른 비트 폭을 적용하면 호환성 문제가 생길 수 있어요.
양자화 MoE 모델 지원 제한 — 양자화된 MoE 모델은 커널 제한(예: mlp.gate 레이어 양자화 미지원) 때문에 추론 문제가 생길 수 있어요. 이런 레이어는 양자화에서 제외해 보세요.
양자화 VLM 지원 제한
- Qwen2.5-VL-7B
- auto_round:auto_gptq 포맷: 정확도가 거의 0에 가까워요.
- GPTQ 포맷:
```
The output size is not aligned with the quantized weight shape
```
- auto_round:auto_awq와 AWQ 포맷: 정상 동작해요.
SGLang API 사용 제한 — SGLang API는 지금 auto-round-int8 양자화 기법만 지원하고, 더 많은 기법이 추가될 예정이에요.

CPU 서빙

AutoRound INT4 체크포인트(auto_round:auto_gptq, auto_round:auto_awq 패킹 포맷 모두)는 Intel AMX 지원 CPU에서 서빙할 수 있어요:

SGLANG_USE_CPU_ENGINE=1 python3 -m sglang.launch_server \
    --model-path OPEA/Qwen2.5-0.5B-Instruct-int4-sym-inc \
    --quantization auto-round \
    --device cpu --trust-remote-code

현재 SGLang CPU 백엔드는 Intel AMX에서 4비트 AutoRound 체크포인트만 지원해요. 다른 AutoRound 비트 폭과 비-AMX CPU 백엔드는 이 경로에서 지원되지 않아요.

GPTQModel 사용

# 설치
pip install gptqmodel --no-build-isolation -v

from datasets import load_dataset
from gptqmodel import GPTQModel, QuantizeConfig

model_id = "meta-llama/Llama-3.2-1B-Instruct"
quant_path = "Llama-3.2-1B-Instruct-gptqmodel-4bit"

calibration_dataset = load_dataset(
    "allenai/c4", data_files="en/c4-train.00001-of-01024.json.gz",
    split="train"
  ).select(range(1024))["text"]

quant_config = QuantizeConfig(bits=4, group_size=128) # 양자화 설정
model = GPTQModel.load(model_id, quant_config) # 모델 로드

model.quantize(calibration_dataset, batch_size=2) # 양자화
model.save(quant_path) # 모델 저장

LLM Compressor 사용

# 설치
pip install llmcompressor

여기서는 meta-llama/Meta-Llama-3-8B-Instruct를 FP8로 양자화하는 예시로 오프라인 양자화 방법을 설명할게요.

from transformers import AutoTokenizer
from llmcompressor.transformers import SparseAutoModelForCausalLM
from llmcompressor.transformers import oneshot
from llmcompressor.modifiers.quantization import QuantizationModifier

# 1단계: 원본 모델 로드
MODEL_ID = "meta-llama/Meta-Llama-3-8B-Instruct"

model = SparseAutoModelForCausalLM.from_pretrained(
  MODEL_ID, device_map="auto", torch_dtype="auto")
tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)

# 2단계: 오프라인 양자화 수행
# 2-1단계: 간단한 PTQ 양자화 설정
recipe = QuantizationModifier(
  targets="Linear", scheme="FP8_DYNAMIC", ignore=["lm_head"])

# 2-2단계: 양자화 알고리즘 적용
oneshot(model=model, recipe=recipe)

# 3단계: 모델 저장
SAVE_DIR = MODEL_ID.split("/")[1] + "-FP8-Dynamic"
model.save_pretrained(SAVE_DIR)
tokenizer.save_pretrained(SAVE_DIR)

그러면 아래 커맨드로 SGLang에서 바로 양자화된 모델을 사용할 수 있어요:

python3 -m sglang.launch_server \
    --model-path $PWD/Meta-Llama-3-8B-Instruct-FP8-Dynamic \
    --port 30000 --host 0.0.0.0

NVIDIA ModelOpt 사용

NVIDIA Model Optimizer(ModelOpt)는 NVIDIA 하드웨어에 최적화된 고급 양자화 기법을 제공해요.

오프라인 vs 온라인 양자화:

SGLang은 ModelOpt에 대해 두 가지 모드를 지원해요.

오프라인 양자화 (사전 양자화):
- 사용법: Hugging Face에서 사전 양자화 모델을 다운로드하거나 hf_ptq.py를 한 번 실행해 새 양자화 체크포인트를 만들고, 이 체크포인트를 로드해요.
- 장점: 서버 시작이 빠르고, 배포 전에 양자화를 검증할 수 있으며, 리소스 활용이 효율적이에요.
- 단점: 별도의 준비 단계가 필요해요.
온라인 양자화 (양자화 + 서빙):
- 사용법: 표준 BF16/FP16 모델을 로드하고 플래그를 추가해요. 엔진이 시작 시점에 양자화를 적용해요.
- 장점: 편리해요 (새 체크포인트가 필요 없음).
- 단점: 시작 시간이 김, 초기화 중 VRAM 사용량이 늘어남 (OOM 위험).

아래 섹션은 오프라인 경로(사전 양자화 모델 로드 또는 직접 체크포인트 생성)를 안내해요.

사전 양자화 체크포인트 사용

모델이 이미 양자화돼 있다면(예: Hugging Face에서) 바로 로드할 수 있어요.

FP8 모델: --quantization modelopt_fp8 사용.

python3 -m sglang.launch_server \
    --model-path nvidia/Llama-3.1-8B-Instruct-FP8 \
    --quantization modelopt_fp8 \
    --port 30000

FP4 모델: --quantization modelopt_fp4 사용.

python3 -m sglang.launch_server \
    --model-path nvidia/Llama-3.3-70B-Instruct-NVFP4 \
    --quantization modelopt_fp4 \
    --port 30000

직접 양자화 체크포인트 만들기

모델에 사전 양자화 체크포인트가 없다면 NVIDIA Model Optimizer의 hf_ptq.py 스크립트로 만들 수 있어요.

왜 양자화하나요?

VRAM 사용량 감소
더 높은 throughput, 더 낮은 지연시간
더 유연한 배포 (작은 GPU에서)

무엇을 양자화할 수 있나요?

모델 전체
MLP 레이어만
KV 캐시

hf_ptq.py의 주요 옵션:

--qformat: 양자화 포맷 fp8, nvfp4, nvfp4_mlp_only

--kv_cache_qformat: KV 캐시 양자화 포맷 (기본값: fp8)

기본 kv_cache_qformat이 모든 유스케이스에 최적인 건 아니에요. 명시적으로 설정하는 걸 고려해 보세요.

하드웨어 요구사항: Hopper 이상 권장. GPU 메모리가 부족하면 가중치 오프로딩이 발생해 양자화 시간이 극도로 길어질 수 있어요.

자세한 사용법과 지원 모델 아키텍처는 NVIDIA Model Optimizer LLM PTQ를 참고하세요.

SGLang에는 ModelOpt로 모델을 양자화하고 배포용으로 자동 export하는 간소화된 워크플로우가 있어요.

설치

먼저 ModelOpt를 설치해요:

pip install nvidia-modelopt

양자화 및 export 워크플로우

SGLang은 ModelOpt 양자화와 export 전체 워크플로우를 보여주는 예제 스크립트를 제공해요. SGLang 저장소 루트에서 실행해요 (modelopt_quantize_and_export.py 참조):

# ModelOpt FP8 양자화로 모델 양자화 및 export
python examples/usage/modelopt_quantize_and_export.py quantize \
    --model-path TinyLlama/TinyLlama-1.1B-Chat-v1.0 \
    --export-dir ./quantized_tinyllama_fp8 \
    --quantization-method modelopt_fp8

# FP4 양자화 (Blackwell GPU 필요)
python examples/usage/modelopt_quantize_and_export.py quantize \
    --model-path TinyLlama/TinyLlama-1.1B-Chat-v1.0 \
    --export-dir ./quantized_tinyllama_fp4 \
    --quantization-method modelopt_fp4

지원 양자화 기법

modelopt_fp8: NVIDIA Hopper 및 Blackwell GPU에서 최적 성능의 FP8 양자화
modelopt_fp4: NVIDIA Blackwell GPU에서 최적 성능의 FP4 양자화

Python API 사용

ModelOpt 양자화를 프로그래밍 방식으로도 사용할 수 있어요:

import sglang as sgl
from sglang.srt.configs.device_config import DeviceConfig
from sglang.srt.configs.load_config import LoadConfig
from sglang.srt.configs.model_config import ModelConfig
from sglang.srt.model_loader.loader import get_model_loader

# ModelOpt 양자화 및 export로 모델 설정
model_config = ModelConfig(
    model_path="TinyLlama/TinyLlama-1.1B-Chat-v1.0",
    quantization="modelopt_fp8",  # 또는 "modelopt_fp4"
    trust_remote_code=True,
)

load_config = LoadConfig(
    modelopt_export_path="./exported_model",
    modelopt_checkpoint_save_path="./checkpoint.pth",  # 선택, fake quantized checkpoint
)
device_config = DeviceConfig(device="cuda")

# 모델 로드 및 양자화 (export는 자동)
model_loader = get_model_loader(load_config, model_config)
quantized_model = model_loader.load_model(
    model_config=model_config,
    device_config=device_config,
)

양자화 모델 배포

양자화와 export 후 SGLang으로 모델을 배포할 수 있어요:

# export된 양자화 모델 배포
python -m sglang.launch_server \
    --model-path ./quantized_tinyllama_fp8 \
    --quantization modelopt \
    --port 30000 --host 0.0.0.0

또는 Python API 사용 (양자화 단계의 modelopt_export_path와 같은 경로 사용):

import sglang as sgl

def main():
    # Export된 ModelOpt 양자화 모델 배포
    # 경로는 양자화 단계의 modelopt_export_path와 일치해야 함 (예: ./exported_model)
    llm = sgl.Engine(
        model_path="./exported_model",
        quantization="modelopt",
    )

    # 추론 실행
    prompts = [
        "Hello, how are you?",
        "What is the capital of France?",
    ]
    sampling_params = {
        "temperature": 0.8,
        "top_p": 0.95,
        "max_new_tokens": 100,
    }

    outputs = llm.generate(prompts, sampling_params)

    for i, output in enumerate(outputs):
        print(f"Prompt: {prompts[i]}")
        print(f"Output: {output['text']}")

if __name__ == "__main__":
    main()

고급 기능

체크포인트 관리: fake quantized 체크포인트를 저장하고 복원해 재사용할 수 있어요:

# 양자화 중 fake quantized 체크포인트 저장
python examples/usage/modelopt_quantize_and_export.py quantize \
    --model-path meta-llama/Llama-3.2-1B-Instruct \
    --export-dir ./quantized_model \
    --quantization-method modelopt_fp8 \
    --checkpoint-save-path ./my_checkpoint.pth

# 체크포인트는 향후 양자화 실행에서 재사용해 교정 단계를 건너뛸 수 있음

Export-only 워크플로우: 이미 fake quantized ModelOpt 체크포인트가 있다면 바로 export할 수 있어요. 전체 API는 LoadConfig를 참고하세요:

from sglang.srt.configs.device_config import DeviceConfig
from sglang.srt.configs.load_config import LoadConfig
from sglang.srt.configs.model_config import ModelConfig
from sglang.srt.model_loader.loader import get_model_loader

model_config = ModelConfig(
    model_path="meta-llama/Llama-3.2-1B-Instruct",
    quantization="modelopt_fp8",
    trust_remote_code=True,
)

load_config = LoadConfig(
    modelopt_checkpoint_restore_path="./my_checkpoint.pth",
    modelopt_export_path="./exported_model",
)

# 모델 로드 및 export (DeviceConfig 기본값 device="cuda")
model_loader = get_model_loader(load_config, model_config)
model_loader.load_model(model_config=model_config, device_config=DeviceConfig())

ModelOpt의 장점

하드웨어 최적화: NVIDIA GPU 아키텍처에 특화
고급 양자화: 최첨단 FP8·FP4 양자화 기법 지원
원활한 통합: HuggingFace 포맷으로 자동 export해 배포 용이
교정 기반: 최적 양자화 품질을 위한 교정 데이터셋 사용
프로덕션 준비: NVIDIA 지원의 엔터프라이즈급 양자화

ModelSlim 사용

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

설치

# 저장소 clone 후 msmodelslim 설치:
git clone https://gitcode.com/Ascend/msmodelslim.git
cd msmodelslim
bash install.sh

LLM 양자화

대형 모델의 원본 부동소수점 가중치를 다운로드해요. Qwen3-32B를 예로 들면 Qwen3-32B에서 원본 모델 가중치를 얻을 수 있어요. 그런 다음 다른 의존성을 설치해요(모델 관련, huggingface 모델 카드 참조).

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

전통적인 양자화 방법은 양자화 과정에서 교정용 데이터 파일(.jsonl 포맷)을 준비해야 해요.

Qwen3-32B/      # 공식 HF(또는 modelscope) 저장소에서 다운로드한 부동소수점 모델
msmodelslim/    # msmodelslim 저장소
  |----- lab_calib # 교정 데이터 폴더(데이터셋을 ```.jsonl``` 포맷으로 여기에 배치하거나 준비된 것을 사용)
      |----- some file (예: laos_calib.jsonl)
  |----- lab_practice # 양자화 설정이 있는 best practice 폴더
      |----- model folder (예: qwen3_5_moe 폴더) # 양자화 설정 폴더
          |----- quant_config (예: qwen3_5_moe_w8a8.yaml) # 양자화 설정
  |----- another folders
output_folder/   # 아래 커맨드로 생성
  |----- quant_model_weights-00001-of-0001.safetensors # 양자화된 가중치
  |----- quant_model_description.json # 각 레이어의 양자화 기법 설명 파일 (```W4A4_DYNAMIC``` 등)
  |----- another files (예: config.json, tokenizer.json 등)

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

msmodelslim quant \
--model_path ${MODEL_PATH} \
--save_path ${SAVE_PATH} \
--device npu:0,1 \
--model_type Qwen3-32B \
--quant_type w8a8 \
--trust_remote_code True

사용 예시

python3 -m sglang.launch_server \
--model-path $PWD/Qwen3-32B-w8a8 \
--port 30000 --host 0.0.0.0

지원 양자화 기법:
- W4A4_DYNAMIC linear (활성화 온라인 양자화)
- W8A8 linear (활성화 오프라인 양자화)
- W8A8_DYNAMIC linear (활성화 온라인 양자화)
- W4A4_DYNAMIC MOE (활성화 온라인 양자화)
- W4A4_MXFP4 MOE (동적 MXFP4 활성화 양자화)
- W4A8_DYNAMIC MOE (활성화 온라인 양자화)
- W4A8_MXFP MOE (동적 MXFP8 활성화 양자화)
- W8A8_DYNAMIC MOE (활성화 온라인 양자화)
- W4A8 linear TBD
- W4A16 linear TBD
- W48A16 linear TBD
- W4A16 MoE 진행 중
- W8A16 MoE 진행 중
- KV Cache 진행 중
- Attention 진행 중

모델 양자화와 지원에 대한 더 상세한 예시는 ModelSLim 저장소의 examples 섹션을 참고하세요.

온라인 양자화

온라인 양자화를 켜려면 커맨드라인에서 --quantization만 지정하면 돼요. 예를 들어 meta-llama/Meta-Llama-3.1-8B-Instruct 모델의 FP8 양자화를 켜려면 다음 커맨드로 서버를 띄우면 돼요:

python3 -m sglang.launch_server \
    --model-path meta-llama/Meta-Llama-3.1-8B-Instruct \
    --quantization fp8 \
    --port 30000 --host 0.0.0.0

우리 팀은 더 많은 온라인 양자화 기법을 지원하기 위해 노력 중이에요. SGLang은 곧 ["awq", "gptq", "marlin", "gptq_marlin", "awq_marlin", "bitsandbytes", "gguf"]를 포함한(이에 국한되지 않는) 기법을 지원할 예정이에요.

`nvfp4_online` 온라인 양자화 기법

--quantization nvfp4_online으로 적격한 BF16, FP16, 또는 FP8 MoE expert 가중치를 로드 시점에 per-token FP32 활성화 스케일과 함께 NVFP4로 변환할 수 있어요. 직렬화된 NVFP4 체크포인트나 per-tensor FP32 활성화 스케일의 동일 로드 시 변환에는 modelopt_fp4를 사용하세요.

이 설계는 가중치 양자화와 활성화 스케일링을 분리해요:

가중치: SGLang은 적격한 각 MoE expert 가중치 텐서를 로드하면서 표준 2D NVFP4 가중치 양자화로 양자화해요. 생성된 NVFP4 가중치는 정적 E4M3 블록 스케일 + 가중치 amax에서 파생된 정적 per-tensor FP32 스케일을 사용해요. gated MoE expert에선 w1/w3 쌍이 per-tensor FP32 스케일 하나를 공유해요.
활성화: FlashInfer가 런타임에 토큰당 FP32 스케일 하나를 계산·전파해요. per-tensor FP32 활성화 스케일 하나만 받는 백엔드는 modelopt_fp4를 사용해야 해요.
FP8 체크포인트: 적격한 expert 가중치가 FP8로 저장된 경우, SGLang은 먼저 그 텐서를 체크포인트 스케일로 역양자화한 뒤 로딩 중에 NVFP4로 재양자화해요.
다른 레이어: Dense linear 레이어는 소스 체크포인트 정밀도 또는 체크포인트 양자화 경로를 유지해요.

--moe-runner-backend flashinfer_trtllm과 --moe-runner-backend flashinfer_trtllm_routed만 지원돼요. --moe-runner-backend를 생략하면 SGLang은 flashinfer_trtllm을 선택해요. 텐서 병렬 처리가 지원되며, 활성화 per-token 스케일은 각 TP 랭크에서 로컬로 계산되고, 온라인 가중치 양자화는 여전히 로드된 expert 텐서의 per-tensor amax 파생 FP32 스케일을 사용해요.

FlashInfer TRTLLM MoE 백엔드는 shared-expert 융합을 비활성화하므로, 온라인 양자화는 routed MoE expert에 적용되고 shared expert는 체크포인트 정밀도에 남아요. 두 온라인 모드 모두 SGLANG_FP4_IGNORED_LAYERS를 존중하며, FP8 소스 체크포인트에선 나열된 expert가 NVFP4로 변환되지 않고 FP8로 유지돼요.

python3 -m sglang.launch_server \
    --model-path Qwen/Qwen3-30B-A3B-Instruct-2507 \
    --tp-size 2 \
    --ep-size 2 \
    --quantization nvfp4_online \
    --port 30000 --host 0.0.0.0

`quark_int4fp8_moe` 온라인 양자화 기법

AMD GPU(CDNA3 또는 CDNA4 아키텍처)에서 실행되는 SGLang은 --quantization quark_int4fp8_moe 양자화 기법을 지원해요. 이 기법은 원래 고정밀(bfloat16, float16 또는 float32)이던 MoE 레이어를 int4로 동적 양자화된 가중치로 교체하고, 추론 중에 float8로 upcast해 활성화를 그때그때 float8로 동적 양자화된 float8 정밀도로 연산을 실행해요.

다른 레이어(예: attention 레이어의 projection)의 가중치는 온라인으로 float8에 직접 양자화돼요.

`quark_mxfp4` 온라인 양자화 기법

하드웨어 FP4 지원 AMD GPU(CDNA4 아키텍처, 예: MI355x)에서 실행되는 SGLang은 --quantization quark_mxfp4를 지원해요. 이 기법은 BF16 또는 NVFP4 모델 가중치를 로드 시점에 MXFP4로 양자화하고, 활성화에 동적 MXFP4 양자화를 사용하며 BF16 GEMM 대신 MXFP4 GEMM을 사용해요.

예시 (BF16 → MXFP4 재양자화):

sglang serve --model-path Qwen/Qwen3-30B-A3B \
    --tensor-parallel-size 1 \
    --quantization quark_mxfp4

온라인 NVFP4 → MXFP4 재양자화

--quantization quark_mxfp4 옵션은 NVFP4 체크포인트(예: nvidia/Kimi-K2.6-NVFP4)를 로드 시점에 MXFP4로 변환해 지원 AMD 하드웨어(gfx95x+)에서 효율적 추론을 가능하게 해요:

소스 NVFP4 체크포인트의 양자화 메타데이터는 config.json(quantization_config) 또는 독립된 hf_quant_config.json에서 읽혀요;
생산자가 제외(declared excluded)한 모듈은 더 높은 정밀도로 유지돼요;
혼합 정밀도 NVFP4 체크포인트("quant_algo": "MIXED_PRECISION", 예: nvidia/Qwen3.5-397B-A17B-NVFP4-V2)도 지원돼요.

예시 (NVFP4 → MXFP4 재양자화):

sglang serve --model-path nvidia/Kimi-K2.6-NVFP4 \
    --tensor-parallel-size 4 \
    --quantization quark_mxfp4 \

온라인 FP8 → MXFP4 재양자화

--quantization quark_mxfp4 옵션은 FP8 dense 및 MOE 모델을 MXFP4로 변환하는데, 다음 로직을 따라요:

FP8 가중치 텐서 로드,
BF16으로 역양자화,
MXFP4로 재양자화

가중치 로딩 동안 점진적으로 수행돼요.

예시 (FP8 → MXFP4 재양자화):

sglang serve --model-path Qwen/Qwen3-30B-A3B-Instruct-2507-FP8 \
    --tensor-parallel-size 1 \
    --quantization quark_mxfp4

Intel® Neural Compressor 온라인 양자화 기법

SGLang은 Intel® Neural Compressor의 고급 알고리즘 auto-round 기반 양자화 기법을 지원해요. --quantization auto-round-int8만 지정하면 이 기능을 쓸 수 있어요. 모델을 대상 포맷으로 그때그때 양자화해요. 더 많은 온라인 양자화 기법이 추가될 예정이에요.

지원 양자화 기법

양자화 기법	스킴	검증 하드웨어 환경
auto-round-int8	INT8 per-channel 양자화 가중치 + INT8 per-token 동적 양자화 활성화	Intel Xeon Scalable 프로세서, Nvidia A100 GPU

Ascend NPU에서의 Diffusion 모델 양자화

SGLang-Diffusion은 Ascend A5 NPU에서 diffusion 모델(예: Wan2.2)용 MXFP8 양자화를 온라인·오프라인(ModelSlim) 두 모드로 지원해요. 이는 LLM 서빙 경로와는 별개이며 sglang serve / sglang generate CLI를 사용해요.

요구사항: Ascend A5, CANN ≥ 8.0.RC3

온라인 MXFP8

--quantization mxfp8을 넘기면 FP16/BF16 transformer 가중치를 로드 시점에 동적으로 MXFP8로 양자화해요:

sglang serve \
  --model-path Wan-AI/Wan2.2-T2V-A14B-Diffusers \
  --quantization mxfp8 \
  --num-gpus 4

오프라인 MXFP8 (ModelSlim)

msModelSlim으로 사전 양자화하고 체크포인트를 직접 로드하면 돼요 — 양자화 스킴은 quant_model_description.json에서 자동 감지돼요:

sglang generate \
  --model-path /path/to/wan2_2_mxfp8_diffusers \
  --prompt "a beautiful sunset" \
  --save-output

완전한 양자화 + 포맷 변환 워크플로우와 지원 스킴 전체 목록은 Ascend NPU diffusion 양자화와 SGLang-Diffusion 양자화를 참고하세요.

참고 자료

더 알아보기 (Learn more)

양자화된 KV 캐시 — KV 캐시를 FP8/FP4로 줄여 더 긴 컨텍스트를 담는 방법
Attention 백엔드 — 커널 성능과 양자화 KV 캐시 지원

양자화

양자화 (Quantization)

오프라인 vs 온라인 양자화

플랫폼 호환성

FP4/FP8 양자화용 GEMM 백엔드

--fp8-gemm-backend (Blockwise FP8 GEMM)

--fp4-gemm-backend (NVFP4 GEMM)

오프라인 양자화

오프라인 모델 양자화 예시

Unsloth 사용

auto-round 사용

GPTQModel 사용

LLM Compressor 사용

NVIDIA ModelOpt 사용

사전 양자화 체크포인트 사용

직접 양자화 체크포인트 만들기

설치

양자화 및 export 워크플로우

지원 양자화 기법

Python API 사용

양자화 모델 배포

고급 기능

ModelOpt의 장점

ModelSlim 사용

온라인 양자화

nvfp4_online 온라인 양자화 기법

quark_int4fp8_moe 온라인 양자화 기법

quark_mxfp4 온라인 양자화 기법

온라인 NVFP4 → MXFP4 재양자화

온라인 FP8 → MXFP4 재양자화

Intel® Neural Compressor 온라인 양자화 기법

지원 양자화 기법

Ascend NPU에서의 Diffusion 모델 양자화

온라인 MXFP8

오프라인 MXFP8 (ModelSlim)

참고 자료

더 알아보기 (Learn more)

`--fp8-gemm-backend` (Blockwise FP8 GEMM)

`--fp4-gemm-backend` (NVFP4 GEMM)

`nvfp4_online` 온라인 양자화 기법

`quark_int4fp8_moe` 온라인 양자화 기법

`quark_mxfp4` 온라인 양자화 기법