vLLM 엔진 다이어그램
vLLM V1 엔진의 실행 경로를 개요 한 장과 상세 여섯 장으로 나누어 정리했습니다. 각 페이지는 단독 HTML이며 다크/라이트 테마, 검색·포커스, PNG·SVG 내보내기를 지원합니다.
개요
V1 엔진 실행 흐름
요청이 들어와 토큰이 스트리밍되어 나가기까지, 세 프로세스 경계를 넘나드는 왕복 경로.
- 프론트엔드(P0) · 엔진 코어(P1) · 워커 프로세스
- ZMQ 입출력 소켓과 rpc_broadcast_mq 구간
- schedule → execute_model → update_from_output 순환
엔진 기동 시퀀스
서빙이 시작되기 전까지. 워커 기동부터 KV 캐시 블록 수가 정해지기까지의 호출 순서.
- WorkerProc 기동 → init_device() → load_model()
- profile_run()으로 KV에 쓸 여유 메모리 측정
- 블록 텐서 할당 · 컴파일 · 그래프 캡처
스케줄러 한 스텝
개요의 Scheduler 구간을 확대한 그림. schedule()이 한 스텝에서 토큰 예산을 어떻게 나누는지.
- RUNNING 큐를 먼저, 남은 예산으로 WAITING 큐
- 블록이 모자랄 때의 선점과 재시도 루프
- 프리픽스 캐시 히트와 청크 프리필 상한
Speculative Decoding 순환
draft가 한 스텝에 만들어져 다음 스텝에 검증되는 순환. 제안기 종류와 무관한 공통 골격.
- 지난 draft 검증 → 수락 → 다음 draft 제안
- 거부분만큼 num_computed_tokens 롤백
- num_lookahead_tokens로 KV 자리 선예약
그래프 모드가 갈리는 지점
엔진 전반에서 FULL · PIECEWISE · NONE이 어디서 갈라지는지. 설정 → 백엔드 능력 → 배치별 조회의 세 단계.
- VLLM_COMPILE이 아니면 PIECEWISE 자체가 불가
- 어텐션 백엔드의 min_cg_support가 상한을 결정
- 같은 설정이어도 배치 모양에 따라 매 스텝 재판정
모델 러너 V1/V2 선택
내 설정이면 어느 러너를 쓰는지. use_v2_model_runner의 판정 순서.
- 기본은 V2, V1은 폴백 경로
- HiSparse · 워터마킹은 V2 고정
- 플랫폼 요건과 미지원 기능 확인
CUDA Graph 디스패치
위 흐름의 GPUModelRunner 구간을 확대한 그림. 그래프를 언제 캡처하고 언제 eager로 떨어지는지.
- 기동 1회: 컴파일 · 커널 워밍업 · 그래프 캡처
- 스텝마다: FULL → PIECEWISE → NONE 키 조회
- 드래프터 그래프는 target 모드에서 파생 (V1/V2 다름)
V1 / V2 지원 범위
커밋 dc36fcc 기준. config/vllm.py의 서로 다른 두 함수이고, 걸렸을 때 동작도 다릅니다.
V2가 아직 못 하는 것 → V1로 폴백
- stock torch.compile
- sequence parallelism (TP > 1일 때)
- pipeline parallelism + external_launcher
- ngram / ngram_gpu speculative decoding
- eagle · eagle3 · mtp · dflash · dspark · extract_hidden_states 외의 spec 방식
- EAGLE parallel drafting
- microbatching(DBO)과 겹치는 기능
- elastic expert parallelism
- custom logits processors
- mamba cache mode
all
V1이 못 하는 것 → ValueError
- prefill context parallel
- dspark speculative decoding
- adaptive draft verification
- mixed sliding/full dflash drafts
- dflash2 drafts
- diffusion models
- batch-sharded sampling