Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 01. 15:44

vLLM 설정 가이드 2026: OpenAI API를 통해 모든 LLM 서빙하기

요약

vLLM을 사용하여 Hugging Face 모델을 OpenAI 호환 API로 서빙하는 방법을 설명하는 가이드입니다. PagedAttention과 연속 배칭 기술을 활용하여 효율적인 LLM 추론 환경을 구축하는 절차를 다룹니다.

핵심 포인트

  • vLLM은 OpenAI API와 호환되는 로컬 엔드포인트를 제공함
  • PagedAttention 및 멀티 GPU 텐서 병렬성 지원
  • 성능의 핵심 병목 지점은 설정이 아닌 VRAM 용량임
  • Linux 환경 및 NVIDIA GPU(CUDA 12.4 이상) 권장

이 기사는 원래 aifoss.dev에 게시되었습니다.

요약 (TL;DR): 이 가이드를 마치면 여러분은 로컬 OpenAI 호환 API 엔드포인트를 통해 모든 Hugging Face 모델을 서빙할 수 있게 됩니다. vLLM v0.21.0은 적절한 플래그(flags)만 설정해주면 PagedAttention, 연속 배칭 (continuous batching), 멀티 GPU 텐서 병렬성 (multi-GPU tensor parallelism)과 같은 복잡한 작업을 처리합니다. 병목 현상은 설정의 복잡성이 아니라 VRAM입니다.

이 가이드를 마친 후 실행 중인 상태:

  • 표준 OpenAI API 요청을 수락하는 http://localhost:8000/v1 상의 vLLM 서버
  • 모든 OpenAI Python 클라이언트, LangChain 앱 또는 채팅 프런트엔드를 연결할 수 있는 검증된 엔드포인트
  • 선택 사항: 팀 사용을 위한 API 키 인증이 포함된 Docker 기반 배포

솔직한 견해: pip install vllm은 정말로 그만큼 간단합니다. 결정해야 할 지점은 하드웨어에 맞는 어떤 GPU 플래그를 설정할 것인지, 그리고 베어메탈 (bare-metal)로 갈 것인지 Docker를 사용할 것인지입니다. 두 가지 경로 모두 아래에 설명되어 있습니다.

vLLM은 Apache 2.0 라이선스 하에 오픈 소스로 제공되므로, 상업적 또는 내부 배포에 사용 제한이 없습니다.

사전 요구 사항

시작하기 전에, vLLM이 실제로 서빙할 수 있는 사양과 여러분의 하드웨어를 비교해 보세요:

설정GPU VRAM시스템 RAM원활하게 실행되는 모델
입문 단계16 GB (RTX 3090)32 GBLlama 3.2 3B (FP16), Mistral 7B
...

GPU VRAM이 16 GB 미만인 경우, 더 작은 모델이나 양자화된 변체 (quantized variants)로 제한될 것입니다. 이는 괜찮습니다. --dtype float16과 --max-model-len을 보수적으로 설정하기만 하면 됩니다 (4단계에서 다룹니다).

소프트웨어 요구 사항:

  • Linux — Ubuntu 22.04 또는 24.04 권장. macOS 및 Windows는 vLLM에서 지원되지 않습니다.
  • Python 3.10–3.14 (Python 3.12가 가장 적합하며, 테스트되었고 지원이 잘 됩니다)
  • CUDA 12.4 및 드라이버 550 이상이 설치된 NVIDIA GPU. 확인 방법: nvidia-smi
  • 모델 가중치를 위한 최소 50 GB의 여유 디스크 공간

Linux를 사용하지 않나요? 대신 Ollama를 사용하세요. Ollama는 macOS와 Windows를 네이티브로 지원하며, API 호환성이 거의 동일합니다. 전체 비교 내용은 Ollama vs vLLM 2026을 참조하세요.

1단계: vLLM 설치

새로운 Python 가상 환경 (virtual environment)을 사용하세요. vLLM은 설치 시 CUDA 커널 (CUDA kernels)을 컴파일하며, 이 커널들은 특정 PyTorch 및 CUDA 버전과 결합되어 있습니다. 기존 환경에 vLLM을 혼합하면 디버깅하기 어려운 버전 충돌이 발생할 수 있습니다.

python3 -m venv ~/.venvs/vllm
source ~/.venvs/vllm/bin/activate

...

Wheel 파일에는 PyTorch 2.11과 사전 컴파일된 CUDA 커널이 포함되어 있습니다. 새로운 환경에서는 설치에 5~10분 정도 소요될 것으로 예상됩니다. 대부분의 시간은 컴파일이 아닌 다운로드에 사용됩니다.

설치를 확인합니다:

python -c "import vllm; print(vllm.__version__)"
# 0.21.0

환경 관리를 위해 conda를 사용하고 싶다면:

conda create -n vllm-env python=3.12 -y
conda activate vllm-env
pip install vllm   # 여전히 conda install이 아닌 pip를 사용하세요

격리를 위해 conda 환경을 사용하는 것은 괜찮습니다. 다만 패키지 자체는 반드시 pip를 통해 설치해야 합니다. conda-forge 빌드는 업데이트가 늦고, 멀티 GPU (multi-GPU) 설정에서 NCCL 충돌이 발생하는 경우가 많기 때문입니다.

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

vllm serve 명령은 HTTP 서버를 시작합니다. 어떤 Hugging Face 모델 ID라도 전달하면 됩니다:

vllm serve meta-llama/Llama-3.2-3B-Instruct

처음 실행할 때 모델은 ~/.cache/huggingface/hub/로 다운로드됩니다. 이후 실행 시에는 캐시 (cache)에서 로드되므로 매우 빠릅니다.

