온라인 서빙 (Online Serving)

온라인 서빙 (Online Serving)

vLLM을 실제 서비스로 띄워서 HTTP API로 모델을 사용하고 싶다면 온라인 서빙을 쓰면 돼요. vLLM은 많은 인터페이스와 호환되는 HTTP 서버를 제공하는데, 지금부터 그 인터페이스들을 정리해 드릴게요.

OpenAI 호환 서버

vLLM은 현재 다음 OpenAI API를 지원해요.

  • Completions API (/v1/completions)
  • Chat Completions API (/v1/chat/completions)
    • 채팅 템플릿이 있는 텍스트 생성 모델에만 적용돼요.
    • 참고: user 파라미터는 무시돼요.
    • 참고: parallel_tool_calls 파라미터를 false로 설정하면 vLLM이 요청당 도구 호출을 0개 또는 1개만 반환하게 돼요. true(기본값)로 설정하면 요청당 도구 호출을 여러 개 반환할 수 있어요. 다만 true로 설정한다고 반드시 여러 개가 반환된다는 보장은 없어요. 이 동작은 모델에 의존적이고, 모든 모델이 병렬 도구 호출을 지원하도록 설계된 건 아니거든요.
  • Chat Completions batch API (/v1/chat/completions/batch)
  • Responses API (/v1/responses, /v1/responses/{response_id}, /v1/responses/{response_id}/cancel)
  • Embeddings API (/v1/embeddings)
  • Transcriptions API (/v1/audio/transcriptions)
  • Translation API (/v1/audio/translations)

Anthropic APIs

  • Anthropic messages API (/v1/messages, /v1/messages/count_tokens)

Cohere APIs

Pooling APIs

Pooling 모델에 대한 자세한 내용은 이 페이지를 참고해 주세요.

음성-텍스트 API (Speech to Text APIs)

음성-텍스트에 대한 자세한 내용은 이 페이지를 참고해 주세요.

커스텀 API (Custom APIs)

계측 API (Instrumentator APIs)

기본 API (Basic APIs)

  • /version — 버전 정보
  • /load — 서버 로드 메트릭
  • /v1/models — 사용 가능한 모델 목록
  • /health — 헬스 체크

메트릭 API (Metrics APIs)

메트릭에 대한 자세한 내용은 이 페이지를 참고해 주세요.

  • /metrics — Prometheus 호환 메트릭 HTTP 엔드포인트

오프라인 API 문서

FastAPI /docs 엔드포인트는 기본적으로 인터넷 연결이 필요해요. 네트워크가 차단된(air-gapped) 환경에서 오프라인 접근을 원한다면 --enable-offline-docs 플래그를 써요.

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

LoRA 동적 로딩

API 서버에서 LoRA 동적 로딩·언로딩이 활성화돼 있어요. 이건 로컬 개발에서만 써야 해요! /v1/load_lora_adapter(LoRA 동적 로딩), /v1/unload_lora_adapter(LoRA 동적 언로딩)가 있어요.

프로파일링 API (Profiling APIs)

vLLM 프로파일링에 대한 자세한 내용은 이 페이지를 참고해 주세요.

  • /start_profile — PyTorch 프로파일러 시작
  • /stop_profile — PyTorch 프로파일러 중지

SageMaker APIs

  • /ping — SageMaker 헬스 체크
  • /invocations — SageMaker 호환 엔드포인트(/v1 엔드포인트와 같은 추론 함수로 라우팅)

확장 API (Scale-Out APIs)

확장 API는 vllm serve에서 기본적으로 비활성화돼 있어요. 환경 변수는 0 또는 1만 받는데, 아래 엔드포인트를 등록하려면 VLLM_ENABLE_SCALE_OUT_ENDPOINTS=1로 설정해 주세요. 전용 vllm launch render와 vllm serve --tokens-only 모드는 명시적 opt-in이며, 변수가 설정되지 않았을 때 필요한 엔드포인트를 활성화해요. 그 모드들에서는 명시적 값 0이 거부돼요.

Tokens IN <> Tokens OUT APIs

  • /inference/v1/generate — 완료 생성
  • /abort_requests — 진행 중인 요청 중단(--tokens-only도 설정됐을 때만)

렌더러 API (Renderer APIs)

렌더러 API에 대한 자세한 내용은 이 페이지를 참고해 주세요.

디렌더러 API (Derenderer APIs)

디렌더러 API에 대한 자세한 내용은 이 페이지를 참고해 주세요.

토크나이즈 API (Tokenize APIs)

  • /tokenize — 텍스트 토크나이즈
  • /detokenize — 토큰 디토크나이즈
  • /tokenizer_info — 채팅 템플릿과 설정을 포함한 종합 토크나이저 정보 조회

탄력적 전문가 병렬 (Elastic Expert Parallelism, EEP)

  • /scale_elastic_ep — 스케일링 작업 트리거
  • /is_scaling_elastic_ep — 스케일링 진행 중인지 확인

개발 모드 서버

VLLM_SERVER_DEV_MODE=1 플래그를 쓰면 개발용 엔드포인트가 활성화돼요.

