このページは Cloud Translation API によって翻訳されました。

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

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

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

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

データストアのスキーマを指定する方法

構造化データのスキーマを決定する方法はいくつかあります。

自動検出と編集。Vertex AI Agent Builder が初期スキーマを自動検出して提案できるようにします。次に、コンソールインターフェースでスキーマを絞り込みます。フィールドが自動検出された後、キープロパティをすべての重要なフィールドにマッピングすることを強くおすすめします。

これは、検索データストアを作成すると汎用レコメンデーションデータストアを作成するで、構造化データに対する Google Cloud コンソール手順に沿って使用するアプローチです。
スキーマを JSON オブジェクトとして指定します。スキーマを JSON オブジェクトとして Vertex AI Agent Builder に指定します。正しい JSON オブジェクトを準備する必要があります。JSON オブジェクトの例については、JSON オブジェクトとしてのスキーマの例をご覧ください。スキーマを作成したら、そのスキーマに従ってデータをアップロードします。

これは、curl コマンド（またはプログラム）を使用して API を介してデータストアを作成する場合に使用できるアプローチです。たとえば、BigQuery から 1 回インポートするをご覧ください。独自のスキーマを指定するの手順もご覧ください。
メディア: Google が定義したスキーマでデータを指定します。メディア用のデータストアを作成する場合は、Google の事前定義スキーマを使用できます。このオプションを選択した場合、メディアドキュメントとデータストアについてで説明されている形式で JSON オブジェクトを構造化していることを前提としています。デフォルトでは、自動検出はデータ取り込み中に検出された新しいフィールドをスキーマに追加します。

これは、メディアアプリとデータストアを作成するの手順に沿って使用するアプローチです。これは、メディアレコメンデーションを使ってみるとメディア検索を使ってみるのチュートリアルでも使用されているアプローチです。これらのチュートリアルでは、サンプルデータが Google の事前定義スキーマで提供されています。
メディア: 自動検索と編集。必要なメディアプロパティが含まれていることを確認します。メディアデータの場合は、自動検出を使用してスキーマを提案し、編集して絞り込むことができます。JSON オブジェクトには、メディアのキープロパティ（title、uri、category、media_duration、media_available_time）にマッピングできるフィールドを含める必要があります。

これは、メディアデータが Google 定義のスキーマにない場合に、Google Cloud コンソールからメディアデータをインポートする際に使用するアプローチです。
メディア: 独自のスキーマを JSON オブジェクトとして指定します。スキーマを JSON オブジェクトとして Vertex AI Agent Builder に指定します。正しい JSON オブジェクトを準備する必要があります。スキーマには、メディアのキープロパティ（title、uri、category、media_duration、media_available_time）にマッピングできるフィールドを含める必要があります。

JSON オブジェクトの例については、JSON オブジェクトとしてのスキーマの例をご覧ください。スキーマを作成したら、そのスキーマに従ってメディアデータをアップロードします。

このアプローチでは、curl コマンド（またはプログラム）を介して API を使用します。独自のスキーマを指定するの手順をご覧ください。

自動検出と編集について

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

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

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

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

独自のスキーマは、JSON Schema 形式を使用して定義できます。これは、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
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

メディアスキーマを定義する場合は、メディアのキープロパティにマッピングできるフィールドを含める必要があります。これらのキープロパティを次の例で示します。

次のスキーマの例でフィールドの一部を示します。

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

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

デフォルトは "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
datatime_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 です。
keyPropertyMapping。事前定義されたキーワードをドキュメントの重要なフィールドにマッピングするフィールド。これにより、セマンティックな意味を明確にできます。値は、title、description、uri、category です。フィールド名は keyPropertyValues 値と一致する必要はありません。たとえば、my_title という名前のフィールドには、値が title の keyPropertyValues フィールドを含めることができます。

検索データストアの場合、keyPropertyMapping でマークされたフィールドは、デフォルトでインデックス登録可能で検索可能ですが、取得可能、補完可能、動的ファセット可能ではありません。つまり、想定されるデフォルトの動作を取得するために、keyPropertyValues フィールドに indexable フィールドまたは searchable フィールドを含める必要はありません。

注: キープロパティを使用すると、検索とレコメンデーションの結果の品質と、検索の自動補完の精度を高めることができます。スキーマの自動検出を使用する場合、キープロパティは自動的に追加されません。schemas.patch メソッドを使用して、データフィールドをキープロパティ（特に title、uri、description）としてマークすることを強くおすすめします。
type。フィールドのタイプ。これは、datetime、geolocation、またはプリミティブ型（integer、boolean、object、array、number、string）のいずれかの文字列値です。

次のプロパティフィールドは、検索アプリにのみ適用されます。

retrievable。このフィールドを検索レスポンスで返すことができるかどうかを示します。これは、number、string、boolean、integer、datetime、geolocation タイプのフィールドに設定できます。取得可能として設定できるフィールドは最大 50 個です。ユーザー定義フィールドと keyPropertyValues フィールドは、デフォルトでは取得できません。フィールドを取得可能にするには、フィールドに "retrievable": true を含めます。
indexable。このフィールドを servingConfigs.search メソッドでフィルタ、ファセット、ブースト、並べ替えることができるかどうかを示します。これは、number、string、boolean、integer、datetime、geolocation タイプのフィールドに設定できます。インデックス登録可能として設定できるフィールドは最大 50 個です。keyPropertyMapping フィールドを含むフィールドを除き、ユーザー定義フィールドはデフォルトでインデックスに登録できません。フィールドをインデックス登録可能にするには、フィールドに "indexable": true を含めます。
dynamicFacetable。このフィールドを動的ファセットとして使用できることを示します。これは、number、string、boolean、integer タイプのフィールドに設定できます。フィールドを動的にファセット可能にするには、インデックス登録可能にする必要があります。フィールドに "dynamicFacetable": true と "indexable": true を含めます。
searchable。このフィールドをリバースインデックス化して、非構造化テキストクエリと照合できるかどうかを示します。これは、string タイプのフィールドにのみ設定できます。検索可能として設定できるフィールドは最大 50 個です。keyPropertyMapping フィールドを含むフィールドを除き、ユーザー定義フィールドはデフォルトで検索できません。フィールドを検索可能にするには、フィールドに "searchable": true を含めます。
completable。このフィールドを自動入力候補として返すことができるかどうかを示します。これは、string タイプのフィールドにのみ設定できます。フィールドを補完可能にするには、フィールドに "completable": true を含めます。

また、次のフィールドはレコメンデーションアプリにのみ適用されます。

recommendationsFilterable。このフィールドをレコメンデーションのフィルタ式で使用できることを示します。レコメンデーションのフィルタリングに関する一般的な情報については、レコメンデーションをフィルタリングするをご覧ください。
```
  ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },
```

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

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

JSON オブジェクトとしてのスキーマの例をガイドとして、スキーマを JSON オブジェクトとして準備します。

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

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: Google Cloud プロジェクトの ID。
DATA_STORE_ID: 作成する Vertex AI Search データストアの ID。この ID に使用できるのは、小文字、数字、アンダースコア、ハイフンのみです。
DATA_STORE_DISPLAY_NAME: 作成する Vertex AI Search データストアの表示名。
INDUSTRY_VERTICAL: GENERIC または MEDIA

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
}'