スキーマを指定または自動検出する

Google Cloud コンソールを使用して構造化データをインポートすると、Gemini Enterprise はスキーマを自動的に検出します。この自動検出されたスキーマをエンジンで使用することも、API を使用してデータの構造を示すスキーマを指定することもできます。

スキーマを指定した後で新しいスキーマで更新する場合、新しいスキーマは元のスキーマと下位互換性がある必要があります。そうでない場合、スキーマの更新は失敗します。

スキーマのリファレンス情報については、dataStores.schemas をご覧ください。

データストアのスキーマを提供する方法

構造化データのスキーマを決定するには、さまざまな方法があります。

  • 自動検出と編集。Gemini Enterprise に初期スキーマを自動検出させて提案させます。次に、コンソール インターフェースでスキーマを調整します。フィールドが自動検出された後、キープロパティをすべての重要なフィールドにマッピングすることを強くおすすめします。

    これは、ファーストパーティ データストアを作成するで、 Google Cloud コンソールを使用して構造化データを処理する場合の方法です。

  • スキーマを JSON オブジェクトとして指定します。スキーマを JSON オブジェクトとして Gemini Enterprise に提供します。正しい JSON オブジェクトを準備しておく必要があります。JSON オブジェクトの例については、JSON オブジェクトとしてのスキーマの例をご覧ください。スキーマを作成したら、そのスキーマに従ってデータをアップロードします。

    これは、curl コマンド(またはプログラム)を使用して API 経由でデータストアを作成する場合に使用できる方法です。たとえば、BigQuery から 1 回インポートするをご覧ください。独自のスキーマを指定するの手順もご覧ください。

自動検出と編集について

データのインポートを開始すると、Gemini Enterprise はインポートされた最初の数個のドキュメントをサンプリングします。これらのドキュメントに基づいて、データのスキーマが提案されます。このスキーマは、後で確認または編集できます。

キープロパティにマッピングするフィールドがサンプリングされたドキュメントにない場合は、スキーマを確認するときにこれらのフィールドを手動で追加できます。

Gemini Enterprise がデータ インポートの後半で追加のフィールドを検出した場合でも、これらのフィールドはインポートされ、スキーマに追加されます。すべてのデータをインポートした後にスキーマを編集する場合は、スキーマを更新するをご覧ください。

Gemini Enterprise がスキーマを自動検出すると、検出されたフィールドに対して次のフィールド設定が自動的に構成されます。ただし、フィールドの最大上限内に収まっている必要があります。

フィールド タイプ 自動検出されたフィールドのデフォルト設定
string indexable、retrievable、searchable、dynamicFacetable
integer、number、boolean indexable、retrievable、dynamicFacetable
object(datetime、geolocation、array)以外の任意の型 indexable、retrievable
object なし

JSON オブジェクトとしてのスキーマの例

独自のスキーマは、JSON スキーマ形式を使用して定義できます。これは、JSON ドキュメントの定義、アノテーション、検証を行うオープンソースの宣言型言語です。たとえば、次の JSON スキーマ アノテーションが有効です。

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "dynamic": "true",
  "datetime_detection": true,
  "geolocation_detection": true,
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title",
      "retrievable": true,
      "completable": true
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "brand": {
      "type": "string",
      "indexable": true,
      "dynamicFacetable": true
    },
    "location": {
      "type": "geolocation",
      "indexable": true,
      "retrievable": true
    },
    "creationDate": {
      "type": "datetime",
      "indexable": true,
      "retrievable": true
    },
    "isCurrent": {
      "type": "boolean",
      "indexable": true,
      "retrievable": true
    }
  }
}

トップレベルのスキーマ設定

JSON スキーマの次の最上位フィールドは、ドキュメントのインポート時に Gemini Enterprise がフィールドを検出して追加する方法を制御します。

  • dynamic。dynamic が文字列値 "true" に設定されている場合、インポートされたデータで見つかった新しいプロパティがスキーマに追加されます。 dynamic が "false" に設定されている場合、インポートされたデータで見つかった新しいプロパティは無視されます。プロパティはスキーマに追加されず、値もインポートされません。

    たとえば、スキーマに title と description の 2 つのプロパティがあり、title、description、rating のプロパティを含むデータをアップロードします。dynamic が "true" の場合、ratings プロパティとデータがインポートされます。dynamic が "false" の場合、title と description はインポートされますが、rating プロパティはインポートされません。

    デフォルトは "true" です。

  • datetime_detection。datetime_detection がブール値 true に設定されている場合、日時形式のデータがインポートされると、スキーマタイプは datetime に設定されます。サポートされている形式は、RFC 3339 と ISO 8601 です。

    例:

    • 2024-08-05 08:30:00 UTC

    • 2024-08-05T08:30:00Z

    • 2024-08-05T01:30:00-07:00

    • 2024-08-05

    • 2024-08-05T08:30:00+00:00

    datetime_detection がブール値 false に設定されている場合、日時形式のデータがインポートされると、スキーマタイプは string に設定されます。

    デフォルトは true です。

  • geolocation_detection。geolocation_detection がブール値 true に設定されている場合、位置情報形式のデータがインポートされると、スキーマタイプは geolocation に設定されます。データが緯度と経度の数値を含むオブジェクト、または住所の文字列を含むオブジェクトである場合、データは位置情報として検出されます。

    例:

    • "myLocation": {"latitude":37.42, "longitude":-122.08}

    • "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}

    geolocation_detection がブール値 false に設定されている場合、位置情報形式のデータがインポートされると、スキーマタイプは object に設定されます。

    デフォルトは true です。

