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

vLLM이란

vLLM은 UC Berkeley Sky Computing Lab에서 시작된 LLM 추론/서빙 오픈소스 프로젝트다. "Easy, fast, and cheap LLM serving for everyone"을 목표로 하며, 2000명 이상의 기여자가 참여하고 있다.

핵심 논문: Efficient Memory Management for Large Language Model Serving with PagedAttention (SOSP 2023)

전체 아키텍처

 ┌──────────────────────────────────────────────────────────────────────────┐
 │                        클라이언트 (HTTP/SDK)                              │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  1. Entry Point                         vllm/entrypoints/               │
 │     OpenAI API Server / Anthropic API / Offline LLM / gRPC              │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  2. Engine                              vllm/v1/engine/                 │
 │     AsyncLLM ─→ InputProcessor ─→ EngineCoreClient (ZMQ IPC)           │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  3. Engine Core                         vllm/v1/engine/core.py          │
 │       ┌─────────────┐   ┌──────────────┐   ┌────────────────────┐      │
 │       │  Scheduler   │──▶│   Executor   │──▶│ update_from_output │      │
 │       └──────┬───────┘   └──────┬───────┘   └────────────────────┘      │
 │              │                  │                                        │
 │              ▼                  │                                        │
 │  ┌─────────────────────┐       │                                        │
 │  │ 4. KV Cache Manager │       │                                        │
 │  └─────────────────────┘       │                                        │
 └────────────────────────────────┼────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  5. Executor → 6. Worker → 7. Model Runner                             │
 │     ┌─────────────────────────────────────────────────────────┐         │
 │     │  8. Attention Backends  │  9. Model Layers              │         │
 │     └─────────────────────────────────────────────────────────┘         │
 │     OUTPUT: logits                                                      │
 └────────────────────────────────┬─────────────────────────────────────────┘
                                  │
                                  ▼
 ┌──────────────────────────────────────────────────────────────────────────┐
 │  10. Sampler + Speculative Decoding → OutputProcessor → 클라이언트       │
 └──────────────────────────────────────────────────────────────────────────┘

 ┌──────────────────────────────────────────────────────────────────────────┐
 │  11. Distributed (횡단 관심사) — TP/PP/EP/CP, KV Transfer               │
 └──────────────────────────────────────────────────────────────────────────┘

시리즈 목차

1. Entry Point (진입점)

• OpenAI 호환 API 서버 — FastAPI 기반 OpenAI 호환 HTTP 서버
• 오프라인 LLM API — 배치 추론용 동기 Python API
• Pooling Tasks — 임베딩, 분류, 스코어링/리랭킹
• Speech-to-Text — 음성 인식 API

2. Engine (엔진)

• AsyncLLM — 비동기 엔진의 최상위 객체
• InputProcessor — 입력 전처리 파이프라인
• OutputProcessor — 출력 후처리 및 디토크나이징
• EngineCore — 핵심 실행 루프
• Renderer & Tokenizer — 모델별 입력 파이프라인 및 토크나이저

3. Scheduler (스케줄러)

• Continuous Batching — 동적 요청 배칭
• Chunked Prefill — 긴 프롬프트 분할 처리
• Preemption & Async Scheduling — 선점과 비동기 스케줄링

4. KV Cache Manager (KV 캐시 관리)

• PagedAttention — 페이징 기반 KV 캐시 관리
• Automatic Prefix Caching — 자동 접두사 캐싱
• KV Cache Offloading — GPU→CPU KV 캐시 오프로딩
• KV Cache Quantization — KV 캐시 FP8/INT8 양자화
• KV Cache Coordinator — 하이브리드 캐시 조율

5. Executor (실행기)

• Executor 아키텍처 — UniProc, Multiproc, Ray 실행기
• Tensor Parallelism — 텐서 병렬화
• Pipeline Parallelism — 파이프라인 병렬화

6. Worker (워커)

• GPU Worker & InputBatch — GPU 워커와 입력 배치 관리
• CPU/XPU Worker — 비NVIDIA 하드웨어 워커

7. Model Runner (모델 실행)

