vLLM 빠른 시작: 2026년 고성능 LLM 제공

OpenAI API를 사용한 빠른 LLM 추론

Page content

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

혁신적인 PagedAttention 알고리즘을 통해 vLLM은 전통적인 서빙 방법보다 14~24배 높은 처리량을 달성하며, 프로덕션 LLM 배포에 있어 최고의 선택이 되고 있습니다.

vllm logo

vLLM이란?

vLLM(virtual LLM)은 2023년에 출시된 빠른 LLM 추론 및 서빙을 위한 오픈소스 라이브러리로, 프로덕션 배포에 있어 산업 표준이 되었습니다. PagedAttention, 메모리 관리 기술의 혁신을 도입하여 서빙 효율성을 크게 향상시켰습니다.

주요 기능

고 처리량 성능: vLLM은 동일한 하드웨어에서 HuggingFace Transformers보다 14~24배 높은 처리량을 제공합니다. 이 높은 성능 향상은 연속 배치, 최적화된 CUDA 커널, 메모리 조각화를 제거하는 PagedAttention 알고리즘에서 비롯됩니다.

OpenAI API 호환성: vLLM은 OpenAI의 형식과 완전히 호환되는 내장 API 서버를 제공합니다. 이는 OpenAI에서 자체 호스팅 인프라로의 이전을 애플리케이션 코드 변경 없이 가능하게 합니다. 단순히 API 클라이언트를 vLLM의 엔드포인트로 지정하면 투명하게 작동합니다.

PagedAttention 알고리즘: vLLM 성능의 핵심 혁신은 PagedAttention으로, 가상 메모리 페이지링 개념을 어텐션 메커니즘에 적용합니다. KV 캐시에 연속적인 메모리 블록을 할당하는 대신, PagedAttention은 고정 크기의 블록을 필요에 따라 할당하도록 합니다. 이는 메모리 낭비를 최대 4배까지 줄이고 더 큰 배치 크기를 가능하게 합니다.

연속 배치: 정적 배치에서 모든 시퀀스가 완료될 때까지 기다리는 것과 달리, vLLM은 연속(롤링) 배치를 사용합니다. 하나의 시퀀스가 완료되면 새로운 시퀀스가 즉시 배치에 추가됩니다. 이는 GPU 활용도를 최대화하고 들어오는 요청의 지연 시간을 최소화합니다.

다중 GPU 지원: vLLM은 대규모 모델을 여러 GPU에 분산하기 위한 텐서 병렬성 및 파이프라인 병렬성을 지원합니다. 단일 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의 무상태 설계와 컨테이너 친화적인 아키텍처는 Kubernetes 클러스터에 이상적입니다. 부하 하에서 일관된 성능과 간단한 리소스 관리가 클라우드 네이티브 인프라와 잘 통합됩니다.

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

vLLM 설치 방법

사전 조건

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

  • GPU: NVIDIA GPU, compute capability 7.0 이상 (V100, T4, A10, A100, H100, RTX 20/30/40 시리즈)
  • CUDA: 11.8 이상
  • Python: 3.8 ~ 3.11
  • VRAM: 7B 모델은 최소 16GB, 13B는 24GB 이상, 더 큰 모델은 40GB 이상
  • 드라이버: 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 버전을 사용하는 시스템에서는 적절한 바이너리를 설치하세요:

# 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 빠른 시작 가이드

첫 번째 모델 실행

명령줄 인터페이스를 사용하여 모델을 시작하세요:

# OpenAI 호환 API로 Mistral-7B 다운로드 및 서빙
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)

채팅 완성 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과 Ollama 비교

vLLM과 Ollama 모두 로컬 LLM 호스팅에 인기 있는 선택이지만, 서로 다른 사용 사례를 대상으로 합니다. 각 도구를 사용해야 할 때를 이해하는 것은 프로젝트의 성공에 큰 영향을 미칩니다.

성능 및 처리량

vLLM은 다중 사용자 시나리오에서 최대 처리량을 위해 설계되었습니다. PagedAttention 알고리즘과 연속 배치는 수백 개의 동시 요청을 효율적으로 처리할 수 있게 합니다. 벤치마크에 따르면 vLLM은 표준 구현보다 1424배 높은 처리량을 달성하고, 고 동시성에서 Ollama보다 24배 높은 처리량을 제공합니다.

