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) である必要があります。
TypeError が送出されます。
Example output
return value is not JSON-serializable というメッセージが表示されます。
JSON オブジェクトのキーには文字列しか使用できません。整数、float、ブール値をキーとする辞書は、変換されずに拒否されます。そのため、サンドボックス内で関数が受け取る値のタイプは、渡したタイプと常に一致します。
NumPy 配列、pandas のデータフレーム、カスタムクラスのインスタンスを扱う場合は、関数を呼び出す前に JSON 互換の値に変換し、関数内で元の形式に再構築してください。
クロージャとグローバル変数
クロージャ変数
関数は、外側のスコープにある変数を取得します。グローバル変数
デコレーターは、関数から参照されているグローバル変数を関数と一緒にシリアライズします。コンテナーイメージ
特定の関数で使用するコンテナーイメージを上書きします。エラー処理
関数で発生した例外は、呼び出し元に伝播します。関数とサンドボックスの使い分け
次の表を参考に、ワークロードに適しているのが関数デコレーター API とサンドボックス API のどちらであるかを判断してください。制限事項
関数 API は意図的にシンプルな設計になっています。複雑なワークフローには、次の方法で対応してください。- リトライとバックオフ: 呼び出し側のコードで実装します。
- タスクの依存関係と DAG: Airflow や Prefect などのワークフローオーケストレーターを使用します。
- 複雑なスケジューリング: サンドボックス API を直接使用します。