このページでは、メディアのドキュメントとデータストアについて説明します。 メディア レコメンデーションまたはメディア検索を使用している場合は、データをアップロードする前に、このページでドキュメントとデータストアのスキーマ要件を確認してください。
概要
ドキュメントとは、Vertex AI Agent Builder データストアにアップロードするアイテムのことです。メディアの場合、ドキュメントには通常、動画、ニュース記事、音楽ファイル、ポッドキャストなどのメディア コンテンツに関するメタデータ情報が含まれます。API の Document
オブジェクトは、このメタデータ情報をキャプチャします。
データストアには、アップロードしたドキュメントのコレクションが含まれています。データストアを作成するときに、メディア ドキュメントが含まれることを指定します。メディアのデータストアは、メディアアプリにのみアタッチできます。一般的な検索やおすすめなどの他のアプリタイプにはアタッチできません。データストアは、API で DataStore
リソースによって表されます。
アップロードするデータの品質は、メディアアプリが提供する結果の品質に直接影響します。一般に、提供できる正確で具体的な情報が多いほど、結果の品質が高くなります。
データストアにアップロードするデータは、特定の JSON スキーマでフォーマットする必要があります。このスキーマに配置されるデータは、BigQuery テーブル、Cloud Storage 内のファイルまたはファイルセット、または Google Cloud コンソールを使用して直接アップロードできる JSON オブジェクトに存在する必要があります。
Google の事前定義スキーマとカスタム スキーマ
メディアデータ スキーマには 2 つのオプションがあります。
Google の事前定義スキーマ。メディアデータのスキーマをまだ設計していない場合は、Google の事前定義スキーマが適しています。
独自のスキーマ。データがすでにスキーマ形式になっている場合は、独自のスキーマを使用できます。ただし、次の要件があります。
スキーマには、メディアの 5 つのキー プロパティにマッピングできるフィールドが必要です。
title
uri
category
media_available_time
media_duration
このフィールドは、ビジネス目標がコンバージョン率(CVR)または訪問者あたりの総再生時間を最大化することであるメディア レコメンデーション アプリに重要です。
必須ではないキー プロパティもありますが、品質の高い結果を得るには、できるだけ多くのキー プロパティをスキーマにマッピングしてください。これらのメディア プロパティは次のとおりです。
description
(強く推奨)image
image_name
image_uri
language-code
media_aggregated_rating
media_aggregated_rating_count
media_aggregated_rating_score
media_aggregated_rating_source
media_content_index
media_content_rating
media_country_of_origin
media_expire_time
media_filter_tag
media_hash_tag
media_in_language
media_organization
media_organization_custom_role
media_organization_name
media_organization_rank
media_organization_role
media_organization_uri
media_person
media_person_custom_role
media_person_name
media_person_rank
media_person_role
media_person_uri
media_production_year
media_type
これらのプロパティの詳細については、キー プロパティをご覧ください。名前は似ていますが、一部は若干異なります。 (たとえば、一部の名前には
media_
が付加され、一部の名前は複数形になっています)。
Document
の JSON スキーマ
メディアを使用する場合、ドキュメントはメディアに Google の事前定義済み JSON スキーマを使用できます。
ドキュメントは、JSON または構造体データ表現でアップロードされます。ドキュメントの JSON または構造体が次の JSON スキーマに準拠していることを確認します。JSON スキーマでは、検証に JSON Schema 2020-12 が使用されます。JSON スキーマの詳細については、json-schema.org の JSON スキーマ仕様ドキュメントもご覧ください。
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", }, "description": { "type": "string", }, "media_type": { "type": "string", }, "language_code": { "type": "string", }, "categories": { "type": "array", "items": { "type": "string", } }, "uri": { "type": "string", }, "images": { "type": "array", "items": { "type": "object", "properties": { "uri": { "type": "string", }, "name": { "type": "string", } }, } }, "in_languages": { "type": "array", "items": { "type": "string", } }, "country_of_origin": { "type": "string", }, "content_index": { "type": "integer", }, "persons": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", }, "role": { "type": "string", }, "custom_role": { "type": "string", }, "rank": { "type": "integer", }, "uri": { "type": "string", } }, "required": ["name", "role"], } }, "organizations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", }, "role": { "type": "string", }, "custom_role": { "type": "string", }, "rank": { "type": "integer", }, "uri": { "type": "string", } }, "required": ["name", "role"], } }, "hash_tags": { "type": "array", "items": { "type": "string", } }, "filter_tags": { "type": "array", "items": { "type": "string", } }, "duration": { "type": "string", }, "content_rating": { "type": "array", "items": { "type": "string", } }, "aggregate_ratings": { "type": "array", "items": { "type": "object", "properties": { "rating_source": { "type": "string", }, "rating_score": { "type": "number", }, "rating_count": { "type": "integer", } }, "required": ["rating_source"], } }, "available_time": { "type": "datetime", }, "expire_time": { "type": "string", }, "production_year": { "type": "integer", } }, "required": ["title", "categories", "uri", "available_time"], }
サンプル JSON Document
オブジェクト
次の例は、JSON Document
オブジェクトの例を示しています。
{ "title": "Test document title", "description": "Test document description", "media_type": "sports-game", "in_languages": [ "en-US" ], "language_code": "en-US", "categories": [ "sports > clip", "sports > highlight" ], "uri": "http://www.example.com", "images": [ { "uri": "http://example.com/img1", "name": "image_1" } ], "country_of_origin": "US", "content_index": 0, "persons": [ { "name": "sports person", "role": "player", "rank": 0, "uri": "http://example.com/person" }, ], "organizations": [ { "name": "sports team", "role": "team", "rank": 0, "uri": "http://example.com/team" }, ], "hash_tags": [ "tag1" ], "filter_tags": [ "filter_tag" ], "duration": "100s", "production_year": 1900, "content_rating": [ "PG-13" ], "aggregate_ratings": [ { "rating_source": "imdb", "rating_score": 4.5, "rating_count": 1250 } ], "available_time": "2022-08-26T23:00:17Z" }
ドキュメントのフィールド
このセクションでは、データストア用のドキュメントを作成するときに指定するフィールド値について説明します。値は、内部ドキュメント データベースで使用されている値に対応している必要があります。また、表されるアイテムを正確に反映する必要があります。
Document
オブジェクト フィールド
次のフィールドは、Document
オブジェクトの最上位フィールドです。Document
リファレンス ページのこれらのフィールドも参照してください。
フィールド | メモ |
---|---|
name
|
ドキュメントの完全で一意のリソース名。create と import を除くすべての Document メソッドに必須です。インポート時に、名前は自動的に生成されます。手動で指定する必要はありません。
|
id
|
内部データベースで使用されるドキュメント ID。ID フィールドはデータストア全体で一意である必要があります。ユーザー イベントを記録する場合に同じ値が使用されます。また、recommend メソッドと search メソッドによって同じ値が返されます。 |
schemaId
|
必須。同じデータストアにあるスキーマの ID。 「default_schema」として設定する必要があります。これは、デフォルトのデータストアの作成時に自動的に作成されます。 |
parentDocumentId
|
親ドキュメントの ID。トップレベル(ルート)ドキュメントの場合、parent_document_id は空にすることも、自身を参照することもできます。子ドキュメントの場合、parent_document_id は有効なルート ドキュメントを参照する必要があります。
|
基本特性
次のプロパティは、メディアの事前定義された JSON スキーマ形式を使用して定義されます。
JSON プロパティの詳細については、json-schema.org のプロパティに関する Understanding JSON Schema のドキュメントをご覧ください。
次の表に、フラットなキー プロパティを示します。
フィールド名 | メモ |
---|---|
title
|
文字列 - 必須 データベース内のドキュメントのタイトル。UTF-8 でエンコードされた文字列。 1000 文字以内で指定します。 |
categories
|
文字列 - 必須 ドキュメントのカテゴリ。このプロパティは、複数の並列カテゴリに属する 1 つのドキュメントをサポートするために繰り返します。より質の高い結果を得るには、カテゴリのフルパスを使用します。
カテゴリのフルパスを表すには、 例:
ドキュメントに含めることができるカテゴリは 250 個までです。各カテゴリは UTF-8 でエンコードされた文字列で、長さの上限は 5,000 文字です。 |
uri
|
文字列 - 必須 ドキュメントの URI。長さの上限は 5,000 文字です。 |
description
|
文字列 - 強く推奨 ドキュメントの説明。長さの上限は 5,000 文字です。 |
media_type
|
文字列 - 映画と番組では必須のフィールド 最上位のカテゴリ。
サポートされているタイプ:
値 |
language_code
|
文字列 - 省略可 タイトル / 説明と他の文字列属性の言語。BCP 47 で定義されている言語タグを使用します。 ドキュメントのレコメンデーションの場合、このフィールドは無視され、テキストの言語が自動的に検出されます。ドキュメントにはさまざまな言語のテキストを含めることができますが、複数の言語でテキストを提供する重複しているドキュメントは、パフォーマンスの低下を招く可能性があります。
ドキュメント検索では、このフィールドが使用されます。未設定の場合のデフォルトは「en-US」です。
例: |
duration
|
文字列 - ビジネス目標がクリック率(CVR)またはセッションあたりの総再生時間であるメディア レコメンデーション アプリに必須です。
メディア コンテンツの長さ。時間は文字列としてエンコードする必要があります。
エンコードは、 |
available_time
|
日時 - 必須 エンドユーザーがコンテンツを利用できる時間。このフィールドは、エンドユーザー向けのコンテンツの鮮度を示します。タイムスタンプは RFC 3339 標準に準拠している必要があります。 例:
|
expire_time
|
文字列 - 省略可 エンドユーザーに対してコンテンツの有効期限が切れる時刻。このフィールドは、エンドユーザー向けのコンテンツの鮮度を示します。タイムスタンプは RFC 3339 標準に準拠している必要があります。 例:
|
in_languages
|
文字列 - 省略可 - 繰り返し メディア コンテンツの言語。BCP 47 で定義されている言語タグを使用します。
例: |
country_of_origin
|
文字列 - 省略可 メディア ドキュメントの原産国。長さの上限は 128 文字です。
例: |
content_index
|
整数 - 省略可 メディア ドキュメントのコンテンツ インデックス。コンテンツ インデックス フィールドを使用すると、他のドキュメントと比較してドキュメントを並べ替えることができます。たとえば、エピソード番号をコンテンツ インデックスとして使用できます。 コンテンツ インデックスは正の整数にする必要があります。
例: |
filter_tags
|
文字列 - 省略可 - 繰り返し ドキュメントのタグをフィルタします。ドキュメントごとに最大 250 個の値を指定でき、長さの上限は 1,000 文字です。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。
このタグは、タグを
例: |
hash_tags
|
文字列 - 省略可 - 繰り返し ドキュメントのハッシュタグ。ドキュメントごとに最大 100 個の値を指定でき、長さの上限は 5,000 文字です。
例: |
content_rating
|
文字列 - 省略可 - 繰り返し コンテンツの評価。コンテンツ アドバイザリー システムや、視聴者に基づくコンテンツのフィルタリングに使用されます。ドキュメントごとに最大 100 個の値を指定できます。長さの上限は 128 文字です。
このタグは、タグを
例: |
次の表に、階層のキー プロパティを示します。
フィールド名 | メモ |
---|---|
images
|
オブジェクト - 省略可 - 繰り返し 画像関連のプロパティをカプセル化するルートキー プロパティ。 |
images.uri
|
文字列 - 省略可 画像の URI。 長さの上限は 5,000 文字です。 |
images.name
|
文字列 - 省略可 画像の名前。長さの上限は 128 文字です。 |
persons
|
オブジェクト - 省略可 - 繰り返し 人物関連のプロパティをカプセル化するルートキー プロパティ。 例: |
persons.name
|
文字列 - 必須 人物の名前。 |
persons.role
|
文字列 - 必須 メディア アイテム内の人物の役割。 サポートされている値: director、actor、player、team、league、editor、author、character、contributor、creator、editor、funder、producer、provider、publisher、sponsor、translator、music-by、channel、custom-role
サポートされている値が |
persons.custom_role
|
文字列 - 省略可
|
persons.rank
|
整数 - 省略可
ロールのランキングに使用されます。たとえば、最初の actor の場合は |
persons.uri
|
文字列 - 省略可 人物の URI。 |
organizations
|
オブジェクト - 省略可 - 繰り返し
例: |
organizations.name
|
文字列 - 必須 組織の名前。 |
organizations.role
|
文字列 - 必須 メディア アイテムにおける組織の役割。 サポートされている値: director、actor、player、team、league、editor、author、character、contributor、creator、editor、funder、producer、provider、publisher、sponsor、translator、music-by、channel、custom-role
サポートされている値が |
organizations.custom_role
|
文字列 - 省略可
|
organizations.rank
|
文字列 - 省略可
ロールのランキングに使用されます。たとえば、最初の publisher の場合: |
organizations.uri
|
文字列 - 省略可 組織の URI。 |
aggregate_ratings
|
オブジェクト - 省略可 - 繰り返し
|
aggregate_ratings.rating_source
|
文字列 - 必須
評価のソース。たとえば、 |
aggregate_ratings.rating_score
|
ダブル - 省略可 集計された評価。評価は [1, 5] の範囲に正規化する必要があります。 |
aggregate_ratings.rating_count
|
整数 - 省略可 個々のレビューの数。正の値にする必要があります。 |
ドキュメント レベル
ドキュメント レベルによって、データストアの階層が決まります。通常、単一レベルのデータストアまたは 2 レベルのデータストアが必要です。サポートされるのは 2 つのレイヤのみです。
たとえば、各ドキュメントが個別のアイテムである単一レベルのデータストアを作成できます。または、項目のグループと個々の項目の両方を含む 2 レベルのデータストアを選択することもできます。
ドキュメント レベルのタイプ
ドキュメント レベルには次の 2 つのタイプがあります。
親。親ドキュメントは、Vertex AI Search がレコメンデーションと検索で返すものです。親は、個々のドキュメントまたは類似ドキュメントのグループにすることができます。このレベルタイプを推奨します。
子。子ドキュメントは、グループの親ドキュメントのバージョンです。 子にできるのは個々のドキュメントのみです。たとえば、親ドキュメントが「Example TV Show」の場合、子ドキュメントは「Episode 1」と「Episode 2」になります。このレベルタイプは構成とメンテナンスが難しいため、推奨されません。
データストアの階層について
データストアの階層を計画する際は、データストアに親のみを含めるか、親と子を含めるかを決定します。覚えておくべき重要な点は、レコメンデーションと検索では親ドキュメントのみが返されることです。
たとえば、親のみのデータストアはオーディオブックに適しています。ここで、おすすめのパネルは個々のオーディオブックの選択を返します。一方、テレビ番組のエピソードを親ドキュメントとして親専用データストアにアップロードした場合、同じパネルに順序が異なる複数のエピソードがおすすめとして表示される可能性があります。
テレビ番組データストアは、親と子の両方に対応できます。各親ドキュメントはテレビ番組を表し、子ドキュメントはそのテレビ番組のエピソードを表します。この 2 レベルのデータストアを使用すると、おすすめのパネルにさまざまな類似したテレビ番組を表示できます。エンドユーザーは、特定の番組をクリックして視聴するエピソードを選択できます。
親子階層は構成と維持が難しいため、親専用のデータストアを使用することを推奨します。
たとえば、テレビ番組データストアは親のみのデータストアとして適しています。ここで、各親ドキュメントはおすすめできるテレビ番組を表し、個々のエピソードは含まれません(したがっておすすめされません)。
データストアに親と子の両方(つまり、グループと単一アイテム)が必要であるものの、現時点では単一アイテムしかない場合は、グループの親を作成する必要があります。親に指定する必要がある最小限の情報は、id
、title
、categories
です。詳細については、ドキュメント フィールドのセクションをご覧ください。
メディアの BigQuery スキーマ
BigQuery からドキュメントをインポートする場合は、事前定義された BigQuery スキーマを使用して、正しい形式の BigQuery テーブルを作成し、ドキュメント データで読み込んでから、ドキュメントをインポートします。
[ { "name": "id", "mode": "REQUIRED", "type": "STRING", "fields": [] }, { "name": "schemaId", "mode": "REQUIRED", "type": "STRING", "fields": [] }, { "name": "parentDocumentId", "mode": "NULLABLE", "type": "STRING", "fields": [] }, { "name": "jsonData", "mode": "NULLABLE", "type": "STRING", "fields": [] } ]