vLLM 사용법: 빠른 LLM Inference Engine 가이드 (2026)

vLLM 사용법: 빠른 LLM 추론 엔진 가이드 (2026)

vLLM은 대규모 언어 모델 서빙을 위한 가장 빠른 오픈 소스 추론 엔진입니다. UC Berkeley에서 개발된 이 엔진은 PagedAttention이라는 기술을 사용하여 기존 HuggingFace 구현체보다 최대 24배 더 높은 처리량(throughput)을 제공합니다. 프로덕션 환경에서 LLM을 서빙하거나, 팀을 위해 모델을 자체 호스팅(self-host)하거나, 로컬 추론을 효율적으로 실행해야 한다면 vLLM은 반드시 익혀야 할 도구입니다.

이 가이드에서는 설치, 기본 서빙, 고급 최적화 및 프로덕션 배포를 다룹니다.

왜 vLLM인가?

시작하기에 앞서, 다른 서빙 옵션들과 vLLM을 비교한 결과입니다:

기능	vLLM	TGI (HuggingFace)	Ollama	llama.cpp	TensorRT-LLM
처리량 (Throughput)	매우 우수	우수	보통	보통	매우 우수
지연 시간 (Latency)	낮음	낮음	보통	낮음	매우 낮음
GPU 지원	NVIDIA, AMD, TPU	NVIDIA	NVIDIA, Apple	CPU, NVIDIA, Apple	NVIDIA 전용
모델 지원	HuggingFace, GGUF	HuggingFace	GGUF	GGUF	커스텀 포맷
OpenAI 호환 API	지원	지원	지원	지원 (서버 모드)	지원
텐서 병렬화 (Tensor parallelism)	지원	지원	지원 안 함	지원 안 함	지원
투기적 디코딩 (Speculative decoding)	지원	제한적 지원	지원 안 함	지원	지원
프로덕션 적합성	적합	적합	부적합	부적합	적합
설정 난이도	중간	중간	쉬움	쉬움	어려움

vLLM은 다수의 동시 사용자가 있는 고처리량 서빙에 탁월합니다. 분당 수백 또는 수천 개의 요청을 처리해야 하는 API를 구축한다면 vLLM이 최적의 선택입니다.

1단계: 설치

사전 요구 사항

• CUDA 12.1+가 설치된 NVIDIA GPU (또는 ROCm 6.0+가 설치된 AMD GPU)
• Python 3.9-3.12
• 7B 모델의 경우 최소 16GB GPU VRAM, 13B는 24GB+, 70B는 80GB+ 권장

pip을 통한 설치

# 가상 환경 생성
python -m venv vllm-env
source vllm-env/bin/activate

# vLLM 설치
pip install vllm

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

Docker를 통한 설치 (프로덕션 권장)

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

# GPU 액세스 권한으로 실행
docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  -p 8000:8000 \
  vllm/vllm-openai:latest \
  --model meta-llama/Llama-3.3-70B-Instruct \
  --tensor-parallel-size 4

소스에서 설치 (최신 기능 사용 시)

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

2단계: 첫 번째 모델 서빙하기

OpenAI 호환 서버 시작

# Llama 3.3 8B 서빙 (단일 24GB GPU에 적합)
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.3-8B-Instruct \
  --port 8000

# 서버가 시작되어 http://localhost:8000 에서 대기합니다.

서버 테스트

# curl 사용
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.3-8B-Instruct",
    "messages": [
      {"role": "user", "content": "피보나치 수열을 계산하는 파이썬 함수를 작성해줘"}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

# OpenAI Python SDK 사용
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="dummy"  # vLLM은 기본적으로 인증을 요구하지 않습니다.
)

response = client.chat.completions.create(
    model="meta-llama/Llama-3.3-8B-Instruct",
    messages=[
        {"role": "system", "content": "당신은 유능한 코딩 도우미입니다."},
        {"role": "user", "content": "파이썬의 async/await에 대해 예시와 함께 설명해줘"}
    ],
    temperature=0.7,
    max_tokens=1024
)

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

// OpenAI Node.js SDK 사용
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8000/v1",
  apiKey: "dummy",
});

const response = await client.chat.completions.create({
  model: "meta-llama/Llama-3.3-8B-Instruct",
  messages: [
    { role: "user", content: "입력 디바운싱을 위한 React 훅을 작성해줘" },
  ],
  temperature: 0.7,
  max_tokens: 1024,
});

console.log(response.choices[0].message.content);

3단계: 성능 최적화

텐서 병렬화 (Tensor Parallelism - 다중 GPU)

