Skip to main content
このガイドでは、サンドボックス内で Python 関数を実行するための @session.function() デコレーターについて説明します。対象読者は、サンドボックスのライフサイクルを直接管理することなく、個々の Python の計算処理を分離された環境にオフロードしたい開発者です。リモート関数の定義方法、API がサポートする引数と戻り値のタイプ、およびこの API が適しているユースケースについて解説します。

認証を選択する

セクションで CKS が指定されていない限り、これらの例はサーバーレスキャパシティ上で実行されます。サンドボックスを所有するアカウントの認証情報を選択してください。キーまたはトークンを取得するには、認証情報の選択と取得を参照してください。 インストールコマンドは、有効化した Python 仮想環境で実行してください。 使用する認証情報のタブにある Python コードを sandbox_auth.py として、このページで実行する Python スクリプトと同じディレクトリに保存します。このファイルに保存されるのはどの認証方式を使うかという設定であり、認証情報そのものは保存されません。各例ではこのファイルから AUTH をインポートし、新しいサンドボックスや Session を作成するたびに明示的に渡します。
SDK の W&B 認証方式で Forge APIキーを使用します。
sandbox_auth.py
CKS に配置する場合は、CoreWeave トークンを選択してランナーを有効化し、サンドボックスの作成時または SandboxDefaults で placement_mode="cks" を設定します。auth=AUTH を指定して Session を作成すると、その Session が所有するサンドボックスも認証されます。サンドボックスへの再接続、一覧表示、クリーンアップを行う際も、同じ認証情報を使用してください。

概要

関数デコレーター API を使用すると、隔離されたサンドボックスコンテナー内で Python 関数を実行できます。呼び出し側のコードをシンプルに保ちつつ、個別の Python 処理をリモートで実行したい場合に使用します:

基本的な使用方法

関数を定義する

次のように、@session.function() で関数をデコレートします。

関数を呼び出す

デコレートした関数で .remote() を呼び出すと、サンドボックス内で実行されます。

実行メソッド

map() で並列実行する

複数の入力に対して実行します:
複数の引数をタプルで渡す場合:

local() でローカル実行する

サンドボックスを使用せずにローカルで実行します。テスト時に便利です。

引数と戻り値のタイプ

リモート関数は、引数と戻り値を JSON として受け渡します。そのため、どちらも JSON シリアライズ可能な値 (辞書、リスト、strings、数値、ブール値、None) である必要があります。
JSON で表現できない引数を渡すと、サンドボックスが起動する前に呼び出しから TypeError が送出されます。
Example output
JSON で表現できない戻り値も同様に失敗し、return value is not JSON-serializable というメッセージが表示されます。 JSON オブジェクトのキーには文字列しか使用できません。整数、float、ブール値をキーとする辞書は、変換されずに拒否されます。そのため、サンドボックス内で関数が受け取る値のタイプは、渡したタイプと常に一致します。 NumPy 配列、pandas のデータフレーム、カスタムクラスのインスタンスを扱う場合は、関数を呼び出す前に JSON 互換の値に変換し、関数内で元の形式に再構築してください。
クライアントは、関数を実行する前にパッケージを一切インストールしません。NumPy など、関数でインポートするライブラリは、あらかじめコンテナーイメージに含めておく必要があります。 JSON として渡すには大きすぎるデータは、サンドボックスからアクセスできるストレージに書き込み、代わりにその参照を渡してください。詳しくは、ファイル操作を参照してください。

クロージャとグローバル変数

クロージャ変数

関数は、外側のスコープにある変数を取得します。

グローバル変数

デコレーターは、関数から参照されているグローバル変数を関数と一緒にシリアライズします。
キャプチャされたクロージャ変数とグローバル変数は、引数や戻り値と同様に JSON 形式でサンドボックスに転送されます。そのため、関数が JSON で表現できない値をキャプチャしている場合は、渡す引数がすべて有効であっても呼び出しは失敗します。

コンテナーイメージ

特定の関数で使用するコンテナーイメージを上書きします。

エラー処理

関数で発生した例外は、呼び出し元に伝播します。

関数とサンドボックスの使い分け

次の表を参考に、ワークロードに適しているのが関数デコレーター API とサンドボックス API のどちらであるかを判断してください。

制限事項

関数 API は意図的にシンプルな設計になっています。複雑なワークフローには、次の方法で対応してください。
  • リトライとバックオフ: 呼び出し側のコードで実装します。
  • タスクの依存関係と DAG: Airflow や Prefect などのワークフローオーケストレーターを使用します。
  • 複雑なスケジューリング: サンドボックス API を直接使用します。

完全な設定例

次の例では、このガイドで説明した概念を組み合わせています。単一実行と並列実行に加えて、引数と戻り値を JSON 形式で受け渡す計算を示します。
最終更新日 2026年10月23日