RTX로 vLLM 돌려보기: Rocky Linux 9·Ubuntu 24.04·26.04

MaruOps

2026.10.23

참고 사진 · 나무 탁자에 세워 놓은 Gigabyte GeForce RTX 3090 그래픽카드의 냉각팬 세 개 · 사진: PantheraLeo1359531 / 원본 / CC BY 4.0 · 목록용 크기 조정

게임을 돌리던 RTX에 AI 서버라는 새 역할을 맡겨볼 수 있어요. 작은 언어 모델을 GPU에 올리고, 내 서버의 HTTP 주소로 질문을 보내 답을 받는 것이 이 글의 실습입니다. Rocky Linux 9와 Ubuntu 24.04·26.04에서 NVIDIA RTX로 시작하고, AMD·Intel GPU를 쓸 때 달라지는 부분도 이어서 살펴봅니다.

기준일은 2026년 10월 22일이며, 예제 이미지는 v0.32.0으로 고정합니다. 공식 문서와 배포 이미지 정보를 확인해 구성한 따라 하기 안내로, 세 운영체제에서 GPU 추론을 모두 실행·측정한 후기는 아닙니다. 본문의 스크린샷은 실제 공식 문서 화면이며, 대표 사진은 참고용 RTX 3090 사진입니다.

이 글의 목차

내 GPU에 맞는 경로부터 고릅니다

RTX는 CUDA, 지원되는 AMD GPU는 ROCm, 지원되는 Intel GPU는 XPU 경로를 사용합니다. GPU 제조사가 바뀌면 이미지와 호스트 드라이버도 함께 바뀝니다. 컨테이너가 설치 차이는 줄여주지만, 지원되지 않는 GPU를 지원되는 GPU로 바꿔주지는 않아요.

GPU	실행 경로	먼저 확인할 조건
NVIDIA RTX 20·30·40·50 계열 등	`vllm/vllm-openai`	vLLM의 Compute Capability 7.5 이상 조건, 드라이버와 이미지 CUDA 호환성
AMD Instinct·일부 Radeon/Ryzen GPU	`vllm/vllm-openai-rocm`	정확한 GPU·gfx 아키텍처·ROCm·OS·커널 조합
지원되는 Intel Arc·데이터센터 GPU	`vllm/vllm-openai-xpu`	검증 하드웨어 목록, Intel 드라이버와 런타임 조합

Compute Capability는 NVIDIA GPU가 지원하는 연산 기능의 세대 구분입니다. VRAM 용량과는 다른 값이에요. 위 표의 제품군만 보고 개별 모델의 모든 기능까지 지원된다고 판단하지 말고 vLLM GPU 설치 문서에서 자신의 모델을 대조합니다.

vLLM 공식 문서의 NVIDIA CUDA 탭에 Linux와 Compute Capability 7.5 이상 요구 조건이 표시된 화면 — NVIDIA 탭에서 확인할 것은 GPU 세대 조건입니다 · 2026-10-22 실제 문서 화면 캡처. 출처: vLLM 프로젝트 / Apache-2.0. 추론 실행 결과 화면이 아닙니다. 읽을 부분만 잘라 표시했습니다.

vLLM이 하는 일과 첫 모델 선택

vLLM은 언어 모델의 추론과 API 제공을 맡는 엔진입니다. 모델이 요리사라면 vLLM은 들어온 주문을 모아 GPU 주방에 배분하는 역할에 가깝습니다. 질문을 동시에 받는 서비스를 만들 때 유용하지만, 설치만으로 모든 모델의 답변 품질이 좋아지거나 한 명의 요청이 항상 가장 빨라지는 것은 아닙니다. (vLLM 소개)

첫 모델은 Qwen/Qwen2.5-1.5B-Instruct로 정합니다. 1.5B급의 작은 대화용 모델이고, 공식 모델 카드에서 Apache-2.0 라이선스와 vLLM 사용 예를 확인할 수 있습니다. 최신 대형 모델을 뽐내기보다 다운로드 → GPU 적재 → 첫 응답의 연결부터 확인하기 좋은 출발점이에요. (Qwen 공식 모델 카드)

