runpod-flash

Runpod SDK アプリ（Flash）

Dockerfile／テンプレートを明示的に求めるプロジェクトでは、 runpod-build-template を使用してください。ユーザーがコードファーストのワークフローを選択しない限り、その成果物を Flash に置き換えないでください。

Python をローカルで記述し、rp flash dev でリモートの Runpod GPU／CPU 上で実行し、続けて rp flash deploy でデプロイします。Flash は runpod パッケージ（2.0）の一部です。SDK は 1 つ、rp CLI は 1 つ、ログインも 1 回です。スタンドアロンの runpod-flash パッケージは非推奨で、2026 年 10 月 29 日以降は修正が提供されません。

コマンドの仕様については、rp --help と rp flash <command> --help が正式な情報源です。 このスキルでは、ヘルプ出力には記載されていない基本的な考え方、判断基準、注意点を説明します。コマンドやパラメーターが利用できないと判断する前に、pip show runpod でインストール済みのバージョンを確認してください。

このプロジェクトで使用している SDK は？

コードを書く前に確認してください。2 つの API を混在させることはできません。

見つかったもの	使用中のプロジェクト	対応
import runpod、runpod.App(...)、@app.queue、rp flash ...	Runpod SDK 2.0	このファイルと reference/
from runpod_flash import Endpoint、@Endpoint(...)、flash dev、依存関係に runpod-flash	レガシーの runpod-flash	維持する場合は reference/runpod-flash-legacy.md、移行する場合は reference/migrate-from-runpod-flash.md
新規プロジェクト	Runpod SDK 2.0	以下から開始

新しいコードでは SDK を使用してください。既存の runpod-flash プロジェクトには移行を提案し、まず 既知の違い を確認してください。黙って移行してはいけません。

SDK のバグで SDK の経路が失敗する場合は、runpod-flash が代替手段です。たとえば、runpod/apps/ 内でトレースバックが発生する、関数が実行される前にワーカーがクラッシュする、同じコードが runpod-flash では動作する、といった場合です。まず runpod をアップグレードしてください。修正の確認方法と代替手段への切り替え手順は reference/runpod-flash-legacy.md にあります。

複数の手順を伴う内容では、まず実例を確認してください。 Flash は以下のエンドツーエンドの手順で使用されています： 03 variant B (whisper endpoint)、 07 (network-volume handoff)、および 08 (fine-tune → serve)。全体の一覧は runpod/golden-paths/README.md をご覧ください。実行可能な単一ファイルのアプリは examples/ にあります。

必要に応じて参照してください：

必要な情報	参照先
インストール、rp login、rp flash init、すべての rp コマンド	reference/setup-and-cli.md
デコレーターのパラメーター、呼び出し方法、Queue／Api／Endpoint クライアント、ボリューム、Model、Secret、GPU と CPU の名称	reference/api.md
実例：モデルの選択、モデルのウォームロード、CPU→GPU パイプライン、ファンアウト、タスク、raw HTTP	reference/patterns.md
runpod-flash プロジェクトを SDK に移行する方法	reference/migrate-from-runpod-flash.md
runpod-flash プロジェクトを現状のまま維持する方法	reference/runpod-flash-legacy.md

クイックスタート：uv add "runpod>=2.0.0"（または pip install "runpod>=2.0.0"）→ rp login（または export RUNPOD_API_KEY=...） → rp flash init my-app → cd my-app && rp flash dev main.py。

アプリモデル

import runpod

app = runpod.App("my-app")                     # names the group of resources

@app.queue(gpu="4090", dependencies=["torch"]) # queue-based serverless endpoint
def infer(x: list[float]):
    import torch
    return {"sum": torch.tensor(x, device="cuda").sum().item()}

@runpod.local_entrypoint                       # runs on YOUR machine
def main():
    print(infer.remote([1.0, 2.0, 3.0]))       # runs on a Runpod worker

デコレーター	作成されるもの	用途
関数に付ける @app.queue(...)	自動スケーリングされるキューベースのエンドポイント	リクエスト／レスポンス型の推論、バッチジョブ
クラスに付ける @app.api(...)	ルート（@runpod.get／@runpod.post、@runpod.init でセットアップ）を提供するロードバランシングされたエンドポイント	HTTP サービス、複数ルートの API、一度読み込んだモデルの状態
関数に付ける @app.task(...)	呼び出しごとに作成され、戻り値を返すと終了する、一時的な Pod	トレーニング、ファインチューニング、長時間実行ジョブ

キューまたはタスクのハンドルで使用できる呼び出し方法：fn.remote(...)（ブロックします）、await fn.remote.aio(...)、fn.spawn(...)（Job、タスクの場合はTaskJobを返します）、fn.stream(...)（キュージェネレーター関数のみ）、fn.local(...)（マシン上で実行します）。API クラスはルートで呼び出します：MyApi.post("/path", body)。

開発とデプロイ

