RunPod Serverless入門【自作AI APIをサーバーレスでデプロイ】

この記事のポイント

RunPod Serverless はリクエスト処理時間だけ課金されるサーバーレス GPU サービス。アイドル中の費用がゼロになる
最安 GPU は A4000 系（16 GB VRAM）で $0.58/hr から。小〜中規模モデルの推論エンドポイントに向く
デプロイの流れは「handler.py 作成 → Docker イメージ化 → RunPod コンソールでエンドポイント登録」の 3 ステップ
runpod SDK は pip install runpod で入る（Ubuntu 24.04 で 1.9.1 を確認済み）
Worker 最小数を 0 にするとアイドル中は無課金になるが、コールドスタートが発生する

「GPU の API エンドポイントを公開したいけど、アイドル中も課金され続けるのがつらい」——RunPod Pods を使い始めて最初に直面する悩みです。

RunPod には Serverless というサービスタイプがあり、リクエストが来たときだけ GPU を起動して処理します。利用者が少ない時間帯は Workers を 0 にでき、アイドル中の費用が実質ゼロになります。私が実際に触ってみると、Pods とは明確にアーキテクチャが違う点がいくつかあって、最初に理解しておくと詰まらずに済みます。

この記事では、Ubuntu 24.04 コンテナで runpod SDK（v1.9.1）を実際にインストールし、ハンドラー関数の動作を確認した上で、Serverless のデプロイ手順を解説します。

検証環境

検証は docker run --rm ubuntu:24.04（Python 3.12.3 / pip 24.0）で実施しています（2026-06-20）。RunPod コンソールの UI は 2026 年 6 月時点の仕様です。

RunPod Serverless とは何か

RunPod には大きく 3 つのサービスタイプがあります。

Pods（Cloud GPU）：専有 GPU インスタンス。起動中は秒単位で課金。SSH 接続できる
Serverless：API エンドポイント形式の GPU 推論サービス。処理時間だけ課金
Clusters：マルチ GPU クラスター。分散学習向け

Serverless が特に向いているのは「本番 API として公開するが、トラフィックの波がある」ケースです。深夜帯にほとんどリクエストがない場合、Pods だと GPU を起動したまま課金が積み上がりますが、Serverless なら Workers を 0 にして無課金にできます。

RunPod Serverless 製品ページ（公式サイト 2026-06-20 実撮影）

Pods との違いをひと言で

Pods は「VPS を GPU で借りる感覚」で、SSH でログインして何でもできます。一方 Serverless は「関数を GPU 上で動かす」イメージで、HTTP リクエストを受け取り、処理して、結果を返すだけです。SSH 接続はできません。

正直なところ、Pods に慣れてから Serverless に移ると最初は不自由に感じます。でもその分、スケーリングとコスト管理が自動化される恩恵は大きいです。

Serverless GPU の料金（実測スクレイピング）

2026-06-13 に Playwright で公式料金ページ（runpod.io/gpu-instance/pricing）をスクレイピングして取得した Serverless Workers の料金です。

RunPod Serverless GPU 料金一覧（Playwright 実測スクレイピング 2026-06-13）

一番安いのは A4000 / A4500 / RTX 4000 系（16 GB VRAM）で $0.58/hr。7B 程度のモデルなら十分動きます。Llama 3 70B クラスなら A100（80 GB）が $2.72/hr、それ以上は H200 や B200 を選ぶことになります。

「PRO」と付いているのは専有リソースの Worker で、コールドスタートが短くなります。非 PRO は共有プールから割り当てられ料金が安い反面、コールドスタートのばらつきが出やすいです。

RunPod 料金ページ Serverless セクション（Playwright 実撮影 2026-06-20）

Serverless のデプロイ手順

デプロイに必要なのは 3 つだけです。

ハンドラー関数（handler.py）を書く
Docker イメージを作って公開レジストリにプッシュする
RunPod コンソールでエンドポイントを登録する

