RunPod Cloud GPU

RunPod serverless で cloud GPU 上のオープンソース AI モデルを実行します。従量課金制、最低料金なし。

セットアップ

# 1. https://runpod.io でアカウントを作成
# 2. .env に API キーを追加
echo "RUNPOD_API_KEY=your_key_here" >> .env

# 3. --setup を使用してツールをデプロイ
python tools/image_edit.py --setup
python tools/upscale.py --setup
python tools/dewatermark.py --setup
python tools/sadtalker.py --setup
python tools/qwen3_tts.py --setup

各 --setup コマンドで以下が実行されます:

1. Docker イメージから RunPod テンプレート を作成
2. 適切な GPU で serverless エンドポイント を作成
3. エンドポイント ID を .env に保存 (例: RUNPOD_QWEN_EDIT_ENDPOINT_ID)

利用可能なイメージ

すべてのイメージは GHCR で公開されており、認証は不要です。

ツール	Docker イメージ	GPU	VRAM	一般的なコスト
image_edit	ghcr.io/conalmullan/video-toolkit-qwen-edit:latest	A6000/L40S	48GB+	~$0.05-0.15/job
upscale	ghcr.io/conalmullan/video-toolkit-realesrgan:latest	RTX 3090/4090	24GB	~$0.01-0.05/job
dewatermark	ghcr.io/conalmullan/video-toolkit-propainter:latest	RTX 3090/4090	24GB	~$0.05-0.30/job
sadtalker	ghcr.io/conalmullan/video-toolkit-sadtalker:latest	RTX 4090	24GB	~$0.05-0.15/job
qwen3_tts	ghcr.io/conalmullan/video-toolkit-qwen3-tts:latest	ADA 24GB	24GB	~$0.01-0.05/job

月間総コスト: 頻繁に使用しても $10 を超えることはほとんどありません。

仕組み

すべてのツールは同じパターンに従います:

Local CLI → Upload input to cloud storage → RunPod API → Poll for result → Download output

1. ファイル転送: ツールは Cloudflare R2 が設定されている場合 (R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_BUCKET_NAME) に使用し、そうでない場合は無料のアップロード サービスにフォールバック
2. RunPod API: ツールは /run エンドポイントを呼び出し、完了するまで /status/{job_id} をポーリング
3. コールドスタート vs ウォームスタート: アイドル後の最初のリクエストはワーカーをスピンアップ (~30-90s)。その後のリクエストは高速 (~5-15s)

エンドポイント管理

ワーカー

workersMin: 0    — アイドル時にゼロにスケール (コストなし)
workersMax: 1    — 最大同時ジョブ数 (スループット向上には増加)
idleTimeout: 5   — ワーカーがスケールダウンするまでの秒数

すべてのエンドポイント全体で、RunPod プランに基づくワーカー プールを共有します。制限に達した場合は、積極的に使用していないエンドポイントの workersMax を減らしてください。

エンドポイント ステータスの確認

各ツールは .env にエンドポイント ID を保存します:

ツール	環境変数
image_edit	RUNPOD_QWEN_EDIT_ENDPOINT_ID
upscale	RUNPOD_UPSCALE_ENDPOINT_ID
dewatermark	RUNPOD_DEWATERMARK_ENDPOINT_ID
sadtalker	RUNPOD_SADTALKER_ENDPOINT_ID
qwen3_tts	RUNPOD_QWEN3_TTS_ENDPOINT_ID

エンドポイントの無効化

エンドポイントを削除せずにワーカー スロットを解放するには、RunPod ダッシュボードまたは GraphQL API 経由で workersMax=0 を設定してください。

RunPod API リファレンス

これらを使用してエンドポイントをプログラムで照会・管理します。RunPod は GraphQL introspection を無効化しているため、これらのフィールド名は検証済みで完全に一致する必要があります。

認証

すべての API 呼び出しに Authorization: Bearer $RUNPOD_API_KEY が必要です。

• GraphQL: POST https://api.runpod.io/graphql
• REST (Serverless): https://api.runpod.ai/v2/{endpoint_id}/...

GraphQL クエリ

すべてのエンドポイントを一覧表示:

query { myself { endpoints { id name gpuIds templateId workersMax workersMin } } }

現在の支出率:

query { myself { currentSpendPerHr spendDetails { localStoragePerHour networkStoragePerHour gpuComputePerHour } } }

Pod を一覧表示:

query { myself { pods { id name runtime { uptimeInSeconds } machine { gpuDisplayName } desiredStatus } } }

よくある間違い: フィールド名は camelCase で完全な単語 — localStoragePerHr ではなく localStoragePerHour。エンドポイントは serverlessWorkers ではなく endpoints。spending はフィールドではなく — currentSpendPerHr と spendDetails を使用してください。

GraphQL ミューテーション

エンドポイント GPU または設定を更新:

