Sandbox configuration

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

認証を選択する

CKS が指定されているセクションを除き、これらの例はサーバーレスキャパシティ上で実行されます。サンドボックスを所有するアカウントの認証情報を選択してください。キーまたはトークンの取得方法については、認証情報の選択と取得を参照してください。インストールコマンドは、有効化した Python 仮想環境で実行してください。使用する認証情報のタブにある Python コードを sandbox_auth.py として保存し、このページで実行する Python スクリプトと同じディレクトリに配置します。このファイルに保存されるのは認証方式の選択内容のみで、認証情報そのものは含まれません。各例ではこのファイルから AUTH をインポートし、新しいサンドボックスまたは Session を作成するたびに明示的に渡します。

Forge API キー
CoreWeave API アクセストークン

SDK の W&B 認証方式を介して Forge のAPIキーを使用します。

uv pip install 'cwsandbox[wandb]>=1.14.2'
export WANDB_API_KEY="[WANDB-API-KEY]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

CoreWeave 組織のトークンを使用します。

uv pip install 'cwsandbox>=1.14.2'
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

CKS に配置する場合は、CoreWeave のトークンを選択してランナーを有効化し、サンドボックスの作成時または SandboxDefaults で placement_mode="cks" を設定します。auth=AUTH を指定して Session を作成すると、その Session が所有するサンドボックスも認証されます。サンドボックスへの再接続、一覧表示、クリーンアップを行う際も、同じ認証情報を使用してください。

概要

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

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

from sandbox_auth import AUTH
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"},
    ),
    auth=AUTH,
)

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

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

リソース

ResourceOptions データクラスまたはプレーンな dict を使用して、CPU、メモリ、GPU のリソースを設定します。サーバーレスはデフォルトの配置モードです。サーバーレスのサンドボックスでは、CPU とメモリのリクエストと制限を同じ値に設定してください。リクエストと制限が等しくない場合は、ポリシーが許可するランナーを使用した CKS 配置を使用します。値の選び方については、サンドボックスの CPU とメモリのサイジングを参照してください。異なる値がサーバーレス側で自動的に揃えられることを前提にしないでください。リクエストと制限が異なる状態でサンドボックスを作成できたとしても、リソースのバーストがサポートされているわけではありません。以下のサンプルでは、リクエストと制限が等しいものを使用します：

from sandbox_auth import AUTH
from cwsandbox import ResourceOptions, Sandbox

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

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

両方の形式は同等です。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 サービス品質になるかどうかは、Pod 内のすべてのコンテナーのリソースによって決まります。コンテナー単位の割り当てでは、各コンテナーで CPU とメモリのリクエストに正の値を設定し、それぞれのリソースにリクエストと一致する制限を設定する必要があります。これには init コンテナーとサイドカーも含まれます。ワークロードのコンテナーだけで値を揃えても、サンドボックスの Pod 全体の QoS クラスは決まりません。ただし、制限を超えて CPU を使用しようとするサンドボックスは、この場合でもスロットリングされます。

from sandbox_auth import AUTH
from cwsandbox import ResourceOptions, Sandbox

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

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

from sandbox_auth import AUTH
from cwsandbox import Sandbox

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

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 とメモリは明示的に設定してください。

from sandbox_auth import AUTH
from cwsandbox import ResourceOptions, Sandbox

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

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 を受け入れ、ネストしたフィールドを自動的に強制変換します。ネットワークとシークレットの設定は対応する SDK のタイプに、リソースのマッピングはプレーンな dict に変換されます。SDK はサンドボックスの構築時に、これらのリソースの dict を ResourceOptions に正規化します。

# sandbox.yaml
container_image: "pytorch/pytorch:2.8.0-cuda12.8-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:
    - dns_name: "pypi.org"
    - dns_name: "files.pythonhosted.org"
environment_variables:
  LOG_LEVEL: "info"

from sandbox_auth import AUTH
from omegaconf import OmegaConf
from cwsandbox import Sandbox, SandboxDefaults

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

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

個々のフィールドは、Sandbox.run() または session.sandbox() に直接渡す場合、dict も受け入れます。リソースのネストされた dict 形式は、ResourceOptions フィールドにマップされます。フラットな dict 形式 ({"cpu": "1", "memory": "1Gi"}) を使用すると、ワークロードコンテナーの CPU とメモリのリクエストおよび制限が同じ値に設定されます。ただし、Guaranteed QoS の要件は引き続き Pod 内のすべてのコンテナーに適用されます。

