RunPod — vLLM 배포

RunPod — vLLM 배포

vLLM은 AI 추론 워크로드를 위한 온디맨드·서버리스 GPU 인스턴스를 제공하는 클라우드 GPU 플랫폼인 RunPod에 배포할 수 있습니다.

출처: 문서

본문

사전 준비 (Prerequisites)

  • GPU 파드 접근 권한이 있는 RunPod 계정
  • CUDA 호환 템플릿(예: runpod/pytorch)으로 실행 중인 GPU 파드

서버 시작 (Starting the Server)

RunPod 파드에 SSH로 접속해 vLLM OpenAI 호환 서버를 실행합니다:

vllm serve <model-name> \
    --host 0.0.0.0 \
    --port 8000

참고: --host 0.0.0.0을 사용해 모든 인터페이스에 바인딩해야 컨테이너 밖에서도 서버에 접근할 수 있습니다.

포트 8000 노출 (Exposing Port 8000)

RunPod은 HTTP 서비스를 자체 프록시를 통해 노출합니다. 포트 8000에 접근하려면:

  • RunPod 대시보드에서 파드 설정으로 이동합니다.
  • 노출할 HTTP 포트 목록에 8000을 추가합니다.
  • 파드가 재시작되면 RunPod이 다음 형식의 공용 URL을 제공합니다:
https://<pod-id>-8000.proxy.runpod.net

502 Bad Gateway 문제 해결 (Troubleshooting 502 Bad Gateway)

RunPod 프록시의 502 Bad Gateway 오류는 보통 서버가 아직 요청을 듣고 있지 않다는 뜻입니다. 흔한 원인:

  • 모델이 아직 로딩 중 — 큰 모델은 다운로드와 GPU 메모리 로딩에 시간이 걸립니다. 파드 로그로 진행 상황을 확인하세요.
  • 잘못된 호스트 바인딩 — --host 0.0.0.0을 전달했는지 확인하세요. 127.0.0.1(기본값)에 바인딩하면 프록시가 서버에 도달할 수 없습니다.
  • 포트 불일치 — --port 값이 RunPod 대시보드에 노출한 포트와 일치하는지 확인하세요.
  • GPU 메모리 부족 — 모델이 할당된 GPU에 비해 너무 클 수 있습니다. 로그에서 CUDA OOM 오류를 확인하고, 인스턴스를 더 크게 만들거나 멀티 GPU 파드에서 --tensor-parallel-size를 추가하는 것을 고려하세요.

배포 검증 (Verifying the Deployment)

서버가 실행되면 curl 요청으로 테스트합니다:

curl https://<pod-id>-8000.proxy.runpod.net/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "<model-name>",
        "messages": [
            {"role": "user", "content": "Hello, how are you?"}
        ],
        "max_tokens": 50
    }'

응답 예시:

{
    "id": "chat-abc123",
    "object": "chat.completion",
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "I'm doing well, thank you for asking! How can I help you today?"
            },
            "index": 0,
            "finish_reason": "stop"
        }
    ]
}

서버 건강 상태(health) 엔드포인트도 확인할 수 있습니다:

curl https://<pod-id>-8000.proxy.runpod.net/health

더 알아보기 (Learn more)