더 빠른 추론을 위해 대규모 모델을 여러 GPU로 분할합니다.

# 4개의 GPU에 70B 모델 분할 서빙
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.3-70B-Instruct \
  --tensor-parallel-size 4 \
  --port 8000

모델 크기	필요한 GPU 수	TP 크기	GPU당 VRAM
7-8B	1x 24GB	1	~16GB
13B	1x 40GB 또는 2x 24GB	1-2	~26GB
34B	2x 40GB 또는 4x 24GB	2-4	~18GB/GPU
70B	4x 24GB 또는 2x 80GB	2-4	~18-40GB/GPU
405B	8x 80GB	8	~52GB/GPU

양자화 (Quantization)

품질을 유지하면서 VRAM 사용량을 줄이기 위해 양자화된 모델을 서빙합니다.

# GPTQ 양자화 모델 서빙 (4-bit)
python -m vllm.entrypoints.openai.api_server \
  --model TheBloke/Llama-3.3-70B-Instruct-GPTQ \
  --quantization gptq \
  --tensor-parallel-size 2 \
  --port 8000

# AWQ 양자화 모델 서빙
python -m vllm.entrypoints.openai.api_server \
  --model TheBloke/Llama-3.3-70B-Instruct-AWQ \
  --quantization awq \
  --tensor-parallel-size 2 \
  --port 8000

# FP8 양자화 (H100에서 최적의 품질/크기 균형)
python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.3-70B-Instruct \
  --quantization fp8 \
  --tensor-parallel-size 2 \
  --port 8000

투기적 디코딩 (Speculative Decoding)

더 작은 "드래프트(draft)" 모델을 사용하여 더 큰 "타겟(target)" 모델의 생성 속도를 높입니다.

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.3-70B-Instruct \
  --speculative-model meta-llama/Llama-3.3-8B-Instruct \
  --num-speculative-tokens 5 \
  --tensor-parallel-size 4 \
  --port 8000

투기적 디코딩은 품질 저하 없이 많은 워크로드에서 처리량을 1.5~2배 향상시킬 수 있습니다.

프리픽스 캐싱 (Prefix Caching)

반복되는 시스템 프롬프트를 사용하는 워크로드를 위해 자동 프리픽스 캐싱을 활성화합니다.

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.3-70B-Instruct \
  --enable-prefix-caching \
  --tensor-parallel-size 4 \
  --port 8000

이는 동일한 시스템 프롬프트나 컨텍스트 프리픽스를 공유하는 요청의 속도를 혁신적으로 높여줍니다.

청크 프리필 (Chunked Prefill)

긴 컨텍스트 워크로드에서 낮은 지연 시간을 유지하기 위해 청크 프리필을 활성화합니다.

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.3-70B-Instruct \
  --enable-chunked-prefill \
  --max-num-batched-tokens 8192 \
  --port 8000

4단계: 프로덕션 환경 설정

프로덕션 권장 실행 명령

python -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.3-70B-Instruct \
  --tensor-parallel-size 4 \
  --port 8000 \
  --host 0.0.0.0 \
  --max-model-len 32768 \
  --max-num-seqs 256 \
  --enable-prefix-caching \
  --gpu-memory-utilization 0.92 \
  --disable-log-requests \
  --api-key "your-secret-api-key"

주요 프로덕션 파라미터

파라미터	설명	기본값	권장 설정
--gpu-memory-utilization	사용할 GPU 메모리 비율	0.9	0.90-0.95
--max-model-len	최대 시퀀스 길이	모델 기본값	사용 사례에 맞춰 설정
--max-num-seqs	최대 동시 시퀀스 수	256	VRAM 상황에 맞춰 설정
--enable-prefix-caching	공통 프리픽스 캐싱	끔	켬 (프로덕션)
--disable-log-requests	로깅 오버헤드 감소	끔	켬 (프로덕션)
--api-key	API 키 인증 요구	없음	항상 설정 권장

프로덕션용 Docker Compose

# docker-compose.yml
version: "3.8"
services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 4
              capabilities: [gpu]
    ports:
      - "8000:8000"
    volumes:
      - huggingface-cache:/root/.cache/huggingface
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
    command: >
      --model meta-llama/Llama-3.3-70B-Instruct
      --tensor-parallel-size 4
      --port 8000
      --host 0.0.0.0
      --max-model-len 32768
      --enable-prefix-caching
      --gpu-memory-utilization 0.92
      --api-key ${VLLM_API_KEY}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./certs:/etc/nginx/certs
    depends_on:
      - vllm

volumes:
  huggingface-cache:

Prometheus를 활용한 모니터링

