vLLM이란 무엇이며, 왜 사용해야 할까요?

vLLM은 UC 버클리에서 개발한 고성능 LLM 추론 및 서빙 라이브러리로, PagedAttention을 통해 효율적인 메모리 관리를 제공합니다. 이는 표준 HuggingFace Transformers 대비 14~24배 높은 처리량을 제공하여 최대 성능이 요구되는 프로덕션 환경에 이상적입니다.

로컬 LLM 호스팅에서 vLLM과 Ollama는 어떻게 비교되나요?

vLLM은 뛰어난 배칭(batching) 및 다중 GPU 지원으로 높은 처리량이 요구되는 프로덕션 환경에서 강점을 보이며, Ollama는 간편한 설정과 우수한 사용자 경험으로 단일 사용자 배포에 적합합니다. vLLM은 많은 동시 요청을 처리하는 API 서비스에 가장 적합하고, Ollama는 로컬 개발 및 실험에 적합합니다.

Docker와 함께 vLLM을 사용할 수 있나요?

네, vLLM는 배포를 간소화하는 공식 Docker 이미지를 제공합니다. NVIDIA Container Toolkit을 사용하여 컨테이너 환경에서 GPU 지원을 통해 vLLM을 실행할 수 있습니다. 프로덕션 환경 및 Kubernetes 클러스터에서는 Docker 배포가 권장됩니다.

vLLM은 OpenAI API 형식을 지원합니까?

네, vLLM은开箱으로 OpenAI 호환 API 서버를 제공합니다. 이를 통해 기존 애플리케이션에서 코드 수정 없이 vLLM을 OpenAI API의 대안으로 바로 사용할 수 있어 마이그레이션이 원활하게 이루어집니다.

vLLM에는 어떤 하드웨어가 필요한가요?

vLLM은 CUDA 지원(NVIDIA GPU, 컴퓨팅 기능 7.0 이상)이 필요합니다. 7B 모델은 최소 16GB VRAM, 13B 모델은 24GB 이상, 30B 이상 모델은 40GB 이상의 VRAM이 필요합니다. CPU 전용 추론은 지원되지 않으며, vLLM은 GPU 가속을 위해 특별히 최적화되어 있습니다.

vLLM을 어떻게 설치하나요?

CUDA 11.8 이상을 지원하는 GPU 시스템에서는 ‘pip install vllm’ 명령어로 vLLM을 설치하십시오. 다른 CUDA 버전의 경우 vLLM 저장소에서 특정 휠(wheel) 파일을 사용하십시오. Docker 사용자는 ‘docker pull vllm/vllm-openai:latest’ 명령어로 공식 이미지를 가져올 수 있습니다.

vLLM의 PagedAttention이란 무엇인가요?

PagedAttention는 OS 가상 메모리 페이징에서 영감을 얻은 vLLM의 메모리 최적화 기법입니다. 이는 메모리 단편화로 인한 낭비를 4배까지 줄여 더 큰 배치 크기와 높은 처리량을 가능하게 하며, vLLM의 성능 우위를 확보하는 핵심 혁신입니다.

vLLM은 동시에 여러 모델을 처리할 수 있습니까?

vLLM은 단일 모델을 최대 처리량(throughput)으로 효율적으로 서비스하는 데 중점을 둡니다. 다중 모델 서비스의 경우, 여러 vLLM 인스턴스를 배포하거나 오케스트레이션 도구를 사용합니다. 이러한 설계 선택은 고트래픽 단일 모델 배포 환경에서 vLLM의 우수한 성능을 가능하게 합니다.

vLLM과 Ollama 및 기타 LLM 호스팅 대안을 비교할 수 있는 곳은 어디입니까?

우리의 LLM 호스팅 개요는 vLLM을 Ollama, Docker Model Runner, LocalAI 및 클라우드 제공업체와 비교하며 비용, 성능, 인프라의 장단점을 다룹니다.

cloud LLM API보다 vLLM을 언제 선택해야 할까요?

LLM 호스팅 가이드는 고처리량 및 자체 호스팅 제어가 필요한 경우 vLLM 사용 시기와 클라우드 API와의 차이점, 그리고 비용과 운영 복잡도 측면에서의 비교를 설명합니다.

vLLM 빠른 시작: 고성능 LLM 서비스 제공 - 2026년

OpenAI API를 활용한 빠른 LLM 추론

Page content

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

혁신적인 PagedAttention 알고리즘을 통해 vLLM은 기존 서빙 방식보다 14-24배 높은 처리량을 달성하여 프로덕션 LLM 배포의 표준으로 자리 잡았습니다. Ollama, Docker Model Runner, LocalAI 및 클라우드 제공업체(비용 및 인프라 트레이드오프 포함)와의 비교를 통해 vLLM이 어떻게 활용되는지 확인하려면 LLM 호스팅: 로컬, 자체 호스팅 및 클라우드 인프라 비교을 참조하세요.

