vLLM 퀵스타트: 2026년 고성능 LLM 서빙

2026년 vLLM 설치, 서빙 및 튜닝

Page content

vLLM은 UC 버클리 스카이 컴퓨팅 랩(Sky Computing Lab)이 개발한 대규모 언어 모델(LLM)을 위한 고처리량, 메모리 효율적인 추론 및 서빙 엔진입니다.

이 엔진의 PagedAttention 알고리즘은 KV 캐시를 OS 가상 메모리 페이지처럼 취급하며, 이는 연속 배치(continuous batching)와 결합됩니다. 이 조합이 vLLM을 프로덕션 LLM 서빙의 기본 엔진으로 만들었습니다. vLLM이 Ollama, Docker Model Runner, LocalAI 및 클라우드 제공업체 중에서 어떻게 위치하는지, 그리고 비용 및 인프라 트레이드오프에 대해 알아보고 싶다면 LLM 호스팅: 로컬, 셀프 호스팅 및 클라우드 인프라 비교를 참조하세요.

vllm 로고

이 가이드는 vLLM v0.31.0 (2026년 10월) 기준 최신 내용입니다. 구버전 튜토리얼에서 온다면 최근 두 가지 사항이 변경되었습니다: python -m vllm.entrypoints.openai.api_server는 더 이상 사용되지 않으며 경고를 출력합니다 — 이제 표준 CLI는 vllm serve입니다 — 그리고 사전 구축된 wheels는 기본적으로 CUDA 11.8이 아닌 CUDA 12.9를 대상화합니다.

vLLM이란?

vLLM(가상 LLM)은 빠른 LLM 추론 및 서빙을 위한 오픈소스 라이브러리로, 프로덕션 배포의 업계 표준으로 빠르게 부상하고 있습니다. 2023년에 출시된 vLLM은 서빙 효율성을 획기적으로 개선하는 groundbreaking 메모리 관리 기법인 PagedAttention을 소개했습니다.

주요 기능

높은 처리량 성능: vLLM의 초기 벤치마크에서는 동일한 하드웨어에서 HuggingFace Transformers보다 14-24배 높은 처리량을 보고했으며, 이 엔진은 연속 배치, 최적화된 CUDA 커널, 그리고 메모리 фрагメン테이션을 제거하는 PagedAttention 알고리즘을 통해 그 우위를 유지해 왔습니다.

OpenAI API 호환성: vLLM은 OpenAI 형식과 완전히 호환되는 내장 API 서버를 포함하고 있습니다. 이를 통해 애플리케이션 코드 변경 없이 OpenAI에서 셀프 호스팅 인프라로 원활하게 마이그레이션할 수 있습니다. 단순히 API 클라이언트를 vLLM의 엔드포인트로 지시하면 투명하게 작동합니다.

PagedAttention 알고리즘: vLLM의 성능을 뒷받침하는 핵심 혁신은 PagedAttention으로, 가상 메모리 페이징 개념을 어텐션 메커니즘에 적용합니다. KV 캐시를 위해 연속된 메모리 블록을 할당하는 것(이는 분편화로 이어짐) 대신, PagedAttention은 메모리를 요청 시 할당할 수 있는 고정 크기 블록으로 나눕니다. 이를 통해 메모리 낭비를 최대 4배까지 줄이고 훨씬 더 큰 배치 크기를 가능하게 합니다.

연속 배치(Continuous Batching): 모든 시퀀스가 완료되기를 기다리는 정적 배치와 달리, vLLM은 연속(rolling) 배치를 사용합니다. 한 시퀀스가 완료되는 즉시 새로운 시퀀스를 배치에 추가할 수 있습니다. 이는 GPU 이용률을 극대화하고 신규 요청의 레이턴시를 최소화합니다.

멀티 GPU 지원: vLLM은 대규모 모델을 여러 GPU에 분산하기 위한 텐서 병렬(tensor parallelism)과 파이프라인 병렬(pipeline parallelism)을 지원합니다. 단일 GPU 메모리에 맞지 않는 모델을 효율적으로 서빙할 수 있으며, 2개부터 8개 이상의 GPU 구성을 지원합니다.

광범위한 모델 지원: LLaMA, Mistral, Mixtral, Qwen, Phi, Gemma 등 인기 있는 모델 아키텍처와 호환됩니다. HuggingFace Hub의 인스트럭션 튜닝 모델과 베이스 모델 모두를 지원합니다.

vLLM 사용 시나리오

vLLM은 그 장점이 빛을 발하는 특정 시나리오에서 탁월한 성능을 발휘합니다:

프로덕션 API 서비스: 많은 동시 사용자에게 LLM을 API를 통해 서빙해야 하는 경우, vLLM의 높은 처리량과 효율적인 배치는 최고의 선택이 됩니다. 챗봇, 코드 어시스턴트, 콘텐츠 생성 서비스를 운영하는 기업들은 초당 수백 개의 요청을 처리할 수 있는 능력에서 이익을 얻습니다.

고동시성 워크로드: 동시에 요청을 보내는 많은 사용자를 가진 애플리케이션의 경우, vLLM의 연속 배치와 PagedAttention은 대안 대비 동일한 하드웨어로 더 많은 사용자에게 서빙할 수 있게 해줍니다.

