CPU 설치

vLLM은 Python 라이브러리이며 사용하는 CPU 아키텍처에 따라 다양한 변형을 지원해요. x86, Arm, Apple Silicon(macOS), IBM Z(s390x) 플랫폼에서 각각 다른 설치 방법이 필요해요. 이 문서에서는 CPU 환경에서 vLLM을 설치하고 실행하는 방법을 안내해요.

출처: 문서

본문

vLLM은 다음 CPU 변형을 지원해요. 자신의 CPU 유형을 선택해 벤더별 지침을 확인하세요.

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

기술 논의

주요 논의는 vLLM Slack의 #sig-cpu 채널에서 이루어져요.
CPU 백엔드에 대한 GitHub 이슈를 열 때는 제목에 [CPU Backend]를 추가하면 cpu 라벨이 붙어 더 잘 보여요.

요구 사항

x86

Python: 3.10 ~ 3.13
OS: Linux
CPU 플래그: avx512f (권장), avx2 (제한적 기능)
- 팁: lscpu로 CPU 플래그를 확인하세요.

Arm

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

macOS

OS: macOS Sonoma 이상
SDK: Command Line Tools를 포함한 XCode 15.4 이상
컴파일러: Apple Clang >= 15.0.0
- 참고: macOS CPU 빌드는 CI에서 최신 GA Apple Silicon 러너로 smoke-test되지만, 다른 macOS나 Apple Clang 버전은 best-effort예요.

s390x (IBM Z)

OS: Linux
SDK: gcc/g++ >= 14.0.0 이상
ISA: VXE 지원 필요 (Z15 이상에서 동작)
사전 빌드 s390x wheel이 없는 패키지를 소스에서 빌드: torchvision, llvmlite, numba, opencv-python-headless, hf-xet

Python으로 설정하기

새 Python 환경 만들기

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

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

사전 빌드 wheel

index URL을 지정할 때 반드시 cpu 변형 서브디렉터리를 사용하세요. 예를 들어 nightly 빌드 index는 https://wheels.vllm.ai/nightly/cpu/이에요.

x86: AVX512/AVX2용 사전 빌드 vLLM wheel은 버전 0.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

특정 리비전 설치 (이전 커밋의 wheel에 접근하려면, 예: 회귀 분석):

export VLLM_COMMIT=730bd35378bf2a5b56b6d3a45be28b3092d26519  # use full commit hash from the main branch
uv pip install vllm --extra-index-url https://wheels.vllm.ai/${VLLM_COMMIT}/cpu --index-strategy first-index --torch-backend cpu

Arm: 사전 빌드 Arm wheel은 버전 0.11.2부터 사용 가능해요. 이 wheel에는 사전 컴파일된 C++ 바이너리가 포함돼요.

export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')

uv pip install "https://github.com/vllm-project/vllm/releases/download/v${VLLM_VERSION}/vllm-${VLLM_VERSION}+cpu-cp38-abi3-manylinux_2_34_aarch64.whl" --torch-backend cpu

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

uv 방식은 vLLM v0.6.6 이상에서 동작해요. uv의 특별한 점은 --extra-index-url의 패키지가 기본 index보다 우선순위가 높다는 거예요. 만약 최신 공개 릴리스가 v0.6.6.post1이라면, uv는 --extra-index-url을 지정해 v0.6.6.post1 이전 커밋을 설치할 수 있어요. 반면 pip는 --extra-index-url과 기본 index의 패키지를 합쳐 최신 버전만 선택하므로, 릴리스 이전 개발 버전 설치가 어려워요.

Arm 최신 코드 / 특정 리비전 설치:

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

pip로 nightly index에서 설치하는 것은 권장되지 않아요. pip는 --extra-index-url과 기본 index의 패키지를 합쳐 최신 버전만 선택하기 때문이에요. 꼭 pip를 쓰려면 wheel 파일의 전체 URL을 지정해야 해요:

pip install https://wheels.vllm.ai/2f3f441f84bd5b35ec8aa9fcfffb540f107da8a7/vllm-0.23.1rc1.dev901%2Bg2f3f441f8.cpu-cp38-abi3-manylinux_2_34_aarch64.whl --extra-index-url https://download.pytorch.org/whl/cpu
# current nightly build (the filename will change!)

현재 Apple silicon CPU wheel은 사전 빌드가 없고, IBM Z CPU wheel도 사전 빌드가 없어요.

소스에서 wheel 빌드

Python-only 빌드 (컴파일 없이) — 플랫폼용 사전 빌드 wheel이 필요해요. GPU 문서의 Python-only 빌드 지침을 참고하고 빌드 명령을 다음과 같이 바꾸세요:

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

환경 만들기, 저장소 클론, 의존성 설치, 빌드:

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

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

pip을 쓴다면:

