온라인 양자화

온라인 양자화 (Online Quantization)

보통 양자화는 모델을 먼저 압축해서 체크포인트로 저장해 두고 배포하죠. 그런데 BF16/FP16 모델을 로딩 시점에 그대로 양자화해 버리는 방법도 있어요. vLLM의 온라인 양자화(Online Quantization) 가 그거예요. 사전 양자화된 체크포인트나 캘리브레이션 데이터 없이도 Linear·MoE 웨이트를 FP8 같은 더 낮은 정밀도로 줄여줍니다. 이 페이지에서 그 사용법을 살펴볼게요.

출처: vLLM 공식 문서 — Online Quantization

동작 방식 (How it works)

온라인 양자화는 로딩 중에 모델의 Linear·MoE 웨이트를 더 낮은 정밀도로 변환하고, 활성화는 매 포워드 패스마다 동적으로 스케일링해요. 즉 미리 양자화된 체크포인트를 만들 필요가 없죠. 스킴 이름을 quantization 파라미터에 넘기기만 하면 돼요.

빠른 시작 (Quick start)

from vllm import LLM

# 텐서별 FP8 양자화 (웨이트 텐서당 스케일 하나)
llm = LLM("meta-llama/Llama-3.1-8B", quantization="fp8_per_tensor")

# 블록별 FP8 양자화 (웨이트 128x128 블록, 활성화 1x128 블록 스케일링)
llm = LLM("meta-llama/Llama-3.1-8B", quantization="fp8_per_block")

# 웨이트·활성화 MXFP8 양자화
llm = LLM("meta-llama/Llama-3.1-8B", quantization="mxfp8")

# MXFP4 웨이트; 활성화 양자화는 선택한 linear_backend에 따라 다름
llm = LLM("meta-llama/Llama-3.1-8B", quantization="mxfp4")

# MXFP4 MOE 전용 웨이트·활성화 양자화
llm = LLM(
    "Qwen/Qwen3.5-35B-A3B",
    quantization="mxfp4",
    quantization_config={"linear": {"activation": None, "weight": None}}
)

CLI로도 같은 걸 할 수 있어요.

vllm serve meta-llama/Llama-3.1-8B --quantization fp8_per_tensor
vllm serve meta-llama/Llama-3.1-8B --quantization fp8_per_block
vllm serve meta-llama/Llama-3.1-8B --quantization mxfp8
vllm serve meta-llama/Llama-3.1-8B --quantization mxfp4

vllm serve Qwen/Qwen3.5-35B-A3B --quantization mxfp4 \
    --quantization-config '{"linear":{"activation":null,"weight":null}}'

지원 스킴 (Supported schemes)

고급 구성 (Advanced configuration)

세밀한 제어를 원하면 quantization_config 딕셔너리를 써요.

quantization_config:
  linear:
    weight: <name>      # vllm/config/quantization.py의 QUANT_KEY_NAMES 참고
    activation: <name>
  moe:
    weight: <name>
    activation: <name>
  ignore: [<layer-name-or-regex-or-fnmatch-pattern>, ...]

linear와 moe는 전체 {weight, activation} 딕셔너리나 단순 문자열을 받아요. 문자열은 먼저 --quantization 약칭(각 레이어 종류 슬롯에 매칭)으로, 그다음 QUANT_KEY_NAMES의 웨이트 이름으로 해석되죠. 설정하지 않은 필드는 --quantization 약칭의 기본값(또는 이미 양자화된 체크포인트라면 체크포인트가 선언한 값)으로 폴백해요.

CLI는 JSON이나 점(dotted) 키 방식 모두 받아요.

vllm serve <model> --quantization-config '{"moe":{"activation":"mxfp8"}}'
vllm serve <model> --quantization-config.moe.activation mxfp8

이미 양자화된 체크포인트의 활성화 오버라이드

체크포인트 양자화 모델에서는 quantization_config로 내장된 웨이트와 무관하게 활성화 포맷을 골라 잡을 수 있어요. 오늘날 이는 MXFP4 MoE 체크포인트(gpt-oss)에서 FP8 활성화를 선택할 때 연결되어 있어요.

vllm serve openai/gpt-oss-20b --quantization-config.moe.activation mxfp8

부분 양자화 체크포인트의 미양자화 레이어 온라인 양자화

온라인 양자화는 이미 양자화된 체크포인트에서 원래 양자화되지 않은 채 남아 있는 레이어에도 쓸 수 있어요(원래 quant_method는 modelopt, compressed-tensors, quark 등 무엇이든 무관). 체크포인트의 quant_method는 그 양자화된 레이어를 계속 담당하고, 선택한 미양자화 레이어만 요청한 온라인 방식을 써요.

vllm serve amd/Qwen3.5-35B-A3B-MXFP4 \
    --quantization-config.linear mxfp8

이 명령은 MOE 전문가만 양자화된 Quark 체크포인트의 dense 선형 레이어에 MXFP8 양자화를 추가해요.

레이어 제외 (Excluding layers)

ignore 파라미터로 특정 레이어를 건너뛸 수 있어요. 정확한 레이어 이름, 정규식(re: 접두사), fnmatch.fnmatch 패턴을 받아요.

from vllm import LLM

llm = LLM(
    "ibm-granite/granite-3.0-1b-a400m-base",
    quantization="fp8_per_tensor",
    quantization_config={
        "ignore": [
            # 정확한 레이어 이름
            "model.layers.1.self_attn.o_proj",
            # regex: 모든 QKV 프로젝션 건너뛰기
            "re:.*[qkv]_proj",
            # fnmatch: 모든 MoE 전문가 건너뛰기
            "*mlp.experts*",
        ],
    },
)

레이어별 세분화 양자화 스킴 (Fine-grained per-layer)

targets 파라미터로 레이어별로 다른 온라인 약칭을 적용할 수 있어요. 키는 정확한 레이어 이름/정규식/fnmatch 패턴, 값은 약칭 이름(fp8_per_tensor, fp8_per_block, fp8_per_channel, mxfp8, int8_per_channel_weight_only, nvfp4_per_token)이에요.

from vllm import LLM

llm = LLM(
    "Qwen/Qwen3.5-35B-A3B",
    quantization="online",
    quantization_config={
        "targets": {
            # 정확한 레이어 이름
            "model.layers.0.self_attn.o_proj": "fp8_per_tensor",
            # regex: 모든 QKV 프로젝션 양자화
            r"re:.*self_attn\.qkv_proj.*": "mxfp8",
            # fnmatch: 모든 MoE 전문가 양자화
            "*mlp.experts*": "mxfp4",
        },
    },
)

targets는 온라인 linear/moe와 상호 배타적이라 둘 중 하나만 써야 해요. 패턴에 매칭되지 않는 레이어는 체크포인트 dtype 그대로 남고, targets와 ignore 양쪽에 매칭되거나 targets 패턴 여러 개에 매칭되면 오류가 납니다. fnmatch 스타일 패턴은 온라인 양자화에서만 지원돼요(Quark·compressed-tensors config에는 적용되지 않음).

더 알아보기 (Learn more)

• vLLM 양자화 (Quantization)
• 양자화된 KV 캐시 (Quantized KV Cache)
• AMD Quark
• LLM Compressor