モデル関数開発者ガイド

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

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

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

モデル関数を公開する

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

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

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

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

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

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

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

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

モデルの直接デプロイメント：各バージョンに対する関数バージョンの自動公開

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

引き続き Marketplace インストールの出力であるモデルについては、インストールおよび製品のアップグレード時に、Marketplace が関数の公開を管理します。デフォルトブランチで新しいモデルバージョンを公開すると、関数バージョンは自動公開されずにライブデプロイメントが更新されます。

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

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

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

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

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

モデル API の変更

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

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

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

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

TypeScript v1

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

TypeScript v2 と Python

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

行単位の公開

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

表形式の入力1個から表形式の出力1個を生成するモデルでは、行単位の関数公開がデフォルトで有効になっています。つまり、モデル API が宣言する入力と出力がそれぞれちょうど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;
    }>;
}>

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