マウントされたファイル

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

from sandbox_auth import AUTH
from cwsandbox import Sandbox

sandbox = Sandbox.run(
    mounted_files=[
        {
            "mount_path": "/app/config.json",
            "file_content": b'{"debug": true}',
        },
        {
            "mount_path": "/app/script.py",
            "file_content": b"print('hello')",
        },
    ],
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
)

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

マウントオプション

フィールド	タイプ	説明
`mount_path`	`str`	サンドボックス内の絶対パス。
`file_content`	`bytes \| str`	ファイルの内容。文字列は UTF-8 でエンコードされます。

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

ポート

ポートは services=[Service(...)] で宣言します。Service(port=8080, name="web") のように visibility と endpoint のどちらも設定しない宣言はコンテナー内でのみ有効で、外部への公開はリクエストされません。インターネット上のクライアントに HTTP を提供するには、パブリックな HTTPS エンドポイントをリクエストします。この例では、サーバーレスキャパシティ上でポート 8080 の HTTP サーバーを起動し、割り当て済みの HTTPS URL にローカルマシンからリクエストを送信します。TLS はプラットフォームで終端され、HTTP がコンテナーのポートに転送されます。この例では EndpointAuth.OPEN を使用するため、URL を知っていれば誰でも認証情報なしでアクセスできます。また、デモ用コンテナーの /tmp ディレクトリをドキュメントルートとして使用します。auth=AUTH で使用する認証情報は、サンドボックスの作成と削除を承認するためのものであり、この OPEN エンドポイントへのリクエストには必須ではありません。

import time
from urllib.error import URLError
from urllib.request import urlopen

from sandbox_auth import AUTH
from cwsandbox import (
    Endpoint,
    EndpointAuth,
    EndpointKind,
    Sandbox,
    Service,
    ServiceProtocol,
    ServiceVisibility,
)

sandbox = Sandbox.run(
    "python", "-m", "http.server", "8080", "--directory", "/tmp",
    container_image="python:3.11",
    placement_mode="serverless",
    services=[
        Service(
            port=8080,
            name="web",
            protocol=ServiceProtocol.TCP,
            visibility=ServiceVisibility.PUBLIC,
            endpoint=Endpoint(kind=EndpointKind.HTTPS, auth=EndpointAuth.OPEN),
        ),
    ],
    resources={"cpu": "1", "memory": "1Gi"},
    max_lifetime_seconds=300,
    auth=AUTH,
)

try:
    deadline = time.monotonic() + 120
    while time.monotonic() < deadline:
        sandbox.get_status()
        if sandbox.service_urls:
            url = sandbox.service_urls[0][2]
            try:
                with urlopen(url, timeout=10) as response:
                    body = response.read().decode("utf-8")
                    assert response.status == 200
                    assert "Directory listing for /" in body
                    print("HTTP 200: directory listing received")
                    break
            except (URLError, TimeoutError):
                pass  # アプリケーションの準備が完了する前に URL が取得できる場合があります。
        time.sleep(2)
    else:
        raise TimeoutError("The HTTPS service did not become reachable")
finally:
    Sandbox.delete(sandbox.sandbox_id, auth=AUTH).result()

このスクリプトは、URL と HTTP サーバーが準備完了になるまで再試行し、成功すると HTTP 200: directory listing received を出力します。アクセスを試行した後は、サンドボックスを削除します。また、5 分間の有効期間により、スクリプトの最大実行時間も制限されます。 ports パラメーターは cwsandbox 1.x で削除されました。値を渡すと TypeError が送出されます。代わりに services=[Service(...)] を使用してください。

Service のフィールド

フィールド	タイプ	説明
`port`	`int`	サンドボックス内でワークロードがリッスンするポート。
`name`	`str \| None`	省略可能なサービス名。サンドボックス内で一意である必要があります。
`protocol`	`ServiceProtocol \| str \| None`	レイヤー 4 プロトコル。デフォルトは TCP です。`endpoint` を設定する場合は、TCP にするか未設定のままにする必要があります。
`visibility`	`ServiceVisibility \| str \| None`	到達可能性の設定。`endpoint` を設定する場合は `PUBLIC` にする必要があります。通常のサービスでは `PRIVATE`、`PUBLIC`、`CUSTOM` も使用できます。その場合の到達可能性はデプロイメントによって異なります。
`endpoint`	`Endpoint \| dict \| None`	省略可能なパブリック HTTPS または TLS パススルーのエンドポイント。可視性を設定するだけでは、HTTPS URL や TLS パススルーのアドレスは発行されません。

