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

本页面提供有关媒体文档和数据存储区的信息。 如果您使用媒体推荐或媒体搜索,请查看 本页面上列出了对文档和数据存储区的架构要求, 上传数据。

概览

文档是您上传到 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_,有些则是 pluralized.)

Document 的 JSON 架构

使用媒体时,文档可以使用 Google 为媒体预定义的 JSON 架构。

使用 JSON 或 Struct 数据表示形式上传文档。确保文档 JSON 或结构体符合以下 JSON 架构。JSON 架构用途 JSON 架构 2020-12 进行验证。有关 JSON 架构的更多信息,另请参阅 JSON 架构规范文档 json-schema.org

{
  "$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 文档的完整、唯一资源名称。必需(针对所有广告) Document 方法(createimport。导入期间,系统会自动生成名称 无需手动提供
id 内部数据库使用的文档 ID。ID 字段 在整个数据存储区中是唯一的。记录用户事件时,也会使用同一个值,recommendsearch 方法也会返回该值。
schemaId 必需。位于同一数据存储区中的架构的标识符。 应设置为“default_schema”,系统会在创建默认数据存储时自动创建该架构。
parentDocumentId 父文档的 ID。对于顶级(根)文档, parent_document_id 可以为空,也可以指向自身。对于 子文档,parent_document_id 应指向一个有效的 根文档。

关键属性

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

如需详细了解 JSON 属性,请参阅“了解 JSON 架构” 文档 属性 json-schema.org

下表定义了 Flat 键属性。

字段名称 备注
title

字符串 - 必填

数据库中的文档标题。UTF-8 编码的字符串。仅限 1000 个字符。

categories

字符串 - 必填

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

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

例如:

"categories": [ "sports > highlight" ]

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

uri

字符串 - 必填

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

description

字符串 - 强烈建议

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

media_type

字符串 - 电影和电视节目需要此字段

顶级类别。

支持的类型:movieshowconcerteventlive-eventbroadcasttv-seriesepisodevideo-gameclipvlogaudioaudio-bookmusicalbumarticlesnewsradiopodcastbooksports-game

movieshow 具有特殊的 差异。它们可以让文档的内容更加丰富 提高排名,并帮助用户通过标题搜索来找到备选标题 展示自己可能感兴趣的内容

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 个值, 长度上限为 5000 个字符。

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

字符串 - 必填

评分来源。例如 imdbrotten_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 集”。这个 级别类型难以配置和维护, 建议。

数据存储区层次结构简介

规划数据存储区层次结构时,请确定您的数据存储区应仅包含父级,还是包含父级和子级。需要注意的要点是 建议和搜索仅返回父文档。

例如,仅父级的数据存储区可能很适合有声读物,而 “推荐”面板会返回所选的单个有声读物。另一方面,如果您将电视节目分集作为父级文档上传到仅包含父级文档的数据存储区,系统可能会在同一面板中推荐多个顺序错误的分集。

电视节目数据存储区可以同时使用父级和子级,其中每个父级文档代表一个电视节目,子级文档代表该电视节目的剧集。这种两级数据存储区允许 面板显示一系列类似的电视节目最终用户可以点击特定节目,选择要观看的分集。

由于父子层次结构难以配置和维护, 建议使用仅父级的数据存储区。

例如,电视节目数据存储区可以很好地用作仅包含父级文档的数据存储区,其中每个父级文档代表一个可推荐的电视节目,不包含单个剧集(因此也不会推荐单个剧集)。

如果您确定数据存储区需要同时包含父级和子级(即组和单个项),但目前只有单个项,则需要为组创建父级。您所需的 为 idtitlecategories。如需更多信息 请参阅文档字段部分。

媒体的 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": []
  }
]