GPU 메모리인 VRAM에는 가중치뿐 아니라 계산 중간값과 KV 캐시도 들어갑니다. KV 캐시는 앞서 처리한 토큰의 attention 계산에 쓰는 값을 보관하는 공간입니다. 입력이 길어지거나 동시에 처리하는 대화가 많아지면 필요한 양도 커집니다.

모델 규모	16비트 가중치만 단순 계산	해석
1.5B	약 3GB	첫 적재와 API 연결 확인용
7B	약 14GB	16GB VRAM에 나머지 공간이 충분하다고 단정할 수 없음
8B	약 16GB	16GB VRAM에 전체 실행 공간이 들어간다는 뜻은 아님

이 표는 파라미터 수 × 2바이트로 계산한 가중치의 거친 추정이며, GPU별 실행 보장이나 실측값이 아닙니다. 처음에는 짧은 문맥과 적은 동시 요청으로 시작합니다. 메모리가 부족하면 모델 크기와 문맥 길이를 먼저 줄이는 편이 원인을 찾기 쉽습니다. (vLLM 메모리 절약 안내)

Rocky Linux 9·Ubuntu 24.04·26.04 준비

예제는 x86_64 호스트, 관리자 권한, Docker Engine이 설치된 일반 Docker 환경을 기준으로 합니다. GPU를 전달받지 않은 가상머신에서는 진행할 수 없습니다. Rootless Docker·Podman은 런타임 설정이 달라 별도 절차가 필요합니다.

cat /etc/os-release
uname -r
uname -m
lspci -nn | grep -Ei 'VGA|3D|Display'
sudo docker version

lspci가 없다면 Rocky는 sudo dnf install pciutils, Ubuntu는 sudo apt install pciutils로 설치합니다. docker version에서 Client와 Server가 모두 보여야 합니다. Docker가 없다면 Ubuntu용 공식 설치 절차 또는 RPM 계열 Docker 설치 절차와 배포판의 지원 범위를 먼저 확인합니다. 기존 컨테이너 서버에서 패키지를 일괄 삭제하는 명령부터 실행하지 마세요.

운영체제	이 글의 NVIDIA 준비 경로	버전 확인 지점
Rocky Linux 9	DNF 드라이버 → RPM Toolkit 저장소	Toolkit 지원표에 명시된 소버전은 9.7. 자신의 9.x·커널과 따로 대조
Ubuntu 24.04 LTS	Ubuntu 드라이버 도구 → DEB Toolkit 저장소	Docker와 Toolkit 지원표에 24.04 명시
Ubuntu 26.04 LTS	Ubuntu 드라이버 도구 → DEB Toolkit 저장소	Docker와 Toolkit 지원표에 26.04 명시

2026-10-22 확인한 NVIDIA Container Toolkit 지원표와 Docker Ubuntu 지원표를 기준으로 작성했습니다. 이 표는 NVIDIA 컨테이너 구성에 관한 것으로, 같은 OS에서 AMD·Intel까지 자동으로 검증됐다는 의미는 아닙니다.

Ubuntu 24.04·26.04: NVIDIA 드라이버

이미 nvidia-smi가 정상 동작하고 이미지의 드라이버 조건을 충족한다면 재설치는 생략합니다. 새 실습 장비에서는 Ubuntu의 드라이버 도구로 후보를 확인한 뒤 설치할 수 있습니다. 기존 NVIDIA 저장소나 수동 .run 설치와 섞기 전에는 설치 방식을 정리해야 합니다. (Ubuntu 공식 NVIDIA 드라이버 안내)

sudo apt update
sudo apt install -y ubuntu-drivers-common pciutils
ubuntu-drivers devices
sudo ubuntu-drivers install
sudo reboot

