vLLM을 실제 서비스 환경에 배포하다 보면 다음과 같은 에러를 마주하게 됨
🚫 ValueError: No available memory for the cache blocks.
🚫 KV cache is needed, which is larger than the available KV cache memory.이 에러는 단순한 메모리 부족이 아니라, vLLM이 내부적으로 사용하는 KV Cache 영역이 부족해서 발생하는 것.
max-model-len 이란?
한 번의 요청에서 입력 (prompt) + 출력 (response) 토큰의 최대 길이
예를들어, max-model-len=8191 일 경우, 모델은 한 번에 최대 8192의 토큰을 처리할 수 있음
| 토큰 수 | 의미 |
|---|---|
| 8192 tokens | 약 6000 단어 ≒ A4 문서 12~15장 분량 |
| 16384 tokens | 논문 요약, 긴 대화 세션 등 |
| 40960 tokens | 거의 책 한 챕터 분량 |
gpu-memory-utilization 이란?
전체 GPU 메모리 중 vLLM이 사용할 수 있는 비율(%)을 설정
예시:
--gpu-memory-utilization 0.7→ GPU의 70%만 사용하겠다는 의미
이 안에서 다음 요소들이 메모리를 공유한다.
- 모델 자체의 파라미터 로딩
Torch compile (선택저) - KV Cache 공간
메모리 에러가 발생하는 이유
max-model-len ↑ ⇒ KV Cache 메모리 ↑
gpu-memory-utilization ↓ ⇒ 사용할 수 있는 총 메모리 ↓
→ 결국 KV Cache가 들어갈 공간이 부족해짐
→ 실행 중단 또는 배포 실패
예시 : H100 80GB 기준
| 항목 | 설명 |
|---|---|
gpu-memory-utilization=0.6 | 사용 가능 메모리: 48GB |
| 모델 로딩 + Torch Compile | 약 35~40GB 소모 |
| 남는 공간 | 8~13GB → 이게 KV Cache 영역 |
max-model-len=40960 | KV Cache가 2.2GB 이상 필요 |
| 두 인스턴스 실행 | 총합 4.4GB+ 필요 → 공간 부족 가능성 매우 큼 |
실전 배포 전략
1. max-model-len 은 8192 ~ 16384 사이로 절충
- 일상적인 대화, 문서 요약 등에는 충분
- 너무 높게 설정하면 멀티 인스터싱 불가
권장
--max-model-len 8192
# 또는
--max-model-len 163842. gpu-memory-utilization은 최소 0.6 이상 확보
너무 낮으면 KV 캐시 공간이 부족
- H100 기준: 0.7 ~ 0.85가 적절
- 인스턴스 수에 따라 비율 조정
*단, 단일 인스턴스일 경우
*멀티 인스턴스 운영 혹은 동시 요청이 많을 경우에는 아닐 수도 있다.
3. 병렬 인스턴스 실행 시 총합 1.0 넘지 않게
# 예: 두 인스턴스를 띄운다면
--gpu-memory-utilization 0.45 # x2 = 0.9- 동시에 요청이 많이 들어온다면 더 줄여야 함 (예: 0.4 이하)
- 여러 vLLM worker 배포 시에도 동일한 원칙 적용
4. 클라이언트 요청에서 max_tokens 제한
예측 응답 길이를 제한해서 KV 캐시 폭주 방지
끄적끄적