Serverless에 vLLM 배포하기

Serverless 엔드포인트를 하나 만들어서 LLM 추론을 API 요청으로 서빙하는 과정을 따라가 볼게요. vLLM 워커는 Hugging Face에 있는 대부분의 모델을 지원하므로, 원하는 모델을 고르고 RunPod Hub에서 바로 배포하면 돼요.

출처: Serverless에 vLLM 배포하기

준비사항(Requirements)

1단계: 모델 고르기

먼저 배포할 LLM을 정해요. vLLM 워커는 Hugging Face의 대부분의 모델을 지원해요.

Llama 3 (예: meta-llama/Llama-3.2-3B-Instruct)
Mistral (예: mistralai/Ministral-8B-Instruct-2410)
Qwen3 (예: Qwen/Qwen3-8B)
OpenChat (예: openchat/openchat-3.5-0106)
Gemma (예: google/gemma-3-1b-it)
DeepSeek-R1 (예: deepseek-ai/DeepSeek-R1-Distill-Qwen-7B)
Phi-4 (예: microsoft/Phi-4-mini-instruct)

이 튜토리얼에서는 openchat/openchat-3.5-0106을 쓰지만, 호환되는 모델 아무거나로 바꿔도 돼요. 고르는 모델에 따라 추가 환경 변수로 엔드포인트를 구성해야 할 수도 있어요.

2단계: RunPod UI로 배포

vLLM 워커를 배포하는 가장 쉬운 방법은 RunPod의 바로 배포 가능한 레포를 쓰는 거예요.

RunPod Hub에서 vLLM 레포를 찾아요.
최신 vLLM 워커 버전으로 Deploy를 클릭해요.
Model 필드에 모델 이름(openchat/openchat-3.5-0106)을 입력해요.
Advanced를 눌러 vLLM 설정을 펼쳐요.
Max Model Length를 8192로 설정해요(모델에 맞는 컨텍스트 길이면 좋아요).
특별한 요구사항이 없으면 나머지 설정은 기본값으로 두고 Next를 클릭해요.
Create Endpoint를 클릭해요.

RunPod가 리소스를 준비하고 선택한 모델을 다운로드하는 동안 엔드포인트 초기화에 몇 분 걸릴 수 있어요. 더 자세한 최적화 방법은 엔드포인트 구성에서 확인하세요.

3단계: 엔드포인트 ID 확인

배포가 끝나면 Endpoint ID를 기록해 둬요. API 요청을 보낼 때 필요해요.

4단계: UI로 테스트 요청 보내기

엔드포인트 상세 페이지의 Requests 탭에서 테스트해요. 왼쪽에 기본 테스트 요청이 보여요.

{
    "input": {
        "prompt": "Hello World"
    }
}

기본 입력을 그대로 두고 Run을 클릭해요. 워커 초기화에 몇 분 걸릴 수 있어요. 처리가 끝나면 오른쪽에 이런 출력이 보여요.

{
  "delayTime": 638,
  "executionTime": 3344,
  "id": "f0706ead-c5ec-4689-937c-e21d5fbbca47-u1",
  "output": [
    {
      "choices": [
        {
          "tokens": ["CHAT_RESPONSE"]
        }
      ],
      "usage": {
        "input": 3,
        "output": 100
      }
    }
  ],
  "status": "COMPLETED",
  "workerId": "0e7o8fgmm9xgty"
}

5단계: API로 테스트 요청 보내기

API로 테스트 요청을 보내려면 아래 명령에서 YOUR_ENDPOINT_ID와 YOUR_API_KEY를 실제 값으로 바꿔요.

curl -X POST "https://api.runpod.ai/v2/YOUR_ENDPOINT_ID/runsync" \
     -H "Authorization: Bearer ***" \
     -H "Content-Type: application/json" \
     -d '{"input": {"prompt": "Hello World"}}'

이렇게 하면 RunPod Serverless에 vLLM 워커 배포가 끝나요. OpenAI 클라이언트와 RunPod 네이티브 API 양쪽 모두와 호환되는 강력한 확장 가능 LLM 추론 API를 갖게 됐어요.

환경 변수로 배포 커스터마이즈하기(선택)

모델 배포를 커스터마이즈하려면 엔드포인트 설정에 환경 변수를 추가하면 돼요. 유용한 변수 몇 가지예요.

MAX_MODEL_LEN: 최대 컨텍스트 길이 (예: 16384)
DTYPE: 모델 가중치 데이터 타입 (float16, bfloat16, float32)
GPU_MEMORY_UTILIZATION: VRAM 사용량 제어 (예: 0.95는 95%)
CUSTOM_CHAT_TEMPLATE: 커스텀 채팅 템플릿이 필요한 모델용
OPENAI_SERVED_MODEL_NAME_OVERRIDE: OpenAI 요청에 쓰일 모델 이름 변경

환경 변수를 추가·수정하는 순서예요.

엔드포인트 상세 페이지로 이동.
Manage → Edit Endpoint 선택.
Public Environment Variables 섹션 펼치기.
원하는 변수 추가·수정.
Save Endpoint 클릭.

전체 목록은 vLLM 환경 변수 레퍼런스에서 확인해요. 요청 입력 파라미터도 조정할 수 있는데, 예를 들어 max_tokens로 응답당 생성 토큰 최대 수를 늘릴 수 있어요. 자세한 건 vLLM 요청 보내기를 참고하세요.

문제 해결(Troubleshooting)

배포 중 문제가 생기면 이렇게 확인해 보세요.

워커 초기화 실패: 모델이 vLLM과 호환되는지, GPU VRAM이 충분한지 확인.
응답이 느릴 때: 더 강력한 GPU를 쓰거나 요청 파라미터를 최적화.
메모리 부족 오류: GPU 크기를 늘리거나 MAX_MODEL_LEN을 줄이기.
API 오류: Endpoint ID와 API 키가 올바른지 확인.

Serverless에 vLLM 배포하기