runpod/runpod-python

Runpod | Python 라이브러리

자신의 코드에서 Runpod의 클라우드 플랫폼(GPU 기반 "pods" 및 서버리스 엔드포인트)과 통신할 수 있게 해주는 가볍고 문서화가 잘 된 Python SDK입니다. Runpod REST v2 API를 래핑하고, 서버리스 워커(사용자 정의 모델 추론 API)를 구축하기 위한 작은 프레임워크를 제공하며, pod 수명 주기 관리를 위한 도우미를 포함합니다.

기능 소개

영역	기능
서버리스 워커 SDK	작업을 처리하는 Python 함수를 작성한 후 `runpod.serverless.start({"handler": my_func})`로 시작합니다. SDK는 상태 확인, 선택적 GPU/볼륨 워밍 캐시를 처리하며, 디버깅을 위해 로컬에서 실행할 수 있습니다.
REST v2 래퍼	`runpod.Endpoint(id)`는 배포된 엔드포인트를 호출하기 위한 `.run()`(비동기) 및 `.run_sync()`(동기) 메서드가 포함된 객체를 제공합니다.
Pod 관리	`runpod.create_pod()`, `runpod.get_pods()`, `runpod.stop_pod()`, `runpod.resume_pod()`, `runpod.terminate_pod()`와 같은 함수를 통해 프로그래밍 방식으로 GPU 또는 CPU pod를 시작, 쿼리 및 제어할 수 있습니다.
API 키 처리	`runpod.api_key`를 통한 전역 키 또는 엔드포인트별 키 설정이 가능하며, 우선순위가 문서화되어 있고 스레드 안전합니다.
유틸리티 도우미	네트워크 마운트된 모델 캐시를 예열하기 위한 `VolumeCache`, 워커 시작 전 GPU, 디스크 공간 등을 확인하는 피트니스 체크 데코레이터 등이 포함되어 있습니다.

퀵 스타트 (서버리스 워커)

# my_worker.py
import runpod

def is_even(job):
    n = job["input"]["number"]
    if not isinstance(n, int):
        return {"error": "need an integer"}
    return n % 2 == 0

runpod.serverless.start({"handler": is_even})

이 스크립트를 컨테이너의 진입점(Docker CMD 또는 Runpod 템플릿)으로 추가하면 해당 함수가 사용자 정의 API 엔드포인트로 노출됩니다.

퀵 스타트 (기존 엔드포인트 호출)

import runpod
runpod.api_key = "YOUR_KEY"

ep = runpod.Endpoint("ENDPOINT_ID")
result = ep.run_sync({"text": "hello"})
print(result)   # → 모델 출력 또는 상태 딕셔너리

Pod 수명 주기 예제

import runpod
runpod.api_key = "YOUR_KEY"

# GPU pod 생성
pod = runpod.create_pod(name="demo", image="runpod/stack", gpu_type="NVIDIA GeForce RTX 4090")
print(pod["id"])

# 나중에…
runpod.stop_pod(pod["id"])   # 일시 중지
runpod.resume_pod(pod["id"]) # 재개
runpod.terminate_pod(pod["id"]) # 삭제

설치

# 안정화 버전
pip install runpod   # 또는: uv add runpod

# 최신 개발 버전
pip install git+https://github.com/runpod/runpod-python.git

Python 3.10 이상이 필요합니다.

주요 설계 포인트

피트니스 체크 – 데코레이터(@runpod.serverless.register_fitness_check)는 워커 시작 시 한 번 실행됩니다. 실패 시 프로세스가 중단되어 오케스트레이터가 정상적인 인스턴스를 다시 시작할 수 있도록 합니다.
네트워크 볼륨 워밍 캐시 – VolumeCache는 콜드 스타트 시 원격 볼륨(예: HuggingFace 모델 캐시)을 로컬 저장소로 복사하고 종료 시 다시 동기화하여, 수 GB의 다운로드 비용을 엔드포인트당 1회 비용으로 줄여줍니다.
스레드 안전한 엔드포인트 객체 – 각 Endpoint는 자체 API 키를 저장하므로 여러 스레드에서 동시에 요청을 보내도 안전합니다.
완벽한 Pod 생성 기능 – GPU 및 CPU pod, 사용자 정의 Docker 인수, 볼륨 마운트, 배치 제약 조건 및 스케일링 매개변수를 지원합니다.

다음 단계

문서 – https://docs.runpod.io/serverless-ai/custom-apis 및 저장소의 docs/ 폴더를 참조하세요.
예제 – examples/ 디렉토리에서 바로 사용할 수 있는 워커 및 pod 스크립트를 확인하세요.
커뮤니티 – Discord(README에 링크 있음)에 참여하여 도움, 기능 요청 및 공지 사항을 확인하세요.

요약: runpod Python 패키지는 코드와 Runpod GPU 클라우드를 연결하는 공식 프로덕션급 브리지로, 몇 줄의 Python 코드만으로 pod를 시작하고, 모델 엔드포인트를 호출하거나, 사용자 정의 서버리스 추론 API를 배포할 수 있습니다.