• GPUModelRunner — GPU 모델 포워드 패스
• Model Loader — 모델 가중치 로딩
• torch.compile 통합 — PyTorch 컴파일러 통합
• CUDA Graphs — CUDA 그래프 캡처/재생
• Compilation Fusion Passes — 컴파일 퓨전 최적화
• Model Weight Offloading — 가중치 CPU 오프로딩
• Warmup — 커널 JIT 사전 컴파일

8. Attention Backends (어텐션 백엔드)

• FlashAttention — IO-aware 타일링 어텐션
• FlashInfer — LLM 서빙 특화 어텐션 엔진
• Multi-head Latent Attention (MLA) — KV 캐시 압축 어텐션
• Mamba (SSM) — 선형 시간 복잡도 시퀀스 모델링
• Tree Attention — 투기적 디코딩용 트리 어텐션
• Lightning & Linear Attention — 선형 어텐션 구현
• GDN & FLA — Gated Delta Net, Flash Linear Attention
• 기타 백엔드 — Flex, Triton, DiffKV, MLA Sparse, CPU/ROCm

9. Model Layers (모델 계층)

양자화 (Quantization)

• GPTQ — 2차 정보 기반 후훈련 양자화
• AWQ — 활성화 인식 가중치 양자화
• FP8 — 8비트 부동소수점 양자화
• MXFP8/MXFP4 — 마이크로스케일링 포맷
• BitsAndBytes (QLoRA) — 4비트 NormalFloat 양자화
• Marlin Kernels — 양자화 고속 GEMM 커널
• GGUF — llama.cpp 양자화 포맷
• Compressed Tensors — 양자화+희소성 통합 프레임워크
• 기타 양자화 — NVFP4, Online FP8, INC, ModelOpt, TorchAO, Quark

MoE (전문가 혼합)

• Fused MoE 기본 구조 — 라우팅+전문가 연산 융합
• MoE 라우팅 전략 — 7종 라우팅 알고리즘
• MoE Oracle & Prepare/Finalize — 백엔드 자동 선택과 분산 데이터 교환
• Shared Experts — 공유 전문가 레이어

LoRA & 위치 인코딩

• LoRA (Multi-LoRA Serving) — 저차원 어댑터 서빙
• RoPE 변형 — 15+ 로타리 위치 인코딩 변형

기타 레이어

• 기타 Model Layers — Sparse Attention, KDA, Batch Invariant, Pooler, Resampler

10. Sampler & Speculative Decoding (샘플러 & 투기적 디코딩)

• Sampler — logits에서 토큰 샘플링
• Sampling Parameters — 샘플링 파라미터 전체 정리
• Beam Search — 빔 서치 디코딩
• Structured Output — JSON/regex/문법 제약 생성
• Speculative Decoding 개요 — 투기적 디코딩 원리
• EAGLE — 은닉 상태 기반 드래프트
• Medusa — 다중 예측 헤드 투기적 디코딩
• N-gram & Suffix Decoding — 모델 프리 드래프트
• MTP & DFlash — 다중 토큰 예측, Flash 기반 드래프팅

11. Distributed (분산 시스템)

• Expert Parallelism — 전문가 병렬화
• EPLB — 전문가 부하 균형
• Context Parallelism — 컨텍스트 병렬화
• Disaggregated Prefill/Decode — 분리된 서빙
• KV Transfer Connectors — KV 캐시 전송 프레임워크

부록

• Reasoning & Tool Calling — 추론 파서, 도구 호출 파서
• Multimodal — Vision, Audio, Video 처리
• Sleep Mode — GPU 메모리 동적 관리
• Observability — 추적, 프로파일링, 메트릭
• Plugin & Hardware — 플러그인 시스템, 하드웨어 플랫폼

핵심 데이터 흐름

EngineInput → EngineCoreRequest → SchedulerOutput → ModelRunnerOutput → SamplerOutput → EngineCoreOutput → RequestOutput

단계	데이터 구조	위치
입력	EngineCoreRequest	vllm/v1/engine/__init__.py
스케줄링 결과	SchedulerOutput	vllm/v1/core/sched/output.py
모델 출력	ModelRunnerOutput	vllm/v1/outputs.py
샘플링 결과	SamplerOutput	vllm/v1/outputs.py
최종 출력	RequestOutput	vllm/outputs.py

참고 자료

• vLLM 공식 문서
• vLLM GitHub
• vLLM 핵심 논문 (PagedAttention)
• vLLM 블로그