Serverless 빠른 시작

핸들러 함수를 하나 쓰고, 워커 이미지를 만들고, 엔드포인트를 만든 뒤 첫 요청을 보내는 것까지를 한 번에 확인해 볼게요. 더 빠르게 시작하고 싶다면 사전 구성된 템플릿인 worker-basic 저장소를 클론해서 6단계(이미지 빌드)부터 진행해도 돼요.

출처: Serverless 빠른 시작

준비사항(Requirements)

RunPod 계정이 있어야 해요.
로컬 머신에 Python 3.10 이상과 Docker를 설치하고 커맨드라인에서 쓸 수 있게 해 둬야 해요.

1단계: 프로젝트 파일 만들기

프로젝트용 빈 파일을 담을 새 디렉터리를 만들어요.

mkdir serverless-quickstart && cd serverless-quickstart
touch handler.py Dockerfile requirements.txt test_input.json

2단계: Serverless SDK 설치

가상환경을 만들고 Serverless SDK를 설치해요.

python3 -m venv .venv
source .venv/bin/activate
pip install runpod

3단계: 핸들러 함수 작성

handler.py에 아래 코드를 넣어요.

import runpod
import time  

def handler(event):
#   This function processes incoming requests to your Serverless endpoint.
#
#    Args:
#        event (dict): Contains the input data and request metadata
#       
#    Returns:
#       Any: The result to be returned to the client
    
    # Extract input data
    print(f"Worker Start")
    input = event['input']
    
    prompt = input.get('prompt')  
    seconds = input.get('seconds', 0)  

    print(f"Received prompt: {prompt}")
    print(f"Sleeping for {seconds} seconds...")
    
    # You can replace this sleep call with your own Python code
    time.sleep(seconds)  
    
    return prompt 

# Start the Serverless function when the script is run
if __name__ == '__main__':
    runpod.serverless.start({'handler': handler })

이건 JSON 객체를 받아 input 객체 안의 prompt 문자열을 그대로 돌려주는 아주 기본적인 핸들러예요. time.sleep(seconds) 호출 자리에 이미지 생성, 텍스트 생성, 기타 AI/ML 워크로드 코드를 넣으면 돼요.

4단계: 테스트 입력 파일 만들기

로컬에서 핸들러를 제대로 테스트하려면 test_input.json에 아래 내용을 넣어요.

{
    "input": {
        "prompt": "Hey there!"
    }
}

5단계: 핸들러 함수 로컬 테스트

로컬 터미널에서 핸들러 함수를 실행해요.

python handler.py

출력은 대략 이렇게 보여요.

--- Starting Serverless Worker |  Version 1.7.9 ---
INFO   | Using test_input.json as job input.
DEBUG  | Retrieved local job: {'input': {'prompt': 'Hey there!'}, 'id': 'local_test'}
INFO   | local_test | Started.
Worker Start
Received prompt: Hey there!
Sleeping for 0 seconds...
DEBUG  | local_test | Handler output: Hey there!
DEBUG  | local_test | run_job return: {'output': 'Hey there!'}
INFO   | Job local_test completed successfully.
INFO   | Job result: {'output': 'Hey there!'}
INFO   | Local testing complete, exiting.

6단계: Dockerfile 만들기

Dockerfile에 아래 내용을 추가해요. Dockerfile이 처음이라면 컨테이너 입문 튜토리얼 시리즈에서 기본을 익혀 보세요.

FROM python:3.10-slim

WORKDIR /

# Install dependencies
RUN pip install --no-cache-dir runpod

# Copy your handler file
COPY handler.py /

# Start the container
CMD ["python3", "-u", "handler.py"]

7단계: 워커 이미지 빌드·푸시

Docker Hub로 빌드·푸시하지 않고 GitHub 저장소에서 워커를 배포하는 방법도 있어요. RunPod에 배포하려면 우선 이미지를 Docker Hub에 푸시해야 해요.

먼저 RunPod 배포용 플랫폼을 지정해서 Docker 이미지를 빌드해요. [YOUR_USERNAME]은 본인 Docker 이름으로 바꿔 주세요.

docker build --platform linux/amd64 --tag [YOUR_USERNAME]/serverless-test .

이어서 컨테이너 레지스트리에 푸시해요.

docker push [YOUR_USERNAME]/serverless-test:latest

8단계: RunPod 콘솔로 워커 배포

워커를 Serverless 엔드포인트로 배포하는 순서예요.

RunPod 콘솔의 Serverless 섹션으로 이동.
New Endpoint 클릭.
Import from Docker Registry 클릭.
Container Image 필드에 Docker 이미지 URL(docker.io/yourusername/serverless-test:latest) 입력.
Next를 눌러 엔드포인트 구성으로 진행.
엔드포인트 설정 구성:
- (선택) 커스텀 이름을 입력하거나 자동 생성된 이름 사용.
- Endpoint Type을 Queue로 설정.
- GPU Configuration에서 16 GB GPU 체크박스 선택.
- 나머지 설정은 기본값 유지.
Deploy Endpoint 클릭.

시스템이 새 엔드포인트 전용 상세 페이지로 이동시켜 줘요.

9단계: 엔드포인트 테스트

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

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

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

{
    "delayTime": 15088,
    "executionTime": 60,
    "id": "04f01223-4aa2-40df-bdab-37e5caa43cbe-u1",
    "output": "Hello World",
    "status": "COMPLETED",
    "workerId": "uhbbfre73gqjwh"
}

이렇게 하면 첫 Serverless 엔드포인트 배포·테스트가 끝나요.

다음 단계

핸들러 함수 — 더 고급 핸들러 만들기
Dockerfile 만들기 — AI/ML 모델과 의존성 추가
요청 보내기 — 엔드포인트 요청 구조와 전송
엔드포인트 관리 — Serverless 엔드포인트 구성·관리

Serverless 빠른 시작