サンプルベースの説明を構成する

サンプルベースの説明を使用するには、Model リソースをインポートまたは Model Registry にアップロードするときに explanationSpec を指定して説明を構成する必要があります。

その後、オンライン説明をリクエストするときに、リクエストで ExplanationSpecOverride を指定することで、これらの構成値の一部をオーバーライドできます。バッチの説明をリクエストすることはできません。バッチの説明はサポートされていません。

このページでは、これらのオプションを構成および更新する方法について説明します。

モデルをインポートまたはアップロードするときに説明を構成する

始める前に、以下のものが揃っていることを確認してください。

モデルアーティファクトが含まれる Cloud Storage の場所。モデルは、出力を潜在空間として使用できる、レイヤの名前または署名を指定するディープニューラルネットワーク（DNN）モデルか、または、埋め込み（潜在空間表現）を直接出力するモデルを指定することもできます。この潜在空間は、説明の生成に使用されるサンプル表現をキャプチャします。
近似最近傍検索用にインデックスが付けられるインスタンスを含む Cloud Storage のロケーション。詳細については、入力データの要件をご覧ください。

コンソール

ガイドに沿って、Google Cloud コンソールを使用してモデルをインポートします。

[説明可能性] タブで [サンプルベースの説明] を選択し、フィールドに入力します。

各フィールドの詳細については、Google Cloud コンソールのヒント（下記参照）と、Example および ExplanationMetadata のリファレンスドキュメントをご覧ください。

gcloud CLI

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

{
  "inputs": {
    "my_input": {
      "inputTensorName": "INPUT_TENSOR_NAME",
      "encoding": "IDENTITY",
    },
    "id": {
      "inputTensorName": "id",
      "encoding": "IDENTITY"
    }
  },
  "outputs": {
    "embedding": {
      "outputTensorName": "OUTPUT_TENSOR_NAME"
    }
  }
}

（省略可）完全な NearestNeighborSearchConfig を指定する場合は、ローカル環境の JSON ファイルに以下を書き込みます。ファイル名は重要ではありませんが、この例では、search_config.json という名前を使用しています。

{
  "contentsDeltaUri": "",
  "config": {
      "dimensions": 50,
      "approximateNeighborsCount": 10,
      "distanceMeasureType": "SQUARED_L2_DISTANCE",
      "featureNormType": "NONE",
      "algorithmConfig": {
          "treeAhConfig": {
              "leafNodeEmbeddingCount": 1000,
              "fractionLeafNodesToSearch": 1.0
          }
      }
    }
  }

次のコマンドを実行して Model をアップロードします。

Preset 検索構成を使用している場合は、--explanation-nearest-neighbor-search-config-file フラグを削除します。NearestNeighborSearchConfig を指定する場合は、--explanation-modality フラグと --explanation-query フラグを削除します。

サンプルベースの説明に関連するフラグは太字になっています。

gcloud ai models upload \
    --region=LOCATION \
    --display-name=MODEL_NAME \
    --container-image-uri=IMAGE_URI \
    --artifact-uri=MODEL_ARTIFACT_URI \
    --explanation-method=examples \
    --uris=[URI, ...] \
    --explanation-neighbor-count=NEIGHBOR_COUNT \
    --explanation-metadata-file=explanation-metadata.json \
    --explanation-modality=IMAGE|TEXT|TABULAR \
    --explanation-query=PRECISE|FAST \
    --explanation-nearest-neighbor-search-config-file=search_config.json

詳細については、gcloud ai モデルのアップロードをご覧ください。

アップロードアクションによって OPERATION_ID が返されます。これを使用して、オペレーションが完了したことを確認できます。レスポンスに "done": true が表示されるまで、オペレーションのステータスをポーリングできます。gcloud ai operations describe コマンドを使用して、ステータスをポーリングします。次に例を示します。
```
gcloud ai operations describe <operation-id>
```
オペレーションが完了するまで、説明をリクエストすることはできません。データセットとモデルアーキテクチャのサイズによっては、サンプルのクエリに使用するインデックスの構築に数時間かかることがあります。

REST

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

PROJECT
LOCATION

他のプレースホルダについては、Model、explanationSpec、Examples をご覧ください。

モデルのアップロードの詳細については、upload メソッドとモデルのインポートをご覧ください。

次の JSON リクエストの本文では、Preset 検索構成を指定しています。または、完全な NearestNeighborSearchConfig を指定することもできます。

HTTP メソッドと URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/models:upload

リクエストの本文（JSON）:

