첫 vLLM 엔드포인트 배포하기 (Quickstart)

Vast.ai 서버리스를 처음 써 보는 분이라면, 1분 안에 첫 vLLM 엔드포인트를 만들어 볼 수 있어요. 과정 자체는 대시보드에서 몇 번 클릭하고 API 키 하나면 끝나요. 여기서는 계정과 API 키를 준비하고, 간단한 요청까지 날려 보는 전체 흐름을 따라가 볼게요.

출처: Vast.ai 공식 문서 — Serverless Quickstart

준비물 (Prerequisites)

시작하기 전에 다음 세 가지를 준비하세요.

Vast.ai 계정: cloud.vast.ai에서 가입하고 계정에 크레딧을 충전해요.
API 키: 계정 설정에서 API 키를 생성해요.
HuggingFace 토큰: gated 모델을 받아오려면 HuggingFace 계정에서 읽기 전용 토큰을 만들어요.

설정 (Configuration)

Vast SDK 설치

서버리스 엔드포인트와 상호작용할 SDK를 설치해요. SDK는 엔드포인트에 요청하는 비동기 파이썬 인터페이스를 제공해요.

pip install vastai

API 키 설정

Vast.ai API 키를 환경 변수로 등록해요. SDK는 이 환경 변수를 자동으로 인증에 사용해요.

export VAST_API_KEY="your-api-key-here"

클라이언트를 초기화할 때 API 키를 직접 넘겨줄 수도 있어요.

client = Serverless(api_key="your-api-key-here")

HuggingFace 토큰 설정

Llama, Mistral 같은 많은 인기 모델은 다운로드 시 인증을 요구해요. HuggingFace 토큰은 계정 단위로 한 번만 설정하면 돼요.

계정 설정으로 이동해요.
"Environment Variables" 섹션을 펼쳐요.
새 변수를 추가해요.
- Key: HF_TOKEN
- Value: HuggingFace 읽기 전용 토큰
"+" 버튼을 클릭한 뒤 "Save Edits" 를 눌러요.

이 토큰은 모든 서버리스 워커에 안전하게 공유돼요. 단, 유효한 HF_TOKEN이 없으면 gated 모델을 내려받지 못하고 워커가 "Loading" 상태에 계속 머물게 되니 주의하세요.

첫 엔드포인트 배포하기

서버리스 대시보드 열기: Serverless Dashboard로 이동해 "Get Started" 를 클릭해요.
엔드포인트 이름 짓고 워크로드 선택: 이름을 넣고(예: vLLM-Qwen3-8B) 드롭다운에서 워크로드 유형을 고르세요. LLM 추론(vLLM, TGI), 이미지 생성(Stable Diffusion, Flux), 텍스트 생성, 기타 중에서 선택 가능해요. 이 퀵스타트에서는 LLM Inference를 골라요.
요청 시작하기: 생성이 끝나면 안내 페이지가 나와요. Vast.ai SDK 설치(pip install vastai), API 키 발급, 샘플 코드 복사까지 진행해요. 시스템이 GPU 워커를 자동으로 프로비저닝하고 템플릿과 스케일링 기본값을 선택해 줘요.
워커 초기화 대기: GPU 인스턴스 기동 → 모델 다운로드(Qwen3-8B 기준 8GB) → GPU 메모리에 로드 → 헬스 체크 순으로 진행돼요. 특히 첫 배포라면 3~5분 정도 기다려야 하고, 더 큰 모델은 그보다 오래 걸릴 수 있어요. 대시보드의 워커 상태로 진행 상황을 확인할 수 있어요.
- Stopped: 모델을 로드해 두고 온디맨드로 활성화될 준비가 된 상태(콜드 워커)
- Loading: 워커가 시작 중이고 모델을 GPU 메모리에 올리는 중
- Ready: 워커가 활성화되어 요청을 처리할 수 있는 상태

SDK는 요청을 자동으로 보유하고 워커가 준비될 때까지 재시도해요. 다만 성능을 위해 첫 호출 전에 워커가 최소 하나는 "Ready" 또는 "Stopped" 상태인 걸 기다리는 게 좋아요.

첫 API 호출 만들기

SDK를 설치했다면, 이제 첫 호출을 날려 볼 차례예요.

import asyncio
from vastai import Serverless
MAX_TOKENS = 100

async def main():
    # API 키가 VAST_API_KEY 환경 변수에 있으면 자동으로 사용돼요
    client = Serverless()

    # 엔드포인트 가져오기
    endpoint = await client.get_endpoint(name="vLLM-Qwen3-8B")

    # 요청 페이로드 준비
    payload = {
          "model": "Qwen/Qwen3-8B",
          "prompt": "Explain quantum computing in simple terms",
          "max_tokens": MAX_TOKENS,
          "temperature": 0.7
    }

    # 요청 보내기
    result = await endpoint.request("/v1/completions", payload, cost=MAX_TOKENS)

    # OpenAI 호환 응답은 result["response"]로 접근
    print(result["response"]["choices"][0]["text"])

    await client.close()

if __name__ == "__main__":
    asyncio.run(main())

SDK가 라우팅, 워커 배정, 인증을 모두 자동으로 처리하니, 엔드포인트 이름을 지정하고 요청만 보내면 돼요.

문제 해결 (Troubleshooting)

워커가 "Loading"에 붙어 있을 때: GPU VRAM이 모델에 충분한지, 모델 이름이 정확한지, 대시보드에서 워커 로그를 확인하고, gated 모델이면 HF_TOKEN이 제대로 설정됐는지 점검해요.
"No workers available" 오류: SDK가 자동으로 재시도하지만, 지속되면 대시보드에서 엔드포인트 상태를 확인하세요.
응답이 느릴 때: 첫 요청은 콜드 상태에서 워커가 깨어나며 오래 걸릴 수 있어요. 워커가 모두 바쁘면 max_workers를 늘리고, 요청이 몰릴 때 즉시 쓸 워커가 부족하면 min_load를 높이고, 요청 폭주가 크면 cold_workers를 늘리거나 목표 사용률을 낮춰 보세요.

첫 vLLM 엔드포인트 배포하기 (Quickstart)