온라인 양자화

온라인 양자화 (Online Quantization)

온라인 양자화를 사용하면 BF16/FP16 모델의 Linear 및 MoE 가중치를 사전 양자화된 체크포인트나 보정 데이터 없이 로드 시점에 낮은 정밀도(예: FP8)로 양자화할 수 있어요. 가중치는 모델 로딩 중 변환되고, 활성화는 매 forward pass마다 동적으로 스케일링됩니다.

출처: 문서

본문

퀵 스타트 (Quick Start)

quantization 파라미터에 체계 이름을 전달합니다.

from vllm import LLM

# Per-tensor FP8 quantization (one scale per weight tensor)
llm = LLM("meta-llama/Llama-3.1-8B", quantization="fp8_per_tensor")

# Per-block FP8 quantization (128x128 block scaling for weights and 1x128 block scaling for activations)
llm = LLM("meta-llama/Llama-3.1-8B", quantization="fp8_per_block")

# MXFP8 quantization for weights and activations
llm = LLM("meta-llama/Llama-3.1-8B", quantization="mxfp8")

# MXFP4 weight; activation quantization depends on the `linear_backend` picked
llm = LLM("meta-llama/Llama-3.1-8B", quantization="mxfp4")

# MXFP4 MOE-only weight and activation quantization
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 딕셔너리를 사용합니다.

스키마 (Schema)

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

linear 과 moe 는 전체 {weight, activation} dict 또는 단순 문자열을 받습니다. 문자열은 먼저 --quantization 쇼트핸드와 대조해 해석되고(일치하는 레이어 종류 슬롯을 가져감), 그다음 QUANT_KEY_NAMES 를 가중치 이름으로 해석합니다. 설정되지 않은 필드는 --quantization 쇼트핸드의 기본값으로 폴백하거나, 이미 양자화된 체크포인트에서는 체크포인트가 선언한 값으로 폴백합니다.

XPU에서 non-block FP8 scaled-mm 선형 레이어는 기본적으로 W8A16이며, --linear-backend xpu 를 설정하면 W8A8을 강제합니다. --linear-backend xpu_woq 를 사용하면 weight-only 양자화(W8A16)를 명시적으로 선택할 수 있어요. --linear-backend torch 도 W8A8을 강제하지만 커스텀 XPU 커널 대신 torch._scaled_mm 을 통해 GEMM을 실행합니다.

CLI는 같은 형태를 JSON 또는 점 표기 키로 받습니다.

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

이미 양자화된 체크포인트의 활성화 오버라이드 (Activation overrides on already-quantized checkpoints)

체크포인트 양자화 모델의 경우 quantization_config 를 사용해 굽혀진 가중치와 독립적으로 활성화 형식을 선택할 수 있어요. 지원되는 오버라이드는 체크포인트별입니다. 오늘날 이것은 FP8 활성화를 옵트인할 수 있는 MXFP4 MoE 체크포인트(gpt-oss)에 연결되어 있습니다.

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

--moe-backend 와 결합해 특정 커널 계열을 고정할 수 있습니다.

부분 양자화 체크포인트의 미양자화 레이어에 온라인 양자화 (Online quantization on unquantized layers from partially-quantized checkpoints)

온라인 양자화는 원본 quant_method(modelopt, compressed-tensors, quark 등)와 무관하게, 원본 체크포인트에서 미양자화로 남은 레이어들에 대해 이미 양자화된 체크포인트에서 사용할 수 있습니다.

체크포인트의 quant_method 는 양자화된 레이어를 계속 담당하고, 선택된 미양자화 레이어는 요청된 온라인 방법을 사용합니다.

예를 들어:

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

MOE 전문가만 양자화된 Quark 체크포인트의 dense 선형 레이어에 MXFP8 양자화를 추가합니다.

Info: quantization_config.ignore 는 온라인 전용 제외입니다. 원본 quant_method 는 자체 ignore 구현과 config.json 에 지정된 무시된 레이어에만 의존합니다.

Dense와 MoE 레이어에 별도 체계 (Separate Schemes for Dense and MoE Layers)

linear 와 moe 필드를 통해 dense 선형 레이어와 MoE 전문가 레이어에 서로 다른 양자화 체계를 적용할 수 있어요. 각각 전체 스펙 dict 또는 온라인 쇼트핸드(예: "fp8_per_block")나 가중치 형식(예: "fp8_per_block_static")을 명명하는 단순 문자열을 받습니다. 설정되지 않은 필드는 쇼트핸드 기본값으로 폴백합니다.

from vllm import LLM

# Linear: per-block FP8; MoE: per-tensor FP8 (inherited from the shorthand)
llm = LLM(
    "ibm-granite/granite-3.0-1b-a400m-base",
    quantization="fp8_per_tensor",
    quantization_config={
        "linear": "fp8_per_block",
    },
)

또는,

from vllm import LLM

# Linear: per-tensor FP8 (inherited); MoE: per-block FP8
llm = LLM(
    "ibm-granite/granite-3.0-1b-a400m-base",
    quantization="fp8_per_tensor",
    quantization_config={
        "moe": "fp8_per_block",
    },
)

양자화에서 레이어 제외 (Excluding Layers from Quantization)

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": [
            # exact layer name
            "model.layers.1.self_attn.o_proj",
            # regex: skip all QKV projections
            "re:.*[qkv]_proj",
            # fnmatch: skip all MoE experts
            "*mlp.experts*",
        ],
    },
)

참고: 융합 레이어(예: q_proj, k_proj, v_proj 를 융합한 qkv_proj)의 경우 패턴이 융합 이름이나 모든 비융합 샤드 이름과 직접 일치할 수 있습니다.

세분화된 per-layer 양자화 체계 (Fine-Grained Per-Layer Quantization Schemes)

targets 파라미터를 사용해 linear / moe 를 통해 모든 곳에 적용되는 하나의 체계 대신 서로 다른 레이어에 서로 다른 온라인 쇼트핸드를 적용합니다. 키는 정확한 레이어 이름, re: 접두사가 붙은 정규식 패턴, 또는 fnmatch.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": {
            # exact layer name
            "model.layers.0.self_attn.o_proj": "fp8_per_tensor",
            # regex: quantize all QKV projections
            r"re:.*self_attn\.qkv_proj.*": "mxfp8",
            # fnmatch: quantize all MoE experts
            "*mlp.experts*": "mxfp4",
        },
    },
)

또는 CLI로:

vllm serve Qwen/Qwen3.5-35B-A3B \
  --quantization online \
  --quantization-config '{"targets":{"model.layers.0.self_attn.o_proj":"fp8_per_tensor","re:.*self_attn\\.qkv_proj.*":"mxfp8","*mlp.experts*":"mxfp4"}}'

Info:

• targets 는 온라인 linear 및 moe 와 상호 배타적입니다. 둘 중 하나만 설정하세요.
• 어떤 targets 패턴과도 일치하지 않는 레이어는 체크포인트 dtype 그대로 둡니다.
• 레이어 이름이 targets 와 ignore 둘 다에 일치하면 오류가 발생합니다.
• 레이어가 둘 이상의 targets 패턴과 일치하면 오류가 발생합니다.
• fnmatch 스타일 패턴은 온라인 양자화에서만 지원되며 Quark 또는 compressed-tensors 구성에는 적용되지 않습니다.

더 알아보기 (Learn more)