メディアドキュメントとデータストアについて

このページでは、メディアのドキュメントとデータストアについて説明します。メディアレコメンデーションまたはメディア検索を使用している場合は、データをアップロードする前に、このページでドキュメントとデータストアのスキーマ要件を確認してください。

概要

ドキュメントは、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": "string",
    },
    "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 つのドキュメントをサポートするために繰り返します。より質の高い結果を得るには、カテゴリのフルパスを使用します。カテゴリのフルパスを表すには、`>` 記号を使用して階層を区切ります。`>` がカテゴリ名の一部である場合は、別の文字に置き換えます。例: `"categories": [ "sports > highlight" ]` ドキュメントに含めることができるカテゴリは 250 個までです。各カテゴリは UTF-8 でエンコードされた文字列で、長さの上限は 5,000 文字です。
`uri`	文字列 - 必須ドキュメントの URI。長さの上限は 5,000 文字です。
`description`	文字列 - 強く推奨ドキュメントの説明。長さの上限は 5,000 文字です。
`media_type`	文字列 - 映画と番組では必須のフィールド最上位のカテゴリ。サポートされているタイプ: `movie`、`show`、`concert`、`event`、`live-event`、`broadcast`、`tv-series`、`episode`、`video-game`、`clip`、`vlog`、`audio`、`audio-book`、`music`、`album`、`articles`、`news`、`radio`、`podcast`、`book`、`sports-game`。値 `movie` と `show` は特別な意味を持ちます。これらにより、ドキュメントが拡充され、ランキングが向上します。また、ユーザーがタイトル検索を行う際に、興味を引く代替コンテンツを見つけやすくなります。
`language_code`	文字列 - 省略可タイトル / 説明と他の文字列属性の言語。BCP 47 で定義されている言語タグを使用します。ドキュメントのレコメンデーションの場合、このフィールドは無視され、テキストの言語が自動的に検出されます。ドキュメントにはさまざまな言語のテキストを含めることができますが、複数の言語でテキストを提供する重複しているドキュメントは、パフォーマンスの低下を招く可能性があります。ドキュメント検索では、このフィールドが使用されます。未設定の場合のデフォルトは「en-US」です。例: `"language_code": "en-US"`
`duration`	文字列 - ビジネス目標がクリック率（CVR）またはセッションあたりの総再生時間であるメディアレコメンデーションアプリに必須です。メディアコンテンツの長さ。時間は文字列としてエンコードする必要があります。エンコードは、`google::protobuf::Duration` JSON 文字列のエンコードと同じである必要があります。例: 「5s」、「1m」
`available_time`	文字列 - 必須エンドユーザーがコンテンツを利用できる時間。このフィールドは、エンドユーザー向けのコンテンツの鮮度を示します。タイムスタンプは RFC 3339 標準に準拠している必要があります。例: `"2022-08-26T23:00:17Z"`
`expire_time`	文字列 - 省略可エンドユーザーに対してコンテンツの有効期限が切れる時刻。このフィールドは、エンドユーザー向けのコンテンツの鮮度を示します。タイムスタンプは RFC 3339 標準に準拠している必要があります。例: `"2032-12-31T23:00:17Z"`
`in_languages`	文字列 - 省略可 - 繰り返しメディアコンテンツの言語。BCP 47 で定義されている言語タグを使用します。例: `"in_languages": [ "en-US"]`
`country_of_origin`	文字列 - 省略可メディアドキュメントの原産国。長さの上限は 128 文字です。例: `"country_of_origin": "US"`
`content_index`	整数 - 省略可メディアドキュメントのコンテンツインデックス。コンテンツインデックスフィールドを使用すると、他のドキュメントと比較してドキュメントを並べ替えることができます。たとえば、エピソード番号をコンテンツインデックスとして使用できます。コンテンツインデックスは正の整数にする必要があります。例: `"content_index": 0`
`filter_tags`	文字列 - 省略可 - 繰り返しドキュメントのタグをフィルタします。ドキュメントごとに最大 250 個の値を指定でき、長さの上限は 1,000 文字です。それ以外の場合は、INVALID_ARGUMENT エラーが返されます。このタグは、タグを `RecommendRequest.filter` の一部として渡すことで、レコメンデーションの結果のフィルタリングに使用できます。例: `"filter_tags": [ "filter_tag"]`
`hash_tags`	文字列 - 省略可 - 繰り返しドキュメントのハッシュタグ。ドキュメントごとに最大 100 個の値を指定でき、長さの上限は 5,000 文字です。例: `"hash_tags": [ "soccer", "world cup"]`
`content_rating`	文字列 - 省略可 - 繰り返しコンテンツの評価。コンテンツアドバイザリーシステムや、視聴者に基づくコンテンツのフィルタリングに使用されます。ドキュメントごとに最大 100 個の値を指定できます。長さの上限は 128 文字です。このタグは、タグを `RecommendRequest.filter` の一部として渡すことで、レコメンデーションの結果のフィルタリングに使用できます。例: `content_rating: ["PG-13"]`