Ollama은 단일 사용자 상호작용을 최적화하고, 개인 요청에 대한 낮은 지연 시간을 중점으로 합니다. vLLM의 다중 사용자 처리량은 비슷하지 않지만, 개발 및 개인 사용에 있어 빠른 시작 시간과 높은 잔여 리소스 소비가 적은 성능을 제공합니다.

사용 편의성

Ollama은 간단함에서 우위를 차지합니다. 설치는 단일 명령(curl | sh)로 이루어지고, 모델 실행은 ollama run llama2처럼 간단합니다. 캐시 최적화 버전이 포함된 모델 라이브러리도 제공합니다. 사용자 경험은 Docker와 유사합니다 – 끌어오기, 실행, 완료.

vLLM은 더 많은 설정이 필요합니다: Python 환경 관리, CUDA 설치, 서빙 매개변수 이해, 수동 모델 지정. 학습 곡선은 더 가파르지만, 하드웨어에서 최대 성능을 뽑아내는 세부 조정을 얻을 수 있습니다. 이 복잡성은 프로덕션 배포에서 필요합니다.

API 및 통합

vLLM은 즉시 사용 가능한 OpenAI 호환 REST API를 제공하여 기존 애플리케이션에서 OpenAI API로의 이전이 가능합니다. 이는 클라우드 제공업체에서 자체 호스팅 인프라로의 프로덕션 서비스 이전 시 코드 변경 없이 가능하게 합니다.

Ollama은 간단한 REST API와 Python/JavaScript 라이브러리를 제공합니다. 기능적으로는 OpenAI 호환되지 않아, OpenAI 형식을 기대하는 애플리케이션과 통합할 때 코드 변경이 필요합니다. 그러나 Ollama-OpenAI 어댑터 같은 커뮤니티 프로젝트가 이 간극을 메우고 있습니다.

메모리 관리

vLLM의 PagedAttention 알고리즘은 동시 요청에 대해 뛰어난 메모리 효율성을 제공합니다. 동일한 VRAM으로 표준 구현보다 2~4배 더 많은 동시 사용자를 서비스할 수 있습니다. 이는 프로덕션 배포에서 직접적인 비용 절감으로 이어집니다.

Ollama은 단일 사용자 시나리오에 적합한 간단한 메모리 관리를 사용합니다. 자동으로 모델 로딩/언로딩을 활동에 따라 관리하며, 개발에 편리하지만 고 동시성 프로덕션 사용에는 최적화되지 않습니다.

다중 GPU 지원

vLLM은 텐서 병렬성 및 파이프라인 병렬성을 통해 2~8개 이상의 GPU에 모델을 효율적으로 분산합니다. 이는 단일 GPU 메모리에 들어지지 않는 대규모 모델(예: 70B 파라미터 LLM)을 서비스하는 데 필수적입니다.

Ollama은 현재 다중 GPU 지원이 제한되어 있으며, 주로 단일 GPU에서 최선의 성능을 보입니다. 이는 분산 추론이 필요한 매우 큰 모델에 적합하지 않습니다.

사용 사례 추천

vLLM을 선택할 때:

  • 많은 동시 사용자가 있는 프로덕션 API 서비스 제공
  • 클라우드 배포에서 요청당 비용 최적화
  • Kubernetes 또는 컨테이너 오케스트레이션 플랫폼에서 실행
  • 기존 애플리케이션에 OpenAI API 호환성 필요
  • 다중 GPU 지원이 필요한 대규모 모델 서비스
  • 성능과 처리량이 필수적인 요구사항

Ollama를 선택할 때:

  • 로컬 개발 및 실험
  • 단일 사용자 상호작용 (개인 어시스턴트, 챗봇)
  • 빠른 프로토타입 및 모델 평가
  • LLM에 대한 학습 없이 인프라 복잡성 없이
  • 개인 워크스테이션 또는 데스크탑에서 실행
  • 간단함과 사용 편의성이 우선순위

많은 팀이 두 가지를 모두 사용합니다: Ollama를 개발 및 실험에, vLLM을 프로덕션 배포에. 이 조합은 개발 생산성을 유지하면서 프로덕션 성능을 유지합니다.

vLLM과 Docker 모델 러너 비교

