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

概要

関数デコレーター 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月15日