Sandbox configuration

これらの例では、CWSANDBOX_API_KEY に設定した CoreWeave API アクセストークンを使用します。Forge APIキーによる認証については、はじめにを参照してください。CKS の要件については、配置モードを参照してください。このガイドでは、リソース、マウントするファイル、ポート、アノテーション、タイムアウトなど、サンドボックスの設定オプションについて説明します。GPU キャパシティの確保、サービスの公開、操作のタイムアウト設定など、ワークロードの要件に合わせてサンドボックスのランタイム環境を調整する際のリファレンスとしてご活用ください。このページは、cwsandbox Python SDK を使用してサンドボックスを起動・管理する開発者を対象としています。

概要

サンドボックスの設定は、範囲が広い順から具体的な順に、以下の3か所で設定できます。

SandboxDefaults: セッション内のすべてのサンドボックスに対する共有デフォルト。
Sandbox.run() kwargs: サンドボックスごとのオーバーライド。
@session.function() kwargs: 関数固有の設定。

from cwsandbox import ResourceOptions, Sandbox, SandboxDefaults, Session

# SandboxDefaults を使用して
defaults = SandboxDefaults(
    container_image="python:3.11",
    max_lifetime_seconds=3600,
    resources=ResourceOptions(
        requests={"cpu": "2", "memory": "2Gi"},
        limits={"cpu": "2", "memory": "2Gi"},
    ),
)

# Sandbox.run() の kwargs を使用して
sandbox = Sandbox.run(
    defaults=defaults,
    resources=ResourceOptions(
        requests={"cpu": "4", "memory": "4Gi"},
        limits={"cpu": "4", "memory": "4Gi"},
    ),
)

# @session.function() の kwargs を使用して
with Session(defaults) as session:
    @session.function(resources={"cpu": "1", "memory": "1Gi"})
    def compute(x: int) -> int:
        return x * 2

以下のセクションでは、各設定領域について詳細に説明します。

リソース

ResourceOptions データクラスまたはプレーンな dict を使用して、CPU、メモリ、GPU のリソースを設定します。サーバーレスはデフォルトの配置モードで、リクエストと制限を等しく使用します。リクエストと制限が等しくない場合は、ポリシーが許可するランナーを使用した CKS 配置を使用します。以下のサンプルでは、リクエストと制限が等しいものを使用します：

from cwsandbox import ResourceOptions, Sandbox

# ResourceOptions を使用
sandbox = Sandbox.run(
    resources=ResourceOptions(
        requests={"cpu": "2", "memory": "2Gi"},
        limits={"cpu": "2", "memory": "2Gi"},
    ),
)

# dict を使用
sandbox = Sandbox.run(
    resources={
        "requests": {"cpu": "2", "memory": "2Gi"},
        "limits": {"cpu": "2", "memory": "2Gi"},
    },
)

両方の形式は同等です。SDK は内部で dict を ResourceOptions に自動的に変換します。 ResourceOptions はリソースリクエストと制限を分離します。リクエストは、サンドボックスが必要とするものをスケジューラーに伝えます。制限は、使用可能な最大値を設定します。Kubernetes がリクエストと制限を使用してサービス品質クラスを割り当てる方法の背景については、Kubernetes のドキュメントを参照してください。

ResourceOptions フィールド

フィールド	タイプ	説明
`requests`	`dict[str, str] \| None`	スケジューリングに使用する CPU とメモリのリクエスト (例: `{"cpu": "500m", "memory": "512Mi"}`) 。
`limits`	`dict[str, str] \| None`	サンドボックスが超えることのできない CPU とメモリの制限 (例: `{"cpu": "2", "memory": "2Gi"}`) 。
`gpu`	`dict[str, Any] \| None`	GPU の設定 (例: `{"count": 1, "type": "H100"}`) 。

クライアント側では、すべてのフィールドはオプションで、デフォルトは None です。最終的に決定される割り当ては、適用されるポリシーを満たす必要があります。リソース割り当てを省略した場合は、そのポリシーで定義された CPU とメモリのデフォルト値 (すべて指定済みで、かつ正の値) が、リクエストと制限の両方に使用されます。

Guaranteed QoS

