注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
以下のドキュメントは、プラットフォームでの使用が推奨されなくなった foundry_ml ライブラリについて説明しています。代わりに palantir_models ライブラリを使用してください。foundry_ml から palantir_models フレームワークへのモデルの移行方法についても 例 を通じて学ぶことができます。
foundry_ml ライブラリは 2025年10月31日に削除される予定です。これは Python 3.9 の廃止計画に対応しています。
Code Repositories の Preview 機能は、foundry_ml.function_stages.pandas_function_stage デコレータを使用するトランスフォームでは現在サポートされていません。代わりに Build を選択してトランスフォームをビルドしてください。
このハウツーは foundry_ml バージョン >= 3.12.0 を必要とします。
FoundryML は、単一の pandas DataFrame 上で動作する Python 関数を組み込むためのネイティブラッパーを提供します。これにより、任意の処理や迅速なプロトタイピングが可能となり、予測モデル、シミュレーション、最適化など、全体のデータセットに対して一度に操作する必要がある非行単位のモデルの実装が可能になります。
以下の条件を満たす Python 関数には foundry_ml.function_stages.pandas_function_stage デコレータを注釈として付けることができます。これにより ステージ が生成され、必要に応じて他のステージと組み合わせて Python モデル を形成することができます。これらのステージを含むモデルは、バッチおよびライブデプロイメントと完全に互換性があり、pandas または pyspark DataFrame 上で呼び出すことができます（ただし後者の場合、処理はローカルで pandas で実行されます）。
デコレートされる関数の主な要件は以下の通りです:
(data: pandas.DataFrame, params: NamedTuple) -> pandas.DataFrame
data は必須の kwarg（キーワード引数）であり、pandas DataFrame でなければなりません。params は必須の kwarg であり、NamedTuple でなければなりません。このチュートリアルでは、Foundry で SIR（Susceptible, Infected, Recovered）モデルを実装する方法を示します。これはパンデミックの拡散を予測するために使用される「区画化」モデルの一部であるシンプルなバージョンです。この例では、SciPy ドキュメントに記載されている シンプルな SIR モデル ↗ を FoundryML エコシステム内で pandas_function_stage デコレータを使用して再実装することに焦点を当てます。
以下のコードは、モデルのコア機能を実装しています:
Copied!1import numpy as np 2from scipy.integrate import odeint 3 4# 総人口, N. 5N = 1000 6# 初期の感染者数と回復者数, I0 と R0. 7I0, R0 = 1, 0 8# 残りの人々, S0, は初めは全員が感染に対して感受性がある。 9S0 = N - I0 - R0 10# 接触率, beta, と平均回復率, gamma, (単位: 日^-1). 11beta, gamma = 0.2, 1./10 12# 時間のグリッド (単位: 日) 13t = np.linspace(0, 160, 160) 14 15# SIRモデルの微分方程式. 16def deriv(y, t, N, beta, gamma): 17 S, I, R = y 18 dSdt = -beta * S * I / N # 感受性がある人々が減少する速度 19 dIdt = beta * S * I / N - gamma * I # 感染者が増減する速度 20 dRdt = gamma * I # 回復者が増加する速度 21 return dSdt, dIdt, dRdt 22 23# 初期条件ベクトル 24y0 = S0, I0, R0 25# 時間グリッドtにわたってSIR方程式を積分する. 26ret = odeint(deriv, y0, t, args=(N, beta, gamma)) 27S, I, R = ret.T
新しいCode Workbookを作成し、導入ダイアログをスキップしてデータセットを環境にインポートします。次に、新しいトランスフォームを作成し、言語として Python を選択します。また、州と対応する人口のデータセットがあり、フィールドとして id: string、population: int が含まれていることを前提とします。データセットを持っていない場合は、以下のコードを使用してテスト用のPandas DataFrameを定義することもできます:
Copied!1import pandas as pd 2 3input_df: pd.DataFrame = pd.DataFrame([ 4 ['TX', 29000000], # テキサス州の人口 5 ['CO', 5800000], # コロラド州の人口 6 ['NY', 8400000]], # ニューヨーク州の人口 7 columns=['id', 'population']) # 'id'列と'population'列を指定
pandas_function_stageデコレータを使用するこのモデルを FoundryML と統合するために、pandas_function_stageデコレータを使用します。このデコレータは、関数を Foundry ML Stage にラップできるように準備し、その後 Foundry ML Model を作成するために使用できます。
これを行うために、最初にNamedTupleを定義し、入力パラメーターに型を適用します。
関数の NamedTuple パラメーター入力を定義する際には、Python の型アノテーションを使用し、NamedTuple の各プロパティにデフォルト値を提供する必要があります。
Copied!1from typing import NamedTuple 2 3# SIRモデルのパラメータを格納するためのNamedTupleクラス 4class SIRParameters(NamedTuple): 5 n_days: int = 2 # シミュレーションする日数 6 I0: int = 1 # 初期感染者数 7 R0: int = 0 # 初期回復者数 8 beta: float = 0.2 # 感染率 9 gamma: float = 0.1 # 回復率
次に、単一の状態に対して予測を実行するための forecast メソッドを作成し、この関数を各状態の DataFrame の行に適用するために sir_model を使用します。
関数のシグネチャを定義する際には、Python の型アノテーションを使用する必要があります。
Copied!1from scipy.integrate import odeint 2import pandas as pd 3import numpy as np # npを利用するためにインポート 4 5# SIRモデルを実行する関数 6def sir_model(data: pd.DataFrame, params: SIRParameters) -> pd.DataFrame: 7 rows = data.to_dict('rows') # データフレームを辞書形式に変換 8 results = [] 9 for state in rows: 10 id = state['id'] # 各状態のIDを取得 11 population = state['population'] # 各状態の人口を取得 12 state_df = forecast(population, params) # 予測を実行 13 state_df['state'] = id # 予測結果に状態IDを追加 14 results.append(state_df) # 結果をリストに追加 15 return pd.concat(results, ignore_index=True) # 結果をデータフレームとして結合して返す 16 17# 予測を行う関数 18def forecast(n_population, parameters): 19 n_days = parameters.n_days # 予測日数を取得 20 I0 = parameters.I0 # 初期感染者数 21 R0 = parameters.R0 # 初期回復者数 22 S0 = n_population - I0 - R0 # 初期感受性者数 23 24 beta = parameters.beta # 感染率 25 gamma = parameters.gamma # 回復率 26 t = np.linspace(0, n_days, n_days) # 時間の配列を生成 27 28 y0 = S0, I0, R0 # 初期状態 29 ret = odeint(deriv, y0, t, args=(n_population, beta, gamma)) # 微分方程式を解く 30 S, I, R = ret.T # 結果を転置してそれぞれの状態を取得 31 return pd.DataFrame({ 32 'susceptible': S, 33 'infected': I, 34 'recovered': R, 35 'n_days': range(n_days), 36 }) # 予測結果をデータフレームとして返す 37 38# SIRモデルの微分方程式 39def deriv(y, t, N, beta, gamma): 40 S, I, R = y 41 dSdt = -beta * S * I / N # 感受性者の変化率 42 dIdt = beta * S * I / N - gamma * I # 感染者の変化率 43 dRdt = gamma * I # 回復者の変化率 44 return dSdt, dIdt, dRdt # 各状態の変化率を返す
最後に、sir_model 関数に pandas_function_stage デコレーターを付けてください。
Copied!1from foundry_ml.function_stages import pandas_function_stage 2 3@pandas_function_stage() 4def sir_model(data: pd.DataFrame, params: SIRParameters) -> pd.DataFrame: 5 # SIRモデルのデータ処理を行う関数 6 # data: SIRモデルの入力データを含むDataFrame 7 # params: SIRモデルのパラメータを含むオブジェクト 8 ...
関数プロパティをデコレートしたので、Foundry ML モデルとしてモデルを保存できます。
Copied!1from foundry_ml import Model, Stage 2 3def model(): 4 return Model(Stage(sir_model)) 5 6# このコードは、foundry_mlライブラリからModelおよびStageをインポートし、 7# sir_modelを使用してModelオブジェクトを生成する関数を定義しています。
transform 関数を使用して、他の Model と同じようにモデルを実行できます。
Copied!1def execute_model(model, states_df: pd.DataFrame): 2 # モデルを実行してオーバーライドなしの結果を取得 3 result_no_overrides = model.transform(states_df) 4 5 # モデルを実行してオーバーライドありの結果を取得（n_daysを10に設定） 6 result_with_override = model.transform(states_df, params={'n_days': 10})
モデルがバッチデプロイメントを使用してデプロイされている場合、パラメーターはユーザー入力で上書きできません。
モデルをライブデプロイメントを通じて提供している場合、ライブデプロイメント推論 API を使用してデプロイメントを実行できます:
curl --http2 -H "Content-Type: application/json" -H "Authorization: <$BEARER_TOKEN>" -d '{"requestData":[{"id":"TX","population":29000000}, {"id":"CO","population":5800000}], "requestParams":{"params":{"num_days":10}}}' --request POST $STACK_URL/foundry-ml-live/api/inference/transform/$DEPLOYMENT_RID
# このコマンドは、curlを使用してHTTP POSTリクエストを送信します。
# --http2: HTTP/2プロトコルを使用します。
# -H "Content-Type: application/json": リクエストヘッダーにコンテンツタイプとしてJSONを指定します。
# -H "Authorization: <$BEARER_TOKEN>": リクエストヘッダーに認証トークンを含めます。
# -d '{"requestData":[{"id":"TX","population":29000000}, {"id":"CO","population":5800000}], "requestParams":{"params":{"num_days":10}}}': リクエストのデータ部分にJSON形式のデータを含めます。
# --request POST: HTTP POSTリクエストを指定します。
# $STACK_URL/foundry-ml-live/api/inference/transform/$DEPLOYMENT_RID: リクエストを送信するエンドポイントURLです。