{
  "model": {
    "displayName": "my-model",
    "artifactUri": "gs://your-model-artifact-folder",
    "containerSpec": {
      "imageUri": "us-docker.pkg.dev/vertex-ai/prediction/tf2-cpu.2-11:latest",
    },
    "explanationSpec": {
      "parameters": {
        "examples": {
          "gcsSource": {
            "uris": ["gs://your-examples-folder"]
          },
          "neighborCount": 10,
          "presets": {
            "modality": "image"
          }
        }
      },
      "metadata": {
        "outputs": {
            "embedding": {
                "output_tensor_name": "embedding"
            }
        },
        "inputs": {
          "my_fancy_input": {
            "input_tensor_name": "input_tensor_name",
            "encoding": "identity",
            "modality": "image"
          },
          "id": {
            "input_tensor_name": "id",
            "encoding": "identity"
          }
        }
      }
    }
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、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/locations/LOCATION/models:upload"

PowerShell（Windows）

リクエスト本文を 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/models:upload" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/models/MODEL_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1.UploadModelOperationMetadata",
    "genericMetadata": {
      "createTime": "2022-01-08T01:21:10.147035Z",
      "updateTime": "2022-01-08T01:21:10.147035Z"
    }
  }
}

アップロードアクションによって OPERATION_ID が返されます。これを使用して、オペレーションが完了したことを確認できます。レスポンスに "done": true が表示されるまで、オペレーションのステータスをポーリングできます。gcloud ai operations describe コマンドを使用して、ステータスをポーリングします。次に例を示します。

gcloud ai operations describe <operation-id>

オペレーションが完了するまで、説明をリクエストすることはできません。データセットとモデルアーキテクチャのサイズによっては、サンプルのクエリに使用するインデックスの構築に数時間かかることがあります。

Python

画像分類のサンプルベースの説明のノートブックの、モデルをアップロードするのセクションをご覧ください。

`NearestNeighborSearchConfig`

次の JSON リクエストの本文は、upload リクエストで完全な NearestNeighborSearchConfig（プリセットではなく）を指定する方法を示しています。

{
  "model": {
    "displayName": displayname,
    "artifactUri": model_path_to_deploy,
    "containerSpec": {
      "imageUri": DEPLOY_IMAGE,
    },
    "explanationSpec": {
      "parameters": {
        "examples": {
          "gcsSource": {
            "uris": [DATASET_PATH]
          },
          "neighborCount": 5,
          "nearest_neighbor_search_config": {
            "contentsDeltaUri": "",
            "config": {
              "dimensions": dimensions,
              "approximateNeighborsCount": 10,
              "distanceMeasureType": "SQUARED_L2_DISTANCE",
              "featureNormType": "NONE",
              "algorithmConfig": {
                  "treeAhConfig": {
                      "leafNodeEmbeddingCount": 1000,
                      "fractionLeafNodesToSearch": 1.0
                  }
                }
              }
          }
        }
      },
      "metadata": { ... }
    }
  }
}

次の表は、NearestNeighborSearchConfig のフィールドを一覧表示しています。

フィールド
`dimensions`	`int32` 必須。入力ベクトルの次元の数。
`approximateNeighborsCount`	`int32` tree-AH アルゴリズムを使用する場合は必須。正確な並べ替えが実行される前に近似探索によってデフォルトで探索される近傍数。正確な並べ替えとは、近似探索アルゴリズムによって返された結果が、よりコストの高い距離計算によって並べ替えられる手続きです。
`distanceMeasureType`	`DistanceMeasureType` 最近傍探索で使用される距離尺度。
`featureNormType`	`FeatureNormType` 各ベクトルに対して実行される正規化のタイプ。
`algorithmConfig`	`oneOf:` `TreeAhConfig` `BruteForceConfig` ベクトル検索で効率的な検索に使用されるアルゴリズムの構成。 `TreeAhConfig`: tree-AH アルゴリズムを使用するための構成オプション。詳細については、TensorFlow Recommender とベクトル検索を使用したディープリトリーブのスケーリングに関するブログ記事をご覧ください。 `BruteForceConfig`: このオプションは、各クエリに対する標準の線形探索をデータベースに実装します。ブルートフォース検索用に構成するフィールドはありません。このアルゴリズムを選択するには、`BruteForceConfig` に空のオブジェクトを渡します。

`DistanceMeasureType`

列挙型
`SQUARED_L2_DISTANCE`	ユークリッド（L₂）距離
`L1_DISTANCE`	マンハッタン（L₁）距離
`DOT_PRODUCT_DISTANCE`	デフォルト値。ドット積の負の値として定義されます。
`COSINE_DISTANCE`	コサイン距離。COSINE 距離の代わりに DOT_PRODUCT_DISTANCE + UNIT_L2_NORM を使用することを強くおすすめします。Google のアルゴリズムは DOT_PRODUCT 距離向けに最適化されており、UNIT_L2_NORM と組み合わせると、COSINE 距離と同じランキングおよび数学的等価性を提供します。

`FeatureNormType`

列挙型
`UNIT_L2_NORM`	ユニット L2 正規化タイプ。
`NONE`	デフォルト値。正規化タイプは指定されません。

`TreeAhConfig`

次のフィールドは、tree-AH アルゴリズム（シャローツリー + 非対称ハッシュ）用に選択されます。

フィールド
`fractionLeafNodesToSearch`	`double`
	クエリが検索されるリーフノードのデフォルトの割合。0.0～1.0 の範囲（両端を除く）を指定してください。設定されない場合は、デフォルト値の 0.05 になります。
`leafNodeEmbeddingCount`	`int32`
	各リーフノードに対する埋め込みの数。設定されない場合は、デフォルト値の 1,000 になります。