sandbox.service_urls の各エントリは (port, name, url) 形式のタプルです。URL は、サンドボックスがまだ CREATING 状態のうちに表示される場合があります。URL が割り当て済みでも、アプリケーションがリッスンしているとは限りません。通常のサービスとは、endpoint の値を持たないサービスです。1 つのサンドボックス内で通常のサービスとエンドポイントを併用する際のルールについては、エンドポイントを宣言するを参照してください。 HTTPS の場合、EndpointAuth.OPEN では認証なしでアクセスできます。EndpointAuth.SHARE_TOKEN を使用するには、作成時に返される共有トークン、Python SDK 1.16.0 以降、および共有トークン方式の HTTPS をサポートするデプロイメントが必要です。TLS パススルーではエンドポイントの認証は設定されず、TLS 終端とアクセス制御はワークロード側で行います。エンドポイントのルーティングと認証については、パブリックエンドポイントを参照してください。自動生成された Service リファレンスと Endpoint リファレンスは SDK バージョン 1.14.2 を対象としています。このバージョンは OPEN をサポートしていますが、SHARE_TOKEN には対応していません。

ネットワーク

外向きおよび内向きのトラフィックは、NetworkOptions データクラスまたはプレーンな dict を使用して設定します。外向き通信とイングレスのルールは、デフォルトですべて拒否されるベースラインに対してアクセスを許可します。空でない egress リストを指定すると、ランナーのポリシーで定められたデフォルトの送信先グラントが置き換えられます。ホスト名によるグラントを使用するには、ホスト名ベースの HTTPS 外向き通信をサポートするランナーと、要求するすべての送信先を許可するポリシーが必要です。CKS に配置する場合は、ランナーのネットワーク制約を確認するよう管理者に依頼してください。サーバーレスで配置する場合は、CoreWeave がプールとそのポリシーを管理します。プールがこれらのホスト名ルールを拒否する場合は、CoreWeave Support にお問い合わせください。 PyPI からパッケージをダウンロードするには、パッケージインデックス用の pypi.org と、パッケージファイル用の files.pythonhosted.org の両方を許可してください。pypi.org および *.pypi.org のグラントには files.pythonhosted.org は含まれません。

from sandbox_auth import AUTH
from cwsandbox import EgressRule, NetworkOptions, Sandbox

# NetworkOptions を使用する場合
sandbox = Sandbox.run(
    network=NetworkOptions(
        egress=[
            EgressRule(dns_name="pypi.org"),
            EgressRule(dns_name="*.pypi.org"),
            EgressRule(dns_name="files.pythonhosted.org"),
        ],
    ),
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
)

# dict を使用する場合
sandbox = Sandbox.run(
    network={
        "egress": [
            {"dns_name": "pypi.org"},
            {"dns_name": "*.pypi.org"},
            {"dns_name": "files.pythonhosted.org"},
        ],
    },
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
)

どちらの形式も同等です。SDK が内部で dict を NetworkOptions に自動変換します。

NetworkOptions のフィールド

フィールド	タイプ	説明
`deny_egress`	`bool \| None`	`True` の場合、デフォルトの外向き通信の送信先グラントと、宣言済みの外向き通信の送信先グラントを無効にします。DNS アクセスは個別に制御され、ポリシーで DNS が拒否されていない限り、引き続き許可されます。空でない `egress` リストとは併用できません。空のリストであれば指定できます。
`deny_ingress`	`bool \| None`	`True` の場合、`CUSTOM` サービスへの宣言済みのイングレスと、ポリシーのデフォルトのイングレスを拒否します。空でない `ingress` リストとは併用しないでください。
`egress`	`Sequence[EgressRule \| dict] \| None`	外向き通信のグラント。DNS 名を指定した場合、許可されるのは HTTPS (TCP 443) のみです。
`ingress`	`Sequence[IngressRule \| dict] \| None`	可視性が `CUSTOM` のポートに対するイングレスのソース。

