2026 Kimi K3 vLLM OOM: 조정과 확장

메모리 부족이 가중치 로딩 중 발생하면 동시성을 낮춰도 해결되지 않습니다. 요청 처리 중 발생하면 문맥 길이·동시성·prefix caching을 순서대로 조정하고, 목표 부하에서 여유가 없을 때만 확장하십시오.

이 글을 볼 사람

개인 연구자와 POC 팀은 현재 환경이 기능 검증까지만 가능한지 판단할 수 있습니다.
소형 Agent 팀은 실제 접두부 재사용을 보존하면서 안정적인 메모리 경계를 찾을 수 있습니다. 플랫폼·생산팀은 기존 클러스터를 고칠지, 공식 토폴로지에 맞는 다중 노드 환경으로 옮길지 결정할 수 있습니다.

마지막 업데이트: 2026년 8월 16일. 데이터는 Kimi K3 공식 vLLM 레시피와 vLLM 공식 배포 안내를 기준으로 확인했습니다.

OOM 위치에 따른 판단선

Kimi K3 vLLM OOM을 하나의 오류로 처리하면 조정 방향을 잘못 잡기 쉽습니다. 먼저 로그와 초기화 상태를 맞춰 보십시오.

공식 레시피는 Kimi K3용 이미지가 CUDA 13 빌드만 제공되며, 호스트에는 R580 이상 드라이버가 필요하다고 안내합니다. CUDA 호환성 표도 CUDA 13 계열의 최소 드라이버를 580 이상으로 제시합니다. 따라서 R575 계열 호스트에서 max-model-len만 줄이는 것은 환경 불일치와 용량 부족을 해결하지 못합니다. (recipes.vllm.ai)

모델 자체도 2.8조 파라미터 규모의 혼합 전문가 구조이며, 공식 레시피에는 1,048,576 토큰 문맥과 8장 이상의 지정 가속기 구성이 적혀 있습니다. 이 수치는 모든 생산 배치의 정답 GPU 수가 아닙니다. 메모리 용량뿐 아니라 병렬 방식, 노드 간 연결, 요청 분포까지 함께 봐야 합니다. (recipes.vllm.ai)

주의: 모델 초기화가 완료되기 전에 멈췄다면 동시성을 1로 낮춘 결과를 용량 증명으로 사용하지 마십시오. 그것은 실행기 부하를 줄인 것일 뿐, 가중치가 지원 토폴로지에 올라간다는 뜻이 아닙니다.

개인 검증팀과 POC 팀의 최소 환경

개인 연구자나 POC 팀의 목표는 생산 처리량이 아닙니다. API 응답, 도구 호출, 기본 추론 흐름이 한 번 끝까지 도는지 확인하는 것이 먼저입니다.

이 단계에서는 다음과 같이 실험 변수를 줄이는 것이 합리적입니다.

• 긴 문서를 제거하고 짧은 검증 문맥으로 시작합니다.
• 동시 요청을 하나로 고정합니다.
• 이미지, 도구 호출, 스트리밍을 한 번에 모두 켜지 않습니다.
• 모델 초기화 완료 시각과 첫 응답 반환 여부를 별도로 기록합니다.
• 같은 이미지와 같은 시작 명령을 유지한 채 한 변수만 바꿉니다.

다만 공식 문서가 확인하지 않은 임의의 메모리 수치나 GPU 조합을 일반 해법처럼 쓰면 안 됩니다. POC에서 짧은 문맥으로 첫 응답이 나왔다면 “기능 검증 가능”이라고 기록할 수 있습니다. “생산 요청을 수용할 수 있다”고 결론 내릴 수는 없습니다.

POC에서 멈춰야 하는 조건

다음 중 하나라도 해당하면 조각난 설정을 계속 바꾸지 말고 공식 지원 환경으로 이동하십시오.

• 공식 Kimi K3 이미지가 호스트 드라이버와 맞지 않습니다.
• 가중치 매핑 전에 메모리 부족으로 반복 중단됩니다.
• 지정된 병렬 방식과 하드웨어 경로를 사용할 수 없습니다.
• 컨테이너는 바꿀 수 있지만 호스트 드라이버와 노드 연결은 바꿀 수 없습니다.
• 로딩 성공 여부를 확인할 수 있는 동일 조건의 로그가 남지 않습니다.

이 경우에는 MacHTML 콘솔에서 임시 추론 환경을 확인하는 방법을 먼저 검토하는 편이 자체 클러스터를 무리하게 재구축하는 것보다 빠릅니다.

소형 Agent 팀의 조정과 캐시 보존

소형 Agent 팀은 단순 채팅보다 메모리 패턴이 복잡합니다. 시스템 지침, 도구 정의, 저장소 요약, 이전 대화가 반복되기 때문입니다. 이때 문맥을 줄이는 것과 캐시를 끄는 것은 같은 조치가 아닙니다.

