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

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

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

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

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

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

  1. モデル アーティファクトが含まれる Cloud Storage の場所。モデルは、出力を潜在空間として使用できる、レイヤの名前または署名を指定するディープ ニューラル ネットワーク（DNN）モデルか、または、埋め込み（潜在空間表現）を直接出力するモデルを指定することもできます。この潜在空間は、説明の生成に使用されるサンプル表現をキャプチャします。

  2. 近似最近傍検索用にインデックスが付けられるインスタンスを含む Cloud Storage のロケーション。詳細については、入力データの要件をご覧ください。

コンソール

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

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

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

gcloud CLI

  1. 次の 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"
    }
  }
}
  1. （省略可）完全な NearestNeighborSearchConfig を指定する場合は、ローカル環境の JSON ファイルに以下を書き込みます。ファイル名は重要ではありませんが、この例では、search_config.json という名前を使用しています。
{
  "contentsDeltaUri": "",
  "config": {
      "dimensions": 50,
      "approximateNeighborsCount": 10,
      "distanceMeasureType": "SQUARED_L2_DISTANCE",
      "featureNormType": "NONE",
      "algorithmConfig": {
          "treeAhConfig": {
              "leafNodeEmbeddingCount": 1000,
              "fractionLeafNodesToSearch": 1.0
          }
      }
    }
  }
  1. 次のコマンドを実行して 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 モデルのアップロードをご覧ください。

  1. アップロード アクションによって 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"
          }
        }
      }
    }
  }
}

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

次のような 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 アルゴリズムを使用する場合は必須。

正確な並べ替えが実行される前に近似探索によってデフォルトで探索される近傍数。正確な並べ替えとは、近似探索アルゴリズムによって返された結果が、よりコストの高い距離計算によって並べ替えられる手続きです。
ShardSize ShardSize

各シャードのサイズ。インデックスが大きい場合は、指定されたシャードサイズに基づいてシャーディングされます。サービング時に、各シャードは個別のノードでサービングされ、個別にスケーリングされます。
distanceMeasureType

DistanceMeasureType

最近傍探索で使用される距離尺度。
featureNormType

FeatureNormType

各ベクトルに対して実行される正規化のタイプ。
algorithmConfig oneOf:

ベクトル検索で効率的な検索に使用されるアルゴリズムの構成。高密度エンベディングにのみ使用されます。

  • TreeAhConfig: tree-AH アルゴリズムを使用するための構成オプション。詳細については、TensorFlow Recommender とベクトル検索を使用したディープ リトリーブのスケーリングに関するブログ記事をご覧ください。
  • BruteForceConfig: このオプションは、各クエリに対する標準の線形探索をデータベースに実装します。ブルート フォース検索用に構成するフィールドはありません。このアルゴリズムを選択するには、BruteForceConfig に空のオブジェクトを渡します。

DistanceMeasureType

列挙型
SQUARED_L2_DISTANCE ユークリッド（L2）距離
L1_DISTANCE マンハッタン（L1）距離
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"]
        }
      ]
    }
  }
}

次のステップ

サンプル ベースの 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"
   }
]

料金

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