vllm-project/llm-compressor

📦 llmcompressor – vLLM 배포를 위한 빠르고 유연한 LLM 양자화 도구

소개 – llmcompressor는 vLLM 런타임에서 효율적인 추론을 위해 대규모 언어 모델 체크포인트를 준비하는 Python 라이브러리입니다. 다양한 양자화 알고리즘(가중치 전용, 활성화, KV 캐시, 어텐션)과 모델 수준 변환을 적용한 후, vLLM이 직접 로드할 수 있는 compressed‑tensors 형식으로 결과를 저장합니다.

중요성 – 양자화를 통해 30B 파라미터 모델을 원래 VRAM 점유율의 일부로 줄이면서도 대부분의 원본 품질을 유지할 수 있습니다. llmcompressor의 특징:

고속 커널 – Triton 기반 GPTQ 커널로 이전의 eager 구현보다 약 15배 빠르며, 동일한 모양의 레이어를 배치 처리할 수 있습니다.
다양한 정밀도 형식 – INT4, FP8, NVFP4, MXFP4, 혼합 정밀도 조합(예: W4A16, NVFP4A16) 및 저비트 사용자 지정 형식.
특수 아키텍처 지원 – MoE 모델, 비전-언어, 오디오-언어, 심지어 모델 정의가 없는 모델까지 지원.
확장 가능한 워크플로우 – DDP 및 디스크 오프로딩을 통해 단일 GPU 또는 소규모 GPU 클러스터에서 수천억 파라미터 모델을 압축할 수 있습니다.

🎯 일반적인 사용 사례

상황	llmcompressor의 도움
단일 GPU에서 30B 파라미터 LLM 배포	가중치/활성화를 FP8 또는 NVFP4로 변환하여 퍼플렉서티(perplexity)를 유지하면서 VRAM 사용량을 70% 이상 절감.
제한된 하드웨어에서 거대한 MoE 모델(예: Qwen‑3.8‑2.4T) 실행	REAP 전문가 가지치기(pruning) + NVFP4 파이프라인을 사용하여 양자화 전 중요도가 낮은 전문가를 제거.
여러 모델에 대한 빠른 양자화 파이프라인 필요	Triton 가속 GPTQ와 배치 처리를 통해 전체 시간을 며칠에서 몇 시간으로 단축.
기존 Hugging‑Face 워크플로우 유지 희망	`AutoModelForCausalLM` / `AutoTokenizer`와 직접 작동하며, vLLM이 `LLM(<path>)`으로 로드하는 표준 `compressed‑tensors` 체크포인트를 출력.

⚙️ 핵심 기능 (README 기준)

양자화 알고리즘: 단순 PTQ, GPTQ, AWQ, SmoothQuant, AutoRound, SpinQuant, QuIP, REAP 전문가 가지치기.
지원 정밀도: W8A8, W4AFP8, NVFP4, MXFP4, MXFP8, FP8, INT4 및 임의 비트(WNA4/8/16).
혼합 정밀도 파이프라인: 가중치 전용(예: INT4)과 활성화 전용(FP8) 또는 블록 단위 형식을 결합.
KV 캐시 및 어텐션 양자화: 헤드별 변형을 포함한 FP8 및 NVFP4 옵션.
아키텍처별 지원: MoE LLM, 비전-언어, 오디오-언어 및 Hugging‑Face 정의가 없는 모델.
확장 가능한 실행: 분산 데이터 병렬(DDP) 양자화, 순차 로딩, GPU 메모리에 맞지 않는 모델을 위한 디스크 오프로딩.
원활한 vLLM 통합: 생성된 체크포인트는 vllm.LLM에서 직접 사용 가능.

📦 설치

pip install llmcompressor   # 라이브러리 및 의존성 설치

(결과 체크포인트로 추론하려면 vllm을 별도로 설치하세요.)

🛠️ 퀵스타트 예제 (README 기준)

from compressed_tensors.offload import dispatch_model
from transformers import AutoModelForCausalLM, AutoTokenizer
from llmcompressor import oneshot
from llmcompressor.modifiers.quantization import QuantizationModifier

MODEL_ID = "Qwen/Qwen3-30B-A3B"
model = AutoModelForCausalLM.from_pretrained(MODEL_ID)
tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)

# 가중치와 활성화를 FP8(블록 단위)로 양자화하고 일부 레이어 건너뛰기
recipe = QuantizationModifier(
    targets="Linear",
    scheme="FP8_BLOCK",
    ignore=["lm_head", "re:.*mlp.gate$"],
)

oneshot(model=model, recipe=recipe)   # 제자리(in-place) 양자화 적용

# 짧은 생성으로 검증
dispatch_model(model)
ids = tokenizer("Hello my name is", return_tensors="pt").input_ids.to(model.device)
print(tokenizer.decode(model.generate(ids, max_new_tokens=20)[0]))

# vLLM용 저장
SAVE_DIR = "Qwen3-30B-A3B-FP8-BLOCK"
model.save_pretrained(SAVE_DIR)
tokenizer.save_pretrained(SAVE_DIR)

vLLM으로 실행:

from vllm import LLM
llm = LLM("Qwen3-30B-A3B-FP8-BLOCK")
print(llm.generate("My name is"))

📚 문서 및 커뮤니티

전체 문서 – https://docs.vllm.ai/projects/llm-compressor/en/latest/ (설치, 단계별 압축 가이드, FAQ).
블로그 공지 – https://neuralmagic.com/blog/llm-compressor-is-here-faster-inference-with-vllm/.
커뮤니티 – vLLM Slack (#sig-quantization, #llm-compressor).
설문조사 – README에 링크된 1분 사용자 설문조사로 피드백 제공.

📈 프로젝트 성숙도

PyPI (llmcompressor)에 게시됨, 버전 ≥ 0.13.0.
Red Hat AI 및 vLLM Project가 활발히 유지 관리.
Hugging Face에 호스팅된 많은 프로덕션 준비 체크포인트(GLM‑5.3, Qwen 3.8, Nemotron 3.5, Muse‑Glimmer, Kimi‑K3 등) 제공.
모든 양자화 경로를 다루는 광범위한 예제 스크립트 포함.

🧩 생태계 적합성

llmcompressor는 모델 준비와 런타임 추론 사이에 위치합니다:

입력 – Hugging Face 체크포인트(모든 아키텍처 지원).
처리 – 라이브러리 API를 통한 양자화/가지치기.
출력 – compressed‑tensors 체크포인트.
런타임 – 초고속 서빙을 위해 vLLM으로 체크포인트 로드.

📜 인용

연구나 제품에서 이 라이브러리를 사용하는 경우 다음을 인용하세요:

@software{llmcompressor2024,
    title={{LLM Compressor}},
    author={Red Hat AI and vLLM Project},
    year={2024},
    month={8},
    url={https://github.com/vllm-project/llm-compressor},
}

결론 – llmcompressor는 크고 다루기 힘든 LLM 체크포인트를 vLLM용의 작고 즉시 사용 가능한 아티팩트로 변환하기 위한 프로덕션급의 고도로 최적화된 툴킷으로, 최신 양자화 연구(GPTQ, AWQ, AutoRound, REAP 등)를 지원하며 수천억 파라미터 모델까지 확장 가능합니다.