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

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

概要

ドキュメントは、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 でエンコードされた文字列。 1,000 文字以内で指定します。
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": []
  }
]