비용 최적화: GPU 비용이 관심사일 때, vLLM의 뛰어난 처리량을 통해 더 적은 GPU로 동일한 트래픽을 서빙하여 인프라 비용을 직접 절감할 수 있습니다. PagedAttention에서 오는 4배의 메모리 효율성은 더 작고 저렴한 GPU 인스턴스를 사용하는 것도 가능하게 합니다.

Kubernetes 배포: vLLM의 상태 없음(stateless) 설계와 컨테이너 친화적 아키텍처는 Kubernetes 클러스터에 이상적입니다. 부하 하에서의 일관된 성능과 간단한 리소스 관리는 클라우드 네이티브 인프라와 잘 통합됩니다.

vLLM을 사용하지 말아야 할 때: 로컬 개발, 실험, 또는 단일 사용자 시나리오의 경우, Ollama 또는 llama.cpp와 같은 도구가 더 단순한 설정으로 더 나은 사용자 경험을 제공합니다. vLLM의 복잡성은 프로덕션 워크로드에서 그 성능 이점을 필요로 할 때 정당화됩니다.

vLLM 설치 방법

사전 요구 사항

vLLM을 설치하기 전에 시스템이 다음 요구 사항을 충족하는지 확인하십시오:

  • OS: glibc 2.35 이상을 갖춘 Linux (Ubuntu 22.04+, Debian 12+, RHEL 9+)
  • GPU: 컴퓨트 카피러빌리티 7.5 이상을 갖춘 NVIDIA GPU (T4, A10, A100, L4, H100, B200, RTX 20/30/40/50 시리즈). V100과 같은 구형 7.0세대 카드는 더 이상 지원 목록에 포함되지 않습니다. AMD GPU는 별도의 ROCm wheels을 통해 지원됩니다 — AMD 전용 이미지, 장치 플래그, 그리고 커널 커버리지 주의 사항에 대해 AMD 로컬 LLM 호스팅을 위한 ROCm vs Vulkan 비교를 참조하세요.
  • CUDA: 기본 pip wheels는 CUDA 12.9 기반으로 컴파일되었으며, 12.8 및 13.0 변형이 함께 게시됩니다. Blackwell GPU(B200, GB200)는 CUDA 12.8 이상을 요구합니다. 설치하려는 CUDA 버전에 맞춰 NVIDIA 드라이버가 충분히 최신이어야 합니다.
  • Python: 3.10부터 3.13까지 — 3.12가 권장 버전입니다 (ROCm wheels는 3.12 전용)
  • VRAM: 7B 모델에는 최소 16GB, 13B에는 24GB 이상, 더 큰 모델에는 40GB 이상

pip를 통한 설치

권장된 설치 방법은 uv를 사용하여 Python 3.12 환경을 생성하고 --torch-backend=auto로 설치된 드라이버를 검사하여 매칭되는 PyTorch CUDA 백엔드를 자동으로 선택하는 것입니다. uv 자체에 대해 더 깊이 알아보고 싶다면 uv: 새로운 Python 패키지 및 프로젝트 환경 매니저를 참조하세요:

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

# 설치 검증
python -c "import vllm; print(vllm.__version__)"

일반적인 pip도 작동합니다:

python3 -m venv vllm-env
source vllm-env/bin/activate
pip install vllm

기본 wheels는 CUDA 12.9 기반으로 컴파일됩니다. 다른 CUDA 버전이 필요하면 매칭되는 PyTorch wheel 인덱스를 가져와야 합니다. 예를 들어, CUDA 12.8의 경우:

pip install vllm --extra-index-url https://download.pytorch.org/whl/cu128

vllm==0.4.2+cu121과 같은 구형 고정 wheels는 더 이상 이 형태로 존재하지 않습니다. vLLM을 다른 PyTorch 빌드와 함께 기존 환경에 혼합하는 것은 설치 실패의 일반적인 원인입니다; 프로젝트에서는 새로운 환경을 권장하며, 맞춤형 CUDA 대상이 필요할 때 소스에서 빌드하는 것을 권장합니다.

Docker를 이용한 설치

Docker는 가장 신뢰할 수 있는 배포 방법을 제공하며, 특히 프로덕션에서 그렇습니다. 업그레이드가 의도적으로 이루어지도록 latest 대신 릴리스 버전을 고정하고, CUDA 12.9 (-cu129 태그 접미사), AMD ROCm (vllm-openai-rocm), CPU (vllm-openai-cpu) 및 Intel XPU (vllm-openai-xpu)를 위한 변형 이미지가 존재한다는 점을 유의하세요:

# 공식 vLLM 이미지 풀링
docker pull vllm/vllm-openai:v0.31.0

# GPU 지원으로 vLLM 실행
docker run --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:v0.31.0 \
    --model Qwen/Qwen3-8B

--ipc=host 플래그는 프로세스 간 통신을 가능하게 하므로 멀티 GPU 설정에서 중요합니다.

소스에서 빌드

최신 기능이나 사용자 정의 수정이 필요한 경우, 소스에서 빌드하십시오:

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

vLLM 퀵스타트 가이드

첫 번째 모델 실행

명령줄 인터페이스를 사용하여 모델로 vLLM을 시작합니다:

# OpenAI 호환 API로 모델 다운로드 및 서빙
vllm serve Qwen/Qwen3-8B \
    --port 8000

vllm serve는 OpenAI 호환 서버를 위한 현재 CLI입니다. 구버전인 python -m vllm.entrypoints.openai.api_server 호출은 여전히 실행되지만 비권장(deprecation) 경고를 출력하며 향후 릴리스에서 제거될 수 있으므로, 여전히 이를 사용하고 있는 스크립트나 Kubernetes 매니페스트를 업데이트해야 합니다.

