このページでは、Google Cloud コンソールまたは Vertex AI API を使用して、トレーニングした分類モデルまたは回帰モデルのバッチ予測をリクエストする方法について説明します。
バッチ予測リクエストは非同期リクエストです(オンライン予測は同期リクエストです)。エンドポイントにモデルをデプロイすることなく、モデルリソースからバッチ予測を直接リクエストします。表形式のデータで、すぐにレスポンスを必要とせず 1 回のリクエストで累積データを処理したい場合は、バッチ予測を使用します。
バッチ予測リクエストでは、入力ソースと、Vertex AI が予測結果を格納する出力先を指定します。
準備
バッチ予測リクエストを行う前に、モデルをトレーニングする必要があります。
入力データ
バッチ予測リクエストの入力データは、モデルが予測を行う際に使用するデータです。分類モデルまたは回帰モデルの場合、入力データは次のいずれかの形式で指定できます。
- BigQuery テーブル
- Cloud Storage の CSV オブジェクト
入力データにも、モデルのトレーニングに使用した形式を使用することをおすすめします。たとえば、BigQuery のデータを使用してモデルをトレーニングした場合は、BigQuery テーブルをバッチ予測の入力として使用することをおすすめします。Vertex AI は、すべての CSV 入力フィールドを文字列として扱うため、トレーニング データ形式と入力データ形式を混在させると、エラーが発生することがあります。
データソースには、モデルのトレーニングに使用したすべての列が含まれている必要があります。ただし、順序は問いません。トレーニング データに含まれなかった列や、トレーニング データに含まれているがトレーニングへの使用からは除外された列を含めることができます。これらの追加の列は出力に含まれますが、予測結果には影響しません。
入力データの要件
BigQuery テーブル
入力として BigQuery テーブルを選択する場合は、次のことを確認する必要があります。
- BigQuery のデータソース テーブルは、100 GB 以下でなければなりません。
- テーブルが別のプロジェクトにある場合は、そのプロジェクトの Vertex AI サービス アカウントに
BigQuery Data Editor
ロールを指定する必要があります。
CSV ファイル
Cloud Storage の入力として CSV オブジェクトを選択する場合は、次のことを確認する必要があります。
- データソースの先頭は、列名を含むヘッダー行にする必要があります。
- 各データソース オブジェクトは 10 GB 以下でなければなりません。最大サイズの 100 GB に達するまで、複数のファイルを含められます。
- Cloud Storage バケットが別のプロジェクトにある場合は、そのプロジェクトの Vertex AI サービス アカウントに
Storage Object Creator
ロールを付与する必要があります。 - すべての文字列は二重引用符(")で囲む必要があります。
出力形式
バッチ予測リクエストの出力形式は、入力に使用した形式と同じにする必要はありません。たとえば、BigQuery テーブルを入力として使用した場合は、Cloud Storage の CSV オブジェクトに結果を出力できます。
モデルにバッチ予測リクエストを行う
バッチ予測リクエストを行うには、Google Cloud コンソールまたは Vertex AI API を使用します。入力データソースは、Cloud Storage バケットまたは BigQuery テーブルに格納された CSV オブジェクトです。入力として送信したデータの量によっては、バッチ予測タスクが完了するまでに時間がかかることがあります。
Google Cloud コンソール
Google Cloud コンソールを使用してバッチ予測をリクエストします。
- Google Cloud コンソールの [Vertex AI] セクションで、[バッチ予測] ページに移動します。
- [作成] をクリックして、[新しいバッチ予測] ウィンドウを開きます。
- [バッチ予測の定義] で、次の手順を完了します。
- バッチ予測の名前を入力します。
- [モデル名] で、このバッチ予測に使用するモデルの名前を選択します。
- [バージョン] で、このバッチ予測に使用するモデル バージョンを選択します。
- [ソースを選択] で、ソース入力データが Cloud Storage 上の CSV ファイルか BigQuery のテーブルかを選択します。
- CSV ファイルの場合は、CSV 入力ファイルのある Cloud Storage のロケーションを指定します。
- BigQuery テーブルの場合、テーブルが存在するプロジェクト ID、BigQuery データセット ID、BigQuery テーブルまたはビュー ID を指定します。
- [出力] で CSV または BigQuery を選択します。
- CSV の場合は、Vertex AI が出力を保存する Cloud Storage バケットを指定します。
- BigQuery の場合は、プロジェクト ID または既存のデータセットを指定します。
- プロジェクト ID を指定するには、[Google Cloud プロジェクト ID] フィールドにプロジェクト ID を入力します。Vertex AI により、新しい出力データセットが作成されます。
- 既存のデータセットを指定するには、[Google Cloud プロジェクト ID] フィールドに BigQuery パス(
bq://projectid.datasetid
など)を入力します。
- 省略可: バッチ予測の Model Monitoring 分析はプレビュー版として提供されています。スキュー検出構成をバッチ予測ジョブに追加する方法については、前提条件をご覧ください。
- [このバッチ予測のモデルのモニタリングを有効にする] をクリックしてオンにします。
- トレーニング データソースを選択します。選択したトレーニング データソースのデータパスまたは場所を入力します。
- (省略可)[アラートのしきい値] で、アラートをトリガーするしきい値を指定します。
- [通知メール] に、モデルがアラートのしきい値を超えたときにアラートを受け取るメールアドレスを 1 つ以上入力します。
- 省略可: 通知チャンネルの場合、モデルがアラートのしきい値を超えたときにアラートを受け取るには、Cloud Monitoring チャンネルを追加します。[通知チャンネルを管理] をクリックして、既存の Cloud Monitoring チャンネルを選択するか、新しい Cloud Monitoring チャネルを作成できます。コンソールでは、PagerDuty、Slack、Pub/Sub 通知チャネルがサポートされています。
- [作成] をクリックします。
API: BigQuery
REST
バッチ予測をリクエストするには、batchPredictionJobs.create メソッドを使用します。
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: モデルを保存し、バッチ予測ジョブを実行するリージョン。例:
us-central1
- PROJECT_ID: 実際のプロジェクト ID
- BATCH_JOB_NAME: バッチジョブの表示名
- MODEL_ID: 予測に使用するモデルの ID
-
INPUT_URI: BigQuery データソースへの参照。フォームで次の操作を行います。
bq://bqprojectId.bqDatasetId.bqTableId
-
OUTPUT_URI: BigQuery の宛先への参照(予測が作成される場所)。プロジェクト ID と、必要に応じて既存のデータセット ID を指定します。プロジェクト ID のみを指定した場合は、Vertex AI によって新しい出力データセットが作成されます。次の形式を使用します。
bq://bqprojectId.bqDatasetId
- MACHINE_TYPE: このバッチ予測ジョブに使用されるマシンリソース。詳細
- STARTING_REPLICA_COUNT: このバッチ予測ジョブの開始ノード数。ノード数は負荷に応じてノードの最大数まで増減できますが、この数を下回ることはできません。
- MAX_REPLICA_COUNT: このバッチ予測ジョブの最大ノード数。ノード数は負荷に応じて増減できますが、最大値を超えることはできません。これは省略可能で、デフォルトは 10 です。
HTTP メソッドと URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs
リクエストの本文(JSON):
{ "displayName": "BATCH_JOB_NAME", "model": "MODEL_ID", "inputConfig": { "instancesFormat": "bigquery", "bigquerySource": { "inputUri": "INPUT_URI" } }, "outputConfig": { "predictionsFormat": "bigquery", "bigqueryDestination": { "outputUri": "OUTPUT_URI" } }, "dedicatedResources": { "machineSpec": { "machineType": "MACHINE_TYPE", "acceleratorCount": "0" }, "startingReplicaCount": STARTING_REPLICA_COUNT, "maxReplicaCount": MAX_REPLICA_COUNT }, }
リクエストを送信するには、次のいずれかのオプションを選択します。
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/batchPredictionJobs"
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/batchPredictionJobs" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs/67890", "displayName": "batch_job_1 202005291958", "model": "projects/12345/locations/us-central1/models/5678", "state": "JOB_STATE_PENDING", "inputConfig": { "instancesFormat": "bigquery", "bigquerySource": { "inputUri": "INPUT_URI" } }, "outputConfig": { "predictionsFormat": "bigquery", "bigqueryDestination": { "outputUri": bq://12345 } }, "dedicatedResources": { "machineSpec": { "machineType": "n1-standard-32", "acceleratorCount": "0" }, "startingReplicaCount": 2, "maxReplicaCount": 6 }, "manualBatchTuningParameters": { "batchSize": 4 }, "generateExplanation": false, "outputInfo": { "bigqueryOutputDataset": "bq://12345.reg_model_2020_10_02_06_04 } "state": "JOB_STATE_PENDING", "createTime": "2020-09-30T02:58:44.341643Z", "updateTime": "2020-09-30T02:58:44.341643Z", }
Java
このサンプルを試す前に、Vertex AI クイックスタート: クライアント ライブラリの使用にある Java の設定手順を完了してください。詳細については、Vertex AI Java API のリファレンス ドキュメントをご覧ください。
Vertex AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。
次のサンプルでは、INSTANCES_FORMAT と PREDICTIONS_FORMAT を「bigquery」に置き換えます。他のプレースホルダを置き換える方法については、このセクションの「REST とコマンドライン」タブをご覧ください。Python
Vertex AI SDK for Python のインストールまたは更新の方法については、Vertex AI SDK for Python をインストールするをご覧ください。 詳細については、Python API リファレンス ドキュメントをご覧ください。
次のサンプルでは、instances_format パラメータと predictions_format パラメータを bigquery に設定します。他のパラメータの設定方法については、このセクションの「REST とコマンドライン」タブをご覧ください。API: Cloud Storage
REST
バッチ予測をリクエストするには、batchPredictionJobs.create メソッドを使用します。
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION_ID: モデルを保存し、バッチ予測ジョブを実行するリージョン。例:
us-central1
- PROJECT_ID: 実際のプロジェクト ID
- BATCH_JOB_NAME: バッチジョブの表示名
- MODEL_ID: 予測に使用するモデルの ID
-
URI: トレーニング データを含む Cloud Storage バケットへのパス(URI)。複数指定することも可能です。各 URI の形式は次のとおりです。
gs://bucketName/pathToFileName
-
OUTPUT_URI_PREFIX: 予測が作成される Cloud Storage の宛先のパス。Vertex AI は、このパスのタイムスタンプ付きのサブディレクトリにバッチ予測を書き込みます。この値は、次の形式の文字列に設定します。
gs://bucketName/pathToOutputDirectory
- MACHINE_TYPE: このバッチ予測ジョブに使用されるマシンリソース。詳細
- STARTING_REPLICA_COUNT: このバッチ予測ジョブの開始ノード数。ノード数は負荷に応じてノードの最大数まで増減できますが、この数を下回ることはできません。
- MAX_REPLICA_COUNT: このバッチ予測ジョブの最大ノード数。ノード数は負荷に応じて増減できますが、最大値を超えることはできません。これは省略可能で、デフォルトは 10 です。
HTTP メソッドと URL:
POST https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/batchPredictionJobs
リクエストの本文(JSON):
{ "displayName": "BATCH_JOB_NAME", "model": "MODEL_ID", "inputConfig": { "instancesFormat": "csv", "gcsSource": { "uris": [ URI1,... ] }, }, "outputConfig": { "predictionsFormat": "csv", "gcsDestination": { "outputUriPrefix": "OUTPUT_URI_PREFIX" } }, "dedicatedResources": { "machineSpec": { "machineType": "MACHINE_TYPE", "acceleratorCount": "0" }, "startingReplicaCount": STARTING_REPLICA_COUNT, "maxReplicaCount": MAX_REPLICA_COUNT }, }
リクエストを送信するには、次のいずれかのオプションを選択します。
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/batchPredictionJobs"
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/batchPredictionJobs" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
{ "name": "projects/PROJECT__ID/locations/LOCATION_ID/batchPredictionJobs/67890", "displayName": "batch_job_1 202005291958", "model": "projects/12345/locations/us-central1/models/5678", "state": "JOB_STATE_PENDING", "inputConfig": { "instancesFormat": "csv", "gcsSource": { "uris": [ "gs://bp_bucket/reg_mode_test" ] } }, "outputConfig": { "predictionsFormat": "csv", "gcsDestination": { "outputUriPrefix": "OUTPUT_URI_PREFIX" } }, "dedicatedResources": { "machineSpec": { "machineType": "n1-standard-32", "acceleratorCount": "0" }, "startingReplicaCount": 2, "maxReplicaCount": 6 }, "manualBatchTuningParameters": { "batchSize": 4 } "outputInfo": { "gcsOutputDataset": "OUTPUT_URI_PREFIX/prediction-batch_job_1 202005291958-2020-09-30T02:58:44.341643Z" } "state": "JOB_STATE_PENDING", "createTime": "2020-09-30T02:58:44.341643Z", "updateTime": "2020-09-30T02:58:44.341643Z", }
バッチ予測の結果を取得する
Vertex AI は、バッチ予測の出力を指定の宛先(BigQuery または Cloud Storage)に送信します。
BigQuery
出力データセット
BigQuery を使用している場合、バッチ予測の出力は出力データセットに保存されます。Vertex AI にデータセットを提供した場合、データセットの名前(BQ_DATASET_NAME)は前に指定した名前です。出力データセットを指定しなかった場合は、Vertex AI によって作成されます。名前(BQ_DATASET_NAME)を確認する手順は次のとおりです。
- Google Cloud コンソールで、[Vertex AI] の [バッチ予測] ページに移動します。
- 作成した予測を選択します。
-
出力データセットは [エクスポート ロケーション] に表示されます。データセット名は
prediction_MODEL_NAME_TIMESTAMP
のように構成されています。
出力データセットには、次の 3 つの出力テーブルのうち 1 つ以上が含まれます。
-
予測テーブル
このテーブルには、予測がリクエストされた入力データのすべての行が含まれています(TARGET_COLUMN_NAME = null)。
-
エラーテーブル
このテーブルには、バッチ予測中に発生した重大でないエラーの行が含まれています。重大でないエラーは、Vertex AI が予測を返せなかった入力データの行に対応しています。
予測テーブル
テーブルの名前(BQ_PREDICTIONS_TABLE_NAME)は、「predictions_」にバッチ予測ジョブの開始時のタイムスタンプが追加された形式(predictions_TIMESTAMP
)になっています。
予測を取得するには、BigQuery ページに移動します。
クエリの形式はモデルタイプによって異なります。分類:
SELECT predicted_TARGET_COLUMN_NAME.classes AS classes, predicted_TARGET_COLUMN_NAME.scores AS scores FROM BQ_DATASET_NAME.BQ_PREDICTIONS_TABLE_NAME
classes
は可能性のあるクラスのリストで、scores
は対応する信頼度スコアです。
回帰:
SELECT predicted_TARGET_COLUMN_NAME.value FROM BQ_DATASET_NAME.BQ_PREDICTIONS_TABLE_NAME
モデルで確立的推論を使用する場合、predicted_TARGET_COLUMN_NAME.value
には最適化目標の最小化が含まれています。たとえば、最適化目標が minimize-rmse
の場合、predicted_TARGET_COLUMN_NAME.value
には平均値が含まれます。minimize-mae
の場合、predicted_TARGET_COLUMN_NAME.value
には中央値が含まれます。
モデルで変位値を使用する確立的推論を使用する場合、Vertex AI では、最適化目標の最小化に加えて、分位値や予測が提供されます。分位点の値はモデルのトレーニング中に設定されます。分位点の予測は、分位点の値に関連付けられた予測値です。
特徴量の重要度は予測テーブルでも確認できます。特徴 BQ_FEATURE_NAME のアトリビューションにアクセスするには、次のクエリを実行します
SELECT predicted_TARGET_COLUMN_NAME.feature_importance.BQ_FEATURE_NAME FROM BQ_DATASET_NAME.BQ_PREDICTIONS_TABLE_NAME
エラーテーブル
テーブルの名前(BQ_ERRORS_TABLE_NAME)は、バッチ予測ジョブの開始時のタイムスタンプにerrors_
が追加された形式になっています。(errors_TIMESTAMP
)
エラー検証テーブルを取得するには:
-
コンソールで、[BigQuery] ページに移動します。
-
次のクエリを実行します。
SELECT * FROM BQ_DATASET_NAME.BQ_ERRORS_TABLE_NAME
- errors_TARGET_COLUMN_NAME.code
- errors_TARGET_COLUMN_NAME.message
Cloud Storage
Cloud Storage を出力先に指定した場合、バッチ予測リクエストの結果は、指定したバケット内の新しいフォルダに CSV オブジェクトとして返されます。フォルダの名前は、先頭に「prediction-」が追加され、バッチ予測ジョブの開始時のタイムスタンプが付加されたモデルの名前です。Cloud Storage フォルダ名は、モデルの [バッチ予測] タブで確認できます。
Cloud Storage フォルダには、次の 2 種類のオブジェクトが含まれます。-
予測オブジェクト
予測オブジェクトの名前は Predictions_1.csv、predictions_2.csv などです。予測ファイルには、列名が表示されたヘッダー行と返されたすべての予測の行が含まれています。予測オブジェクトでは、Vertex AI が予測データを返し、モデルタイプに応じて予測結果の新しい列が 1 つ以上作成されます。
-
分類: ターゲット列の各潜在値に対して、
TARGET_COLUMN_NAME_VALUE_score
という列が結果に追加されます。この列には、その値のスコアまたは信頼度の推定値が含まれます。 -
回帰: 行の予測値が、
predicted_TARGET_COLUMN_NAME
という列で返されます。CSV 出力の予測間隔は返されません。
-
分類: ターゲット列の各潜在値に対して、
-
エラー オブジェクト
エラー オブジェクトの名前は errors_1.csv、errors_2.csv などです。ヘッダー行と、Vertex AI が予測を返せなかった入力データ内の各行(null 値を許容しない特徴が null であった場合など)が含まれます。
注: 結果が大きい場合は、複数のオブジェクトに分割されます。
特徴の重要度は、Cloud Storage で返されるバッチ予測結果では使用できません。
予測結果を解釈する
分類
分類モデルは信頼スコアを返します。
信頼スコアは、モデルによる各クラスまたはラベルとテスト項目の関連性の強さを表します。数値が大きいほど、その項目にラベルを適用するモデルの信頼度が高くなります。モデルの結果を受け入れるのに必要な信頼スコアの高さを決定します。
回帰
回帰モデルは予測値を返します。
モデルで確立的推論を使用する場合、value
フィールドには最適化目標の最小化が含まれています。たとえば、最適化目標が minimize-rmse
の場合、value
フィールドには平均値が含まれます。minimize-mae
の場合、value
フィールドには中央値が含まれます。
モデルで変位値を使用する確立的推論を使用する場合、Vertex AI では、最適化目標の最小化に加えて、分位値や予測が提供されます。分位点の値はモデルのトレーニング中に設定されます。分位点の予測は、分位点の値に関連付けられた予測値です。
BigQuery に保存されたバッチ予測結果の場合、TabNet は、どの特徴が意思決定に役立ったかをユーザーが把握できるようにすることで、モデルを本質的に解釈可能なものにします。このアルゴリズムはアテンションを利用します。アテンションは、一部の特徴の影響を選択的に強化し、加重平均を使用して他の特徴の影響を軽減することを学習します。特定の決定を行う場合、TabNet は各特長に設定する重要度を段階的に決定します。その後、各ステップを組み合わせて最終的な予測を作成します。アテンションは乗算です。値が大きいほど、特徴が予測でより大きな役割を果たしていることを示します。値が 0 の場合、その決定で特徴がロールを果たしていないことを意味します。 TabNet は複数の決定ステップを使用するため、すべてのステップにわたって特徴に設定されたアテンションは、適切なスケーリング後に線形結合されます。TabNet のすべての決定ステップにわたるこの線形結合は、TabNet が提供する総体的な特徴の重要度です。
次のステップ
- モデルのエクスポート方法を確認する。
- バッチ予測の料金について学習する。