vLLM의 일반적인 prefix caching은 같은 접두부의 KV 상태를 재사용해 프리필 계산을 줄입니다. Kimi K3는 일반 KV뿐 아니라 KDA의 반복 상태까지 함께 다루므로, 공식 안내에 따라 --enable-prefix-caching을 명시해야 합니다. Kimi K3에서는 이 기능이 기본으로 켜져 있지 않습니다. (vllm.ai)

캐시를 켰는데도 메모리 부족이 발생하면 먼저 실제 접두부가 반복되는지 확인하십시오. 한 번만 등장하는 요청이 대부분이라면 캐시 적중은 낮고 보존 공간만 늘 수 있습니다. 반대로 고정 시스템 프롬프트와 도구 정의가 반복된다면 캐시를 모두 끄는 것은 프리필 부담을 되돌리는 조치가 될 수 있습니다.

vLLM 공식 문서는 Kimi K3의 캐시 보존에 프롬프트 끝 지점과 선택적 보존 정책을 사용한다고 설명합니다. 보존 간격을 넓히면 캐시 공간과 재계산 사이의 균형이 달라지므로, 짧은 테스트 한 번이 아니라 같은 Agent 요청 집합으로 비교해야 합니다. (vllm.ai)

소형 팀의 재측정 절차

1. 실제 시스템 지침, 도구 정의, 대표 사용자 입력을 포함한 요청 집합을 고정합니다.
2. 캐시를 켠 기본 조건에서 최고 GPU 메모리와 적중 상태를 기록합니다.
3. 동시성을 낮추고 같은 요청 집합을 다시 실행합니다.
4. 문맥 길이를 낮추고 같은 요청 집합을 다시 실행합니다.
5. 캐시 보존 정책을 바꾼 뒤 프리필 시간과 적중 상태를 비교합니다.
6. 문맥·동시성·캐시를 원래 목표값으로 되돌려 안정성을 확인합니다.
7. 목표값으로 되돌렸을 때 여유가 없으면 조정 성공이 아니라 확장 필요 상태로 분류합니다.

운영 경험: 짧은 단일 프롬프트가 성공한 뒤 실제 Agent 요청에서 OOM이 재발하는 경우가 많습니다. 해결 판정은 반드시 같은 요청 집합의 전후 비교로 남기십시오.

플랫폼팀의 환경 통제와 재구축 비용

이미 GPU 클러스터를 가진 플랫폼팀은 설치 명령을 처음부터 반복하기보다 바꿀 수 있는 계층을 먼저 확인해야 합니다.

공식 안내는 NVLink 환경과 RDMA 환경에 서로 다른 all-to-all 경로를 사용하도록 구분합니다. 또한 생산 트래픽은 다중 노드 구성을 전제로 하며, 전문가 병렬과 데이터 병렬을 연결 방식에 맞춰 선택해야 합니다. 따라서 GPU 장수만 세어 “두 배 확장하면 두 배 처리”라고 계산하면 안 됩니다. (recipes.vllm.ai)

기존 클러스터가 컨테이너만 수정할 수 있는 구조라면 다음 순서로 판단하십시오.

1. 호스트에서 실제 드라이버 버전을 확인합니다.
2. 컨테이너가 CUDA 13 전용 이미지인지 확인합니다.
3. 단일 노드에서 엔진 초기화가 완료되는지 확인합니다.
4. 노드 간 연결 방식과 공식 all-to-all 설정을 대조합니다.
5. 작은 요청이 아니라 목표에 가까운 프리필 요청을 실행합니다.
6. 연결 오류와 메모리 부족을 서로 다른 사건으로 분류합니다.

환경 계층을 바꿀 권한이 없다면 자체 빌드의 비용은 단순한 개발 시간에 그치지 않습니다. 이미지 재생성, 의존성 고정, 드라이버 갱신 후 재검증, 노드별 설정 동기화가 계속 필요합니다. MacHTML 도움말의 원격 환경 운영 절차처럼 접근 권한과 배포 경계를 먼저 확인한 뒤, 단기 검증과 장기 운영을 분리하십시오.

생산팀의 확장 기준

생산 서비스에서는 “서버가 켜진다”가 통과 조건이 아닙니다. 다음 네 가지를 목표 부하에 넣어야 합니다.

• 예상 입력 문맥 길이
• 동시 Agent 세션 수
• 고정 접두부와 도구 정의의 재사용률
• 장애 발생 후 재시작과 대기열 회복 요구

vLLM 공식 자료는 Kimi K3에 전문가 병렬, 데이터 병렬, 프리필·디코드 분리 구성을 제시합니다. 프리필과 디코드를 분리하면 각 경로를 서로 다른 병목에 맞춰 설계할 수 있지만, KDA 상태·KV 상태·블록 정보의 전송과 노드 연결이 추가로 필요합니다. 따라서 다중 노드는 메모리 부족을 단순히 나누는 버튼이 아닙니다. (vllm.ai)