vLLM은 모델이 캐시에 없으면 HuggingFace Hub에서 자동으로 다운로드하고 서버를 시작합니다. 서버가 준비되었음을 나타내는 출력을 볼 수 있습니다:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

API 요청 보내기

서버가 실행되면 OpenAI Python 클라이언트 또는 curl을 사용하여 요청을 보낼 수 있습니다:

curl 사용:

curl http://localhost:8000/v1/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "Qwen/Qwen3-8B",
        "prompt": "Explain what vLLM is in one sentence:",
        "max_tokens": 100,
        "temperature": 0.7
    }'

OpenAI Python 클라이언트 사용:

from openai import OpenAI

# vLLM 서버를 가리키기
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"  # vLLM은 서버를 --api-key로 시작하지 않는 한 이를 무시합니다
)

response = client.completions.create(
    model="Qwen/Qwen3-8B",
    prompt="Explain what vLLM is in one sentence:",
    max_tokens=100,
    temperature=0.7
)

print(response.choices[0].text)

Chat Completions API:

response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is PagedAttention?"}
    ],
    max_tokens=200
)

print(response.choices[0].message.content)

고급 설정

vLLM은 성능을 최적화하기 위해 다양한 매개변수를 제공합니다:

vllm serve Qwen/Qwen3-8B \
    --port 8000 \
    --gpu-memory-utilization 0.95 \  # GPU 메모리의 95% 사용
    --max-model-len 32k \            # 최대 시퀀스 길이 (8192와 32k 모두 작동)
    --tensor-parallel-size 2 \       # 텐서 병렬로 2개 GPU 사용
    --dtype float16 \                # FP16 정밀도 사용
    --max-num-seqs 256               # 최대 배치 크기

주요 매개변수 설명:

  • --gpu-memory-utilization: 모델 실행자를 위한 GPU 메모리의 비율 (기본값 0.92). 더 높은 값은 더 큰 배치를 허용하지만 메모리 스파이크를 위한 여유를 덜 남겨두게 됩니다.
  • --max-model-len: 최대 컨텍스트 길이. 토큰 수 또는 32k와 같은 인간 가독 가능한 값을 받아들입니다. 이 값을 줄이면 더 큰 배치를 위해 메모리를 절약합니다.
  • --tensor-parallel-size: 모델을 분할할 GPU의 수.
  • --dtype: 가중치를 위한 데이터 유형 (auto, float16, bfloat16, float32). auto는 체크포인트의 dtype을 따르며, 이것이 보통 원하는 것입니다.
  • --max-num-seqs: 배치 내 최대 시퀀스 수.
  • --max-num-active-seqs: max_num_seqs와 독립적으로 RUNNING 수용을 제한합니다 (v0.31.0 신규) — 스케줄러의 배치 창을 축소하지 않고 레이턴시를 제한하는 데 유용합니다.

vLLM vs Ollama

vLLM은 연속 배치, PagedAttention, 멀티 GPU 지원을 갖춘 고처리량, 멀티 사용자 프로덕션 서빙을 위해 설계되었습니다. Ollama는 빠른 로컬 설정, 단일 사용자 편의성, 간단한 모델 관리를 최적화합니다.

마이그레이션 신호, 계획 단계, Docker Compose 설정 및 실무적인 체크리스트를 다루는 상세한 의사결정 가이드를 위해 Ollama에서 vLLM으로: 로컬 LLM 서버를 언제 마이그레이션할 것인가를 참조하세요.

vLLM vs Docker Model Runner

Docker의 Model Runner는 로컬 AI 모델 배포를 위한 공식 솔루션입니다. vLLM과 비교하면 어떻게 될까요?

아키텍처 철학

Docker Model Runner는 “AI용 Docker"가 되고자 합니다 – 컨테이너를 실행하는 것과 동일한 손쉬움으로 로컬에서 AI 모델을 실행하기 위한 간단하고 표준화된 방법입니다. 이는 복잡성을 추상화하고 다양한 모델과 프레임워크 간에 일관된 인터페이스를 제공합니다.

vLLM은 최대 성능으로 LLM 서빙에만 전념하는 전문적인 추론 엔진입니다. 이는 완전한 플랫폼이 아니라 Docker로 컨테이너화하는 저레벨 도구입니다.

설정 및 시작하기

Docker Model Runner의 설치 방식은 Docker 사용자에게 직관적입니다:

docker model pull llama3:8b
docker model run llama3:8b

Docker의 이미지 워크플로우와 이러한 유사성은 이미 컨테이너를 사용하는 개발자에게 즉시 친숙하게 느껴지게 합니다; 전체 명령어 세트는 Docker Model Runner 치트시트에 있습니다.

vLLM은 더 많은 초기 설정(Python, CUDA, 의존성) 또는 사전 구축된 Docker 이미지 사용을 요구합니다:

docker pull vllm/vllm-openai:latest
docker run --runtime nvidia --gpus all vllm/vllm-openai:latest --model <model-name>

성능 특성

vLLM은 PagedAttention과 연속 배치 덕분에 멀티 사용자 시나리오에서 뛰어난 처리량을 제공합니다. 초당 수백 개의 요청을 처리하는 프로덕션 API 서비스의 경우, vLLM의 최적화는 범용 서빙 접근법보다 2-5배 높은 처리량을 제공합니다.

