CPU 설치

CPU 설치 (CPU)

vLLM은 Python 라이브러리이고, 다양한 CPU 변형을 지원해요. 자신의 CPU 종류를 선택해 벤더별 지침을 확인하면 됩니다.

  • x86 (Intel/AMD): FP32, FP16, BF16 데이터 타입으로 기본적인 모델 추론과 서빙을 지원해요.
  • Arm (AArch64): NEON을 지원하고 FP32, FP16, BF16 데이터 타입을 지원하며 기본적인 모델 추론과 서빙을 할 수 있어요.
  • Apple Silicon (macOS): 실험적 지원이에요. 지금은 macOS에서 네이티브로 실행하려면 소스에서 빌드해야 해요. CPU 구현은 FP32와 FP16 데이터 타입을 지원합니다.
    • 참고: Apple Silicon에서 Metal로 GPU 가속 추론을 하려면 커뮤니티 유지보수 하드웨어 플러그인인 vllm-metal을 확인하세요. MLX를 컴퓨트 백엔드로 사용해요.
  • s390x (IBM Z): 실험적 지원이에요. IBM Z에서 네이티브 실행하려면 소스에서 빌드해야 해요. FP32, BF16, FP16과 AWQ, GPTQ 4-bit 양자화, compressed-tensors INT8 W8A8을 지원합니다.

출처: vLLM 공식 문서 — getting_started-installation-cpu

기술 토론 (Technical Discussions)

주요 논의는 vLLM Slack의 #sig-cpu 채널에서 이루어져요. CPU 백엔드에 관한 GitHub 이슈를 열 때는 제목에 [CPU Backend]를 넣으면 cpu 라벨이 붙어 인지도가 높아져요.

요구사항 (Requirements)

  • Python: 3.10 -- 3.13
  • OS: Linux

x86

  • CPU flags: avx512f (권장), avx2 (제한적 기능)
    • 팁: lscpu로 CPU flags를 확인할 수 있어요.

Arm (AArch64)

  • OS: Linux
  • 컴파일러: gcc/g++ >= 12.3.0 (선택, 권장)
  • ISA: NEON 지원 필수

Apple Silicon

  • OS: macOS Sonoma 이상
  • SDK: XCode 15.4 이상 with Command Line Tools
  • 컴파일러: Apple Clang >= 15.0.0

s390x (IBM Z)

  • OS: Linux
  • SDK: gcc/g++ >= 14.0.0 이상 with Command Line Tools
  • ISA: VXE 지원 필수 (Z15 이상에서 동작)
  • 소스에서 빌드해야 하는 패키지(사전 빌드된 s390x wheel 없음): torchvision, llvmlite, numba, opencv-python-headless, hf-xet

Python으로 설정하기 (Set up using Python)

새 Python 환경 만들기

매우 빠른 Python 환경 관리자인 uv를 사용하는 걸 권장해요. uv 설치 후 다음 명령으로 새 환경을 만들 수 있어요.

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

사전 빌드된 wheel (Pre-built wheels)

인덱스 URL을 지정할 때 cpu 변형 하위 디렉토리를 꼭 사용하세요. 예를 들어 nightly 빌드 인덱스는 https://wheels.vllm.ai/nightly/cpu/예요.

x86용 AVX512/AVX2 사전 빌드 wheel은 v0.17.0부터 사용 가능해요. 릴리스 wheel 설치는 다음과 같아요.

export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
# use uv
uv pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cpu-cp38-abi3-manylinux_2_34_x86_64.whl --torch-backend cpu

# use pip
pip install https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cpu-cp38-abi3-manylinux_2_34_x86_64.whl --extra-index-url https://download.pytorch.org/whl/cpu

LD_PRELOAD 설정: wheel로 설치한 vLLM CPU를 쓰기 전에 Intel OpenMP가 LD_PRELOAD에 추가되어 있는지 확인하세요.

# manually find the path
sudo find / -iname *libiomp5.so
IOMP_PATH=...
# add it to LD_PRELOAD
export LD_PRELOAD="$IOMP_PATH:$LD_PRELOAD"

최신 코드 설치

main 브랜치에서 빌드된 wheel을 설치하려면:

uv pip install vllm --extra-index-url https://wheels.vllm.ai/nightly/cpu --index-strategy first-index --torch-backend cpu

