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 スキーマ形式を使用して定義できます。これは、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 UTC2024-08-05T08:30:00Z2024-08-05T01:30:00-07:002024-08-052024-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フィールドを含める必要はありません。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 }'以下を置き換えます。
PROJECT_ID: Google Cloud プロジェクトの ID。DATA_STORE_ID: Vertex AI Search データストアの 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" } } }
省略可: スキーマ定義を表示するの手順に沿ってスキーマを確認します。