CI/CD

RTX 5090에서 vLLM을 실행하려면 CUDA 13.5가 필요할까요? 2026 환경 문제 해결

판정: CUDA 13.5를 기본 요구 사항으로 간주하지 말고, 설치하려는 vLLM 빌드에 맞는 조합을 선택해야 합니다. 해당 버전의 공식 설치 안내와 드라이버, PyTorch CUDA 백엔드, 양자화 형식이 서로 맞는 경우에만 다음 단계로 진행합니다.

이 글은 RTX 5090에 vLLM을 설치하거나 업그레이드하는 개발자, 단일 GPU에서 대형 모델과 FP4를 시험하는 엔지니어, 컨테이너와 PyTorch 환경 충돌을 다루는 운영자를 위한 점검 경로입니다.

최종 업데이트: 2026년 9월 30일. 버전 정보는 NVIDIA의 CUDA 툴킷 아카이브와 vLLM의 설치 안내 및 배포 자료를 기준으로 확인했습니다.

먼저 확인할 것: CUDA 13.5는 필수 조건이 아닙니다

NVIDIA 아카이브에는 확인 기준일 현재 CUDA 13.4.1이 올라와 있습니다. 확인한 vLLM 설치 자료와 배포 항목에는 CUDA 12.8, 12.9, 13.0 빌드 선택지가 표시되지만, 이것만으로 모든 vLLM 버전과 설치 방식의 호환성을 단정할 수는 없습니다. 그러므로 “RTX 5090이므로 CUDA 13.5를 설치해야 한다”는 전제로 환경을 바꾸지 않는 편이 안전합니다. vLLM 공식 배포 기록을 사용 중인 버전에 맞춰 대조하세요.

설치 형태도 중요합니다. 컨테이너에 포함된 라이브러리와 호스트 드라이버를 함께 써야 하는 환경이라면, 호스트에 설치된 툴킷 버전만 보고 호환된다고 판단할 수 없습니다. NVIDIA는 드라이버와 CUDA 런타임의 관계를 CUDA 하위 버전 호환성 안내에서 구분합니다.

증상별로 설치 조합을 분리해 확인합니다

선택지 또는 점검 항목 확인 기준 판단
CUDA 툴킷 버전 NVIDIA 아카이브와 실제 설치 형태를 대조합니다. 툴킷 번호 하나만으로 vLLM 지원 여부를 결정하지 않습니다.
PyTorch 백엔드 실행 중인 파이토치가 인식하는 CUDA 백엔드를 기록합니다. 휠의 백엔드가 예상과 다르면 vLLM 설치 전에 환경을 바로잡습니다.
vLLM 빌드 공식 설치 안내와 배포 자료에서 해당 버전의 설치 선택지를 확인합니다. 다른 버전의 명령이나 휠을 공통 해결책으로 재사용하지 않습니다.
드라이버와 GPU 드라이버 정보와 장치 인식 결과를 기록합니다. 장치 인식 실패와 파이썬 확장 모듈 오류를 따로 분류합니다.

설치 중단, 확장 모듈 가져오기 실패, 시작 시 CUDA 오류는 같은 문제로 취급하면 안 됩니다. 설치 중단은 휠 또는 빌드 선택, 확장 모듈 오류는 파이썬·바이너리 조합, 시작 시 오류는 드라이버와 런타임 연결부터 살펴봅니다. 우선 앞서 연결한 vLLM 공식 설치 안내에서 해당 버전의 설치 경로를 찾고, 기존 가상 환경이나 컨테이너에 서로 다른 빌드를 덧씌우지 않습니다.

FP4 로딩 오류는 형식과 실행 지원을 따로 봅니다

“4비트 모델”이라는 설명만으로 로딩 가능 여부나 실제 메모리 사용량을 예측할 수 없습니다. 모델 카드와 가중치 설정에서 NVFP4 같은 부동소수점 형식인지 INT4 정수 형식인지 확인하고, 생성에 사용된 양자화 도구 체인도 기록해야 합니다. NVFP4의 형식 선택은 vLLM의 양자화 방식 안내에서, ModelOpt 체크포인트 지원 여부는 vLLM의 ModelOpt 문서에서 확인합니다.

오류가 나면 다음 갈래로 분리합니다.

  • 가중치가 열리지 않으면 파일 구성과 선언된 양자화 형식을 확인합니다.
  • 모델은 읽지만 연산자 오류가 나면 현재 실행 백엔드가 해당 형식을 지원하는지 확인합니다.
  • 요청은 처리되지만 출력이 이상하면 모델 설정, 토크나이저, 실행 경로를 고정하고 재현 여부를 확인합니다.

