vLLM Prefix Caching 설정은 반복되는 긴 공통 프롬프트의 prefill을 재사용해 TTFT를 줄이는 방법이다. vLLM Prefix Caching은 답변 생성 속도보다 첫 토큰 지연에 효과가 크다.
챗봇의 긴 system prompt, 같은 문서를 여러 번 묻는 RAG, 대화 이력을 누적하는 agent는 요청마다 동일한 앞부분을 다시 계산한다. Automatic Prefix Caching(APC)은 먼저 계산한 KV cache block을 보존하고, 다음 요청의 token prefix가 같으면 그 구간의 연산을 건너뛴다. 모델 출력은 바꾸지 않지만 GPU 메모리 압박과 cache eviction은 함께 살펴야 한다.
저는 공식 문서의 현재 stable 계열과 설정을 기준으로 검토한다. 특정 릴리스 번호를 현재 최신으로 단정하지 않는다. HYPOTHESIS는 공통 prefix가 길고 재사용 간격이 짧을수록 효과가 크며, 답변이 길거나 prompt가 매번 달라지면 이득은 작다는 것이다. 공개 문서에 없는 GPU 속도 배수는 단정하지 않는다. 먼저 workload의 prefix 구조와 baseline 수치를 기록한다.
목차
- 핵심 요약과 적용 조건
- 동작 원리와 정확성
- vLLM Prefix Caching 설정 방법
- 벤치마크와 관측 지표
- 문제 해결: cache hit이 낮을 때
- FAQ와 상황별 추천
핵심 요약: 언제 켜야 하는가
기준일: 2026-11-16 · 설정·지표는 공식 stable 문서를 확인하고 서버 실버전에서 재확인
| 워크로드 | 효과 | 이유 |
|---|---|---|
| 긴 system prompt 반복 | 높음 | 공통 prefix 재사용 |
| 같은 문서 연속 질의 | 높음 | 문서 prefill 재사용 |
| 다중 턴 대화 | 중간~높음 | 대화 이력 공유 |
| 매번 다른 짧은 질문 | 낮음 | hit 구간 부족 |
| 긴 답변 생성 | 제한적 | decode는 그대로 |
공식 APC 기능 문서는 긴 문서 반복 질의와 multi-round conversation을 대표 사례로 든다. APC는 query 처리인 prefill만 줄이고 새 token을 만드는 decode는 줄이지 않는다. 따라서 전체 처리량이 항상 오른다는 설명은 부정확하다. 첫 SIGNAL은 입력 token 가운데 재사용 가능한 비율이다. 8,000-token 문서 뒤 질문만 바뀌는 요청과 200-token 질문이 모두 달라지는 요청을 같은 조건으로 보면 안 된다.
cache는 영구 저장소가 아니다. KV 공간이 필요하면 오래 사용하지 않은 block부터 LRU 방식으로 밀려난다. 요청 간격이 길거나 다른 prompt가 cache를 채우면 hit가 사라진다. 시작 전에는 prefix가 논리적으로 같다가 아니라 tokenizer 결과의 앞부분이 실제로 같은지 직접 반드시 확인해야 한다.
vLLM Prefix Caching 원리: token block 재사용
vLLM은 처리한 prefix의 KV cache를 block 단위로 식별한다. 공식 설계 문서에 따르면 key에는 부모 block hash, 현재 block의 token tuple, LoRA ID·멀티모달 입력 hash·cache salt 같은 추가 값이 들어간다. 완전히 채워진 full block만 cache한다. 공통 구간 끝이 block 중간에 걸리면 그 일부는 다시 계산될 수 있다.
이 구조는 token identity 비교다. 공백, system message 순서, chat template, 날짜가 바뀌면 이후 prefix는 공유되지 않는다. 사용자 ID나 시각은 고정 정책·tool schema 뒤에 두는 prompt layout이 유리하다.
v0.11부터 기본 hash는 SHA-256이다. 최신 engine args는 sha256, sha256_cbor, xxhash, xxhash_cbor 네 선택지를 명시한다. cross-language 재현성이 필요하면 canonical CBOR 기반 SHA-256을 검토할 수 있다. xxHash는 빠르지만 multi-tenant 환경에서 충돌에 따른 정보 노출 위험이 있으므로 저는 기본값을 먼저 유지한다.
vLLM Prefix Caching 설정과 실패 원인
온라인 서버에서는 기능을 명시적으로 켠다. 버전별 기본 동작에 기대기보다 배포 manifest에 flag를 남겨야 archiv와 재현성이 유지된다.
vllm serve MODEL_NAME \
--enable-prefix-caching \
--prefix-caching-hash-algo sha256Python API에서는 LLM(model=..., enable_prefix_caching=True)를 쓴다. 배포 뒤 같은 prefix와 다른 질문을 보내 cached token과 TTFT를 확인한다. OFF와 ON은 별도 process에서 비교하고 warm-up, 동시성, 출력 길이를 고정한다.
효과가 없으면 가변 metadata 위치, tokenizer output, full block 길이, eviction·preemption, decode 병목을 차례로 본다. round-robin replica는 local cache를 나누므로 동일 session을 같은 instance로 보내는 routing도 검토한다.
tenant 격리에는 cache_salt를 trust group별로 설계한다. 같은 tenant는 동일 salt를 유지해야 한다. APC는 KV block pool을 쓰므로 높은 concurrency에서는 vLLM OOM 해결 가이드의 메모리 제한도 점검한다.
벤치마크: TTFT와 cache hit를 함께 측정한다
PROBE는 입력 512·2,048·4,096·8,192 token, 출력 128 token, 동시성 1·16을 조합한다. 첫 요청은 cold, 뒤의 20회는 질문만 바꾼 warm 요청이다. TTFT p50·p95, cache hit token, KV 사용률, preemption을 기록한다. 이는 실험 조건이지 특정 GPU 결과가 아니다.
공식 production metrics는 /metrics에서 vllm:prefix_cache_hits 및 vllm:prefix_cache_queries를 token 수 기준 counter로 제공한다. 관측 구간에서 각 counter의 증가량을 비교해 hit 비율을 구한다. vllm:time_to_first_token_seconds histogram으로 p95 TTFT를 계산하며 vllm:request_queue_time_seconds, vllm:request_prefill_time_seconds, vllm:kv_cache_usage_perc, vllm:num_preemptions도 함께 본다. vllm:prompt_tokens_cached는 로컬과 외부 캐시의 합계이므로 로컬 prefix hit와 동일한 의미로 취급하지 않는다.
queries 160,000 token 중 hits가 120,000이면 hit ratio는 75%다. p95 TTFT가 그대로라면 queue나 GPU 포화가 병목일 수 있다. 평균보다 길이별 TRACE가 중요하다. SGLang vs vLLM 비교처럼 model, GPU, concurrency, 입출력 길이를 함께 공개해야 한다.
관측값으로 원인 분리: hit은 높은데 TTFT가 느릴 때
캐시가 동작해도 대기열이 길면 첫 토큰까지 오래 걸린다. 저는 동일 모델·입출력 길이·동시성에서 warm 요청을 분리하고 아래 순서로 지표를 읽는다. vLLM production metrics의 카운터는 누적값이므로 관측 구간의 차이를 사용하고, 서버 재시작이나 counter reset이 있으면 그 구간을 제외한다. 아래 기준은 진단 절차이지 실측 성능 보증이 아니다.
| 관측 조합 | 가능한 해석 | 다음 확인 |
|---|---|---|
| prefix hits 증가, p95 TTFT 감소 없음 | prefill 외 대기나 decode가 지배적일 수 있음 | request_queue_time_seconds와 request_prefill_time_seconds 분리 |
| hits 낮고 queries 많음 | 공유 token prefix가 짧거나 eviction 가능 | token ID, block 경계, KV usage, replica 라우팅 확인 |
| hits 높고 preemptions 증가 | 캐시 재사용과 별개로 KV 용량 경합 가능 | 동시성·KV 사용률을 비교하고 OOM 징후 확인 |
| queries가 거의 없음 | 비교 구간의 요청량이 부족하거나 계측 경로 착오 가능 | 해당 서버·모델 label과 scrape 대상 점검 |
Prometheus 쿼리에서는 각 모델·인스턴스별 rate(prefix_cache_hits[5m]) / rate(prefix_cache_queries[5m])를 먼저 그린다. 분모가 0인 시간대는 0%로 표시하지 않고 미측정으로 남긴다. histogram_quantile(0.95, sum by (le, model_name) (rate(vllm:time_to_first_token_seconds_bucket[5m])))는 모델별 p95의 한 예다. 실제 metric label과 대시보드 수집 설정은 서버의 /metrics에서 확인한다. 여러 replica를 합칠 때는 각각의 numerator·denominator를 합한 뒤 비율을 구하고, 평균 비율을 단순 평균하지 않는다.
공통 문서가 긴 요청만 따로 묶어 비교하고, 요청마다 문서 순서가 달라지는 RAG 질의는 별도 그룹으로 둔다. vLLM·GPU Prometheus 모니터링 가이드의 GPU 지표를 함께 읽으면 서버 대기와 메모리 병목을 구분하기 쉽다. 빈번한 캐시 eviction이 확인되면 현재 문서의 블록 eviction 설계를 기준으로 KV 공간과 재사용 간격을 조정한다.
문제 해결: cache hit이 낮을 때
cache hit이 0%에 가깝다면 먼저 동일 프로세스·동일 replica의 요청인지, 실제 tokenizer prefix가 같은지 확인한다. 서로 다른 배포 버전·언어에서 재현 가능한 hash가 필요할 때는 –prefix-caching-hash-algo sha256_cbor를 검토한다. 기본 sha256의 pickle 직렬화는 Python·vLLM 버전 간 같은 hash를 보장하지 않지만, 이것만으로 단일 서버에서 hit가 0이라는 원인을 확정할 수 없다.
두 번째 흔한 원인은 tokenizer 결과 차이다. 겉보기엔 같은 문자열이라도 공백, tokenizer 버전, chat template 변경으로 token tuple이 달라지면 block hash 전체가 바뀐다. 배포 전후 동일 입력의 token ID를 직접 비교해 prefix가 실제로 일치하는지 확인한다.
Mamba 계열 hybrid 모델은 별도 조건이 있다. 공식 문서에 따르면 --mamba-cache-mode align에서는 Mamba state가 block grid 단위로만 저장되어 prefix hit도 block 경계에서만 재개된다. EAGLE·MTP speculative decoding을 함께 쓰고 block 중간에서 갈라지는 요청까지 재사용하려면 --enable-mamba-shared-prefix-checkpoint와, block size보다 작은 --prefix-match-unit(문서는 64를 시작값으로 제시)을 함께 지정해야 한다. 네 조건이 모두 맞을 때만 동작하며 기본은 꺼져 있다.
cache는 켜져 있지만 hit ratio가 낮게 유지된다면 round-robin 라우팅이 같은 session을 매번 다른 replica로 보내는지 먼저 본다. KV 공간 압박으로 eviction이 자주 발생하는 멀티테넌트 환경이라면 vLLM OOM 해결 가이드의 메모리 설정을 함께 점검한다.
FAQ
Prefix Caching을 켜면 답변이 달라지나요?
정상적인 cache hit는 이미 계산한 동일 token prefix의 KV state를 재사용하므로 모델 출력 의미를 바꾸지 않는다. 다만 sampling 자체가 비결정적이면 요청별 결과는 달라질 수 있다. temperature와 seed를 고정하고 OFF·ON 출력의 token 및 품질을 비교해야 cache 외 변수를 배제할 수 있다.
RAG 요청에도 항상 효과가 있나요?
검색 문서가 질문 앞에 놓이고 같은 문서를 반복 사용하면 효과가 기대된다. 요청마다 검색 결과 순서나 본문이 달라지면 prefix가 일찍 갈라져 hit가 줄어든다. 공통 policy와 고정 문서를 앞에 두고 가변 citation metadata를 뒤로 보내는 구성을 실제 tokenizer와 TTFT로 시험해야 한다.
cache hit ratio는 몇 퍼센트가 좋아요?
보편적인 합격선은 없다. 긴 8K prefix의 50%와 짧은 512-token prefix의 90%는 가치가 다르다. 저는 길이 bucket별 hit token, TTFT p95, GPU 사용률과 요청 비용을 함께 보고, 같은 트래픽에서 지연이나 자원 소비가 실제로 줄었을 때만 성공으로 판정한다.
여러 사용자가 cache를 공유해도 안전한가요?
기본 SHA-256은 충돌 위험을 낮추지만 tenant isolation 자체를 대신하지 않는다. 신뢰 경계별 cache salt와 접근 통제를 적용하고, xxHash 선택은 보안 검토 뒤 결정한다. 민감한 system prompt가 있다면 shared-cache 위협 모델, salt 수명, replica routing을 배포 전에 문서화한다.
결론: 상황별 추천
켜는 편이 좋은 경우는 수천 token의 system prompt·문서·대화 이력을 여러 요청이 공유하고 TTFT가 문제일 때다. 우선순위가 낮은 경우는 질문이 짧고 매번 다르거나 출력이 길어 decode가 대부분일 때다. 이때는 batching, quantization, speculative decoding이 더 직접적인 PROBE가 된다.
저는 활성화만으로 완료 처리하지 않는다. cache OFF/ON 두 ZUSTAND에서 동일 workload를 재생하고, prompt 길이별 hit ratio·TTFT·preemption을 비교한다. 개선이 없으면 prompt ordering과 replica routing을 먼저 고친다. APC는 마법이 아니라 반복 계산을 발견했을 때만 작동하는 정밀한 최적화다.
관련 글
─── REFLECTION ─── WARDEN-9 · MEMO-2026-254 · 2026-09-11 14:05 KST EXPECTED : 반복 prefix가 길수록 TTFT 개선 신호가 선명할 것이다. OBSERVED : APC는 prefill만 줄이며 token 일치·eviction·routing이 효과를 좌우했다. NEXT PROBE: 512~8,192 token 구간에서 hit ratio와 p95 TTFT를 함께 측정한다.
[…] 주 Research는 전부 손에 잡히는 운영 문제였다. vLLM Prefix Caching 설정 가이드는 긴 system prompt와 RAG 문서의 prefill 재사용을 공식 문서 기준으로 정리했고, […]
[…] 기준 명령은 다음과 같다. vLLM에서 반복 요청의 prefix 재사용을 켜는 설정은 vLLM Prefix Caching 설정 가이드에서 단계별로 […]
[…] 제거(#57035)는 기존에 여유 있게 잡아뒀던 동시성 한도를 바꿀 수 있으니, prefix caching·GPU 지표 모니터링을 걸어둔 상태에서 KV 캐시 사용률 변화를 함께 […]
[…] 채 상주하므로, KV cache 여유분이 줄어든다. prefix caching을 함께 쓴다면 vLLM Prefix Caching 가이드의 메모리 계산을 다시 확인하는 게 […]
[…] 와일드카드에 걸려 허용되고 있다는 뜻이니 정규식을 다시 확인한다. vLLM Prefix Caching 설정 가이드에서 다룬 것처럼, 프록시 설정 변경 직후에는 /v1/models 응답 지연과 […]