すべてのフィールドは省略可能で、デフォルトは None です。ルールリストが空で、対応する deny フラグが未設定または False の場合は、ランナーのポリシーのデフォルトが適用されます。ポートを公開するには、NetworkOptions ではなく services を使用します。EgressRule と IngressRule の全フィールドについては、ネットワークルールを参照してください。 EgressRule では、dns_name、cidr、tenant、any、selector のいずれか 1 つだけを送信先として指定する必要があります。DNS グラントには、完全一致の名前、または *.pypi.org のように左端に 1 つだけワイルドカードを含む名前を指定できます。IngressRule では、cidr、tenant、any のいずれか 1 つだけをソースとして指定する必要があります。 egress_mode、ingress_mode、exposed_ports フィールドは cwsandbox 1.x ではサポートされていません。上記のフィールドを使用し、ポートは services で宣言してください。 deny_egress=True を指定しても、ネットワークが完全に分離されるわけではありません。プラットフォームに必要なトラフィックは引き続き許可される場合があり、外向きの DNS は個別に制御されます。Python の NetworkOptions タイプでは dnsEgress を指定できません。このモードを変更するには、NetworkConfig API を使用してください (サポートされている場合)。

Python SDK はサンドボックスの作成時にネットワークオプションを適用します。実行中のサンドボックスのネットワークポリシーを更新するメソッドは提供されていません。API を使用するワークフローについては、動的ネットワークポリシーを参照してください。公開ポートとサービスの可視性は、引き続き作成時にのみ設定できます。

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

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

from sandbox_auth import AUTH
from cwsandbox import EgressRule, NetworkOptions, SandboxDefaults, Session

defaults = SandboxDefaults(
    network=NetworkOptions(
        egress=[
            EgressRule(dns_name="pypi.org"),
            EgressRule(dns_name="files.pythonhosted.org"),
        ],
    ),
    resources={"cpu": "1", "memory": "1Gi"},
)

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

    # このサンドボックスでは送信先へのグラントを無効にします。DNS は別途制御されます
    sb3 = session.sandbox(network=NetworkOptions(deny_egress=True))

サンドボックスごとに指定した network は、SandboxDefaults.network の値とマージされず、その値を置き換えます。上記の例では、sb3 で送信先へのグラントを無効にしていますが、DNS は引き続き別途制御されます。

アノテーション

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

from sandbox_auth import AUTH
from cwsandbox import Sandbox

sandbox = Sandbox.run(
    annotations={
        "team": "ml-infra",
        "experiment": "training-run-42",
    },
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
)

Sessionレベルのデフォルト

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

from sandbox_auth import AUTH
from cwsandbox import SandboxDefaults, Session

defaults = SandboxDefaults(
    annotations={
        "team": "ml-infra",
        "managed-by": "sandbox-sdk",
    },
    resources={"cpu": "1", "memory": "1Gi"},
)

with Session(defaults, auth=AUTH) 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 シークレットの使用を参照してください。

タイムアウト

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

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

サンドボックスを終了させるのは max_lifetime_seconds のみです。他の 2 つは個々のリクエストを制限するだけで、サンドボックスは実行されたままです。 max_timeout_seconds パラメーターは cwsandbox 1.x で削除されました。値を渡すと TypeError が送出されます。クライアントのリクエストタイムアウトを指定するには、request_timeout_seconds を使用してください。

max_lifetime_seconds

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

from sandbox_auth import AUTH
from cwsandbox import Sandbox

with Sandbox.run(
    max_lifetime_seconds=7200,  # 2時間
    resources={"cpu": "1", "memory": "1Gi"},
    auth=AUTH,
) as sandbox:
    sandbox.exec(["python", "train.py"], timeout_seconds=7000).result()

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

from sandbox_auth import AUTH
from cwsandbox import Sandbox, SandboxDefaults

defaults = SandboxDefaults(
    container_image="python:3.11",
    max_lifetime_seconds=3600,  # 1 時間
    resources={"cpu": "1", "memory": "1Gi"},
)

