2026 Kimi K3 vLLM 오류: 환경부터 캐시까지

컨테이너가 시작되지 않거나 OOM 뒤에 prefix caching까지 미적중한다면, 먼저 공식 이미지와 CUDA 13 빌드, 호스트 드라이버를 확인해야 합니다. 그다음 의존성 로딩, 메모리, 다중 노드 통신을 점검하고 마지막에 캐시 동작을 검증해야 합니다.

이 글은 Kimi K3를 직접 운영하는 추론 플랫폼 엔지니어, 긴 프롬프트를 공유하는 AI Agent 팀, 기존 GPU 클러스터를 계속 사용할지 새 환경을 빌릴지 판단하는 인프라 담당자를 위한 장애 대응 문서입니다.

마지막 업데이트: 2026년 8월 11일. vLLM Kimi K3 공식 레시피와 발표 글, NVIDIA CUDA 13 호환성 문서를 기준으로 내용을 다시 확인했습니다.

첫 로그로 나누는 장애 계층

Kimi K3 vLLM 오류는 마지막 한 줄만 보면 오판하기 쉽습니다. 다음 자료를 한 번에 보존해야 합니다.

• 실행한 Docker 명령
• 컨테이너 태그
• vLLM 버전
• nvidia-smi 전체 출력
• 첫 번째 예외와 전체 Python 추적 기록
• 노드별 GPU, 네트워크 인터페이스, 드라이버 상태

Kimi K3 전용 이미지와 실행 조건은 vLLM 공식 Kimi K3 레시피에서 먼저 대조하십시오. 일반적인 모델 장애 사례를 Kimi K3에 그대로 적용하면 이미지, 커널, 캐시 구조의 차이를 놓칠 수 있습니다.

판단 순서는 아래처럼 잡으면 됩니다.

증상 → 확인 대상 → 다음 행동

• 컨테이너가 즉시 종료됨 → 이미지 태그와 호스트 드라이버 → CUDA 13과 r580 이상 여부 확인
• module not found, 연산자 누락, 모델 구조 미인식 → vLLM 이미지와 wheel 구성 → 공식 Kimi K3 이미지로 재현
• 엔진 초기화 중 메모리 부족 → GPU 수, 가중치 로딩 방식, 병렬 설정 → 하드웨어 토폴로지와 시작 로그 확인
• 요청 처리 중 메모리 부족 → 입력 길이, 동시 요청, 배치, KV cache → 실행 중 메모리 변화를 분리 기록
• 캐시가 켜졌지만 재사용되지 않음 → 플래그, 입력 접두부, 보존 정책 → 로그와 캐시 지표를 함께 확인
• NCCL error 또는 mlx5dv_reg_dmabuf_mr 실패 → all-to-all backend, RDMA, 커널 모듈 → 연결 방식에 맞는 설정으로 되돌림

장애 계층 판정 체크리스트

아래 항목을 위에서부터 확인하십시오.

• [ ] 호스트 드라이버가 r580 이상입니다.
• [ ] 공식 Kimi K3 이미지와 올바른 태그를 사용합니다.
• [ ] 컨테이너 내부 vLLM과 관련 연산자 버전을 기록했습니다.
• [ ] 시작 단계와 요청 처리 단계의 OOM 로그를 분리했습니다.
• [ ] --enable-prefix-caching이 실제 실행 명령에 포함되어 있습니다.
• [ ] 요청의 시스템 프롬프트와 도구 정의가 동일합니다.
• [ ] NVLink와 RDMA 중 실제 연결 방식을 확인했습니다.
• [ ] 모든 노드의 드라이버, 이미지, 커널 모듈이 일치합니다.

첫 세 항목에서 실패하면 캐시나 컨텍스트 길이를 조정하지 마십시오. 환경을 먼저 고친 뒤 다음 계층으로 넘어가야 합니다.

CUDA 13 이미지와 r580 드라이버

호스트 드라이버와 컨테이너 런타임의 차이

공식 Kimi K3 레시피는 vllm/vllm-openai:kimi-k3 이미지를 사용하며, 이 이미지는 CUDA 13, 즉 cu130 빌드만 제공합니다. 공식 레시피에는 cu129 태그가 없고 K3용 wheel도 cu129 nightly 색인에 제공되지 않는다고 명시되어 있습니다. 호스트는 r580 이상 NVIDIA 드라이버를 사용해야 합니다. (Kimi K3 공식 vLLM 레시피)

NVIDIA의 CUDA 13.0 릴리스 노트는 CUDA 13.0에 Linux 드라이버 580.65.06 이상이 필요하며, CUDA 13 계열이 r580 이상 드라이버와 호환된다고 설명합니다. 따라서 “r580 이상”은 Kimi K3 레시피와 CUDA 공식 문서가 모두 뒷받침하는 환경 기준입니다.

