빠른 시작

빠른 시작 (Quickstart)

이 가이드는 vLLM을 빠르게 시작할 수 있도록 도와드릴게요. vLLM으로 할 수 있는 두 가지 핵심 사용법을 중심으로 설명합니다.

  • 오프라인 배치 추론 (Offline batched inference)
  • 온라인 서빙 (Online serving)

출처: vLLM 공식 문서 — getting_started-quickstart

사전 요구사항 (Prerequisites)

  • OS: Linux
  • Python: 3.10 -- 3.13

설치 (Installation)

NVIDIA GPU

빠른 Python 환경 관리자 uv 사용을 권장해요.

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto

uv는 설치된 CUDA 드라이버 버전을 검사해 --torch-backend=auto로 적절한 PyTorch 인덱스를 자동 선택해요. 특정 백엔드(예: cu126)를 고르려면 --torch-backend=cu126으로 설정하면 됩니다.

또한 uv run --with vllm처럼 임시 환경으로 바로 실행할 수도 있어요.

uv run --with vllm vllm --help

AMD GPU

uv 사용을 권장합니다. uv는 extra 인덱스에 기본 인덱스보다 높은 우선순위를 주기 때문이에요.

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --extra-index-url https://wheels.vllm.ai/rocm/

참고: 현재 Python 3.12, ROCm 7.0, glibc >= 2.35를 지원해요.

기타 하드웨어

오프라인 배치 추론 (Offline Batched Inference)

vLLM을 설치했다면, 입력 프롬프트 목록에 대해 텍스트를 생성하는 오프라인 배치 추론을 시작할 수 있어요. 예제 스크립트: examples/basic/offline_inference/basic.py

첫 번째 줄은 LLM과 SamplingParams 클래스를 임포트해요.

  • LLM은 vLLM 엔진으로 오프라인 추론을 실행하는 메인 클래스예요.
  • SamplingParams는 샘플링 과정의 파라미터를 지정해요.
from vllm import LLM, SamplingParams

다음 섹션에서는 입력 프롬프트 목록과 텍스트 생성용 sampling 파라미터를 정의해요. 샘플링 온도는 0.8, nucleus sampling 확률은 0.95로 설정되어 있죠.

prompts = ["Hello, my name is", "The president of the United States is", "The capital of France is", "The future of AI is"]
sampling_params = SamplingParams(temperature=0.8, top_p=0.95)

중요: 기본적으로 vLLM은 Hugging Face 모델 저장소에 generation_config.json이 있으면 이를 적용해 모델 제작자가 권장하는 sampling 파라미터를 사용해요. 대부분의 경우 SamplingParams를 지정하지 않으면 기본적으로 최상의 결과를 얻어요. vLLM의 기본 sampling 파라미터를 선호한다면 LLM 인스턴스를 만들 때 generation_config="vllm"을 설정하세요.

LLM 클래스는 vLLM의 엔진과 OPT-125M 모델을 오프라인 추론용으로 초기화해요.

llm = LLM(model="facebook/opt-125m")

참고: 기본적으로 vLLM은 Hugging Face에서 모델을 다운로드해요. ModelScope에서 모델을 쓰려면 엔진 초기화 전에 VLLM_USE_MODELSCOPE 환경 변수를 설정하세요.

export VLLM_USE_MODELSCOPE=True

이제 재미있는 부분이에요. llm.generate로 출력을 생성합니다. 입력 프롬프트를 vLLM 엔진의 대기 큐에 추가하고, 높은 처리량으로 출력을 생성하도록 엔진을 실행해요. 출력은 RequestOutput 객체 목록으로 반환됩니다.

outputs = llm.generate(prompts, sampling_params)
for output in outputs:
    prompt = output.prompt
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

참고: llm.generate 메서드는 입력 프롬프트에 모델의 chat template을 자동 적용하지 않아요. Instruct 모델이나 Chat 모델을 쓴다면 chat template을 직접 적용해야 해요. 또는 llm.chat 메서드를 쓰고 OpenAI의 client.chat.completions와 같은 형식의 메시지 목록을 전달할 수도 있어요. 전체 예제는 basic.py를 참고하세요.

온라인 서빙 (Online Serving)

vLLM은 OpenAI API 프로토콜을 구현하는 서버로 배포할 수 있어요. 기본적으로 http://localhost:8000에서 서버를 시작해요. --host와 --port 인자로 주소를 지정할 수 있어요. 서버는 한 번에 하나의 모델을 호스팅하며, list models, create chat completion, create completion 엔드포인트를 구현합니다.

vllm serve Qwen/Qwen2.5-1.5B-Instruct

이 서버는 OpenAI API와 같은 형식으로 쿼리할 수 있어요. 예를 들어 모델 목록을 보려면:

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

--api-key 인자나 VLLM_API_KEY 환경 변수로 API 키 확인을 활성화할 수 있어요. --api-key 뒤에 여러 키를 전달할 수도 있고, 서버는 전달된 키 중 아무거나 받아들여요.

OpenAI Completions API

curl http://localhost:8000/v1/completions \
-H "Content-Type: application/json" \
-d '{"model": "Qwen/Qwen2.5-1.5B-Instruct", "prompt": "San Francisco is a", "max_tokens": 7, "temperature": 0}'

OpenAI Chat Completions API

curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model": "Qwen/Qwen2.5-1.5B-Instruct", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Who won the world series in 2020?"}]}'

openai Python 패키지로도 쿼리할 수 있어요. 자세한 클라이언트 예제는 예제 스크립트를 참고하세요.

어텐션 백엔드 (On Attention Backends)

vLLM은 다양한 플랫폼과 가속기 아키텍처에서 효율적인 어텐션 계산을 위한 여러 백엔드를 지원해요. 시스템과 모델 사양에 맞는 가장 성능 좋은 백엔드를 자동 선택합니다. 원하면 --attention-backend CLI 인자로 직접 선택할 수도 있어요.

사용 가능한 백엔드에는 예를 들어 다음이 있어요.

  • NVIDIA CUDA: FLASH_ATTN 또는 FLASHINFER
  • AMD ROCm: TRITON_ATTN, ROCM_ATTN 등
  • Intel XPU: FLASH_ATTN, TRITON_ATTN, TRITON_MLA 등

경고: Flash Infer를 포함한 사전 빌드 vllm wheel은 없으므로 환경에 직접 설치해야 해요. Flash Infer 공식 문서를 참고하세요.

더 알아보기 (Learn more)