재부팅이 끝난 뒤 다시 접속해 nvidia-smi로 GPU와 Driver Version을 확인합니다. Secure Boot를 사용하는 장비는 모듈 서명·키 등록 절차도 확인합니다. 자동 추천 드라이버가 아래 이미지에 필요한 CUDA 13 조건을 충족하지 못하면 그대로 진행하지 말고, 해당 GPU와 Ubuntu 버전을 지원하는 최신 드라이버 설치 경로를 확인합니다.

Rocky Linux 9: NVIDIA 드라이버

아래는 기존 드라이버 설치가 없는 x86_64 실습 장비와 RTX 등 Turing 이후 GPU를 위한 NVIDIA 공식 RPM 저장소 경로입니다. rhel9는 Rocky 9에서 사용하는 저장소 식별자입니다. 설치된 드라이버가 정상이라면 이 단계는 건너뜁니다. (NVIDIA의 Rocky Linux 설치 안내)

sudo dnf install -y dnf-plugins-core pciutils
sudo dnf install -y kernel-devel-matched kernel-headers
sudo dnf config-manager --set-enabled crb
sudo dnf install -y epel-release
sudo dnf config-manager --add-repo \
  https://developer.download.nvidia.com/compute/cuda/repos/rhel9/x86_64/cuda-rhel9.repo
sudo dnf clean expire-cache
sudo dnf module enable -y nvidia-driver:open-dkms
sudo dnf install -y nvidia-open
sudo reboot

open-dkms의 open은 NVIDIA 커널 모듈의 종류를 뜻합니다. AMD 드라이버나 Nouveau를 설치하는 명령이 아닙니다. 재부팅 후에도 모듈이 올라오지 않으면 현재 커널과 개발 패키지의 일치 여부, DKMS 빌드 상태, Secure Boot 서명을 확인합니다. 원인을 확인하지 않은 채 SELinux부터 끄지는 않습니다.

호스트 GPU를 Docker 안으로 연결

호스트에서 GPU가 보이는 것과 컨테이너에서 GPU가 보이는 것은 두 단계입니다. 먼저 호스트에서 다음 명령이 성공해야 합니다. 실패하면 vLLM을 설치하기 전에 드라이버부터 해결합니다.

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

이 글에서 확인한 vllm/vllm-openai:v0.32.0의 amd64 이미지 설정에는 CUDA 13.0.2가 기록돼 있습니다. CUDA 13 계열의 일반 실행에는 R580 이상 드라이버가 필요하며, 실제 GPU·기능에 따라 더 새 드라이버가 필요할 수 있습니다. GeForce RTX에 데이터센터 GPU용 호환성 우회 설정을 그대로 적용하지 마세요. (공식 이미지 태그, NVIDIA CUDA 드라이버 호환 조건)

nvidia-smi 상단의 CUDA Version은 호스트 드라이버가 지원하는 CUDA 수준입니다. 호스트에 설치한 CUDA Toolkit이나 컨테이너 안의 CUDA 버전을 그대로 뜻하지 않습니다. 아래 컨테이너 방식은 호스트의 nvcc 설치를 전제로 하지 않습니다.

Ubuntu 24.04·26.04용 Toolkit

NVIDIA의 DEB 저장소와 서명 키를 등록합니다. 이미 같은 저장소가 설정돼 있다면 중복 등록하지 말고 기존 파일부터 확인합니다. 다음 코드는 일반 Docker용입니다. (NVIDIA Container Toolkit 설치 문서)

sudo apt install -y curl ca-certificates gnupg
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey \
  -o /tmp/nvidia-container-toolkit-gpgkey
sudo gpg --dearmor \
  -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  /tmp/nvidia-container-toolkit-gpgkey
curl -fsSL https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list \
  -o /tmp/nvidia-container-toolkit.list
sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' \
  /tmp/nvidia-container-toolkit.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt update
sudo apt install -y nvidia-container-toolkit

