vLLM 빠른 시작: 2026년 고성능 LLM 서빙

vLLM는 UC 버클리의 Sky Computing Lab에서 개발한 대규모 언어 모델(LLM)을 위한 고처리량, 메모리 효율적인 추론 및 서빙 엔진입니다.

혁신적인 PagedAttention 알고리즘을 통해 vLLM은 기존 서빙 방식보다 14~24배 높은 처리량을 달성하여, 프로덕션 환경의 LLM 배포 시 가장 선호되는 선택지가 되었습니다. vLLM이 Ollama, Docker Model Runner, LocalAI 및 클라우드 제공사들 사이에서 어떻게 위치하는지, 비용과 인프라 트레이드오프를 포함한 비교를 확인하려면 LLM 호스팅: 로컬, 셀프호스트드 & 클라우드 인프라 비교를 참조하세요.

vLLM이란?

vLLM(Virtual LLM)은 빠른 LLM 추론과 서빙을 위한 오픈소스 라이브러리로, 프로덕션 배포의 업계 표준으로 빠르게 자리 잡고 있습니다. 2023년에 출시된 vLLM은 서빙 효율성을 극적으로 높이는 획기적인 메모리 관리 기술인 PagedAttention을 도입했습니다.

주요 특징

높은 처리량 성능: vLLM은 동일한 하드웨어에서 HuggingFace Transformers 대비 14~24배 높은 처리량을 제공합니다. 이 막대한 성능 향상은 컨티뉴어스 배치(Continuous Batching), 최적화된 CUDA 커널, 그리고 메모리 분할을 제거하는 PagedAttention 알고리즘에서 비롯됩니다.

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

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

컨티뉴어스 배치(Continuous Batching): 모든 시퀀스가 완료될 때까지 기다리는 정적 배치와 달리, vLLM은 컨티뉴어스(롤링) 배치를 사용합니다. 한 시퀀스가 끝나면 즉시 새 시퀀스를 배ちに 추가할 수 있습니다. 이를 통해 GPU 활용도를 극대화하고 incoming 요청의 지연 시간을 최소화합니다.

멀티-GPU 지원: vLLM은 텐서 평행성(Tensor Parallelism)과 파이프라인 평행성(Pipeline Parallelism)을 지원하여 대형 모델을 여러 GPU에 분산 배치합니다. 단일 GPU 메모리에 들어맞지 않는 모델을 효율적으로 서빙할 수 있으며, 2개에서 8개 이상의 GPU 구성을 지원합니다.

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

vLLM을 사용할 때

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

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

고동시성 워크로드: 동시 요청을 보내는 사용자가 많은 애플리케이션을 운영 중이라면, vLLM의 컨티뉴어스 배치와 PagedAttention은 다른 대안 대비 동일한 하드웨어로 더 많은 사용자를 서빙할 수 있게 해줍니다.

비용 최적화: GPU 비용이 걱정된다면, vLLM의 우수한 처리량을 통해 더 적은 GPU로 동일한 트래픽을 서빙하여 인프라 비용을 직접적으로 줄일 수 있습니다. PagedAttention에 따른 4배의 메모리 효율성은 더 작고 저렴한 GPU 인스턴스를 사용하는 것도 가능하게 합니다.

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

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

vLLM 설치 방법

사전 요구 사항

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

• GPU: Compute capability 7.0 이상의 NVIDIA GPU (V100, T4, A10, A100, H100, RTX 20/30/40 시리즈)
• CUDA: 버전 11.8 이상
• Python: 3.8 ~ 3.11
• VRAM: 7B 모델은 최소 16GB, 13B 모델은 24GB 이상, 더 큰 모델은 40GB 이상
• Driver: NVIDIA 드라이버 450.80.02 이상

pip를 통한 설치

가장 간단한 설치 방법은 pip를 사용하는 것입니다. 이는 CUDA 11.8 이상을 지원하는 시스템에서 작동합니다:

# 가상 환경 생성 (권장)
python3 -m venv vllm-env
source vllm-env/bin/activate

