GPU 하드웨어

2026 Kimi K3 vLLM OOM: 문맥 vs 동시성

판정: Kimi K3 vLLM 배포 OOM은 모든 값을 동시에 낮추지 말고, 발생 시점에 따라 조치해야 합니다. 모델을 올리기 전부터 실패하면 환경과 자원 조건을 먼저 확인하고, 첫 번째 긴 요청에서 실패하면 문맥과 프리필 부하를 줄이며, 동시성을 높인 뒤에만 실패하면 동시 요청 수와 캐시 예산을 제한하는 순서가 맞습니다. 최소 부하에서도 안정적으로 실행되지 않으면 계속 기능을 포기하기보다 호환 환경으로 전환해야 합니다.

이 글은 이미 Kimi K3를 vLLM으로 실행했지만 OOM의 원인을 아직 나누지 못한 엔지니어를 위한 내용입니다. 긴 문맥 에이전트의 동시성 한계를 정해야 하는 플랫폼 팀과, 기존 자원 유지·확장·격리 환경 전환을 비교하는 기술 책임자도 대상에 포함됩니다.

마지막 검토: 2026년 8월 6일, vLLM Kimi K3 공식 레시피와 vLLM 배포 안내를 기준으로 확인했습니다.

첫 단계는 OOM이 발생한 순간을 고정하는 일입니다

오류 로그의 마지막 줄만 보고 max-model-len이나 max-num-seqs를 바꾸면 원인이 섞입니다. 다음 네 시점을 별도로 표시해야 합니다.

  • 모델 가중치를 읽기 전후
  • 서버가 준비된 뒤 첫 요청
  • 짧은 요청은 성공하고 긴 요청을 넣은 순간
  • 단일 요청은 성공하고 동시성을 올린 순간

각 실험에서 시작 로그, 종료 로그, GPU별 메모리 변화, 요청의 입력 길이와 출력 예산을 함께 보관해야 합니다. 이 기록이 있어야 정적 모델 자원 부족, 프리필 피크, 동시성에 따른 캐시 압력을 구분할 수 있습니다.

실제로 vLLM은 스케줄러에서 한 번에 처리할 토큰 수와 시퀀스 수를 별도 인자로 관리합니다. max-num-batched-tokens는 한 반복에서 처리할 토큰 수이고, max-num-seqs는 한 반복에서 처리할 시퀀스 수입니다. 둘은 비슷해 보이지만 같은 실험값이 아닙니다. vLLM 엔진 인자 문서에서도 두 설정을 별도 항목으로 설명합니다. (docs.vllm.ai)

로딩 단계라면 문맥 설정보다 환경 경계를 먼저 봅니다

서버가 요청을 받기도 전에 OOM으로 종료된다면 동시성을 낮추는 조치는 의미가 없습니다. 이 단계에서는 다음 항목을 확인해야 합니다.

  • 공식 Kimi K3 전용 Docker 이미지 사용 여부
  • 이미지가 CUDA 13, 즉 cu130 빌드인지 여부
  • NVIDIA 호스트 드라이버가 r580 이상인지 여부
  • 공식 레시피가 제시한 GPU 구성과 실제 구성의 일치 여부
  • 모든 rank가 가중치를 정상적으로 읽었는지 여부

현재 공식 레시피는 Kimi K3 이미지에 CUDA 13 빌드만 제공하며 cu129 태그가 없다고 명시합니다. NVIDIA 호스트에는 r580 이상 드라이버가 필요하고, r575 기반 호스트는 드라이버 업그레이드나 별도 빌드가 필요합니다. 공식 레시피의 하드웨어 기준도 함께 확인해야 하며, 커뮤니티에서 계산한 특정 총 메모리 하한을 확정값처럼 사용해서는 안 됩니다. (recipes.vllm.ai)

