カスタムエンベディングを使用する

注: この機能はプレビュー版で、GCP サービス固有の規約の「pre-GA サービス規約」が適用されます。一般提供前のプロダクトと機能では、サポートが制限されることがあります。また、これらのプロダクトや機能には、他の一般提供前のバージョンと互換性のない変更が行われる場合があります。詳細については、リリースステージの説明をご覧ください。さらに、この機能を使用すると、生成 AI プレビュー版の利用規約（以下「プレビュー規約」）に同意したことになります。この機能については、お客様は Cloud のデータ処理に関する追加条項に記載されているとおりに個人データを処理できます。その際、（プレビュー規約に定義されるとおり）本契約で規定されている制限と義務が適用されます。

データに独自のカスタムベクトルエンベディングをすでに作成している場合は、Vertex AI Search にアップロードして、Vertex AI Search でクエリするときに使用できます。

この機能は、一般的な構造化データまたはメタデータを含む非構造化データを含むデータストアで使用できます。この機能は、メディア検索と医療検索ではご利用いただけません。

デフォルトでは、Vertex AI Search は構成なしでベクトルエンベディングを自動的に生成します。エンベディングの作成に慣れていない場合は、Vertex AI Search にエンベディングの作成と使用を任せることをおすすめします。ただし、データに独自のエンベディングを作成した場合は、Vertex AI Search によって生成されたエンベディングではなく、独自のエンベディングを使用するほうが好ましいかもしれません。特に、カスタムエンベディングに検索の取得とランキングを強化できる追加のコンテキストが含まれている場合はそれが当てはまります。次に例を示します。

エンベディングは、公開データでのトレーニングでは意味的な類似性がキャプチャされない内部用語などのカスタム単語でトレーニングされています。たとえば、非公開ドキュメントにのみ表示される組織固有の用語などです。
ユーザープロファイルのエンベディングを作成しました。このエンベディングを使用して、セマンティックに関連するパーソナライズされたドキュメントのランキングを作成したいとします。エンベディングを使用してパーソナライズベースのランキングを取得できます。これにより、Google のドキュメントエンベディングを拡張して、関連性ベースのランキングを取得できます。

独自のエンベディングを使用するには:

始める前に: エンベディングがすべての要件を満たしていることを確認する
エンベディングを使用してデータを取り込む: エンベディングを使用してドキュメントを取り込む
スキーマを更新する: 重要なプロパティフィールドとディメンション仕様を使用してスキーマを更新する
エンベディングを指定する: エンベディングを、グローバルに指定するか、検索リクエストごとに指定します。

始める前に

開始する前に、エンベディングが次の要件を満たしていることを確認してください。

エンベディングは、構造化データとメタデータを含む非構造化データでサポートされています
エンベディングは 1 次元配列として指定する必要があります
エンベディングの次元は 1～768（両端を含む）の整数にする必要があります
エンベディングは、テキストと画像でサポートされています。動画はサポートされていません
エンベディングキープロパティフィールドとしてタグ付けできるフィールドは最大 2 つです。エンベディングの A/B テストなどのケースでは、2 つのフィールドを使用できます。
現在、エンべディングフィールドのキープロパティの指定は、設定後に削除できません

エンベディングを使用してデータを取り込む

ドキュメントのエンベディングは、ドキュメントの取り込み時に、そのドキュメントのデータまたはメタデータの一部として 1～2 つのフィールドに格納できます。

エンベディングを使用してデータを取り込むには:

データの種類に応じて、取り込み用のデータを準備します。
- 構造化データ: データを準備する際は、各ドキュメントのエンベディングを 1 次元配列としてドキュメント内の 1～2 つのフィールドに含めます。最大 2 つのエンベディングを指定できます（エンベディング間の A/B テストの場合など）。各エンベディングは、ドキュメント内の独自のフィールドに指定する必要があります（例: "example_embedding_vector": [0.1, 0.2, 0.3 ...]）。
  
  取り込み用にデータを準備するのドキュメントの構造化データの準備に関するガイダンスに沿って操作します。
- メタデータを含む非構造化データ: データを準備するときに、各ドキュメントのエンベディングを 1 次元配列としてドキュメントメタデータのフィールドに含めます。最大 2 つのエンベディングを指定できます（エンベディング間の A/B テストの場合など）。各エンベディングは、ドキュメントメタデータの独自のフィールドで指定する必要があります（例: "example_embedding_vector": [0.1, 0.2, 0.3 ...]）。
  
  取り込み用にデータを準備するのドキュメントの取り込み方法（Cloud Storage または BigQuery）の、メタデータを含む非構造化データの準備に関するガイダンスに沿って操作します。