リクエストが制限と等しい場合、サンドボックスには Guaranteed サービス品質クラスが割り当てられます。スケジューラーは割り当て全体を予約し、ノードのリソースが逼迫した場合でも、Kubernetes は Guaranteed の Pod を最後に退避させます。ただし、制限を超えて CPU を使用しようとするサンドボックスは、この場合でもスロットリングされます。レイテンシーに敏感なワークロードには、この設定を使用してください。

sandbox = Sandbox.run(
    resources=ResourceOptions(
        requests={"cpu": "2", "memory": "4Gi"},
        limits={"cpu": "2", "memory": "4Gi"},
    ),
)

Guaranteed QoS では、フラットな dict による省略記法を使用できます。SDK は、リクエストと制限の両方を同じ値に設定して、フラットな dict を正規化します。

# フラットな dict による省略記法: リクエストと制限は同じ値に設定されます
sandbox = Sandbox.run(
    resources={"cpu": "2", "memory": "4Gi"},
)

Burstable QoS

CKS ランナーのポリシーでリクエストと制限を不均等に設定できる場合、リクエストを低くするとサンドボックスに Burstable サービス品質クラスが割り当てられます。リクエストを低くするとスケジューラーがより多くのサンドボックスをビンパックできますが、各サンドボックスはキャパシティがあれば制限までバーストできます。独自のコンピュートを使用するの手順を完了し、CWSANDBOX_API_KEY に CoreWeave API アクセストークンを設定してください。[RUNNER-ID] は、リクエストと制限を許可するポリシーの CKS ランナーの ID に置き換えてください:

from cwsandbox import AuthStrategy, ResourceOptions, Sandbox

sandbox = Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_mode="cks",
    runner_ids=["[RUNNER-ID]"],
    resources=ResourceOptions(
        requests={"cpu": "500m", "memory": "512Mi"},
        limits={"cpu": "4", "memory": "4Gi"},
    ),
)

CPU の値

CPU はミリコア単位またはコア単位で指定します。詳細については、Resource units in Kubernetes を参照してください。

値	意味
`"100m"`	100 ミリコア (0.1 CPU)
`"500m"`	500 ミリコア (0.5 CPU)
`"1000m"` または `"1"`	1 CPU コア
`"2000m"` または `"2"`	2 CPU コア

メモリ値

メモリは標準の Kubernetes memory units を使用します：

値	意味
`"128Mi"`	128 メビバイト
`"512Mi"`	512 メビバイト
`"1Gi"`	1 ギビバイト
`"4Gi"`	4 ギビバイト

GPU

CPU とメモリに加えて GPU リソースをリクエストします。GPU のリクエストで確保されるのは GPU のみであるため、CPU とメモリは明示的に設定してください。

sandbox = Sandbox.run(
    resources=ResourceOptions(
        requests={"cpu": "4", "memory": "16Gi"},
        limits={"cpu": "4", "memory": "16Gi"},
        gpu={"count": 1},
    ),
)

GPU の設定キー:

キー	タイプ	説明
`count`	`int`	リクエストする GPU の数。
`type`	`str`	GPU のタイプ。ディスカバリーでランナーが提示するタイプと完全一致する必要があります。サーバーレスキャパシティでは GPU のタイプが自動的に割り当てられるため、設定しないでください。GPU サンドボックスを実行するを参照してください。
`memory_gb`	`int`	GPU メモリの最小容量 (GB) 。ランナー上で、この容量以上のメモリを持つ GPU のタイプが選択されます。複数のタイプが条件を満たす場合、どのタイプが選択されるかは未定義です。

type と memory_gb は代替となる設定です。設定するのはどちらか一方だけにしてください。

確定したリソースを確認する

サンドボックスの起動後、確定したリソース割り当てを確認します。この例では、CKS 上でリクエストと制限に異なる値を使用します。CKS のセットアップを完了し、CWSANDBOX_API_KEY に CoreWeave API アクセストークンを設定してください。[RUNNER-ID] は、GPU キャパシティがあり、これらのリソースを許可するポリシーが設定された CKS ランナーの ID に置き換えてください：

from cwsandbox import AuthStrategy, ResourceOptions, Sandbox