Docker Model Runner는 최대 성능이 아니라 사용 편의성에 초점을 맞춥니다. 로컬 개발, 테스트, 중간 수준의 워크로드에는 적합하지만, vLLM이 스케일에서 excel하게 만드는 고급 최적화를 구현하지는 않습니다.

모델 지원

Docker Model Runner는 인기 있는 모델에 대한 원-커맨드 접근을 제공하는 큐레이션된 모델 라이브러리를 제공합니다. 이는 LLM뿐만 아니라 Stable Diffusion, Whisper 및 기타 AI 모델을 포함한 여러 프레임워크를 지원하여 다양한 AI 워크로드에 더 다재다능합니다.

vLLM은 트랜스포머 기반 언어 모델에 대한 깊은 지원을 갖춘 LLM 추론에 전문화되어 있습니다. 모든 HuggingFace 호환 LLM을 지원하지만 이미지 생성이나 음성 인식과 같은 다른 AI 모델 유형으로는 확장되지 않습니다.

프로덕션 배포

vLLM은 Anthropic, Replicate 및 수일억 토큰을 매일 서빙하는 기타 많은 기업에서 프로덕션에서 검증되었습니다. 그 성능 특성과 무거운 부하 하에서의 안정성은 프로덕션 LLM 서빙의 사실상 표준으로 만듭니다.

Docker Model Runner는 더 신규하며 개발 및 로컬 테스트 시나리오에 더 많이 포지셔닝되고 있습니다. 프로덕션 트래픽을 서빙할 수는 있지만, 프로덕션 배포가 요구하는 검증된 track record와 성능 최적화 기능이 부족합니다.

통합 생태계

vLLM은 프로덕션 인프라 도구와 통합됩니다: Kubernetes 오เปร이터, Prometheus 메트릭, 분산 서빙을 위한 Ray, 그리고 기존 애플리케이션을 위한 광범위한 OpenAI API 호환성.

Docker Model Runner는 Docker의 생태계와 Docker Desktop과 자연스럽게 통합됩니다. Docker에 이미 표준화된 팀에게, 이 통합은 일관된 경험을 제공하지만 전문적인 LLM 서빙 기능은 적습니다.

언제 각각을 사용해야 하는가

vLLM을 사용하세요:

  • 프로덕션 LLM API 서비스
  • 고처리량, 멀티 사용자 배포
  • 최대 효율성이 필요한 비용 민감형 클라우드 배포
  • Kubernetes 및 클라우드 네이티브 환경
  • 검증된 확장성과 성능이 필요할 때

Docker Model Runner를 사용하세요:

  • 로컬 개발 및 테스트
  • 다양한 AI 모델 유형 실행 (LLM 제외)
  • Docker 생태계에 심도 있게 투자한 팀
  • 인프라 설정 없이 빠른 실험
  • 학습 및 교육 목적

하이브리드 접근: 많은 팀들이 편의를 위해 로컬에서 Docker Model Runner로 개발하고, 성능을 위해 프로덕션에서 vLLM으로 배포합니다. Docker Model Runner 이미지는 또한 vLLM 컨테이너를 실행하는 데 사용될 수 있어, 두 가지 접근 방식을 결합할 수 있습니다.

프로덕션 배포 모범 사례

Docker 배포

프로덕션 준비가 된 Docker Compose 구성을 생성하세요:

version: '3.8'

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    environment:
      - CUDA_VISIBLE_DEVICES=0,1
    volumes:
      - ~/.cache/huggingface:/root/.cache/huggingface
      - ./logs:/logs
    ports:
      - "8000:8000"
    command: >
      --model Qwen/Qwen3-8B
      --tensor-parallel-size 2
      --gpu-memory-utilization 0.90
      --max-num-seqs 256
      --max-model-len 8192
    restart: unless-stopped
    shm_size: '16gb'
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]

Kubernetes 배포

프로덕션 규모로 Kubernetes에 vLLM을 배포합니다:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        args:
          - --model
          - Qwen/Qwen3-8B
          - --tensor-parallel-size
          - "2"
          - --gpu-memory-utilization
          - "0.90"
        resources:
          limits:
            nvidia.com/gpu: 2
        ports:
        - containerPort: 8000
        volumeMounts:
        - name: cache
          mountPath: /root/.cache/huggingface
      volumes:
      - name: cache
        hostPath:
          path: /mnt/huggingface-cache
---
apiVersion: v1
kind: Service
metadata:
  name: vllm-service
spec:
  selector:
    app: vllm
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

모니터링 및 관측 가능성

OpenAI 호환 서버는 기본적으로 /metrics에서 Prometheus 메트릭을 노출합니다 — 추가 플래그가 필요하지 않습니다:

curl -s http://localhost:8000/metrics | grep '^vllm:'

모니터링해야 할 주요 메트릭:

  • vllm:num_requests_running / vllm:num_requests_waiting / vllm:num_requests_swapped — RUNNING, WAITING 및 SWAPPED 스케줄러 상태의 요청
  • vllm:kv_cache_usage_perc — 사용된 KV 캐시 블록의 비율 (0–1)
  • vllm:time_to_first_token_seconds — TTFT 히스토그램
  • vllm:time_per_output_token_seconds — 토큰당 생성 속도
  • vllm:num_preemptions_total — 누적 선점(preemptions); 증가하는 카운터는 KV 캐시가 오버서브스크라이브되어 요청이 재계산되고 있음을 의미합니다.