서버는 기본적으로 http://localhost:8000/v1에 바인딩되며, 이는 OpenAI API 기본 URL (base URL)과 일치합니다. 준비가 완료되면 다음과 같은 시작 출력이 나타납니다:

INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

게이트 모델 (gated models) (Llama 3.1, Llama 3.3 및 유사한 Meta 모델)의 경우, Hugging Face 액세스 토큰 (access token)이 필요합니다. huggingface.co/settings/tokens에서 토큰을 발급받고, 모델 페이지에서 모델 이용 약관에 동의한 후 다음을 수행하세요:

export HF_TOKEN=hf_your_token_here
vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct

Step 3: 엔드포인트 테스트

/v1/chat/completions 엔드포인트는 OpenAI와 호환됩니다. 애플리케이션 코드를 건드리기 전에 curl로 먼저 테스트하세요:

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
...

model 필드는 HuggingFace 전체 경로를 포함하여 vllm serve에 전달한 값과 정확히 일치해야 합니다. 서버가 로드된 모델로 인식하는 것을 확인하세요:

curl http://localhost:8000/v1/models

OpenAI Python 클라이언트를 사용하는 경우:

from openai import OpenAI

client = OpenAI(
...

스트리밍 (Streaming)은 OpenAI SDK와 동일하게 작동합니다. stream=True를 전달하고 response를 반복(iterate)하면 됩니다. vLLM은 /v1/completions (레거시 텍스트 완성) 및 /v1/embeddings 엔드포인트도 지원합니다.

Step 4: 주요 설정 플래그 (Key configuration flags)

기본 설정은 대부분의 단일 사용자 환경에서 즉시 작동합니다. 하지만 한계에 도달하거나 실제 트래픽을 처리할 때는 다음 플래그들이 중요해집니다.

GPU 메모리 사용률 (GPU memory utilization)

vllm serve meta-llama/Meta-Llama-3.1-8B-Instruct \
  --gpu-memory-utilization 0.90

기본값은 0.90 (vLLM을 위해 예약된 VRAM의 90%)입니다. 모델이 간신히 들어가는 경우 0.95로 높이세요. 다른 프로세스가 GPU를 공유하는 경우 0.80으로 낮추세요. 남은 여유 공간(headroom)은 CUDA 컨텍스트 오버헤드로 인한 OOM (Out of Memory) 에러를 방지합니다.

데이터 타입 (Data type)

vllm serve ... --dtype float16

auto (기본값)는 Ampere+ GPU에서 bfloat16을 선택합니다. 만약 RuntimeError: No GPU memory available이 발생하면 float16으로 전환하세요. 이는 품질 저하를 최소화하면서 bfloat16 대비 메모리 사용량을 약 5% 줄여줍니다. float32는 거의 사용되지 않으며, VRAM 사용량을 두 배로 늘립니다.

컨텍스트 윈도우 제한 (Context window cap)

vllm serve ... --max-model-len 8192

vLLM은 모델의 최대 컨텍스트 길이(최신 모델의 경우 종종 128k)를 기본값으로 사용합니다. 이 최대 컨텍스트 길이는 단 2k 토큰만 사용하는 요청에 대해서도 vLLM이 사전 할당하는 KV 캐시 (KV cache) VRAM 양을 결정합니다. --max-model-len 8192를 설정하면 상당한 양의 VRAM을 확보할 수 있으며, 서버가 처리할 수 있는 동시 요청 (concurrent requests) 수를 늘릴 수 있습니다. 모델의 이론적 최대치가 아닌, 실제 사용 사례에서 필요한 가장 긴 컨텍스트를 사용하세요.

호스트 및 포트 (Host and port)

vllm serve ... --host 0.0.0.0 --port 8080

--host 0.0.0.0은 모든 네트워크 인터페이스에서 서버를 노출하며, 이는 Docker 컨테이너 및 원격 팀 액세스에 필수적입니다. 기본값인 127.0.0.1은 로컬호스트(localhost)에서만 접근 가능합니다.

API 키 인증 (API key authentication)

vllm serve ... --api-key your-secret-key-here

설정되면 모든 요청에는 다음 내용이 포함되어야 합니다:

Authorization: Bearer your-secret-key-here

OpenAI() 생성자에 api_key="your-secret-key-here"를 전달하면 OpenAI Python 클라이언트가 이를 자동으로 처리합니다.

단계 5: 멀티 GPU 텐서 병렬화 (Multi-GPU tensor parallelism)

단일 GPU의 VRAM보다 큰 모델의 경우, vLLM은 텐서 병렬화 (tensor parallelism)를 통해 모델을 여러 GPU에 분산합니다. --tensor-parallel-size 값은 모델의 어텐션 헤드 (attention head) 개수의 약수로 나누어져야 하며, 대부분의 모델에서는 2, 4, 또는 8개의 GPU가 적합합니다.

vllm serve meta-llama/Meta-Llama-3.1-70B-Instruct \
  --tensor-parallel-size 2 \
  --dtype bfloat16 \
...

두 개의 RTX 4090(결합 VRAM 48GB)을 사용하면 이 컨텍스트 길이에서 bfloat16 형식으로 Llama 3.1 70B를 서빙할 수 있습니다. 먼저 GPU 가시성을 확인하세요:

nvidia-smi

멀티 GPU 컨테이너는 NCCL 통신을 위해 추가적인 공유 메모리 (shared memory)가 필요하며, 이는 아래의 Docker 단계에서 처리됩니다. 베어메탈 (bare-metal) 환경에서 실행하는 경우 vLLM이 이를 자동으로 관리합니다.

단계 6: Docker 배포 (Docker deployment)

재현 가능한

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0