이 경우 max-model-len은 근본 해결책이 아닙니다. 해당 값은 요청에 사용할 문맥 상한과 캐시 계획에 영향을 주지만, CUDA 이미지와 호스트 드라이버가 맞지 않거나 모델 가중치 자체를 올릴 자원이 부족한 상황을 고치지 못합니다. 다음처럼 최소 실행 명령을 별도 보관해 기준선을 만들어야 합니다.

vllm serve moonshotai/Kimi-K3 \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --load-format fastsafetensors \
  --enable-prefix-caching

명령의 GPU 수와 옵션은 버전에 따라 달라질 수 있으므로 실제 적용 전에는 공식 레시피를 다시 대조해야 합니다. 기준 명령조차 모델 로딩 단계에서 실패하면 요청 파라미터 조정은 중단하고 드라이버, 이미지, GPU 자원을 바꾸는 단계로 넘어가야 합니다.

긴 요청에서만 실패하면 문맥과 프리필을 분리해 줄입니다

짧은 요청이 안정적이고 긴 문서, 코드 저장소, 이미지 입력에서만 Kimi K3 vLLM 배포 OOM이 발생한다면 첫 조정 대상은 동시성이 아니라 입력 부하입니다. 이때 확인할 항목은 다음과 같습니다.

  • 실제 입력 토큰 수
  • 프리필 시작 직전과 피크 시점의 GPU 메모리
  • 출력 토큰 예산
  • 텍스트 입력과 멀티모달 입력의 차이
  • max-model-len과 실제 요청 길이의 간격

max-model-len은 실제 업무에 필요한 문맥 길이가 아니라 허용 상한입니다. 따라서 처음부터 큰 상한을 선언하기보다 목표 에이전트 요청을 짧은 문맥, 중간 문맥, 긴 문맥으로 나누고 각 단계에서 품질과 메모리를 함께 측정해야 합니다.

프리필이 병목이라면 max-num-batched-tokens를 낮추는 실험도 가능합니다. vLLM의 청크 프리필은 긴 입력을 여러 조각으로 나누어 처리할 수 있으며, 해당 값이 작아지면 프리필 피크를 낮추는 대신 첫 토큰까지 걸리는 시간이나 전체 처리량이 달라질 수 있습니다. 멀티모달 입력에서는 이미지 토큰이 중간에 끊기지 않도록 관련 옵션과 현재 버전의 동작을 함께 확인해야 합니다. (docs.vllm.ai)

검증 순서는 다음처럼 고정하는 편이 좋습니다.

  1. 동일한 요청에서 출력 예산을 고정합니다.
  2. 입력 문맥만 한 단계 낮춥니다.
  3. 서버 재시작 후 같은 요청을 다시 실행합니다.
  4. 피크 메모리와 응답 품질을 기록합니다.
  5. 안정화되면 다음 문맥 단계로 올립니다.

문맥을 줄였는데도 첫 긴 요청에서 동일한 지점에 실패하면 프리필만의 문제가 아닐 수 있습니다. 이때는 캐시를 끄거나 동시성을 낮추기 전에 로그의 메모리 할당 실패 위치와 각 rank 상태를 다시 확인해야 합니다.

동시성 상승 뒤에만 실패하면 캐시 예산을 따로 시험합니다

단일 요청과 짧은 요청이 반복해서 성공하고, 동시 요청 수를 올릴 때만 OOM이 발생한다면 max-num-seqs와 max-num-batched-tokens가 우선 대상입니다. vLLM 공식 메모리 안내도 KV 캐시 공간이 부족할 때 동시 시퀀스 수와 배치 토큰 수를 낮추는 방법을 제시합니다. 반대로 tensor-parallel-size를 늘리면 모델 가중치를 더 많은 GPU에 나눌 수 있지만 통신 비용이 커질 수 있습니다. (docs.vllm.ai)

이때 문맥 축소와 동시성 축소를 한 번에 하지 않아야 합니다.

  • 실험 A: 입력 문맥을 유지하고 동시성만 낮춥니다.
  • 실험 B: 동시성을 유지하고 입력 문맥만 낮춥니다.
  • 실험 C: 두 값을 원래대로 돌리고 prefix caching만 끕니다.
  • 각 실험에서 처리량, 대기 시간, 피크 메모리, OOM 재현 여부를 비교합니다.