LLM 서빙을 중심으로 한 대시보드, PromQL 예제 및 경고 임계값에 대해 프로덕션에서 LLM 추론 모니터링 (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp를 참조하세요.

성능 튜닝

GPU 메모리 사용률 최적화: 기본값은 0.92입니다; 관찰된 행동에 따라 조정하세요. 더 높은 값은 더 큰 배치를 허용하지만 트래픽 스파이크 동안 OOM 오류의 위험을 감수하게 됩니다.

최대 시퀀스 길이 튜닝: 사용 사례에서 전체 컨텍스트 길이가 필요하지 않다면 --max-model-len을 줄이세요. 이는 더 큰 배치를 위해 메모리를 해제합니다. 예를 들어, 4K 컨텍스트만 필요하다면 모델의 최대값(종종 8K-32K) 대신 --max-model-len 4096으로 설정하세요.

적절한 양자화 선택: 이를 지원하는 모델의 경우, 양자화 버전(8-bit, 4-bit)을 사용하여 메모리를 줄이고 처리량을 높이세요:

--quantization awq  # AWQ 양자화 모델용
--quantization gptq # GPTQ 양자화 모델용

프refix 캐싱: prefix 캐싱은 현재 엔진에서 기본적으로 활성화되어 있으므로, 프롬프트 prefix(고정된 시스템 프롬프트, RAG 컨텍스트 템플릿 등)를 공유하는 요청은 플래그 없이 그 KV 캐시를 재사용합니다. 캐싱 bookkeeping이 아무것도 얻지 못하는 많은 고유한 긴 프롬프트를 가진 워크로드의 경우 --no-enable-prefix-caching으로 비활성화하세요.

공통 문제 해결

Out of Memory 오류

증상: 서버가 CUDA out of memory 오류로 충돌합니다.

솔루션:

  • --gpu-memory-utilization을 0.85 또는 0.80으로 감소
  • 사용 사례가 허용하는 경우 --max-model-len을 감소
  • 배치 크기를 줄이기 위해 --max-num-seqs를 낮추기
  • 양자화 모델 버전 사용
  • 더 많은 GPU로 분산하기 위해 텐서 병렬 활성화

두 가지 별개의 OOM 형태는 다른 수정이 필요합니다. 시작 시 OOM은 요청 전에 발생합니다: vLLM이 메모리를 프로파일링하고 최소 KV 캐시조차 할당하지 못하므로 --max-num-seqs 감소는 도움이 되지 않습니다 — 여유가 있다면 --max-model-len을 줄이거나 --gpu-memory-utilization을 높이세요. 부하 하에서의 런타임 OOM은 CUDA-graph 캡처 메모리에서 비롯될 수 있으며, 이는 --max-num-seqs와 함께 확장되지만 KV-cache 계산 밖에 있습니다; CUDA 그래프가 누락된 메모리인지 확인하기 위해 --enforce-eager를 사용하여 한 번 실행하고, 캐스를 비난하기 전에 동일한 구성을 재테스트하세요. 동일한 하드웨어에서 시작이 계속 성공하고 동일한 할당을 사용 중이라면, vLLM이 시작 시 기록하는 --kv-cache-memory-bytes 값을 전달하여 후속 부팅에서 프로파일링 패스를 건너뛰세요.

단일 16 GB 카드에서, 이러한 OOM 오류의 대부분은 가중치 자체보다는 KV-cache 예산으로 거슬러 올라갑니다 — 16 GB GPU에서 KV Cache는 더 작은 모델로 이동하기 전에 --max-model-len과 --max-num-seqs 뒤에 있는 정확한 공식, FP8 KV-cache dtype, prefix 캐싱 트레이드오프를 다룹니다.

느린 시작

증상: 서버가 “Application startup complete"까지 수 분이 걸립니다.

솔루션:

  • 가중치 로딩, 컴파일 및 CUDA-graph 캡처가 시작을 지배합니다 — --enforce-eager는 컴파일과 캡처를 모두 건너뛰며 부팅의 어느 부분이 그 비용인지 알려줍니다, 단 안정 상태 디코딩 속도의 대가로
  • 반복 부팅에서 메모리 프로파일링 및 CUDA-graph 추정 패스를 건너뛰기 위해 기록된 --kv-cache-memory-bytes 값을 재사용
  • v0.30.0+에서, vllm preload 명령어는 양자화 후 가중치를 GPU 메모리에 상주시키는 지속 가중치 캐시 데몬을 실행하여, 엔진 재시작이 디스크에서 다시 로드하는 대신 CUDA IPC를 통해 가중치를 맵핑하게 합니다 (--load-format ipc_cache)
  • 시작 시 컴파일 중 OOM이 발생하는 NVFP4 체크포인트의 경우, MAX_JOBS=4와 NVCC_THREADS=4로 빌드 스레드를 제한하는 것이 널리 사용되는 수정 방법입니다 — 이는 JIT 빌드를 늦추지만 OOM을 막습니다

낮은 처리량

증상: 서버가 예상보다 적은 요청을 처리합니다.

솔루션:

  • 더 큰 배치를 허용하기 위해 --max-num-seqs 증가
  • 여유가 있다면 --gpu-memory-utilization 높이기
  • htop으로 CPU가 병목인지 확인 – 더 빠른 CPU 고려
  • nvidia-smi로 GPU 사용률 검증 – 95% 이상이어야 합니다
  • FP32를 사용하고 있다면 FP16 활성화: --dtype float16

느린 첫 번째 토큰 시간

증상: 생성이 시작되기 전의 높은 레이턴시.

솔루션:

  • 레이턴시 크리티컬 애플리케이션에 더 작은 모델 사용
  • prefix 캐싱은 기본적으로 켜져 있습니다 — 플래그를 다시 추가하는 대신 활성화되어 있는지 확인
  • 레이턴시를 처리량보다 우선시하기 위해 --max-num-seqs 감소
  • 지원하는 경우 투기적 디코딩(speculative decoding) 고려
  • 텐서 병렬 구성 최적화

모델 로딩 실패

증상: 서버가 시작에 실패하고 모델을 로드할 수 없음.

솔루션:

  • 모델 이름이 HuggingFace 형식과 정확히 일치하는지 확인
  • HuggingFace Hub에 대한 네트워크 연결 확인
  • ~/.cache/huggingface에 충분한 디스크 공간 있는지 확인
  • 게이트된 모델의 경우, HF_TOKEN 환경 변수 설정
  • hf download <model> (또는 구형 설치의 경우 huggingface-cli download <model>)으로 수동 다운로드 시도

고급 기능

투기적 디코딩 (Speculative Decoding)

vLLM은 투기적 디코딩을 지원합니다. 여기서 더 작은 드래프트 모델이 더 큰 대상 모델이 검증하는 토큰을 제안합니다. 이는 생성을 1.5-2배 가속화할 수 있습니다. 투기적 디코딩 방법에 대한 포괄적인 가이드 — 드래프트 모델, EAGLE-3, P-EAGLE, n-gram — 를 위해 Speculative Decoding: 품질 손실 없이 빠른 추론.

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --speculative-config '{"method": "draft_model", "model": "meta-llama/Llama-3.2-1B-Instruct", "num_speculative_tokens": 4}'

구형 --speculative-model 및 --num-speculative-tokens 플래그는 사라졌고 — 구성은 단일 --speculative-config JSON 인수로 이동했으며, 이는 방법(draft_model, ngram, EAGLE 계열, 또는 네이티브 멀티 토큰 예측 헤드를 가진 모델의 경우 MTP)을 선택하기도 합니다.

LoRA 어댑터

기본 모델 위에 여러 LoRA 어댑터를 서빙하여 여러 전체 모델을 로드하지 않습니다:

vllm serve meta-llama/Llama-3.1-8B-Instruct \
    --enable-lora \
    --lora-modules sql-lora=/path/to/sql-adapter \
                   code-lora=/path/to/code-adapter

그 다음 요청마다 model 필드에 그 이름을 넣어 사용할 어댑터를 지정합니다 — 동일한 메커니즘은 메모리에 기본 모델만 상주 상태로 수십 개의 작업별 어댑터(고객별 또는 도메인별 변형)까지 확장됩니다:

response = client.completions.create(
    model="sql-lora",  # SQL 어댑터 사용
    prompt="Convert this to SQL: Show me all users created this month"
)

Prefix Caching

Prefix 캐싱은 공유 프롬프트 prefix에 대한 KV 캐시 재계산을 피하며, 현재 엔진에서 기본적으로 활성화되어 있습니다.

가장 큰 효과가 있는 경우:

  • 고정된 시스템 프롬프트를 가진 챗봇
  • 일관된 컨텍스트 템플릿을 가진 RAG 애플리케이션
  • 요청 간 반복되는 few-shot 학습 프롬프트

prefix를 공유하는 요청의 경우, 공유 부분의 prefill이 건너뛰어져 first-token 시간이 크게 줄어듭니다.

통합 예제

LangChain 통합

from langchain_community.llms import VLLMOpenAI

llm = VLLMOpenAI(
    openai_api_key="EMPTY",
    openai_api_base="http://localhost:8000/v1",
    model_name="Qwen/Qwen3-8B",
    max_tokens=512,
    temperature=0.7,
)

response = llm("Explain PagedAttention in simple terms")
print(response)

FastAPI 애플리케이션

from fastapi import FastAPI
from openai import AsyncOpenAI

app = FastAPI()
client = AsyncOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

@app.post("/generate")
async def generate(prompt: str):
    response = await client.completions.create(
        model="Qwen/Qwen3-8B",
        prompt=prompt,
        max_tokens=200
    )
    return {"result": response.choices[0].text}

성능 벤치마크

실세계 성능 데이터는 vLLM의 이점을 일러주는데 도움이 됩니다. 아래 숫자는 프로젝트의 초기 문서 및 초기 커뮤니티 측정에서 가져온 것입니다 — 이를 현재 모델 생성에 대한 현재 결과로서가 아니라, 아키텍처 효과의 크기 지표로 취급하세요:

처리량 비교 (A100 GPU에서 Mistral-7B):

  • vLLM: 64 동시 사용자로 초당 ~3,500 토큰
  • HuggingFace Transformers: 동일한 동시성으로 초당 ~250 토큰
  • Ollama: 동일한 동시성으로 초당 ~1,200 토큰
  • 결과: vLLM은 기본 구현 대비 14배 개선

메모리 효율성 (LLaMA-2-13B):

  • 표준 구현: 24GB VRAM, 32 동시 시퀀스
  • PagedAttention 사용 vLLM: 24GB VRAM, 128 동시 시퀀스
  • 결과: 동일한 메모리로 4배 더 많은 동시 요청

부하 하에서의 레이턴시 (2xA100에서 Mixtral-8x7B):

  • vLLM: 100 req/s에서 P50 레이턴시 180ms, P99 레이턴시 420ms
  • 표준 서빙: 100 req/s에서 P50 레이턴시 650ms, P99 레이턴시 3,200ms
  • 결과: vLLM은 높은 부하 하에서도 일관된 레이턴시를 유지

비용 분석

vLLM 선택의 비용 영향 이해:

시나리오: 하루 100만 요청 서빙

표준 서빙 사용 시:

  • 필요: 8x A100 GPU (80GB)
  • AWS 비용: ~$32/시간 × 24 × 30 = $23,040/월
  • 100만 토큰당 비용: ~$0.75

vLLM 사용 시:

  • 필요: 2x A100 GPU (80GB)
  • AWS 비용: ~$8/시간 × 24 × 30 = $5,760/월
  • 100만 토큰당 비용: ~$0.19
  • 절약: $17,280/월 (75% 감소)

이 비용 이점은 규모와 함께 커집니다. 월 수억 토큰을 서빙하는 조직은 vLLM의 최적화된 서빙을 사용하여 단순 구현보다 수십만 달러를 절약합니다.

보안 고려 사항

인증

vLLM은 내장 --api-key 플래그를 포함하지만, 공식 문서에 따르면 이는 /v1, /v2 및 /inference 경로 접두사 아래의 엔드포인트만 인증합니다 — 동일한 서버의 다른 엔드포인트는 인증되지 않은 상태가 유지됩니다. 이를 단일 레이어로 취급하고 전체 답변으로 보지 마세요; 전체 커버리지를 위해 리버스 프록시 레벨에서 인증을 구현하세요:

# Nginx 구성
location /v1/ {
    auth_request /auth;
    proxy_pass http://vllm-backend:8000;
}

location /auth {
    proxy_pass http://auth-service:8080/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

또는 엔터프라이즈 등급 인증 및 레이트 리미팅을 위해 Kong, Traefik, 또는 AWS API Gateway와 같은 API 게이트웨이를 사용하세요.

네트워크 격리

vLLM을 인터넷에 직접 노출하지 않고 사설 네트워크에서 실행하세요:

# Kubernetes NetworkPolicy 예제
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: vllm-access
spec:
  podSelector:
    matchLabels:
      app: vllm
  policyTypes:
  - Ingress
  ingress:
  - from:
    - podSelector:
        matchLabels:
          role: api-gateway
    ports:
    - protocol: TCP
      port: 8000

레이트 리미팅

악용을 방지하기 위해 레이트 리미팅을 구현하세요:

# Redis를 사용한 레이트 리미팅 예제
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
import redis
from datetime import datetime, timedelta

app = FastAPI()
redis_client = redis.Redis(host='localhost', port=6379)

@app.middleware("http")
async def rate_limit_middleware(request, call_next):
    client_ip = request.client.host
    key = f"rate_limit:{client_ip}"
    
    requests = redis_client.incr(key)
    if requests == 1:
        redis_client.expire(key, 60)  # 60초 윈도우
    
    if requests > 60:  # 분당 60 요청
        raise HTTPException(status_code=429, detail="Rate limit exceeded")
    
    return await call_next(request)

모델 액세스 제어

멀티 테넌트 배포의 경우, 사용자와 모델의 액세스를 제어하세요:

ALLOWED_MODELS = {
    "user_tier_1": ["Qwen/Qwen3-8B"],
    "user_tier_2": ["Qwen/Qwen3-8B", "meta-llama/Llama-2-13b-chat-hf"],
    "admin": ["*"]  # 모든 모델
}

def verify_model_access(user_tier: str, model: str) -> bool:
    allowed = ALLOWED_MODELS.get(user_tier, [])
    return "*" in allowed or model in allowed

마이그레이션 가이드

OpenAI에서 vLLM으로

API 호환성 덕분에 OpenAI에서 셀프 호스팅 vLLM으로의 마이그레이션은 간단합니다:

이전 (OpenAI):

from openai import OpenAI

client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello"}]
)

이후 (vLLM):

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vllm-server.com/v1",
    api_key="your-internal-key"  # 인증을 추가했다면
)
response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[{"role": "user", "content": "Hello"}]
)

