モデルアダプター API

モデルアダプターの api() メソッドは、このモデルアダプターの推論ロジックを実行するために期待される入力と出力を指定します。入力と出力は別々に指定します。

実行時には、指定された入力でモデルアダプターの predict() メソッドが呼び出されます。

api() の実装例

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

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
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
import palantir_models as pm


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)
        }
        outputs = {
            "output_dataframe": pm.Pandas(columns=[("input_feature", float), ("prediction", float)])
        }
        return inputs, outputs

    ...

API のデータ型

モデルアダプター API の入力と出力のデータ型は、以下のクラスで指定できます。各クラスの詳細は後述します。

• pm.Pandas：Pandas データフレーム用 (*)
• pm.Spark：Spark データフレーム用 (*)
• pm.Parameter：単一の値を持つ定数パラメーター用
• pm.FileSystem：Foundry データセットのファイルシステムへのアクセス用
• pm.MediaReference：Media Reference での使用用
• pm.Object：オントロジーオブジェクトでの使用用
• pm.ObjectSet：オントロジーのオブジェクトセットでの使用用

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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# 次のクラスは `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):
        """
        FileSystem にアクセスする入力または出力オブジェクトを定義します。この型は、モデルアダプターの `transform()` または `transform_write()` メソッドを Foundry データセットオブジェクトで呼び出した場合にのみ利用できます。

        入力として使用すると、データセットの FileSystem 表現が返されます。

        出力として使用すると、`open()` メソッドを持つオブジェクトを使用して出力データセットにファイルを書き込みます。

        FileSystem 出力は、`.transform_write()` の呼び出しでのみ利用できることに注意してください。
        """

class MediaReference:
    def __init__(self):
        """
        入力オブジェクトを MediaReference 型として定義します。この入力には、Media Reference オブジェクトの JSON 表現を文字列化したもの、または辞書表現を渡すことが期待されます。

        この型は API 出力としては利用できません。
        """

class Object:
    def __init__(self):
        """
        入力オブジェクトを Object 型として定義します。この入力には、指定された Object 型の主キー、または Object 型自体のインスタンスを渡すことが期待されます。

        この型は API 出力としては利用できません。
        """

class ObjectSet:
    def __init__(self):
        """
        入力オブジェクトを ObjectSet 型として定義します。この入力には、指定された Object 型のオブジェクトセットの rid、または ObjectSet 自体のインスタンスを渡すことが期待されます。

        この型は API 出力としては利用できません。
        """

(*) モデルを関数として公開する際にこれらのデータ型を使用する場合は、後述の要件を確認してください。

表形式の列を指定する

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

列のデータ型

表形式の列では、以下のデータ型がサポートされています。

• str
• int
• float
• bool
• list (*)
• dict(*)
• datetime.date
• datetime.time
• datetime.datetime
• typing.Any (*)
• MediaReference

ライブ推論とは異なり、バッチ推論では通常、列のデータ型は強制_されません_。主に、このモデルアダプターを利用するユーザー向けのドキュメントとして使用されます。API の強制適用に関する仕様の詳細は、モデルアダプターのリファレンスを参照してください。

(*) モデルを関数として公開する際にこれらのデータ型を使用する場合は、後述の要件を確認してください。

パラメーターのデータ型

Parameter の入力と出力では、以下のデータ型がサポートされています。

• str
• int
• float
• bool
• list(*)
• dict(*)
• typing.Any(*)
• pm.NDArray(shape: list[int], dtype: numpy.typing.DTypeLike)

パラメーターのデータ型は強制適用され、model.transform() に入力されたパラメーターが指定されたデータ型に対応していない場合は、実行時エラーが発生します。

(*) モデルを関数として公開する際にこれらのデータ型を使用する場合は、後述の要件を確認してください。

NDArray 型

モデル API では、pm.NDArray(shape, dtype) パラメーターのデータ型定義を通じて、NumPy ndarray ↗（N 次元配列）型がサポートされています。ndarray 入力には、形状と dtype の両方を指定する必要があります。

