このページでは、Google Cloud コンソールまたは Vertex AI API を使用して、表形式の分類モデルまたは回帰モデルからオンライン(リアルタイム)予測と説明を取得する方法を説明します。
オンライン予測は同期リクエストです(バッチ予測は非同期リクエストです)。アプリケーションの入力に応じてリクエストを送信する場合、またはタイムリーな推定が必要となる状況でリクエストを送信する場合は、オンライン予測を使用します。
オンライン予測用にモデルを配信する前に、モデルをエンドポイントにデプロイする必要があります。モデルのデプロイでは、少ないレイテンシでオンライン予測を提供できるように、モデルに物理リソースを関連付けます。
ここで取り上げるトピックは次のとおりです。
- エンドポイントにモデルをデプロイする
- デプロイされたモデルを使用してオンライン予測を取得する
- デプロイされたモデルを使用してオンライン説明を取得する
始める前に
オンライン予測を取得するには、まず、分類モデルまたは回帰モデルをトレーニングして、精度評価を行う必要があります。
エンドポイントにモデルをデプロイする
1 つのエンドポイントに複数のモデルをデプロイすることも、モデルを複数のエンドポイントにデプロイすることもできます。モデルのデプロイにおけるオプションとユースケースの詳細については、モデルのデプロイについてをご覧ください。
モデルをデプロイするには、次のいずれかの方法を使用します。
Google Cloud コンソール
Google Cloud コンソールの [Vertex AI] セクションで、[モデル] ページに移動します。
デプロイするモデルの名前をクリックして、詳細ページを開きます。
[デプロイとテスト] タブを選択します。
モデルがいずれかのエンドポイントにデプロイされている場合は、[モデルのデプロイ] セクションに一覧表示されます。
[エンドポイントへのデプロイ] をクリックします。
[エンドポイントの定義] ページで、次のように構成します。
モデルは、新しいエンドポイントまたは既存のエンドポイントにデプロイできます。
- 新しいエンドポイントにモデルをデプロイするには、[ 新しいエンドポイントを作成する] を選択し、新しいエンドポイントの名前を指定します。
- モデルを既存のエンドポイントにデプロイするには、[ 既存のエンドポイントに追加] を選択して、プルダウン リストからエンドポイントを選択します。
- 1 つのエンドポイントに複数のモデルを追加することも、モデルを複数のエンドポイントに追加することもできます。詳細
[続行] をクリックします。
[モデル設定] ページで、次のように構成します。
-
モデルを新しいエンドポイントにデプロイする場合は、トラフィック分割を 100 にします。1 つ以上のモデルがデプロイされている既存のエンドポイントにモデルをデプロイする場合は、すべての割合の合計が 100% になるように、デプロイするモデルとデプロイ済みのモデルのトラフィック分割の割合を更新する必要があります。
-
モデルのコンピューティング ノードの最小数を入力します。
これは、このモデルで使用可能なノードの数になります。予測負荷を処理しているか、スタンバイ状態かに関係なく、使用されているノードに対して料金が発生します(予測トラフィックがない場合でも課金されます)。料金ページをご覧ください。
-
マシンタイプを選択します。
マシンリソースのサイズが大きいほど、予測パフォーマンスが向上しますが、コストも増加します。
-
予測ロギングのデフォルト設定を変更する方法をご確認ください。
-
[続行] をクリックする
-
[モデルのモニタリング] ページで、[続行] をクリックします。
[モニタリングの目的] ページで、次のように構成します。
- トレーニング データの場所を入力します。
- ターゲット列の名前を入力します。
[デプロイ] をクリックして、エンドポイントにモデルをデプロイします。
API
Vertex AI API を使用してモデルをデプロイする場合は、次の手順を行います。
- 必要に応じてエンドポイントを作成します。
- エンドポイント ID を取得します。
- エンドポイントにモデルをデプロイします。
エンドポイントを作成する
既存のエンドポイントにモデルをデプロイする場合は、この手順を省略できます。
gcloud
次の例では、gcloud ai endpoints create
コマンドを使用します。
gcloud ai endpoints create \
--region=LOCATION \
--display-name=ENDPOINT_NAME
次のように置き換えます。
- LOCATION_ID: Vertex AI を使用するリージョン。
ENDPOINT_NAME: エンドポイントの表示名。
Google Cloud CLI ツールがエンドポイントを作成するまでに数秒かかる場合があります。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: 使用するリージョン。
- PROJECT_ID: 実際のプロジェクト ID。
- ENDPOINT_NAME: エンドポイントの表示名。
HTTP メソッドと URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints
リクエストの本文(JSON):
{ "display_name": "ENDPOINT_NAME" }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.CreateEndpointOperationMetadata", "genericMetadata": { "createTime": "2020-11-05T17:45:42.812656Z", "updateTime": "2020-11-05T17:45:42.812656Z" } } }
"done": true
が含まれるまで、オペレーションのステータスをポーリングできます。
Java
このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Java の設定手順を完了してください。詳細については、Vertex AI Java API のリファレンス ドキュメントをご覧ください。
Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
Node.js
このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Node.js の設定手順を完了してください。詳細については、Vertex AI Node.js API のリファレンス ドキュメントをご覧ください。
Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。
エンドポイント ID を取得する
モデルをデプロイするには、エンドポイント ID が必要です。
gcloud
次の例では、gcloud ai endpoints list
コマンドを使用します。
gcloud ai endpoints list \
--region=LOCATION \
--filter=display_name=ENDPOINT_NAME
次のように置き換えます。
- LOCATION_ID: Vertex AI を使用するリージョン。
ENDPOINT_NAME: エンドポイントの表示名。
ENDPOINT_ID
列に表示される番号をメモします。この ID は次の手順で使用します。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: Vertex AI を使用するリージョン。
- PROJECT_ID: 実際のプロジェクト ID。
- ENDPOINT_NAME: エンドポイントの表示名。
HTTP メソッドと URL:
GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints?filter=display_name=ENDPOINT_NAME
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "endpoints": [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/endpoints/ENDPOINT_ID", "displayName": "ENDPOINT_NAME", "etag": "AMEw9yPz5pf4PwBHbRWOGh0PcAxUdjbdX2Jm3QO_amguy3DbZGP5Oi_YUKRywIE-BtLx", "createTime": "2020-04-17T18:31:11.585169Z", "updateTime": "2020-04-17T18:35:08.568959Z" } ] }
モデルをデプロイする
お使いの言語または環境に応じて、以下のタブを選択してください。
gcloud
次の例では、gcloud ai endpoints deploy-model
コマンドを使用しています。
次の例では、予測処理を高速化するために GPU を使用せずに Model
を Endpoint
にデプロイし、複数の DeployedModel
リソース間でトラフィックを分割しません。
後述のコマンドデータを使用する前に、次のように置き換えます。
- ENDPOINT_ID: エンドポイントの ID。
- LOCATION_ID: Vertex AI を使用するリージョン。
- MODEL_ID: デプロイするモデルの ID。
-
DEPLOYED_MODEL_NAME:
DeployedModel
の名前。DeployedModel
のModel
の表示名を使用することもできます。 -
MACHINE_TYPE: 省略可。このデプロイの各ノードで使用するマシンリソース。デフォルトの設定は
n1-standard-2
です。マシンタイプの詳細。 -
MIN_REPLICA_COUNT: このデプロイの最小ノード数。ノード数は、予測負荷に応じてノードの最大数まで増減できますが、この数より少なくすることはできません。
1 以上の値を指定してください。
--min-replica-count
フラグを省略すると、値はデフォルトで 1 になります。 -
MAX_REPLICA_COUNT: このデプロイの最大ノード数。ノード数は、予測負荷に応じてこのノード数まで増減に応じて増減できますが、最大値を超えることはできません。
--max-replica-count
フラグを省略した場合、最大ノード数は--min-replica-count
の値に設定されます。
gcloud ai endpoints deploy-model コマンドを実行します。
Linux、macOS、Cloud Shell
gcloud ai endpoints deploy-model ENDPOINT_ID\ --region=LOCATION_ID \ --model=MODEL_ID \ --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE \ --min-replica-count=MIN_REPLICA_COUNT \ --max-replica-count=MAX_REPLICA_COUNT \ --traffic-split=0=100
Windows(PowerShell)
gcloud ai endpoints deploy-model ENDPOINT_ID` --region=LOCATION_ID ` --model=MODEL_ID ` --display-name=DEPLOYED_MODEL_NAME ` --machine-type=MACHINE_TYPE ` --min-replica-count=MIN_REPLICA_COUNT ` --max-replica-count=MAX_REPLICA_COUNT ` --traffic-split=0=100
Windows(cmd.exe)
gcloud ai endpoints deploy-model ENDPOINT_ID^ --region=LOCATION_ID ^ --model=MODEL_ID ^ --display-name=DEPLOYED_MODEL_NAME ^ --machine-type=MACHINE_TYPE ^ --min-replica-count=MIN_REPLICA_COUNT ^ --max-replica-count=MAX_REPLICA_COUNT ^ --traffic-split=0=100
トラフィックの分割
上記の例の --traffic-split=0=100
フラグでは、Endpoint
が受信する新しい予測トラフィックの 100% を新しい DeployedModel
に送信します。これは、一時的な ID 0
で表されます。Endpoint
にすでに他の DeployedModel
リソースがある場合は、新しい DeployedModel
と古いリソースとの間でトラフィックを分割できます。たとえば、トラフィックの 20% を新しい DeployedModel
に、80% を古いリソースに送信するには、次のコマンドを実行します。
後述のコマンドデータを使用する前に、次のように置き換えます。
- OLD_DEPLOYED_MODEL_ID: 既存の
DeployedModel
の ID。
gcloud ai endpoints deploy-model コマンドを実行します。
Linux、macOS、Cloud Shell
gcloud ai endpoints deploy-model ENDPOINT_ID\ --region=LOCATION_ID \ --model=MODEL_ID \ --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE \ --min-replica-count=MIN_REPLICA_COUNT \ --max-replica-count=MAX_REPLICA_COUNT \ --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
Windows(PowerShell)
gcloud ai endpoints deploy-model ENDPOINT_ID` --region=LOCATION_ID ` --model=MODEL_ID ` --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE ` --min-replica-count=MIN_REPLICA_COUNT ` --max-replica-count=MAX_REPLICA_COUNT ` --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
Windows(cmd.exe)
gcloud ai endpoints deploy-model ENDPOINT_ID^ --region=LOCATION_ID ^ --model=MODEL_ID ^ --display-name=DEPLOYED_MODEL_NAME \ --machine-type=MACHINE_TYPE ^ --min-replica-count=MIN_REPLICA_COUNT ^ --max-replica-count=MAX_REPLICA_COUNT ^ --traffic-split=0=20,OLD_DEPLOYED_MODEL_ID=80
REST
オンライン予測をリクエストするには、endpoints.predict メソッドを使用します。
モデルをデプロイします。
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: Vertex AI を使用するリージョン。
- PROJECT_ID: 実際のプロジェクト ID。
- ENDPOINT_ID: エンドポイントの ID。
- MODEL_ID: デプロイするモデルの ID。
-
DEPLOYED_MODEL_NAME:
DeployedModel
の名前。DeployedModel
のModel
の表示名を使用することもできます。 -
MACHINE_TYPE: 省略可。このデプロイの各ノードで使用するマシンリソース。デフォルトの設定は
n1-standard-2
です。マシンタイプの詳細。 - ACCELERATOR_TYPE: マシンに接続するアクセラレータのタイプ。ACCELERATOR_COUNT が指定されていない場合、またはゼロの場合は省略できます。AutoML モデルや、GPU 以外のイメージを使用するカスタム トレーニング モデルでは、推奨されません。詳細。
- ACCELERATOR_COUNT: 各レプリカで使用するアクセラレータの数。省略可。GPU 以外のイメージを使用する AutoML モデルまたはカスタム トレーニング モデルの場合、0 を指定するか何も指定しないかのどちらかにしてください。
- MIN_REPLICA_COUNT: このデプロイの最小ノード数。ノード数は、予測負荷に応じてノードの最大数まで増減できますが、この数より少なくすることはできません。 1 以上の値を指定してください。
- MAX_REPLICA_COUNT: このデプロイの最大ノード数。ノード数は、予測負荷に応じてこのノード数まで増減に応じて増減できますが、最大値を超えることはできません。
- TRAFFIC_SPLIT_THIS_MODEL: このオペレーションでデプロイするモデルにルーティングされる、このエンドポイントへの予測トラフィックの割合。デフォルトは 100 です。すべてのトラフィックの割合の合計は 100 になる必要があります。トラフィック分割の詳細
- DEPLOYED_MODEL_ID_N: 省略可。他のモデルがこのエンドポイントにデプロイされている場合は、すべての割合の合計が 100 になるように、トラフィック分割の割合を更新する必要があります。
- TRAFFIC_SPLIT_MODEL_N: デプロイされたモデル ID キーのトラフィック分割の割合値。
- PROJECT_NUMBER: プロジェクトに自動生成されたプロジェクト番号
HTTP メソッドと URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:deployModel
リクエストの本文(JSON):
{ "deployedModel": { "model": "projects/PROJECT/locations/us-central1/models/MODEL_ID", "displayName": "DEPLOYED_MODEL_NAME", "dedicatedResources": { "machineSpec": { "machineType": "MACHINE_TYPE", "acceleratorType": "ACCELERATOR_TYPE", "acceleratorCount": "ACCELERATOR_COUNT" }, "minReplicaCount": MIN_REPLICA_COUNT, "maxReplicaCount": MAX_REPLICA_COUNT }, }, "trafficSplit": { "0": TRAFFIC_SPLIT_THIS_MODEL, "DEPLOYED_MODEL_ID_1": TRAFFIC_SPLIT_MODEL_1, "DEPLOYED_MODEL_ID_2": TRAFFIC_SPLIT_MODEL_2 }, }
リクエストを送信するには、次のいずれかのオプションを展開します。
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/locations/LOCATION/endpoints/ENDPOINT_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.aiplatform.v1.DeployModelOperationMetadata", "genericMetadata": { "createTime": "2020-10-19T17:53:16.502088Z", "updateTime": "2020-10-19T17:53:16.502088Z" } } }
Java
このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Java の設定手順を完了してください。詳細については、Vertex AI Java API のリファレンス ドキュメントをご覧ください。
Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Node.js の設定手順を完了してください。詳細については、Vertex AI Node.js API のリファレンス ドキュメントをご覧ください。
Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
予測ロギングのデフォルト設定を変更する方法をご確認ください。
オペレーションのステータスを取得する
一部のリクエストでは、完了までに長時間かかるオペレーションが実行されます。このようなリクエストではオペレーション名が返されます。そのオペレーション名を使用して、オペレーションのステータス確認やキャンセルを行うことができます。Vertex AI には、長時間実行オペレーションに対して呼び出しを行うためのヘルパー メソッドが用意されています。詳細については、長時間実行オペレーションによる作業をご覧ください。
デプロイされたモデルを使用してオンライン予測を取得する
オンライン予測を行うには、モデルに分析のためのテスト項目を 1 つ以上送信し、モデルがモデルの目的に基づいて結果を返します。Google Cloud コンソールまたは Vertex AI API を使用して、オンライン予測をリクエストします。
Google Cloud コンソール
Google Cloud コンソールの [Vertex AI] セクションで、[モデル] ページに移動します。
モデルのリストで、予測をリクエストするモデルの名前をクリックします。
[デプロイとテスト] タブを選択します。
[モデルのテスト] セクションで、予測をリクエストするテスト項目を追加します。ベースラインの予測データが入力されたか、独自の予測データを入力して [予測] をクリックします。
予測が完了すると、Vertex AI がコンソールに結果を返します。
API: 分類
gcloud
-
次の内容のファイルを
request.json
という名前で作成します。{ "instances": [ { PREDICTION_DATA_ROW } ] }
次のように置き換えます。
-
PREDICTION_DATA_ROW: キー(特徴の名前)と値(対応する特徴の値)を持つ JSON オブジェクト。たとえば、数値、文字列の配列、カテゴリを持つデータセットの場合、データの行は次のリクエストの例のようになります。
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
トレーニングに含まれるすべての特徴に対して値を指定する必要があります。予測に使用するデータの形式は、トレーニングに使用される形式と同じにする必要があります。詳細については、予測のデータ形式をご覧ください。
-
-
次のコマンドを実行します。
gcloud ai endpoints predict ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
次のように置き換えます。
- ENDPOINT_ID: エンドポイントの ID。
- LOCATION_ID: Vertex AI を使用するリージョン。
REST
オンライン予測をリクエストするには、endpoints.predict メソッドを使用します。
リクエストのデータを使用する前に、次のように置き換えます。
-
LOCATION_ID: エンドポイントが配置されているリージョン。例:
us-central1
- PROJECT_ID: 実際のプロジェクト ID。
- ENDPOINT_ID: エンドポイントの ID。
-
PREDICTION_DATA_ROW: キー(特徴の名前)と値(対応する特徴の値)を持つ JSON オブジェクト。たとえば、数値、文字列の配列、カテゴリを持つデータセットの場合、データの行は次のリクエストの例のようになります。
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
トレーニングに含まれるすべての特徴に対して値を指定する必要があります。予測に使用するデータの形式は、トレーニングに使用される形式と同じにする必要があります。詳細については、予測のデータ形式をご覧ください。
- DEPLOYED_MODEL_ID:
predict
メソッドの出力。explain
メソッドで入力として使用されます。予測の生成に使用されるモデルの ID。以前にリクエストした予測の説明をリクエストする必要があり、複数のモデルがデプロイされている場合は、この ID を使用して、以前に予測を提供したのと同じモデルに説明が返されるようにします。
HTTP メソッドと URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict
リクエストの本文(JSON):
{ "instances": [ { PREDICTION_DATA_ROW } ] }
リクエストを送信するには、次のいずれかのオプションを選択します。
curl
リクエスト本文を request.json
という名前のファイルに保存して、次のコマンドを実行します。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"
PowerShell
リクエスト本文を request.json
という名前のファイルに保存して、次のコマンドを実行します。
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
{ "predictions": [ { "scores": [ 0.96771615743637085, 0.032283786684274673 ], "classes": [ "0", "1" ] } ] "deployedModelId": "2429510197" }
Java
このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Java の設定手順を完了してください。詳細については、Vertex AI Java API のリファレンス ドキュメントをご覧ください。
Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
Node.js
このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Node.js の設定手順を完了してください。詳細については、Vertex AI Node.js API のリファレンス ドキュメントをご覧ください。
Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。
API: 回帰
gcloud
-
request.json という名前のファイルを作成します。その内容は次のとおりです。
{ "instances": [ { PREDICTION_DATA_ROW } ] }
次のように置き換えます。
-
PREDICTION_DATA_ROW: キー(特徴の名前)と値(対応する特徴の値)を持つ JSON オブジェクト。たとえば、数値、数値の配列、カテゴリを持つデータセットの場合、データの行は次のリクエストの例のようになります。
"age":3.6, "sq_ft":5392, "code": "90331"
トレーニングに含まれるすべての特徴に対して値を指定する必要があります。予測に使用するデータの形式は、トレーニングに使用される形式と同じにする必要があります。詳細については、予測のデータ形式をご覧ください。
-
-
次のコマンドを実行します。
gcloud ai endpoints predict ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
次のように置き換えます。
- ENDPOINT_ID: エンドポイントの ID。
- LOCATION_ID: Vertex AI を使用するリージョン。
REST
オンライン予測をリクエストするには、endpoints.predict メソッドを使用します。
リクエストのデータを使用する前に、次のように置き換えます。
-
LOCATION_ID: エンドポイントが配置されているリージョン。例:
us-central1
- PROJECT_ID: 実際のプロジェクト ID。
- ENDPOINT_ID: エンドポイントの ID。
-
PREDICTION_DATA_ROW: キー(特徴の名前)と値(対応する特徴の値)を持つ JSON オブジェクト。たとえば、数値、数値の配列、カテゴリを持つデータセットの場合、データの行は次のリクエストの例のようになります。
"age":3.6, "sq_ft":5392, "code": "90331"
トレーニングに含まれるすべての特徴に対して値を指定する必要があります。予測に使用するデータの形式は、トレーニングに使用される形式と同じにする必要があります。詳細については、予測のデータ形式をご覧ください。
- DEPLOYED_MODEL_ID:
predict
メソッドの出力。explain
メソッドで入力として使用されます。予測の生成に使用されるモデルの ID。以前にリクエストした予測の説明をリクエストする必要があり、複数のモデルがデプロイされている場合は、この ID を使用して、以前に予測を提供したのと同じモデルに説明が返されるようにします。
HTTP メソッドと URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict
リクエストの本文(JSON):
{ "instances": [ { PREDICTION_DATA_ROW } ] }
リクエストを送信するには、次のいずれかのオプションを選択します。
curl
リクエスト本文を request.json
という名前のファイルに保存して、次のコマンドを実行します。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict"
PowerShell
リクエスト本文を request.json
という名前のファイルに保存して、次のコマンドを実行します。
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/endpoints/ENDPOINT_ID:predict" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
{ "predictions": [ [ { "value": 65.14233, "lower_bound": 4.6572, "upper_bound": 164.0279 } ] ], "deployedModelId": "DEPLOYED_MODEL_ID" }
Java
このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Java の設定手順を完了してください。詳細については、Vertex AI Java API のリファレンス ドキュメントをご覧ください。
Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
Node.js
このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Node.js の設定手順を完了してください。詳細については、Vertex AI Node.js API のリファレンス ドキュメントをご覧ください。
Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。
予測結果を解釈する
分類
分類モデルは信頼スコアを返します。
信頼スコアは、モデルによる各クラスまたはラベルとテスト項目の関連性の強さを表します。数値が大きいほど、その項目にラベルを適用するモデルの信頼度が高くなります。モデルの結果を受け入れるのに必要な信頼スコアの高さを決定します。
回帰
回帰モデルは予測値を返します。 宛先が BigQuery の場合、予測間隔も返されます。予測区間は、モデルが実際の結果を 95% の信頼度で含む値の範囲を示します。
デプロイされたモデルを使用してオンライン説明を取得する
説明(特徴アトリビューション)付きの予測をリクエストして、モデルがどのように予測を達成したかを確認できます。ローカル特徴量の重要度の値は、各特徴量が予測結果に及ぼした影響の度合いを示します。特徴アトリビューションは、Vertex Explainable AI による Vertex AI の予測に含まれています。
コンソール
Google Cloud コンソールを使用してオンライン予測をリクエストすると、ローカル特徴量の重要度の値が自動的に返されます。
事前入力された予測値を使用した場合、ローカル特徴量の重要度の値はすべてゼロになります。これは、事前入力値がベースラインの予測データなので、返される予測はベースラインの予測値になるためです。
gcloud
次の内容のファイルを
request.json
という名前で作成します。{ "instances": [ { PREDICTION_DATA_ROW } ] }
以下を置き換えます。
-
PREDICTION_DATA_ROW: キー(特徴の名前)と値(対応する特徴の値)を持つ JSON オブジェクト。たとえば、数値、文字列の配列、カテゴリを持つデータセットの場合、データの行は次のリクエストの例のようになります。
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
トレーニングに含まれるすべての特徴に対して値を指定する必要があります。予測に使用するデータの形式は、トレーニングに使用される形式と同じにする必要があります。詳細については、予測のデータ形式をご覧ください。
-
次のコマンドを実行します。
gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION_ID \ --json-request=request.json
次のように置き換えます。
- ENDPOINT_ID: エンドポイントの ID。
- LOCATION_ID: Vertex AI を使用するリージョン。
必要に応じて、
Endpoint
の特定のDeployedModel
に説明リクエストを送信する場合は、--deployed-model-id
フラグを指定します。gcloud ai endpoints explain ENDPOINT_ID \ --region=LOCATION \ --deployed-model-id=DEPLOYED_MODEL_ID \ --json-request=request.json
前述のプレースホルダのほかに、次のコードを置き換えます。
-
DEPLOYED_MODEL_ID(省略可): 解釈を取得する、デプロイ済みモデルの ID。この ID は
predict
メソッドのレスポンスに含まれます。特定のモデルの説明をリクエストする必要があり、複数のモデルが同じエンドポイントにデプロイされている場合は、この ID を使用して、その特定のモデルに説明が返されるようにします。
REST
次の例は、ローカル特徴アトリビューションを使用する表形式の分類モデルのオンライン予測リクエストを示しています。リクエストの形式は、回帰モデルと同じです。
リクエストのデータを使用する前に、次のように置き換えます。
-
LOCATION: エンドポイントが配置されているリージョン。例:
us-central1
- PROJECT: 実際のプロジェクト ID。
- ENDPOINT_ID: エンドポイントの ID。
-
PREDICTION_DATA_ROW: キー(特徴の名前)と値(対応する特徴の値)を持つ JSON オブジェクト。たとえば、数値、文字列の配列、カテゴリを持つデータセットの場合、データの行は次のリクエストの例のようになります。
"length":3.6, "material":"cotton", "tag_array": ["abc","def"]
トレーニングに含まれるすべての特徴に対して値を指定する必要があります。予測に使用するデータの形式は、トレーニングに使用される形式と同じにする必要があります。詳細については、予測のデータ形式をご覧ください。
-
DEPLOYED_MODEL_ID(省略可): 説明を取得する、デプロイ済みモデルの ID。この ID は
predict
メソッドのレスポンスに含まれます。特定のモデルの説明をリクエストする必要があり、複数のモデルが同じエンドポイントにデプロイされている場合は、この ID を使用して、その特定のモデルに説明が返されるようにします。
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain
リクエストの本文(JSON):
{ "instances": [ { PREDICTION_DATA_ROW } ], "deployedModelId": "DEPLOYED_MODEL_ID" }
リクエストを送信するには、次のいずれかのオプションを選択します。
curl
リクエスト本文を request.json
という名前のファイルに保存して、次のコマンドを実行します。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain"
PowerShell
リクエスト本文を request.json
という名前のファイルに保存して、次のコマンドを実行します。
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/endpoints/ENDPOINT_ID:explain" | Select-Object -Expand Content
Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。
以前に返された予測の説明を取得する
説明によってリソースの使用量が増加するため、具体的に必要になった場合に備えて説明のリクエストを用意しておくことをおすすめします。予測が外れ値であったり、意味がよくわからなかったりしたために、すでに取得した予測結果についての説明をリクエストしておくと役立つことがあります。
すべての予測が同じモデルから送信されている場合は、今回リクエストした説明とリクエスト データを再送するだけでかまいません。ただし、複数のモデルで予測を返す場合は、説明リクエストを正しいモデルに送信する必要があります。デプロイされたモデルの ID deployedModelID
をリクエストに含めることで、特定のモデルの説明を表示できます。この ID は、元の予測リクエストのレスポンスに含まれます。デプロイされたモデルの ID はモデル ID とは異なるため、注意が必要です。
説明の結果を解釈する
ローカル特徴量の重要度を計算するには、まず、ベースライン予測スコアを計算します。ベースライン値は、数値特徴の中央値とカテゴリ型の特徴のモードを使用して、トレーニング データから計算されます。ベースライン値から生成される予測が、ベースライン予測スコアです。ベースライン値はモデルに対して 1 回計算され、変更されることはありません。
特定の予測について、各特徴のローカル特徴量の重要度は、ベースラインの予測スコアと比較して、結果に特徴量がどのくらい加算または減算が生じたかを示します。特徴量の重要度の値をすべて合計すると、ベースラインの予測スコアと予測結果の差分と等しくなります。
分類モデルの場合、スコアは常に 0.0~1.0 にすべて含まれます。したがって、分類モデルのローカル特徴量の重要度の値は常に -1.0~1.0 になります。
特徴アトリビューション クエリの例と詳細については、分類と回帰のための特徴アトリビューションをご覧ください。予測と説明の出力例
分類
特徴量の重要度がある表形式の分類モデルのオンライン予測に対する戻りペイロードは、次の例のようになります。
0.928652400970459
という instanceOutputValue
は、信頼スコアが最大のスコアクラス(この場合は class_a
)です。baselineOutputValue
フィールドには、ベースライン予測スコア(0.808652400970459
)が含まれています。この結果に最も大きく影響した特徴は feature_3
でした。
{
"predictions": [
{
"scores": [
0.928652400970459,
0.071347599029541
],
"classes": [
"class_a",
"class_b"
]
}
]
"explanations": [
{
"attributions": [
{
"baselineOutputValue": 0.808652400970459,
"instanceOutputValue": 0.928652400970459,
"approximationError": 0.0058915703929231,
"featureAttributions": {
"feature_1": 0.012394922231235,
"feature_2": 0.050212341234556,
"feature_3": 0.057392736534209,
},
"outputIndex": [
0
],
"outputName": "scores"
}
],
}
]
"deployedModelId": "234567"
}
回帰
表形式の回帰モデルで、特徴の重要度を適用したオンライン予測を行うと、次の例のようなペイロードが返されます。
1795.1246466281819
の instanceOutputValue
は予測値で、lower_bound
フィールドと upper_bound
フィールドは 95% 信頼区間を表します。baselineOutputValue
フィールドには、ベースライン予測スコア(1788.7423095703125
)が含まれています。この結果に最も大きく影響した特徴は feature_3
でした。
{
"predictions": [
{
"value": 1795.1246466281819,
"lower_bound": 246.32196807861328,
"upper_bound": 8677.51904296875
}
]
"explanations": [
{
"attributions": [
{
"baselineOutputValue": 1788.7423095703125,
"instanceOutputValue": 1795.1246466281819,
"approximationError": 0.0038215703911553,
"featureAttributions": {
"feature_1": 0.123949222312359,
"feature_2": 0.802123412345569,
"feature_3": 5.456264423211472,
},
"outputIndex": [
-1
]
}
]
}
],
"deployedModelId": "345678"
}
次のステップ
- モデルのエクスポート方法を学習する。