特徴ベースの説明を構成する

カスタムトレーニングモデルで 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 を試してください。
モデルの各入力特徴を構成します。

注: TensorFlow 2 モデルの場合、入力特徴名は省略可能です。
1. 入力特徴名を入力します。
2. 必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン（画像データの黒い画像）を選択します。
3. TensorFlow モデルをインポートする場合は、追加の入力フィールドがあります。
  1. 入力テンソル名を入力します。
  2. 必要に応じて、インデックスのテンソル名または高密度の形状テンソル名を入力します。
  3. ここではモダリティを更新できません。表形式モデルの場合は NUMERIC、画像モデルの場合は IMAGE に自動的に設定されます。
  4. 必要に応じて [エンコード] フィールドを設定します。設定しない場合、デフォルトで IDENTITY になります。
  5. 該当する場合、[グループ名] フィールドを設定します。
TensorFlow モデルをインポートする場合は、出力フィールドを指定します。
1. 特徴の出力名を設定します。
2. 特徴の出力テンソル名を設定します。
3. 必要に応じて、インデックスの表示名のマッピングを設定します。
4. 必要に応じて、表示名のマッピングキーを設定します。
説明可能性の構成が完了したら、[インポート] ボタンをクリックします。

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 を試してください。
他のプレースホルダの適切な値については、upload とモデルのインポートをご覧ください。

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

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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. [可視化タイプ] と [カラーマップ] を設定します。
2. [下位をクリップ]、[上位をクリップ]、[オーバーレイのタイプ]、[積分ステップの数] は、デフォルトの設定にしておくことができます。
詳しくは、可視化設定をご覧ください。
特徴アトリビューションの計算でパス積分を概算するためのステップ数を設定します。これは、[1, 100] の範囲の整数にする必要があります。

値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、50 を試してください。
モデルの各入力特徴を構成します。

注: TensorFlow 2 モデルの場合、入力特徴名は省略可能です。
1. 入力特徴名を入力します。
2. 必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン（画像データの黒い画像）を選択します。
3. TensorFlow モデルをインポートする場合は、追加の入力フィールドがあります。
  1. 入力テンソル名を入力します。
  2. 必要に応じて、インデックスのテンソル名または高密度の形状テンソル名を入力します。
  3. ここではモダリティを更新できません。表形式モデルの場合は NUMERIC、画像モデルの場合は IMAGE に自動的に設定されます。
  4. 必要に応じて [エンコード] フィールドを設定します。設定しない場合、デフォルトで IDENTITY になります。
  5. 該当する場合、[グループ名] フィールドを設定します。
TensorFlow モデルをインポートする場合は、出力フィールドを指定します。
1. 特徴の出力名を設定します。
2. 特徴の出力テンソル名を設定します。
3. 必要に応じて、インデックスの表示名のマッピングを設定します。
4. 必要に応じて、表示名のマッピングキーを設定します。
説明可能性の構成が完了したら、[インポート] ボタンをクリックします。

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. [カラーマップ] を設定します。
2. [下位をクリップ]、[上位をクリップ]、[オーバーレイのタイプ]、[積分ステップの数] は、デフォルトの設定にしておくことができます。
  
  詳しくは、可視化設定をご覧ください。
特徴アトリビューションの計算でパス積分を概算するためのステップ数を設定します。これは、[1, 100] の範囲の整数にする必要があります。

値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、50 を試してください。
モデルの各入力特徴を構成します。

注: TensorFlow 2 モデルの場合、入力特徴名は省略可能です。
1. 入力特徴名を入力します。
2. 必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン（画像データの黒い画像）を選択します。
3. TensorFlow モデルをインポートする場合は、追加の入力フィールドがあります。
  1. 入力テンソル名を入力します。
  2. 必要に応じて、インデックスのテンソル名または高密度の形状テンソル名を入力します。
  3. ここではモダリティを更新できません。表形式モデルの場合は NUMERIC、画像モデルの場合は IMAGE に自動的に設定されます。
  4. 必要に応じて [エンコード] フィールドを設定します。設定しない場合、デフォルトで IDENTITY になります。
  5. 該当する場合、[グループ名] フィールドを設定します。
TensorFlow モデルをインポートする場合は、出力フィールドを指定します。
1. 特徴の出力名を設定します。
2. 特徴の出力テンソル名を設定します。
3. 必要に応じて、インデックスの表示名のマッピングを設定します。
4. 必要に応じて、表示名のマッピングキーを設定します。
説明可能性の構成が完了したら、[インポート] ボタンをクリックします。

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 を試してください。
モデルの各入力特徴を構成します。
1. 入力特徴名を入力します。
  
  モデルアーティファクトに特徴名が含まれていない場合、Vertex AI は指定された入力特徴名をモデルにマッピングできません。その場合は、input_features など、わかりやすい名前の任意の入力特徴を 1 つだけ指定してください。説明のレスポンスでは、N 次元のアトリビューションリストが返されます。ここで、N はモデル内の特徴の数で、リスト内の要素はトレーニングデータセットと同じ順序で表示されます。
2. 必要に応じて、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 を試してください。
他のプレースホルダの適切な値については、upload とモデルのインポートをご覧ください。

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 を試してください。
モデルの各入力特徴を構成します。
1. 入力特徴名を入力します。
  
  モデルアーティファクトに特徴名が含まれていない場合、Vertex AI は指定された入力特徴名をモデルにマッピングできません。その場合は、input_features など、わかりやすい名前の任意の入力特徴を 1 つだけ指定してください。説明のレスポンスでは、N 次元のアトリビューションリストが返されます。ここで、N はモデル内の特徴の数で、リスト内の要素はトレーニングデータセットと同じ順序で表示されます。
2. 必要に応じて、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 を試してください。
他のプレースホルダの適切な値については、upload とモデルのインポートをご覧ください。

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

次のステップ

Model を Endpoint にデプロイして、説明を取得する。

特徴ベースの説明を構成する

説明を構成するタイミングと場所

モデルの作成またはインポート時に説明を構成する

モデルのデプロイ時またはバッチ予測の取得時に説明を構成する

オンライン説明を取得するときに構成をオーバーライドする

explanationSpec フィールドを使用してモデルをインポートする

TensorFlow のビルド済みコンテナ

サンプリングされた Shapley

コンソール

gcloud

explanation-metadata.json

REST

curl

PowerShell

統合勾配

コンソール

gcloud

explanation-metadata.json

REST

curl

PowerShell

XRAI

コンソール

gcloud

explanation-metadata.json

REST

curl

PowerShell

scikit-learn と XGBoost のビルド済みコンテナ

コンソール

gcloud

explanation-metadata.json

REST

curl

PowerShell

カスタム コンテナ

特徴名と出力名の決定

特徴名の決定

出力名の決定

Model の作成

コンソール

gcloud

explanation-metadata.json

REST

curl

PowerShell

次のステップ

`explanationSpec` フィールドを使用してモデルをインポートする

`explanation-metadata.json`

`explanation-metadata.json`

`explanation-metadata.json`

`explanation-metadata.json`

カスタムコンテナ

`Model` の作成

`explanation-metadata.json`