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のダウンロードをエンドポイントごとに一度のコストに抑えます。
スレッドセーフなエンドポイントオブジェクト – 各 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のデプロイを可能にします。