Docker는 최근 모델 러너(Model Runner, 이전 이름: GenAI Stack)를 공식적인 로컬 AI 모델 배포 솔루션으로 소개했습니다. 이는 vLLM과 어떻게 비교되는가?

아키텍처 철학

Docker 모델 러너는 “AI용 Docker"를 목표로 하며, 컨테이너와 동일한 방식으로 로컬에서 AI 모델을 실행할 수 있는 간단하고 표준화된 방법을 제공합니다. 이는 다양한 모델과 프레임워크에 대해 일관된 인터페이스를 제공합니다.

vLLM은 LLM 서빙에 특화된 최적화된 추론 엔진으로, 최대 성능을 위해 설계되었습니다. 이는 하위 수준 도구이며, Docker를 사용하여 컨테이너화해야 합니다.

설정 및 시작

Docker 모델 러너 설치는 Docker 사용자에게 간단합니다:

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

이 Docker 이미지 워크플로와의 유사성은 이미 컨테이너 사용에 익숙한 개발자에게 즉시 익숙하게 됩니다.

vLLM은 더 많은 초기 설정(파이썬, 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 모델 러너는 사용 편의성에 초점을 맞추며, 최대 성능보다는 로컬 개발, 테스트, 중간 워크로드에 적합합니다. 그러나 vLLM이 확장에 우수한 최적화를 제공하는 것과는 다릅니다.

모델 지원

Docker 모델 러너는 인기 있는 모델에 대한 정리된 라이브러리를 제공하며, Stable Diffusion, Whisper, 기타 AI 모델 등 다양한 프레임워크(LLM에 한정되지 않음)를 지원합니다. 이는 다양한 AI 워크로드에 더 유연합니다.

vLLM은 트랜스포머 기반 언어 모델에 깊은 지원을 제공하는 LLM 추론에 특화되어 있습니다. HuggingFace 호환 LLM은 지원하지만, 이미지 생성 또는 음성 인식과 같은 다른 AI 모델 유형은 지원하지 않습니다.

프로덕션 배포

vLLM은 Anthropic, Replicate 등 많은 회사에서 일일 수십억 토큰을 처리하는 데 검증된 경험이 있습니다. 높은 부하에서의 안정성과 성능 특성으로 인해 프로덕션 LLM 서빙의 표준이 되었습니다.

Docker 모델 러너는 더 최근에 출시되었으며, 개발 및 로컬 테스트 시나리오에 더 적합합니다. 프로덕션 트래픽을 처리할 수는 있지만, 프로덕션 배포에 필요한 검증된 기록과 성능 최적화는 제공하지 않습니다.

통합 생태계

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

Docker 모델 러너는 Docker 생태계와 Docker Desktop과 자연스럽게 통합됩니다. Docker에 표준화된 팀은 이 통합으로 일관된 경험을 제공하지만, 특화된 LLM 서빙 기능은 적습니다.

사용 시점

vLLM을 사용할 때:

  • 프로덕션 LLM API 서비스
  • 고 처리량, 다중 사용자 배포
  • 클라우드 배포에서 비용 효율성 필요
  • Kubernetes 및 클라우드 네이티브 환경
  • 확장성과 성능이 필수적인 경우

Docker 모델 러너를 사용할 때:

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

혼합 접근법: 많은 팀은 로컬에서 편리함을 위해 Docker 모델 러너를 사용하고, 프로덕션에서 성능을 위해 vLL段을 사용합니다. Docker 모델 러너 이미지도 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 배포

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
          - 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 컨텍스트만 필요하다면 --max-model-len 4096으로 설정하세요.

적절한 양자화 선택: 모델이 지원하는 경우, 양자화 버전(8비트, 4비트)을 사용하여 메모리를 줄이고 처리량을 증가시킬 수 있습니다:

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

프리픽스 캐싱 활성화: 반복된 프롬프트(예: 시스템 메시지가 있는 챗봇)가 있는 애플리케이션에 대해 프리픽스 캐싱을 활성화하세요:

--enable-prefix-caching

이 옵션은 일반적인 프리픽스의 KV 값을 캐시하여 동일한 프롬프트 프리픽스를 공유하는 요청에 대한 계산을 줄입니다.

일반적인 문제 해결

메모리 부족 오류

증상: 서버가 CUDA 메모리 부족 오류와 함께 크래시합니다.

해결책:

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

낮은 처리량

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

해결책:

  • --max-num-seqs를 늘려 더 큰 배치를 허용하세요
  • 여유가 있는 경우 --gpu-memory-utilization을 높이세요
  • htop으로 CPU 병목 현상을 확인하세요 – 더 빠른 CPU를 고려하세요
  • nvidia-smi로 GPU 사용률을 확인하세요 – 95% 이상이어야 합니다
  • FP32 사용 시 FP16으로 전환하세요: --dtype float16

첫 토큰 시간이 느림

증상: 생성 시작 전에 높은 지연 시간이 발생합니다.

해결책:

  • 지연 시간이 중요한 애플리케이션에 대해 더 작은 모델을 사용하세요
  • 반복된 프롬프트에 대해 프리픽스 캐싱을 활성화하세요
  • --max-num-seqs를 줄여 지연 시간을 우선시하세요
  • 지원되는 모델에 대해 예측적 생성을 고려하세요
  • 텐서 병렬성 설정을 최적화하세요

모델 로딩 실패

증상: 서버가 시작되지 않거나 모델을 로딩하지 못합니다.

해결책:

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

고급 기능

예측적 생성

vLLM은 더 작은 드래프트 모델이 토큰을 제안하고 더 큰 타겟 모델이 검증하는 예측적 생성을 지원합니다. 이는 생성 속도를 1.5~2배까지 높일 수 있습니다:

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의 이점들을 보여줍니다:

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

  • vLLM: ~3,500 토큰/초, 64개 동시 사용자
  • HuggingFace Transformers: ~250 토큰/초, 동일한 동시 사용자
  • Ollama: ~1,200 토큰/초, 동일한 동시 사용자
  • 결과: vLLM은 기본 구현보다 14배 향상된 성능

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

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

부하 하의 지연 시간 (Mixtral-8x7B on 2xA100):

  • vLLM: P50 지연 시간 180ms, P99 지연 시간 420ms at 100 req/s
  • 표준 서빙: P50 지연 시간 650ms, P99 지연 시간 3,200ms at 100 req/s
  • 결과: vLLM은 고부하에서도 일관된 지연 시간을 유지합니다

이 벤치마크는 vLLM이 성능이 중요한 프로덕션 LLM 서빙에서 de facto 표준이 되는 이유를 보여줍니다.

비용 분석

vLLM 선택의 비용 영향을 이해하세요:

시나리오: 1M 요청/일 서비스

표준 서빙 사용 시:

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

vLLM 사용 시:

  • 필요: 2x A100 GPU (80GB)
  • AWS 비용: ~$8/시간 × 24 × 30 = $5,760/월
  • 1M 토큰당 비용: ~$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: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 네트워크 정책 예시
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 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?"
)