단 두 가지 변경이 필요합니다: base_url과 model 이름 업데이트. 모든 다른 코드는 동일하게 유지됩니다.

Ollama에서 vLLM으로

Ollama은 다른 API 형식을 사용합니다. 기본 클라이언트 측 변경 사항은 Ollama의 REST 엔드포인트에서 vLLM의 OpenAI 호환 API로 전환하는 것입니다:

Ollama API:

import requests

response = requests.post('http://localhost:11434/api/generate',
    json={'model': 'llama2', 'prompt': 'Why is the sky blue?'})

vLLM 동등:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed")
response = client.completions.create(
    model="meta-llama/Llama-2-7b-chat-hf",
    prompt="Why is the sky blue?"
)

Ollama API는 자체 요청 형식을 가진 순수 REST인 반면, vLLM은 OpenAI 프로토콜을 speaks합니다 — 그 API 형식 차이가 주요 클라이언트 측 변경 사항이며, 단계적 접근 방식(두 서버 실행, 트래픽을 엔드포인트별로 이동)은 이 기사 앞부분에서 링크된 마이그레이션 가이드에서 다뤄집니다.

HuggingFace Transformers에서 vLLM으로

직접적인 Python 사용 마이그레이션:

HuggingFace:

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3-8B")
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-8B")

