Worker SDK

English

The half of the SDK that runs inside your worker container. The other half is Client SDK.

Read out of the installed source (runpod 1.11.0) and confirmed by running each case. Where behaviour is surprising, the observed output is shown.

Startup fitness checks

Before your handler is ever called, the worker validates the machine it landed on. A failed check kills the process with os._exit(1) and the orchestrator routes the job elsewhere, rather than letting it fail slowly on bad hardware. At ~1,125 lines this is the largest part of the worker half, and it runs whether you ask for it or not.

Thresholds are environment variables, so you set them on the endpoint: RUNPOD_MIN_MEMORY_GB (4.0), RUNPOD_MIN_DISK_PERCENT (10.0), RUNPOD_MIN_CUDA_VERSION (11.8), and RUNPOD_SKIP_GPU_CHECK / RUNPOD_SKIP_AUTO_SYSTEM_CHECKS to turn groups off.

Add your own with a decorator — sync or async, raise to fail:

@runpod.serverless.register_fitness_check
def check_weights_present():
    if not os.path.exists("/runpod-volume/model.safetensors"):
        raise RuntimeError("model weights missing")

Handler utilities

The contract

import runpod

def handler(job):
    return {"result": job["input"]["x"] * 2}

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

start() takes a config dict, not just a handler, and does not return — it takes over the process and calls your handler once per job. The handler receives at least id and input; job["input"] is exactly what the caller sent.

Return values — two keys are control signals

The SDK inspects your return value and pulls two keys out as control signals rather than data:

DEBUG | run_job return: {'output': {'ok': False}, 'error': 'bad input'}
ERROR | Job local_test failed with error: bad input

Exceptions

The SDK catches them, the worker survives, and the job fails with a JSON blob containing error_type, error_message, error_traceback, hostname, worker_id and runpod_version.

Streaming

yield instead of return, and each partial is sent as its own {"output": ...}. Sync and async generators both work. Add return_aggregate_stream: True so /runsync and /status can return the collected output, not just /stream.

Other config keys

Worth knowing

• progress_update(job, msg) — visible to callers via /status, runs on a background thread.
• rp_validator.validate(input, schema) — type checks, defaults, constraints lambdas, rejects unexpected keys.
• download_files_from_urls / upload_file_to_bucket — for caller-supplied URLs and large results.
• register_fitness_check — startup checks; a failure exits the worker so the orchestrator restarts it.
• Return bodies over 20 MB trigger an SDK tip recommending S3 instead. A log line, not enforced — treat it as a limit anyway.

Local test flags

Full reference in the repo →

한국어

설치된 SDK 소스(runpod 1.11.0)를 직접 읽고 각 경우를 실행해 확인한 내용입니다. 동작이 직관과 다른 부분은 실제 출력을 함께 실었습니다.

기동 시 fitness check

핸들러가 호출되기 전에 워커가 자기가 배치된 머신을 검증합니다. 검사가 실패하면 os._exit(1) 로 프로세스를 종료하고 오케스트레이터가 작업을 다른 곳으로 보냅니다. 불량 하드웨어 위에서 천천히 실패하게 두지 않는 것입니다. 약 1,125줄로 워커 절반에서 가장 큰 부분이며, 요청하지 않아도 실행됩니다.

임계값은 환경변수라 엔드포인트에서 설정합니다. RUNPOD_MIN_MEMORY_GB (4.0), RUNPOD_MIN_DISK_PERCENT (10.0), RUNPOD_MIN_CUDA_VERSION (11.8), 그리고 그룹을 끄려면 RUNPOD_SKIP_GPU_CHECK / RUNPOD_SKIP_AUTO_SYSTEM_CHECKS.

데코레이터로 직접 추가할 수 있습니다. 동기·비동기 모두 되고, 실패시키려면 예외를 던집니다.

@runpod.serverless.register_fitness_check
def check_weights_present():
    if not os.path.exists("/runpod-volume/model.safetensors"):
        raise RuntimeError("model weights missing")

Handler 유틸리티

계약

import runpod

def handler(job):
    return {"result": job["input"]["x"] * 2}

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

start() 는 핸들러가 아니라 설정 딕셔너리를 받고, 반환하지 않습니다. 프로세스를 넘겨받아 작업마다 핸들러를 호출합니다. 핸들러는 최소 id 와 input 을 받으며, job["input"] 은 호출자가 보낸 그대로입니다.

반환값 — 키 두 개는 제어 신호입니다

SDK 가 반환값을 검사해 두 키를 데이터가 아닌 제어 신호로 꺼냅니다.

DEBUG | run_job return: {'output': {'ok': False}, 'error': 'bad input'}
ERROR | Job local_test failed with error: bad input

예외

SDK 가 잡습니다. 워커는 살아남고 작업만 실패하며, error_type, error_message, error_traceback, hostname, worker_id, runpod_version 이 담긴 JSON 이 반환됩니다.

스트리밍

return 대신 yield 하면 각 조각이 개별 {"output": ...} 으로 전송됩니다. 동기·비동기 제너레이터 모두 됩니다. return_aggregate_stream: True 를 주면 /stream 뿐 아니라 /runsync 와 /status 에서도 모아진 출력을 받습니다.

그 외 설정 키

알아두면 좋은 것

• progress_update(job, msg) — 호출자가 /status 에서 확인. 백그라운드 스레드에서 실행되어 핸들러를 막지 않음
• rp_validator.validate(input, schema) — 타입 검사, 기본값, constraints 람다, 예상치 못한 키 거부
• download_files_from_urls / upload_file_to_bucket — 호출자가 준 URL 처리와 큰 결과물 업로드
• register_fitness_check — 기동 시 점검. 실패하면 워커가 종료되어 오케스트레이터가 재시작
• 반환 본문 20MB 초과 시 SDK 가 S3 사용을 권하는 팁을 남김. 강제는 아니지만 제한으로 취급할 것

로컬 테스트 플래그

저장소에서 전체 레퍼런스 보기 →