GPU 설치

GPU 설치

vLLM은 Python 라이브러리이며 여러 GPU 변형을 지원해요. NVIDIA(CUDA), AMD(ROCm), Intel(XPU), Apple Silicon(vLLM-Metal)을 각각의 벤더별 지침에 따라 설치할 수 있어요. 이 문서에서는 GPU 환경에서 vLLM을 설치하고 실행하는 방법을 안내해요.

출처: 문서

본문

지원 GPU 변형

  • NVIDIA CUDA: vLLM에는 사전 컴파일된 C++ 및 CUDA(12.9) 바이너리가 포함돼요.

  • AMD ROCm: vLLM은 ROCm 6.3 이상의 AMD GPU를 지원해요. 사전 빌드 wheel은 ROCm 7.0과 ROCm 7.2.1용으로 제공돼요.

    ROCm Variant Python 버전 ROCm 버전 glibc 요구 지원 버전
    rocm700 3.12 7.0 >= 2.35 0.14.0 ~ 0.18.0
    rocm721 3.12 7.2.1 >= 2.35 commit 171775f306a333a9cf105bfd533bf3e113d401d9 이후 nightly

  • Intel XPU: Intel GPU 플랫폼에서 기본 모델 추론과 서빙을 지원해요.

  • Apple Silicon (vLLM-Metal): Apple Silicon에서 GPU 가속 추론을 하려면 MLX를 compute 백엔드로 사용하고 Apple의 Metal 프레임워크로 네이티브 GPU 가속을 제공하는 커뮤니티 유지 하드웨어 플러그인인 vLLM-Metal을 사용하세요. Hugging Face의 mlx-community 조직에서 제공하는 MLX 최적화 모델과 함께 동작하며, 이는 Apple Silicon에 최적화된 인기 모델의 양자화 버전을 제공해요.

요구 사항

NVIDIA CUDA

  • OS: Linux
  • Python: 3.10 ~ 3.13
    • 참고: vLLM은 Windows를 네이티브로 지원하지 않아요. Windows에서 vLLM을 실행하려면 호환 Linux 배포판의 WSL을 사용하거나 커뮤니티 포크(예: https://github.com/SystemPanic/vllm-windows)를 사용하세요.
  • GPU: compute capability 7.5 이상 (예: T4, RTX20xx, A100, L4, H100, B200 등)

AMD ROCm

  • GPU: MI200s (gfx90a), MI300 (gfx942), MI350 (gfx950), Radeon RX 7900 시리즈 (gfx1100/1101), Radeon RX 9000 시리즈 (gfx1200/1201), Ryzen AI MAX / AI 300 시리즈 (gfx1151/1150)
  • ROCm 6.3 이상. MI350은 ROCm 7.0 이상, Ryzen AI MAX / AI 300 시리즈는 ROCm 7.0.2 이상 필요

Intel XPU

  • 지원 하드웨어: Intel Data Center GPU, Intel ARC GPU
  • 의존성: vllm-xpu-kernels — Intel GPU 플랫폼에서 vLLM을 실행할 때 필요한 모든 커스텀 커널을 제공하는 패키지
  • Python: 3.12 (제공되는 vllm-xpu-kernels whl은 Python 3.12 전용이므로 필수)

vLLM-Metal

  • OS: macOS Sonoma 이상
  • 하드웨어: Apple Silicon
  • Metal 지원 활성화

Python으로 설정하기

새 Python 환경 만들기

빠른 Python 환경 관리자인 uv를 권장해요:

uv venv --python 3.12 --seed --managed-python
source .venv/bin/activate

참고: conda로 설치한 PyTorch는 NCCL 라이브러리를 정적으로 링크하는데, vLLM이 NCCL을 사용할 때 문제가 될 수 있어요 (Issue #8420). 성능을 위해 vLLM은 많은 CUDA 커널을 컴파일해야 해요. 이 컴파일은 다른 CUDA 버전, 같은 PyTorch 버전이라도 빌드 구성이 다르면 바이너리 비호환성을 만들기 때문이에요. 따라서 새 환경에서 vLLM을 설치하는 것을 권장해요. 다른 CUDA 버전을 쓰거나 기존 PyTorch 설치를 쓰려면 소스에서 vLLM을 빌드해야 해요. vLLM wheel은 PyTorch와 모든 필요 의존성을 묶으므로 호환성을 위해 포함된 PyTorch를 사용해야 해요.

vLLM-Metal로 설정

vLLM-Metal은 Apple Silicon에서 네이티브 GPU 가속을 제공하는 별도 패키지로 배포돼요. 설치 문서를 따라 다음을 수행하면 돼요: ① 적절한 Python 환경 설정, ② MLX 및 필요 의존성 설치, ③ vLLM-Metal 패키지 설치. 최상의 성능을 위해 mlx-community 모델(4/8-bit 양자화 버전 포함)을 사용하세요. 예: mlx-community/Qwen2.5-0.5B-Instruct-4bit.

vLLM-Metal 사용법:

# Activate the vLLM-Metal environment
source ~/.venv-vllm-metal/bin/activate

# Start the API server (specify your mlx-community model or it will use default)
vllm serve

2~3분 후 INFO: Application startup complete.가 보일 때까지 기다리세요. 이후 대화형 vllm chat, curl API 요청, OpenAI SDK로 상호작용할 수 있어요:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
      "messages": [{"role": "user", "content": "Hello!"}],
      "max_tokens": 50
  }'

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="dummy"  # No auth required for local server
)