# vLLM 설치
pip install vllm

# 설치 확인
python -c "import vllm; print(vllm.__version__)"

CUDA 버전이 다른 시스템의 경우, 적절한 휠(wheel)을 설치하세요:

# CUDA 12.1용
pip install vllm==0.4.2+cu121 -f https://github.com/vllm-project/vllm/releases

# CUDA 11.8용
pip install vllm==0.4.2+cu118 -f https://github.com/vllm-project/vllm/releases

Docker를 통한 설치

Docker는 가장 신뢰할 수 있는 배포 방법을 제공하며, 특히 프로덕션 환경에서 유용합니다:

# 공식 vLLM 이미지 가져오기
docker pull vllm/vllm-openai:latest

# GPU 지원으로 vLLM 실행
docker run --runtime nvidia --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:latest \
    --model mistralai/Mistral-7B-Instruct-v0.2

--ipc=host 플래그는 프로세스 간 통신을 적절하게 활성화하기 때문에 멀티-GPU 설정에서 중요합니다.

소스 코드에서 빌드

최신 기능이나 커스텀 수정 사항이 필요한 경우 소스에서 빌드하세요:

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

vLLM 빠른 시작 가이드

첫 번째 모델 실행

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

# Mistral-7B를 다운로드하여 OpenAI 호환 API로 서빙
python -m vllm.entrypoints.openai.api_server \
    --model mistralai/Mistral-7B-Instruct-v0.2 \
    --port 8000

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": "mistralai/Mistral-7B-Instruct-v0.2",
        "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은 기본적으로 인증을 요구하지 않습니다
)

response = client.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.2",
    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="mistralai/Mistral-7B-Instruct-v0.2",
    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은 성능을 최적화하기 위해 수많은 파라미터를 제공합니다:

python -m vllm.entrypoints.openai.api_server \
    --model mistralai/Mistral-7B-Instruct-v0.2 \
    --port 8000 \
    --gpu-memory-utilization 0.95 \  # GPU 메모리의 95% 사용
    --max-model-len 8192 \            # 최대 시퀀스 길이
    --tensor-parallel-size 2 \        # 텐서 평행성으로 2개 GPU 사용
    --dtype float16 \                 # FP16 정밀도 사용
    --max-num-seqs 256                # 최대 배치 크기

주요 파라미터 설명:

• --gpu-memory-utilization: 사용할 GPU 메모리 비율 (0.90 = 90%). 값이 높을수록 더 큰 배치가 가능하지만 메모리 스파이크에 대한 여유가 줄어듭니다.
• --max-model-len: 최대 컨텍스트 길이. 이 값을 줄이면 더 큰 배치를 위해 메모리를 절약할 수 있습니다.
• --tensor-parallel-size: 모델을 분산 배치할 GPU의 수.
• --dtype: 가중치를 위한 데이터 타입 (float16, bfloat16, 또는 float32). 일반적으로 FP16이 최적입니다.
• --max-num-seqs: 배프로 처리할 최대 시퀀스 수.

vLLM vs Ollama

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

마이그레이션 신호, 계획 단계, Docker Compose 설정 및 실무 체크리스트를 포함한 상세한 의사결정 가이드를 확인하려면 Ollama to vLLM: 로컬 LLM 서버 마이그레이션 시점를 참조하세요.

vLLM vs Docker Model Runner

Docker는 최근 공식 로컬 AI 모델 배포 솔루션인 Model Runner(구 GenAI Stack)를 소개했습니다. 이는 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 이미지 워크플로와의 유사성은 이미 컨테이너를 사용 중인 개발자에게 즉시 익숙하게 느껴집니다.

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이 대규모로 우세해지는 데 기여하는 고급 최적화를 구현하지는 않습니다.

모델 지원

Docker Model Runner는 인기 있는 모델에 대한 원명령어 액세스가 포함된 큐레이션된 모델 라이브러리를 제공합니다. Stable Diffusion, Whisper 및 기타 AI 모델을 포함하여 여러 프레임워크(단순히 LLM만 아님)를 지원하므로 다양한 AI 워크로드에 더 다재다능합니다.

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