공식 성능 수치는 특정 시험 구성에만 적용됩니다. 예를 들어 공식 글의 단일 사용자 디코드 수치는 16장 구성과 특정 시험 조건에서 측정된 값이며, 다른 문맥·동시성·연결 방식에 그대로 적용할 수 없습니다. 모든 처리량과 지연 수치는 시험 토폴로지와 요청 조건을 함께 기록해야 합니다. (vllm.ai)

생산 확장을 결정할 때는 다음과 같이 분기하십시오.

• 목표 문맥과 동시성을 낮추지 않아도 안정적인 여유가 남으면 현재 환경을 유지하고 감시를 강화합니다.
• 문맥이나 동시성을 합리적으로 낮춘 뒤에만 안정되면, 해당 제한을 서비스 계약으로 받아들일지 확장할지 결정합니다.
• 목표 부하에서 반복 OOM이 발생하거나 장애 복구용 여유가 사라지면 다중 노드 또는 임시 환경을 검토합니다.
• 가중치 로딩 자체가 지원 토폴로지에서 실패하면 조정보다 환경 이동이 먼저입니다.

재현 기록과 최종 결정

OOM 대응 결과는 다음 세 가지 중 하나로 남겨야 합니다.

재현 기록에는 다음 항목을 빠뜨리지 마십시오.

• 컨테이너 이미지와 vLLM 버전
• 호스트 드라이버와 CUDA 실행 경로
• GPU 구성과 노드 수
• TP, EP, DEP, 프리필·디코드 분리 설정
• 시작 인자와 환경 변수
• 대표 요청 원문 또는 안전한 샘플
• 최대 문맥, 동시성, 출력 길이
• 최고 메모리와 캐시 적중 상태
• OOM이 발생한 로그 위치
• 측정 날짜와 변경한 변수

vLLM의 Kimi K3 지원은 공식 레시피와 이미지가 갱신될 때 조건이 바뀔 수 있습니다. 안정 버전 지원, 레시피 이미지 변경, 드라이버 조건 변경, OOM 관련 옵션 변경이 발생하면 동일 기록으로 다시 측정해야 합니다. 현재 공식 레시피는 2026년 8월 14일에 갱신되어 있으므로, 이전 커뮤니티 글보다 최신 레시피를 우선하십시오. (recipes.vllm.ai)

실행 전 점검 목록

• [ ] OOM 로그가 가중치 로딩 전후인지 첫 요청 이후인지 분류했습니다.
• [ ] 모델 초기화 완료와 첫 응답 반환 여부를 각각 기록했습니다.
• [ ] Kimi K3 전용 이미지와 CUDA 13 실행 경로를 확인했습니다.
• [ ] 호스트 드라이버가 R580 이상인지 확인했습니다.
• [ ] 현재 하드웨어와 공식 병렬 토폴로지를 대조했습니다.
• [ ] 실제 Agent 요청 집합을 고정했습니다.
• [ ] 문맥 길이와 동시성을 한 번에 하나씩 조정했습니다.
• [ ] prefix caching을 켠 조건과 끈 조건을 같은 요청으로 비교했습니다.
• [ ] 최고 메모리, 적중 상태, 지연, 오류율을 저장했습니다.
• [ ] 목표 부하에서 필요한 장애 복구 여유를 별도로 확인했습니다.
• [ ] 로딩 실패와 용량 부족을 다른 판정으로 기록했습니다.
• [ ] 현재 클러스터에서 바꿀 수 있는 계층과 바꿀 수 없는 계층을 구분했습니다.

현재 클러스터가 CUDA 13·R580 이상·공식 병렬 경로를 만족하지 않는다면, 자체 구축을 계속하는 동안 원인 분리가 더 어려워질 수 있습니다. 반대로 환경은 맞지만 목표 Agent 부하에서만 OOM이 발생한다면, 문맥과 동시성을 계속 희생하기보다 실제 연결 조건을 갖춘 다중 노드 확장이 더 정직한 해법입니다.

특히 기존 방식은 호스트 드라이버를 직접 올릴 수 없고, 컨테이너와 네트워크 설정이 분리되어 있으며, GPU를 추가해도 NVLink나 RDMA 경로가 맞지 않을 수 있다는 문제가 있습니다. 이 상태에서 장기 운영을 시작하면 자체 이미지 유지, 노드별 설정 차이, 재부팅 후 재현 실패가 누적됩니다. 단기 검증이나 마이그레이션 전 비교라면 MacHTML의 이용 가능한 클라우드 맥 환경에서 같은 요청 집합을 재현해 보는 편이 안전합니다. 대조 결과를 기준으로 기존 클러스터를 조정할지, 공식 토폴로지에 맞는 환경으로 확장할지 결정하십시오.

자주 묻는 질문