プロパティ単位のフィールド設定

properties オブジェクト内の各フィールドは、次のアノテーションをサポートして、データ型、キープロパティ マッピング、検索動作を定義します。

  • keyPropertyMapping。事前定義されたキーワードをドキュメント内の重要なフィールドにマッピングし、その意味を明確にする際に役立つフィールド。値は title、description、uri、category です。フィールド名は keyPropertyValues 値と一致する必要はありません。たとえば、my_title という名前のフィールドに、値が title の keyPropertyValues フィールドを含めることができます。

    keyPropertyMapping アノテーションが付いたフィールドは、キー プロパティによって決定される事前定義の indexable 設定と searchable 設定を使用します。デフォルトでは、retrievable、completable、dynamicFacetable ではありません。indexable と searchable は事前定義されているため、JSON スキーマの同じフィールドに明示的な "indexable" アノテーションまたは "searchable" アノテーションを含めることはできません。false の値であっても同様です。それ以外の場合、リクエストは INVALID_ARGUMENT エラー(Key property FIELD_NAME should not contain searchable or indexable annotation.)で失敗します。"retrievable": true を含めることで、マッピングされたフィールドが検索結果に返されるようにできます。

  • type。フィールドの型。これは、datetime、geolocation、またはプリミティブ型(integer、boolean、object、array、number、string)のいずれかの文字列値です。

  • retrievable。このフィールドを検索レスポンスで返すことができるかどうかを示します。これは、number、string、boolean、integer、datetime、geolocation タイプのフィールドに設定できます。取得可能として設定できるフィールドは最大 50 個です。JSON スキーマを明示的に指定または更新すると、スキーマ定義で "retrievable": true を明示的に設定しない限り、ユーザー定義フィールドと keyPropertyMapping フィールドはデフォルトで retrievable の false になります。

  • indexable。このフィールドを servingConfigs.search メソッドでフィルタ、ファセット、ブースト、並べ替えできるかどうかを示します。これは、number、string、boolean、integer、datetime、geolocation タイプのフィールドに設定できます。インデックス登録可能として設定できるフィールドは最大 50 個です。JSON スキーマを明示的に指定または更新すると、スキーマ定義で "indexable": true を明示的に設定しない限り、ユーザー定義フィールドは indexable の false にデフォルトで設定されます(keyPropertyMapping を含むフィールドを除く)。

  • dynamicFacetable。フィールドを動的ファセットとして使用できることを示します。これは、number、string、boolean、integer タイプのフィールドに設定できます。フィールドを動的ファセット可能にするには、インデックス登録可能にする必要もあります。フィールドに "dynamicFacetable": true と "indexable": true を含めます。

  • searchable。このフィールドをインデックスに逆順に登録して、非構造化テキストクエリと照合できるかどうかを示します。これは、string タイプのフィールドにのみ設定できます。検索可能として設定できるフィールドは最大 50 個です。JSON スキーマを明示的に指定または更新すると、スキーマ定義で "searchable": true を明示的に設定しない限り、ユーザー定義フィールドは searchable の false にデフォルトで設定されます(keyPropertyMapping を含むフィールドを除く)。

  • completable。このフィールドを予測入力の候補として返すことができるかどうかを示します。これは、string タイプのフィールドにのみ設定できます。フィールドを補完可能にするには、フィールドに "completable": true を含めます。

独自のスキーマを JSON オブジェクトとして指定する

独自のスキーマを指定するには、空のスキーマを含むデータストアを作成し、スキーマを更新して、スキーマを JSON オブジェクトとして指定します。 手順は次のとおりです。

  1. JSON オブジェクトとしてのスキーマの例を参考に、スキーマを JSON オブジェクトとして準備します。

  2. データストアを作成します。

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "X-Goog-User-Project: PROJECT_ID" \
    "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
    -d '{
      "displayName": "DATA_STORE_DISPLAY_NAME",
      "industryVertical": "INDUSTRY_VERTICAL"
    }'
    

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

    • PROJECT_ID: 実際のプロジェクトの ID。
    • DATA_STORE_ID: 作成するデータストアの ID。この ID に使用できるのは、小文字、数字、アンダースコア、ハイフンのみです。
    • DATA_STORE_DISPLAY_NAME: 作成するデータストアの表示名。
    • INDUSTRY_VERTICAL: GENERIC
  3. schemas.patch API メソッドを使用して、新しい JSON スキーマを JSON オブジェクトとして指定します。

    curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/schemas/default_schema" \
    -d '{
      "structSchema": JSON_SCHEMA_OBJECT
    }'
    

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

    • PROJECT_ID: 実際のプロジェクトの ID。
    • DATA_STORE_ID: データストアの ID。
    • JSON_SCHEMA_OBJECT: JSON オブジェクトとする新しい JSON スキーマ。例:

      {
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
          "title": {
            "type": "string",
            "keyPropertyMapping": "title"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string",
              "keyPropertyMapping": "category"
            }
          },
          "uri": {
            "type": "string",
            "keyPropertyMapping": "uri"
          }
        }
      }
  4. 省略可: スキーマ定義を表示するの手順に沿って、スキーマを確認します。

次のステップ