프로덕션 배포

vLLM은 Anthropic, Replicate 및 기타 많은 기업에서 프로덕션 환경에서 검증되어 하루 수조 개의 토큰을 서빙하고 있습니다. 높은 부하 하에서의 성능 특성과 안정성은 프로덕션 LLM 서빙의 사실상 표준을 만들어 줍니다.

Docker Model Runner는 비교적 새로워 개발 및 로컬 테스트 시나리오에 더 적합한 포지셔닝을 가지고 있습니다. 프로덕션 트래픽을 서빙할 수는 있지만, 프로덕션 배포에 필요한 검증된 레코드와 성능 최적화가 부족합니다.

통합 생태계

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 mistralai/Mistral-7B-Instruct-v0.2
      --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 배포

프로덕션 규모로 vLLM을 Kubernetes에 배포하세요:

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
          - mistralai/Mistral-7B-Instruct-v0.2
          - --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

모니터링 및 관찰 가능성

vLLM은 모니터링을 위해 Prometheus 메트릭을 노출합니다:

import requests

# 메트릭 가져오기
metrics = requests.get("http://localhost:8000/metrics").text
print(metrics)

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

• vllm:num_requests_running - 활성 요청 수
• vllm:gpu_cache_usage_perc - KV 캐시 사용률
• vllm:time_to_first_token - 지연 시간 메트릭
• vllm:time_per_output_token - 생성 속도

성능 튜닝

GPU 메모리 사용률 최적화: --gpu-memory-utilization 0.90으로 시작하여 관찰된 행동에 따라 조정하세요. 값이 높을수록 더 큰 배치가 가능하지만 트래픽 스파이크 중 OOM 오류 위험이 있습니다.

최대 시퀀스 길이 조정: 사용 사례에서 전체 컨텍스트 길이가 필요하지 않다면 --max-model-len을 줄이세요. 이를 통해 더 큰 배치를 위해 메모리를 확보할 수 있습니다. 예를 들어, 4K 컨텍스트만 필요하다면 모델의 최대 값(일반적으로 8K-32K) 대신 --max-model-len 4096을 설정하세요.

적절한 양자화(Quantization) 선택: 지원되는 모델의 경우, 양자화된 버전(8-bit, 4-bit)을 사용하여 메모리를 줄이고 처리량을 높일 수 있습니다:

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

프릭스 캐싱 활성화: 반복적인 프롬프트(시스템 메시지가 있는 챗봇 등)가 있는 애플리케이션의 경우, 프릭스 캐싱을 활성화하세요:

--enable-prefix-caching

이것은 공통 프릭스에 대한 KV 값을 캐시하여 동일한 프롬프트 프릭스를 공유하는 요청의 컴퓨테이션을 줄입니다.

일반적인 문제 해결

메모리 부족(OOM) 오류

증상: CUDA 메모리 부족 오류로 서버가 충돌합니다.

해결 방법:

• --gpu-memory-utilization을 0.85 또는 0.80으로 줄이기
• 사용 사례가 허용한다면 --max-model-len 줄이기
• 배치 크기를 줄이기 위해 --max-num-seqs 낮추기
• 양자화된 모델 버전 사용
• 더 많은 GPU에 분산 배치하기 위해 텐서 평행성 활성화

16GB 단일 카드에서 대부분의 OOM 오류는 가중치 자체보다 KV-캐시 예산에서 비롯됩니다. — 더 작은 모델로 전환하기 전에 --max-model-len과 --max-num-seqs 뒤의 정확한 공식, FP8 KV-캐시 dtype, 그리고 프릭스 캐싱 트레이드오프를 다루는 16 GB GPU에서의 KV Cache를 참조하세요.

낮은 처리량

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

해결 방법:

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

첫 토큰 시간 지연

증상: 생성 시작 전 높은 지연 시간.

해결 방법:

