媒体文档和数据存储区简介

本页介绍了媒体的文档和数据存储区。 如果您使用的是媒体推荐或媒体搜索，请先查看此页面上针对文档和数据存储区的要求，然后再上传数据。

概览

文档是指您上传到 Vertex AI Agent Builder 数据存储区的任何内容。对于媒体，文档通常包含有关媒体内容（例如视频、新闻报道、音乐文件或播客）的元数据信息。API 中的 Document 对象会捕获此元数据信息。

您的数据存储区包含您上传的一系列文档。创建数据存储区时，您可以指定该数据存储区将包含媒体文档。媒体数据存储区只能附加到媒体应用，而不能附加到其他类型的应用（例如通用搜索和推荐）。在该 API 中，数据存储区由 DataStore 资源表示。

您上传的数据质量会直接影响媒体应用提供的结果质量。一般来说，您提供的信息越准确、具体，结果的质量就越高。

您上传到数据存储区的数据必须采用特定 JSON 架构的格式。按照该架构排列的数据必须位于 BigQuery 表、Cloud Storage 中的文件或文件集，或者位于可直接使用 Google Cloud 控制台上传的 JSON 对象中。

Google 预定义架构与自定义架构

您可以为媒体数据架构选择以下两种方案。

  • Google 预定义架构。如果您尚未为媒体数据设计架构，Google 预定义的架构是一个不错的选择。

  • 您自己的架构。如果您的数据已采用架构格式，您可以使用自己的架构，但必须满足以下要求。

    您的架构中必须包含可映射到媒体的五项关键属性的字段：

    • 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 必需。位于同一数据存储区中的架构的标识符。 应设置为“default_schema”，系统会在创建默认数据存储区时自动创建该架构。
parentDocumentId 父文档的 ID。对于顶级（根）文档，parent_document_id 可以为空，也可以指向自身。对于子文档，parent_document_id 应指向有效的根文档。

关键属性

以下媒体属性是使用预定义的 JSON 架构格式定义的。

如需详细了解 JSON 属性，请参阅 json-schema.org 上有关属性的“了解 JSON 架构”文档。

下表定义了扁平键值属性。

字段名称 备注
title

字符串 - 必需

数据库中的文档标题。UTF-8 编码的字符串。不得超过 1,000 个字符。

categories

字符串 - 必需

文档类别。此属性会重复，以支持一个文档属于多个并行类别。使用完整的类别路径可获得更高质量的结果。

如需表示类别的完整路径，请使用 > 符号分隔层次结构。如果 > 是类别名称的一部分，请将其替换为其他字符。

例如：

"categories": [ "sports > highlight" ]

文档最多可包含 250 个类别。每个类别都是一个 UTF-8 编码字符串，长度上限为 5,000 个字符。

uri

字符串 - 必需

文档的 URI。长度上限为 5000 个字符。

description

字符串 - 强烈建议

文档说明。长度上限为 5000 个字符。

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 字符串编码相同。例如：“5 秒”“1 分钟”

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

Int - 可选

媒体文档的内容索引。内容索引字段可用于对文档进行排序。例如，剧集编号可用作内容索引。

内容索引应为非负整数。

例如："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

字符串 - 必需

媒体内容中人物的角色。

支持的值：导演、演员、球员、球队、联盟、编辑、作者、角色、贡献者、创作者、编辑者、资助者、制作人、提供商、发布商、赞助商、译者、音乐人、频道、自定义角色

如果没有任何受支持的值应用于 role，请将 role 设为 custom-role，并在 custom_role 字段中提供值。

persons.custom_role

字符串 - 可选

仅当 role 设置为 custom-role 时，才会设置 custom_role。必须是采用 UTF-8 编码的字符串，长度不得超过 128 个字符。必须与 [a-zA-Z0-9][a-zA-Z0-9_]* 格式匹配。
persons.rank

Int - 可选

用于角色排名。例如，对于第一个角色，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

字符串 - 必需

组织在媒体内容中的角色。

支持的值：导演、演员、球员、球队、联盟、编辑、作者、角色、贡献者、创作者、编辑者、资助者、制作人、提供商、发布商、赞助商、译者、音乐人、频道、自定义角色

如果没有任何受支持的值应用于 role，请将 role 设为 custom-role，并在 custom_role 字段中提供值。

organizations.custom_role

字符串 - 可选

仅当 role 设置为 custom-role 时，才会设置 custom_role。必须是采用 UTF-8 编码的字符串，长度不得超过 128 个字符。必须与 [a-zA-Z0-9][a-zA-Z0-9_]* 格式匹配。
organizations.rank

字符串 - 可选

用于角色排名。例如，对于第一个发布商：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

Int - 可选

单独评价的数量。应为非负值。

文档级别

文档级别决定了数据存储区中的层次结构。通常，您应该使用单级数据存储区或双级数据存储区。仅支持两层。

例如，您可以使用单级数据存储区，其中每个文档都是一个单独的项。或者，您也可以选择一个包含内容组和单个内容的两级数据存储区。

文档级类型

文档级类型有两种：

  • 父级。父文档是 Vertex AI Search 在推荐和搜索中返回的内容。父级可以是单个文档，也可以是类似文档的群组。建议使用此级别类型。

  • 子账号。子文档是组父文档的版本。子文件只能是单个文档。例如，如果父文档为“示例电视节目”，子文档可以是“第 1 集”和“第 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": []
  }
]