Vertex AI Search でエンジンを作成し、データを取り込むの、データタイプに応じた手順に沿って、エンベディングを含むドキュメントを取り込みます。

次に、正しいエンベディングフィールドを使用するようにスキーマを更新します。

スキーマを更新する

Google Cloud コンソールまたは API を使用して、エンベディングフィールドのキープロパティのマッピングとディメンションでスキーマを更新します。

コンソール

Google Cloud コンソールを使用してスキーマを更新する手順は次のとおりです。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
ナビゲーションメニューで [データストア] をクリックします。
[名前] 列で、更新するスキーマを含むデータストアをクリックします。
[スキーマ] タブをクリックして、データのスキーマを表示します。
[編集] ボタンをクリックします。
スキーマでエンベディングフィールドを見つけ、[キープロパティ] 列で、そのフィールドのキープロパティとして embedding_vector を選択します。

2 つ目のエンベディングフィールドがある場合は、そのフィールドに対してこの手順を繰り返します。
[ディメンション] 列に、そのエンベディングフィールドのディメンション数を入力します。

2 つ目のエンベディングフィールドがある場合は、そのフィールドに対してこの手順を繰り返します。
[保存] をクリックして、スキーマの変更を適用します。

スキーマを更新した後、データストアのサイズによっては、インデックスの再作成に最大 24 時間かかることがあります。

REST

API を使用してスキーマを更新する手順は次のとおりです。

スキーマを更新するの REST の手順に沿って、キープロパティのマッピングと、各エンベディングフィールドのディメンション数を指定します。
- "keyPropertyMapping": "embedding_vector"
- "dimension": NUMBER_OF_DIMENSIONS
たとえば、フィールド example_embedding_vector に 768 個のディメンションを持つフォーマットされた JSON スキーマは次のとおりです。
```
  {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "example_embedding_vector": {
        "type": "array",
        "keyPropertyMapping": 'embedding_vector',
        "dimension": 768,
        "items": {
          "type": "number"
        }
      }
    }
  }
```
更新スキーマリクエストでは、上記の形式の JSON が JSON 文字列として含まれます。
```
  "jsonSchema": "{\"$schema\":\"https://json-schema.org/draft/2020-12/schema\",\"type\":\"object\",\"properties\":{\"example_embedding_vector\":{\"type\":\"array\",\"keyPropertyMapping\":\"embedding_vector\",\"dimension\":768,\"items\":{\"type\":\"number\"}}}}"
```
スキーマを更新した後、データストアのサイズによっては、インデックスの再作成に最大 24 時間かかることがあります。

次に、エンベディングを指定します。

エンベディングを指定する

スキーマの更新からのインデックス登録作成が完了したら、エンベディング仕様を含む検索リクエストを送信できます。

エンベディングを指定するには、次の 2 つの方法があります。

エンベディングをグローバルに指定する: すべての検索リクエストに同じエンベディングを指定するには、Google Cloud コンソールまたは API を使用して、エンベディング仕様を含めるようにサービス提供設定を更新します。
検索リクエストごとにエンベディングを指定する: API を使用して、各検索リクエストで embeddingSpec を送信します。グローバル設定が設定されている場合は、その設定がオーバーライドされます。

エンベディングをグローバルに指定する

Google Cloud コンソールまたは API を使用して、すべての検索リクエストで同じエンベディングを指定できます。

コンソール

すべての検索リクエストに同じエンベディング仕様を指定するには、エンベディング仕様を使用してサービス提供設定を更新します。

Google Cloud コンソールで、[Agent Builder] ページに移動します。

Agent Builder
更新するスキーマを含むデータストアの [表示] をクリックします。
[構成] ページに移動し、[サービス提供] タブをクリックします。
[エンベディングフィールドパス] に、エンベディングキープロパティにマッピングしたフィールドの名前を入力します。
[ランキング式] に、結果のランキングを制御する関数を入力します。変数は、入力した式に従って重み付けされます。ランキング式は、function, { " + ", function } 形式で、+ で結合された単一の関数または複数の関数です。

サポートされる関数は次のとおりです。
- DOUBLE * relevance_score
- DOUBLE * dotProduct(EMBEDDING_FIELD_PATH)
使用できる変数は次のとおりです。
- relevance_score: ドキュメントの関連性を測定するために Vertex AI Search から提供される事前定義変数。スコアの範囲は 0～1.0 です（両端を含みます）。
- dotProduct(): Vertex AI Search から提供される事前定義関数。この関数には、embeddingVector.fieldPath と同じフィールド名を指定する必要があります。
例:
- 0.3 * relevance_score
- 0.5 * relevance_score + 0.3 * dotProduct(example_embedding_field)

REST

