vLLM 내부 해부: 고처리량 LLM 추론 시스템의 구조

TL;DR Highlight

vLLM 엔진의 스케줄러·KV 캐시·prefix caching 구조를 한 번에 정리한 글

Who Should Read

vLLM으로 LLM을 직접 서빙하면서 처리량·지연 시간 튜닝의 원리가 궁금한 백엔드 개발자

Core Mechanics

엔진은 스케줄러와 KV 캐시 관리자가 핵심
- vLLM 엔진 코어는 Model Executor, Structured Output Manager, Scheduler로 구성된다.
- 스케줄러는 FCFS 또는 우선순위 정책과 waiting·running 큐를 가진다.
- KV 캐시 관리자는 paged attention의 핵심이다.
매 step은 스케줄, 순전파, 후처리 3단계
- 스케줄 단계에서 이번 step에 돌릴 요청(decode, 청크 prefill)을 고른다.
- 순전파 단계에서 모델을 돌려 토큰을 샘플링한다.
- 후처리 단계에서 토큰을 붙이고 종료 조건을 확인한 뒤 끝난 요청의 KV 블록을 반환한다.
V1 스케줄러는 prefill과 decode를 한 step에 섞는다
- V0 엔진은 step마다 prefill 또는 decode 중 하나만 처리할 수 있었다.
- 스케줄러는 running 큐의 decode 요청을 먼저 처리하고 그다음 waiting 큐의 prefill을 처리한다.
- prefill은 대체로 compute-bound, decode는 memory-bandwidth-bound다.
Chunked prefill로 긴 프롬프트의 독점을 막는다
- 긴 프롬프트의 prefill을 작은 청크로 쪼개 여러 step에 나눠 돌린다.
- 쪼개지 않으면 긴 요청 하나가 step을 독점해 다른 요청의 지연이 늘어난다.

Community Reactions

nano-vllm 코드를 읽으면 이해가 쉽다는 의견
- 약 5kloc에 모델 하나만 지원하는 축소판이라고 한다.
- 추론 엔진을 빠르게 만드는 핵심 요소는 모두 들어 있다고 한다.
Radix Attention과 비교가 궁금하다는 질문
- 글이 paged attention을 넘어 다룬다는 점이 좋다는 반응과 함께 나왔다.
paged attention보다 다른 요소가 더 중요했다는 의견
- 웹 서버와 GPU 프로세스 분리, continuous batching, KV 캐싱·청킹, 저정밀도를 포함한 대형 모델 라이브러리가 더 중요했다는 평가다.

How to Apply

prefix caching이 먹히게 프롬프트 앞부분 고정하기
- 오늘 vLLM 서비스의 프롬프트에서 시스템 프롬프트와 공통 문맥을 맨 앞에 두고 요청별 내용은 뒤에 붙여라.
- 앞부분이 16토큰 블록 단위로 일치해야 재사용되므로 공통 부분 앞에 요청마다 달라지는 값을 넣지 마라.
긴 프롬프트가 많으면 chunked prefill 설정 켜기
- 긴 요청 때문에 다른 요청 지연이 튀면 long_prefill_token_threshold를 양수로 설정해 비교 측정하라.
멀티테넌트면 cache salt 쓰기
- 사용자 간 KV 블록 재사용을 막아야 하면 요청에 cache salt를 넣어라.
- 첫 블록 해시에 salt가 들어가 같은 salt의 요청만 블록을 재사용한다.
디버깅할 땐 --enforce-eager로 CUDA graph 끄기
- 그래프 캡처 영향을 배제하고 싶을 때만 켜고, 평소 지연 시간 측정은 끄지 않은 상태로 해라.

Try It

복사해서 바로 해보기

# Claude 또는 ChatGPT 채팅창에 붙여넣기 (글의 prefix caching 개념을 내 서비스에 적용하는 점검 프롬프트)

나는 vLLM으로 LLM을 서빙한다. vLLM은 prefix caching(기본 켜짐)으로 16토큰 블록 단위 해시가 같은 앞부분의 KV 캐시를 재사용한다. 이 캐시는 prefill만 빠르게 하고 decode는 빠르게 하지 않는다.

아래는 우리 서비스의 프롬프트 템플릿이다.
{{프롬프트 템플릿}}

이 템플릿에서 요청마다 달라지는 부분과 항상 같은 부분을 구분해 줘. 같은 부분이 앞에 오도록 순서를 바꾼 템플릿을 제시하고, 어떤 변경이 캐시 재사용을 깨는지 설명해 줘.

이어서 해 볼 것: 바꾼 템플릿으로 같은 요청을 두 번 보내 첫 토큰까지 걸리는 시간을 비교해 봐라.

Terminology

Paged attentionKV 캐시를 고정 크기 블록으로 나눠 운영체제의 페이지처럼 관리하는 방식이다. 블록이 토큰과 계산된 KV를 이어주는 색인 역할을 한다.

Continuous batching한 번 정한 배치를 끝까지 돌리지 않고 step마다 새 요청과 기존 요청을 다시 고려하는 방식이다. 식당에서 빈자리가 나면 바로 다음 손님을 앉히는 것과 비슷하다.

Prefill / Decodeprefill은 프롬프트 전체를 한 번에 처리하는 단계이고, decode는 최신 토큰 하나만 처리해 다음 토큰을 만드는 단계다.

KV cache이미 계산한 토큰의 key/value 벡터를 저장해 둔 것이다. 매번 처음부터 다시 계산하지 않게 해 준다.

CUDA graphGPU 작업 순서를 통째로 녹화해 두었다가 재생하는 기능이다. 커널을 하나씩 실행할 때 드는 오버헤드를 줄인다.