보안 경고: 이 엔드포인트는 프로덕션에서 절대 쓰면 안 돼요!

캐시 관리 API (Cache Management APIs)

  • /reset_prefix_cache — 프리픽스 캐시 리셋(서비스 중단 가능)
  • /reset_mm_cache — 멀티모달 캐시 리셋(서비스 중단 가능)
  • /reset_encoder_cache — 인코더 캐시 리셋(서비스 중단 가능)

가중치 전송 API (RL Training)

가중치 전송에 대한 자세한 내용은 이 페이지를 참고해 주세요.

  • /pause — 생성 일시 중지(서비스 거부 유발)
  • /resume — 생성 재개
  • /is_paused — 생성이 일시 중지됐는지 확인
  • /abort_requests — 스케줄러를 일시 중지하지 않고 진행 중인 요청(전체 또는 주어진 request_ids) 중단
  • /init_weight_transfer_engine — RLHF용 가중치 전송 엔진 초기화
  • /start_weight_update — 추론 엔진을 가중치 업데이트용으로 준비
  • /update_weights — 모델 가중치 업데이트(모델 동작 변경 가능)
  • /finish_weight_update — 가중치 업데이트 마무리
  • /update_weight_version — 모델 가중치를 업데이트하지 않고 가중치 버전 설정
  • /weight_info — 최신 커밋된 가중치 버전 조회
  • /get_world_size — 분산 world size 조회

콜렉티브 RPC (Collective RPC)

  • /collective_rpc — 엔진에서 임의의 RPC 메서드 실행(극도로 위험)

서버 정보 (Server info)

  • /server_info — 상세 서버 설정 조회

슬립 모드 API (Sleep Mode APIs)

슬립 모드에 대한 자세한 내용은 이 페이지를 참고해 주세요.

  • /sleep — 엔진 슬립(서비스 거부 유발)
  • /wake_up — 엔진 깨우기
  • /is_sleeping — 엔진이 슬립 중인지 확인

채팅 템플릿 (Chat Template)

언어 모델이 채팅 프로토콜을 지원하게 하려면 vLLM이 모델의 토크나이저 설정에 채팅 템플릿을 포함할 것을 요구해요. 채팅 템플릿은 역할, 메시지, 기타 채팅 전용 토큰이 입력에 어떻게 인코딩되는지를 지정하는 Jinja2 템플릿이에요. NousResearch/Meta-Llama-3-8B-Instruct의 채팅 템플릿 예시는 여기에서 볼 수 있어요.

일부 모델은 instruction/chat 미세튜닝이 됐는데도 채팅 템플릿을 제공하지 않아요. 그런 모델은 --chat-template 파라미터로 채팅 템플릿 경로나 문자열 형태를 직접 지정할 수 있어요. 채팅 템플릿이 없으면 서버가 채팅을 처리할 수 없어서 모든 채팅 요청이 에러로 끝나요.

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

vLLM 커뮤니티는 인기 모델용 채팅 템플릿 세트를 제공해요. examples 디렉토리에서 찾을 수 있어요.

멀티모달 채팅 API가 포함되면서 OpenAI 스펙은 이제 type과 text 필드를 모두 지정하는 새 형식의 채팅 메시지를 받아들여요. 예시는 아래와 같아요.

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!"},
            ],
        },
    ],
)

대부분의 LLM 채팅 템플릿은 content 필드가 문자열일 거라고 기대하지만, meta-llama/Llama-Guard-3-1B 같은 최신 모델은 콘텐츠가 요청의 OpenAI 스키마대로 형식화되길 기대해요. vLLM은 이를 자동 감지하는 best-effort 지원을 제공하는데, "Detected the chat template content format to be..." 같은 문자열로 로그에 남기고, 들어오는 요청을 감지된 형식에 맞게 내부적으로 변환해요. 가능한 형식은 다음과 같아요.

  • "string": 문자열.
    • 예: "Hello world"
  • "openai": OpenAI 스키마와 비슷한 딕셔너리 목록.
    • 예: [{"type": "text", "text": "Hello world!"}]

결과가 기대와 다르다면 --chat-template-content-format CLI 인자로 사용할 형식을 오버라이드할 수 있어요.

Ray Serve LLM

Ray Serve LLM은 vLLM 엔진의 확장 가능하고 프로덕션급 서빙을 가능하게 해요. vLLM과 밀접하게 통합되며 자동 스케일링, 로드 밸런싱, 백프레셔 같은 기능을 더해 줘요. 핵심 기능은 다음과 같아요.

  • OpenAI 호환 HTTP API와 Pythonic API를 모두 노출해요.
  • 코드 변경 없이 단일 GPU에서 멀티 노드 클러스터로 확장돼요.
  • Ray 대시보드와 메트릭을 통한 관측성과 자동 스케일링 정책을 제공해요.

DeepSeek R1 같은 큰 모델을 Ray Serve LLM으로 배포하는 예시는 examples/ray_serving/ray_serve_deepseek.py에서 볼 수 있어요. Ray Serve LLM에 대해 더 알고 싶다면 공식 Ray Serve LLM 문서를 참고해 주세요.

출처: vLLM 공식 문서 — Online Serving