with Sandbox.run(
    auth=AuthStrategy.COREWEAVE_API_KEY,
    placement_mode="cks",
    runner_ids=["[RUNNER-ID]"],
    resources=ResourceOptions(
        requests={"cpu": "500m", "memory": "512Mi"},
        limits={"cpu": "2", "memory": "2Gi"},
        gpu={"count": 1},
    ),
) as sb:
    print(sb.resource_requests)  # {"cpu": "500m", "memory": "512Mi"}
    print(sb.resource_limits)    # {"cpu": "2", "memory": "2Gi"}
    print(sb.resource_gpu)       # {"count": 1}

設定ライブラリの相互運用

すべての設定タイプ (NetworkOptions, Secret, ResourceOptions) は、データクラスまたはプレーンな dict のいずれかを受け入れます。これにより、設定を dict または dict-like オブジェクトに解決する ML 設定ライブラリは、手動変換なしで SDK に値を直接渡すことができます。 SandboxDefaults.from_dict() はプレーンな dict または OmegaConf の DictConfig を受け入れ、ネストしたフィールドを自動的に強制変換します。dict は必要に応じて NetworkOptions、Secret、または ResourceOptions になり、lists は tuples になります。

# sandbox.yaml
container_image: "pytorch/pytorch:2.4.0-cuda12.4-cudnn9-runtime"
max_lifetime_seconds: 3600
tags:
  - training
  - experiment-42
resources:
  requests:
    cpu: "4"
    memory: "8Gi"
  limits:
    cpu: "4"
    memory: "8Gi"
  gpu:
    count: 1
network:
  egress_mode: "internet"
environment_variables:
  LOG_LEVEL: "info"

from omegaconf import OmegaConf
from cwsandbox import Sandbox, SandboxDefaults

cfg = OmegaConf.load("sandbox.yaml")
defaults = SandboxDefaults.from_dict(cfg)

with Sandbox.run(defaults=defaults) as sb:
    result = sb.exec(["python", "train.py"]).result()

個々のフィールドは、Sandbox.run() または session.sandbox() に直接渡す場合、dict も受け入れます。リソースのネストされた dict 形式は、ResourceOptions フィールドにマップされます。フラットな dict 形式 ({"cpu": "1", "memory": "1Gi"}) も受け入れられ、Guaranteed QoS として扱われます。

マウントされたファイル

マウントされたファイルを使用すると、設定ファイル、スクリプト、その他の読み取り専用アセットを、コンテナーイメージに組み込むことなく、起動時にサンドボックスへ提供できます。

sandbox = Sandbox.run(
    mounted_files=[
        {
            "path": "/app/config.json",
            "content": '{"debug": true}',
        },
        {
            "path": "/app/script.py",
            "content": "print('hello')",
        },
    ],
)

# ファイルはすぐに利用可能です
result = sandbox.exec(["python", "/app/script.py"]).result()

マウントオプション

フィールド	タイプ	説明
`path`	`str`	サンドボックス内の絶対パス。
`content`	`str`	ファイルの内容 (テキスト) 。

マウントされたファイルは読み取り専用です。変更が必要なファイルには write_file() を使用してください。

ポート

サンドボックス内のプロセスが外部クライアントにトラフィックを配信できるようにポートを公開します：

sandbox = Sandbox.run(
    "python", "-m", "http.server", "8080",
    ports=[
        {"container_port": 8080},
    ],
)

ポート設定

フィールド	タイプ	説明
`container_port`	`int`	サンドボックス内のポート。

ポートにプラットフォームの TLS または TLS パススルーを使用してインターネット到達可能なアドレスを付与するには、パブリックエンドポイントを参照してください。

ネットワーク

NetworkOptions データクラスまたはプレーンな dict を使用してネットワークのオプションを設定します：

from cwsandbox import NetworkOptions, Sandbox

# NetworkOptions を使用
sandbox = Sandbox.run(
    network=NetworkOptions(
        ingress_mode="public",
        exposed_ports=(8080,),
    ),
)

# dict を使用
sandbox = Sandbox.run(
    network={"ingress_mode": "public", "exposed_ports": [8080]},
)