Kimi K3의 prefix caching은 기본으로 켜져 있다고 가정하면 안 됩니다. vLLM 공식 안내는 enable_prefix_caching=True 또는 이에 대응하는 실행 옵션을 명시해야 기능을 활성화한다고 설명합니다. Kimi K3 공식 블로그의 실행 예시에도 --enable-prefix-caching이 포함되어 있습니다. (docs.vllm.ai)

캐시의 효과는 서버가 켜지는지로 판단할 수 없습니다. 같은 시스템 프롬프트, 문서 접두부, 도구 정의를 공유하는 요청과 매번 다른 접두부를 쓰는 요청을 분리해야 합니다. 공유 접두부가 없는 업무라면 캐시를 켜도 프리필 재사용 이득이 작을 수 있습니다. 반대로 반복 접두부가 많으면 메모리 블록을 보유하는 비용과 프리필 절감 효과를 함께 계산해야 합니다. vLLM 문서도 자동 접두부 캐시는 공유 접두부의 프리필 계산을 재사용하지만 디코드 시간을 줄이지는 않는다고 설명합니다. (docs.vllm.ai)

OOM처럼 보이는 종료가 실제 메모리 부족인지 확인합니다

로그에 out of memory가 보인다고 모두 같은 장애는 아닙니다. 다음 세 가지를 구분해야 합니다.

  • CUDA 메모리 할당 실패가 직접 기록된 경우
  • 운영체제나 컨테이너가 프로세스를 종료한 경우
  • 비동기 illegal memory access 뒤에 여러 프로세스가 연쇄 종료된 경우

세 번째 유형은 동시성이나 캐시를 낮췄을 때 발생 빈도가 달라질 수 있지만, 그것만으로 메모리 용량 문제가 해결됐다고 볼 수 없습니다. 캐시를 끄거나 동시성을 제한했는데 오류가 사라지지 않고 단지 충돌 시점만 바뀐다면, 용량 조정 실험을 중단하고 해당 버전과 하드웨어 조합의 CUDA 오류 재현 자료를 수집해야 합니다.

특정 GitHub 이슈나 커뮤니티 재현 사례는 환경, 드라이버, 이미지, vLLM 버전이 다르면 일반적인 Kimi K3 원인으로 확대할 수 없습니다. 공식 레시피의 환경 조건과 실제 로그가 일치하는지 먼저 확인한 뒤, 같은 조건에서 다시 재현되는 경우에만 상위 장애로 분류하는 것이 안전합니다.

재검증은 다섯 단계로 끝내고 중단 조건을 정합니다

다음 체크리스트는 설정을 무작정 낮추지 않기 위한 최소 절차입니다.

  • [ ] 로딩 전후와 요청 단계별 GPU 메모리 변화를 저장합니다.
  • [ ] CUDA 이미지, 드라이버, GPU 구성, vLLM 버전을 고정합니다.
  • [ ] 단일 짧은 요청을 기준선으로 실행합니다.
  • [ ] 문맥 길이만 바꾸는 실험을 완료합니다.
  • [ ] 동시성만 바꾸는 실험을 완료합니다.
  • [ ] prefix caching을 켠 경우 공유 접두부 요청으로 효과를 검증합니다.
  • [ ] 실제 할당 실패와 비동기 CUDA 오류를 분리합니다.
  • [ ] 최소 기준선도 실패하면 기존 환경의 튜닝을 중단합니다.

한 번의 성공보다 중요한 것은 반복 가능한 기준선입니다. 단일 요청, 목표 문맥, 목표 출력, 예상 동시성에서 같은 결과가 반복되지 않으면 해당 환경을 배포 가능하다고 판단해서는 안 됩니다.

