此页面由 Cloud Translation API 翻译。

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

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

概览

文档是您上传到 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` 方法（`create` 和 `import`。导入期间，系统会自动生成名称无需手动提供
`id`	内部数据库使用的文档 ID。ID 字段在整个数据存储区中是唯一的。记录用户事件时，也会使用同一个值，`recommend` 和 `search` 方法也会返回该值。
`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`	字符串 - 电影和电视节目需要此字段顶级类别。支持的类型：`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 个值，长度上限为 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`	字符串 - 必填评分来源。例如 `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": []
  }
]