Model adapter API

adapter の api() メソッドは、この adapter の推論ロジックを実行するために必要な入力と出力を指定します。入力と出力は別々に指定されます。

実行時には、adapter の predict() メソッドが指定された入力で呼び出されます。

`api()` 実装例

以下の例は、input_dataframe という名前の 1 個の入力と、output_dataframe という名前の 1 個の出力を指定する API を示しています。入力および出力オブジェクトはどちらも Pandas データフレームとして指定され、入力データフレームには input_feature という名前の float 型の列が 1 個あり、出力データフレームには 2 個の列があります。1 つは input_feature という名前の float 型の列で、もう 1 つは output_feature という名前の int 型の列です。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import palantir_models as pm


class ExampleModelAdapter(pm.ModelAdapter):
    ...

    @classmethod
    def api(cls):
        # 入力データフレームのスキーマを定義
        inputs = {
            "input_dataframe": pm.Pandas(columns=[("input_feature", float)])
        }
        # 出力データフレームのスキーマを定義
        outputs = {
            "output_dataframe": pm.Pandas(columns=[("input_feature", float), ("prediction", float)])
        }
        # 入力と出力のスキーマを返す
        return inputs, outputs

    ...

API 定義は、任意のタイプの複数入力または出力をサポートするように拡張することもできます。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import palantir_models as pm

# ExampleModelAdapterクラスはpm.ModelAdapterを継承しています
class ExampleModelAdapter(pm.ModelAdapter):
    ...

    @classmethod
    def api(cls):
        # inputsとして、input_dataframeとinput_parameterを定義
        inputs = {
            "input_dataframe": pm.Pandas(columns=[("input_feature", float)]),  # input_feature列を持つPandas DataFrame
            "input_parameter": pm.Parameter(float, default=1.0)  # デフォルト値が1.0のパラメータ
        }
        # outputsとして、output_dataframeを定義
        outputs = {
            "output_dataframe": pm.Pandas(columns=[("input_feature", float), ("prediction", float)])  # input_featureとprediction列を持つPandas DataFrame
        }
        return inputs, outputs  # 入力と出力を返す

    ...

バッチデプロイと自動モデル評価の直接設定は、Modeling Objectivesアプリケーション内で単一の表形式データセット入力を持つモデルとしか互換性がありません。もしModel Adapterが複数の入力を必要とする場合、Pythonトランスフォーム内でバッチ推論を設定できます。

APIの種類

Model Adapter APIの入力および出力の種類は、以下のクラスで指定できます。詳細は以下に記載されています。

pm.Pandas, Pandas Dataframe用
pm.Spark, Spark Dataframe用
pm.Parameter, 定数の単一値パラメーター用
pm.FileSystem, Foundry Datasetファイルシステムアクセス用
pm.MediaReference, Media Referencesでの使用用

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# 以下のクラスは `palantir_models` または `pm` を介してアクセス可能です

class Pandas:
    def __init__(self, columns: List[Union[str, Tuple[str, type]]]):
        """
        Pandas Dataframe の入力または出力を定義します。カラム名と型の定義は、このタイプのパラメータとして指定できます。
        """

class Spark:
    def __init__(self, columns: List[Union[str, Tuple[str, type]]] = []):
        """
        Spark Dataframe (pyspark.sql.Dataframe) の入力または出力を定義します。カラム名と型の定義は、このタイプのパラメータとして指定できます。
        """

class Parameter:
    def __init__(self, type: type = Any, default = None):
        """
        定数の単一値パラメータの入力または出力を定義します。このパラメータの型（デフォルトは Any）とデフォルト値は、このタイプのパラメータとして指定できます。
        """

class FileSystem:
    def __init__(self):
        """
        ファイルシステムアクセスの入力または出力オブジェクトを定義します。このタイプは、モデルアダプタの `transform()` または `transform_write()` メソッドが Foundry Dataset オブジェクトで呼び出された場合にのみ使用可能です。

        入力として使用される場合、データセットのファイルシステム表現が返されます。

        出力として使用される場合、出力データセットにファイルを書き込むための `open()` メソッドを含むオブジェクトが使用されます。

        ファイルシステムの出力は `.transform_write()` の呼び出しを通じてのみ使用可能であることに注意してください。
        """

class MediaReference:
    def __init__(self):
        """
        MediaReference タイプの入力オブジェクトを定義します。この入力は、メディア参照オブジェクトの文字列化された JSON 表現または辞書表現のいずれかを期待します。

        このタイプは API 出力としてはサポートされていません。
        """

表形式の列の指定

Pandas または Spark の入力および出力に対して、列は列名を指定する strings のリスト、または (<name>, <type>) 形式の 2 オブジェクト tuples のリストとして指定できます。ここで <name> は列名を表す文字列で、<type> は列内のデータの型を表す Python 型です。列の定義に文字列が提供された場合、その型はデフォルトで Any になります。

列の型

表形式の列に対してサポートされる型は以下の通りです：

str
int
float
bool
list
dict
set
tuple
typing.Any
MediaReference

列の型は 強制されず、この model adapter の利用者に期待される列の型を示す方法として機能します。唯一の例外は MediaReference 型であり、この型は列内の各要素がメディアリファレンス文字列であることを期待し、各要素を MediaReference オブジェクトに変換してからこの model adapter の推論ロジックに渡します。

パラメーターの型

パラメーター の入力および出力に対して、以下の型がサポートされています：

str
int
float
bool
list
dict
set
tuple
typing.Any

パラメーターの型は強制され、指定された型に対応しない model.transform() へのパラメーター入力はランタイムエラーを投げます。

`predict()` 実装の例

この例は上記の api() の例の定義と互換性があります。これには入力および出力として Pandas データフレームを使用し、パラメーターも併用します。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
class ExampleModelAdapter(pm.ModelAdapter):
    ...

    @classmethod
    def api(cls):
        # モデルの入力と出力のスキーマを定義
        inputs = {
            "input_dataframe": pm.Pandas(columns=[("input_feature", float)]),  # 入力データフレーム
            "input_parameter": pm.Parameter(float, default=1.0)  # 入力パラメータ、デフォルト値は1.0
        }
        outputs = {
            "output_dataframe": pm.Pandas(columns=[("input_feature", float), ("prediction", float)])  # 出力データフレーム
        }
        return inputs, outputs

    def predict(self, input_dataframe, input_parameter):
        # モデルを使って予測を行い、結果にパラメータを掛ける
        outputs["prediction"] = self.model.predict(input_dataframe) * input_parameter
        return outputs  # 出力を返す
    ...

データフレームでは、コンストラクタに渡される列のリストには必要な列のみが含まれます。実行時には、入力および出力データフレームに追加の列を含めることができます。例の実装では、入力データフレームを保持し、出力に予測列を追加します。これにより、すべての追加列が実質的に保持されます。
評価中、出力には常にモデルの予測とラベルが含まれている必要があります。例では、メソッド内でラベル列が削除されないようにしてください。
一部のモデルは、トレーニング中に使用された列のみが予測メソッドに渡されることを必要とします。したがって、モデルに渡す特徴列のみを抽出することをお勧めします。
一部のモデルは、列の順序が保持されることを必要とします。REST APIリクエストを介してJSONオブジェクトとして入力が渡される場合、列の順序は必ずしも保持されません。したがって、列をモデルの推論メソッドに渡す前に再注文することをお勧めします。