• rp flash dev main.py — 反復開発。 一時エンドポイント（dev-<app>-<resource>-<hash>）を作成し、マシン上で@runpod.local_entrypointを実行して、ワーカーのprint出力をターミナルにストリーミングし、ファイルが保存されるたびに再実行します。Ctrl-C でエンドポイントが削除されます。ローカル HTTP サーバーはありません。コードを実行するにはエントリーポイントを使います。
• rp flash dev main.py --once — エントリーポイントを一度実行し、終了処理を行って終了します。失敗した場合はゼロ以外のステータスコードを返します。CI および「移行したコードが動作するか」のスモークテストに使います。
• rp flash deploy — デプロイ。 アーティファクト（組み込み GPU イメージでは torch を除いて最大 1,500 MB）をビルドし、default環境に永続エンドポイントを作成します（その他の環境には--env NAMEを指定します）。再実行すると更新されます。--build-onlyはデプロイせずにパッケージ化するため、エンドポイントの検出と依存関係の解決が機能するかを確認する、手軽なオフラインチェックに使えます。

開発とデプロイでは同じモジュールのソースを実行するため、モジュールレベルのインポート、定数、ヘルパーはどちらでも同じように動作します。デプロイではプロジェクトディレクトリがパッケージ化されますが、開発セッションで送信されるのはモジュールのソースのみです。そのため、rp flash devを使う場合はアプリを1つのファイルにまとめてください。

自律的な開発ループ

開発セッションは長時間実行されます。次の3つのルールを守ってください。

• 標準入力を閉じてバックグラウンドで実行します（< /dev/null）。標準入力がない場合、ファイルが保存されるたびにエントリーポイントが再実行されるため、Enter キーを押す必要はありません。
• 出力をログファイルに記録し、内容を確認します。 ワーカーのprint、トレースバック、✗ remote execution failed: ...、実行ごとの✓ done in ...／✗ failed in ...行がログに出力されます。
• kill（SIGTERM）または SIGINT で停止し、エンドポイントを削除します。 ログがcleaning up N deletedで終わっていることを確認してください。2回目のシグナルを送ると、実行中のエントリーポイントの終了を待たずに、直接クリーンアップに進みます。kill -9ではクリーンアップが省略されます。1回の実行で十分な場合は、--onceを使うと自動でクリーンアップされます。

rp flash dev main.py < /dev/null > /tmp/rp-dev.log 2>&1 &
DEV=$!
# poll the log (bounded) for the run result: "✓ done in ..." or "✗ failed in ..."
for i in $(seq 1 120); do grep -qE "✓ done in|✗ failed in" /tmp/rp-dev.log && break; sleep 3; done
tail -40 /tmp/rp-dev.log
# edit main.py and save -> the session re-scans, refreshes endpoints, re-runs main()
# (each run appends a new result line; read the last one)
kill $DEV; wait $DEV; tail -3 /tmp/rp-dev.log   # expect "cleaning up N deleted"

1回だけ確認する場合は、rp flash dev main.py --onceを使うほうが簡単で、自動的にクリーンアップされます。クリーンアップされずにセッションが終了した場合は、runpodctl serverless listで残ったエンドポイントを一覧表示し、このセッションで作成したdev-<app>-...エンドポイントを ID で削除してください。

リソースの形状を選ぶ

Runpod ランタイムイメージ上の通常の Python をデフォルトとして使います。dependencies=[...]とsystem_dependencies=[...]はワーカーにインストールされるため、Dockerfile は不要です。また、大きな HuggingFace モデルもコード内に保持できます（reference/patterns.mdを参照）。

• どのデコレーターでも**image="org/image:tag"**を指定すると、そのイメージ上で関数が実行されます。必要なのは Python 3 であり、Serverless ハンドラーではありません。システムライブラリや特定の CUDA スタックを使う場合に使用します。 registry_auth=には、プライベートイメージ用に保存した認証情報を指定します（rp registry add）。
• 事前ビルド済みの推論サーバーイメージ（vLLM、worker-comfyui）は、すでに Serverless ハンドラーを実装しているため、SDK アプリではありません。runpodctl または runpod-mcp でデプロイし、runpod.Endpoint("ENDPOINT_ID")で呼び出してください。
• ID で指定する既存のエンドポイント：runpod.Endpoint("ENDPOINT_ID").run_sync({...})。
• 別のデプロイ済みアプリにあるリソース：runpod.Queue(app="media", name="transcribe")／runpod.Api(app="media", name="inference")。

注意事項