mutation { saveEndpoint(input: {
  id: "endpoint_id",
  name: "endpoint-name",
  templateId: "template_id",
  gpuIds: "AMPERE_24",
  workersMin: 0,
  workersMax: 1
}) { id gpuIds } }

saveEndpoint は更新時でも name と templateId が必要です — まず現在の値を取得するためにクエリしてください。

REST API (Serverless)

アクション	メソッド	URL
ジョブを送信	POST	/v2/{id}/run
ステータスを確認	GET	/v2/{id}/status/{job_id}
ジョブをキャンセル	POST	/v2/{id}/cancel/{job_id}
保留中を一覧表示	GET	/v2/{id}/requests
ヘルス/統計	GET	/v2/{id}/health

ヘルス レスポンス にはジョブ数とワーカー状態が含まれます:

{
  "jobs": { "completed": 16, "failed": 1, "inProgress": 0, "inQueue": 2, "retried": 0 },
  "workers": { "idle": 0, "initializing": 1, "ready": 0, "running": 0, "throttled": 0 }
}

注: /requests は保留中/キューに入っているジョブのみを返します。完了したジョブの履歴は API では利用できません — ログについては RunPod ウェブ コンソールを確認してください。

GPU タイプ ID

ID	GPU	VRAM	一般的なコスト
AMPERE_24	RTX 3090	24GB	~$0.34/hr
ADA_24	RTX 4090	24GB	~$0.69/hr
AMPERE_48	A6000	48GB	~$0.76/hr
AMPERE_80	A100	80GB	~$1.99/hr

可用性に関する注: ADA_24 (4090) は RunPod で頻繁にスロットル/利用不可です。ジョブがキューに無限に留まることを避けるため、常に 複数のフォールバック GPU タイプ でエンドポイントを設定してください (カンマ区切り):

gpuIds: "AMPERE_24,ADA_24"   # 最初に 3090 を試行、4090 にフォールバック

すべてのツールキット ツールは 5 分間のキュー タイムアウトも適用しており、300 秒以内に GPU が利用できない場合、ジョブは自動的にキャンセルされて、初期化サイクル失敗からの失控請求を防ぎます。

Cloudflare R2 (AWS CLI 経由)

R2 は S3 互換 API を使用しますが --region auto が必要です:

AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY_ID" \
AWS_SECRET_ACCESS_KEY="$R2_SECRET_ACCESS_KEY" \
aws s3api list-objects-v2 \
  --bucket "$R2_BUCKET_NAME" \
  --endpoint-url "https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com" \
  --region auto

よくある間違い: --region auto を省略すると InvalidRegionName エラーが発生します。R2 有効リージョン: wnam, enam, weur, eeur, apac, oc, auto。

トラブルシューティング

イメージ プルを強制

新しい Docker イメージ バージョンをプッシュしても、RunPod はキャッシュされた古いイメージをまだ使用する可能性があります。プルを強制するには:

1. テンプレートの imageName を @sha256:DIGEST 記法を使用するように更新
2. ワーカーが再起動するまで待機
3. 確認後 :latest タグに戻す

コールドスタートが遅い

• qwen3-tts: ~70s コールドスタート、~7s ウォーム
• sadtalker: ~60s コールドスタート、~10s ウォーム
• image_edit: ~90s コールドスタート、~15s ウォーム

コールドスタートが問題の場合は、workersMin: 1 を設定してください (アイドル時にコストがかかります)。

ジョブが OOM で失敗

モデルが GPU が提供する VRAM より多くの VRAM を必要とします。オプション:

• より大きい GPU ティアを使用
• dewatermark の場合: --resize-ratio を減らす (デフォルト 0.5 で安全)
• image_edit の場合: --steps を減らす

「No workers available」

RunPod プランの同時ワーカー制限に達しました。以下のいずれか:

• 実行中のジョブが終了するまで待機
• 使用していないエンドポイントで workersMax=0 を設定
• RunPod プランをアップグレード

Docker イメージ

すべての Dockerfile は docker/runpod-*/ に存在します。イメージはツール全体でレイヤーを共有するために runpod/pytorch をベースとして使用します。

RunPod 用にビルド (Apple Silicon Mac から):

docker buildx build --platform linux/amd64 -t ghcr.io/conalmullan/video-toolkit-<name>:latest docker/runpod-<name>/
docker push ghcr.io/conalmullan/video-toolkit-<name>:latest

GHCR パッケージはデフォルトで プライベート です — RunPod が実行できるようにするには手動でパブリックにする必要があります。GitHub > Packages > Package Settings > Change Visibility に移動してください。

コスト最適化

• すべてのエンドポイントで workersMin: 0 を保持 (ゼロにスケール)
• 積極的に使用するエンドポイントのみをデプロイ
• workersMax=0 を使用してアイドル エンドポイントを削除せずに無効化
• Qwen3-TTS は ElevenLabs よりナレーション用に大幅に安い
• RunPod ダッシュボードで使用状況と請求を確認