両方の形式は同等です。SDK は内部で dict を NetworkOptions に自動的に変換します。

NetworkOptions のフィールド

フィールド	タイプ	説明
`ingress_mode`	`str \| None`	`"public"` (インターネットからアクセス可能) や `"internal"` (クラスター内のみ) など、受信トラフィックを制御します。
`exposed_ports`	`tuple[int, ...] \| None`	公開するポート (`ingress_mode` を指定する場合は必須) 。タプル `(8080,)` またはリスト `[8080]` として渡します。
`egress_mode`	`str \| None`	`"internet"` (アクセス制限なし) 、`"isolated"` (外部アクセスなし) 、`"org"` (組織内のみ) など、送信トラフィックを制御します。

すべてのフィールドは省略可能で、デフォルトは None です。この場合、バックエンドのデフォルトを使用します。

SandboxDefaults でネットワークを設定する

すべてのサンドボックスにデフォルトのネットワーク設定を指定します：

from cwsandbox import NetworkOptions, SandboxDefaults, Session

defaults = SandboxDefaults(
    network=NetworkOptions(egress_mode="internet"),
)

with Session(defaults) as session:
    # すべてのサンドボックスがネットワーク設定を継承します
    sb1 = session.sandbox()  # egress_mode="internet" を使用します
    sb2 = session.sandbox()  # egress_mode="internet" を使用します

    # 特定のサンドボックス用に上書きします
    sb3 = session.sandbox(network=NetworkOptions(egress_mode="user"))

アノテーション

サンドボックスに Kubernetes Pod のアノテーションを追加します。アノテーションは、基盤となる Pod に関連付けられるキーと値の文字列ペアです。スケジューラー、コスト配賦ツール、外部オートメーションなど、Pod のメタデータを読み取るインテグレーションに役立ちます。

sandbox = Sandbox.run(
    annotations={
        "team": "ml-infra",
        "experiment": "training-run-42",
    },
)

セッションレベルのデフォルト

セッション内のすべてのサンドボックスにデフォルトのアノテーションを設定します:

defaults = SandboxDefaults(
    annotations={
        "team": "ml-infra",
        "managed-by": "sandbox-sdk",
    },
)

with Session(defaults) as session:
    # デフォルトのアノテーションを継承します
    sb1 = session.sandbox()

    # マージ: キーが重複する場合、明示的なアノテーションがデフォルトを上書きします
    sb2 = session.sandbox(
        annotations={"experiment": "run-42", "team": "ml-research"},
    )
    # sb2 に設定される値: team=ml-research, managed-by=sandbox-sdk, experiment=run-42

マージの動作

SandboxDefaults.annotations とサンドボックスごとの annotations の両方を指定した場合、SDK はそれらをマージします。キーが競合した場合は、サンドボックスごとに明示的に指定した値が優先されます。これは environment_variables と同じセマンティクスです。

SUNK インテグレーション

SUNK インテグレーションで Slurm コンテキストを Pod アノテーションとして渡す方法については、SUNK Pod Scheduler インテグレーションガイドを参照してください。

検証

SDK はアノテーションのキーや値を検証しません。予約済みキーの接頭辞、値の形式、エントリ数の上限は、サーバー側で検証されます。

シークレット

Forge チームのシークレット注入、認証要件、および Python と TypeScript のサンプルについては、Forge シークレットの使用を参照してください。

タイムアウト

サンドボックスとその操作の実行時間は、4 つの設定で制御されます。名前が似ているため、各設定の制限対象を次の表にまとめます。

設定	制限対象	適用元	デフォルト
`max_lifetime_seconds`	自動終了されるまでのサンドボックスの合計有効期間	サーバー	ランナーポリシーのデフォルト値。未設定の場合は 10 分
`timeout_seconds`	`exec()`、`read_file()`、`write_file()` の 1 回の呼び出し	クライアント	`request_timeout_seconds` にフォールバック
`max_timeout_seconds`	サーバーがサンドボックスの配置を待機し、失敗と判定するまでの時間	サーバー	30 秒
`request_timeout_seconds`	ほとんどのリモートプロシージャ呼び出し (RPC) に対するクライアント側の HTTP タイムアウト	クライアント	300 秒

