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

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

データ用に独自のカスタムベクトルエンベディングを作成した場合は、Gemini Enterprise にアップロードしてクエリの実行時に使用できます。

この機能は、カスタムの構造化データまたはメタデータを含む非構造化データが入っているデータストアに対して使用できます。

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

公開データでトレーニングしても意味的な類似性を捉えられない内部用語（非公開のドキュメントでのみ使用される組織固有の用語など）のようなカスタムの語句を使ってエンベディングをトレーニングした場合。
ユーザープロファイル用に作成したエンベディングを使用して、意味的に関連するドキュメントのパーソナライズされたランキングを作成したい場合。そのエンベディングによってパーソナライズベースのランキングを取得することで、関連性に基づくランキング用の Google のドキュメントエンベディングを強化できます。

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

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

始める前に

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

エンベディングは、構造化データと、メタデータを含む非構造化データに対応しています
エンベディングは 1 次元配列として提供される必要があります
エンベディングの次元は 1～768 の範囲に含まれる整数である必要があります
エンベディングはテキストと画像で利用できます（動画では利用できません）
2 つまでのフィールドをエンベディングのキープロパティフィールドとしてタグ付けできます（A/B テストなどのケースで 2 つのフィールドを使用する場合があります）
エンベディングフィールドをキープロパティとして指定した後は、その設定を解除できません

エンベディングを含むデータを取り込む

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

エンベディングを含むデータを取り込むには:

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

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

スキーマを更新する

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

コンソール

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

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

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

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

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

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

REST

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

スキーマを更新するに記載された REST 向けの手順に沿って、各エンベディングフィールドのキープロパティマッピングとディメンション数を次のように指定します。
- "keyPropertyMapping": "embedding_vector"
- "dimension": NUMBER_OF_DIMENSIONS
たとえば、768 個のディメンションを持つフォーマット済み JSON スキーマを example_embedding_vector フィールド用に指定する場合は次のようになります。
```
  {
    "$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 コンソールで、[Gemini Enterprise] ページに移動します。

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

利用できる関数は次のとおりです。
- DOUBLE * relevance_score
- DOUBLE * dotProduct(EMBEDDING_FIELD_PATH)
次の変数を使用できます。
- relevance_score: Gemini Enterprise で提供されている、ドキュメントの関連性を測定する事前定義変数。スコアの範囲は 0～1.0 です。
- dotProduct(): Gemini Enterprise で提供されている事前定義関数。この関数では、embeddingVector.fieldPath で指定したものと同じフィールド名を指定する必要があります。
例:
- 0.3 * relevance_score
- 0.5 * relevance_score + 0.3 * dotProduct(example_embedding_field)

REST

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

更新するフィールドを指定して、servingConfig エンティティの PATCH リクエストを実行します。更新するフィールドは 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: Gemini Enterprise で提供されている事前定義変数。
- dotProduct(): Gemini Enterprise で提供されている事前定義関数。ドット積は正規化されます。この関数では、embeddingVector.fieldPath で指定したものと同じフィールド名を指定する必要があります。
例:
- 0.3 * relevance_score
- 0.5 * relevance_score + 0.3 * dotProduct(example_embedding_field)
検索リクエストの送信時に、servingConfig.embeddingConfig が自動的に含められます。

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

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

API を使用して、単一の検索リクエスト用のエンベディングを指定できます。リクエストごとに指定されたエンベディングは、グローバルに指定されたエンベディングをオーバーライドします。

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: Gemini Enterprise で提供されている、ドキュメントの関連性を測定するための事前定義変数。スコアの範囲は 0～1.0 です。
  - dotProduct(): Gemini Enterprise で提供されている事前定義関数。この関数では、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

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

次のステップ

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