FP4라는 표기가 있어도 양자화 스케일과 실행 중 작업 공간이 사라지는 것은 아닙니다. 따라서 명목상 비트 수를 실제 사용 메모리나 출력 품질의 보증으로 받아들이면 안 됩니다.

Chunked Prefill은 대조 실행으로 원인을 가립니다

청크 프리필은 긴 프롬프트의 처리와 요청 스케줄링에 관여하는 기능입니다. 가중치와 KV 캐시가 차지할 메모리를 대신 마련해 주지는 않습니다. 먼저 같은 모델과 요청으로 해당 기능을 끄거나 설정을 바꾼 실행을 비교하세요. 그 뒤 프롬프트 길이, 동시 요청 수, 최대 배치 토큰 설정을 기록하면 특정 요청 조건에 묶인 오류인지 구분하는 데 도움이 됩니다.

실제 매개변수 이름과 기본값은 설치된 vLLM 버전의 문서를 기준으로 해야 합니다. 버전이 다른 예제 설정을 가져오거나, 한 번에 여러 값을 바꾸면 원인을 좁히기 어렵습니다. 긴 프롬프트에서만 재현되는지, 짧은 요청에서도 발생하는지 나누어 기록하고, 변경은 한 번에 하나씩 진행합니다.

자주 묻는 배포 질문

설치할 CUDA 버전은 무엇을 기준으로 고르면 되나요?

CUDA 13.5를 전제로 두지 말고, 먼저 설치하려는 vLLM 버전과 설치 형태를 정합니다. 확인 기준일의 NVIDIA 아카이브와 앞서 연결한 vLLM 배포 자료를 대조하고, 드라이버와 PyTorch 백엔드도 함께 확인해야 합니다. 설치 자료에 표시된 빌드 선택지는 모든 환경에 통용되는 단일 명령이 아니라, 해당 vLLM 버전과 설치 방식에 따라 검토할 항목입니다.

빌드 실패가 PyTorch 문제인지 CUDA 문제인지 어떻게 좁히나요?

드라이버, 파이토치가 인식한 CUDA 백엔드, vLLM 설치 출처를 먼저 기록합니다. 장치 인식은 되는데 vLLM 확장 모듈에서 실패한다면 빌드 조합을 우선 의심하고, 시작 단계에서 런타임 오류가 난다면 드라이버와 런타임 연결도 확인합니다. 앞서 연결한 NVIDIA 호환성 안내와 vLLM 설치 자료를 함께 사용합니다.

FP4 모델 오류에서 먼저 볼 설정은 무엇인가요?

모델 카드와 가중치 설정에 적힌 형식, 양자화 도구 체인, 실행 백엔드 지원 여부를 차례로 확인합니다. NVFP4와 INT4는 같은 실행 형식이 아니므로 비트 수만으로 판단하지 않습니다. 앞서 연결한 NVFP4 방식 안내와 ModelOpt 체크포인트 문서를 대조한 뒤, 로딩 오류와 연산자 오류, 출력 이상을 각각 분리해 기록합니다.

Chunked Prefill을 바꾼 뒤 오류가 나면 무엇을 비교하나요?

동일한 모델과 요청에서 기능을 끄거나 매개변수를 바꾼 대조 실행을 합니다. 프롬프트 길이와 동시 요청, 최대 배치 토큰 설정을 함께 기록하고, 긴 입력에만 발생하는지 확인합니다. 오류가 사라져도 메모리 문제가 해결됐다고 단정하지 말고 가중치와 KV 캐시 사용량을 별도로 점검합니다. 설정값은 설치된 vLLM 버전의 안내에 맞춥니다.

메모리 문제는 모델 이름이 아니라 실제 상주 항목으로 판단합니다

RTX 5090의 메모리 한계 안에서 모델을 안정적으로 추론할 수 있는지는 가중치만으로 결정되지 않습니다. 양자화 스케일, 실행 작업 공간, KV 캐시도 계산에 포함해야 합니다. 이론 추정치는 모델 설정과 요청 길이를 전제로 한 가늠값이며, 실제 측정값과 섞어 쓰지 않습니다.

