콘텐츠로 이동

vLLM 서빙 (OpenAI 호환 API)

개요

모델을 서버로 띄워 HTTP로 요청을 받으려면, 요청을 받고·배치하고·응답을 돌려주는 서빙 계층을 직접 짜야 해요. vLLM은 이걸 OpenAI 호환 HTTP 서버로 제공해서, OpenAI API를 쓰던 클라이언트를 그대로 연결할 수 있게 합니다. 이 페이지는 vllm serve로 서버를 띄우고 /v1 엔드포인트를 호출하는 흐름을 공식 문서 기준으로 설명해요.

핵심 개념

vllm serve로 서버 띄우기

vLLM을 설치한 뒤 터미널에서 vllm serve <모델>로 서버를 시작해요. 모델은 Hugging Face 모델 ID나 경로를 지정하고, 기본 포트는 8000입니다. --dtype, --api-key 같은 옵션으로 정밀도와 인증을 함께 잡아요.

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

OpenAI 호환 엔드포인트

서버는 OpenAI의 Completions API, Chat API 등을 /v1 경로 아래에 구현합니다. Chat Completions라면 /v1/chat/completions로 요청을 보내고, 클라이언트는 OpenAI 스타일의 messages 배열을 그대로 써요. 반응도 choices 구조로 돌아와요.

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="token-abc123")

completion = client.chat.completions.create(
    model="meta-llama/Llama-3-8B-Instruct",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(completion.choices[0].message.content)

스트리밍과 구조화 출력

stream: true를 보내면 서버가 토큰을 조각 단위로 흘려보내요. UI처럼 첫 글자가 빨리 떠야 하는 서비스에 필요하죠. 또 xgrammar나 guidance 기반의 구조화 출력(JSON 스키마 강제)과 도구 호출(tool calling) 도 지원해요.

인증 주의 — api-key가 모든 경로를 보호하진 않아요

문서가 강조하는 주의점이 있어요. --api-key(또는 VLLM_API_KEY)는 /v1, /v2, /inference 접두어 아래 요청만 인증합니다. 같은 서버의 /invocations 같은 나머지 경로는 인증이 걸리지 않아서, api-key 하나만 믿고 공개망에 두면 안 됩니다. 역방향 프록시 뒤에 두는 등 별도 하드닝이 필요해요.

실제 적용 (데이터스케쳐스)

  • 뉴런 생성 단계 서빙 후보 — 자체 GPU에서 모델을 띄울 때, OpenAI 호환 API로 클라이언트 코드 수정을 최소화해요. 기존에 OpenAI SDK로 작성한 호출부를 base_url만 바꿔 연결할 수 있어요.
  • 프록시/게이트웨이 구성 — 보안상 /invocations 노출을 막기 위해 서버를 역방향 프록시(리버스 프록시) 뒤에 두고, 네트워크 경계에서만 공개하는 구성을 검토합니다.
  • 검증 시점 — 아직 로드맵이라 실제 모델 선택과 인증·라우팅 구성은 자체 GPU 서빙 계획이 구체화될 때 확정해요.

서버가 --api-key만으로 모든 엔드포인트를 보호하지 않는다는 점은 공식 문서가 명시적으로 경고한 부분이에요. 공개 배포 전 인증 범위를 반드시 확인합니다.

더 알아보기