[llm-compressor] 프로젝트 전체 아키텍처 분석 - 개요 및 목차

llm-compressor란

llm-compressor는 vLLM 프로젝트에서 관리하는 LLM 후훈련 압축(Post-Training Compression) 프레임워크이다. HuggingFace transformers 모델을 입력으로 받아, 양자화(Quantization), 가지치기(Pruning), 변환(Transform) 등 다양한 알고리즘을 "레시피(Recipe)" 기반으로 조합해 적용한 뒤, compressed-tensors 포맷의 체크포인트로 저장한다. 저장된 체크포인트는 vLLM이나 SGLang 같은 추론 엔진에서 그대로 로딩해 가속 추론에 활용할 수 있다.

llm-compressor의 설계 철학은 다음 세 가지로 요약할 수 있다.

1. 알고리즘을 Modifier라는 단위로 추상화한다. GPTQ, AWQ, SmoothQuant, SparseGPT, Wanda, AutoRound, QuIP, SpinQuant 등 서로 다른 논문 구현이 동일한 Modifier 인터페이스를 구현한다.
2. Recipe라는 선언적 DSL로 Modifier를 조합한다. YAML 또는 Python 리스트 형태로 "어느 레이어에 어떤 Modifier를 어느 순서로 적용할지"를 기술한다.
3. Pipeline이 실제 실행 방식을 결정한다. 데이터가 필요 없는(data_free) 레시피는 한 번에, 캘리브레이션 데이터가 필요한 레시피는 레이어를 순차적으로 돌면서(sequential) 실행된다.

이 시리즈는 llm-compressor의 전체 아키텍처를 11개 계층으로 분해하고, 논문 구현 8편을 포함한 45개의 포스트로 코드를 분석한다. vLLM과 SGLang 시리즈가 "추론" 관점에서 LLM 서빙을 해부했다면, 이 시리즈는 "모델 준비" 관점에서 LLM 압축 파이프라인을 해부한다.

• 레포: vllm-project/llm-compressor
• 공식 문서: llm-compressor README
• 관련 포맷: compressed-tensors — vLLM이 로딩할 체크포인트 포맷

전체 아키텍처

 ┌──────────────────────────────────────────────────────────────────────────┐
 │  HuggingFace Model + Calibration Dataset (옵션)                          │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  1. Entrypoints                         src/llmcompressor/entrypoints/  │
 │     oneshot() / model_free                                               │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  2. Args & Recipe DSL                   src/llmcompressor/{args,recipe}/ │
 │     ModelArguments / DatasetArguments / RecipeArguments / Recipe YAML    │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  3. Core / Session                      src/llmcompressor/core/         │
 │     CompressionSession ─→ Lifecycle ─→ State ─→ EventBroadcaster        │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  4. Pipelines                           src/llmcompressor/pipelines/    │
 │     registry → basic / sequential / data_free / independent             │
 │                              │                                           │
 │                              ▼                                           │
 │  5. Modifiers                           src/llmcompressor/modifiers/    │
 │     ┌──────────────────┬─────────────┬─────────────────┐                │
 │     │ Quantization     │ Pruning     │ Transform       │                │
 │     │ (GPTQ/AWQ/SQ/AR) │ (SGPT/Wanda)│ (QuIP/Spin/iMat)│                │
 │     └─────────┬────────┴──────┬──────┴────────┬────────┘                │
 │               │               │               │                         │
 │               ▼               ▼               ▼                         │
 │  6. Observers                            src/llmcompressor/observers/   │
 │     min_max / mse / moving_base / imatrix                                │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  7. Modeling Overrides                  src/llmcompressor/modeling/     │
 │     DeepSeek-V3 / Llama4 / Qwen3-MoE / GPT-OSS / Gemma4 등              │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  8. Transformers Integration            src/llmcompressor/transformers/ │
 │     tracing / compression save / data loaders (c4, wikitext, ...)       │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  Compressed checkpoint → vLLM / SGLang 로딩 → 가속 추론                 │
 └──────────────────────────────────────────────────────────────────────────┘

왼쪽 경로는 "선언" 영역, 가운데 경로는 "실행" 영역, 오른쪽 끝은 "출력" 영역이다. vLLM/SGLang 시리즈와 달리 llm-compressor는 한 번 실행되고 끝나는 오프라인 파이프라인이므로, 모든 계층이 oneshot() 한 번의 호출 안에서 한 방향으로 흐른다.

시리즈 목차

1. Entrypoints (진입점)

• Oneshot 진입점 — oneshot() 함수의 인자 해석과 실행 흐름
• Model-Free Entrypoint — safetensors 파일만으로 압축을 수행하는 경로

2. Args & Recipe DSL (선언 계층)

• Args Dataclasses — ModelArguments / DatasetArguments / RecipeArguments
• Recipe DSL — YAML/Python 레시피 파싱과 Modifier 조합
• Recipe Metadata — 레시피 해시, 버전 관리, 상태 직렬화

3. Core / Session (실행 엔진)

• CompressionSession — 전역 세션과 API 진입점
• Lifecycle — Initialized → Finalized 상태 머신
• State & ModelLayer — 상태 저장소와 레이어 참조
• Events — BatchStart / ModifierStart 등 이벤트 브로드캐스트

4. Pipelines (실행 파이프라인)

• Pipeline Registry — Modifier → Pipeline 자동 라우팅
• Basic Pipeline — 단일 forward로 전체 캘리브레이션 처리
• Sequential Pipeline — 레이어 단위 분할 forward, GPTQ/SparseGPT 전용
• Data-Free Pipeline — 데이터 없이 실행되는 Modifier 전용
• Intermediates Cache — 레이어 중간 활성화 오프로딩 캐시

