Runpod Flash

ローカルで書いたコードを flash run でテストし (localhost:8888 の開発サーバー)、flash が自動的にクラウド上のリモート GPU/CPU にプロビジョニングしてデプロイします。Endpoint がすべてを処理します。

セットアップ

pip install runpod-flash                 # requires Python >=3.10

# 認証オプション 1: ブラウザベースのログイン (トークンをローカルに保存)
flash login

# 認証オプション 2: 環境変数経由の API キー
export RUNPOD_API_KEY=your_key

flash init my-project                    # scaffold a new project in ./my-project

CLI

flash run                                # start local dev server at localhost:8888
flash run --auto-provision               # same, but pre-provision endpoints (no cold start)
flash build                              # package artifact for deployment (500MB limit)
flash build --exclude pkg1,pkg2          # exclude packages from build
flash deploy                             # build + deploy (auto-selects env if only one)
flash deploy --env staging               # build + deploy to "staging" environment
flash deploy --app my-app --env prod     # deploy a specific app to an environment
flash deploy --preview                   # build + launch local preview in Docker
flash env list                           # list deployment environments
flash env create staging                 # create "staging" environment
flash env get staging                    # show environment details + resources
flash env delete staging                 # delete environment + tear down resources
flash undeploy list                      # list all active endpoints
flash undeploy my-endpoint                # remove a specific endpoint

Endpoint: 3 つのモード

モード 1: あなたのコード (キューベースデコレータ)

1 つの関数 = 独自のワーカーを持つ 1 つのエンドポイント。

from runpod_flash import Endpoint, GpuGroup

@Endpoint(name="my-worker", gpu=GpuGroup.AMPERE_80, workers=5, dependencies=["torch"])
async def compute(data):
    import torch  # MUST import inside function (cloudpickle)
    return {"sum": torch.tensor(data, device="cuda").sum().item()}

result = await compute([1, 2, 3])

モード 2: あなたのコード (ロードバランスルート)

複数の HTTP ルートが 1 つのワーカープールを共有します。

from runpod_flash import Endpoint, GpuGroup

api = Endpoint(name="my-api", gpu=GpuGroup.ADA_24, workers=(1, 5), dependencies=["torch"])

@api.post("/predict")
async def predict(data: list[float]):
    import torch
    return {"result": torch.tensor(data, device="cuda").sum().item()}

@api.get("/health")
async def health():
    return {"status": "ok"}

モード 3: 外部イメージ (クライアント)

事前構築済みの Docker イメージをデプロイし、HTTP 経由で呼び出します。

from runpod_flash import Endpoint, GpuGroup, PodTemplate

server = Endpoint(
    name="my-server",
    image="my-org/my-image:latest",
    gpu=GpuGroup.AMPERE_80,
    workers=1,
    env={"HF_TOKEN": "xxx"},
    template=PodTemplate(containerDiskInGb=100),
)

# LB スタイル
result = await server.post("/v1/completions", {"prompt": "hello"})
models = await server.get("/v1/models")

# QB スタイル
job = await server.run({"prompt": "hello"})
await job.wait()
print(job.output)

既存のエンドポイントに ID で接続します (プロビジョニングなし):

ep = Endpoint(id="abc123")
job = await ep.runsync({"input": "hello"})
print(job.output)

モードの決定方法

パラメータ	モード
name= のみ	デコレータ (あなたのコード)
image= 設定	クライアント (イメージをデプロイして HTTP 呼び出し)
id= 設定	クライアント (既存に接続、プロビジョニングなし)

Endpoint コンストラクタ

Endpoint(
    name="endpoint-name",                  # required (unless id= set)
    id=None,                               # connect to existing endpoint
    gpu=GpuGroup.AMPERE_80,               # single GPU type (default: ANY)
    gpu=[GpuGroup.ADA_24, GpuGroup.AMPERE_80],  # or list for auto-select by supply
    cpu=CpuInstanceType.CPU5C_4_8,        # CPU type (mutually exclusive with gpu)
    workers=5,                             # shorthand for (0, 5)
    workers=(1, 5),                        # explicit (min, max)
    idle_timeout=60,                       # seconds before scale-down (default: 60)
    dependencies=["torch"],                # pip packages for remote exec
    system_dependencies=["ffmpeg"],        # apt-get packages
    image="org/image:tag",                 # pre-built Docker image (client mode)
    env={"KEY": "val"},                    # environment variables
    volume=NetworkVolume(...),             # persistent storage
    gpu_count=1,                           # GPUs per worker
    template=PodTemplate(containerDiskInGb=100),
    flashboot=True,                        # fast cold starts
    execution_timeout_ms=0,                # max execution time (0 = unlimited)
)