vLLM이란 무엇인가요?

vLLM(가상 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 활용도를 극대화하고 들어오는 요청의 지연 시간을 최소화합니다.

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

광범위한 모델 지원: LLaMA, Mistral, Mixtral, Qwen, Phi, Gemma를 비롯한 인기 있는 모델 아키텍처와 호환됩니다. HuggingFace Hub의 지시 튜닝(instruction-tuned) 모델과 베이스(base) 모델 모두를 지원합니다.

vLLM을 언제 사용해야 할까요?

vLLM은 다음과 같은 특정 시나리오에서 강점이 빛을 발합니다:

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

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

비용 최적화: GPU 비용이 문제인 경우, vLLM의 우수한 처리량은 더 적은 GPU로 동일한 트래픽을 서빙할 수 있게 하여 인프라 비용을 직접적으로 줄입니다. PagedAttention의 4배 메모리 효율성은 더 작고 저렴한 GPU 인스턴스를 사용할 수 있게 해줍니다.

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

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

vLLM 설치 방법

전제 조건

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

GPU: 컴퓨팅 기능 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+
드라이버: 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에서 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는 인기 있는 모델에 대한 원클릭 접근을 갖춘 큐레이팅된 모델 라이브러리를 제공합니다. 이는 여러 프레임워크(LLM뿐만 아니라)를 지원하며, Stable Diffusion, Whisper 및 기타 AI 모델을 포함하여 다양한 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 배포

프로덕션 규모로 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 컨텍스트만 필요하면 모델의 최대치(종종 8K-32K) 대신 --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 감소
지원되는 모델에 대해 예측 디코딩(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 등)에 대한 종합적인 가이드는 예측 디코딩: 품질 손실 없는 더 빠른 추론을 참조하세요.

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 req/s에서 P50 지연 시간 180ms, P99 지연 시간 420ms
표준 서빙: 100 req/s에서 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: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": ["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 동등:

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에서 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+ 토큰)를 위한 링 어텐션(ring attention), 그리고 기타 최첨단 어텐션 메커니즘.

더 나은 모델 커버리지: 멀티모달 모델(비전-언어 모델), 오디오 모델 및 새롭게 등장하는 특화 아키텍처에 대한 지원 확장.

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

유용한 링크

이 사이트의 관련 기사

로컬 LLM 호스팅: 2026 완전 가이드 - Ollama, vLLM, LocalAI, Jan, LM Studio 등 - Ollama, LocalAI, Jan, LM Studio 등과의 상세 vLLM 분석을 포함한 12개 이상의 로컬 LLM 호스팅 도구 종합 비교. 올바른 솔루션을 선택하는 데 도움이 되는 API 성숙도, 도구 호출 지원, GGUF 호환성 및 성능 벤치마크를 다룹니다.
Ollama 치트시트 - 설치, 모델 관리, API 사용 및 로컬 LLM 배포 모범 사례를 다루는 완전한 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 치트시트. Docker의 접근 방식과 vLLM의 특화된 LLM 서빙 기능을 비교하는 팀에게 유용합니다.

외부 리소스 및 문서

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 엔드포인트 모두와 함께 작동해야 하는 애플리케이션을 빌드할 때 참조하세요.

vLLM이란 무엇인가요?

주요 기능

vLLM을 언제 사용해야 할까요?

vLLM 설치 방법

전제 조건

pip를 통한 설치

Docker를 통한 설치

소스에서 빌드

vLLM 빠른 시작 가이드

첫 번째 모델 실행

API 요청하기

고급 구성

vLLM vs Ollama

vLLM vs Docker Model Runner

아키텍처 철학

설정 및 시작

성능 특성

모델 지원

프로덕션 배포

통합 생태계

각각을 언제 사용해야 할까요

프로덕션 배포 모범 사례

Docker 배포

Kubernetes 배포

모니터링 및 관찰 가능성

성능 튜닝

일반적인 문제 해결

메모리 부족 오류

낮은 처리량

느린 첫 번째 토큰 시간

모델 로드 실패

고급 기능

예측 디코딩(Speculative Decoding)

LoRA 어댑터

멀티 LoRA 서빙

접두사 캐싱

통합 예제

LangChain 통합

LlamaIndex 통합

FastAPI 애플리케이션

성능 벤치마크

비용 분석

시나리오: 일일 100만 요청 서빙

보안 고려 사항

인증

네트워크 격리

속도 제한

모델 액세스 제어

마이그레이션 가이드

OpenAI에서 vLLM으로

Ollama에서 vLLM으로

HuggingFace Transformers에서 vLLM으로

vLLM의 미래

유용한 링크

이 사이트의 관련 기사

외부 리소스 및 문서

구독하기