vllm-serving
OpenAI 호환 API 기반 고성능 LLM 서빙 환경입니다.
문서 기준
- 기준일:
2026-02-23
- Python:
3.12
- 운영체제: macOS, Ubuntu, Windows
- 동기화 명령:
uv sync
호환성 메모
| 환경 | PyTorch | vLLM | 설명 |
|---|
| Ubuntu x86_64 | 2.9.1 | 0.15.1 | vLLM 런타임 포함 전체 구성 (GPU 서빙 가능) |
| macOS / Windows | 2.10.0 | — | 클라이언트/공통 라이브러리 중심 (vllm, flashinfer-python 제외) |
vLLM 0.15.1은 PyTorch 2.10을 아직 지원하지 않습니다. Ubuntu x86_64에서는 PyTorch 2.9.1로 고정하고, macOS/Windows에서는 클라이언트 개발 용도로 최신 PyTorch를 사용합니다.
pyproject.toml
[project]
name = "vllm-serving"
version = "0.1.0"
description = "vLLM serving environment"
requires-python = "==3.12.*"
dependencies = [
"torch==2.9.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
"torchvision==0.24.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
"torchaudio==2.9.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
"torch==2.10.0; platform_system != 'Linux' or platform_machine != 'x86_64'",
"torchvision==0.25.0; platform_system != 'Linux' or platform_machine != 'x86_64'",
"torchaudio==2.10.0; platform_system != 'Linux' or platform_machine != 'x86_64'",
"vllm==0.15.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
"flashinfer-python==0.6.1; platform_system == 'Linux' and platform_machine == 'x86_64'",
"xgrammar==0.1.29",
"transformers==4.57.6",
"openai==2.21.0",
"ray==2.54.0",
"ipykernel==7.2.0",
"pytest==9.0.2",
"ruff==0.15.2",
]
[tool.uv]
package = false
프로젝트 생성
uv init vllm-serving
cd vllm-serving
Jupyter 커널 등록
uv run python -m ipykernel install --user --name vllm-serving --display-name "UV vllm-serving"
설치 확인
모든 OS 공통 확인:
uv run python -c "import torch, transformers, openai, xgrammar; print('torch', torch.__version__); print('transformers', transformers.__version__); print('xgrammar', xgrammar.__version__)"
uv run python -c "import vllm; print('vllm', vllm.__version__)"
서빙 시작 (Ubuntu x86_64)
기본 서빙
uv run python -m vllm.entrypoints.openai.api_server \
--model meta-llama/Llama-3.1-8B-Instruct \
--host 0.0.0.0 \
--port 8000 \
--max-model-len 4096
주요 서빙 옵션
| 옵션 | 설명 | 기본값 |
|---|
--model | HuggingFace 모델 ID 또는 로컬 경로 | (필수) |
--tensor-parallel-size | GPU 병렬 수 | 1 |
--max-model-len | 최대 시퀀스 길이 | 모델 기본값 |
--gpu-memory-utilization | GPU 메모리 사용 비율 | 0.9 |
--dtype | 연산 정밀도 (auto, half, bfloat16) | auto |
--quantization | 양자화 방식 (awq, gptq, squeezellm) | None |
클라이언트 호출 예시
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="token-not-needed" # vLLM 자체 서빙 시 인증 불필요
)
response = client.chat.completions.create(
model="meta-llama/Llama-3.1-8B-Instruct",
messages=[{"role": "user", "content": "한국의 수도는?"}],
max_tokens=256
)
print(response.choices[0].message.content)
트러블슈팅
| 증상 | 원인 | 해결 |
|---|
vllm import 실패 | Linux x86_64 + CUDA 환경이 아님 | uname -m, nvidia-smi 확인 |
uv sync 의존성 충돌 | 기존 락 파일과 버전 불일치 | uv lock --refresh 사용 |
| CUDA OOM | max-model-len이 VRAM 초과 | --max-model-len 줄이거나 --quantization awq 적용 |
| 느린 첫 응답 | 모델 로딩 + KV 캐시 초기화 | 정상 동작, warm-up 요청으로 대응 |
ray 관련 오류 | 멀티 GPU 설정 불일치 | --tensor-parallel-size와 실제 GPU 수 일치 확인 |