• gpu= と cpu= は相互排他的です
• workers=5 は (0, 5) を意味します。デフォルトは (0, 1) です
• idle_timeout のデフォルトは 60 秒です
• flashboot=True (デフォルト) -- スナップショット復元による高速コールドスタートを有効にします
• gpu_count -- ワーカーあたりの GPU 数 (デフォルト 1)、マルチ GPU モデルには >1 を使用します

NetworkVolume

NetworkVolume(name="my-vol", size=100)  # size in GB, default 100

PodTemplate

PodTemplate(
    containerDiskInGb=64,    # container disk size (default 64)
    dockerArgs="",           # extra docker arguments
    ports="",                # exposed ports
    startScript="",          # script to run on start
)

EndpointJob

クライアントモードで ep.run() と ep.runsync() から返されます。

job = await ep.run({"data": [1, 2, 3]})
await job.wait(timeout=120)        # poll until done
print(job.id, job.output, job.error, job.done)
await job.cancel()

GPU タイプ (GpuGroup)

Enum	GPU	VRAM
ANY	any	varies
AMPERE_16	RTX A4000	16GB
AMPERE_24	RTX A5000/L4	24GB
AMPERE_48	A40/A6000	48GB
AMPERE_80	A100	80GB
ADA_24	RTX 4090	24GB
ADA_32_PRO	RTX 5090	32GB
ADA_48_PRO	RTX 6000 Ada	48GB
ADA_80_PRO	H100 PCIe (80GB) / H100 HBM3 (80GB) / H100 NVL (94GB)	80GB+
HOPPER_141	H200	141GB

CPU タイプ (CpuInstanceType)

Enum	vCPU	RAM	最大ディスク	タイプ
CPU3G_1_4	1	4GB	10GB	General
CPU3G_2_8	2	8GB	20GB	General
CPU3G_4_16	4	16GB	40GB	General
CPU3G_8_32	8	32GB	80GB	General
CPU3C_1_2	1	2GB	10GB	Compute
CPU3C_2_4	2	4GB	20GB	Compute
CPU3C_4_8	4	8GB	40GB	Compute
CPU3C_8_16	8	16GB	80GB	Compute
CPU5C_1_2	1	2GB	15GB	Compute (5th gen)
CPU5C_2_4	2	4GB	30GB	Compute (5th gen)
CPU5C_4_8	4	8GB	60GB	Compute (5th gen)
CPU5C_8_16	8	16GB	120GB	Compute (5th gen)

from runpod_flash import Endpoint, CpuInstanceType

@Endpoint(name="cpu-work", cpu=CpuInstanceType.CPU5C_4_8, workers=5, dependencies=["pandas"])
async def process(data):
    import pandas as pd
    return pd.DataFrame(data).describe().to_dict()

一般的なパターン

CPU + GPU パイプライン

from runpod_flash import Endpoint, GpuGroup, CpuInstanceType

@Endpoint(name="preprocess", cpu=CpuInstanceType.CPU5C_4_8, workers=5, dependencies=["pandas"])
async def preprocess(raw):
    import pandas as pd
    return pd.DataFrame(raw).to_dict("records")

@Endpoint(name="infer", gpu=GpuGroup.AMPERE_80, workers=5, dependencies=["torch"])
async def infer(clean):
    import torch
    t = torch.tensor([[v for v in r.values()] for r in clean], device="cuda")
    return {"predictions": t.mean(dim=1).tolist()}

async def pipeline(data):
    return await infer(await preprocess(data))

並列実行

import asyncio
results = await asyncio.gather(compute(a), compute(b), compute(c))

注意点

1. 関数外のインポート -- 最も一般的なエラー。デコレータされた関数内にすべてを配置します。
2. await の忘却 -- すべてのデコレータされた関数とクライアントメソッドは await が必要です。
3. 依存関係の欠落 -- dependencies=[] にリストする必要があります。
4. gpu/cpu は排他的 -- Endpoint ごとに 1 つを選択します。
5. idle_timeout は秒 -- デフォルト 60 秒、分ではありません。
6. 10MB ペイロード上限 -- 大きなオブジェクトではなく URL を渡します。
7. クライアント vs デコレータ -- image=/id= = クライアント。そうでなければ = デコレータ。
8. 自動 GPU 切り替えには workers >= 5 が必要 -- GPU タイプのリストを渡し (例: gpu=[GpuGroup.ADA_24, GpuGroup.AMPERE_80]) 、workers=5 以上に設定します。プラットフォームは最大ワーカーが 5 以上の場合にのみ供給に基づいて自動的に GPU タイプを切り替えます。
9. runsync のタイムアウトは 60 秒 -- コールドスタートは 60 秒を超える可能性があります。最初のリクエストには ep.runsync(data, timeout=120) を使用するか、ep.run() + job.wait() を代わりに使用します。