このページでは、メディアのドキュメントとデータストアについて説明します。メディア レコメンデーションまたはメディア検索を使用している場合は、データをアップロードする前に、このページのドキュメントとデータストアのスキーマ要件を確認してください。
概要
ドキュメントとは、Vertex AI Search データストアにアップロードするアイテムのことです。メディアの場合、ドキュメントには通常、動画、ニュース記事、音楽ファイル、ポッドキャストなどのメディア コンテンツに関するメタデータ情報が含まれます。API の Document
オブジェクトは、このメタデータ情報をキャプチャします。
データストアには、アップロードしたドキュメントのコレクションが含まれています。データストアを作成するときに、メディア ドキュメントを格納することを指定します。メディアのデータストアは、メディアアプリにのみアタッチできます。カスタム検索やおすすめなどの他のアプリタイプにはアタッチできません。データストアは、API で DataStore
リソースによって表されます。
アップロードするデータの品質は、メディアアプリが提供する結果の品質に直接影響します。一般に、提供できる情報がより正確で具体的であるほど、結果の品質が高くなります。
データストアにアップロードするデータは、特定の JSON スキーマでフォーマットする必要があります。そのスキーマで配置されたデータは、BigQuery テーブル、Cloud Storage のファイルまたはファイルのセット、または Google Cloud コンソールを使用して直接アップロードできる JSON オブジェクトに存在する必要があります。
Google により事前定義されたスキーマとカスタム スキーマ
メディアデータのスキーマには、次の 2 つのオプションがあります。
Google により事前定義されたスキーマ。メディアデータのスキーマをまだ設計していない場合は、Google の事前定義スキーマが適しています。
独自のスキーマ。データがスキーマでフォーマットされている場合は、独自のスキーマを使用できます。詳細については、下記のカスタム スキーマをご覧ください。
どちらのオプションでも、最初のデータ インポート後にスキーマにフィールドを追加できます。ただし、Google の事前定義スキーマを使用する場合、最初のインポートでは、データ フィールドの名前と型が ドキュメント フィールド テーブルのものと完全に一致している必要があります。
基本特性
プロパティは、検索とレコメンデーションのモデルをトレーニングするために使用されます。プロパティ フィールドは、スキーマ内のすべてのフィールドを表します。
キー プロパティは、Google スキーマ内の特別な固定プロパティのセットです。キープロパティは、データの意味を理解するために使用される重要な情報を示します。
カスタム スキーマを使用する場合は、できるだけ多くのキー プロパティにフィールドをマッピングしてください。マッピングは、データをインポートした後に Google Cloud コンソールで行います。メディア データストアを作成するをご覧ください。
Document
の Google 事前定義 JSON スキーマ
メディアを使用する場合、ドキュメントはメディア用の Google 事前定義 JSON スキーマを使用できます。
ドキュメントは、JSON または構造体データ表現でアップロードされます。ドキュメントの JSON または Struct が次の JSON スキーマに準拠していることを確認します。JSON スキーマでは、検証に JSON スキーマ 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", }, "transcript": { "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": "datetime", }, "live_event_start_time": { "type": "datetime", }, "live_event_end_time": { "type": "datetime", }, "production_year": { "type": "integer", } }, "required": ["title", "categories", "uri", "available_time"], }
Document
オブジェクトの JSON サンプル
次の例は、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, "transcript": "Test document transcript", "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 の properties に関する JSON スキーマのドキュメントをご覧ください。
次の表に、フラット フィールドを示します。
フィールド名 | メモ |
---|---|
title
|
文字列 - 必須 データベースのドキュメント タイトル。UTF-8 でエンコードされた文字列。 1,000 文字以内で指定します。 |
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
|
Datetime - 必須 コンテンツをエンドユーザーが利用できる期間。このフィールドは、エンドユーザー向けのコンテンツの鮮度を識別します。タイムスタンプは RFC 3339 標準に準拠している必要があります。 次に例を示します。
空き状況でフィルタするには、レコメンデーションをフィルタすると利用可能なドキュメントをフィルタするをご覧ください。 |
expire_time
|
日時 - 省略可 エンドユーザー向けのコンテンツの有効期限。このフィールドは、エンドユーザー向けのコンテンツの鮮度を識別します。タイムスタンプは RFC 3339 標準に準拠している必要があります。 次に例を示します。
期限切れのドキュメントを結果から除外するには、レコメンデーションをフィルタするとメディア検索をフィルタするをご覧ください。 |
live_event_start_time
|
日時 - 省略可 ライブ イベントの開始時刻。タイムスタンプは RFC 3339 標準に準拠している必要があります。 次に例を示します。
|
live_event_end_time
|
日時 - 省略可 ライブ イベントが終了した時間。タイムスタンプは RFC 3339 標準に準拠している必要があります。 次に例を示します。
|
in_languages
|
文字列 - 省略可 - 繰り返し メディア コンテンツの言語。BCP 47 で定義されている言語タグを使用します。
例: |
country_of_origin
|
文字列 - 省略可 メディア ドキュメントの原産国。長さの上限は 128 文字です。
例: |
transcript
|
文字列 - 省略可 メディア ドキュメントの文字起こし。 |
content_index
|
整数 - 省略可 メディア ドキュメントのコンテンツ インデックス。コンテンツ インデックス フィールドを使用して、ドキュメントを他のドキュメントとの相対的な順序で並べ替えることができます。たとえば、エピソード番号をコンテンツ インデックスとして使用できます。 コンテンツ インデックスは正の整数にする必要があります。
例: |
filter_tags
|
文字列 - 省略可 - 繰り返し ドキュメントのタグをフィルタします。ドキュメントごとに最大 250 個の値を指定でき、長さの上限は 1,000 文字です。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。
これらのタグは、検索結果とレコメンデーションの結果をフィルタリングするために使用できます。レコメンデーションの結果をフィルタするには、タグを
例: |
hash_tags
|
文字列 - 省略可 - 繰り返し ドキュメントのハッシュタグ。ドキュメントごとに最大 100 個の値を指定でき、長さの上限は 5,000 文字です。
例: |
production_year
|
整数 - 省略可 メディアが制作された年。 |
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
|
Double - 必須 集計された評価。評価は [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": [] } ]
カスタム スキーマ
データがスキーマでフォーマットされている場合は、上記の Google の事前定義スキーマを使用しないこともできます。代わりに、独自のスキーマを使用して、スキーマのフィールドをメディアキー プロパティにマッピングできます。データ メディア ストアを作成するときにスキーマをマッピングするには、Google Cloud コンソールを使用します。
独自のスキーマを使用する場合は、スキーマに、メディアの次の 5 つのキー プロパティにマッピングできるフィールドが必要です。
必須のキー プロパティ名 | メモ |
---|---|
title
|
文字列 - 必須 データベースのドキュメント タイトル。UTF-8 でエンコードされた文字列。 1,000 文字以内で指定します。 |
uri
|
文字列 - 必須 ドキュメントの URI。長さの上限は 5,000 文字です。 |
categories
|
文字列 - 必須 ドキュメントのカテゴリ。このプロパティは、複数の並列カテゴリに属する 1 つのドキュメントをサポートするために繰り返します。より質の高い結果を得るには、カテゴリのフルパスを使用します。
カテゴリのフルパスを表すには、 次に例を示します。
ドキュメントに含めることができるカテゴリは 250 個までです。各カテゴリは UTF-8 でエンコードされた文字列で、長さの上限は 5,000 文字です。 |
media_available_time
|
Datetime - 必須 コンテンツをエンドユーザーが利用できる期間。このフィールドは、エンドユーザー向けのコンテンツの鮮度を識別します。タイムスタンプは RFC 3339 標準に準拠している必要があります。 次に例を示します。
空き状況でフィルタするには、レコメンデーションをフィルタすると利用可能なドキュメントをフィルタするをご覧ください。 |
media_duration
|
文字列 - ビジネス目標がクリック率(CVR)またはセッションあたりの総再生時間であるメディア レコメンデーション アプリに必須です。
メディア コンテンツの長さ。時間は文字列としてエンコードする必要があります。
エンコードは、 このフィールドは、ビジネス目標がコンバージョン率(CVR)またはユーザーあたりの総再生時間を最大化することであるメディア レコメンデーション アプリで重要です。 |
また、必須ではないキー プロパティもありますが、品質の高い結果を得るには、これらのプロパティをできるだけ多くスキーマにマッピングしてください。
主なプロパティは次のとおりです。
キー プロパティ名 | メモ |
---|---|
description
|
文字列 - 強く推奨 ドキュメントの説明。長さの上限は 5,000 文字です。 |
image
|
オブジェクト - 省略可 - 繰り返し 画像関連のプロパティをカプセル化するルートキー プロパティ。 |
image_name
|
文字列 - 省略可 画像の名前。長さの上限は 128 文字です。 |
image_uri
|
文字列 - 省略可 画像の URI。 長さの上限は 5,000 文字です。 |
language-code
|
文字列 - 省略可 タイトル / 説明と他の文字列属性の言語。 BCP 47 で定義されている言語タグを使用します。 ドキュメントのレコメンデーションの場合、このフィールドは無視され、テキストの言語が自動的に検出されます。ドキュメントにはさまざまな言語のテキストを含めることができますが、複数の言語でテキストを提供する重複しているドキュメントは、パフォーマンスの低下を招く可能性があります。
ドキュメント検索では、このフィールドが使用されます。未設定の場合のデフォルトは「en-US」です。
例: |
media_aggregated_rating
|
オブジェクト - 省略可 - 繰り返し
|
media_aggregated_rating_count
|
整数 - 省略可 個々のレビューの数。正の値にする必要があります。 |
media_aggregated_rating_score
|
Double - 必須 集計された評価。評価は [1, 5] の範囲に正規化する必要があります。 |
media_aggregated_rating_source
|
文字列 - 必須
評価のソース。たとえば、 |
media_content_index
|
整数 - 省略可 メディア ドキュメントのコンテンツ インデックス。コンテンツ インデックス フィールドを使用して、ドキュメントを他のドキュメントとの相対的な順序で並べ替えることができます。たとえば、エピソード番号をコンテンツ インデックスとして使用できます。 コンテンツ インデックスは正の整数にする必要があります。
例: |
media_content_rating
|
文字列 - 省略可 - 繰り返し コンテンツの評価。コンテンツ アドバイザリー システムや、視聴者に基づくコンテンツのフィルタリングに使用されます。ドキュメントごとに最大 100 個の値を指定できます。長さの上限は 128 文字です。
このタグは、タグを
例: |
media_country_of_origin
|
文字列 - 省略可 メディア ドキュメントの原産国。長さの上限は 128 文字です。
例: |
media_expire_time
|
日時 - 省略可 エンドユーザー向けのコンテンツの有効期限。このフィールドは、エンドユーザー向けのコンテンツの鮮度を識別します。タイムスタンプは RFC 3339 標準に準拠している必要があります。 次に例を示します。
期限切れのドキュメントを結果から除外するには、レコメンデーションをフィルタするとメディア検索をフィルタするをご覧ください。 |
live_event_start_time
|
日時 - 省略可 ライブ イベントの開始時刻。タイムスタンプは RFC 3339 標準に準拠している必要があります。 次に例を示します。
|
live_event_end_time
|
日時 - 省略可 ライブ イベントが終了した時間。タイムスタンプは RFC 3339 標準に準拠している必要があります。 次に例を示します。
|
media_filter_tag
|
文字列 - 省略可 - 繰り返し ドキュメントのタグをフィルタします。ドキュメントごとに最大 250 個の値を指定でき、長さの上限は 1,000 文字です。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。
このタグは、タグを
例: |
media_hash_tag
|
文字列 - 省略可 - 繰り返し ドキュメントのハッシュタグ。ドキュメントごとに最大 100 個の値を指定でき、長さの上限は 5,000 文字です。
例: |
media_in_language
|
文字列 - 省略可 - 繰り返し メディア コンテンツの言語。BCP 47 で定義されている言語タグを使用します。
例: |
media_organization
|
オブジェクト - 省略可 - 繰り返し
例: |
media_organization_custom_role
|
文字列 - 省略可
|
media_organization_name
|
文字列 - 必須 組織の名前。 |
media_organization_rank
|
文字列 - 省略可
役割のランキングに使用されます。たとえば、最初の publisher の場合: |
media_organization_role
|
文字列 - 必須 メディア アイテムにおける組織の役割。 サポートされている値: director、actor、player、team、league、editor、author、character、contributor、creator、editor、funder、producer、provider、publisher、sponsor、translator、music-by、channel、custom-role
サポートされている値が |
media_organization_uri
|
文字列 - 省略可 組織の URI。 |
media_person
|
オブジェクト - 省略可 - 繰り返し 人物関連のプロパティをカプセル化するルートキー プロパティ。 例: |
media_person_custom_role
|
文字列 - 省略可
|
media_person_name
|
文字列 - 必須 人物の名前。 |
media_person_rank
|
整数 - 省略可
役割のランキングに使用されます。たとえば、最初の actor の場合は |
media_person_role
|
文字列 - 必須 メディア アイテムにおける人物の役割。 サポートされている値: director、actor、player、team、league、editor、author、character、contributor、creator、editor、funder、producer、provider、publisher、sponsor、translator、music-by、channel、custom-role
サポートされている値が |
media_person_uri
|
文字列 - 省略可 人物の URI。 |
media_production_year
|
整数 - 省略可 メディアが制作された年。 |
media_transcript
|
文字列 - 省略可 メディア ドキュメントの文字起こし。 |
media_type
|
文字列 - 映画と番組では必須のフィールド 最上位のカテゴリ。
サポートされているタイプ:
値 |
Google の事前定義スキーマではなく独自のスキーマを使用している場合は、独自のスキーマの形式設定とインポートについてスキーマを指定する、または自動検出するをご覧ください。