次の表に、階層のキープロパティを示します。

フィールド名	メモ
`images`	オブジェクト - 省略可 - 繰り返し画像関連のプロパティをカプセル化するルートキープロパティ。
`images.uri`	文字列 - 省略可画像の URI。長さの上限は 5,000 文字です。
`images.name`	文字列 - 省略可画像の名前。長さの上限は 128 文字です。
`persons`	オブジェクト - 省略可 - 繰り返し人物関連のプロパティをカプセル化するルートキープロパティ。例: `"persons":[{"name":"sports person","role":"player","rank":0,"uri":"http://example.com/person"}]`
`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 サポートされている値が `role` に適用されていない場合は、`role` を `custom-role` に設定し、`custom_role` フィールドに値を指定します。
`persons.custom_role`	文字列 - 省略可 `custom_role` は、`role` が `custom-role` に設定されている場合にのみ設定されます。UTF-8 でエンコードされた文字列で、長さの上限は 128 文字です。パターン `[a-zA-Z0-9][a-zA-Z0-9_]*` と一致している必要があります。
`persons.rank`	整数 - 省略可ロールのランキングに使用されます。たとえば、最初の actor の場合は `role = "actor", rank = 1`
`persons.uri`	文字列 - 省略可人物の URI。
`organizations`	オブジェクト - 省略可 - 繰り返し `organization` 関連プロパティをカプセル化するルートキープロパティ。例: `"organizations ":[{"name":"sports team","role":"team","rank":0,"uri":"http://example.com/team"}]`
`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 サポートされている値が `role` に適用されていない場合は、`role` を `custom-role` に設定し、`custom_role` フィールドに値を指定します。
`organizations.custom_role`	文字列 - 省略可 `custom_role` は、`role` が `custom-role` に設定されている場合にのみ設定されます。UTF-8 でエンコードされた文字列で、長さの上限は 128 文字です。パターン `[a-zA-Z0-9][a-zA-Z0-9_]*` と一致している必要があります。
`organizations.rank`	文字列 - 省略可ロールのランキングに使用されます。たとえば、最初の publisher の場合: `role = "publisher", rank = 1`。
`organizations.uri`	文字列 - 省略可組織の URI。
`aggregate_ratings`	オブジェクト - 省略可 - 繰り返し `aggregate_rating` 関連プロパティをカプセル化するルートキープロパティ。
`aggregate_ratings.rating_source`	文字列 - 必須評価のソース。たとえば、`imdb` や、`rotten_tomatoes` です。UTF-8 でエンコードされた文字列で、長さの上限は 128 文字です。パターン `[a-zA-Z0-9][a-zA-Z0-9_]*` と一致している必要があります
`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": []
  }
]

メディア ドキュメントとデータストアについて

概要

Google の事前定義スキーマとカスタム スキーマ

Document の JSON スキーマ

サンプル JSON Document オブジェクト