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

カスタム トレーニング モデルで Vertex Explainable AI を使用するには、説明をリクエストする Model リソースの作成時、モデルのデプロイ時、またはバッチ説明ジョブの送信時に特定のオプションを構成する必要があります。このページでは、これらのオプションの構成について説明します。

AutoML 表形式のモデルで Vertex Explainable AI を使用する場合は、構成を行う必要はありません。Vertex AI は Vertex Explainable AI のモデルを自動的に構成します。このドキュメントをスキップして、説明の取得をご覧ください。

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

説明は、モデルの作成時またはインポート時に構成します。まだ説明を構成していなくても、作成済みのモデルに説明を構成することもできます。

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

Model を作成またはインポートするときに、Model の explanationSpec フィールドを使用して、すべての説明のデフォルト構成を設定できます。

Vertex AI では、次の方法でカスタム トレーニング済みの Model を作成できます。

いずれの場合も、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 リクエストで、次のフィールドをオーバーライドできます。

説明リクエストの explanationSpecOverride フィールドで、これらの設定をオーバーライドします。

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

予測にビルド済みコンテナを使用するのか、カスタム コンテナを使用するのかによって、ExplanationSpec に指定する詳細が少し異なります。使用しているコンテナに対応するタブを選択してください。

TensorFlow のビルド済みコンテナ

Vertex Explainable AI には、次のいずれかのアトリビューション方式を使用できます。Model に適切な方法については、特徴アトリビューション方式の比較をご覧ください。

サンプリングされた Shapley

Model の作成またはインポートに使用するツールに応じて、次のいずれかのタブを選択してください。

コンソール

ガイドに沿って、Google Cloud コンソールを使用してモデルをインポートします。説明可能性のステップが表示されたら、次の手順を行います。

  1. 特徴アトリビューション方式として、サンプリングされた Shapely（表形式モデル用）を選択します。

  2. パス数に、サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数を設定します。これは、[1, 50] の範囲の整数にする必要があります。

    値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、25 を試してください。

  3. モデルの各入力特徴を構成します。

    1. 入力特徴名を入力します。

    2. 必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン（画像データの黒い画像）を選択します。

    3. TensorFlow モデルをインポートする場合は、追加の入力フィールドがあります。

      1. 入力テンソル名を入力します。

      2. 必要に応じて、インデックスのテンソル名または高密度の形状テンソル名を入力します。

      3. ここではモダリティを更新できません。表形式モデルの場合は NUMERIC、画像モデルの場合は IMAGE に自動的に設定されます。

      4. 必要に応じて [エンコード] フィールドを設定します。設定しない場合、デフォルトで IDENTITY になります。

      5. 該当する場合、[グループ名] フィールドを設定します。

  4. TensorFlow モデルをインポートする場合は、出力フィールドを指定します。

    1. 特徴の出力名を設定します。
    2. 特徴の出力テンソル名を設定します。
    3. 必要に応じて、インデックスの表示名のマッピングを設定します。
    4. 必要に応じて、表示名のマッピングキーを設定します。

  5. 説明可能性の構成が完了したら、[インポート] ボタンをクリックします。

gcloud

  1. 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 の入力ベースラインを選択します。

  2. 次のコマンドを実行して、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

    次のように置き換えます。

    他のプレースホルダの適切な値については、upload とモデルのインポートをご覧ください。

REST

リクエストのデータを使用する前に、次のように置き換えます。

他のプレースホルダの適切な値については、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. 特徴アトリビューション方式の場合は、[統合勾配（表形式モデル用）] または [統合勾配（画像分類モデル用）] を選択します。

  2. 画像分類モデルをインポートする場合は、次の操作を行います。

    1. [可視化タイプ] と [カラーマップ] を設定します。

    2. [下位をクリップ]、[上位をクリップ]、[オーバーレイのタイプ]、[積分ステップの数] は、デフォルトの設定にしておくことができます。

    詳しくは、可視化設定をご覧ください。

  3. 特徴アトリビューションの計算でパス積分を概算するためのステップ数を設定します。これは、[1, 100] の範囲の整数にする必要があります。

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

  4. モデルの各入力特徴を構成します。

    1. 入力特徴名を入力します。

    2. 必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン（画像データの黒い画像）を選択します。

    3. TensorFlow モデルをインポートする場合は、追加の入力フィールドがあります。

      1. 入力テンソル名を入力します。

      2. 必要に応じて、インデックスのテンソル名または高密度の形状テンソル名を入力します。

      3. ここではモダリティを更新できません。表形式モデルの場合は NUMERIC、画像モデルの場合は IMAGE に自動的に設定されます。

      4. 必要に応じて [エンコード] フィールドを設定します。設定しない場合、デフォルトで IDENTITY になります。

      5. 該当する場合、[グループ名] フィールドを設定します。

  5. TensorFlow モデルをインポートする場合は、出力フィールドを指定します。

    1. 特徴の出力名を設定します。
    2. 特徴の出力テンソル名を設定します。
    3. 必要に応じて、インデックスの表示名のマッピングを設定します。
    4. 必要に応じて、表示名のマッピングキーを設定します。

  6. 説明可能性の構成が完了したら、[インポート] ボタンをクリックします。