Rocky Linux 9용 Toolkit

Rocky에서는 같은 Toolkit을 RPM 저장소에서 설치합니다. 위 Ubuntu 명령과 이 명령을 모두 실행하는 것이 아니라, 자신의 OS에 맞는 한 쪽만 선택합니다.

sudo dnf install -y curl
curl -fsSL https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo \
  -o /tmp/nvidia-container-toolkit.repo
sudo install -m 0644 /tmp/nvidia-container-toolkit.repo \
  /etc/yum.repos.d/nvidia-container-toolkit.repo
sudo dnf install -y nvidia-container-toolkit

공통 런타임 설정과 GPU 확인

이제 Docker에 NVIDIA 런타임을 등록합니다. nvidia-ctk가 /etc/docker/daemon.json을 수정하므로 기존 설정을 보관합니다. Docker 재시작은 실행 중인 다른 컨테이너에 영향을 줄 수 있으므로 운영 서버에서는 작업 시간을 확보한 뒤 진행합니다.

if sudo test -f /etc/docker/daemon.json; then
  sudo cp -a /etc/docker/daemon.json "/etc/docker/daemon.json.before-nvidia-$(date +%Y%m%d-%H%M%S)"
fi
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

sudo docker pull vllm/vllm-openai:v0.32.0
sudo docker run --rm --runtime nvidia --gpus all \
  --entrypoint nvidia-smi \
  vllm/vllm-openai:v0.32.0

컨테이너 안에서도 GPU 이름과 드라이버 정보가 보여야 합니다. 여기까지 통과하면 호스트 드라이버 → Toolkit → Docker의 연결을 확인한 셈입니다. 아직 모델 적재나 추론까지 검증한 것은 아닙니다. (Docker 런타임 설정 근거)

RTX에서 작은 모델로 서버 실행

첫 실행에서는 가중치를 다운로드하고 실행 준비를 하므로 시간이 걸릴 수 있습니다. 모델 캐시는 Docker의 named volume에 보관합니다. Rocky의 SELinux 환경에서 임의의 홈 디렉터리를 바인드 마운트할 때 생길 수 있는 레이블 문제도 줄일 수 있어요.

sudo docker volume create maruops-vllm-hf-cache
sudo docker volume create maruops-vllm-compile-cache

sudo docker run -d --name maruops-vllm \
  --runtime nvidia --gpus '"device=0"' \
  --shm-size=4g \
  -p 127.0.0.1:8000:8000 \
  -v maruops-vllm-hf-cache:/root/.cache/huggingface \
  -v maruops-vllm-compile-cache:/root/.cache/vllm \
  vllm/vllm-openai:v0.32.0 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --served-model-name local-qwen \
  --host 0.0.0.0 --port 8000 \
  --dtype half \
  --max-model-len 2048 \
  --max-num-seqs 2 \
  --gpu-memory-utilization 0.80

sudo docker logs -f maruops-vllm

device=0은 첫 번째 GPU를 선택합니다. 여러 GPU가 있다면 호스트의 nvidia-smi에서 번호를 확인해 바꿉니다. --dtype half는 FP16을 사용하고, 2048은 입력과 출력을 합친 최대 문맥 길이입니다. --max-num-seqs 2는 동시에 실행하는 시퀀스 수를 제한합니다. 이 값들은 작은 실습의 시작값이며 모든 카드에서 동작을 보장하는 최소 사양이 아닙니다.

--gpu-memory-utilization 0.80은 엔진이 사용할 GPU 메모리 예산의 비율입니다. 모델을 80% 크기로 압축하는 옵션이 아니에요. --shm-size=4g도 GPU VRAM을 늘리지 않습니다. 프로세스 간 공유 메모리 공간의 상한이며, 실제 호스트 RAM 여유가 필요합니다. (vLLM 실행 옵션, 공식 컨테이너 사용법)

