빠른 시작 (Quickstart)

빠른 시작 (Quickstart)

이 가이드는 vLLM을 빠르게 시작할 수 있게 도와드릴게요. vLLM으로 할 수 있는 두 가지 핵심 작업, **오프라인 배치 추론(offline batched inference)**과 **온라인 서빙(online serving)**을 직접 해 보면서 감을 잡아 볼게요.

사전 준비

• OS: Linux
• Python: 3.10 ~ 3.13

참고: vLLM은 vLLM-Metal로 Apple Silicon(Mac)에서도 GPU 가속으로 동작해요. GPU 설치 가이드에서 "Apple Silicon" 탭을 확인하면 돼요.

설치

설치 방법은 사용하는 하드웨어에 따라 달라져요. 탭별로 하나씩 볼게요.

NVIDIA CUDA

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

Python 환경을 만들고 관리할 때는 엄청 빠른 uv를 쓰길 권해요. uv 설치는 공식 문서를 따라 하면 되고, 설치 후엔 아래 명령으로 새 환경을 만들고 vLLM을 설치해요.

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

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

또 하나 편한 방법은 uv run에 --with [dependency] 옵션을 쓰는 거예요. 영구 환경을 만들지 않고도 vllm serve 같은 명령을 실행할 수 있거든요.

uv run --with vllm vllm --help

conda를 쓰고 싶다면 conda 공식 문서를 참고해서 환경을 만들고, 그 안에 uv를 pip로 설치해 관리하면 돼요.

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

AMD ROCm

AMD GPU를 쓴다면 vLLM을 uv로 설치해요. uv가 별도 인덱스에 기본 인덱스보다 높은 우선순위를 주기 때문에, 여러 인덱스에 존재하는 패키지일 때 안전하게 설치할 수 있어요.

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

참고: 예전엔 AMD 도커 릴리스 파이프라인으로 이미지를 게시해 rocm/vllm-dev에 뒀었는데, 이제는 vLLM의 도커 릴리스 파이프라인을 쓰도록 바뀌고 있어요(기존 방식은 폐기 예정).

팁: 최신 개발 빌드를 테스트할 땐 vllm/vllm-openai-rocm:nightly 야간 도커 이미지를 쓸 수 있어요.

Intel GPU

vLLM은 XPU 백엔드로 Intel GPU를 지원해요. 사전 빌드된 XPU 휠은 곧 제공될 예정이고요. Intel GPU 공식 도커 이미지는 v0.26.0부터 vLLM 릴리스에 포함되며, 야간 이미지로 vllm/vllm-openai-xpu:nightly를 쓸 수 있어요.

팁: 소스 빌드나 도커 이미지 설정 포함한 더 자세한 방법은 GPU 설치 가이드에서 "Intel XPU" 탭을 확인해 주세요.

Google TPU

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

uv pip install vllm-tpu

참고: 도커, 소스 설치, 트러블슈팅을 포함한 자세한 방법은 vLLM on TPU 문서를 참고해 주세요.

Ascend NPU

Ascend NPU를 쓴다면 커뮤니티가 유지 보수하는 하드웨어 플러그인 vLLM Ascend를 통해 vLLM을 실행할 수 있어요.

설치는 vLLM Ascend 빠른 시작을 따라 하면 돼요.

참고: Ascend 설정은 사용하는 NPU 하드웨어와 CANN 버전에 따라 달라져요. 지원 버전, 도커 이미지, 트러블슈팅은 vLLM Ascend 문서를 참고해 주세요.

Apple Silicon (Mac)

Apple Silicon Mac을 쓴다면 Apple의 Metal 프레임워크를 통한 GPU 가속 추론을 위해 vLLM-Metal을 사용할 수 있어요.

설치는 vLLM-Metal 문서를 따라 하면 돼요.

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

팁: 더 자세한 방법은 GPU 설치 가이드에서 "Apple Silicon" 탭을 확인해 주세요.

참고: CUDA 외 플랫폼의 더 자세한 설치 방법은 설치 가이드에서 확인할 수 있어요.

오프라인 배치 추론

vLLM이 설치됐으면, 입력 프롬프트 목록에 대해 텍스트를 생성할 수 있어요. 이걸 오프라인 배치 추론(offline batched inference)이라고 해요. 예시 스크립트: examples/basic/offline_inference/basic.py

이 예시의 첫 줄은 클래스 LLM과 SamplingParams를 임포트해요.

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

from vllm import LLM, SamplingParams

다음 섹션은 텍스트 생성을 위한 입력 프롬프트 목록과 샘플링 파라미터를 정의해요. 샘플링 온도는 0.8, 뉴클리어스 샘플링 확률은 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 엔진의 대기 큐에 넣고 엔진을 실행해 높은 처리량으로 출력을 만들어요. 출력은 모든 출력 토큰을 담은 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에 넘기는 것과 같은 형식의 메시지 목록을 넘겨줄 수 있어요.

# Using tokenizer to apply chat template
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, )

Generate outputs

outputs = llm.generate(texts, sampling_params)

Print the outputs.

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

Using chat interface.

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}")

온라인 서빙

vLLM은 OpenAI API 프로토콜을 구현하는 서버로 배포할 수 있어요. 덕분에 OpenAI API를 쓰는 애플리케이션의 drop-in 대체품으로 vLLM을 쓸 수 있어요. 기본적으로 서버는 http://localhost:8000에서 시작돼요. 주소는 --host와 --port 인자로 바꿀 수 있고요. 서버는 한 번에 하나의 모델을 호스팅하며 모델 목록, 채팅 완료 생성, 완료 생성 엔드포인트를 구현해요.

아래 명령으로 Qwen2.5-1.5B-Instruct 모델로 vLLM 서버를 시작해 볼게요.

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

참고: 기본적으로 서버는 토크나이저에 저장된 사전 정의 채팅 템플릿을 사용해요. 이를 바꾸는 방법은 여기에서 배울 수 있어요.

중요: 기본적으로 서버는 Hugging Face 모델 저장소에 generation_config.json이 있다면 이를 적용해요. 즉 특정 샘플링 파라미터의 기본값이 모델 제작자가 권장하는 값으로 바뀔 수 있어요. 이 동작을 끄려면 서버를 시작할 때 --generation-config vllm을 넘겨 주세요.

이 서버는 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 API와 호환되므로, OpenAI API를 쓰는 애플리케이션의 drop-in 대체품으로 쓸 수 있어요. 예를 들어 openai Python 패키지로 질의할 수도 있어요.

from openai import OpenAI

# Modify OpenAI's API key and API base to use vLLM's API server.
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에서 볼 수 있어요.

OpenAI Chat Completions API

vLLM은 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 패키지를 써도 돼요.

from openai import OpenAI
# Set OpenAI's API key and API base to use vLLM's API server.
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)

어텐션 백엔드에 대해

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

원한다면 --attention-backend CLI 인자로 백엔드를 직접 고를 수도 있어요.

# For online serving
vllm serve Qwen/Qwen2.5-1.5B-Instruct --attention-backend FLASH_ATTN

# For offline inference
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.
• Intel XPU: FLASH_ATTN, TRITON_ATTN, TRITON_MLA, XPU_MLA_SPARSE, TORCH_SDPA 또는 TURBOQUANT.

경고: Flash Infer를 포함한 사전 빌드 vllm 휠은 없어서, 사용 환경에 Flash Infer를 직접 설치해야 해요. 설치 방법은 Flash Infer 공식 문서나 docker/Dockerfile을 참고해 주세요.

출처: vLLM 공식 문서 — Quickstart