サポートされている dtype

以下の NumPy dtype がサポートされています。

• np.str_
• np.bool_
• np.int8
• np.int16
• np.int32
• np.int64
• np.float16
• np.float32
• np.float64

形状の指定

形状は list[int] として指定し、各要素が次元を表します。任意の次元に -1 を指定すると、その次元の形状チェックが無視されます。

使用例

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


class NumpyModelAdapter(pm.ModelAdapter):
    ...

    @classmethod
    def api(cls):
        inputs = {
            "ndarray_in": pm.Parameter(
                type=pm.NDArray([1, 1, 2], np.int8),
                default=np.array([[[1, -5]]], dtype=np.int8)
            )
        }
        outputs = {
            "ndarray_out": pm.Parameter(type=pm.NDArray([1, 1, 2], np.int8))
        }
        return inputs, outputs

    def predict(self, ndarray_in):
        # ndarray に対してモデルを呼び出します。
        return self.model.process(ndarray_in)

トランスフォームで NDArray を持つモデルを使用する

トランスフォームでは、np.ndarray オブジェクト、または ndarray を表すリストのいずれかを入力として指定できます。

Copied!
1
2
3
4
5
6
7
8
9
# numpy 配列を直接使用します。
ndarray = np.array([[[-95, -63]]], dtype=np.int8)

model_output = model.predict(ndarray_in=ndarray)
type(model_output["ndarray_out"])  # <class 'numpy.ndarray'>

# リスト表現を使用します（自動的に変換されます）。
model_output = model.transform(ndarray_in=ndarray.tolist())
type(model_output["ndarray_out"])  # <class 'numpy.ndarray'>

Functions で NDArray を使用する

Functions で NDArray 入力を持つモデルを使用する場合は、入力を必ず JSON に対応したネストされたリストとして指定する必要があります。出力が np.ndarray の場合、出力もネストされたリストとして返されます。

Copied!
1
2
3
4
5
6
7
8
import { model } from "<...>/models";

@Function()
public async ndarray_model_example(input: Integer[][][]): Promise<Integer[][][]> {
    return await model({
        "ndarray_in": input
    });
}

Object 型と ObjectSet 型

Object または ObjectSet の入力では、モデルアダプター API で入力を定義する際にオブジェクトタイプを指定します。このオブジェクトタイプは、選択したオントロジー用に生成されたオントロジー SDKからインポートされます。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from ontology_sdk.ontology.objects import ExampleRestaurant


class ExampleModelAdapter(pm.ModelAdapter):
    ...

    @classmethod
    def api(cls):
        inputs = {
            "input_object": pm.Object(ExampleRestaurant),
            "input_object_set": pm.ObjectSet(ExampleRestaurant)
        }
        outputs = {
            "output_dataframe": pm.Pandas(columns=[("input_feature", float), ("prediction", float)])
        }
        return inputs, outputs

    def predict(self, input_object: ExampleRestaurant, input_object_set: ExampleRestaurantObjectSet):
        outputs = ...
        return outputs
    ...

predict() の実装例

この例では、パラメーターとともに、Pandas データフレームを入力と出力に使用します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
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)
        }
        outputs = {
            "output_dataframe": pm.Pandas(columns=[("input_feature", float), ("prediction", float)])
        }
        return inputs, outputs

    def predict(self, input_dataframe, input_parameter):
        input_dataframe["prediction"] = self.model.predict(input_dataframe) * input_parameter
        return input_dataframe
    ...