코드베이스의 모든 API 호출을 업데이트해야 하지만, OpenAI 클라이언트 라이브러리는 더 나은 오류 처리와 기능을 제공합니다.

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은 빠른 개발을 계속하며 흥미로운 기능들이 도입되고 있습니다:

분리된 서빙: 프리필(프롬프트 처리)과 디코드(토큰 생성)를 다른 GPU에 분리하여 자원 사용률을 최적화합니다. 프리필은 계산에 제한이 있고, 디코드는 메모리에 제한이 있으므로, 전용 하드웨어에서 실행하여 효율성을 향상시킵니다.

다중 노드 추론: 100B+ 파라미터의 매우 큰 모델을 여러 머신에 분산하여, 단일 노드 설정에서 처리할 수 없는 모델을 서비스할 수 있게 합니다.

향상된 양자화: llama.cpp에서 사용하는 GGUF(예: GGUF) 및 AWQ/GPTQ 통합 개선을 위한 새로운 양자화 형식을 지원합니다.

예측적 생성 개선: 정확도 손실 없이 더 효율적인 드래프트 모델 및 적응형 예측 전략을 도입하여 더 높은 속도 향상을 달성합니다.

어텐션 최적화: FlashAttention 3, 100K+ 토큰의 고장치를 위한 링 어텐션, 그리고 다른 최신 어텐션 메커니즘을 지원합니다.

더 나은 모델 커버리지: 멀티모달 모델(비주얼-언어 모델), 오디오 모델, 그리고 특수한 아키텍처를 지원하여 확장합니다.

