モデル関数開発者ガイド

モデル関数は、ライブモデルデプロイメントをラップする、自動生成された関数です。Workshop、Vertex、その他のエンドユーザー向けアプリケーションで、モデルをライブ推論に使用できるようにします。モデル関数は基盤となるモデルと同じ入力および出力 API を持ち、TypeScript や Python から呼び出したり、アプリケーションで直接使用したりできます。

この開発者ガイドでは、バージョンの更新、API の変更、設定オプションなど、モデル関数の動作について説明します。直接モデルデプロイメントと Modeling Objective のライブデプロイメントの両方から公開された関数に適用されます。

コードでモデル関数をインポートして呼び出す方法については、モデルに対する関数を参照してください。

モデル関数を公開する

モデル関数を公開する前に、モデルが関数公開の要件を満たしていることを確認してください。

モデル関数は、2種類のデプロイメントから公開できます。

直接モデルデプロイメント：直接デプロイメントを作成した後、モデルページのサイドバーで + アイコンを選択します。
- ブランチごとに、対応するデプロイメントをラップする関数を1個のみ作成できます。
Modeling Objective のライブデプロイメント：ライブデプロイメントを作成した後、デプロイメントの詳細ページで関数を公開カードを使用して、デプロイメントを関数でラップします。

デプロイメントのサイドバーにある「関数を公開」カード。

Modeling Objective から公開する場合は、関数のパラメーターを設定する手順が案内されます。

新しい関数を公開するダイアログ

どちらの方法でも、機能的に同等のモデル関数が作成されます。これらは、すべてのロジックを基盤となるライブデプロイメントに委ねるシンプルなラッパーですが、モデル API は関数で認識される入力および出力のデータ型に変換されます。

コードでモデル関数をインポートして呼び出す方法については、モデルに対する関数を参照してください。

関数バージョンのアップグレード

このセクションでは、関数のアップグレード時の動作と、特にモデル API が変更された場合に、関数を使用するリソースを管理する方法について説明します。

直接モデルデプロイメント：バージョンごとの関数バージョンの自動公開

関数が公開されているブランチでモデルの新しいバージョンが公開されると、関連する関数の新しいバージョンも自動的に作成されます。後述するように、モデル API が変更されていない限り、関数を使用するリソースを新しい関数バージョンに更新する必要はありません。

通常、特定のリポジトリまたはアプリケーションにインポートできる関数バージョンは1個のみですが、変更管理のためにプロジェクトにモデルの複数のバージョンをインポートしたい場合は、異なるブランチで複数の関数を公開することで対応できます。これは、モデルのブランチごとにデプロイメントを1個、関数を1個作成できるためです。

Modeling Objectives：API が変更された場合はリリース後に新しいバージョンを作成する

Modeling Objectives で API の変更を伴うモデルバージョンをリリースすると、新しい関数を公開する必要がある場合に、次の警告が表示されます。

API 変更の警告

この警告を無視しないでください。ライブデプロイメントを、モデル API が異なる新しいモデルに更新すると、下流での使用を修正するために手動での操作が必要になります。ダイアログでは、リリースの影響を受けるデプロイメントに対して、新しい関数バージョンを公開する手順が案内されます。

新しい関数バージョンを公開するダイアログ

新しい関数バージョンを公開しないことを選択すると、現在の関数バージョンを使用している箇所が動作しなくなります。この問題を解決するには、デプロイメントの詳細ページに戻り、新しい関数バージョンを公開します。

モデル API の変更

バージョン間でモデル API が変更された場合、引き続き動作するように、モデル関数を使用する側を更新する必要があります。これには、TypeScript v1 関数と Workshop アプリケーションが含まれます。モデル関数は、関数でサポートされているデータ型を使用してモデルの API を反映します。API の変更後は、次のようになります。

以前のモデル関数バージョンは、現在のモデルと一致しなくなった古い API を公開します。
関数と基盤となるライブデプロイメントの両方が、現在の API に照らして入力と出力を検証します。
ライブデプロイメントは新しいモデル API バージョンに一致する入力と出力のみを受け付けるため、以前のモデル関数バージョンは検証に失敗し、動作しなくなります。

モデル API を変更するたびに、モデル関数とアプリケーションを更新してください。

Code Repositories でモデル関数の依存関係をアップグレードする

TypeScript v1

モデル関数の依存関係をアップグレードするには、resources.json ファイルを編集し、モデル関数の新しいバージョンを選択します。これにより、必要な型バインディングが自動的に再生成されます。

TypeScript v2 と Python

リソースのインポートサイドバーを使用して関数を削除し、適切なバージョンを指定して再インポートします。

行単位の公開

行単位の公開では、単一の表形式入力と単一の表形式出力を持つモデルの関数 API をフラット化し、関数の各呼び出しで配列ではなく1行を処理できるようにします。

単一の表形式入力から単一の表形式出力を生成するモデルでは、行単位の関数公開がデフォルトで有効になっています。つまり、モデル API が入力をちょうど1個、出力をちょうど1個宣言しており、両方が表形式である場合です。表形式入力に加えて Parameter 入力がある場合など、追加の入力または出力を宣言するモデル API は、行単位の公開の対象にはならず、公開済みの関数は代わりに配列を受け付け、配列を返します。

行単位の公開では、推論呼び出しごとにモデル API をフラット化できるため、関数を実行すると、表形式の1行を入力として受け取り、表形式の1行を出力します。別の方法として、関数でモデルをオブジェクトとともに使用しやすくするために、モデル API で Object または ObjectSet を直接使用することも検討してください。

モデル API が次のような場合を考えます。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
    @classmethod
    def api(cls):
        inputs = {
            "input_df": pm.Pandas(columns=[("area_code", int),
                              ("num_bedrooms", int),
                              ("num_bathrooms", int)])
        }
        outputs = {
            "output_df": pm.Pandas(columns=[("area_code", int),
                              ("num_bedrooms", int),
                              ("num_bathrooms", int),
                              ("predicted_price", int)])
        }
        return inputs, outputs

行単位の処理ありの直接公開関数のシグネチャは、次のようになります。

Copied!1
2
3
4
5
6
7
8
9
10
export async function housingPriceModelingObjective(parameters: {
    "area_code": FunctionsApi.Integer;
    "num_bedrooms": FunctionsApi.Integer;
    "num_bathrooms": FunctionsApi.Integer;
}): Promise<{
    "predicted_price": FunctionsApi.Double;
    "num_bathrooms": FunctionsApi.Integer;
    "area_code": FunctionsApi.Integer;
    "num_bedrooms": FunctionsApi.Integer;
}>

行単位の処理なしの直接公開関数のシグネチャは、次のようになります。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
export async function housingPriceModelingObjective(parameters: {
    "input_df": Array<{
        "num_bathrooms": FunctionsApi.Integer;
        "area_code": FunctionsApi.Integer;
        "num_bedrooms": FunctionsApi.Integer;
    }>;
}): Promise<{
    "output_df": Array<{
        "predicted_price": FunctionsApi.Double;
        "num_bathrooms": FunctionsApi.Integer;
        "area_code": FunctionsApi.Integer;
        "num_bedrooms": FunctionsApi.Integer;
    }>;
}>

特定の関数で行単位の処理を有効または無効にするには、新しい関数バージョンを公開し、行単位の処理を有効にするオプションを切り替えます。

←

PREVIOUS概要 / 結論と次のステップ

NEXTIntegrate models / Models / モデル

→