response = client.chat.completions.create(
    model="mlx-community/Qwen2.5-0.5B-Instruct-4bit",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

사전 빌드 wheel (CUDA)

uv pip install vllm --torch-backend=auto

# Install vLLM with CUDA 12.9.
pip install vllm --extra-index-url https://download.pytorch.org/whl/cu129

--torch-backend=auto(또는 UV_TORCH_BACKEND=auto)는 설치된 CUDA 드라이버 버전을 검사해 적절한 PyTorch index를 자동 선택해요. 특정 백엔드(예: cu130)를 고르려면 --torch-backend=cu130으로 설정하세요.

참고: NVIDIA Blackwell GPU(B200, GB200)는 최소 CUDA 12.8이 필요하므로 그 이상 버전의 PyTorch wheel을 설치해야 해요. 현재 vLLM 바이너리는 기본적으로 CUDA 12.9와 공개 PyTorch 릴리스 버전으로 컴파일돼요. CUDA 12.8, 13.0으로 컴파일된 vLLM 바이너리도 제공돼요:

export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
export CUDA_VERSION=130  # or other
export CPU_ARCH=$(uname -m)  # x86_64 or aarch64

uv pip install "https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cu${CUDA_VERSION}-cp38-abi3-manylinux_2_28_${CPU_ARCH}.whl" --extra-index-url "https://download.pytorch.org/whl/cu${CUDA_VERSION}"

최신 코드 설치 (CUDA)

vLLM은 v0.5.3 이후의 모든 커밋용 wheel을 https://wheels.vllm.ai/nightly에 제공해요. index는 두 종류예요:

  • https://wheels.vllm.ai/nightly: 기본 변형 (main 브랜치 최신 커밋으로 빌드, 현재 CUDA 12.9)
  • https://wheels.vllm.ai/nightly/<variant>: 기타 변형 (cu130, cpu 등)
uv pip install -U vllm \
    --torch-backend=auto \
    --extra-index-url https://wheels.vllm.ai/nightly
# add variant subdirectory here if needed

pip으로 nightly index에서 설치하는 것은 지원되지 않아요. pip은 --extra-index-url과 기본 index의 패키지를 합쳐 최신 버전만 선택하기 때문이에요. 꼭 pip을 쓰려면 wheel 파일의 전체 URL을 지정해야 해요. 이전 커밋의 wheel은 URL에 커밋 해시를 지정해 접근할 수 있어요.

사전 빌드 wheel (ROCm)

파이썬 3.12에서 ROCm 7.0, glibc >= 2.35용 최신 버전 설치:

uv pip install vllm --extra-index-url https://wheels.vllm.ai/rocm/ --upgrade

ROCm wheel 변형과 버전을 자동으로 추출하는 방법:

# automatically extract the available rocm variant
export VLLM_ROCM_VARIANT=$(curl -s https://wheels.vllm.ai/rocm/vllm | grep -oP 'rocm\d+' | head -1)
# automatically extract the vLLM version
export VLLM_VERSION=$(curl -s https://wheels.vllm.ai/rocm/vllm | grep -oP 'vllm-\K[0-9.]+' | head -1)

echo $VLLM_ROCM_VARIANT
echo $VLLM_VERSION
# inspect if the ROCm version is compatible with your environment

특정 버전·ROCm 변형 설치:

# version without the `v`
uv pip install vllm==${VLLM_VERSION} --extra-index-url https://wheels.vllm.ai/rocm/${VLLM_VERSION}/${VLLM_ROCM_VARIANT}

# Example
uv pip install vllm==0.18.0 --extra-index-url https://wheels.vllm.ai/rocm/0.18.0/rocm700

pip 사용 시 유의할 점: 커스텀 index에서 설치할 때는 패키지 이름에 정확한 vLLM 버전을 지정하고 --extra-index-url로 커스텀 index URL을 제공해야 해요:

pip install vllm==0.18.0+rocm700 --extra-index-url https://wheels.vllm.ai/rocm/0.18.0/rocm700

ROCm의 최신 코드 설치: nightly wheel을 지원하는 첫 ROCm 변형은 7.2.1이에요. auto 추출을 쓴 다음:

export VLLM_ROCM_VARIANT=$(curl -s https://wheels.vllm.ai/rocm/nightly | grep -oP 'rocm\d+' | head -1 | sed 's/%2B/+/g')
uv pip install --pre vllm \
    --extra-index-url https://wheels.vllm.ai/rocm/nightly/${VLLM_ROCM_VARIANT} \
    --index-strategy unsafe-best-match

중요 — ROCm wheel은 Python 3.12 전용: 다른 Python 버전(3.11, 3.13 등)을 쓰면 설치기가 PyPI의 CUDA wheel로 조용히 폴백하고, AMD GPU에서 libcudart.so: cannot open shared object file 같은 오류로 실패해요. python3 --version으로 확인하고, 필요하면 uv venv --python 3.12로 격리 환경을 만드세요.

사전 빌드 wheel (XPU)

vLLM XPU wheel은 wheels.vllm.ai에 게시돼요. 각 XPU wheel index에는 아래 설명된 triton==3.7.2+xpu shim도 포함돼요. PyTorch XPU 패키지는 PyTorch XPU index에서 제공되므로 두 index URL이 모두 필요해요.

uv pip install vllm \
    --extra-index-url https://wheels.vllm.ai/nightly/xpu \
    --extra-index-url https://download.pytorch.org/whl/xpu \
    --index-strategy unsafe-best-match

PyTorch 2.14로 업그레이드 후 XPU 그래프 지원에는 특정 oneAPI 패키지가 필요해요 (intel-cmplr-lib-rt==2026.1.1, intel-sycl-rt==2026.1.1, oneccl==2022.1.2 등).

소스에서 wheel 빌드 (CUDA)

Python-only 빌드 (컴파일 없이) — Python 코드만 바꾸면 컴파일 없이 빌드·설치할 수 있어요:

git clone https://github.com/vllm-project/vllm.git
cd vllm

VLLM_USE_PRECOMPILED=1 uv pip install --editable . --torch-backend=auto

이 명령은 현재 브랜치를 찾아 main 브랜치의 대응 base commit을 식별하고, 해당 commit의 사전 빌드 wheel을 다운로드해 그 컴파일된 라이브러리와 vllm-rs 바이너리를 설치에 사용해요.

  • C++나 커널 코드를 바꾸면 Python-only 빌드를 쓸 수 없어요 (라이브러리 미발견/정의되지 않은 심볼 import 오류가 남).
  • dev 브랜치를 rebase하면 vllm을 제거하고 명령을 다시 실행해 라이브러리를 최신화하는 것을 권장해요.
  • Rust 프론트엔드 재컴파일: ./build_rust.sh (release), ./build_rust.sh --debug (개발용).
  • 제어 환경 변수: VLLM_PRECOMPILED_WHEEL_LOCATION(정확한 wheel URL/경로), VLLM_PRECOMPILED_WHEEL_COMMIT(커밋 해시, nightly로 최신 빌드 commit 자동 선택), VLLM_PRECOMPILED_WHEEL_VARIANT(변형 서브디렉터리, 미지정 시 CUDA 버전 자동 감지).

전체 빌드 (컴파일 포함) — GCC/G++ ≥ 11.3 필요 (PyTorch의 C++20 헤더는 GCC 10과 호환되지 않아요):

sudo apt-get install -y gcc-11 g++-11
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 110 \
    --slave /usr/bin/g++ g++ /usr/bin/g++-11

git clone https://github.com/vllm-project/vllm.git
cd vllm
uv pip install -e . --torch-backend=auto
  • CUDA Architecture & PTX: vLLM은 빌드 시간과 wheel 크기 최적화를 위해 소스별로 CUDA 아키텍처를 정규화해요. TORCH_CUDA_ARCH_LIST의 전역 +PTX 요청은 일반 extension 타깃에서 무시되고, PTX는 필요한 특정 내부 커널에만 생성돼요.
  • 반복 빌드 시 ccache로 컴파일 결과를 캐시하세요. pip install -e .과 함께 쓸 때는 CCACHE_NOHASHDIR="true" pip install --no-build-isolation -e .을 실행하세요. sccache는 원격 스토리지 캐싱을 지원해요.
  • MAX_JOBS로 동시 컴파일 수를 제한할 수 있어요 (WSL은 기본 메모리의 50%만 할당하므로 export MAX_JOBS=1로 OOM을 피할 수 있어요).
  • 기존 PyTorch 설치를 쓰려면 python use_existing_torch.py 실행 후 uv pip install --no-build-isolation -e ., 또는 uv의 빌드 격리 비활성화를 활용할 수 있어요.
  • VLLM_CUTLASS_SRC_DIR로 로컬 cutlass 디렉터리를 지정할 수 있어요.
  • 빌드에 문제가 있으면 NVIDIA PyTorch Docker 이미지를 권장해요: docker run --gpus all -it --rm --ipc=host nvcr.io/nvidia/pytorch:23.10-py3. docker를 쓰지 않으면 CUDA Toolkit 전체 설치는 물론 CUDA_HOME 설정과 nvcc를 PATH에 넣는 것을 권장해요.

지원되지 않는 OS 빌드 — vLLM은 Linux에서만 완전히 실행되지만, 개발용으로 다른 시스템(macOS 등)에서 import와 편리한 개발 환경을 위해 빌드할 수 있어요 (export VLLM_TARGET_DEVICE=empty 후 uv pip install -e .). 바이너리는 컴파일되지 않으며 non-Linux에서는 동작하지 않아요.

ROCm 전체 빌드 핵심: 사전 요구 사항(ROCm, PyTorch)을 설치하고, ROCm용 Triton을 설치(git clone https://github.com/ROCm/triton.git 후 setup.py install), 선택 사항으로 CK flash attention / AITER / MORI를 설치한 뒤:

pip install --upgrade pip
# Build & install AMD SMI
pip install /opt/rocm/share/amd_smi
# Install dependencies
pip install --upgrade numba scipy huggingface-hub setuptools_scm
pip install -r requirements/rocm.txt
# To build for a single architecture (e.g., MI300) for faster installation (recommended):
export PYTORCH_ROCM_ARCH="gfx942"
python3 setup.py develop

이는 5~10분 걸릴 수 있어요. ROCm에서 소스 설치 시 pip install .은 동작하지 않아요. PyTorch의 ROCm 버전은 ROCm 드라이버 버전과 맞추는 것이 이상적이에요. 검증된 $TRITON_BRANCH, $FA_BRANCH, $AITER_BRANCH_OR_COMMIT, $MORI_BRANCH_OR_COMMIT는 docker/Dockerfile.rocm_base에서 찾을 수 있어요.

XPU 빌드 핵심: 드라이버 설치 후 pip install -v -r requirements/xpu.txt, 그리고 VLLM_TARGET_DEVICE=xpu pip install --no-build-isolation -e . -v. requirements/xpu.txt는 triton==3.7.2+xpu 호환 shim을 고정하는데, 이는 일부 전이 의존성(예: xgrammar)이 문자 그대로 triton이라는 배포를 무조건 요구하기 때문이에요. 수동 재설치/제거는 필요 없어요.

Docker로 설정하기

사전 빌드 이미지 (NVIDIA)

Docker Hub에서 vllm/vllm-openai로 OpenAI 호환 서버를 실행할 수 있어요:

docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model Qwen/Qwen3-0.6B
  • ipc=host 또는 --shm-size 플래그로 컨테이너가 호스트 공유 메모리에 접근하게 해야 해요. PyTorch는 특히 tensor parallel 추론에서 프로세스 간 데이터 공유에 공유 메모리를 써요.
  • 라이선스 이슈(예: Issue #8030)를 피하기 위해 선택적 의존성은 포함되지 않아요. 필요하면 기본 이미지 위에 커스텀 Dockerfile로 설치하세요. 일부 새 모델은 HF Transformers의 main 브랜치에만 있을 수 있어요.

구형 CUDA 드라이버 시스템에서 실행: vLLM Docker 이미지에는 CUDA 호환성 라이브러리가 사전 설치돼 있어요. VLLM_ENABLE_CUDA_COMPATIBILITY=1(또는 true)을 설정하면 이미지의 CUDA Toolkit 버전보다 오래된 NVIDIA 드라이버 시스템에서 실행할 수 있어요 (선택된 프로페셔널/데이터센터 GPU만). 이는 PyTorch를 로드하기 전에 LD_LIBRARY_PATH를 호환성 라이브러리로 자동 구성해요.

사전 빌드 이미지 (ROCm)

vllm/vllm-openai-rocm:latest(stable), :nightly(preview). 실행:

docker run --rm \
    --group-add video \
    --cap-add SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --device /dev/kfd \
    --device /dev/dri \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai-rocm:<tag> \
    --model Qwen/Qwen3-0.6B

deprecated: AMD의 rocm/vllm 및 rocm/vllm-dev Docker 이미지는 공식 vLLM 이미지(vllm/vllm-openai-rocm)로 대체되어 deprecated 되었어요.

사전 빌드 이미지 (XPU)

vllm/vllm-openai-xpu:latest(v0.26.0부터 stable), :nightly. --network host, /dev/dri 장치, --privileged 등이 필요해요.

소스에서 이미지 빌드

NVIDIA:

# optionally specifies: --build-arg max_jobs=8 --build-arg nvcc_threads=2
DOCKER_BUILDKIT=1 docker build . \
    --target vllm-openai \
    --tag vllm/vllm-openai \
    --file docker/Dockerfile
  • 기본적으로 모든 GPU 유형으로 빌드해요. 현재 GPU 유형만 빌드하려면 --build-arg torch_cuda_arch_list=""를 추가하세요.
  • C++/CUDA 커널 코드를 바꾸지 않았다면 --build-arg VLLM_USE_PRECOMPILED="1"로 사전 컴파일된 wheel을 써서 빌드 시간을 크게 줄일 수 있어요.

Arm64/aarch64 빌드: --platform "linux/arm64"로 Nvidia Grace-Hopper·Grace-Blackwell용 컨테이너를 빌드할 수 있어요. non-ARM 호스트에서 크로스 컴파일하려면 QEMU를 등록해야 해요:

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

[Preview] NVIDIA Rubin 아키텍처 빌드: INSTALL_RUBIN_PRERELEASE=true로 Rubin 빌드 경로를 활성화해요. Triton을 TRITON_INSTALL_FROM_SOURCE_REPO/TRITON_INSTALL_FROM_SOURCE_REVISION으로 지정해 소스에서 설치해야 해요. FINAL_BASE_IMAGE로 nvcr.io/nvidia/cuda-dl-base:26.08-cuda13.4-devel-ubuntu24.04(public multi-arch)를 사용하세요.

커스텀 빌드 이미지 사용

docker run ... vllm/vllm-openai <args...>에서 vllm/vllm-openai를 커스텀 빌드 이미지 이름(빌드 명령의 -t 태그)으로 바꾸면 돼요.

ROCm: docker/Dockerfile.rocm은 기본적으로 ROCm 7.0을 사용하며, buildkit(DOCKER_BUILDKIT=1 또는 daemon.json 설정)으로 빌드해야 해요. docker build -f docker/Dockerfile.rocm -t vllm/vllm-openai-rocm .로 빌드할 수 있어요. BASE_IMAGE와 ARG_PYTORCH_ROCM_ARCH 인자를 바꿀 수 있어요.

지원 기능

  • Feature × Hardware 호환성 매트릭스를 참고하세요.
  • XPU: tensor parallel 추론/서빙을 지원하며, 온라인 서빙에서 pipeline parallel을 beta 기능으로 지원해요 (--distributed-executor-backend=mp --pipeline-parallel-size=2 등). 기본적으로 시스템에 기존 ray 인스턴스가 없으면 num-gpus=parallel_config.world_size로 ray 인스턴스가 자동 시작돼요.
  • vLLM-Metal: Metal 네이티브 GPU 가속, Apple Silicon용 MLX 기반 compute 백엔드, OpenAI 호환 API 서버, 인기 모델 아키텍처 지원을 제공해요.

더 알아보기 (Learn more)