カスタム トレーニング モデルで Vertex Explainable AI を使用するには、説明をリクエストする Model
リソースの作成時、モデルのデプロイ時、またはバッチ説明ジョブの送信時に特定のオプションを構成する必要があります。このページでは、これらのオプションの構成について説明します。
AutoML 表形式のモデルで Vertex Explainable AI を使用する場合は、構成を行う必要はありません。Vertex AI は Vertex Explainable AI のモデルを自動的に構成します。このドキュメントをスキップして、説明の取得をご覧ください。
説明を構成するタイミングと場所
説明は、モデルの作成時またはインポート時に構成します。まだ説明を構成していなくても、作成済みのモデルに説明を構成することもできます。
モデルの作成またはインポート時に説明を構成する
Model
を作成またはインポートするときに、Model
の explanationSpec
フィールドを使用して、すべての説明のデフォルト構成を設定できます。
Vertex AI では、次の方法でカスタム トレーニング済みの Model
を作成できます。
Model
を Vertex AI Model Registry にインポートまたは登録する。Model
をインポートするカスタムTrainingPipeline
リソースを作成する。- BigQuery ML モデルを作成し、
CREATE MODEL
構文でオプションのmodel_registry
設定を指定する。この設定では、モデルが Vertex AI Model Registry に自動的に登録され、そのexplanationSpec
が構成されます。
いずれの場合も、Model
を構成して Vertex Explainable AI をサポートできます。このドキュメントの例では、Model
をインポートしていることを前提としています。TrainingPipeline
を使用してカスタム トレーニングの Model
を作成するときに Vertex Explainable AI を構成するには、このドキュメントで説明する設定を TrainingPipeline
の modelToUpload
フィールドで使用します。
モデルのデプロイ時またはバッチ予測の取得時に説明を構成する
Model
を Endpoint
リソースにデプロイすると、次のいずれかが可能になります。
- 説明を構成する(モデルに説明用に構成済みかどうか)。これは、説明を取得する予定がなかった(モデルの作成時に
explanationSpec
フィールドを省略した)ものの、後でモデルの説明を取得する場合や、一部の説明設定をオーバーライドする場合に便利です。 - 説明を無効にする。これは、モデルが説明用に構成されているものの、エンドポイントから説明を取得する予定はない場合に便利です。エンドポイントにモデルをデプロイするときに説明を無効にするには、Cloud コンソールで説明可能性のオプションのチェックボックスをオフにするか、
DeployedModel.disableExplanations
をtrue
に設定します。
同様に、Model
からバッチ予測を取得する場合は、BatchPredictionJob.explanationSpec
フィールドを入力して説明を構成することも、BatchPredictionJob.generateExplanation
を false
に設定して説明を無効にすることもできます。
オンライン説明を取得するときに構成をオーバーライドする
説明設定を含む Model
を作成またはインポートしたかどうか、デプロイ時に説明設定を構成したかどうかにかかわらず、オンライン説明を取得するときに、Model
の説明の初期設定をオーバーライドできます。
explain
リクエストを Vertex AI に送信すると、以前に Model
または DeployedModel
に設定した説明構成の一部をオーバーライドできます。
explain
リクエストで、次のフィールドをオーバーライドできます。
- カスタム トレーニング モデルの入力ベースライン
- 画像モデルの可視化構成
ExplanationParameters
(method
は除く)
説明リクエストの explanationSpecOverride フィールドで、これらの設定をオーバーライドします。
explanationSpec
フィールドを使用してモデルをインポートする
予測にビルド済みコンテナを使用するのか、カスタム コンテナを使用するのかによって、ExplanationSpec
に指定する詳細が少し異なります。使用しているコンテナに対応するタブを選択してください。
TensorFlow のビルド済みコンテナ
Vertex Explainable AI には、次のいずれかのアトリビューション方式を使用できます。Model
に適切な方法については、特徴アトリビューション方式の比較をご覧ください。
サンプリングされた Shapley
Model
の作成またはインポートに使用するツールに応じて、次のいずれかのタブを選択してください。
コンソール
ガイドに沿って、Google Cloud コンソールを使用してモデルをインポートします。説明可能性のステップが表示されたら、次の手順を行います。
特徴アトリビューション方式として、サンプリングされた Shapely(表形式モデル用)を選択します。
パス数に、サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数を設定します。これは、
[1, 50]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
25
を試してください。モデルの各入力特徴を構成します。
-
入力特徴名を入力します。
-
必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン(画像データの黒い画像)を選択します。
-
TensorFlow モデルをインポートする場合は、追加の入力フィールドがあります。
入力テンソル名を入力します。
必要に応じて、インデックスのテンソル名または高密度の形状テンソル名を入力します。
ここではモダリティを更新できません。表形式モデルの場合は
NUMERIC
、画像モデルの場合はIMAGE
に自動的に設定されます。必要に応じて [エンコード] フィールドを設定します。設定しない場合、デフォルトで
IDENTITY
になります。該当する場合、[グループ名] フィールドを設定します。
-
TensorFlow モデルをインポートする場合は、出力フィールドを指定します。
- 特徴の出力名を設定します。
- 特徴の出力テンソル名を設定します。
- 必要に応じて、インデックスの表示名のマッピングを設定します。
- 必要に応じて、表示名のマッピングキーを設定します。
説明可能性の構成が完了したら、[インポート] ボタンをクリックします。
gcloud
TensorFlow 2 の場合、
ExplanationMetadata
は省略可能です。次の
ExplanationMetadata
をローカル環境の JSON ファイルに書き込みます。ファイル名は重要ではありませんが、この例では、explanation-metadata.json
という名前を使用しています。explanation-metadata.json
{ "inputs": { "FEATURE_NAME": { "inputTensorName": "INPUT_TENSOR_NAME", } }, "outputs": { "OUTPUT_NAME": { "outputTensorName": "OUTPUT_TENSOR_NAME" } } }
次のように置き換えます。
- FEATURE_NAME: 入力特徴の覚えやすい名前。
- INPUT_TENSOR_NAME: TensorFlow の入力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
- OUTPUT_NAME: モデル出力の覚えやすい名前。
- OUTPUT_TENSOR_NAME: TensorFlow の出力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
必要に応じて、入力ベースラインを
ExplanationMetadata
に追加できます。追加しない場合は、Vertex AI がModel
の入力ベースラインを選択します。次のコマンドを実行して、Vertex Explainable AI をサポートする
Model
リソースを作成します。Vertex Explainable AI に関連するフラグはハイライト表示されています。gcloud ai models upload \ --region=LOCATION \ --display-name=MODEL_NAME \ --container-image-uri=IMAGE_URI \ --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \ --explanation-method=sampled-shapley \ --explanation-path-count=PATH_COUNT \ --explanation-metadata-file=explanation-metadata.json
次のように置き換えます。
- IMAGE_URI: 予測に使用する TensorFlow のビルド済みコンテナの URI。
-
PATH_COUNT: サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数。
[1, 50]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
25
を試してください。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- IMAGE_URI: 予測に使用する TensorFlow のビルド済みコンテナの URI。
-
PATH_COUNT: サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数。
[1, 50]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
25
を試してください。 - FEATURE_NAME: 入力特徴の覚えやすい名前。
- INPUT_TENSOR_NAME: TensorFlow の入力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
- OUTPUT_NAME: モデル出力の覚えやすい名前。
- OUTPUT_TENSOR_NAME: TensorFlow の出力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
他のプレースホルダの適切な値については、upload
とモデルのインポートをご覧ください。
必要に応じて、入力ベースラインを ExplanationMetadata
に追加できます。追加しない場合は、Vertex AI が Model
の入力ベースラインを選択します。
TensorFlow 2 モデルの場合、metadata
フィールドは省略可能です。省略した場合、Vertex AI はモデルから inputs
と outputs
を自動的に推測します。
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload
リクエストの本文(JSON):
{ "model": { "displayName": "MODEL_NAME", "containerSpec": { "imageUri": "IMAGE_URI" }, "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY", "explanationSpec": { "parameters": { "sampledShapleyAttribution": { "pathCount": PATH_COUNT } }, "metadata": { "inputs": { "FEATURE_NAME": { "inputTensorName": "INPUT_TENSOR_NAME", } }, "outputs": { "OUTPUT_NAME": { "outputTensorName": "OUTPUT_TENSOR_NAME" } } } } } }
リクエストを送信するには、次のいずれかのオプションを選択します。
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_ID/locations/LOCATION/models:upload"
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_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content
統合勾配
Model
の作成またはインポートに使用するツールに応じて、次のいずれかのタブを選択してください。
コンソール
ガイドに沿って、Google Cloud コンソールを使用してモデルをインポートします。説明可能性のステップが表示されたら、次の手順を行います。
特徴アトリビューション方式の場合は、[統合勾配(表形式モデル用)] または [統合勾配(画像分類モデル用)] を選択します。
画像分類モデルをインポートする場合は、次の操作を行います。
[可視化タイプ] と [カラーマップ] を設定します。
[下位をクリップ]、[上位をクリップ]、[オーバーレイのタイプ]、[積分ステップの数] は、デフォルトの設定にしておくことができます。
詳しくは、可視化設定をご覧ください。
特徴アトリビューションの計算でパス積分を概算するためのステップ数を設定します。これは、
[1, 100]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
50
を試してください。モデルの各入力特徴を構成します。
-
入力特徴名を入力します。
-
必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン(画像データの黒い画像)を選択します。
-
TensorFlow モデルをインポートする場合は、追加の入力フィールドがあります。
入力テンソル名を入力します。
必要に応じて、インデックスのテンソル名または高密度の形状テンソル名を入力します。
ここではモダリティを更新できません。表形式モデルの場合は
NUMERIC
、画像モデルの場合はIMAGE
に自動的に設定されます。必要に応じて [エンコード] フィールドを設定します。設定しない場合、デフォルトで
IDENTITY
になります。該当する場合、[グループ名] フィールドを設定します。
-
TensorFlow モデルをインポートする場合は、出力フィールドを指定します。
- 特徴の出力名を設定します。
- 特徴の出力テンソル名を設定します。
- 必要に応じて、インデックスの表示名のマッピングを設定します。
- 必要に応じて、表示名のマッピングキーを設定します。
説明可能性の構成が完了したら、[インポート] ボタンをクリックします。
gcloud
TensorFlow 2 の場合、
ExplanationMetadata
は省略可能です。次の
ExplanationMetadata
をローカル環境の JSON ファイルに書き込みます。ファイル名は重要ではありませんが、この例では、explanation-metadata.json
という名前を使用しています。explanation-metadata.json
{ "inputs": { "FEATURE_NAME": { "inputTensorName": "INPUT_TENSOR_NAME", "modality": "MODALITY", "visualization": VISUALIZATION_SETTINGS } }, "outputs": { "OUTPUT_NAME": { "outputTensorName": "OUTPUT_TENSOR_NAME" } } }
次のように置き換えます。
- FEATURE_NAME: 入力特徴の覚えやすい名前。
- INPUT_TENSOR_NAME: TensorFlow の入力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
-
MODALITY:
Model
が入力として画像を受け入れる場合はimage
、Model
が入力として表形式データを受け入れる場合はnumeric
。デフォルトはnumeric
です。 -
VIZUALIZATION_OPTIONS: 説明の可視化オプション。このフィールドの設定方法については、画像データの可視化設定の構成をご覧ください。
modality
フィールドを省略した場合、またはmodality
フィールドをnumeric
に設定した場合は、visualization
フィールド全体を省略します。 - OUTPUT_NAME: モデル出力の覚えやすい名前。
- OUTPUT_TENSOR_NAME: TensorFlow の出力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
必要に応じて、入力ベースラインを
ExplanationMetadata
に追加できます。追加しない場合は、Vertex AI がModel
の入力ベースラインを選択します。次のコマンドを実行して、Vertex Explainable AI をサポートする
Model
リソースを作成します。Vertex Explainable AI に関連するフラグはハイライト表示されています。gcloud ai models upload \ --region=LOCATION \ --display-name=MODEL_NAME \ --container-image-uri=IMAGE_URI \ --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \ --explanation-method=integrated-gradients \ --explanation-step-count=STEP_COUNT \ --explanation-metadata-file=explanation-metadata.json
次のように置き換えます。
- IMAGE_URI: 予測に使用する TensorFlow のビルド済みコンテナの URI。
-
STEP_COUNT: 特徴アトリビューションの計算でパス積分を概算するためのステップ数。
[1, 100]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
50
を試してください。
他のプレースホルダの適切な値については、
upload
とモデルのインポートをご覧ください。必要に応じてフラグを追加して勾配の SmoothGrad 近似値を構成できます。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- IMAGE_URI: 予測に使用する TensorFlow のビルド済みコンテナの URI。
-
STEP_COUNT: 特徴アトリビューションの計算でパス積分を概算するためのステップ数。
[1, 100]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
50
を試してください。 - FEATURE_NAME: 入力特徴の覚えやすい名前。
- INPUT_TENSOR_NAME: TensorFlow の入力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
-
MODALITY:
Model
が入力として画像を受け入れる場合はimage
、Model
が入力として表形式データを受け入れる場合はnumeric
。デフォルトはnumeric
です。 -
VIZUALIZATION_OPTIONS: 説明の可視化オプション。このフィールドの設定方法については、画像データの可視化設定の構成をご覧ください。
modality
フィールドを省略した場合、またはmodality
フィールドをnumeric
に設定した場合は、visualization
フィールド全体を省略します。 - OUTPUT_NAME: モデル出力の覚えやすい名前。
- OUTPUT_TENSOR_NAME: TensorFlow の出力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
他のプレースホルダの適切な値については、upload
とモデルのインポートをご覧ください。
必要に応じて、入力ベースラインを ExplanationMetadata
に追加できます。追加しない場合は、Vertex AI が Model
の入力ベースラインを選択します。
必要に応じて、ExplanationParameters
に SmoothGrad 近似値を構成するフィールドを追加できます。
TensorFlow 2 モデルの場合、metadata
フィールドは省略可能です。省略した場合、Vertex AI はモデルから inputs
と outputs
を自動的に推測します。
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload
リクエストの本文(JSON):
{ "model": { "displayName": "MODEL_NAME", "containerSpec": { "imageUri": "IMAGE_URI" }, "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY", "explanationSpec": { "parameters": { "integratedGradientsAttribution": { "stepCount": STEP_COUNT } }, "metadata": { "inputs": { "FEATURE_NAME": { "inputTensorName": "INPUT_TENSOR_NAME", "modality": "MODALITY", "visualization": VISUALIZATION_SETTINGS } }, "outputs": { "OUTPUT_NAME": { "outputTensorName": "OUTPUT_TENSOR_NAME" } } } } } }
リクエストを送信するには、次のいずれかのオプションを選択します。
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_ID/locations/LOCATION/models:upload"
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_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content
XRAI
Model
の作成またはインポートに使用するツールに応じて、次のいずれかのタブを選択してください。
コンソール
ガイドに沿って、Google Cloud コンソールを使用してモデルをインポートします。説明可能性のステップが表示されたら、次の手順を行います。
特徴アトリビューション方式として [XRAI(画像分類モデル用)] を選択します。
次の可視化オプションを設定します。
[カラーマップ] を設定します。
[下位をクリップ]、[上位をクリップ]、[オーバーレイのタイプ]、[積分ステップの数] は、デフォルトの設定にしておくことができます。
詳しくは、可視化設定をご覧ください。
特徴アトリビューションの計算でパス積分を概算するためのステップ数を設定します。これは、
[1, 100]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
50
を試してください。モデルの各入力特徴を構成します。
-
入力特徴名を入力します。
-
必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン(画像データの黒い画像)を選択します。
-
TensorFlow モデルをインポートする場合は、追加の入力フィールドがあります。
入力テンソル名を入力します。
必要に応じて、インデックスのテンソル名または高密度の形状テンソル名を入力します。
ここではモダリティを更新できません。表形式モデルの場合は
NUMERIC
、画像モデルの場合はIMAGE
に自動的に設定されます。必要に応じて [エンコード] フィールドを設定します。設定しない場合、デフォルトで
IDENTITY
になります。該当する場合、[グループ名] フィールドを設定します。
-
TensorFlow モデルをインポートする場合は、出力フィールドを指定します。
- 特徴の出力名を設定します。
- 特徴の出力テンソル名を設定します。
- 必要に応じて、インデックスの表示名のマッピングを設定します。
- 必要に応じて、表示名のマッピングキーを設定します。
説明可能性の構成が完了したら、[インポート] ボタンをクリックします。
gcloud
TensorFlow 2 の場合、
ExplanationMetadata
は省略可能です。次の
ExplanationMetadata
をローカル環境の JSON ファイルに書き込みます。ファイル名は重要ではありませんが、この例では、explanation-metadata.json
という名前を使用しています。explanation-metadata.json
{ "inputs": { "FEATURE_NAME": { "inputTensorName": "INPUT_TENSOR_NAME", "modality": "image", "visualization": VISUALIZATION_SETTINGS } }, "outputs": { "OUTPUT_NAME": { "outputTensorName": "OUTPUT_TENSOR_NAME" } } }
次のように置き換えます。
- FEATURE_NAME: 入力特徴の覚えやすい名前。
- INPUT_TENSOR_NAME: TensorFlow の入力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
- VIZUALIZATION_OPTIONS: 説明の可視化オプション。このフィールドの設定方法については、画像データの可視化設定の構成をご覧ください。
- OUTPUT_NAME: モデル出力の覚えやすい名前。
- OUTPUT_TENSOR_NAME: TensorFlow の出力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
必要に応じて、入力ベースラインを
ExplanationMetadata
に追加できます。追加しない場合は、Vertex AI がModel
の入力ベースラインを選択します。次のコマンドを実行して、Vertex Explainable AI をサポートする
Model
リソースを作成します。Vertex Explainable AI に関連するフラグはハイライト表示されています。gcloud ai models upload \ --region=LOCATION \ --display-name=MODEL_NAME \ --container-image-uri=IMAGE_URI \ --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \ --explanation-method=xrai \ --explanation-step-count=STEP_COUNT \ --explanation-metadata-file=explanation-metadata.json
次のように置き換えます。
- IMAGE_URI: 予測に使用する TensorFlow のビルド済みコンテナの URI。
-
STEP_COUNT: 特徴アトリビューションの計算でパス積分を概算するためのステップ数。
[1, 100]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
50
を試してください。
他のプレースホルダの適切な値については、
upload
とモデルのインポートをご覧ください。必要に応じてフラグを追加して勾配の SmoothGrad 近似値を構成できます。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- IMAGE_URI: 予測に使用する TensorFlow のビルド済みコンテナの URI。
-
STEP_COUNT: 特徴アトリビューションの計算でパス積分を概算するためのステップ数。
[1, 100]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
50
を試してください。 - FEATURE_NAME: 入力特徴の覚えやすい名前。
- INPUT_TENSOR_NAME: TensorFlow の入力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
- VIZUALIZATION_OPTIONS: 説明の可視化オプション。このフィールドの設定方法については、画像データの可視化設定の構成をご覧ください。
- OUTPUT_NAME: モデル出力の覚えやすい名前。
- OUTPUT_TENSOR_NAME: TensorFlow の出力テンソルの名前。このフィールドの正しい値については、Vertex Explainable AI での TensorFlow の使用をご覧ください。
他のプレースホルダの適切な値については、upload
とモデルのインポートをご覧ください。
必要に応じて、入力ベースラインを ExplanationMetadata
に追加できます。追加しない場合は、Vertex AI が Model
の入力ベースラインを選択します。
必要に応じて、ExplanationParameters
に SmoothGrad 近似値を構成するフィールドを追加できます。
TensorFlow 2 モデルの場合、metadata
フィールドは省略可能です。省略した場合、Vertex AI はモデルから inputs
と outputs
を自動的に推測します。
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload
リクエストの本文(JSON):
{ "model": { "displayName": "MODEL_NAME", "containerSpec": { "imageUri": "IMAGE_URI" }, "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY", "explanationSpec": { "parameters": { "xraiAttribution": { "stepCount": STEP_COUNT } }, "metadata": { "inputs": { "FEATURE_NAME": { "inputTensorName": "INPUT_TENSOR_NAME", "modality": "image", "visualization": VISUALIZATION_SETTINGS } }, "outputs": { "OUTPUT_NAME": { "outputTensorName": "OUTPUT_TENSOR_NAME" } } } } } }
リクエストを送信するには、次のいずれかのオプションを選択します。
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_ID/locations/LOCATION/models:upload"
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_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content
scikit-learn と XGBoost のビルド済みコンテナ
Model
が入力として表形式データを受け入れ、予測用にビルド済みの scikit-learn または XGBoost コンテナを使用して予測を行う場合は、説明にサンプリングされた Shapley のアトリビューション方式を使用するように構成できます。
Model
の作成またはインポートに使用するツールに応じて、次のいずれかのタブを選択してください。
コンソール
ガイドに沿って、Google Cloud コンソールを使用してモデルをインポートします。説明可能性のステップが表示されたら、次の手順を行います。
特徴アトリビューション方式として、サンプリングされた Shapely(表形式モデル用)を選択します。
パス数に、サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数を設定します。これは、
[1, 50]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
25
を試してください。モデルの各入力特徴を構成します。
入力特徴名を入力します。
モデル アーティファクトに特徴名が含まれていない場合、Vertex AI は指定された入力特徴名をモデルにマッピングできません。その場合は、
input_features
など、わかりやすい名前の任意の入力特徴を 1 つだけ指定してください。説明のレスポンスでは、N 次元のアトリビューション リストが返されます。ここで、N はモデル内の特徴の数で、リスト内の要素はトレーニング データセットと同じ順序で表示されます。必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン(画像データの黒い画像)を選択します。
特徴の出力名を設定します。
説明可能性の構成が完了したら、[インポート] ボタンをクリックします。
gcloud
次の
ExplanationMetadata
をローカル環境の JSON ファイルに書き込みます。ファイル名は重要ではありませんが、この例では、explanation-metadata.json
という名前を使用しています。explanation-metadata.json
{ "inputs": { "FEATURE_NAME": { } }, "outputs": { "OUTPUT_NAME": { } } }
次のように置き換えます。
- FEATURE_NAME: 入力特徴の覚えやすい名前。
- OUTPUT_NAME: モデル出力の覚えやすい名前。
入力ベースラインを指定する場合は、モデルの入力(通常は 2D マトリックスのリスト)に一致することを確認してください。それ以外の場合、入力ベースラインのデフォルト値は入力シェイプの 0 値の 2D マトリックスです。
次のコマンドを実行して、Vertex Explainable AI をサポートする
Model
リソースを作成します。Vertex Explainable AI に関連するフラグはハイライト表示されています。gcloud ai models upload \ --region=LOCATION \ --display-name=MODEL_NAME \ --container-image-uri=IMAGE_URI \ --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \ --explanation-method=sampled-shapley \ --explanation-path-count=PATH_COUNT \ --explanation-metadata-file=explanation-metadata.json
次のように置き換えます。
- IMAGE_URI: 予測に使用するビルド済みコンテナの URI。
-
PATH_COUNT: サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数。
[1, 50]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
25
を試してください。
REST
リクエストのデータを使用する前に、次のように置き換えます。
- IMAGE_URI: 予測に使用するビルド済みコンテナの URI。
-
PATH_COUNT: サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数。
[1, 50]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
25
を試してください。 - FEATURE_NAME: 入力特徴の覚えやすい名前。
- OUTPUT_NAME: モデル出力の覚えやすい名前。
他のプレースホルダの適切な値については、upload
とモデルのインポートをご覧ください。
入力ベースラインを指定する場合は、モデルの入力(通常は 2D マトリックスのリスト)に一致することを確認してください。それ以外の場合、入力ベースラインのデフォルト値は入力シェイプの 0 値の 2D マトリックスです。
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload
リクエストの本文(JSON):
{ "model": { "displayName": "MODEL_NAME", "containerSpec": { "imageUri": "IMAGE_URI" }, "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY", "explanationSpec": { "parameters": { "sampledShapleyAttribution": { "pathCount": PATH_COUNT } }, "metadata": { "inputs": { "FEATURE_NAME": { } }, "outputs": { "OUTPUT_NAME": { } } } } }
リクエストを送信するには、次のいずれかのオプションを選択します。
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_ID/locations/LOCATION/models:upload"
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_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content
カスタム コンテナ
Model
が入力として表計算データを受け入れ、カスタム コンテナを使用して予測を行う場合は、説明にサンプリングされた Shapley のアトリビューション方式を使用するように構成してください。
特徴名と出力名の決定
次の手順では、Model
が入力として想定している特徴の名前を Vertex AI に指定する必要があります。また、Model
の予測で出力に使用するキーを指定する必要があります。
特徴名の決定
Model
が、各入力インスタンスに特定のトップレベル キーがあることを想定している場合、これらのキーが特徴名になります。
たとえば、Model
が次の形式の入力インスタンスを想定しているとします。
{
"length": <value>,
"width": <value>
}
この場合、特徴名は length
と width
です。これらのフィールドの値にネストされたリストやオブジェクトが含まれている場合でも、次の手順で必要なキーは length
と width
だけです。説明をリクエストすると、Vertex Explainable AI が特徴のネスト要素ごとにアトリビューションを提供します。
Model
がキーなしの入力を想定している場合、Vertex Explainable AI は Model
に単一の特徴があると見なします。特徴名には、覚えやすい文字列を使用できます。
たとえば、Model
が次の形式の入力インスタンスを想定しているとします。
[
<value>,
<value>
]
この場合、dimensions
などの単一の特徴名を Vertex Explainable AI に提供します。
出力名の決定
Model
が、キー付きの出力を含むオンライン予測インスタンスを返す場合、そのキーが出力名になります。
たとえば、Model
が次の形式で予測を返すとします。
{
"scores": <value>
}
この場合、出力名は scores
になります。scores
フィールドの値が配列の場合、説明を取得すると、各予測で最も値の大きい要素の特徴アトリビューションが返されます。出力フィールドの追加要素に特徴アトリビューションを提供するように Vertex Explainable AI を構成するには、ExplanationParameters
で topK
または outputIndices
フィールドを指定できます。ただし、このドキュメントの例では、これらのオプションについて説明しません。
Model
がキーなしの予測を返す場合、出力名として覚えやすい文字列を使用できます。たとえば、Model
が予測ごとに配列またはスカラーを返す場合に、これが適用されます。
Model
の作成
Model
の作成またはインポートに使用するツールに応じて、次のいずれかのタブを選択してください。
コンソール
ガイドに沿って、Google Cloud コンソールを使用してモデルをインポートします。説明可能性のステップが表示されたら、次の手順を行います。
特徴アトリビューション方式として、サンプリングされた Shapely(表形式モデル用)を選択します。
パス数に、サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数を設定します。これは、
[1, 50]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
25
を試してください。モデルの各入力特徴を構成します。
入力特徴名を入力します。
モデル アーティファクトに特徴名が含まれていない場合、Vertex AI は指定された入力特徴名をモデルにマッピングできません。その場合は、
input_features
など、わかりやすい名前の任意の入力特徴を 1 つだけ指定してください。説明のレスポンスでは、N 次元のアトリビューション リストが返されます。ここで、N はモデル内の特徴の数で、リスト内の要素はトレーニング データセットと同じ順序で表示されます。必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン(画像データの黒い画像)を選択します。
特徴の出力名を設定します。
説明可能性の構成が完了したら、[インポート] ボタンをクリックします。
gcloud
次の
ExplanationMetadata
をローカル環境の JSON ファイルに書き込みます。ファイル名は重要ではありませんが、この例では、explanation-metadata.json
という名前を使用しています。explanation-metadata.json
{ "inputs": { "FEATURE_NAME": {} }, "outputs": { "OUTPUT_NAME": {} } }
次のように置き換えます。
- FEATURE_NAME: 特徴の名前。このドキュメントの「特徴名の決定」をご覧ください。
- OUTPUT_NAME: 出力の名前。このドキュメントの「出力名の決定」をご覧ください。
必要に応じて、入力ベースラインを
ExplanationMetadata
に追加できます。追加しない場合は、Vertex AI がModel
の入力ベースラインを選択します。入力ベースラインを指定する場合は、モデルの入力(通常は 2D マトリックスのリスト)に一致することを確認してください。それ以外の場合、入力ベースラインのデフォルト値は入力シェイプの 0 値の 2D マトリックスです。
次のコマンドを実行して、Vertex Explainable AI をサポートする
Model
リソースを作成します。Vertex Explainable AI に関連するフラグはハイライト表示されています。gcloud ai models upload \ --region=LOCATION \ --display-name=MODEL_NAME \ --container-image-uri=IMAGE_URI \ --artifact-uri=PATH_TO_MODEL_ARTIFACT_DIRECTORY \ --explanation-method=sampled-shapley \ --explanation-path-count=PATH_COUNT \ --explanation-metadata-file=explanation-metadata.json
次のように置き換えます。
-
PATH_COUNT: サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数。
[1, 50]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
25
を試してください。
-
REST
リクエストのデータを使用する前に、次のように置き換えます。
-
PATH_COUNT: サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数。
[1, 50]
の範囲の整数にする必要があります。値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、
25
を試してください。 - FEATURE_NAME: 特徴の名前。このドキュメントの「特徴名の決定」をご覧ください。
- OUTPUT_NAME: 出力の名前。このドキュメントの「出力名の決定」をご覧ください。
他のプレースホルダの適切な値については、upload
とモデルのインポートをご覧ください。
必要に応じて、入力ベースラインを ExplanationMetadata
に追加できます。追加しない場合は、Vertex AI が Model
の入力ベースラインを選択します。
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/models:upload
リクエストの本文(JSON):
{ "model": { "displayName": "MODEL_NAME", "containerSpec": { "imageUri": "IMAGE_URI" }, "artifactUri": "PATH_TO_MODEL_ARTIFACT_DIRECTORY", "explanationSpec": { "parameters": { "sampledShapleyAttribution": { "pathCount": PATH_COUNT } }, "metadata": { "inputs": { "FEATURE_NAME": {} }, "outputs": { "OUTPUT_NAME": {} } } } }
リクエストを送信するには、次のいずれかのオプションを選択します。
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_ID/locations/LOCATION/models:upload"
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_ID/locations/LOCATION/models:upload" | Select-Object -Expand Content