> ## 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.

# ウォームプールを実装する

> Python のウォームプールレシピを使用して、受け付ける処理に備えてサンドボックスを準備完了の状態で待機させます。

サンドボックスの起動を待たずに、実行中のサンドボックスでリクエストを処理する必要がある場合は、ウォームプールを使用します。[ウォームプールレシピ](https://github.com/coreweave/cwsandbox-recipes/tree/main/recipes/warm-pool)は、準備済みのサンドボックスをバッファとして確保し、
各ワークロードに専用のサンドボックスを割り当てたうえで、バックグラウンドでバッファを補充します。
なお、アイドル状態のサンドボックスは、処理を待機している間もコンピュートを消費します。

<h2 id="how-the-pool-works">
  プールの仕組み
</h2>

レシピの `WarmPool` ヘルパーは、設定された数のサンドボックスを起動し、
それぞれで準備完了チェックを実行します。各サンドボックスのメインプロセスは、コマンドの合間も実行されたままです。
定期的な ping は必要ありません。

各ワークロードが準備完了のサンドボックスを 1 つクレームすると、それをトリガーとして代わりのサンドボックスの準備が始まります。
クレームしたサンドボックス内で実行される `exec()` はすべて、同じサンドボックスとファイルを共有します。
ワークロードが終了または失敗すると、ヘルパーはそのサンドボックスを停止します。後続のワークロードには
別のサンドボックスが割り当てられるため、以前のワークロードのローカル状態が引き継がれることはありません。

<h2 id="run-the-recipe">
  レシピを実行する
</h2>

Python 3.11 以降、[`uv`](https://docs.astral.sh/uv/getting-started/installation/)、
および[サーバーレスのアクセス権と認証情報](/ja/products/sandboxes/get-started#run-a-sandbox-on-serverless-capacity)が必要です。

1. [レシピのリポジトリ](https://github.com/coreweave/cwsandbox-recipes/tree/main/recipes/warm-pool)をダウンロードまたはクローンし、
   `recipes/warm-pool` を開きます。依存関係をインストールし、環境ファイルを作成します。

   ```bash theme={"system"}
   uv sync --frozen
   cp .env.example .env
   ```

2. `.env` と `demo.py` の冒頭付近で認証情報を設定します。

   <Tabs>
     <Tab title="Forge APIキー">
       Forge APIキーを `.env` に追加します。

       ```bash theme={"system"}
       FORGE_API_KEY="[FORGE-API-KEY]"
       ```

       `demo.py` に次のインポートを追加し、既存の `AUTH` の代入を置き換えます。

       ```python theme={"system"}
       import os
       from cwsandbox import AuthHeaders

       AUTH = AuthHeaders(
           headers={"x-wandb-api-key": os.environ["FORGE_API_KEY"]},
           strategy="wandb_api_key",
       )
       ```

       このコードは `FORGE_API_KEY` を明示的に読み取り、SDK がサポートする認証ヘッダーを使用します。ヘッダー名とストラテジー名は互換性のための識別子であり、実際に使用する認証情報は Forge APIキーです。オプションの `wandb` 依存関係をインストールする必要はありません。
     </Tab>

     <Tab title="CoreWeave API アクセストークン">
       トークンを `.env` に追加します。

       ```bash theme={"system"}
       CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
       ```

       レシピのデフォルトの `AUTH` 設定はそのままにしておきます。

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

       AUTH = AuthStrategy.COREWEAVE_API_KEY
       ```
     </Tab>
   </Tabs>

3. 比較を実行します。

   ```bash theme={"system"}
   uv run --frozen --env-file .env demo.py
   ```

このデモでは、オンデマンドで作成する 4 件のリクエストと、プールを使用する 4 件のリクエストを比較します。
初回のプール準備時間はリクエストの所要時間とは分けて報告され、
各ワークロードに一意のサンドボックスが割り当てられていることも確認されます。最後に次のメッセージが表示されれば成功です。

```text theme={"system"}
Verified 8 distinct workload sandboxes; all sandboxes stopped.
```

<h2 id="adapt-the-pool-to-your-workload">
  ワークロードに合わせてプールを調整する
</h2>

`demo.py` 内の定数を編集します。

```python theme={"system"}
POOL_SIZE = 2     # 待機状態のサンドボックスの目標数。
CONCURRENCY = 2   # 実行中のワークロードの最大数。
REQUESTS = 4      # 比較モードごとのリクエスト数。
```

これらのデフォルト設定では、同時に最大 4 つのサンドボックスを実行できます。内訳は、実行中のワークロード 2 つと、バッファ用サンドボックス 2 つです。各サンドボックスは 2 vCPU と 4 GiB の RAM をリクエストします。
バッファが空になると、リクエストは補充されるまで待機します。実行中の上限に
達した場合は、ワークロードが終了するまで待機します。バッファを増やす前に、
実際のリクエスト到着パターンで測定してください。

`demo.py` 内の `WORKLOAD` を独自のコードに置き換えます。共通のセットアップ処理は `warm_pool.py` の `prepare()` に追加し、
アプリケーションに適した準備完了チェックを使用してください。非同期のワークロードハンドラ内で
複数のコマンドを実行する場合は、レシピのクレームコンテキストを使用します。

```python theme={"system"}
async with pool.claim() as sandbox:
    await sandbox.exec(["sh", "-c", "echo hello > /tmp/result.txt"], check=True)
    result = await sandbox.exec(["cat", "/tmp/result.txt"], check=True)
    print(result.stdout)
```

クレームを解放する前に出力を回収してください。お客様の入力と認証情報はクレームを取得した後に指定し、共有の外部ストレージは対象のお客様にスコープを限定してください。

<h2 id="keep-the-pool-running">
  プールを稼働させ続ける
</h2>

リクエストを受け付けている間は、プールとそれを囲む `Session` コンテキストを開いたままにしてください。
各 Python プロセスはそれぞれ個別のプールを所有します。デモでは比較の完了後に両方を閉じます。

ヘルパーは、アイドル状態が 5 分続いたサンドボックスを置き換えます。各サンドボックスの有効期間は 10 分です。
プールは、コンテキストが開いている間は補充を続けます。これらのデフォルト設定では、ジョブが 5 分を十分に下回るようにしてください。
サンドボックスをクレームしても、その期限はリセットされません。より長いジョブ向けの設定や、中断された run の後のクリーンアップについては、
[レシピ](https://github.com/coreweave/cwsandbox-recipes/tree/main/recipes/warm-pool)を参照してください。

準備が一時的に失敗した場合は、最大 3 回まで試行されます。すべての試行が失敗した場合、
または準備中に再試行できないエラーが発生した場合は、準備完了のサンドボックスが残っていても、以降のクレームはすべて失敗します。
プールと `Session` コンテキストを終了してクリーンアップし、
根本的な問題が解決してから新しいプールを作成してください。

補充時間を短縮するには、安定した依存関係をイメージにビルドしておくか、
[ファイルシステムスナップショット](/ja/products/sandboxes/file-system-snapshots)から準備済みのワークスペースファイルをリストアします。
スナップショットが取得するのは、設定済みのマウント内のファイルです。アプリケーションプロセスは別途
起動する必要があります。[サンドボックステンプレート](/ja/products/sandboxes/profiles/templates)
に、共有イメージとスナップショットの設定を保存できます。