> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Group and manage multiple sandboxes with sessions.

ここで紹介する例では、`CWSANDBOX_API_KEY` に設定した CoreWeave API アクセストークンを使用します。Forge の APIキーによる認証については、[はじめに](/ja/products/sandboxes/get-started)を参照してください。CKS の要件については、[配置モード](/ja/products/sandboxes/placement)を参照してください。

このガイドでは、`Session` を使用して共通の設定を持つ複数のサンドボックスを管理する方法を説明します。サンドボックスのグループを連携させ、共通のデフォルトを適用し、ワークロード全体で一貫したクリーンアップを確実に行う必要があるクライアント開発者向けです。

<h2 id="session-overview">
  Session の概要
</h2>

`Session` は以下を提供します：

* すべてのサンドボックスに対する共有デフォルト設定。
* セッションが閉じられたときの自動クリーンアップ。
* `@session.function()` デコレータのスコープ。

<h2 id="basic-usage">
  基本的な使い方
</h2>

```python theme={"system"}
import cwsandbox
from cwsandbox import SandboxDefaults

# 共有設定を定義する
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("project-alpha",),
)

# コンテキストマネージャーでセッションを作成する
with cwsandbox.Session(defaults=defaults) as session:
    # セッションを通じてサンドボックスを作成する
    sb1 = session.sandbox()
    sb2 = session.sandbox()

    # サンドボックスを使用する
    result1 = sb1.exec(["echo", "sandbox 1"]).result()
    result2 = sb2.exec(["echo", "sandbox 2"]).result()

# コンテキストを終了するとすべてのサンドボックスが自動的に停止される
```

<h2 id="create-sandboxes">
  サンドボックスを作成する
</h2>

以下のセクションでは、セッションを使用してサンドボックスを作成する方法と、セッションのデフォルトを上書きする方法について説明します。

<h3 id="sessionsandbox">
  session.sandbox()
</h3>

セッションのデフォルトを使用してサンドボックスを作成します。サンドボックスは初回使用時まで開始されません。

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    # sandbox() は未開始のサンドボックスを返します
    sandbox = session.sandbox()

    # オペレーションは初回使用時にサンドボックスを自動開始します
    result = sandbox.exec(["echo", "hello"]).result()
```

起動 RPC がいつ発火するかを明示的に制御する場合:

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    sandbox = session.sandbox()
    sandbox.start().result()  # 明示的な開始
    sandbox.wait()            # RUNNING を待機
    result = sandbox.exec(["echo", "hello"]).result()
```

<h3 id="override-defaults">
  デフォルトを上書きする
</h3>

追加の引数を渡して、セッションのデフォルトを上書きします。

```python theme={"system"}
from cwsandbox import ResourceOptions

# 基本設定を使用する Session
defaults = SandboxDefaults(
    container_image="python:3.11",
    tags=("my-project",),
)

with cwsandbox.Session(defaults=defaults) as session:
    # このサンドボックスのイメージとリソースを上書きします
    gpu_sandbox = session.sandbox(
        command="sleep",
        args=["infinity"],
        container_image="pytorch/pytorch:latest",
        resources=ResourceOptions(
            requests={"cpu": "4", "memory": "16Gi"},
            limits={"cpu": "8", "memory": "32Gi"},
            gpu={"count": 1},
        ),
        tags=["gpu-workload"],  # セッションのタグと統合されます
    )
```

利用可能なすべてのオプションについては、[サンドボックスの設定ガイド](/ja/products/sandboxes/client/guides/sandbox-configuration)を参照してください。

<h2 id="multiple-sandbox-management">
  複数のサンドボックスの管理
</h2>

セッションは、サンドボックスプールの管理に適しています。

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    # サンドボックスのプールを作成します
    sandboxes = [
        session.sandbox()
        for _ in range(5)
    ]

    # プール内で処理を分散します
    processes = [
        sb.exec(["python", "-c", f"print({i})"])
        for i, sb in enumerate(sandboxes)
    ]

    # 結果を収集します
    results = [p.result() for p in processes]

# 5 つのサンドボックスはすべて自動的にクリーンアップされます
```

リクエストが届く前にサンドボックスを準備しておくには、
[ウォームプールを実装する](/ja/products/sandboxes/warm-pools)を参照してください。
このレシピでは、準備完了状態のサンドボックスをバッファとして確保し、ワークロードごとに個別の
サンドボックスを割り当て、ワークロードがサンドボックスを取得するたびにバッファを補充します。

<h2 id="session-lifecycle">
  セッションのライフサイクル
</h2>

以下のセクションでは、セッションを閉じる方法、`close()` の動作、およびエラーの処理方法について説明します。

<h3 id="manual-close">
  手動で閉じる
</h3>

コンテキストマネージャーを使用しない場合は、セッションを明示的に閉じてください：

```python theme={"system"}
session = cwsandbox.Session(defaults=defaults)

sandbox = session.sandbox()
result = sandbox.exec(["echo", "hello"]).result()

# セッションを閉じます（すべてのサンドボックスを停止します）
session.close().result()
```

<h3 id="what-close-does">
  close() の動作
</h3>

`close()` を呼び出すと、次の処理が実行されます。

1. セッションを通じて作成された、またはセッションに取り込まれたすべてのサンドボックスを停止します。
2. クリーンアップが完了するまで待機します。
3. `OperationRef[None]` を返します。

<h3 id="error-handling">
  エラー処理
</h3>

例外が発生した場合でも、セッションはクリーンアップされます。

```python theme={"system"}
with cwsandbox.Session(defaults=defaults) as session:
    sandbox = session.sandbox()
    raise RuntimeError("Something went wrong!")
# サンドボックスはクリーンアップされます
```

<h2 id="adopt-external-sandboxes">
  外部のサンドボックスを取り込む
</h2>

セッション外で作成されたサンドボックスをセッションの管理下に取り込みます。

```python theme={"system"}
import cwsandbox
from cwsandbox import Sandbox

with cwsandbox.Session(defaults=defaults) as session:
    # 既存のサンドボックスを検索する
    existing = Sandbox.list(tags=["orphaned-work"]).result()

    # クリーンアップのために取り込みます
    for sandbox in existing:
        session.adopt(sandbox)

    # これで session.close() はこれらもクリーンアップします
```

<h2 id="session-properties">
  Session のプロパティ
</h2>

`sandbox_count` などの組み込みプロパティを使用して、セッションの状態を確認できます。

```python theme={"system"}
session = cwsandbox.Session(defaults=defaults)

# 追跡しているサンドボックスの数
print(session.sandbox_count)  # 0

sandbox = session.sandbox()
print(session.sandbox_count)  # 1
```

<h2 id="when-to-use-sessions">
  セッションを使用する場面
</h2>

| ユースケース | 推奨される方法 |
| - | - |
| 単一のサンドボックス、単純なタスク | コンテキストマネージャーで `Sandbox.run()` を使用 |
| 複数のサンドボックス、共有設定 | Session |
| 関数デコレータ API | Session が必須 |
| ワーカープール | Session |
| 単発のコマンド | `Sandbox.run()` を直接使用 |

<h2 id="without-sessions">
  セッションを使用しない場合
</h2>

サンドボックスを 1 つだけ使用する場合、セッションは不要です：

```python theme={"system"}
from cwsandbox import Sandbox

# セッションを使わずに直接利用します
with Sandbox.run() as sandbox:
    result = sandbox.exec(["echo", "hello"]).result()
# コンテキストマネージャーがクリーンアップを処理します
```