pip install --upgrade pip
pip install -v -r requirements/build/cpu.txt --extra-index-url https://download.pytorch.org/whl/cpu
pip install -v -r requirements/cpu.txt --extra-index-url https://download.pytorch.org/whl/cpu

빌드 및 설치:

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에 추가되어 있는지 확인하세요:

# install TCMalloc, Intel OpenMP is installed with vLLM CPU
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을 실행하려면 AVX512 지원을 위한 4세대 이상 프로세서(Zen 4/Genoa)가 필요해요.
Could not find a version that satisfies the requirement torch==X.Y.Z+cpu+cpu 오류가 나면 pyproject.toml의 build-system의 requires에 "torch==X.Y.Z+cpu"를 추가해 pip이 의존성 해석을 돕게 하세요.

s390x 빌드는 더 복잡해요 (numactl, rust>=1.80, LLVM 20, gperftools(TCMalloc) 등을 소스에서 빌드). docker/Dockerfile.s390x에서 각 multi-stage build에 사용된 정확한 버전과 빌드 명령을 참고하세요. s390x Docker 이미지에는 TCMalloc이 포함되고 LD_PRELOAD가 자동 설정돼요.

Docker로 설정하기

사전 빌드 이미지

x86: Docker Hub에서 최신 CPU 이미지를 받을 수 있어요:

docker pull vllm/vllm-openai-cpu:latest-x86_64
# 특정 버전
export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
docker pull vllm/vllm-openai-cpu:v${VLLM_VERSION}-x86_64

모든 태그: https://hub.docker.com/r/vllm/vllm-openai-cpu/tags

실행:

docker run \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --env "HF_TOKEN=<secret>" \
    vllm/vllm-openai-cpu:latest-x86_64 \
    <args...>

Arm: vllm/vllm-openai-cpu:latest-arm64, 버전은 v${VLLM_VERSION}-arm64.

최신 코드 Docker 이미지 (public.ecr.aws/q9t5s3a7/vllm-ci-postmerge-repo:${VLLM_COMMIT}-arm64-cpu)는 프로덕션용이 아니며 CI/테스트 전용으로 며칠 후 만료돼요.

현재 Arm silicon CPU 이미지와 IBM Z CPU 이미지는 사전 빌드되어 있지 않아요.

소스에서 이미지 빌드

자신의 타깃 CPU 빌드:

docker build -f docker/Dockerfile.cpu \
        --build-arg VLLM_CPU_X86=<false (default)|true> \  # For cross-compilation
        --tag vllm-cpu-env \
        --target vllm-openai \
        .

AMD Zen 최적화로 빌드 (linux/amd64 전용, vllm-openai-zen 타깃):

docker build -f docker/Dockerfile.cpu \
        --tag vllm-cpu-zen-env \
        --target vllm-openai-zen \
        .

OpenAI 서버 실행:

docker run --rm \
    --security-opt seccomp=unconfined \
    --cap-add SYS_NICE \
    --shm-size=4g \
    -p 8000:8000 \
    -e VLLM_CPU_KVCACHE_SPACE=<KV cache space> \
    vllm-cpu-env \
    meta-llama/Llama-3.2-1B-Instruct \
    --dtype=bfloat16 \
    other vLLM OpenAI server arguments

ARM 타깃 CPU 빌드:

docker build -f docker/Dockerfile.cpu \
        --platform=linux/arm64 \
        --build-arg VLLM_CPU_ARM_BF16=<false (default)|true> \
        --tag vllm-cpu-env \
        --target vllm-openai \
        .

ARM CPU 명령 세트(BF16, NEON 등)는 기본적으로 빌드 시스템 CPU 플래그에서 자동 감지돼요. VLLM_CPU_ARM_BF16 빌드 인자는 크로스 컴파일용이에요.
ARM BF16 지원은 ARMv8.6-A 이상(FEAT_BF16)이 필요해요. AWS Graviton3/4, AmpereOne 등 최신 ARM 프로세서에서 지원돼요.

--privileged=true 대신 --cap-add SYS_NICE --security-opt seccomp=unconfined가 더 안전해요.

AMD Zen 최적화

AMD Zen CPU에서 vLLM은 ZenCpuPlatform(CpuPlatform의 서브클래스)을 자동 선택하며, linear layer를 zentorch의 ZenDNN 최적화 커널로 디스패치해요. 설치 명령은 FAQ의 "How do I enable AMD Zen optimizations?" 항목을 참고하세요.

감지 규칙 — 다음 조건이 모두 맞으면 ZenCpuPlatform이 선택돼요:

vLLM이 CPU용으로 빌드됨
/proc/cpuinfo가 AuthenticAMD와 avx512를 보고함
import zentorch가 성공

그 외에는 기본 CpuPlatform(oneDNN / sgl-kernel 경로)으로 폴백돼요.

