빠른 시작 (Quickstart)

출처: vLLM 공식 문서 — Quickstart

이 가이드는 vLLM을 빠르게 시작할 수 있도록 도와줘요. 여기서 두 가지를 직접 해볼 거예요.

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

사전 요구사항 (Prerequisites)

OS: Linux
Python: 3.10 -- 3.13

설치 (Installation)

NVIDIA GPU를 쓰고 있다면 pip로 vLLM을 바로 설치할 수 있어요.

Python 환경을 만들고 관리할 때는 아주 빠른 환경 관리자인 uv를 쓰는 걸 추천해요. 문서를 따라 uv를 설치한 뒤, 아래 명령으로 새 Python 환경을 만들고 vLLM을 설치하면 돼요.

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

uv는 설치된 CUDA 드라이버 버전을 검사해서 --torch-backend=auto(혹은 UV_TORCH_BACKEND=auto)로 실행 시점에 적절한 PyTorch 인덱스를 자동으로 골라줘요. 특정 백엔드(예: cu126)를 고르고 싶으면 --torch-backend=cu126(혹은 UV_TORCH_BACKEND=cu126)로 지정하면 돼요.

또 하나 편리한 방법으로 uv run을 --with [dependency] 옵션과 함께 쓰면, 영구적인 환경을 만들지 않고도 vllm serve 같은 명령을 바로 실행할 수 있어요.

 uv run --with vllm vllm --help

conda로 환경을 만들고 관리할 수도 있어요. 환경 안에서 관리하고 싶다면 pip로 uv를 conda 환경에 설치할 수 있답니다.

 conda create -n myenv python=3.12 -y
 conda activate myenv
 pip install --upgrade uv
 uv pip install vllm --torch-backend=auto

AMD GPU를 쓴다면 uv로 vLLM을 설치할 수 있어요.

uv를 추천하는 이유는, 기본 인덱스보다 추가 인덱스(extra index)에 더 높은 우선순위를 주기 때문이에요. uv는 환경 관리도 굉장히 빠르게 해줘요. 문서를 따라 uv를 설치한 뒤, 아래 명령으로 새 Python 환경을 만들고 vLLM을 설치하면 돼요.

 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을 지원해요.

참고 — 예전에는 docker 이미지가 AMD의 docker 릴리스 파이프라인으로 배포되어 rocm/vllm-dev에 있었는데요, 이제 vLLM의 docker 릴리스 파이프라인을 쓰는 방향으로 바뀌면서 이 방식은 지원이 중단되고 있어요.

Google TPU에서 vLLM을 돌리려면 vllm-tpu 패키지를 설치해야 해요.

 uv pip install vllm-tpu

참고 — Docker 사용법, 소스에서 설치하는 방법, 트러블슈팅까지 더 자세한 내용은 vLLM on TPU 문서를 참고해 주세요.

Apple Silicon Mac을 쓴다면 Apple의 Metal 프레임워크로 GPU 가속 추론을 제공하는 vLLM-Metal을 쓸 수 있어요.

vLLM-Metal 문서의 설치 안내를 따라가면 돼요.

참고 — vLLM-Metal은 컴퓨트 백엔드로 PyTorch 대신 MLX를 쓰고, Hugging Face의 mlx-community에서 MLX에 최적화된 모델이 필요해요.

팁 — 더 자세한 안내는 GPU 설치 가이드에서 "Apple Silicon" 탭을 선택해서 확인해 주세요.

참고 — 더 자세한 내용과 non-CUDA 플랫폼별 설치는 설치 가이드에서 각 플랫폼에 맞는 방법을 확인할 수 있어요.

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

vLLM을 설치했으니 이제 입력 프롬프트 목록으로 텍스트를 생성할 수 있어요. 이것이 바로 오프라인 배치 추론(offline batched inference)이에요. 예제 스크립트는 examples/basic/offline_inference/basic.py에서 볼 수 있어요.

이 예제의 첫 줄은 LLM과 SamplingParams 클래스를 불러와요.

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

 from vllm import LLM, SamplingParams

다음 절에서는 텍스트 생성을 위한 입력 프롬프트 목록과 샘플링 파라미터를 정의해요. 샘플링 온도는 0.8로, nucleus sampling 확률은 0.95로 설정했어요. 샘플링 파라미터에 대한 자세한 내용은 여기에서 확인할 수 있어요.

중요 — 기본적으로 vLLM은 Hugging Face 모델 저장소의 generation_config.json이 있으면 모델 제작자가 권장하는 샘플링 파라미터를 적용해요. 대부분의 경우 SamplingParams를 지정하지 않아도 기본값으로 가장 좋은 결과를 얻을 수 있어요. vLLM 고유의 기본 샘플링 파라미터를 쓰고 싶다면 LLM 인스턴스를 만들 때 generation_config="vllm"로 설정하면 돼요.

 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)

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 엔진의 대기 큐(waiting queue)에 넣고 엔진을 실행해서 높은 처리량으로 출력을 만들어요. 결과는 모든 출력 토큰을 담은 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 메서드는 입력 프롬프트에 모델의 채팅 템플릿을 자동으로 적용하지 않아요. 그래서 Instruct 모델이나 Chat 모델을 쓸 때는 기대한 동작을 위해 채팅 템플릿을 직접 적용해야 해요. 아니면 llm.chat 메서드를 쓰고 OpenAI의 client.chat.completions에 전달하는 것과 같은 형식의 메시지 리스트를 넘겨도 돼요.