여기서 세 가지를 분리해야 합니다.

• 호스트 드라이버: GPU와 컨테이너가 통신할 때 필요한 커널 수준 구성입니다.
• 컨테이너 CUDA 런타임: 이미지 안에 포함된 실행 라이브러리입니다.
• 로컬 CUDA Toolkit: 직접 빌드할 때 사용하는 개발 도구입니다.

컨테이너 안에서 CUDA 라이브러리를 다시 설치해도 호스트 드라이버가 오래된 문제는 해결되지 않습니다. NVIDIA의 드라이버와 CUDA Toolkit 호환성 표도 설치된 드라이버가 해당 CUDA 계열의 최소 요구 버전 이상이어야 한다고 안내합니다.

먼저 다음을 실행합니다.

nvidia-smi
docker image inspect vllm/vllm-openai:kimi-k3
docker run --rm --gpus all vllm/vllm-openai:kimi-k3 nvidia-smi

확인 결과 호스트가 r575 계열이라면 선택지는 두 가지뿐입니다.

1. 호스트 NVIDIA 드라이버를 r580 이상으로 올립니다.
2. 공식 설명에 따라 K3 지원 브랜치에서 cu129 기반 환경을 직접 빌드합니다.

두 경로를 섞어 컨테이너 안에 임의의 CUDA 패키지를 추가하는 방식은 피해야 합니다. 드라이버를 올릴 수 없는 환경이라면 공식 설명과 현재 하드웨어 조건을 대조한 뒤 별도 빌드의 재현성을 먼저 검증해야 합니다.

주의: nvidia-smi에 표시되는 CUDA 버전은 드라이버가 지원하는 최대 CUDA 계열입니다. 컨테이너가 실제로 사용하는 CUDA 런타임 버전과 같은 값이라고 단정하지 마십시오.

공식 이미지와 의존성 조합

일반 vLLM 이미지가 실패하는 이유

Kimi K3는 표준 Transformer 모델과 다른 Kimi Delta Attention, Attention Residuals, 하이브리드 캐시 구조를 사용합니다. vLLM의 Kimi K3 발표 글도 Kimi K3 지원을 위해 별도 커널과 캐시 관리 기능을 통합했다고 설명합니다. 따라서 일반 vLLM 이미지나 오래된 nightly wheel을 같은 기능으로 볼 수 없습니다.

다음 오류는 의존성 조합을 먼저 의심해야 합니다.

• 모델 구조를 인식하지 못함
• Kimi K3 모듈 import 실패
• FlashInfer 또는 CUDA 연산자 누락
• unknown model architecture
• 존재하지 않는 이미지 태그
• undefined symbol 또는 wheel ABI 오류

복구 순서는 다음과 같습니다.

1. 현재 이미지 이름과 태그를 기록합니다.
2. 컨테이너 내부의 vLLM 버전을 확인합니다.
3. pip list로 FlashInfer와 관련 패키지 버전을 기록합니다.
4. 동일한 모델 경로를 공식 Kimi K3 이미지에서 재현합니다.
5. 두 환경의 첫 예외를 비교합니다.
6. 공식 이미지에서 정상 로딩되면 기존 이미지의 변형을 중단하고 환경을 고정합니다.

vLLM 공식 안내는 현재 Kimi K3 실행에 여러 시험 단계 의존성이 필요하므로 Docker 이미지 사용을 권장합니다. 비슷한 모델의 GitHub issue를 보고 같은 수정 방법을 적용하지 마십시오. Kimi K3의 전체 추적 기록과 공식 레시피를 기준으로 판단해야 합니다.

정상 확인용 명령은 다음과 같이 최소화합니다.

python -c "import vllm; print(vllm.__version__)"
python -c "import torch; print(torch.__version__, torch.version.cuda)"
pip freeze > environment.txt

정상 이미지와 현재 이미지의 environment.txt를 보관하면 다음 배포에서 동일한 장애를 재현하기 쉽습니다. 컨테이너 상태와 실행 로그는 MacHTML 운영 도움말에 정리할 때도 이 형태가 가장 유용합니다.

prefix caching 설정과 실제 적중

플래그만 넣고 끝나지 않는 이유

Kimi K3의 prefix caching은 현재 기본으로 켜져 있지 않습니다. 공식 실행 예시에는 --enable-prefix-caching이 명시되어 있습니다. 먼저 시작 명령에 이 옵션이 실제로 들어갔는지 확인해야 합니다. 세부 동작과 실행 인자는 vLLM 공식 문서의 Kimi K3 안내에서도 확인할 수 있습니다.

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