手順 1：runpod SDK をインストールする

まずローカル（または Docker コンテナ内）で SDK をインストールして動作確認します。Ubuntu 24.04 で実測した結果です。

ubuntu@linuxlab: ~

$ pip install runpod
Successfully installed runpod-1.9.1 …
$ python3 -c “import runpod; print(runpod.__version__)”
1.9.1

SDK が入ると runpod.serverless モジュールが使えるようになります。Ubuntu 24.04 のシステム pip に入れる場合は --break-system-packages フラグが必要です（venv 内なら不要）。

runpod SDK インストールとハンドラー動作確認（Ubuntu 24.04 実測）

手順 2：handler.py を書く

Serverless の核となるのがハンドラー関数です。job という辞書を受け取り、処理結果を返すだけです。

handler.py

# handler.py — RunPod Serverless ハンドラーの最小構成
import runpod

def handler(job):
job_input = job[“input”] # リクエストボディの “input” キー
prompt = job_input.get(“prompt”, “Hello”)

# ここに実際の推論処理を書く（例: model.generate(…)）
result = f”Echo: {prompt}”

return {“result”: result} # dict を返す

runpod.serverless.start({“handler”: handler})

ハンドラーが受け取る job の構造は次の通りです。

job の構造（RunPod から渡される）

{
“id”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”, # ジョブ固有 ID
“input”: { “prompt”: “こんにちは” } # API リクエストの input
}

ハンドラーが返す値は辞書（dict）でも文字列でも構いません。RunPod が JSON としてレスポンスに載せてくれます。

ローカルでハンドラーをテストするときは runpod.serverless.start() を呼ばずに、ハンドラー関数を直接呼び出す方が簡単です。Ubuntu 24.04 コンテナで確認した結果では次のように動きました。

ubuntu@linuxlab: ~

$ python3 -c ”
import runpod
def handler(job):
return {‘result’: ‘Echo: ‘ + job[‘input’][‘prompt’]}
out = handler({‘input’: {‘prompt’: ‘serverless test’}})
print(out)
“
{‘result’: ‘Echo: serverless test’}

手順 3：Dockerfile を作る

RunPod Serverless は Docker イメージで動くので、handler.py を含む Dockerfile を作ります。

Dockerfile

# GPU ありの場合は nvidia/cuda ベースを使う
FROM python:3.12-slim

WORKDIR /app
COPY handler.py .
COPY requirements.txt .

RUN pip install –no-cache-dir -r requirements.txt

CMD [“python3”, “-u”, “handler.py”]

requirements.txt

runpod==1.9.1
# 必要に応じて追加（例: transformers, torch, …）

GPU を使う場合（PyTorch + CUDA）は FROM nvidia/cuda:12.1.0-cudnn8-runtime-ubuntu22.04 のような NVIDIA ベースイメージに切り替えて、torch を GPU 版でインストールします。

注意：イメージサイズ

PyTorch の GPU 版イメージは 10 GB 超になることがあります。nvidia/cuda ベースに必要最小限のパッケージのみ入れ、--no-cache-dir で pip キャッシュをオフにしましょう。

手順 4：Docker Hub にプッシュする

ubuntu@linuxlab: ~

$ docker login
$ docker build -t yourusername/my-runpod-handler:latest .
$ docker push yourusername/my-runpod-handler:latest

Docker Hub（無料アカウントで Public リポジトリ可）でも GitHub Container Registry でも使えます。RunPod コンソールからイメージ URL を指定するので、公開アクセス可能な URL が必要です。

手順 5：RunPod コンソールでエンドポイントを作成する

RunPod コンソール（runpod.io/console/serverless）にログインし、「+ New Endpoint」から設定します。主な設定項目は次の通りです。

