vLLM 지연을 TTFT·TPOT·KV 캐시로 나눠 진단하는 법

AI를 활용하여 생성한 이미지입니다.

vLLM 서버가 느려졌을 때 GPU 사용률만 보면 원인을 놓치기 쉬워요. 요청이 큐에서 오래 기다리는지, 첫 토큰이 늦는지, 토큰 사이 간격이 벌어지는지, KV 캐시가 한계에 가까운지에 따라 조치가 달라집니다. vLLM은 OpenAI 호환 API 서버의 /metrics 엔드포인트에 Prometheus 형식의 지표를 내보내므로, 로그 몇 줄보다 먼저 관측 항목을 고정하는 편이 좋습니다.[1]

먼저 네 가지 시간을 나눠요

vLLM 문서는 TTFT, inter-token latency, 요청별 TPOT, 전체 요청 지연을 서로 다른 히스토그램으로 제공합니다. 특히 TPOT와 inter-token latency는 같은 값이 아니므로, 어떤 사용자 경험을 측정할지 먼저 정해야 해요.[2]

1. /metrics를 읽는 최소 구성

서버를 실행한 뒤 Prometheus가 연결되어 있다면 다음처럼 엔드포인트를 확인할 수 있어요.

curl http://127.0.0.1:8000/metrics | grep '^vllm:'

실제 운영에서는 원문 전체를 화면에 뿌리기보다 필요한 지표만 수집하세요. 기본 대시보드에는 vllm:num_requests_running, vllm:num_requests_waiting, vllm:kv_cache_usage_perc, vllm:time_to_first_token_seconds, vllm:request_time_per_output_token_seconds, vllm:e2e_request_latency_seconds를 우선 넣을 만합니다.[1]

Counter는 시간이 지나며 누적되고, Gauge는 현재 상태를 나타내며, Histogram은 구간별 분포를 보여줘요. 누적 토큰 수를 평균 지연처럼 읽거나, 순간 GPU 사용률 하나로 전체 요청 품질을 판단하면 안 됩니다.[2]

2. 큐가 길 때와 생성이 느릴 때

num_requests_waiting이 오르고 TTFT도 함께 나빠지면 요청이 실행되기 전부터 밀리고 있을 가능성이 큽니다. 이때 무조건 GPU 메모리를 더 쓰도록 설정하기보다, 동시 요청 수·입력 길이·최대 출력 토큰을 먼저 확인하세요. 긴 프롬프트가 한꺼번에 들어오면 프리필이 다른 요청의 첫 토큰을 늦출 수 있어요.

반대로 대기열은 짧은데 TPOT와 inter-token latency가 높다면 디코드 단계나 동시성 문제가 더 가까울 수 있습니다. 생성 길이를 줄인 요청과 긴 요청을 나눠 비교하고, 스트리밍을 켠 요청과 비스트리밍 요청을 같은 지표로 섞지 마세요. 사용자 체감은 첫 토큰과 토큰 간격에 민감하고, 전체 완료 시간은 출력 길이에 크게 좌우됩니다.

3. KV 캐시를 성능 원인으로 연결하기

kv_cache_usage_perc는 KV 캐시 블록 사용 비율을 보여주는 Gauge예요. 값이 계속 높고 대기 요청이 함께 늘면, 단순히 GPU 코어가 바쁘다는 문제보다 컨텍스트와 동시 요청이 캐시 용량을 압박하는 상황일 수 있습니다.[1]

이때 먼저 확인할 항목은 요청의 입력 토큰 수, 최대 생성 토큰, 동시성, 접두사 캐시 사용 여부입니다. 같은 시스템 프롬프트를 반복하는 업무라면 prefix cache hit와 query를 함께 모아 실제 재사용이 있는지 보세요. vLLM은 prefix cache query와 hit를 Counter로 제공하므로, 히트 수가 많다는 말보다 쿼리 대비 히트 비율을 시간대별로 계산하는 편이 유용합니다.[2]

rate(vllm:prefix_cache_hits[5m])
/
rate(vllm:prefix_cache_queries[5m])

캐시 사용량이 낮은데 TTFT만 높다면 캐시를 늘리는 것이 답이 아닐 수 있어요. 프롬프트 토큰 수, 큐 시간, 네트워크 구간을 따로 보면서 원인을 좁혀야 합니다.

4. 대시보드에서 섞지 말아야 할 것

모델이 여러 개라면 모든 지표를 하나의 평균으로 합치지 마세요. vLLM은 메트릭에 모델 이름 라벨을 붙일 수 있으므로 모델별로 TTFT와 TPOT를 분리해 보관하는 구성이 안전합니다.[2] 짧은 출력 모델과 긴 출력 모델의 E2E 지연을 합치면 어느 쪽이 느려졌는지 가려집니다.

또한 요청이 한 토큰만 생성하면 TPOT가 0으로 기록될 수 있고, 벤치마크 도구가 계산하는 TPOT와 Prometheus 히스토그램의 모집단이 다를 수 있어요. 숫자가 다를 때 어느 쪽이 틀렸다고 결론내리기보다 측정 정의와 표본을 맞추세요.[2]

운영 점검 체크리스트

• 모델별로 실행·대기 요청 수를 분리해 보기
• TTFT·TPOT·inter-token latency·E2E를 다른 지표로 저장하기
• KV 캐시 사용률과 대기열 변화를 같은 시간축에서 비교하기
• prefix cache query 대비 hit 비율을 계산하기
• 한 토큰 응답과 긴 응답의 TPOT 표본을 따로 보기
• 설정 변경 뒤 동일한 프롬프트·동시성 조건으로 재측정하기

로컬 모델을 직접 운영하면서 도구 호출의 재시도와 병렬 실행까지 설계한다면 AI 에이전트 도구 호출의 멱등성·재시도·병렬화 기준도 함께 읽어 보세요. 서버 지표와 에이전트 작업 실패를 같은 문제로 섞지 않는 데 도움이 됩니다.

Sources

• [1] vLLM, Production Metrics
• [2] vLLM, Metrics design