캐시 미적중은 다음 세 경우로 나눠야 합니다.

• 기능이 꺼진 경우: 시작 명령이나 배포 템플릿에 플래그가 없습니다.
• 입력 접두부가 다른 경우: 시스템 메시지, 도구 정의, 공백, 토큰화 결과가 달라집니다.
• KDA 상태 보존 범위가 다른 경우: Kimi K3는 일반 KV cache만이 아니라 KDA 상태도 다루므로 모든 위치를 같은 방식으로 보존하지 않습니다.

따라서 첫 요청의 지연 시간이 줄지 않았다는 이유만으로 실패를 선언하면 안 됩니다. 다음 순서로 검증합니다.

1. 시작 로그에서 prefix caching 활성화 여부를 확인합니다.
2. 동일한 system prompt와 tool schema를 두 요청에 사용합니다.
3. 사용자 질문만 바꿔 접두부를 고정합니다.
4. 두 번째와 세 번째 요청의 캐시 지표를 확인합니다.
5. 입력 토큰 수와 재계산 구간을 함께 기록합니다.
6. 프롬프트 끝 보존과 주기적 보존 설정을 분리해 비교합니다.

Kimi K3의 KDA 상태는 모든 토큰 위치에 저장되지 않고, 프롬프트 끝이나 선택된 체크포인트를 중심으로 보존됩니다. 공식 발표 글에는 VLLM_PREFIX_CACHE_RETENTION_INTERVAL로 주기적 보존 간격을 조절할 수 있으며, 값을 0으로 설정하면 프롬프트 끝 상태만 보존한다고 설명되어 있습니다.

시작 OOM과 요청 OOM

Kimi K3 배포에서 OOM은 발생 시점으로 나눠야 합니다. 시작 단계와 요청 처리 단계는 원인이 다릅니다.

시작 단계 OOM

• GPU 수와 실제 인식된 장치 확인
• tensor parallel 또는 expert parallel 설정 확인
• 가중치 로딩 형식 확인
• 다른 프로세스가 점유한 메모리 확인
• 노드별 GPU 토폴로지와 링크 상태 확인

요청 처리 단계 OOM

• max-model-len
• 동시 요청 수
• 배치 크기
• 입력과 출력 토큰 길이
• KV cache와 prefix cache 점유량
• 긴 요청이 종료된 뒤 메모리가 회수되는지

Kimi K3 공식 레시피는 NVIDIA 환경에서 최소 8개의 GB300 사용을 전제로 하며, 실제 운영 트래픽에는 다중 노드를 권장합니다. 필요한 GPU 수는 하드웨어 세대와 병렬 구성에 따라 달라질 수 있으므로, 일반적인 소형 모델의 단일 GPU 경험으로 용량을 추정하면 안 됩니다. 이 하드웨어 전제는 Kimi K3 공식 레시피의 요구 조건을 기준으로 확인해야 합니다.

다음 정보를 함께 저장해야 원인을 분리할 수 있습니다.

nvidia-smi --query-gpu=index,name,memory.total,memory.used,memory.free \
  --format=csv

• 시작 직전부터 메모리가 부족하면 하드웨어, 가중치, 병렬 설정을 먼저 봅니다.
• 서버는 뜨지만 긴 요청에서만 부족하면 컨텍스트와 동시성을 먼저 봅니다.
• 캐시를 켠 뒤에만 부족하면 캐시 보존 정책과 요청 재사용률을 함께 봅니다.

OOM 메시지만 보고 무조건 max-model-len을 줄이는 것은 임시 처방입니다. 줄인 뒤 정상화되더라도 원래의 이미지, 토폴로지, 캐시 설정이 맞았다는 뜻은 아닙니다.

다중 노드 통신 경로

Kimi K3의 다중 노드 장애는 NVLink와 RDMA 설정을 섞지 않는 것이 핵심입니다. 공식 레시피는 RDMA에 deepep_v2, NVLink에 flashinfer_nvlink_one_sided all-to-all backend를 사용하도록 구분합니다.

운영 중에는 다음 순서로 좁힙니다.

1. 모든 노드의 드라이버와 컨테이너 태그가 같은지 확인합니다.
2. GPU 수와 rank 배치를 노드별로 비교합니다.
3. 실제 연결 방식이 NVLink인지 RDMA인지 확인합니다.
4. 그 방식에 맞는 all-to-all backend를 선택합니다.
5. RDMA라면 UCX_TLS="rc,cuda_copy" 설정을 확인합니다.
6. NIC 이름, mlx5 장치, 커널 모듈 상태를 확인합니다.
7. 작은 기본 요청으로 통신을 검증한 뒤 긴 요청과 동시 요청으로 확대합니다.