vLLM 프로젝트는 UC Berkeley, Anyscale, 그리고 더 넓은 오픈소스 커뮤니티에서 활발한 개발을 유지하고 있습니다. LLM 배포가 프로덕션 시스템에 더 중요해지면서, vLLM은 성능 표준으로서의 역할이 계속 성장하고 있습니다.

유용한 링크

이 사이트의 관련 기사

  • 로컬 LLM 호스팅: 2026년 완전 가이드 - Ollama, vLLM, LocalAI, Jan, LM Studio & 더 많은 것들 - Ollama, vLLM, LocalAI, Jan, LM Studio 및 기타 도구를 포함한 12개 이상의 로컬 LLM 호스팅 도구에 대한 포괄적인 비교. API 성숙도, 도구 호출 지원, GGUF 호환성 및 성능 벤치마크를 통해 적절한 솔루션을 선택하는 데 도움을 줍니다.

  • Ollama 쉬트컷 - 설치, 모델 관리, API 사용 및 로컬 LLM 배포를 위한 최고의 실천 가이드를 포함한 Ollama 명령어의 완전한 참조 및 쉬트컷. Ollama를 vLLM 대신 사용하거나 함께 사용하는 개발자에게 필수입니다.

  • Docker 모델 러너 vs Ollama: 어떤 것을 선택해야 할까요? - Docker의 모델 러너와 Ollama를 로컬 LLM 배포에 사용할 때의 성능, GPU 지원, API 호환성 및 사용 사례에 대한 심층 비교. vLLM이 운영되는 경쟁 환경을 이해하는 데 도움이 됩니다.

  • Docker 모델 러너 쉬트컷: 명령어 및 예제 - AI 모델 배포를 위한 실용적인 Docker 모델 러너 쉬트컷으로 명령어 및 예제가 포함되어 있습니다. Docker의 접근 방식을 vLLM의 전용 LLM 서빙 기능과 비교하는 팀에게 유용합니다.

외부 자원 및 문서

  • vLLM GitHub 저장소 - 공식 vLLM 저장소로 소스 코드, 포괄적인 문서, 설치 가이드 및 활발한 커뮤니티 토론이 포함되어 있습니다. 최신 기능을 파악하고 문제 해결에 도움이 되는 필수 자원입니다.

  • vLLM 문서 - vLLM의 기본 설정부터 고급 구성까지 모든 측면을 다루는 공식 문서입니다. API 참조, 성능 최적화 가이드 및 배포 최고 실천 가이드가 포함되어 있습니다.

  • PagedAttention 논문 - vLLM의 효율성을 가능하게 하는 PagedAttention 알고리즘을 소개한 학술 논문입니다. vLLM의 성능 우위에 대한 기술 혁신을 이해하는 데 필수적인 읽을거리입니다.

  • vLLM 블로그 - vLLM의 공식 블로그로 릴리스 발표, 성능 벤치마크, 기술 심층 분석 및 프로덕션 배포에서의 커뮤니티 사례 연구가 포함되어 있습니다.

  • HuggingFace 모델 허브 - vLLM과 호환되는 오픈소스 LLM 모델의 포괄적인 저장소입니다. 모델 크기, 작업, 라이선스 및 성능 특성에 따라 사용 사례에 적합한 모델을 찾을 수 있습니다.

  • Ray Serve 문서 - Ray Serve 프레임워크 문서로 스케일 가능한 분산 vLLM 배포를 구축하는 방법을 설명합니다. Ray는 자동 확장, 다중 모델 서빙 및 자원 관리와 같은 생산 시스템을 위한 고급 기능을 제공합니다.

  • NVIDIA TensorRT-LLM - NVIDIA의 TensorRT-LLM은 NVIDIA GPU에서 고도로 최적화된 추론을 수행합니다. vLLM과 다른 최적화 전략을 사용하는 대안으로, 추론 최적화의 전반적인 풍경을 이해하는 데 유용합니다.

  • OpenAI API 참조 - vLLM의 API와 호환되는 공식 OpenAI API 문서입니다. OpenAI와 자주 사용하는 vLLM 엔드포인트를 교차적으로 사용해야 하는 애플리케이션을 개발할 때 참고할 수 있습니다.