지원 dtype — ZenCpuPlatform은 float16을 지원하지 않아요. bfloat16과 float32만 허용하며, torch_dtype=float16으로 선언된 모델은 로드 시 bfloat16으로 자동 다운캐스트돼요.

환경 변수 — VLLM_ZENTORCH_WEIGHT_PREPACK (기본 1): 모델 로드 시 linear 가중치를 ZenDNN의 blocked layout으로 미리 prepack해 추론당 레이아웃 변환 오버헤드를 없애요. 0으로 비활성화.

설계 근거용 RFC는 RFC #35089: In-Tree AMD Zen CPU Backend via zentorch를 참고하세요.

FAQ

어떤 dtype을 써야 하나요?

현재 vLLM CPU는 모델 기본 설정을 dtype으로 사용해요. 그런데 torch CPU의 float16 지원이 불안정하므로, 성능이나 정확도 문제가 있으면 dtype=bfloat16을 명시적으로 설정하는 것을 권장해요.
AMD Zen CPU(ZenCpuPlatform)에서는 float16이 지원되지 않아요. bfloat16과 float32만 허용되며, float16으로 선언된 모델은 로드 시 bfloat16으로 자동 다운캐스트돼요.

CPU에서 vLLM 서비스를 어떻게 띄우나요?

온라인 서빙 시 CPU 과잉 할당(oversubscription)을 피하려면 서빙 프레임워크용으로 CPU 코어 1~2개를 예약하는 것을 권장해요. 32 물리 코어 플랫폼 예시:

export VLLM_CPU_KVCACHE_SPACE=40
export VLLM_CPU_OMP_THREADS_BIND=0-30
vllm serve facebook/opt-125m --dtype=bfloat16

또는 기본 auto 스레드 바인딩 사용:

export VLLM_CPU_KVCACHE_SPACE=40
export VLLM_CPU_NUM_OF_RESERVED_CPU=1
vllm serve facebook/opt-125m --dtype=bfloat16

world_size == 1일 때는 vLLM 프론트엔드 프로세스용으로 CPU 1개를 수동으로 예약하는 것을 권장해요.

CPU에서 어떤 모델이 지원되나요?

공식 문서 "Supported Models on CPU"를 참고하세요.

지원되는 CPU 모델의 벤치마크 설정 예시는?

CPU 지원 모델 각각에 대해 vLLM Benchmark Suite의 CPU 테스트 케이스(serving-tests-cpu.json 등)에 최적화된 런타임 설정이 제공돼요. 벤치마크 실행 예시:

ON_CPU=1 bash .buildkite/performance-benchmarks/scripts/run-performance-benchmarks.sh

결과는 ./benchmark/results/에 저장되고, .commands 파일에 모든 예시 명령이 들어 있어요. tensor-parallel-size는 시스템의 NUMA 노드 수와 맞추는 것을 권장하며, 현재 tensor-parallel-size=6은 지원되지 않아요. lscpu | grep "NUMA node(s):" | awk '{print $3}'로 NUMA 노드 수를 확인하세요.

Dry-Run 모드(DRY_RUN=1)를 주면 벤치마크 없이 최적화된 실행 설정만 생성할 수 있어요. MODEL_FILTER, DTYPE_FILTER, SERVING_JSON로 필터링할 수 있어요.

AMD Zen 최적화를 어떻게 활성화하나요?

AMD Zen 4/Zen 5 CPU에서 zen extra와 함께 CPU wheel을 설치하면 해당 릴리스용으로 테스트된 zentorch 버전을 받아요:

export VLLM_VERSION=$(curl -s https://api.github.com/repos/vllm-project/vllm/releases/latest | jq -r .tag_name | sed 's/^v//')
uv pip install "vllm[zen]" --extra-index-url https://wheels.vllm.ai/${VLLM_VERSION}/cpu --index-strategy first-index --torch-backend cpu

플랫폼이 자동 감지되고 linear layer가 ZenDNN 최적화 커널로 라우팅돼요. 시작 로그에서 "AMD Zen CPU detected with zentorch installed" 줄을 찾아 활성화를 확인할 수 있어요.

VLLM_CPU_OMP_THREADS_BIND를 어떻게 정하나요?

대부분의 경우 기본 auto 스레드 바인딩을 권장해요. 이상적으로 각 OpenMP 스레드는 전용 물리 코어에, 각 rank의 스레드는 같은 NUMA 노드에 바인딩되고 예약 CPU는 다른 vLLM 컴포넌트용으로 남겨져요. 성능 문제가 있으면 수동 바인딩을 시도하세요.

멀티 소켓 NUMA 머신에서 tensor parallel이나 pipeline parallel을 쓸 때는 각 NUMA 노드를 TP/PP rank로 취급해요. 단일 rank의 CPU 코어가 같은 NUMA 노드에 있어 교차 NUMA 메모리 접근을 피하세요.

VLLM_CPU_KVCACHE_SPACE를 어떻게 정하나요?

기본값은 4GB예요. 더 크게 잡으면 더 많은 동시 요청/긴 컨텍스트를 지원해요. 각 TP rank의 메모리 사용량은 가중치 샤드 크기 + VLLM_CPU_KVCACHE_SPACE의 합이므로, 단일 NUMA 노드 용량을 초과하면 TP 워커가 exitcode 9(out-of-memory)로 종료돼요.

vLLM CPU 성능 튜닝은?

스레드 바인딩과 KV 캐시 공간이 제대로 설정·적용되는지 확인하세요 (htop으로 CPU 코어 사용 확인).
--block-size는 32의 배수를 사용하세요 (기본 128).
배치 크기는 성능의 중요한 파라미터예요. --max-num-batched-tokens(첫 토큰 성능에 영향, 기본 오프라인 4096*world_size / 온라인 2048*world_size)와 --max-num-seqs(출력 토큰 성능에 영향, 기본 오프라인 256*world_size / 온라인 128*world_size)를 기본값에서 시작해 튜닝하세요.
vLLM CPU는 데이터 병렬(DP), 텐서 병렬(TP), 파이프라인 병렬(PP)을 지원하며, CPU 소켓과 메모리 노드가 충분하면 함께 사용하는 것을 권장해요.

vLLM CPU는 어떤 양자화 구성을 지원하나요?

AWQ (x86, s390x)
GPTQ (x86, s390x)
compressed-tensor INT8 W8A8 (x86, s390x만)

Docker에서 `get_mempolicy: Operation not permitted`가 보이는 이유?

일부 컨테이너 환경(Docker 등)에서는 vLLM이 쓰는 NUMA 관련 syscall(get_mempolicy, migrate_pages)이 기본 seccomp/capabilities 설정에서 차단돼요. 기능에는 영향이 없지만 NUMA 메모리 바인딩/마이그레이션 최적화가 적용되지 않아 성능이 저하될 수 있어요. 최소 권한으로 활성화하려면:

docker run ... --cap-add SYS_NICE --security-opt seccomp=unconfined ...

# 1) `--cap-add SYS_NICE` is to address `get_mempolicy` EPERM issue.
# 2) `--security-opt seccomp=unconfined` is to enable `migrate_pages` for `numa_migrate_pages()`.

K8S에서는 workload yaml에 다음을 추가해 같은 효과를 얻을 수 있어요:

securityContext:
  seccompProfile:
    type: Unconfined
  capabilities:
    add:
      - SYS_NICE

CPU 설치

CPU 설치

본문

기술 논의

요구 사항

Python으로 설정하기

새 Python 환경 만들기

사전 빌드 wheel

소스에서 wheel 빌드

Docker로 설정하기

사전 빌드 이미지

소스에서 이미지 빌드

AMD Zen 최적화

관련 런타임 환경 변수

FAQ

어떤 dtype을 써야 하나요?

CPU에서 vLLM 서비스를 어떻게 띄우나요?

CPU에서 어떤 모델이 지원되나요?

지원되는 CPU 모델의 벤치마크 설정 예시는?

AMD Zen 최적화를 어떻게 활성화하나요?

VLLM_CPU_OMP_THREADS_BIND를 어떻게 정하나요?

VLLM_CPU_KVCACHE_SPACE를 어떻게 정하나요?

vLLM CPU 성능 튜닝은?

vLLM CPU는 어떤 양자화 구성을 지원하나요?

Docker에서 `get_mempolicy: Operation not permitted`가 보이는 이유?

더 알아보기 (Learn more)

CPU 설치

CPU 설치

본문

기술 논의

요구 사항

Python으로 설정하기

새 Python 환경 만들기

사전 빌드 wheel

소스에서 wheel 빌드

Docker로 설정하기

사전 빌드 이미지

소스에서 이미지 빌드

AMD Zen 최적화

관련 런타임 환경 변수

FAQ

어떤 dtype을 써야 하나요?

CPU에서 vLLM 서비스를 어떻게 띄우나요?

CPU에서 어떤 모델이 지원되나요?

지원되는 CPU 모델의 벤치마크 설정 예시는?

AMD Zen 최적화를 어떻게 활성화하나요?

VLLM_CPU_OMP_THREADS_BIND를 어떻게 정하나요?

VLLM_CPU_KVCACHE_SPACE를 어떻게 정하나요?

vLLM CPU 성능 튜닝은?

vLLM CPU는 어떤 양자화 구성을 지원하나요?

Docker에서 get_mempolicy: Operation not permitted가 보이는 이유?

더 알아보기 (Learn more)

Docker에서 `get_mempolicy: Operation not permitted`가 보이는 이유?