서버 내부는 컨테이너의 0.0.0.0:8000에서 듣고, 호스트에는 127.0.0.1:8000만 공개합니다. 인증 없는 실습 API를 인터넷 전체에 열지 않기 위한 설정입니다. 로그를 보고 준비가 끝나면 Ctrl+C로 로그 보기만 종료합니다. -d로 띄운 서버는 계속 실행됩니다.

첫 질문: GPU에게 야간 근무를 부탁합니다

같은 서버의 다른 터미널에서 모델 목록을 조회합니다. 모델 다운로드나 엔진 초기화가 끝나지 않았다면 잠시 기다린 뒤 로그를 확인합니다. 단순히 컨테이너가 Running 상태라는 것만으로 API가 준비됐다고 판단하지 않습니다.

curl --fail-with-body -sS http://127.0.0.1:8000/v1/models

목록에서 local-qwen을 확인했다면 대화를 보냅니다. --served-model-name으로 정한 별칭과 요청의 model이 일치해야 합니다. vLLM의 Chat Completions 경로를 호출하는 것이며 외부 AI 서비스에 보내는 요청이 아닙니다. (vLLM API 문서)

curl --fail-with-body -sS http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "model": "local-qwen",
  "messages": [
    {"role": "system", "content": "한국어로 간결하게 답하세요."},
    {"role": "user", "content": "너는 오늘부터 GPU 야간 근무 담당이야. 자기소개를 두 문장으로 해줘."}
  ],
  "temperature": 0.7,
  "max_tokens": 160
}
JSON

성공하면 JSON 응답의 choices[0].message.content에서 답변을 읽습니다. 문장 내용은 실행마다 달라질 수 있으므로 고정된 정답 문구를 기다릴 필요는 없어요. usage가 있으면 입력·출력 토큰 수도 함께 확인합니다. 이 글에는 실행하지 않은 답변이나 속도 수치를 결과처럼 만들어 넣지 않았습니다.

다른 PC에서 접속하고 싶다면 실습 단계에서는 SSH 터널을 사용할 수 있습니다. 다음 명령은 접속할 PC에서 실행하며, user와 gpu-host는 실제 SSH 계정과 서버 주소로 바꿉니다.

ssh -L 18000:127.0.0.1:8000 user@gpu-host

터널을 연 PC에서는 http://127.0.0.1:18000/v1/models로 접속합니다. 공개 서비스로 바꿀 때는 TLS·인증·요청 제한을 별도로 구성합니다. 단순히 포트의 127.0.0.1: 부분을 지우는 것으로 운영 구성을 마치지는 않습니다.

AMD GPU: ROCm 경로로 바꾸기

AMD에서는 nvidia-smi와 NVIDIA Container Toolkit 대신 amdgpu 드라이버·ROCm과 장치 전달을 확인합니다. vLLM 문서에는 MI200·MI300·MI350, RX 7900·RX 9000 계열과 일부 Ryzen AI GPU가 명시돼 있습니다. 같은 Radeon 이름을 쓰더라도 모든 제품이 대상은 아닙니다. (vLLM ROCm 요구 조건)

vLLM 공식 문서 AMD ROCm 탭에 지원 GPU의 gfx 코드와 ROCm 버전 조건이 표시된 화면 — AMD 탭에서는 제품명뿐 아니라 gfx 코드도 대조합니다 · 2026-10-22 실제 문서 화면 캡처. 출처: vLLM 프로젝트 / Apache-2.0. 추론 실행 결과 화면이 아닙니다. 읽을 부분만 잘라 표시했습니다.

확인한 vllm/vllm-openai-rocm:v0.32.0의 빌드 이력은 ROCm 7.2.3 기반입니다. 해당 버전의 OS 표에는 Ubuntu 24.04.4와 Rocky Linux 9가 있지만 Ubuntu 26.04는 없습니다. 따라서 아래 명령을 26.04에서 공식 지원되는 조합으로 안내하지 않습니다. 26.04를 유지하려면 지원이 명시된 더 새 ROCm 이미지·호스트 드라이버 조합을 별도로 선정해야 합니다. (ROCm 7.2.3 버전별 호환성 표)