すべての検索リクエストに同じエンベディング仕様を指定するには、servingConfig を embeddingConfig で更新します。

更新するフィールドを使用して servingConfig エンティティにパッチを適用します。更新するフィールドを updateMask で指定します。

次の例では、embeddingConfig はフィールド example_embedding_field でエンベディングを使用し、relevance_score に重み 0.5 を付与します。
```
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
      "name": "projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search",
      "embeddingConfig": {
        "fieldPath": "example_embedding_field"
      },
      "ranking_expression": "0.5 * relevance_score"
    }' \
'https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/default_search?updateMask=embeddingConfig,rankingExpression'
```
- fieldPath: エンベディングキープロパティにマッピングしたフィールドの名前。
- ranking_expression: 結果のランキングを制御します。変数は、入力した式に従って重み付けされます。ランキング式は、function, { " + ", function } 形式で、+ で結合された単一の関数または複数の関数です。
サポートされる関数は次のとおりです。
- DOUBLE * relevance_score
- DOUBLE * dotProduct(EMBEDDING_FIELD_PATH)
使用できる変数は次のとおりです。
- relevance_score: Vertex AI Search から提供される事前定義変数。
- dotProduct(): Vertex AI Search から提供される事前定義関数。ドット積は正規化されます。この関数には、embeddingVector.fieldPath と同じフィールド名を指定する必要があります。
例:
- 0.3 * relevance_score
- 0.5 * relevance_score + 0.3 * dotProduct(example_embedding_field)
検索リクエストを送信すると、servingConfig.embeddingConfig が自動的に含まれます。

別の embeddingSpec を明示的に含む検索リクエストを送信すると、servingConfig.embeddingConfig がオーバーライドされます。1 件の検索リクエストにエンベディング仕様を指定する方法については、リクエストごとの手順をご覧ください。

検索リクエストごとにエンベディングを指定する

API を使用して、1 つの検索リクエストにエンベディング仕様を指定できます。リクエストごとのエンベディング仕様は、グローバルなエンベディング仕様をオーバーライドします。

embeddingSpec を含む検索リクエストを送信します。

次の embeddingSpec の例では、フィールド example_embedding_field のエンベディングを使用し、「サンプルクエリ」を入力ベクトルとして指定し、ランキングの計算時に relevance_score に 0.5、example_embedding_field に 0.3 の重みを設定しています。
```
  "embeddingSpec": {
    "embeddingVectors": [{
      "fieldPath": "example_embedding_field",
      "vector": [
        0.96241474,
        -0.45999944,
        0.108588696
      ]
    }]
  },
  "ranking_expression": "0.5 * relevance_score + 0.3 * dotProduct(example_embedding_field)"
```
- fieldPath: エンベディングキープロパティにマッピングしたフィールドの名前。
- vector: 配列として指定された入力ベクトル。
- ranking_expression: 結果のランキングを制御します。変数は、入力した式に従って重み付けされます。ランキング式は、function, { " + ", function } 形式で、+ で結合された単一の関数または複数の関数です。
  
  サポートされる関数は次のとおりです。
  - DOUBLE * relevance_score
  - DOUBLE * dotProduct(EMBEDDING_FIELD_PATH)
  使用できる変数は次のとおりです。
  - relevance_score: ドキュメントの関連性を測定するために Vertex AI Search から提供される事前定義変数。スコアの範囲は 0～1.0 です（両端を含みます）。
  - dotProduct(): Vertex AI Search から提供される事前定義関数。この関数には、embeddingVector.fieldPath と同じフィールド名を指定する必要があります。
  例:
  - 0.3 * relevance_score
  - 0.5 * relevance_score + 0.3 * dotProduct(example_embedding_field)
検索レスポンスで結果を取得します。各検索結果には、関連性スコアとドット積の値が含まれます。例:
```
"modelScores": {
  "dotProduct(example_embedding_field)": [0.02150772698223591],
  "relevance_score": [ 0.8828125 ]
}
```
- dotProduct(): 検索結果ドキュメントの計算されたドット積。
- relevance_score: 検索結果ドキュメントの計算された関連性スコア。

次のステップ

取り込み用にデータを準備する。
スキーマを更新する。
検索結果をプレビューする。
カスタムエンベディングが汎用検索アプリの検索品質に与える影響を把握するには、検索品質を評価します。詳細については、検索品質を評価するをご覧ください。

カスタム エンベディングを使用する

始める前に

エンベディングを使用してデータを取り込む

スキーマを更新する

コンソール

REST

エンベディングを指定する

エンベディングをグローバルに指定する

コンソール

REST

検索リクエストごとにエンベディングを指定する

次のステップ

カスタムエンベディングを使用する