inputs = tokenizer("Hello", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=100)
result = tokenizer.decode(outputs[0])

vLLM:

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-8B")
sampling_params = SamplingParams(max_tokens=100)

outputs = llm.generate("Hello", sampling_params)
result = outputs[0].outputs[0].text

vLLM의 Python API는 배치 추론을 위해 더 간단하고 훨씬 더 빠릅니다.

최근 릴리스: 2026년에 무엇이 바뀌었는가

2026년 9~10월의 세 가지 릴리스(v0.29.0, v0.30.0, v0.31.0)는 개발이 어디로 향하고 있는지를 보여줍니다:

빠른 재시작: vllm preload는 양자화 후, TP-sharded 가중치를 GPU 메모리에 상주시키는 GPU별 지속 가중치 캐시 데몬을 시작하여, 재시작된 엔진이 디스크에서 다시 로드하는 대신 CUDA IPC (--load-format ipc_cache)를 통해 이를 맵핑합니다. 실험적인 vllm snapshot create/restore는 CRIU로 완전히 초기화된 엔진의 스냅샷을 찍습니다.

Model Runner V2에서의 투기적 디코딩: 드래프트 모델 투기적 디코딩, 사용자 정의 logits 프로세서 및 적응형 검증이 새로운 모델 러너로 이동했으며, LiLiCorr 드래프터가 추가되고 DFlash 드래프터를 위한 비동기 스케줄링이 도입되었습니다.