Ubuntu 24.04와 Rocky 9에서도 정확한 GPU·OS 소버전·커널 조건을 대조합니다. 특히 Radeon용 표와 Instinct용 표를 섞으면 안 됩니다. Rocky 9의 지원 각주가 특정 Instinct 제품에만 해당하는지도 확인하세요. 최신 표의 OS 지원을 이전 이미지에 소급 적용하지 않습니다. (AMD 최신 GPU·OS 호환성 선택표)

맞는 호스트 드라이버와 ROCm을 설치했다면 먼저 장치와 GPU를 확인합니다. /dev/kfd와 /dev/dri가 있어야 하며 rocminfo에서 자신의 GPU에 해당하는 gfx... 이름을 찾습니다. 패키지 설치는 위 AMD 지원표에서 선택한 배포판·GPU의 절차를 따릅니다.

ls -l /dev/kfd /dev/dri
rocminfo

NVIDIA 실습을 같은 호스트에서 진행했다면 먼저 sudo docker stop maruops-vllm으로 8000번 포트를 비웁니다. 다음은 지원 조합을 확인한 단일 AMD GPU 실습 장비용입니다. 호스트에서 인식되는 GPU와 이미지의 커널 지원이 맞아야 실행됩니다.

VLLM_RENDER_GID=$(stat -c '%g' /dev/dri/renderD128)
VLLM_KFD_GID=$(stat -c '%g' /dev/kfd)
sudo docker volume create maruops-vllm-amd-hf-cache

sudo docker run -d --name maruops-vllm-amd \
  --device /dev/kfd --device /dev/dri \
  --group-add "$VLLM_RENDER_GID" --group-add "$VLLM_KFD_GID" \
  --shm-size=4g \
  -p 127.0.0.1:8000:8000 \
  -v maruops-vllm-amd-hf-cache:/root/.cache/huggingface \
  vllm/vllm-openai-rocm:v0.32.0 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --served-model-name local-qwen \
  --host 0.0.0.0 --port 8000 \
  --dtype half \
  --max-model-len 2048 \
  --max-num-seqs 2 \
  --gpu-memory-utilization 0.80

sudo docker logs -f maruops-vllm-amd

renderD128은 예시 장치명입니다. 앞의 ls 결과가 다르면 자신의 GPU 장치로 바꿉니다. 그룹 이름이 컨테이너와 호스트에서 달라도 접근 권한을 맞출 수 있도록 장치의 숫자 그룹 ID를 전달합니다. 공식 ROCm 예제의 SYS_PTRACE와 seccomp=unconfined는 우선 제외했으며, 보안 정책 오류가 생기면 로그와 공식 예제를 대조해 필요한 범위를 판단합니다. 준비가 끝나면 앞의 curl 요청을 그대로 사용할 수 있습니다. (vLLM 공식 ROCm 이미지와 실행 예)

Intel GPU: XPU 이미지를 따로 사용

Intel은 XPU 백엔드를 사용합니다. vLLM v0.32.0의 검증 하드웨어 문서에는 Intel Arc Pro B-Series가 표시돼 있습니다. 설치 문서의 폭넓은 Arc·데이터센터 GPU 언급과 이 검증 목록은 구분해서 읽어야 합니다. 일반 Intel 내장 그래픽까지 전부 검증됐다는 뜻은 아닙니다. (vLLM Intel 검증 하드웨어·모델 목록)

vLLM 공식 Intel XPU 탭에 Intel GPU 지원 경로와 XPU 커널의 Python 3.12 조건이 표시된 화면 — Intel의 Python 직접 설치는 XPU 패키지의 버전 조건도 따릅니다 · 2026-10-22 실제 문서 화면 캡처. 출처: vLLM 프로젝트 / Apache-2.0. 추론 실행 결과 화면이 아닙니다. 읽을 부분만 잘라 표시했습니다.

