OpenAI 호환 서버로 서빙하기

vLLM은 OpenAI의 Completions API, Chat API를 구현한 HTTP 서버를 제공해요. vllm serve로 모델을 하나 띄워 두면, 언어를 가리지 않고 HTTP 클라이언트로 모델을 호출할 수 있어요. 프로덕션 서빙의 표준 경로예요.

출처: https://docs.vllm.ai/en/latest/serving/openai_compatible_server

서버 시작하기

터미널에서 vllm serve로 시작하고, Docker 이미지로도 띄울 수 있어요.

vllm serve NousResearch/Meta-Llama-3-8B-Instruct \
  --dtype auto \
  --api-key token-abc123

--api-key로 인증키를 걸어 두면, 호출할 때 이 키가 필요해요. 응답이 OpenAI 형식이라, 공식 OpenAI 파이썬 클라이언트로 바로 쓸 수 있어요.

채팅 호출하기

서버가 뜨면 OpenAI 파이썬 클라이언트의 chat.completions.create로 모델을 호출할 수 있어요.

completion = client.chat.completions.create(
    model="NousResearch/Meta-Llama-3-8B-Instruct",
    messages=[
        {"role": "user", "content": [{"type": "text", "text": "Classify this sentiment: vLLM is wonderful!"}]}
    ]
)

OpenAI에 없는 파라미터

vLLM은 top_k 같은 OpenAI에 없는 파라미터를 지원해요. OpenAI 클라이언트에서는 extra_body로 넘기면 돼요.

client.chat.completions.create(
    model="NousResearch/Meta-Llama-3-8B-Instruct",
    messages=[...],
    extra_body={"top_k": 50}
)

기본 API 엔드포인트

서버가 기본으로 제공하는 엔드포인트 중 핵심은 이래요.

/v1/models – 사용 가능한 모델 목록.
/health – 헬스 체크.
/metrics – Prometheus 호환 지표.
/version – 버전 정보.

FastAPI의 /docs 엔드포인트는 기본적으로 인터넷 연결을 요구해요. 오프라인 환경에서는 --enable-offline-docs 플래그를 켜서 로컬에서 접근 가능하게 할 수 있어요.

vllm serve NousResearch/Meta-Llama-3-8B-Instruct --enable-offline-docs

설정 주의점

기본적으로 서버는 Hugging Face 모델 저장소의 generation_config.json이 있으면 그 설정을 적용해요. 모델 제작자가 권장한 샘플링 기본값이 반영될 수 있다는 뜻이라, 이 동작을 끄려면 --generation-config vllm을 써요.

또한 모델이 채팅을 지원하려면 채팅 템플릿이 있어야 해요. 없으면 채팅 요청이 모두 오류로 떨어져요.

vllm serve <model> --chat-template ./path-to-chat-template.jinja

인기 모델용 채팅 템플릿은 vLLM 저장소의 examples 디렉터리에서 공개돼 있어요.

더 알아보기

코드 안에서 쓰는 법은 «오프라인 추론하기»를 보세요.
생성 옵션은 «생성 파라미터 다루기»에서 다뤄요.