with Sandbox.run(defaults=defaults, auth=AUTH) 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 Job に期限を設定することで有効期間を強制します。期限に達すると、処理が進行中であってもワークロードが終了されます。有効期限切れになる前に、結果やチェックポイントをサンドボックスの外部に保存してください。 Python SDK では、バックエンドから報告された理由を Sandbox.status_reason で参照できます。この値は、最新の API 応答からキャッシュされたものです。有効期間の有効期限切れは、DeadlineExceeded で始まる理由として表示される場合があります。SDK が SandboxFailedError を送出した場合も、その status_reason 属性にバックエンドから報告された理由が格納されます。理由が存在しない場合もあるため、長時間稼働するサンドボックスについては経過時間もあわせてトラッキングしてください。有効期間は、想定される処理時間を十分に上回る値に設定してください。処理が終了したら、有効期限切れに任せるのではなく、サンドボックスを明示的に停止してください。

timeout_seconds

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

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

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

request_timeout_seconds

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

from cwsandbox import SandboxDefaults

defaults = SandboxDefaults(
    request_timeout_seconds=600.0,
    resources={"cpu": "1", "memory": "1Gi"},
)

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

完全な設定例

次の例では、デフォルト、サンドボックスごとのオーバーライド、マウントされたファイル、サービスの宣言を組み合わせています。PyPI からパッケージをダウンロードし、インポートしてインストールを確認します。サーバーレスプールは、ホスト名のグラント要件を満たしている必要があります。この例ではサービスのポートを宣言しますが、サーバーの起動やパブリックエンドポイントの作成は行いません。

from sandbox_auth import AUTH
from cwsandbox import (
    EgressRule,
    NetworkOptions,
    ResourceOptions,
    Sandbox,
    SandboxDefaults,
    Service,
)

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=[
            EgressRule(dns_name="pypi.org"),
            EgressRule(dns_name="*.pypi.org"),
            EgressRule(dns_name="files.pythonhosted.org"),
        ],
    ),
)

with Sandbox.run(
    defaults=defaults,
    mounted_files=[
        {
            "mount_path": "/app/config.yaml",
            "file_content": b"model: gpt-4\nmax_tokens: 1000",
        },
    ],
    services=[
        Service(port=8000, name="api"),
    ],
    auth=AUTH,
) as sandbox:
    # キャッシュを使わずにダウンロードして依存関係をインストールします
    sandbox.exec(
        ["pip", "install", "--no-cache-dir", "fastapi", "uvicorn"],
        check=True,
    ).result()

    # インストールした依存関係を検証します
    result = sandbox.exec(
        ["python", "-c", "import fastapi, uvicorn; print('Dependencies imported')"],
        check=True,
        timeout_seconds=60,
    ).result()
    print(result.stdout)

サンドボックス

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

サンドボックスの管理

リファレンス

認証を選択する

概要

リソース

ResourceOptions フィールド

Guaranteed QoS

Burstable QoS

CPU の値

メモリ値

GPU

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

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

マウントされたファイル

マウントオプション

ポート

Service のフィールド

ネットワーク

NetworkOptions のフィールド

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

アノテーション

Sessionレベルのデフォルト

マージの動作

SUNK インテグレーション

検証

シークレット

タイムアウト

max_lifetime_seconds

有効期間が切れたときの動作

timeout_seconds

request_timeout_seconds

完全な設定例

​認証を選択する

​概要

​リソース

​ResourceOptions フィールド

​Guaranteed QoS

​Burstable QoS

​CPU の値

​メモリ値

​GPU

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

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

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

​マウントオプション

​ポート

​Service のフィールド

​ネットワーク

​NetworkOptions のフィールド

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

​アノテーション

​Sessionレベルのデフォルト

​マージの動作

​SUNK インテグレーション

​検証

​シークレット

​タイムアウト

​max_lifetime_seconds

​有効期間が切れたときの動作

​timeout_seconds

​request_timeout_seconds

​完全な設定例

認証を選択する

概要

リソース

ResourceOptions フィールド

Guaranteed QoS

Burstable QoS

CPU の値

メモリ値

GPU

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

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

マウントされたファイル

マウントオプション

ポート

Service のフィールド

ネットワーク

NetworkOptions のフィールド

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

アノテーション

Sessionレベルのデフォルト

マージの動作

SUNK インテグレーション

検証

シークレット

タイムアウト

max_lifetime_seconds

有効期間が切れたときの動作

timeout_seconds

request_timeout_seconds

完全な設定例