vLLM은 별도의 설정 없이 Prometheus 메트릭을 제공합니다.

# /metrics 엔드포인트에서 메트릭 확인 가능
curl http://localhost:8000/metrics

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

메트릭	설명
vllm:num_requests_running	활성 상태인 요청 수
vllm:num_requests_waiting	대기 중인 요청 수
vllm:avg_generation_throughput_toks_per_s	초당 생성 토큰 수
vllm:avg_prompt_throughput_toks_per_s	프롬프트 처리 속도
vllm:gpu_cache_usage_perc	KV 캐시 점유율

5단계: 인기 모델 서빙하기

Qwen 2.5 Coder (코딩 최적화)

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --tensor-parallel-size 2 \
  --port 8000

DeepSeek V3 (최고 수준의 오픈 소스 범용 모델)

python -m vllm.entrypoints.openai.api_server \
  --model deepseek-ai/DeepSeek-V3 \
  --tensor-parallel-size 8 \
  --trust-remote-code \
  --port 8000

Mistral Large (강력한 유럽 기반 모델)

python -m vllm.entrypoints.openai.api_server \
  --model mistralai/Mistral-Large-Instruct-2411 \
  --tensor-parallel-size 4 \
  --port 8000

배포 벤치마킹

vLLM에는 벤치마킹 도구가 포함되어 있습니다.

# 처리량(throughput) 벤치마크
python -m vllm.entrypoints.openai.bench_serving \
  --backend vllm \
  --base-url http://localhost:8000 \
  --model meta-llama/Llama-3.3-70B-Instruct \
  --num-prompts 100 \
  --request-rate 10

예상 처리량 (Llama 3.3 70B, 4x A100 80GB 기준)

동시 사용자 수	토큰/초	지연 시간 (p50)	지연 시간 (p99)
1	85 tok/s	12ms/tok	18ms/tok
10	620 tok/s	16ms/tok	35ms/tok
50	2,100 tok/s	24ms/tok	65ms/tok
100	3,200 tok/s	31ms/tok	120ms/tok

자주 묻는 질문 (FAQ)

vLLM은 어떤 GPU를 지원하나요? 연산 능력(compute capability) 7.0 이상의 NVIDIA GPU(V100, T4, A10, A100, H100, L40S, RTX 3090/4090 등). ROCm 6.0 이상인 AMD GPU (MI210, MI250, MI300X). JAX 백엔드를 통한 Google TPU 등을 지원합니다.

하나의 GPU에서 여러 모델을 서빙할 수 있나요? 단일 vLLM 인스턴스에서는 직접적으로 불가능합니다. 서로 다른 포트에서 여러 vLLM 인스턴스를 실행하여 각각 다른 모델을 서빙하고, 로드 밸런서를 사용해 요청을 라우팅할 수 있습니다.

개인용으로 사용할 때 Ollama와 비교하면 어떤가요? Ollama는 설정이 더 쉽고 단일 사용자 중심의 로컬 추론에 매우 적합합니다. vLLM은 높은 처리량이 필요한 다중 사용자 서빙을 위해 설계되었습니다. 개인적인 용도라면 Ollama를, 팀 프로젝트나 프로덕션 환경이라면 vLLM을 권장합니다.

vLLM은 스트리밍을 지원하나요? 네. API 요청 시 "stream": true를 사용하면 실시간 토큰 스트리밍 응답을 받을 수 있습니다.

모델을 파인튜닝한 뒤 vLLM으로 서빙할 수 있나요? 네. HuggingFace, Axolotl 등 모든 프레임워크로 학습한 뒤, 저장된 모델 디렉토리나 LoRA 어댑터를 vLLM에 연결하면 됩니다.

마치며

vLLM은 2026년 기준 자체 호스팅 LLM 서빙의 표준(Gold standard)입니다. PagedAttention 아키텍처, 텐서 병렬화, 투기적 디코딩을 통해 프로덕션 배포에서 타의 추종을 불허하는 처리량을 제공합니다. 간단한 단일 GPU 설정으로 시작하여 워크로드를 벤치마킹한 후, 필요에 따라 다중 GPU 구성으로 확장해 보세요.

LLM 텍스트 생성과 AI 생성 미디어를 결합한 애플리케이션을 준비 중이라면, Hypereal AI에서 비디오 생성, AI 아바타, 이미지 합성 등을 위한 프로덕션급 API를 제공합니다. 자체 호스팅된 vLLM 인스턴스와 Hypereal의 미디어 API를 결합하여 완벽한 AI 스택을 구축해 보세요. 35개의 무료 크레딧과 함께 시작할 수 있습니다.