LLM 양자화 기법 비교 가이드 — GPTQ, AWQ, GGUF, bitsandbytes 실전 적용

import torch
import numpy as np

def absmax_quantize(tensor: torch.Tensor, bits: int = 8) -> tuple:
    """Absmax 양자화: 절대 최대값 기준 대칭 스케일링"""
    qmax = 2 ** (bits - 1) - 1  # INT8이면 127, INT4이면 7
    scale = tensor.abs().max() / qmax
    quantized = torch.round(tensor / scale).clamp(-qmax, qmax).to(torch.int8)
    return quantized, scale

def zeropoint_quantize(tensor: torch.Tensor, bits: int = 8) -> tuple:
    """Zero-Point 양자화: 비대칭 분포 대응"""
    qmin = -(2 ** (bits - 1))
    qmax = 2 ** (bits - 1) - 1
    scale = (tensor.max() - tensor.min()) / (qmax - qmin)
    zero_point = qmin - torch.round(tensor.min() / scale)
    quantized = torch.round(tensor / scale + zero_point).clamp(qmin, qmax).to(torch.int8)
    return quantized, scale, zero_point

# 예시: 양자화 오차 비교
weight = torch.randn(4096, 4096, dtype=torch.float32)
q_abs, scale_abs = absmax_quantize(weight, bits=4)
restored_abs = q_abs.float() * scale_abs
error_4bit = (weight - restored_abs).abs().mean()

q_abs8, scale_abs8 = absmax_quantize(weight, bits=8)
restored_abs8 = q_abs8.float() * scale_abs8
error_8bit = (weight - restored_abs8).abs().mean()

print(f"INT8 평균 양자화 오차: {error_8bit:.6f}")
print(f"INT4 평균 양자화 오차: {error_4bit:.6f}")
# INT8 평균 양자화 오차: 0.003127
# INT4 평균 양자화 오차: 0.048915

from transformers import AutoModelForCausalLM, AutoTokenizer
from auto_gptq import AutoGPTQForCausalLM, BaseQuantizeConfig

# 1. 원본 모델 로딩
model_id = "meta-llama/Llama-3.1-8B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_id)

# 2. 양자화 설정
quantize_config = BaseQuantizeConfig(
    bits=4,                   # 4bit 양자화
    group_size=128,           # 128개 가중치 단위로 스케일 공유
    desc_act=True,            # Activation order 사용 (정확도 향상)
    damp_percent=0.1,         # Hessian 안정화를 위한 댐핑 비율
    sym=True,                 # 대칭 양자화
)

# 3. 캘리브레이션 데이터 준비 (128~256 샘플 권장)
calibration_data = [
    tokenizer(text, return_tensors="pt", max_length=2048, truncation=True)
    for text in calibration_texts[:128]
]

# 4. 양자화 실행
model = AutoGPTQForCausalLM.from_pretrained(
    model_id, quantize_config=quantize_config
)
model.quantize(calibration_data)

# 5. 양자화된 모델 저장
model.save_quantized("./llama-3.1-8b-gptq-4bit")
tokenizer.save_pretrained("./llama-3.1-8b-gptq-4bit")

from awq import AutoAWQForCausalLM
from transformers import AutoTokenizer

# 1. 모델 및 토크나이저 로딩
model_id = "meta-llama/Llama-3.1-8B-Instruct"
model = AutoAWQForCausalLM.from_pretrained(model_id)
tokenizer = AutoTokenizer.from_pretrained(model_id)

# 2. AWQ 양자화 설정
quant_config = {
    "zero_point": True,       # Zero-Point 양자화 사용
    "q_group_size": 128,      # 그룹 크기
    "w_bit": 4,               # 4bit 양자화
    "version": "GEMM",        # GEMM 커널 사용 (범용)
    # "version": "Marlin",    # Marlin 커널 (A100/H100에서 최적)
}

# 3. 양자화 실행 (GPTQ보다 빠름)
model.quantize(tokenizer, quant_config=quant_config)

# 4. 저장
model.save_quantized("./llama-3.1-8b-awq-4bit")
tokenizer.save_pretrained("./llama-3.1-8b-awq-4bit")

# 1. llama.cpp 빌드
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
cmake -B build -DLLAMA_CUDA=ON  # GPU 가속 활성화
cmake --build build --config Release -j$(nproc)

# 2. HuggingFace 모델을 GGUF FP16으로 변환
python convert_hf_to_gguf.py \
    ./models/Llama-3.1-8B-Instruct/ \
    --outfile ./models/llama-3.1-8b-f16.gguf \
    --outtype f16

# 3. Q4_K_M 양자화 적용
./build/bin/llama-quantize \
    ./models/llama-3.1-8b-f16.gguf \
    ./models/llama-3.1-8b-Q4_K_M.gguf \
    Q4_K_M

# 4. (선택) Importance Matrix를 활용한 고품질 양자화
# 먼저 imatrix 데이터 생성
./build/bin/llama-imatrix \
    -m ./models/llama-3.1-8b-f16.gguf \
    -f calibration_data.txt \
    -o imatrix.dat

# imatrix 기반 양자화
./build/bin/llama-quantize \
    --imatrix imatrix.dat \
    ./models/llama-3.1-8b-f16.gguf \
    ./models/llama-3.1-8b-Q4_K_M-imat.gguf \
    Q4_K_M