設定項目	内容	備考
Endpoint Name	任意の名前	識別用。URL には影響しない
Container Image	`yourusername/my-runpod-handler:latest`	Docker Hub の Public イメージ URL
GPU Type	推論に合わせて選択	小モデルなら A4000（$0.58/hr）でも十分
Min Workers	0（推奨）	0 にするとアイドル中は無課金
Max Workers	1〜3 程度から始める	同時リクエスト数の上限
Idle Timeout	5〜30 秒	最後のリクエストから何秒で Worker を停止するか

「Deploy」を押すと数分でエンドポイントが起動します。エンドポイント ID（例：abc1234xyz）が発行されるので、API 呼び出しに使います。

API の呼び出し方

エンドポイントの URL は https://api.runpod.ai/v2/<endpoint_id>/run です。RunPod API キー（コンソールの Settings → API Keys で取得）を Bearer トークンとして渡します。

curl での呼び出し

ubuntu@linuxlab: ~

$ curl -X POST \
“https://api.runpod.ai/v2/<endpoint_id>/run” \
-H “Authorization: Bearer $RUNPOD_API_KEY” \
-H “Content-Type: application/json” \
-d ‘{“input”: {“prompt”: “こんにちは”}}’
{
“id”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”,
“status”: “IN_QUEUE”
}

/run は非同期エンドポイントで、まず IN_QUEUE が返ります。結果を取得するには /status/<job_id> を叩くか、/runsync（同期エンドポイント）を使います。

/runsync で同期的に結果を受け取る

ubuntu@linuxlab: ~

$ curl -X POST \
“https://api.runpod.ai/v2/<endpoint_id>/runsync” \
-H “Authorization: Bearer $RUNPOD_API_KEY” \
-H “Content-Type: application/json” \
-d ‘{“input”: {“prompt”: “こんにちは”}}’
{
“id”: “xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx”,
“status”: “COMPLETED”,
“output”: {“result”: “Echo: こんにちは”}
}

/runsync はリクエストが完了するまでコネクションを保持して結果を返します。処理が短い（〜30 秒以内）場合はこちらが使いやすいです。

Python SDK で呼ぶ

call_endpoint.py

import runpod

runpod.api_key = “YOUR_RUNPOD_API_KEY”
endpoint = runpod.Endpoint(“<endpoint_id>”)

run_request = endpoint.run_sync({“prompt”: “こんにちは”}, timeout=60)
print(run_request)
# {‘result’: ‘Echo: こんにちは’}

コールドスタートへの対処

Worker 最小数を 0 にしてコストを抑える場合、最初のリクエストが来たときに Worker が 0→1 に上がるまで待ち時間（コールドスタート）が発生します。モデルによっては 30 秒〜2 分かかります。

コールドスタートを短くしたいときの選択肢は次の 3 つです。

Min Workers を 1 以上にする：常に Worker が 1 台待機。コールドスタートなしだが、アイドル時も課金される
PRO Worker を選ぶ：専有リソースでコールドスタートが短い（ただし料金が高め）
イメージを軽くする：モデルをイメージに焼かず Network Storage に置くと起動が速くなる場合がある

実際に触ってみて驚いたのは、Serverless のエンドポイント URL が発行されるのに数分しかかからなかった点です。Docker イメージをプッシュして RunPod コンソールで登録するだけで、GPU の推論 API がすぐに立ち上がります。自分でロードバランサーやオートスケーラーを用意する手間が省けるのはやはり便利です。

よくある質問とエラー

Worker がいつまでも IN_QUEUE のまま

Docker イメージの Pull に時間がかかっているか、コンテナの起動直後にクラッシュしている可能性があります。RunPod コンソールの Logs タブで Worker のログを確認してください。ModuleNotFoundError や OOM（メモリ不足）が出ていることが多いです。

handler.py の runpod.serverless.start() を外すと動かない

ローカルテスト時に runpod.serverless.start() を呼ぶと RunPod のワーカーループに入るため、コンソールで止まります。ローカルテストはハンドラー関数を直接呼ぶか、RUNPOD_WEBHOOK_GET_JOB などの環境変数を設定してダミーのジョブを渡す方法を使います。