gcloud

  1. 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 の入力ベースラインを選択します。

  2. 次のコマンドを実行して、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 コンソールを使用してモデルをインポートします。説明可能性のステップが表示されたら、次の手順を行います。

  1. 特徴アトリビューション方式として [XRAI（画像分類モデル用）] を選択します。

  2. 次の可視化オプションを設定します。

    1. [カラーマップ] を設定します。

    2. [下位をクリップ]、[上位をクリップ]、[オーバーレイのタイプ]、[積分ステップの数] は、デフォルトの設定にしておくことができます。

      詳しくは、可視化設定をご覧ください。

  3. 特徴アトリビューションの計算でパス積分を概算するためのステップ数を設定します。これは、[1, 100] の範囲の整数にする必要があります。

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

  4. モデルの各入力特徴を構成します。

    1. 入力特徴名を入力します。

    2. 必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン（画像データの黒い画像）を選択します。

    3. TensorFlow モデルをインポートする場合は、追加の入力フィールドがあります。

      1. 入力テンソル名を入力します。

      2. 必要に応じて、インデックスのテンソル名または高密度の形状テンソル名を入力します。

      3. ここではモダリティを更新できません。表形式モデルの場合は NUMERIC、画像モデルの場合は IMAGE に自動的に設定されます。

      4. 必要に応じて [エンコード] フィールドを設定します。設定しない場合、デフォルトで IDENTITY になります。

      5. 該当する場合、[グループ名] フィールドを設定します。

  5. TensorFlow モデルをインポートする場合は、出力フィールドを指定します。

    1. 特徴の出力名を設定します。
    2. 特徴の出力テンソル名を設定します。
    3. 必要に応じて、インデックスの表示名のマッピングを設定します。
    4. 必要に応じて、表示名のマッピングキーを設定します。

  6. 説明可能性の構成が完了したら、[インポート] ボタンをクリックします。

gcloud

  1. 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"
    }
  }
}

    次のように置き換えます。

    必要に応じて、入力ベースラインを ExplanationMetadata に追加できます。追加しない場合は、Vertex AI が Model の入力ベースラインを選択します。

  2. 次のコマンドを実行して、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

リクエストのデータを使用する前に、次のように置き換えます。

他のプレースホルダの適切な値については、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 コンソールを使用してモデルをインポートします。説明可能性のステップが表示されたら、次の手順を行います。

  1. 特徴アトリビューション方式として、サンプリングされた Shapely（表形式モデル用）を選択します。

  2. パス数に、サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数を設定します。これは、[1, 50] の範囲の整数にする必要があります。

    値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、25 を試してください。

  3. モデルの各入力特徴を構成します。

    1. 入力特徴名を入力します。

      モデル アーティファクトに特徴名が含まれていない場合、Vertex AI は指定された入力特徴名をモデルにマッピングできません。その場合は、input_features など、わかりやすい名前の任意の入力機能を 1 つだけ指定してください。説明のレスポンスでは、N 次元のアトリビューション リストが返されます。ここで、N はモデル内の特徴の数で、リスト内の要素はトレーニング データセットと同じ順序で表示されます。

    2. 必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン（画像データの黒い画像）を選択します。

  4. 特徴の出力名を設定します。

  5. 説明可能性の構成が完了したら、[インポート] ボタンをクリックします。

gcloud

  1. 次の ExplanationMetadata をローカル環境の JSON ファイルに書き込みます。ファイル名は重要ではありませんが、この例では、explanation-metadata.json という名前を使用しています。

    explanation-metadata.json

    {
  "inputs": {
    "FEATURE_NAME": {
    }
  },
  "outputs": {
    "OUTPUT_NAME": {
    }
  }
}

    次のように置き換えます。

    • FEATURE_NAME: 入力特徴の覚えやすい名前。
    • OUTPUT_NAME: モデル出力の覚えやすい名前。

    入力ベースラインを指定する場合は、モデルの入力（通常は 2D マトリックスのリスト）に一致することを確認してください。それ以外の場合、入力ベースラインのデフォルト値は入力シェイプの 0 値の 2D マトリックスです。

  2. 次のコマンドを実行して、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 コンソールを使用してモデルをインポートします。説明可能性のステップが表示されたら、次の手順を行います。

  1. 特徴アトリビューション方式として、サンプリングされた Shapely（表形式モデル用）を選択します。

  2. パス数に、サンプリングされた Shapley のアトリビューション方式に使用する特徴順列の数を設定します。これは、[1, 50] の範囲の整数にする必要があります。

    値を大きくすると、近似誤差が少なくなりますが、より多くの計算能力が必要になります。使用する値がわからない場合は、25 を試してください。

  3. モデルの各入力特徴を構成します。

    1. 入力特徴名を入力します。

      モデル アーティファクトに特徴名が含まれていない場合、Vertex AI は指定された入力特徴名をモデルにマッピングできません。その場合は、input_features など、わかりやすい名前の任意の入力機能を 1 つだけ指定してください。説明のレスポンスでは、N 次元のアトリビューション リストが返されます。ここで、N はモデル内の特徴の数で、リスト内の要素はトレーニング データセットと同じ順序で表示されます。

    2. 必要に応じて、1 つ以上の入力ベースラインを追加できます。それ以外の場合、Vertex Explainable AI は、すべてゼロの値のデフォルトの入力ベースライン（画像データの黒い画像）を選択します。

  4. 特徴の出力名を設定します。

  5. 説明可能性の構成が完了したら、[インポート] ボタンをクリックします。

gcloud

  1. 次の 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 マトリックスです。

  2. 次のコマンドを実行して、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

次のステップ