1. キューの引数と結果は JSON にシリアライズ可能である必要があります。 キュージョブは開発環境とデプロイ環境のどちらでも、プレーンな JSON です。JSON にシリアライズできない引数を渡すと、開発環境では arguments must be json-serializable が発生し、デプロイ済みエンドポイントでは Python 本来の JSON TypeError が発生します。オブジェクトではなく URL または base64 を渡してください。整数値の浮動小数点数は整数として渡される場合があります（1.0 → 1）。そのため、数値入力は明示的にキャストしてください（torch.tensor(x, dtype=torch.float32)）。
2. 開発環境ではアプリごとにファイルを 1 つにしてください。 開発セッションではモジュールのソースのみが送信されるため、同じディレクトリにあるローカルモジュールのインポートはデプロイ環境では成功しても、開発環境では失敗します。開発セッションでは、ヘルパーを同じファイルかインストール可能なパッケージに置いてください。
3. モジュールスコープではブロッキング処理を行わないでください。 SDK はリソースを検出するため、ローカル環境と各ワーカーでモジュールをインポートします。重いインポート（torch）や処理は関数内に置き、ローカル環境専用のコードは runpod.is_local() で保護してください。
4. gpu= と cpu= は同時に指定できません（gpu and cpu are mutually exclusive）。GPU の文字列は短い形式（"4090"、"H100"）でも、使用可能な GPU のリストでも指定できます。
5. workers=(0, 3) がデフォルトです（runpod-flash では (0, 1) でした）。コストや同時実行数が重要な場合は、明示的に設定してください。idle_timeout の単位は秒です（デフォルトは 60）。
6. GPU の自動切り替えで GPU のリストを渡す場合、workers の最大値を 5 以上にする必要があります。
7. リクエストのペイロード上限は 10 MB です。 大きな出力はボリュームまたはオブジェクトストレージの URL 経由で返してください。
8. ボリュームはすべてが終了しても残ります。 開発セッションと rp flash undeploy はエンドポイントを削除しますが、作成した NetworkVolumes は削除されず、課金が続きます。キューリソースと API リソースは 1 つのボリュームを /runpod-volume にマウントします。リモート関数内で vol.path を読み取り、インポート時には読み取らないでください。モデルの重みはマウントから直接読み込まず、VolumeCache を使って読み込んでください（参考／パターン）。
9. タスクは戻るまで課金されます。 .spawn() したタスクに対して wait() も cancel() もしない場合、スクリプトの終了後も Pod の実行が続きます。
10. ネイティブ CUDA ライブラリも dependencies に含めてください。 たとえば faster-whisper には nvidia-cublas-cu12 と nvidia-cudnn-cu12 が必要です。これらがないと、エラーなしで CPU にフォールバックします。
11. 開発セッションとタスクには、ローカルに Python 3.10～3.14 が必要です。 コードは使用中のインタープリターで pickle 化されて送信されるため、ワーカーのバージョンもローカルと一致します。それ以外のバージョンでは、デプロイは警告を出して 3.12 にフォールバックします。rp flash deploy --python-version で明示的に設定できます。
12. RUNPOD_API_KEY が設定されていると、rp login より優先されます。 古いキーが環境変数として設定されていると、保存済みのログイン情報が有効でも 401 が発生します。runpodctl user で確認し、unset RUNPOD_API_KEY を実行するか、有効なキーをエクスポートしてください。
13. torch ファミリーは GPU イメージに含まれるため、バージョンを固定しないでください。 ビルドでは、一覧に含めているか、依存関係が取り込むか（peft、accelerate、sentence-transformers）にかかわらず、torch、torchvision、torchaudio、triton と、torch のみが必要とする wheel はアーティファクトから除外されます。GPU ワーカーはイメージのビルド（torch 2.9.1+cu128）を使うため、これらのパッケージのバージョン固定は無視されます。CPU リソースと GPU リソースを混在させるアプリでは、依存関係に torch が必要な CPU リソースはコールドスタート時に torch をインストールします。そのための余裕を container_disk_gb に持たせてください（該当する場合、ビルド時に警告が出ます）。
14. 開発セッションでは、ランタイムイメージに組み込まれた runpod が実行されます。 デプロイではローカルのパッケージが同梱されますが、rp flash dev のワーカーは組み込みイメージに含まれる runpod をインポートします。開発ワーカーのトレースバックで runpod. の名前に対する AttributeError が発生する場合、イメージが SDK より古いことを意味します。rp flash deploy ではインストール済みのバージョンが実行されます。
15. アプリと環境を指定してクリーンアップします： rp flash undeploy --app APP --env default -y は、1 つの環境のエンドポイントを削除します。rp flash app delete APP --yes は、すべての環境を削除します（--yes を付けない場合は確認を求め、端末がないと中止します）。その後、不要になったボリュームを削除してください。
16. キュー名と API 名は、デプロイするには 3 文字以上である必要があります。 名前は関数名またはクラス名がデフォルトで使われます。開発セッションではチェックされないため、class SD は rp flash dev では通っても、rp flash deploy では失敗します。名前を変更するか、name= を渡してください。
17. すべてのエンドポイントにアカウントの API キーが渡されます。 デプロイ時も開発時も、コードが別のリソースを呼び出すかどうかにかかわらず、各エンドポイントのテンプレート環境変数に RUNPOD_API_KEY が設定されます。そのため、テンプレートを読める人は誰でもキーを読めます。

リソース

• セットアップと CLI：reference/setup-and-cli.md · API：reference/api.md · パターン：reference/patterns.md · 例：examples/
• SDK のソースと上流の例：https://github.com/runpod/runpod-python (examples/apps/)
• ドキュメント：https://docs.runpod.io/sdk/overview · CLI：https://docs.runpod.io/sdk/cli · 移行：https://docs.runpod.io/sdk/migrate-from-flash