MoE 모델은 한 토큰을 생성할 때 활성화되는 매개변수 수와 GPU에 올려야 하는 전체 가중치 규모가 다를 수 있습니다. Meta는 Llama 4 소개 자료에서 Scout를 전체 매개변수 109B, 활성 매개변수 17B로, Maverick을 전체 400B, 활성 17B로 설명합니다. 따라서 Llama 4를 통칭해 “120B 모델”이라고 부르거나 활성 매개변수만으로 단일 GPU 상주 여부를 정하면 안 됩니다.

추론 판단 항목 이론상 확인 실제 실행에서 확인
가중치 모델 크기와 양자화 형식을 확인합니다. 모델 로딩 완료 여부와 로딩 직후 메모리를 기록합니다.
추가 가중치 정보 양자화 스케일과 모델 설정을 확인합니다. 형식에 맞는 실행 경로인지 검증합니다.
실행 작업 공간 사용하는 백엔드와 연산 경로를 확인합니다. 시작 시점과 요청 처리 중 메모리 변화를 기록합니다.
KV 캐시 목표 프롬프트와 생성 조건을 반영합니다. 목표 길이와 동시 요청 조건으로 별도 시험합니다.

재현 가능한 점검 기록을 남깁니다

문제를 다시 확인할 수 있도록 아래 항목을 체크합니다.

  • [ ] GPU와 드라이버 정보, 컨테이너 또는 호스트 설치 여부를 기록합니다.
  • [ ] PyTorch 버전과 CUDA 백엔드, vLLM 버전 및 설치 출처를 함께 남깁니다.
  • [ ] 모델 설정, 양자화 형식, 전체 오류 로그와 실행 매개변수를 보관합니다.
  • [ ] 요청 시 프롬프트 길이, 동시 요청 수, 배치 토큰 설정과 메모리 상태를 기록합니다.
  • [ ] 설치 완료, 모델 로딩, 짧은 요청, 목표 문맥 길이 순으로 확인합니다.
  • [ ] 한 번에 한 변수만 바꾸고, 커뮤니티 이슈는 재현 전까지 개별 사례로 취급합니다.
확인 단계 통과 조건 실패하면 돌아갈 항목
설치 선택한 vLLM 빌드 설치가 끝나고 모듈을 불러옵니다. 휠·빌드와 파이썬 환경을 다시 대조합니다.
로딩 모델과 양자화 형식이 오류 없이 초기화됩니다. 모델 설정, 형식, 백엔드 지원을 다시 확인합니다.
짧은 요청 기본 요청에서 출력이 재현됩니다. 토크나이저와 실행 경로, 전체 로그를 확인합니다.
목표 조건 목표 문맥과 요청 부하에서 안정적으로 처리됩니다. KV 캐시와 작업 공간, 요청 설정을 다시 분리합니다.

개발 환경과 CUDA 추론 장비는 역할을 나눕니다

현재 장비 한 대에 편집, 코드 실행, 컨테이너 관리, CUDA 추론을 모두 맡기면 드라이버 변경이 개발 환경까지 흔들 수 있고, vLLM 빌드 충돌을 분리하기 어려우며, 대형 모델 시험 중 다른 작업의 자원을 예측하기도 어렵습니다. 클라우드 맥은 CUDA 추론을 수행하는 대체 장비가 아닙니다. 다만 코드 편집과 배포 정리 같은 비 CUDA 작업을 분리하고, RTX 5090을 로컬 추론에 남기는 운영 방식은 검토할 수 있습니다.

따라서 CUDA 커널과 로컬 GPU 검증이 핵심인 작업은 RTX 5090 환경을 유지하고, 개발 도구와 비 CUDA 작업을 분리할 이유가 있을 때만 클라우드 맥을 비교하는 것이 적절합니다. KuzCloud의 이용 환경 확인 경로에서 제공 조건을 먼저 확인하고, 계정 이용 절차는 KuzCloud 콘솔에서 검토할 수 있습니다. 클라우드 맥은 CUDA 추론 서버로 간주하지 말고, 현재 환경과 분리할 작업이 분명할 때만 선택해야 합니다.

쿠다 점검은 마쳤다면, 원격 개발용 전용 맥도 준비해 보세요

쿠즈클라우드는 그래픽 연산 장비가 아닌 전용 맥 미니를 제공하므로 쿠다 실행 환경과는 별도의 개발 및 빌드 작업에 활용하실 수 있습니다.

가상화 오버헤드 없이 전용 하드웨어와 관리자 권한을 사용해 필요한 개발 도구를 자유롭게 구성하실 수 있습니다.