@session.function() デコレーターについて説明します。対象読者は、サンドボックスのライフサイクルを直接管理することなく、個々の Python の計算処理を分離された環境にオフロードしたい開発者です。リモート関数の定義方法、API がサポートする引数と戻り値のタイプ、およびこの API が適しているユースケースについて解説します。
認証を選択する
セクションで CKS が指定されていない限り、これらの例はサーバーレスキャパシティ上で実行されます。サンドボックスを所有するアカウントの認証情報を選択してください。キーまたはトークンを取得するには、認証情報の選択と取得を参照してください。 インストールコマンドは、有効化した Python 仮想環境で実行してください。 使用する認証情報のタブにある Python コードをsandbox_auth.py として、このページで実行する Python スクリプトと同じディレクトリに保存します。このファイルに保存されるのはどの認証方式を使うかという設定であり、認証情報そのものは保存されません。各例ではこのファイルから AUTH をインポートし、新しいサンドボックスや Session を作成するたびに明示的に渡します。
- Forge API キー
- CoreWeave API アクセストークン
SDK の W&B 認証方式で Forge APIキーを使用します。
sandbox_auth.py
SandboxDefaults で placement_mode="cks" を設定します。auth=AUTH を指定して Session を作成すると、その Session が所有するサンドボックスも認証されます。サンドボックスへの再接続、一覧表示、クリーンアップを行う際も、同じ認証情報を使用してください。
概要
関数デコレーター API を使用すると、隔離されたサンドボックスコンテナー内で Python 関数を実行できます。呼び出し側のコードをシンプルに保ちつつ、個別の Python 処理をリモートで実行したい場合に使用します:基本的な使用方法
関数を定義する
次のように、@session.function() で関数をデコレートします。
関数を呼び出す
デコレートした関数で.remote() を呼び出すと、サンドボックス内で実行されます。
実行メソッド
map() で並列実行する
複数の入力に対して実行します:local() でローカル実行する
サンドボックスを使用せずにローカルで実行します。テスト時に便利です。引数と戻り値のタイプ
リモート関数は、引数と戻り値を JSON として受け渡します。そのため、どちらも JSON シリアライズ可能な値 (辞書、リスト、strings、数値、ブール値、None) である必要があります。
TypeError が送出されます。
Example output
return value is not JSON-serializable というメッセージが表示されます。
JSON オブジェクトのキーには文字列しか使用できません。整数、float、ブール値をキーとする辞書は、変換されずに拒否されます。そのため、サンドボックス内で関数が受け取る値のタイプは、渡したタイプと常に一致します。
NumPy 配列、pandas のデータフレーム、カスタムクラスのインスタンスを扱う場合は、関数を呼び出す前に JSON 互換の値に変換し、関数内で元の形式に再構築してください。
クロージャとグローバル変数
クロージャ変数
関数は、外側のスコープにある変数を取得します。グローバル変数
デコレーターは、関数から参照されているグローバル変数を関数と一緒にシリアライズします。コンテナーイメージ
特定の関数で使用するコンテナーイメージを上書きします。エラー処理
関数で発生した例外は、呼び出し元に伝播します。関数とサンドボックスの使い分け
次の表を参考に、ワークロードに適しているのが関数デコレーター API とサンドボックス API のどちらであるかを判断してください。制限事項
関数 API は意図的にシンプルな設計になっています。複雑なワークフローには、次の方法で対応してください。- リトライとバックオフ: 呼び出し側のコードで実装します。
- タスクの依存関係と DAG: Airflow や Prefect などのワークフローオーケストレーターを使用します。
- 複雑なスケジューリング: サンドボックス API を直接使用します。