대규모 MoE 서빙: 새로운 균형 있는 전문가 병렬 all2all 백엔드 (--all2all-backend moonep), 시퀀스 병렬을 갖춘 DeepEPv2, 공유 전문가 오버랩을 갖춘 EPLB, 그리고 데이터 병렬과 결합된 prefill 컨텍스트 병렬.

스케줄링 제어: --max-num-active-seqs는 max_num_seqs와 독립적으로 RUNNING 수용을 제한하며, 대기 큐는 이제 이미 KV 블록을 가진 요청을 먼저 스케줄링합니다.

구형 vLLM 가이드의 로드맵 항목은 오랫동안 출시되었습니다 — GGUF 지원, 멀티모달 서빙, 분리된 prefill/decode 및 멀티 노드 추론은 모두 현재 릴리스의 일부이므로, 이를 “곧 출시 예정"이라고 목록에 올리는 모든 튜토리얼은 구식이라고 간주하세요. 모든 버전의 릴리스 노트는 vLLM 릴리스 페이지에 있습니다.

유용한 링크

이 사이트의 관련 기사

  • Ollama 치트시트 - 설치, 모델 관리, API 사용, 로컬 LLM 배포 모범 실천을 다루는 완전한 Ollama 명령어 참조 및 치트시트. vLLM과 함께 또는 대신 Ollama을 사용하는 개발자에게 필수적입니다.

  • Docker Model Runner vs Ollama: 무엇을 선택할 것인가? - Docker의 Model Runner와 Ollama의 로컬 LLM 배포에 대한 심층 비교, 성능, GPU 지원, API 호환성 및 사용 사례 분석. vLLM이 작동하는 경쟁 환경을 이해하는 데 도움이 됩니다.

외부 리소스 및 문서

  • vLLM GitHub 저장소 - 소스 코드, 포괄적인 문서, 설치 가이드, 활발한 커뮤니티 토론을 갖춘 공식 vLLM 저장소. 최신 기능과 문제 해결을 유지하기 위한 필수 리소스.

  • vLLM 문서 - 기본 설정부터 고급 구성까지 vLLM의 모든 측면을 다루는 공식 문서. API 참조, 성능 튜닝 가이드, 배포 모범 실천 포함.

  • PagedAttention 논문 - vLLM의 효율성을 뒷받침하는 PagedAttention 알고리즘을 소개하는 학술 논문. vLLM의 성능 이점 뒤에 있는 기술적 혁신을 이해하는 데 필수적인 읽기 자료.

  • vLLM 블로그 - 릴리스 발표, 성능 벤치마크, 기술 딥 다이버, 프로덕션 배포에서 온 커뮤니티 사례 연구를 특징으로 하는 공식 vLLM 블로그.

  • HuggingFace 모델 허브 - vLLM과 작동하는 오픈소스 LLM의 포괄적인 저장소. 크기, 작업, 라이선스, 성능 특성별로 모델을 검색하여 사용 사례에 맞는 모델을 찾으세요.

  • Ray Serve 문서 - 확장 가능한, 분산된 vLLM 배포를 구축하기 위한 Ray Serve 프레임워크 문서. Ray는 자동 확장, 멀티 모델 서빙, 프로덕션 시스템을 위한 리소스 관리와 같은 고급 기능을 제공합니다.

  • NVIDIA TensorRT-LLM - NVIDIA GPU에서 고탄도 최적화 추론을 위한 NVIDIA의 TensorRT-LLM. 다른 최적화 전략을 가진 vLLM의 대안으로, 비교 및 추론 최적화 양상을 이해하는 데 유용합니다.

  • OpenAI API 참조 - vLLM의 API가 호환되는 공식 OpenAI API 문서. OpenAI와 셀프 호스팅 vLLM 엔드포인트를 호환되게 작동해야 하는 애플리케이션을 구축할 때 이 문서를 참조하세요.

구독하기

시스템, 인프라, AI 엔지니어링에 관한 새 글을 받아보세요.