Rocky 9·Ubuntu 24.04·26.04 중 어느 OS든 먼저 Intel GPU 드라이버 설치 문서에서 GPU 모델과 OS·커널·런타임의 지원 조합을 확인합니다. 컨테이너가 호스트 커널 드라이버를 대신하지는 않습니다. Python 직접 설치 시 문서에 나온 XPU 커널의 Python 3.12 조건도 지켜야 하므로, 여기서는 전용 이미지로 환경을 구분합니다.

다음은 지원 드라이버를 설치한 단일 Intel GPU 실습 호스트에서 장치 접근을 확인하는 시작 명령입니다. 앞서 띄운 NVIDIA·AMD 컨테이너가 있다면 중지해 8000번 포트를 비웁니다.

ls -l /dev/dri
VLLM_RENDER_GID=$(stat -c '%g' /dev/dri/renderD128)
sudo docker volume create maruops-vllm-intel-hf-cache

sudo docker run -d --name maruops-vllm-intel \
  --device /dev/dri:/dev/dri \
  --group-add "$VLLM_RENDER_GID" \
  --shm-size=4g \
  -p 127.0.0.1:8000:8000 \
  -v maruops-vllm-intel-hf-cache:/root/.cache/huggingface \
  vllm/vllm-openai-xpu:v0.32.0 \
  --model Qwen/Qwen2.5-1.5B-Instruct \
  --served-model-name local-qwen \
  --host 0.0.0.0 --port 8000 \
  --dtype half \
  --max-model-len 2048 \
  --max-num-seqs 2 \
  --gpu-memory-utilization 0.80

sudo docker logs -f maruops-vllm-intel

renderD128이 자신의 GPU 장치인지 확인하고 필요하면 바꿉니다. 공식 XPU 예제는 --privileged, 호스트 네트워크, /dev/dri/by-path 마운트를 포함합니다. 위 명령은 단일 GPU의 기본 접근을 먼저 시도하도록 그보다 권한을 줄인 예제이며, 모든 Intel 환경에서 동일하게 동작한다고 검증한 명령은 아닙니다. 장치 탐색이나 통신에서 실패하면 공식 XPU 실행 옵션과 드라이버 문서를 대조합니다.

VRAM이 부족할 때 조정할 순서

큰 모델을 올렸을 때 GPU가 답 대신 OOM을 내놓는다면, OOM은 Out Of Memory, 메모리 부족의 줄임말입니다. 여기서는 옵션을 한꺼번에 바꾸기보다 어느 공간이 부족한지 나눠 봅니다. (공식 메모리 절약 방법)

다른 GPU 작업 확인: NVIDIA는 nvidia-smi에서 사용 프로세스와 남은 메모리를 봅니다. 다른 사람의 프로세스를 임의로 종료하지 않습니다.
모델부터 축소: 가중치 적재 중 실패하면 문맥 길이만 줄여서는 해결되지 않을 수 있습니다. 더 작은 모델이나 해당 GPU가 지원하는 양자화 모델을 검토합니다.
문맥 길이 축소: KV 캐시 공간이 부족하면 --max-model-len 1024처럼 줄이고, 요청의 입력+출력도 그 범위에 맞춥니다.
동시 실행 수 축소: --max-num-seqs 1로 시작해 단일 요청을 먼저 확인합니다.
CUDA 그래프 영향 분리: NVIDIA에서 그래프 캡처 중 메모리 문제가 생기면 --enforce-eager를 임시로 비교합니다. 성능 특성이 달라지므로 자동으로 더 좋은 설정은 아닙니다.

--gpu-memory-utilization을 낮추면 엔진이 사용할 예산도 줄어듭니다. 다른 프로그램에 여유를 남길 때는 도움이 되지만 이미 부족한 KV 캐시를 더 줄일 수도 있습니다. 반대로 무작정 0.99까지 높이면 화면 출력이나 다른 작업과 충돌할 수 있어요. VRAM을 새로 만들어주는 마법의 숫자는 없습니다.