`leafNodesToSearchPercent`	`int32`
	非推奨: `fractionLeafNodesToSearch` を使用します。クエリが検索されるリーフノードのデフォルトの割合。すべて含めて 1～100 の範囲にする必要があります。設定されない場合は、デフォルト値の 10（つまり 10%）になります。

`BruteForceConfig`

このオプションは、各クエリに対する標準の線形探索をデータベースに実装します。ブルートフォース検索用に構成するフィールドはありません。このアルゴリズムを選択するには、BruteForceConfig の空のオブジェクトを algorithmConfig に渡します。

入力データの要件

データセットを Cloud Storage のロケーションにアップロードします。ファイルが JSON Lines 形式であることを確認します。

ファイルは JSON Lines 形式である必要があります。次のサンプルは、画像分類のサンプルベースの説明のノートブックからのものです。

{"id": "0", "bytes_inputs": {"b64": "..."}}
{"id": "1", "bytes_inputs": {"b64": "..."}}
{"id": "2", "bytes_inputs": {"b64": "..."}}

インデックスまたは構成を更新する

Vertex AI を使用すると、モデルの最近傍インデックスまたは Example 構成を更新できます。これは、データセットのインデックスを再作成せずにモデルを更新する場合に便利です。たとえば、モデルのインデックスに 1,000 個のインスタンスがあり、さらに 500 個のインスタンスを追加する場合は、元の 1,000 個のインスタンスを再処理せずに UpdateExplanationDataset を呼び出してインデックスに追加します。

説明データセットの更新:

Python

def update_explanation_dataset(model_id, new_examples):
    response = clients["model"].update_explanation_dataset(model=model_id,  examples=new_examples)
    update_dataset_response = response.result()
    return update_dataset_response

PRESET_CONFIG = {
    "modality": "TEXT",
    "query": "FAST"
}
NEW_DATASET_FILE_PATH = "new_dataset_path"
NUM_NEIGHBORS_TO_RETURN = 10

EXAMPLES = aiplatform.Examples(presets=PRESET_CONFIG,
                                    gcs_source=aiplatform.types.io.GcsSource(uris=[NEW_DATASET_FILE_PATH]),
                                      neighbor_count=NUM_NEIGHBORS_TO_RETURN)

MODEL_ID = 'model_id'
update_dataset_response = update_explanation_dataset(MODEL_ID, EXAMPLES)

使用上の注意:

model_id は、UpdateExplanationDataset オペレーションの後も変更されません。
UpdateExplanationDataset オペレーションは Model リソースにのみ影響します。関連付けられている DeployedModel は更新されません。つまり、deployedModel のインデックスには、デプロイされた時点のデータセットが含まれています。deployedModel のインデックスを更新するには、更新されたモデルをエンドポイントに再デプロイする必要があります。

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

説明をリクエストするときに、ExplanationSpecOverride フィールドを指定することで、一部のパラメータをその場でオーバーライドできます。

アプリケーションによっては、返される説明の種類に対していくつかの制約が必要になる場合があります。たとえば、説明の多様性を確保するために、1 つの種類のサンプルが説明で過度に表現されないように、クラウディングパラメータを指定できます。具体的には、ユーザーが、モデルによって鳥が飛行機としてラベル付けされた理由を理解しようとする場合、根本原因をより深く調査するために、説明として多くの鳥のサンプルを確認することに関心がない可能性があります。

次の表は、サンプルベースの説明リクエストでオーバーライドできるパラメータをまとめたものです。

プロパティ名	プロパティ値	説明
neighborCount	`int32`	説明として返す例の数
crowdingCount	`int32`	同じクラウディングタグで返されるサンプルの最大数
allow	`String Array`	説明に使用できるタグ
拒否	`String Array`	説明に使用できないタグ

Vector Search のフィルタリングでこれらのパラメータについて詳しく説明します。

オーバーライドを使用した JSON リクエスト本文の例を次に示します。

{
  "instances":[
    {
      "id": data[0]["id"],
      "bytes_inputs": {"b64": bytes},
      "restricts": "",
      "crowding_tag": ""
    }
  ],
  "explanation_spec_override": {
    "examples_override": {
      "neighbor_count": 5,
      "crowding_count": 2,
      "restrictions": [
        {
          "namespace_name": "label",
          "allow": ["Papilloma", "Rift_Valley", "TBE", "Influenza", "Ebol"]
        }
      ]
    }
  }
}

次のステップ

Model を Endpoint にデプロイし、サンプルベースの説明を取得する。

サンプルベースの explain リクエストからのレスポンスの例を次に示します。

[
   {
      "neighbors":[
         {
            "neighborId":"311",
            "neighborDistance":383.8
         },
         {
            "neighborId":"286",
            "neighborDistance":431.4
         }
      ],
      "input":"0"
   },
   {
      "neighbors":[
         {
            "neighborId":"223",
            "neighborDistance":471.6
         },
         {
            "neighborId":"55",
            "neighborDistance":392.7
         }
      ],
      "input":"1"
   }
]

料金

料金ページのサンプルベースの説明のセクションをご覧ください。