• 表形式の出力では、API で指定する列のリストに、必要な列のみを含める必要があります。実行時には、API で指定されていない列がデータフレームに渡された場合、その列は predict メソッドの入力で利用可能になり、出力として返すことができます。上の例では、input_feature 列と extra_column 列を持つデータフレームを渡すと、input_feature、extra_column、prediction の列を持つデータフレームが返されます。
• 一部のモデルでは、学習時に使用した列のみを予測メソッドに渡す必要があります。そのため、特徴量の列のみを抽出してモデルに渡すことを推奨します。
• 一部のモデルでは、列の順序を維持する必要があります。REST API リクエストを通じて入力を JSON オブジェクトとして渡す場合、列の順序が維持されるとは限りません。そのため、モデルの推論メソッドに渡す前に列を並べ替えることを推奨します。

API 定義の要件

Objectives のバッチデプロイメントの要件

Modeling Objectives アプリケーションでバッチデプロイメントと自動モデル評価を直接設定できるのは、表形式データセットの入力が1個のみのモデルに限られます。モデルアダプターで複数の入力が必要な場合は、Python トランスフォーム内でバッチ推論を設定できます。

Objectives の評価の要件

Modeling Objectives での評価では、表形式の入力と出力がそれぞれ1個であることを想定しています。評価セット内の正解データと予測を比較してメトリクスを計算できるように、入力と出力の両方にラベル列を含める必要があります。モデルアダプターを評価に対応させるには、次のルールに留意する必要があります。

1. API に含める表形式の入力と出力は、それぞれ1個のみでなければなりません。
2. ラベル列や正解データの列は、入力テーブルや出力テーブルの列リストに含めないでください。
   • ライブ推論では宣言された列のデータ型が強制されるため、これらの列を含めると、ラベル列が存在しない場合にモデルをライブ推論で使用できなくなります。
3. predict メソッドでラベル列や正解データの列を削除しないでください。
   • これらの列を削除すると、predict メソッドの推論出力に対して実行される評価ロジックで、比較に使用するラベルが利用できなくなります。

例として、回帰タスク用の次のアダプターを考えます。

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
40
41
42
43
import palantir_models as pm
from palantir_models.serializers import DillSerializer

class LinearRegressionModelAdapter(pm.ModelAdapter):

    @pm.auto_serialize(
        model=DillSerializer()
    )
    def __init__(self, model):
        self.model = model

    @classmethod
    def api(cls):
        input_columns = [
            ('median_income', float),
            ('housing_median_age', float),
            ('total_rooms', float),

            # 目的変数を API に明示的に含めないでください。
            # アダプターのロジックは、ライブ推論で
            # ラベルが見つからない場合にエラーをスローするためです。
            # これは、モデルをトレーニングセットまたは評価セット
            # 以外に適用すると必ず発生します。

            # ('house_price', float) # should not be included
        ]
        output_columns = columns + [('predicted_house_price', float)]
        return {'df_in': pm.Pandas(input_columns)}, \
               {'df_out': pm.Pandas(output_columns)}

    def predict(self, df_in):
        cols_to_keep = ['median_income', 'housing_median_age', 'total_rooms']
        # これを行わないと、次の行で
        # 'house_price' 列が暗黙的に削除されます。
        # この列は「ラベル」または目的変数を表すため、
        # このアダプターは Modeling Objectives の
        # Evaluation での使用に適さなくなります。
        if 'house_price' in df_in.columns:
            cols_to_keep.append('house_price')
        df_in['prediction'] = self.model.predict(
            df_in[cols_to_keep]
        )
        return df_in

関数の直接公開および Functions でのモデル使用の要件

モデルを関数として公開できるようにするには、次の条件を満たす必要があります。

• モデル API に含められる入力は、Parameter、Tabular、Object、または ObjectSet のみです。
• API に Typing.Any 型を含めてはいけません。
• 表形式の入力では、API で必要な入力列または出力列を指定する必要があります。単に pm.Pandas() または pm.Spark() を使用することはできません。これらは暗黙的に TypeScript の Array<any> として解釈されるためです。
• list や dict などのコレクション型では、要素のデータ型を指定する必要があります（たとえば、list[str] や dict[str, str] を使用します）。指定しない場合、要素のデータ型は any 型として解釈されます。