Session

class Session(defaults: SandboxDefaults | Mapping[str, Any] | None = None, report_to: list[str] | None = None, *, auth: AuthConfig | None = None)

• 共通の設定で複数のサンドボックスを作成する場合
• サンドボックスで Python 関数を実行する場合
• 孤立したサンドボックスを自動的にクリーンアップしたい場合

​

プロパティ

​

sandbox_count

@property
def sandbox_count(self) -> int

​

メソッド

​

log_metrics

log_metrics(step: int | None = None, *, reset: bool = True) -> bool

• step (int | None): メトリクスに関連付けるトレーニングステップ。指定した場合、メトリクスは wandb 上でこのステップ番号にログされます。
• reset (bool): True (デフォルト) の場合、ログに成功した後、蓄積されたメトリクスをリセットします。log() が失敗した場合 (実行中の wandb run がない場合) は、メトリクスは保持されます。False に設定すると、ログの成否にかかわらず蓄積を継続します。

• bool: メトリクスがログされた場合は True、レポーターが設定されていない場合は False
• bool: または実行中の wandb run がない場合。

with Session(defaults, report_to=["wandb"]) as session:
    for step in range(100):
        sb = session.sandbox(...)
        result = sb.exec(...).result()  # メトリクスを自動的に追跡します
        session.log_metrics(step=step)  # 各 step でログします

​

get_metrics

get_metrics() -> dict[str, Any]