# 토크나이저로 채팅 템플릿 적용하기
from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("/path/to/chat_model")
messages_list = [[{"role": "user", "content": prompt}] for prompt in prompts]
texts = tokenizer.apply_chat_template(
    messages_list,
    tokenize=False,
    add_generation_prompt=True,
)

# 출력 생성
outputs = llm.generate(texts, 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}")


# 채팅 인터페이스 사용하기
outputs = llm.chat(messages_list, sampling_params)
for idx, output in enumerate(outputs):
    prompt = prompts[idx]
    generated_text = output.outputs[0].text
    print(f"Prompt: {prompt!r}, Generated text: {generated_text!r}")

온라인 서빙 (Online Serving)

vLLM은 OpenAI API 프로토콜을 구현하는 서버로 배포할 수 있어요. 그래서 vLLM을 OpenAI API를 쓰는 애플리케이션의 드롭인(drop-in) 대체품으로 쓸 수 있죠. 기본적으로 서버는 http://localhost:8000에서 시작돼요. 주소는 --host와 --port 인자로 지정할 수 있어요. 이 서버는 한 번에 하나의 모델을 호스팅하며, 모델 목록 조회(list models), create chat completion, create completion 같은 엔드포인트를 구현해요.

다음 명령으로 Qwen2.5-1.5B-Instruct 모델을 띄운 vLLM 서버를 시작해 볼게요.

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

참고 — 기본적으로 서버는 토크나이저에 저장된 미리 정의된 채팅 템플릿을 사용해요. 이를 덮어쓰는 방법은 여기에서 확인할 수 있어요.

중요 — 기본적으로 서버는 huggingface 모델 저장소에 generation_config.json이 있으면 그것을 적용해요. 즉 특정 샘플링 파라미터의 기본값이 모델 제작자가 권장하는 값으로 덮어써질 수 있어요. 이 동작을 끄려면 서버를 실행할 때 --generation-config vllm을 넘겨주세요.

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

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

--api-key 인자나 환경 변수 VLLM_API_KEY로 헤더의 API 키를 검사하도록 서버를 설정할 수 있어요. --api-key 뒤에 여러 키를 넘기면 서버는 넘겨진 키 중 아무거나 받아들여요. 키 순환(rotation)을 할 때 유용하죠.

vLLM으로 OpenAI Completions API 사용하기 (OpenAI Completions API with vLLM)

서버가 시작되면 입력 프롬프트로 모델을 조회할 수 있어요.

 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 API와 호환되기 때문에 OpenAI API를 쓰는 애플리케이션의 드롭인 대체품으로 쓸 수 있어요. 예를 들어 openai Python 패키지로도 서버를 조회할 수 있답니다.

from openai import OpenAI

# OpenAI의 API key와 API base를 vLLM의 API 서버로 바꿔서 써요.
openai_api_key = "EMPTY"
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

completion = client.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    prompt="San Francisco is a",
)

print("Completion result:", completion)

더 자세한 클라이언트 예제는 examples/basic/offline_inference/basic.py에서 찾을 수 있어요.

vLLM으로 OpenAI Chat Completions API 사용하기 (OpenAI Chat Completions API with vLLM)

vLLM은 OpenAI Chat Completions API도 지원하도록 설계됐어요. 채팅 인터페이스는 모델과 더 역동적이고 대화식으로 소통하는 방식이라, 채팅 기록에 저장할 수 있는 주고받는 교환(back-and-forth exchanges)이 가능해요. 대화 맥락이나 더 자세한 설명이 필요한 작업에 유용하죠.

모델과 상호작용하려면 create chat completion 엔드포인트를 쓸 수 있어요.

 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 패키지를 쓸 수도 있어요.

from openai import OpenAI

# OpenAI의 API key와 API base를 vLLM의 API 서버로 설정해요.
openai_api_key = "EMPTY"
openai_api_base = "http://localhost:8000/v1"

client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)

chat_response = client.chat.completions.create(
    model="Qwen/Qwen2.5-1.5B-Instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Tell me a joke."},
    ],
)

print("Chat response:", chat_response)

Attention 백엔드에 관해 (On Attention Backends)

현재 vLLM은 서로 다른 플랫폼과 가속기 아키텍처에서 효율적인 Attention 연산을 계산하기 위해 여러 백엔드를 지원해요. 시스템과 모델 사양에 호환되는 가장 성능 좋은 백엔드를 자동으로 선택해요.

원한다면 --attention-backend CLI 인자로 원하는 백엔드를 직접 설정할 수도 있어요.

# 온라인 서빙용
vllm serve Qwen/Qwen2.5-1.5B-Instruct --attention-backend FLASH_ATTN

# 오프라인 추론용
python script.py --attention-backend FLASHINFER

사용할 수 있는 백엔드 옵션 중 일부는 다음과 같아요.

NVIDIA CUDA에서: FLASH_ATTN 또는 FLASHINFER
AMD ROCm에서: TRITON_ATTN, ROCM_ATTN, ROCM_AITER_FA, ROCM_AITER_UNIFIED_ATTN, TRITON_MLA, ROCM_AITER_MLA 또는 ROCM_AITER_TRITON_MLA

경고 — Flash Infer를 포함한 미리 빌드된 vllm wheel은 없어서, 먼저 환경에 직접 설치해야 해요. 설치 방법은 Flash Infer 공식 문서나 docker/Dockerfile을 참고하세요.