vLLM 핵심 실무 가이드

1. vLLM란?

vLLM은 LLM(Large Language Model) 추론 서빙을 위한 고성능 라이브러리입니다. PagedAttention 알고리즘을 통해 메모리 효율성을 극대화하고, 수천 개의 동시 요청을 처리할 수 있는 처리량(throughput)을 제공합니다.

2. 왜 써야 하는가?

기존 LLM 서빙 솔루션 대비 vLLM의 장점을 비교합니다.

3. 핵심 개념

아키텍처 개요

주요 컴포넌트 설명

• LLM Engine: 추론 요청의 생명주기를 관리하는 핵심 컴포넌트.
• PagedAttention: KV 캐시를 고정 크기 블록으로 관리, 가상 메모리 시스템과 유사.
• Block Manager: GPU 메모리의 블록 할당/해제를 담당.
• Scheduler: 들어오는 요청을 배치로 구성하고 실행 순서를 결정.

4. 퀵스타트

4.1 설치

# CUDA 12.1 기준 (가상환경 권장)
pip install vllm

# 특정 버전 설치
pip install vllm==0.6.0

# 추가 기능 포함 (AWQ, GPTQ 등)
pip install vllm[all]

4.2 기본 서버 실행

# CLI로 서버 실행 (Meta-Llama-3-8B-Instruct 예시)
vllm serve meta-llama/Meta-Llama-3-8B-Instruct \
    --port 8000 \
    --max-model-len 8192 \
    --tensor-parallel-size 1 \
    --gpu-memory-utilization 0.9

4.3 Python에서 직접 사용

from vllm import LLM, SamplingParams

# 모델 로드
llm = LLM(model="meta-llama/Meta-Llama-3-8B-Instruct",
          max_model_len=8192,
          gpu_memory_utilization=0.9)

# 샘플링 파라미터 설정
sampling_params = SamplingParams(temperature=0.7,
                                 top_p=0.95,
                                 max_tokens=512)

# 추론 실행
prompts = [
    "대한민국의 수도는?",
    "파이썬에서 리스트를 정렬하는 방법은?"
]
outputs = llm.generate(prompts, sampling_params)

# 결과 출력
for output in outputs:
    print(f"Prompt: {output.prompt}")
    print(f"Generated: {output.outputs[0].text}\n")

4.4 OpenAI 호환 API 사용

import openai

# vLLM 서버를 OpenAI 클라이언트로 연결
client = openai.OpenAI(
    api_key="token-abc123",  # 임의 값
    base_url="http://localhost:8000/v1"
)

# 채팅 완성 요청
response = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    messages=[
        {"role": "user", "content": "안녕! 너의 이름은 뭐야?"}
    ],
    temperature=0.7,
    max_tokens=100
)

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

5. 핵심 설정 레퍼런스

6. 실무 팁 & 트러블슈팅

모니터링 명령어

# GPU 메모리 사용량 확인
nvidia-smi --query-gpu=memory.used,memory.total --format=csv

# vLLM 서버 메트릭 (활성화 시)
curl http://localhost:8000/metrics

# 로그 확인 (상세 로깅 활성화)
vllm serve ... --log-level debug

7. 참고 자료

• 📚 공식 문서 (vLLM Documentation) - 가장 최신 정보
• 🐙 GitHub 저장소 - 이슈 및 소스 코드
• 📄 PagedAttention 논문 - 핵심 알고리즘 설명
• ⚖️ 양자화 가이드 - 모델 경량화
• 💡 예제 코드 - 고급 사용법