5. Modifier 프레임워크

• Modifier Base — 모든 Modifier의 베이스 클래스
• Modifier Factory — 문자열 이름에서 클래스 인스턴스 생성
• Modifier Interface — on_initialize / on_event / on_finalize 인터페이스

6. Quantization Modifiers

• Quantization Base — QuantizationModifier와 QuantizationMixin
• Quantization Calibration — Observer 등록과 스케일/제로포인트 수집
• Group Size Validation — 그룹 크기 호환성 검사
• GPTQ — 2차 정보 기반 후훈련 양자화 (논문)
• AWQ — 활성화 인식 가중치 양자화 (논문)
• SmoothQuant — 활성화→가중치 난이도 이동 (논문)
• AutoRound — 부호 경사로 라운딩 최적화 (논문)
• Logarithmic Equalization — 로그 스케일 균등화 변형

7. Pruning Modifiers

• Pruning Overview — OBCQ/SparseGPT 계열 구조
• SparseGPT — 원샷 대규모 모델 가지치기 (논문)
• Wanda — 활성화 가중 노름 기반 가지치기 (논문)
• Magnitude Pruning — 크기 기반·상수 희소성 Modifier

8. Transform Modifiers

• Transform Overview — 가중치 회전/변환 기반 Modifier 계열
• QuIP — 랜덤 직교 변환 기반 2비트 양자화 (논문)
• SpinQuant — 학습된 회전 행렬 기반 양자화 (논문)
• iMatrix Transform — 중요도 행렬 기반 가중치 리스케일

9. Observers

• Observers Base — 스케일/제로포인트 계산의 기본 인터페이스
• MinMax Observer — 단순 최대·최소 기반 스케일
• MSE Observer — 평균제곱오차 최소화 스케일
• Moving Average Observer — 이동 평균 기반 온라인 관측
• iMatrix Observer — 중요도 행렬 관측기

10. HuggingFace Integration

• Transformers Tracing — 모델 그래프 추적과 부분 forward
• Compression Save — compressed-tensors 체크포인트 저장
• Modeling Overrides — DeepSeek/Llama4/Qwen3 등 모델별 패치
• Dataset Calibration — c4/wikitext/ultrachat 등 캘리브레이션 데이터 로더

11. 부록

• PyTorch Utils — 희소화 통계, 모듈 헬퍼
• Sentinel & Typing — 센티넬 객체와 타입 별칭

핵심 데이터 흐름

llm-compressor의 데이터 흐름은 Recipe → Modifier 리스트 → Pipeline 실행 → Observer 수집 → 체크포인트 저장의 단방향이다.

 Recipe (YAML/Python)
      │
      ▼
 RecipeArguments → Modifier 인스턴스 리스트
      │
      ▼
 CompressionSession.initialize()
      │  ├─ State 준비 (model, calibration_data)
      │  └─ Lifecycle(Modifier 목록).initialize() → on_initialize 훅
      ▼
 Pipeline.run()
      │  ├─ [basic]      한 번의 forward로 모든 Modifier 데이터 수집
      │  ├─ [sequential] 레이어 단위로 forward → GPTQ/SparseGPT 호출 → 다음 레이어
      │  └─ [data_free]  forward 없이 Modifier의 변환만 적용
      ▼
 Lifecycle.finalize() → Modifier.on_finalize() → 가중치 최종화
      │
      ▼
 compressed-tensors 체크포인트 저장

단계	데이터 구조	위치
입력	ModelArguments, DatasetArguments, RecipeArguments	src/llmcompressor/args/
레시피	Recipe	src/llmcompressor/recipe/recipe.py
세션	CompressionSession, State	src/llmcompressor/core/
실행 단위	Modifier	src/llmcompressor/modifiers/modifier.py
실행 정책	Pipeline + registry	src/llmcompressor/pipelines/
관측	Observer	src/llmcompressor/observers/
출력	compressed-tensors	src/llmcompressor/transformers/compression/

이 시리즈의 읽는 순서 제안

1. 처음 접한다면: Oneshot → Recipe DSL → CompressionSession 순서로 읽어 "한 번의 호출이 어떻게 흘러가는지" 감을 잡는다.
2. 양자화 알고리즘이 궁금하다면: Quantization Base → GPTQ / AWQ / SmoothQuant 순서로 각 논문 구현을 비교한다.
3. 왜 GPTQ는 sequential pipeline만 쓰는지 궁금하다면: Sequential Pipeline → Intermediates Cache → GPTQ 순서로 읽는다.
4. 가지치기 알고리즘에 관심이 있다면: Pruning Overview → SparseGPT → Wanda 순서로 읽는다.
5. 2비트 양자화에 관심이 있다면: Transform Overview → QuIP → SpinQuant 순서로 읽는다.

참고 자료

• 공식 레포: vllm-project/llm-compressor
• README: README.md
• 예제: examples/
• 관련 엔진: vLLM architecture overview, SGLang architecture overview
• 관련 포맷: vLLM Compressed Tensors
• 핵심 논문(구현된 것):
  • GPTQ (arXiv:2210.17323)
  • AWQ (arXiv:2306.00978)
  • SmoothQuant (arXiv:2211.10438)
  • AutoRound (arXiv:2309.05516)
  • SparseGPT (arXiv:2301.00774)
  • Wanda (arXiv:2306.11695)
  • QuIP (arXiv:2307.13304)
  • SpinQuant (arXiv:2405.16406)