마지막에는 조정, 확장, 환경 교체를 비교합니다

현재 자원을 계속 쓰는 방법은 테스트 목표가 작고, 최소 문맥과 단일 요청을 안정적으로 통과할 때 적합합니다. 이 경우 동시성을 낮추고, 캐시 보유량을 제한하며, 긴 입력을 사전에 잘라 서비스 목표를 축소할 수 있습니다. 다만 처리량과 에이전트 품질이 떨어지는 지점을 명확히 기록해야 합니다.

자원을 늘리는 방법은 목표 문맥과 동시성을 유지해야 하고, 현재 GPU 구성이 공식 호환 조건을 만족할 때 적합합니다. GPU를 추가하면 모델과 캐시를 분산할 여지가 생기지만 통신 구조와 운영 비용이 늘어납니다. 단순히 GPU 수만 늘리고 드라이버와 이미지 조건을 그대로 두면 같은 오류를 더 큰 환경에서 반복할 수 있습니다.

격리된 테스트 환경으로 바꾸는 방법은 원인 분리가 우선인 경우에 적합합니다. 기존 클러스터를 바로 개조하지 않고 공식 이미지와 드라이버 조합을 갖춘 환경에서 최소 기준선을 실행하면, 모델 자체의 요구와 현재 클러스터의 문제가 분리됩니다. KuzCloud의 콘솔에서 테스트 환경 확인하거나 환경 사용 안내를 먼저 확인한 뒤, 장기 자원 구매 여부를 결정하는 방식이 비용과 복구 시간을 동시에 줄이기 쉽습니다.

선택지 먼저 선택할 조건 기대 효과 감수할 비용 중단 기준
기존 자원 유지 단일 요청과 최소 문맥이 안정적임 가장 빠른 설정 변경 문맥과 동시성 축소 목표 품질 또는 처리량 미달
호환 GPU 확장 환경 조건은 맞고 목표 부하만 부족함 문맥과 동시성 유지 가능성 GPU 비용, 통신과 운영 복잡도 확장 후에도 기준선 실패
격리 환경 전환 로딩 조건이나 드라이버가 불확실함 공식 기준선의 빠른 재현 임시 환경 비용과 데이터 이동 기준선 자체가 실패하거나 목표와 불일치

현재 방식이 오래된 호스트 드라이버, 비공식 CUDA 조합, 공유 GPU 환경에 의존한다면 OOM을 매번 설정값으로만 덮는 데 한계가 있습니다. 모델 로딩 단계의 자원 부족과 요청 단계의 캐시 압력을 한 환경에서 동시에 해결하려 하면 장애 원인과 비용이 함께 커집니다. 반면 KuzCloud처럼 격리된 Mac 기반 테스트 환경을 임시로 활용하면 NVIDIA 전용 Kimi K3 실행 자체를 대체하지는 못하더라도, 에이전트 API 흐름과 상위 플랫폼 통합을 분리 검증할 수 있습니다. Kimi K3의 GPU 기준선이 필요한 팀은 먼저 호환 GPU 환경을 대여해 최소 실행을 확인한 뒤 장기 클러스터를 결정하는 편이 안전합니다.

최소 기준선도 통과하지 못한 상태라면 더 많은 파라미터를 낮추기보다 KuzCloud의 지원 문서를 통해 테스트 범위와 환경 조건을 확인하는 것이 다음 단계입니다. 장기 운영 자원이 이미 확정된 팀은 직접 클러스터를 구성하고, 아직 모델의 실제 문맥·동시성 요구를 모르는 팀은 격리 테스트 후 구매 또는 확장 결정을 내리는 편이 합리적입니다.

대규모 모델 배포 환경을 KuzCloud에서 준비하세요

로컬 장비의 메모리 한계를 넘어 원격 맥에서 모델 배포와 성능 검증을 진행할 수 있습니다.

문맥 길이와 동시성을 하나씩 조정하며 안정적인 실행 조건을 체계적으로 확인할 수 있습니다.