배포 자습서: Docker로 vLLM 실행하기

배포 자습서: Docker로 vLLM 실행하기 (Using Docker)

미리 빌드된 이미지 (Pre-built images)

vLLM은 공식 Docker 이미지를 제공해요. CUDA용 이미지와 ROCm용 이미지가 별도로 있고, CPU 전용 이미지도 따로 있어요. 이미지 태그는 vllm/vllm-openai:latest를 기준으로 해요. 자세한 설치·빌드 방법은 GPU 설치 가이드의 pre-built images 항목을 참고하면 돼요.

vLLM Recipes 설정 실행하기

vLLM Recipes는 config.yaml과 env.sh로 변환할 수 있어요. 사용법은 Recipes 변환 도구 README를 보면 돼요.

Docker에서는 두 파일을 마운트하고, 컨테이너 안에서 vLLM을 시작하기 전에 env.sh를 source 하세요:

docker run --rm --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -v "$PWD/config.yaml:/recipe/config.yaml:ro" \
    -v "$PWD/env.sh:/recipe/env.sh:ro" \
    -p 8000:8000 \
    --ipc=host \
    --entrypoint /bin/bash \
    vllm/vllm-openai:latest \
    -lc 'source /recipe/env.sh && exec vllm serve --config /recipe/config.yaml'

이렇게 하면 설정 파일은 읽기 전용(:ro)으로 넣어 두고, 컨테이너 시작 시 env.sh를 적용한 뒤 vLLM을 컨테이너 메인 프로세스로(exec) 띄워요.

컴파일 캐시를 컨테이너 간에 유지하기

Hugging Face 캐시를 마운트하면 모델 가중치는 컨테이너 간에 유지돼요. 하지만 새 컨테이너는 매번 빈 VLLM_CACHE_ROOT(기본값 ~/.cache/vllm)로 시작해서 모델의 torch.compile 산출물을 다시 컴파일해요. 두 번째 컨테이너부터는 inductor, Triton, AOT 산출물을 재사용하도록 그 경로에 named volume을 마운트하세요:

docker run --rm --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -v vllm-cache:/root/.cache/vllm \
    -p 8000:8000 \
    vllm/vllm-openai:latest \
    meta-llama/Llama-3.1-8B-Instruct

이 메커니즘과 캐시가 무효화되는 조건은 Faster Startup에서 자세히 볼 수 있어요.

비-root 사용자로 실행하기

CUDA용 vllm/vllm-openai 이미지는 호환성을 위해 기본적으로 root로 실행돼요. 이미 빌트인 vllm 사용자(UID 2000, GID 0)로 실행하도록 준비도 되어 있어요:

docker run --rm --gpus all \
    --user 2000:0 \
    -p 8000:8000 \
    vllm/vllm-openai:latest \
    meta-llama/Llama-3.1-8B-Instruct

비-root 컨테이너에서 모델·캐시 볼륨을 마운트할 때는 /root 대신 /home/vllm 아래의 쓰기 가능한 경로로 마운트하세요. 예를 들어 Hugging Face 캐시를 /home/vllm/.cache/huggingface에 마운트하고, 마운트한 디렉터리를 group 0가 쓰기 가능하게 만들어 주세요.

docker run --rm --gpus all \
    --user 2000:0 \
    -v ~/.cache/huggingface:/home/vllm/.cache/huggingface \
    -p 8000:8000 \
    vllm/vllm-openai:latest \
    meta-llama/Llama-3.1-8B-Instruct

기본적으로 비-root vllm 사용자를 쓰는 이미지를 빌드하려면 opt-in 타깃 vllm-openai-nonroot를 사용하세요:

docker build --target vllm-openai-nonroot \
    -t vllm-openai-nonroot:local \
    -f docker/Dockerfile .

docker run --rm --gpus all \
    -p 8000:8000 \
    vllm-openai-nonroot:local \
    meta-llama/Llama-3.1-8B-Instruct

vllm-openai-nonroot 타깃은 런타임 UID가 group 0의 구성원일 때 OpenShift 스타일의 임의 UID도 지원해요. Kubernetes 매니페스트에서는 컨테이너 security context를 그에 맞게 설정하고, 마운트한 캐시·모델 경로를 group 0가 쓰기 가능하게 유지하세요:

securityContext:
  runAsNonRoot: true
  runAsUser: 1000540000
  runAsGroup: 0
  fsGroup: 0

group 0 밖의 런타임 UID는 /home/vllm이나 /opt/uv/cache에 쓰지 못할 수 있어서, 문서화된 지원 매트릭스에 포함되지 않아요.

소스에서 이미지 빌드하기

공식 Dockerfile로 소스에서 직접 빌드할 수도 있어요. 빌드 방법은 GPU 설치 가이드의 build-image-from-source 항목을 참고하세요.

출처: 공식문서

더 알아보기 (Learn more)