サンドボックスを終了させるのは max_lifetime_seconds のみです。他の 3 つは個々のリクエストを制限するだけで、サンドボックスは実行されたままです。

max_lifetime_seconds

max_lifetime_seconds はサンドボックスの総ウォールクロック有効期間を設定します。サンドボックスがこの有効期間に達すると、作業が進行中であっても、プラットフォームはそれを終了します。 max_lifetime_seconds を設定しない場合は、ランナーのポリシーのデフォルトが適用されます。ポリシーのデフォルトで正の値の有効期間が指定されていない場合、プラットフォームは 10 分を使用します。長時間実行する作業では、値を明示的に設定してください：

from cwsandbox import Sandbox

with Sandbox.run(max_lifetime_seconds=7200) as sandbox:  # 2時間
    sandbox.exec(["python", "train.py"], timeout_seconds=7000).result()

セッションが作成するすべてのサンドボックスに同じ有効期間を適用するには、SandboxDefaults で設定します：

from cwsandbox import Sandbox, SandboxDefaults

defaults = SandboxDefaults(
    container_image="python:3.11",
    max_lifetime_seconds=3600,  # 1 時間
)

with Sandbox.run(defaults=defaults) as sandbox:
    sandbox.exec(["python", "-c", "print('working')"]).result()

Sandbox.run() に明示的に指定した max_lifetime_seconds 引数は、defaults の値より優先されます。この引数のデフォルトは None なので、defaults で設定済みの有効期間をこの引数で削除することはできません。リクエストできる有効期間の上限は、サーバーレスと CKS のどちらの配置でも 30 日 (2,592,000 秒) です。プラットフォームは、それを超えるリクエストを拒否します。

サンドボックスの起動後に max_lifetime_seconds を変更することはできません。実行中のサンドボックスの有効期間を延長する API はないため、作成時に値を決めてください。上限を超えて作業を続けるには、必要なものを取得し、最大 30 日の有効期間で新しいサンドボックスを起動してください。

作成の例と CKS ランナーポリシーのデフォルトについては、長時間実行サンドボックスを実行するを参照してください。

有効期間が終了したときの動作

プラットフォームはサンドボックスの基盤となる Kubernetes ジョブを終了して有効期間を適用するため、猶予期間を設けずに即座に終了します。実際の運用では、次の 2 点に注意してください。

サンドボックス内のプロセスには、stop() が提供する猶予期間がありません。書き出されていないデータは失われます。
クライアントは、終了を示す一意のエラーや理由を受け取りません。SDK は Sandbox の終了理由を report しないため、有効期限切れとその他の障害をプログラムで区別できません。長期間稼働するサンドボックスの経過時間は、自分でトラッキングしてください。

有効期間は、想定する作業時間より十分に長く設定してください。また、有効期限切れに頼らず、作業が終わったらサンドボックスを明示的に停止してください。

timeout_seconds

timeout_seconds は、実行中のサンドボックスでの単一の操作に時間制限を設定します：

result = sandbox.exec(
    ["python", "long_script.py"],
    timeout_seconds=300,  # 5分
).result()

これは、クライアントが応答を待つ時間を制御します。待機時間がタイムアウトを超えると、SDK は SandboxTimeoutError を送出します。サンドボックスは実行を続けます。時間の計測はサンドボックスが RUNNING に達してから開始されるため、起動時間は含まれません。 timeout_seconds はサンドボックスの max_lifetime_seconds より小さい値にしてください。タイムアウトがサンドボックスの残りの有効期間を超えるコマンドは、サンドボックスの終了時に停止します。

max_timeout_seconds

max_timeout_seconds は、サンドボックスをランナーに配置する試みが失敗するまでに、サーバーが待機する時間の上限を設定します。これはサーバー側の配置の時間制限であり、クライアントの読み取りタイムアウトではありません。また、その後のサンドボックスの実行時間には影響しません:

sandbox = Sandbox.run(max_timeout_seconds=120)