• 지연 시간 중요한 애플리케이션에는 더 작은 모델 사용
• 반복 프롬프트에 대해 프릭스 캐싱 활성화
• 처리량보다 지연 시간 우선시하기 위해 --max-num-seqs 줄이기
• 지원되는 모델의 경우 추측적 디코딩(Speculative Decoding) 고려
• 텐서 평행성 설정 최적화

모델 로딩 실패

증상: 서버 시작 실패, 모델 로딩 불가.

해결 방법:

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

고급 기능

추측적 디코딩(Speculative Decoding)

vLLM은 더 작은 드래프트 모델이 토큰을 제안하고 더 큰 타겟 모델이 이를 검증하는 추측적 디코딩을 지원합니다. 이를 통해 생성 속도를 1.5~2배로 가속할 수 있습니다. 드래프트 모델, EAGLE-3, P-EAGLE, n-gram을 포함한 추측적 디코딩 방법의 포괄적인 가이드를 확인하려면 Speculative Decoding: 품질 저하 없는 빠른 추론를 참조하세요.

python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-2-70b-chat-hf \
    --speculative-model meta-llama/Llama-2-7b-chat-hf \
    --num-speculative-tokens 5

LoRA 어댑터

여러 개의 전체 모델을 로딩하지 않고 베이스 모델 위에 여러 LoRA 어댑터를 서빙할 수 있습니다:

python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-2-7b-hf \
    --enable-lora \
    --lora-modules sql-lora=./path/to/sql-adapter \
                   code-lora=./path/to/code-adapter

그런 후 요청마다 사용할 어댑터를 지정합니다:

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

멀티-LoRA 서빙

vLLM의 멀티-LoRA 서빙은 최소한의 메모리 오버헤드로 수십 개의 파인튜닝된 어댑터를 호스팅할 수 있습니다. 이는 고객별 또는 작업별 모델 변형을 서빙하는 데 이상적입니다:

# 특정 LoRA 어댑터와 함께 요청
response = client.chat.completions.create(
    model="meta-llama/Llama-2-7b-hf",
    messages=[{"role": "user", "content": "Write SQL query"}],
    extra_body={"lora_name": "sql-lora"}
)

프릭스 캐싱

반복되는 프롬프트 프릭스에 대한 KV 캐시를 다시 계산하지 않도록 자동 프릭스 캐싱을 활성화하세요:

--enable-prefix-caching

이는 특히 다음과 같은 경우 효과적입니다:

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

프릭스 캐싱은 프롬프트 프릭스를 공유하는 요청의 첫 토큰 도달 시간을 50-80%까지 줄일 수 있습니다.

통합 예제

LangChain 통합

from langchain.llms import VLLMOpenAI

llm = VLLMOpenAI(
    openai_api_key="EMPTY",
    openai_api_base="http://localhost:8000/v1",
    model_name="mistralai/Mistral-7B-Instruct-v0.2",
    max_tokens=512,
    temperature=0.7,
)

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

LlamaIndex 통합

from llama_index.llms import VLLMServer

llm = VLLMServer(
    api_url="http://localhost:8000/v1",
    model="mistralai/Mistral-7B-Instruct-v0.2",
    temperature=0.7,
    max_tokens=512
)

response = llm.complete("What is vLLM?")
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="mistralai/Mistral-7B-Instruct-v0.2",
        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 요청 시 P50 지연 180ms, P99 지연 420ms
• 표준 서빙: 초당 100 요청 시 P50 지연 650ms, P99 지연 3,200ms
• 결과: vLLM은 높은 부하 하에서도 일관된 지연 시간 유지

이러한 벤치마크는 성능이 중요한 프로덕션 LLM 서빙에서 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에는 기본적으로 인증이 포함되어 있지 않습니다. 프로덕션 환경에서는 리버스 프록시 레벨에서 인증을 구현하세요:

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