양자화는 가중치를 더 낮은 비트 수로 표현하는 방법입니다. AWQ·GPTQ·FP8 같은 형식의 지원 범위는 GPU 세대와 백엔드에 따라 다릅니다. 다른 카드의 성공 예에 나온 --quantization 값부터 복사하기보다 vLLM 양자화 하드웨어 지원표를 확인합니다.

실패한 위치로 원인을 좁힙니다

멈춘 지점·증상	우선 확인할 항목	다음 확인
호스트 `nvidia-smi` 실패	드라이버 모듈, 재부팅, Secure Boot	현재 커널·DKMS·GPU 패스스루
호스트는 성공, Docker에서 GPU 선택 실패	Toolkit 설치와 Docker 런타임 등록	`sudo docker info`, 런타임 설정 후 재시작 여부
CUDA 드라이버가 오래됐다는 오류	선택 이미지의 CUDA와 호스트 드라이버	이 글의 CUDA 13 이미지 조건, GPU가 지원하는 드라이버
`no kernel image`·`invalid device function`	GPU 아키텍처와 이미지의 커널 지원	NVIDIA Compute Capability 또는 AMD gfx 대상
모델 다운로드 401·403	모델 접근권한·라이선스 동의·토큰	Hugging Face의 실제 해당 모델 페이지
요청만 연결 실패·포트 충돌	초기화 로그·포트 점유·접속 위치	`sudo docker ps -a`, `ss -ltn`, SSH 터널
모델을 찾지 못한다는 API 오류	`local-qwen` 별칭 일치 여부	`/v1/models` 목록과 요청 JSON

모델 접근 오류는 GPU 연산 오류와 다릅니다. 이 글의 공개 모델 대신 승인이 필요한 모델로 바꾸었다면 토큰과 동의 상태를 먼저 확인합니다. 실제 토큰은 글·스크린샷·명령 이력에 노출하지 않도록 관리합니다. 문제 해결 시에는 마지막 줄뿐 아니라 첫 오류와 그 앞의 초기화 로그를 함께 봅니다. (vLLM 문제 해결 문서)

종료·재실행과 다음 실험

NVIDIA 예제 서버를 멈추거나 다시 켤 때는 다음 명령을 사용합니다. AMD·Intel은 위에서 정한 컨테이너 이름으로 바꿉니다. 중지와 삭제는 다르며, 모델 캐시 volume은 아래 명령으로 삭제되지 않습니다.

# 서버 중지
sudo docker stop maruops-vllm

# 기존 컨테이너를 같은 설정으로 재시작
sudo docker start maruops-vllm

# 실행 옵션을 바꾸려면 중지 후 컨테이너를 지우고 새로 생성
sudo docker stop maruops-vllm
sudo docker rm maruops-vllm

첫 응답을 받았다면 질문을 하나 고정하고 문맥 길이·동시 요청 수·모델 크기를 한 번에 하나씩 바꿔보세요. 처음 적재하는 시간과 준비된 서버의 답변 시간은 따로 기록합니다. 같은 입력에서도 답변이 달라질 수 있으므로 품질과 속도도 구분해서 봅니다.

다음 실험은 적재 시간·첫 응답·생성 속도 따로 측정하기로 이어갈 수 있습니다. GPU가 주문을 받기 시작했다면, 이제는 얼마나 바쁘게 일하고 어디에서 기다리는지 볼 차례예요.

참고 문서와 이미지 출처

문서 화면 3장은 vLLM 공식 사이트를 실제 브라우저에서 캡처했습니다. 문서 내용은 변경하지 않았고 필요한 영역만 잘라 표시했습니다. © vLLM contributors, Apache License 2.0. 원문 라이선스 사본도 제공합니다. 대표 사진의 촬영자·원본·사용 조건은 사진 아래에 표시합니다.