자주 보이는 증상은 다음과 같습니다.

• NCCL error: unhandled system error
• mlx5dv_reg_dmabuf_mr 실패
• rank 하나만 초기화되지 않음
• all-to-all 단계에서 시간 초과
• 노드 간 연결은 되지만 추론 중단

NCCL 공식 문제 해결 문서는 네트워크 인터페이스, 공유 메모리, PCI 경로와 드라이버 구성을 분리해 확인하도록 안내합니다. 따라서 NCCL 오류가 보인다고 곧바로 모델 메모리 문제로 분류해서는 안 됩니다.

공식 레시피는 mlx5dv_reg_dmabuf_mr에서 오류 번호 524가 보이면 커널 또는 드라이버에 mlx5 dmabuf 지원이 부족할 수 있다고 설명합니다. 이 경우 NCCL_DMABUF_ENABLE=0으로 nvidia_peermem 경로를 사용할 수 있지만, 해당 모듈이 모든 노드에 로드되어 있어야 합니다.

환경을 유지할지 다시 빌릴지

다음 조건으로 현재 환경을 유지할지, 다시 빌드할지, 임시 환경을 확보할지 결정합니다.

기존 클러스터를 업그레이드하는 편이 맞는 경우

• 모든 노드의 GPU 세대가 공식 하드웨어 조건에 맞습니다.
• 드라이버를 r580 이상으로 올릴 수 있습니다.
• 재부팅과 커널 모듈 변경을 위한 유지보수 시간이 있습니다.
• RDMA 또는 NVLink 토폴로지를 직접 검증할 수 있습니다.

공식 이미지 기준으로 다시 구축하는 편이 맞는 경우

• 기존 환경에 CUDA 12.9 wheel과 CUDA 13 라이브러리가 혼재합니다.
• 일반 vLLM 이미지에서 Kimi K3를 억지로 불러오고 있습니다.
• 노드마다 vLLM, FlashInfer, 드라이버 버전이 다릅니다.
• 같은 오류를 여러 번 재현하지만 원본 로그가 보존되어 있지 않습니다.

임시로 검증된 환경을 확보하는 편이 맞는 경우

• 드라이버 변경 권한이 없습니다.
• 다중 노드 장비의 납기나 점검 일정이 길어집니다.
• AI Agent의 긴 프롬프트 재사용을 먼저 검증해야 합니다.
• 기존 서비스 중단 없이 Kimi K3 호환성을 확인해야 합니다.

복구 판정은 다음 순서로 끝내십시오.

1. 서비스가 오류 없이 시작되는지 확인합니다.
2. 짧은 기본 요청을 보냅니다.
3. 같은 긴 접두부를 반복해 캐시 재사용을 확인합니다.
4. 동시 요청에서 메모리와 지연을 기록합니다.
5. 다중 노드에서 일정 시간 안정적으로 처리되는지 확인합니다.
6. 실행 명령, 이미지 태그, 로그, 드라이버 출력을 인수 기록으로 남깁니다.

서비스가 뜨는 것만으로 완료 처리하면 안 됩니다. prefix caching, OOM, 통신 안정성까지 같은 조건에서 다시 재현되어야 운영 가능한 배포입니다.

현재 클러스터에서 Kimi K3를 계속 시험하는 방식은 드라이버 교체 권한, GPU 토폴로지, 커널 모듈, 노드 간 환경 일치라는 네 가지 부담을 함께 안고 갑니다. 특히 CUDA 12 계열에 남아 있는 노드와 CUDA 13 이미지를 섞으면 컨테이너만 바꿔도 문제가 끝나지 않습니다. 드라이버 업그레이드 일정이 불확실하거나 검증용 노드가 부족하다면, MacHTML의 추론 환경 안내와 관리 콘솔을 먼저 확인한 뒤 프로젝트 기간에 맞는 임시 AI Agent 추론 환경을 비교하는 편이 반복적인 비호환성 재시도보다 효율적입니다. 장기적으로 고정된 대규모 부하를 계속 처리하거나 물리 장비와 직접 연결해야 한다면 자체 클러스터가 더 적합하지만, 단기 검증과 장애 원인 분리는 이미 확인된 환경을 빌리는 쪽이 안전합니다.

더 읽기: 케이아이엠아이 케이쓰리 브이엘엘엠 시작 실패 때 드라이버 호환성부터 점검하기 케이아이엠아이 케이쓰리 자체 배치에 필요한 메모리와 장비 조건 살펴보기 직접 배치가 어려울 때 케이아이엠아이 케이쓰리 추론 경로와 예비 공급자 구성 비교하기