location /auth {
    proxy_pass http://auth-service:880/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": ["mistralai/Mistral-7B-Instruct-v0.2"],
    "user_tier_2": ["mistralai/Mistral-7B-Instruct-v0.2", "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="mistralai/Mistral-7B-Instruct-v0.2",
    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 equivalent:

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 to vLLM: 로컬 LLM 서버 마이그레이션 시점를 참조하세요.

HuggingFace Transformers에서 vLLM으로

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

HuggingFace:

from transformers import AutoModelForCausalLM, AutoTokenizer

model = AutoModelForCausalLM.from_pretrained("mistralai/Mistral-7B-Instruct-v0.2")
tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-Instruct-v0.2")

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="mistralai/Mistral-7B-Instruct-v0.2")
sampling_params = SamplingParams(max_tokens=100)

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

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

vLLM의 미래

vLLM은 로드맵에 흥미로운 기능들을 두고 빠른 개발을 계속하고 있습니다:

분리된 서빙(Disaggregated Serving): 프릭(프롬프트 처리)과 디코드(토큰 생성)를 다른 GPU로 분리하여 리소스 활용도를 최적화합니다. 프릭은 컴퓨테이션 바운드리고 디코드는 메모리 바운드이므로, 전문 하드웨어에서 실행하면 효율성이 향상됩니다.

멀티노드 추론: 매우 큰 모델(100B+ 파라미터)을 여러 기계에 분산 배치하여, 단일 노드 설정에 맞지 않는 모델의 서빙을 가능하게 합니다.

향상된 양자화: llama.cpp에서 사용되는 GGUF와 같은 새로운 양자화 형식 및 양자화된 모델의 더 나은 성능을 위한 개선된 AWQ/GPTQ 통합 지원.

추측적 디코딩 개선: 정확도 손실 없이 더 높은 속도 향상을 달성하기 위한 더 효율적인 드래프트 모델 및 적응형 추측 전략.

어텐션 최적화: FlashAttention 3, 극도로 긴 컨텍스트(100K+ 토큰)를 위한 링 어텐션, 기타 최신 어텐션 메커니즘.

더 나은 모델 커버리지: 멀티모달 모델(비전-언어 모델), 오디오 모델 및 전문 아키텍처가 등장함에 따라 지원 확장.

vLLM 프로젝트는 UC Berkeley, Anyscale 및 더 넓은 오픈소스 커뮤니티의 기여로 활발한 개발을 유지하고 있습니다. LLM 배포가 프로덕션 시스템에 더 중요해짐에 따라, vLLM의 성능 표준으로서의 역할은 계속 성장하고 있습니다. vLLM과 다른 로컬 및 클라우드 LLM 인프라의 더 광범위한 비교를 확인하려면 LLM 호스팅: 로컬, 셀프호스트드 & 클라우드 인프라 비교를 확인하세요.

유용한 링크

이 사이트의 관련 아티클

• 로컬 LLM 호스팅: 2026 완벽 가이드 - Ollama, vLLM, LocalAI, Jan, LM Studio & 그 외 - Ollama, LocalAI, Jan, LM Studio 등을 포함하여 12개 이상의 로컬 LLM 호스팅 도구의 포괄적인 비교 및 vLLM의 상세 분석. API 성숙도, 도구 호출 지원, GGUF 호환성 및 성능 벤치마크를 다룹니다.

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

• CLI 및 서버를 사용한 llama.cpp 빠른 시작 - llama-cli 및 OpenAI 호환 llama-server를 이용한 GGUF 모델의 경량 C/C++ 추론. 세밀한 제어, 오프라인 배포 또는 Python 없는 최소 스택이 필요할 때 이상적입니다.

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

• Docker Model Runner 치트시트: 명령어 및 예제 - AI 모델 배포를 위한 명령어와 예제가 포함된 실용적인 Docker Model Runner 치트시트. vLLM의 전문적인 LLM 서빙 기능과 Docker의 접근법을 비교하는 팀에 유용합니다.

외부 리소스 및 문서

• 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에서 altamente 최적화된 추론을 위한 NVIDIA TensorRT-LLM. 다른 최적화 전략을 가진 vLLM의 대안으로, 추론 최적화 환경을 이해하고 비교하는 데 유용합니다.

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