# 5. 여러 양자화 타입 일괄 생성
for QTYPE in Q4_K_M Q5_K_M Q6_K Q8_0; do
    ./build/bin/llama-quantize \
        ./models/llama-3.1-8b-f16.gguf \
        "./models/llama-3.1-8b-${QTYPE}.gguf" \
        ${QTYPE}
    echo "완료: ${QTYPE}"
done

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

# 1. 4-bit 양자화 설정 (NF4 + Double Quantization)
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,                    # 4bit 양자화 활성화
    bnb_4bit_quant_type="nf4",            # NF4 데이터 타입 (FP4 대비 우수)
    bnb_4bit_compute_dtype=torch.bfloat16, # 연산은 BF16으로 수행
    bnb_4bit_use_double_quant=True,        # 이중 양자화 (0.4bit 추가 절감)
)

# 2. 양자화된 모델 로딩 (사전 양자화 체크포인트 불필요!)
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B-Instruct",
    quantization_config=bnb_config,
    device_map="auto",
)
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-3.1-8B-Instruct")

# 3. 8-bit 양자화도 간단히 적용 가능
bnb_config_8bit = BitsAndBytesConfig(
    load_in_8bit=True,
    llm_int8_threshold=6.0,   # 아웃라이어 탐지 임계값
)

model_8bit = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B-Instruct",
    quantization_config=bnb_config_8bit,
    device_map="auto",
)

# 4. QLoRA 파인튜닝을 위한 설정 예시
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

model = prepare_model_for_kbit_training(model)

lora_config = LoraConfig(
    r=16,
    lora_alpha=32,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)

model = get_peft_model(model, lora_config)
print(f"학습 가능 파라미터: {model.print_trainable_parameters()}")

용도 판별
  |
  +-- GPU 서버 프로덕션 서빙? --> AWQ (Marlin 커널) 또는 GPTQ (Marlin 커널)
  |
  +-- 로컬/엣지 배포? --> GGUF (Q4_K_M 또는 Q5_K_M)
  |
  +-- 파인튜닝(QLoRA)? --> bitsandbytes (NF4)
  |
  +-- 빠른 프로토타이핑? --> bitsandbytes (설정 2줄로 즉시 적용)

# AWQ 모델을 vLLM으로 서빙
pip install vllm

# AWQ Marlin 커널로 최적 성능 달성
python -m vllm.entrypoints.openai.api_server \
    --model ./llama-3.1-8b-awq-4bit \
    --quantization awq_marlin \
    --dtype auto \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.9 \
    --port 8000

# GPTQ 모델 서빙
python -m vllm.entrypoints.openai.api_server \
    --model ./llama-3.1-8b-gptq-4bit \
    --quantization gptq_marlin \
    --dtype auto \
    --max-model-len 8192 \
    --port 8000

# Ollama로 GGUF 모델 서빙 (로컬 환경)
ollama create my-llama -f Modelfile
# Modelfile 내용:
# FROM ./llama-3.1-8b-Q4_K_M.gguf
# PARAMETER num_ctx 8192
# PARAMETER temperature 0.7

from transformers import AutoModelForCausalLM, AutoTokenizer
import torch

def evaluate_quantized_model(model, tokenizer, test_prompts: list) -> dict:
    """양자화 모델 품질 평가"""
    results = {
        "total": len(test_prompts),
        "coherent": 0,
        "avg_length": 0,
    }

    total_length = 0
    for prompt in test_prompts:
        inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
        with torch.no_grad():
            outputs = model.generate(
                **inputs,
                max_new_tokens=256,
                temperature=0.7,
                do_sample=True,
            )
        response = tokenizer.decode(outputs[0], skip_special_tokens=True)
        generated = response[len(prompt):]
        total_length += len(generated)

        # 기본 일관성 검사
        if len(generated.strip()) > 20 and not generated.strip().endswith(generated.strip()[:10]):
            results["coherent"] += 1

    results["avg_length"] = total_length / len(test_prompts)
    results["coherence_rate"] = results["coherent"] / results["total"]
    return results

# 평가 실행 예시
test_prompts = [
    "Python으로 이진 탐색 알고리즘을 구현하세요:",
    "머신러닝에서 과적합을 방지하는 방법 3가지를 설명하세요:",
    "REST API와 GraphQL의 차이점을 비교하세요:",
]
# results = evaluate_quantized_model(model, tokenizer, test_prompts)
# print(f"일관성: {results['coherence_rate']:.1%}")

RuntimeError: CUDA out of memory

error: unknown tensor 'model.layers.0.self_attn.rotary_emb.inv_freq'

RuntimeError: No GPU found. A GPU is needed for quantization.

ValueError: The quantization method is not supported

시작: LLM 양자화가 필요한가?
  |
  +-- 파인튜닝이 목적인가?
  |     |
  |     +-- Yes --> bitsandbytes NF4 + QLoRA
  |     +-- No --> 다음 단계
  |
  +-- 서빙 환경은?
        |
        +-- GPU 서버 (A100/H100)
        |     |
        |     +-- 속도 최우선 --> AWQ + Marlin 커널 (741 tok/s)
        |     +-- 품질 최우선 --> AWQ 또는 bitsandbytes 8bit
        |
        +-- 소비자 GPU (RTX 3090/4090)
        |     |
        |     +-- GGUF Q4_K_M (CPU 오프로딩 가능)
        |     +-- AWQ 4bit (VRAM 충분 시)
        |
        +-- CPU / Apple Silicon
              |
              +-- GGUF Q4_K_M 또는 Q5_K_M (유일한 선택지)