Arm용 사전 빌드 wheel은 v0.11.2부터 사용 가능해요. 사전 컴파일된 C++ 바이너리를 포함합니다. 설치는 x86과 같은 방식(파일명만 aarch64로)이에요. Arm CPU에서는 https://wheels.vllm.ai/nightly/cpu/vllm 인덱스를 권장합니다.

uv 방식은 vLLM v0.6.6 이후 버전에서 동작해요. uv는 --extra-index-url의 패키지에 기본 인덱스보다 높은 우선순위를 주는 특징이 있어요. 반면 pip는 --extra-index-url과 기본 인덱스의 패키지를 합쳐 최신 버전만 고르므로, 릴리스된 버전보다 앞선 개발 버전을 설치하기가 어려워요.

소스에서 wheel 빌드 (Build wheel from source)

컴파일 없는 Python-only 빌드는 플랫폼용 사전 빌드 wheel이 필요해요. GPU 가이드의 Python-only build를 참고하되 빌드 명령은 아래로 바꾸면 됩니다.

VLLM_USE_PRECOMPILED=1 VLLM_PRECOMPILED_WHEEL_VARIANT=cpu VLLM_TARGET_DEVICE=cpu uv pip install --editable .

**전체 빌드(컴파일 포함)**를 하려면 권장 컴파일러를 설치해야 해요. gcc/g++ >= 12.3.0을 기본 컴파일러로 쓰는 걸 권장합니다. 예를 들어 Ubuntu 22.4에서:

sudo apt-get update -y
sudo apt-get install -y gcc-12 g++-12 libnuma-dev
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 10 --slave /usr/bin/g++ g++ /usr/bin/g++-12

그 다음 vLLM 프로젝트를 클론하고 의존성을 설치합니다.

git clone https://github.com/vllm-project/vllm.git vllm_source
cd vllm_source
uv pip install -r requirements/build/cpu.txt --torch-backend cpu --index-strategy unsafe-best-match
uv pip install -r requirements/cpu.txt --torch-backend cpu --index-strategy unsafe-best-match

빌드 후 설치:

VLLM_TARGET_DEVICE=cpu uv pip install . --no-build-isolation

개발용이라면 editable 모드로 설치하세요.

VLLM_TARGET_DEVICE=cpu python3 setup.py develop

선택적으로 이식 가능한 wheel을 만들어 다른 곳에 설치할 수도 있어요.

VLLM_TARGET_DEVICE=cpu uv build --wheel --no-build-isolation
uv pip install dist/*.whl

LD_PRELOAD 설정: wheel로 설치한 vLLM CPU를 쓰기 전에 TCMalloc과 Intel OpenMP가 설치되어 LD_PRELOAD에 추가되어 있는지 확인하세요.

sudo apt-get install -y --no-install-recommends libtcmalloc-minimal4
sudo find / -iname *libtcmalloc_minimal.so.4
sudo find / -iname *libiomp5.so
TC_PATH=...
IOMP_PATH=...
export LD_PRELOAD="$TC_PATH:$IOMP_PATH:$LD_PRELOAD"

문제 해결 (Troubleshooting)

  • NumPy ≥2.0 오류: pip install "numpy<2.0"로 다운그레이드하세요.
  • CMake가 CUDA를 감지함: CPU 빌드에서 CUDA가 설치되어 있어도 감지되지 않도록 CMAKE_DISABLE_FIND_PACKAGE_CUDA=ON을 추가하세요.
  • AMD CPU는 vLLM CPU 실행에 AVX512를 지원하려면 4세대(Genoa) 이상 프로세서가 필요해요.

성능 튜닝 (Performance Tuning)

먼저 thread-binding과 KV cache 공간이 제대로 설정되어 적용되는지 확인하세요. --block-size는 32의 배수(기본값 128)를 쓰세요. 배치 크기는 중요한 성능 파라미터예요. --max-num-batched-tokens(기본: offline 4096, online 2048)와 --max-num-seqs(기본: offline 256, online 128)를 조정해 throughput과 latency 균형을 맞추세요.

vLLM CPU는 성능 극대화를 위해 데이터 병렬(DP), 텐서 병렬(TP), 파이프라인 병렬(PP)을 함께 쓰는 걸 권장해요.

더 알아보기 (Learn more)