サーバーは 1～300 秒の値を受け入れ、デフォルトは 30 秒です。サーバーは 300 を超える値を 300 に制限します。クラスターの負荷が高い状況でサンドボックスの起動に失敗する場合は、値を大きくしてください。max_timeout_seconds は Sandbox.run() と session.sandbox() で使用できますが、SandboxDefaults では使用できません。

request_timeout_seconds

request_timeout_seconds は、ほとんどの RPC に適用されるクライアント側の HTTP タイムアウトで、呼び出し時に独自の timeout_seconds が渡されない場合のフォールバックとして使用されます。SandboxDefaults で設定します。

defaults = SandboxDefaults(request_timeout_seconds=600.0)

ステータスのポーリングでは代わりに poll_rpc_timeout_seconds を使用するため、ポーリングが停止した場合、リクエストのタイムアウト時間全体にわたってブロックするのではなく、速やかに失敗します。クライアント側の調整オプションの一覧については、SandboxDefaults リファレンスを参照してください。

完全な設定例

次の例では、デフォルト、サンドボックスごとのオーバーライド、マウントされたファイル、ポートを、本番ワークロードの起動方法を想定した単一の設定にまとめています。

from cwsandbox import NetworkOptions, ResourceOptions, Sandbox, SandboxDefaults

defaults = SandboxDefaults(
    container_image="python:3.11",
    max_lifetime_seconds=1800,  # 30 分
    tags=("production", "ml-pipeline"),
    resources=ResourceOptions(
        requests={"cpu": "4", "memory": "8Gi"},
        limits={"cpu": "4", "memory": "8Gi"},
    ),
    network=NetworkOptions(egress_mode="internet"),
)

with Sandbox.run(
    defaults=defaults,
    mounted_files=[
        {
            "path": "/app/config.yaml",
            "content": "model: gpt-4\nmax_tokens: 1000",
        },
    ],
    ports=[
        {"container_port": 8000},
    ],
) as sandbox:
    # 依存関係をインストールします
    sandbox.exec(["pip", "install", "fastapi", "uvicorn"]).result()

    # アプリケーションを実行します
    result = sandbox.exec(
        ["python", "-c", "print('Server started')"],
        timeout_seconds=60,
    ).result()
    print(result.stdout)

サンドボックス

サンドボックスを使用する

サンドボックスの管理

リファレンス

概要

リソース

ResourceOptions フィールド

Guaranteed QoS

Burstable QoS

CPU の値

メモリ値

GPU

確定したリソースを確認する

設定ライブラリの相互運用

マウントされたファイル

マウントオプション

ポート

ポート設定

ネットワーク

NetworkOptions のフィールド

SandboxDefaults でネットワークを設定する

アノテーション

セッションレベルのデフォルト

マージの動作

SUNK インテグレーション

検証

シークレット

タイムアウト

max_lifetime_seconds

有効期間が終了したときの動作

timeout_seconds

max_timeout_seconds

request_timeout_seconds

完全な設定例

​概要

​リソース

​ResourceOptions フィールド

​Guaranteed QoS

​Burstable QoS

​CPU の値

​メモリ値

​GPU

​確定したリソースを確認する

​設定ライブラリの相互運用

​マウントされたファイル

​マウントオプション

​ポート

​ポート設定

​ネットワーク

​NetworkOptions のフィールド

​SandboxDefaults でネットワークを設定する

​アノテーション

​セッションレベルのデフォルト

​マージの動作

​SUNK インテグレーション

​検証

​シークレット

​タイムアウト

​max_lifetime_seconds

​有効期間が終了したときの動作

​timeout_seconds

​max_timeout_seconds

​request_timeout_seconds

​完全な設定例

概要

リソース

ResourceOptions フィールド

Guaranteed QoS

Burstable QoS

CPU の値

メモリ値

GPU

確定したリソースを確認する

設定ライブラリの相互運用

マウントされたファイル

マウントオプション

ポート

ポート設定

ネットワーク

NetworkOptions のフィールド

SandboxDefaults でネットワークを設定する

アノテーション

セッションレベルのデフォルト

マージの動作

SUNK インテグレーション

検証

シークレット

タイムアウト

max_lifetime_seconds

有効期間が終了したときの動作

timeout_seconds

max_timeout_seconds

request_timeout_seconds

完全な設定例