• dict[str, Any]: cwsandbox/* 接頭辞付きのメトリクス名と値を含む辞書。
• dict[str, Any]: レポーター が設定されていない場合は空の dict。

​

close

close() -> OperationRef[None]

• OperationRef[None]: OperationRef[None]: .result() を使用すると、すべてのサンドボックスが停止するまでブロックします。

• SandboxError: 実行中のサンドボックスが 1 つ以上停止に失敗した場合。

session.close().result()  # すべてのサンドボックスが停止するまで待機します

​

sandbox

sandbox(*, command: str | None = None, args: list[str] | None = None, container_image: str | None = None, tags: list[str] | None = None, runner_ids: list[str] | None = None, resources: ResourceOptions | dict[str, Any] | None = None, mounted_files: list[dict[str, Any]] | None = None, network: NetworkOptions | dict[str, Any] | None = None, services: list[Service] | tuple[Service, ...] | None = None, volumes: list[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any]] | tuple[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any], ...] | None = None, file_system_snapshot: FileSystemSnapshotOptions | dict[str, Any] | None = None, placement_mode: PlacementMode | str | None = None, placement_spillover: PlacementSpillover | str | None = None, template_id: str | None = None, image_pull_credentials: ImagePullCredentials | dict[str, Any] | None = None, runtime_class: str | None = None, security_context: SecurityContext | dict[str, Any] | None = None, working_dir: str | None = None, object_storage_access: ObjectStorageAccess | dict[str, Any] | None = None, environment_variables: dict[str, str] | None = None, annotations: dict[str, str] | None = None, secrets: Sequence[Secret | dict[str, Any]] | None = None, request_timeout_seconds: float | None = None, data_plane_mode: DataPlaneMode | str | None = None, auth: AuthConfig | None = None, containers: Sequence[Container | Mapping[str, Any]] | None = None, **kwargs: Any = {}) -> Sandbox

• command (str | None): サンドボックスで実行するコマンド
• args (list[str] | None): コマンドの引数
• container_image (str | None): 使用するコンテナーイメージ
• tags (list[str] | None): サンドボックスのタグ (template_id が設定されている場合もセッションのデフォルトとマージされ、list()/adopt でサンドボックスを検索できます) 。テンプレートを使用する場合 (テンプレートが所有する spec) 、環境変数とアノテーションはマージされません。
• profile_ids: 1.x で削除されました。値を渡すと TypeError が送出されます。
• profile_names: 1.x で削除されました。値を渡すと TypeError が送出されます。
• runner_ids (list[str] | None): オプションの CKS ランナー固定指定 (サーバーレスおよび placement_spillover='serverless_then_cks' とは併用できません)
• resources (ResourceOptions | dict[str, Any] | None): リソース設定。リクエストと制限を個別に指定する ResourceOptions、または後方互換性のある Guaranteed QoS 用のフラットな dict を受け入れます。
• mounted_files (list[dict[str, Any]] | None): 起動時にサンドボックスにマウントするファイル。各 dict には mount_path (str) と file_content (bytes) が必要です。注: マウントされたファイルは実行時に読み取り専用です。ファイルを変更するには、サンドボックスの実行開始後に sandbox.write_file() を使用します。
• s3_mount: 1.x で削除されました。値を渡すと TypeError が送出されます。
• ports: 1.x で削除されました。代わりに services=[Service(...)] を使用します。
• network (NetworkOptions | dict[str, Any] | None): 拒否フラグと、作成時に指定するオプションのホスト名グラントを含む NetworkOptions (または dict) 。ポートの公開には services= を使用します。
• file_system_snapshot (FileSystemSnapshotOptions | dict[str, Any] | None): 単一マウントを簡便に指定する FSS オプション (FileSystemSnapshotOptions または dict) 。複数ボリュームの構成には volumes= を推奨します。
• max_timeout_seconds: 1.x で削除されました。request_timeout_seconds を使用します。
• request_timeout_seconds (float | None): サンドボックス RPC のクライアント側 HTTP タイムアウト。デフォルトはセッションの SandboxDefaults.request_timeout_seconds です。
• data_plane_mode (DataPlaneMode | str | None): セッションのデータプレーンのトランスポートポリシーを上書きします。
• auth (AuthConfig | None): 認証方式、解決済みのヘッダー、またはプロバイダー。このサンドボックスについてセッションのデフォルトを上書きします。
• environment_variables (dict[str, str] | None): サンドボックスに注入する環境変数。セッションのデフォルトとマージされ、一致するキーを上書きします。機密性のない設定にのみ使用してください。
• annotations (dict[str, str] | None): サンドボックスの Kubernetes Pod アノテーション。セッションのデフォルトとマージされ、一致するキーを上書きします。機密性のないメタデータにのみ使用してください。
• secrets (Sequence[Secret | dict[str, Any]] | None): 環境変数として注入するシークレット。セッションのデフォルトとマージされます (デフォルトが先、このリストが後) 。
• containers (Sequence[Container | Mapping[str, Any]] | None): 複数コンテナーの spec。単一コンテナーのキーワード引数とは相互に排他的です。セッションの defaults.secrets、environment_variables、security_context、working_dir を置き換えます。これらは各 Container に設定してください。@session.function() では使用されません。

• Sandbox: セッションに登録された、未起動の Sandbox。

• SandboxError: セッションが閉じられている場合。

with Session(defaults) as session:
    # 自動起動: 最初の exec() 呼び出しでサンドボックスが起動します
    sb = session.sandbox(command="sleep", args=["infinity"])
    result = sb.exec(["echo", "hello"]).result()

    # 起動タイミングを制御するために明示的に起動します
    sb2 = session.sandbox(command="sleep", args=["infinity"])
    sb2.start().result()
    sb2.wait()
    result = sb2.exec(["echo", "hello"]).result()

​

list

list(*, tags: list[str] | None = None, status: str | None = None, profile_ids: list[str] | None = None, profile_names: list[str] | None = None, runner_ids: list[str] | None = None, show_terminated: bool = False, adopt: bool = False, volume_ids: list[str] | tuple[str, ...] | None = None) -> OperationRef[list[Sandbox]]

• tags (list[str] | None): フィルターに使用する追加のタグ (セッションのデフォルトのタグと統合されます)
• status (str | None): ステータスでフィルターします
• profile_ids (list[str] | None): 1.x で削除されました。値を渡すと TypeError が送出されます。
• profile_names (list[str] | None): 1.x で削除されました。値を渡すと TypeError が送出されます。
• runner_ids (list[str] | None): ランナー ID でフィルターします (セッションの runner_ids が設定されている場合は、それがデフォルトになります)
• volume_ids (list[str] | tuple[str, ...] | None): これらの登録済み Volume ID に関連付けられたサンドボックスに絞り込みます
• show_terminated (bool): True の場合、終端状態のサンドボックス (完了、失敗、終了) を含めます。デフォルトは False です。
• adopt (bool): True の場合、検索されたサンドボックスをこのセッションに登録し、セッションが閉じられたときに停止されるようにします

• OperationRef[list[Sandbox]]: OperationRef[list[Sandbox]]: .result() を使用して、結果が得られるまでブロックします。
• OperationRef[list[Sandbox]]: または、Asyncコンテキストで直接 await します。

# セッションのデフォルトには、このアプリケーション/run 用のタグが含まれます
defaults = SandboxDefaults(tags=("my-app", "run-abc123"))

with Session(defaults) as session:
    # 同期での使用例 - ["my-app", "run-abc123"] で自動的にフィルターします
    orphans = session.list(adopt=True).result()

    # フィルターを追加できます
    running = session.list(status="running").result()

    # クリーンアップや監査のために、停止したサンドボックスを含めます
    all_sandboxes = session.list(show_terminated=True).result()

# Async の使用例
async with Session(defaults) as session:
    orphans = await session.list(adopt=True)

​

from_id

from_id(sandbox_id: str, *, adopt: bool = True) -> OperationRef[Sandbox]

• sandbox_id (str): 既存のサンドボックスの ID
• adopt (bool): True (デフォルト) の場合、サンドボックスをこのセッションに登録します

• OperationRef[Sandbox]: OperationRef[Sandbox]: .result() を使用して Sandbox インスタンスが得られるまでブロックします。
• OperationRef[Sandbox]: または、Asyncコンテキストで直接 await します。

with Session(defaults) as session:
    # 同期での使用例 - サンドボックスに再接続します
    sb = session.from_id("sandbox-abc123").result()
    result = sb.exec(["echo", "hello"]).result()
# セッション終了時に sb は停止します

# Async の使用例
async with Session(defaults) as session:
    sb = await session.from_id("sandbox-abc123")
    result = await sb.exec(["echo", "hello"])

​

adopt

adopt(sandbox: Sandbox) -> None

• sandbox (Sandbox): トラッキングする Sandbox インスタンス

• SandboxError: セッションが終了している場合
• ValueError: サンドボックスに sandbox_id がない場合

with Session(defaults) as session:
    # クラスメソッドでサンドボックスを取得します
    sandboxes = Sandbox.list(tags=["my-job"]).result()

    # サンドボックスをセッションに取り込みます
    for sb in sandboxes:
        session.adopt(sb)

    # これでセッションが閉じるとサンドボックスが停止します

​

function

function(*, container_image: str | None = None, temp_dir: str | None = None, runner_ids: list[str] | None = None, resources: ResourceOptions | dict[str, Any] | None = None, mounted_files: Sequence[dict[str, Any]] | None = None, network: NetworkOptions | dict[str, Any] | None = None, services: Sequence[Service] | None = None, volumes: Sequence[ScratchVolumeOptions | RegisteredVolumeOptions | dict[str, Any]] | None = None, file_system_snapshot: FileSystemSnapshotOptions | dict[str, Any] | None = None, placement_mode: PlacementMode | str | None = None, placement_spillover: PlacementSpillover | str | None = None, runtime_class: str | None = None, security_context: SecurityContext | dict[str, Any] | None = None, working_dir: str | None = None, object_storage_access: ObjectStorageAccess | dict[str, Any] | None = None, environment_variables: dict[str, str] | None = None, annotations: dict[str, str] | None = None, request_timeout_seconds: float | None = None, data_plane_mode: DataPlaneMode | str | None = None, **kwargs: Any = {}) -> Callable[[Callable[P, R]], RemoteFunction[P, R]]

• container_image (str | None): この関数で使用するセッションのデフォルトイメージを上書きします
• temp_dir (str | None): サンドボックス内のペイロード/結果ファイル用の一時ディレクトリを上書きします。デフォルトはセッションのデフォルトです。存在しない場合は作成されます。
• profile_ids: 1.x で削除されました。値を渡すと TypeError が送出されます。
• profile_names: 1.x で削除されました。値を渡すと TypeError が送出されます。
• runner_ids (list[str] | None): 任意の CKS ランナー固定指定です (サーバーレスおよび placement_spillover='serverless_then_cks' とは併用できません)
• resources (ResourceOptions | dict[str, Any] | None): リソース設定です。リクエストと制限を個別に指定する ResourceOptions、または後方互換の Guaranteed QoS 用のフラットな dict を受け入れます。
• mounted_files (Sequence[dict[str, Any]] | None): 起動時にサンドボックスにマウントするファイルです。各 dict には mount_path (str) と file_content (bytes) が必要です。注: マウントされたファイルは実行時には読み取り専用です。ファイルを変更するには、サンドボックスの稼働後に sandbox.write_file() を使用してください。
• s3_mount: 1.x で削除されました。値を渡すと TypeError が送出されます。
• ports: 1.x で削除されました。代わりに services=[Service(...)] を使用してください。
• network (NetworkOptions | dict[str, Any] | None): 拒否フラグと、任意の作成時ホスト名グラントを指定する NetworkOptions (または dict) です。ポートの公開には services= を使用します。
• file_system_snapshot (FileSystemSnapshotOptions | dict[str, Any] | None): 単一マウント用の簡易 FSS オプション (FileSystemSnapshotOptions または dict) です。複数ボリュームの構成では volumes= を推奨します。
• max_timeout_seconds: 1.x で削除されました。request_timeout_seconds を使用してください。
• request_timeout_seconds (float | None): サンドボックス RPC 用のクライアント側 HTTP タイムアウトです。デフォルトはセッションの SandboxDefaults.request_timeout_seconds です。
• data_plane_mode (DataPlaneMode | str | None): セッションのデータプレーンのトランスポートポリシーを上書きします。
• environment_variables (dict[str, str] | None): サンドボックスに注入する環境変数です。セッションのデフォルトとマージされ、一致するキーを上書きします。機密性のない設定にのみ使用してください。
• annotations (dict[str, str] | None): サンドボックスの Kubernetes Pod アノテーションです。セッションのデフォルトとマージされ、一致するキーを上書きします。機密性のないメタデータにのみ使用してください。

• Callable[[Callable[P, R]], RemoteFunction[P, R]]: 関数を RemoteFunction としてラップするデコレーターです

with Session(defaults) as session:
    @session.function()
    def compute(x: int, y: int) -> int:
        return x + y

    # .remote() を呼び出してサンドボックスで実行する
    ref = compute.remote(2, 3)  # OperationRef をすぐに返す
    result = ref.result()       # 結果をブロックする
    print(result)  # 5

    # または async コンテキストで await を使用する
    result = await compute.remote(2, 3)

    # テストのためにローカルで実行する
    result = compute.local(2, 3)

    # 複数の入力を並列にマップする
    refs = compute.map([(1, 2), (3, 4), (5, 6)])
    results = [ref.result() for ref in refs]