这是与 Recommendations AI、Retail Search 和新的 Retail 控制台相关的文档。如需在受限 GA 阶段使用 Retail Search,请与 Cloud 销售人员联系

如果您仅使用 Recommendations AI,请保留在 Recommendations 控制台上并参阅 Recommendations AI 文档

目录和目录信息

本页面提供了创建目录信息和填充目录数据的最佳做法。

概览

导入到 Retail 的目录数据会直接影响生成的模型的质量,因此 Retail API 提供的结果的质量。通常,您提供的目录信息越准确、具体,您的模型质量就越高。

您的目录应保持最新。您可以根据需要随时上传目录更改;理想情况下,对于变化率较高的目录,每天都应该如此。您可以上传(补丁)现有产品项;系统只会更新更改后的字段。上传目录信息不收取任何费用。如需了解详情,请参阅使目录保持最新状态

目录分支

使用目录分支测试您离线上传的新数据,然后在您的网站上发布。

使用 Retail API,您最多可以使用三个分支,标识为 012。实际网站指向其目录数据的 default_branch。使用 setDefaultBranch 或 Cloud Console 中的“数据”标签页,指定是您当前实际 default_branch 的分支(默认设置为分支 0)。然后,由于您的网站的目录数据指向 default_branch,您

例如,假设 default_branch 当前设置为分支 ID 0,因此您的网站正在使用已上传到该分支的目录数据。您可以将新的目录数据上传到分支 1 并进行预览。确认目录已正确上传后,您可以切换到分支 1 作为实际 default_branch

产品

目录是一系列产品对象的集合。

必需的产品信息

以下字段为必填字段;在目录中创建产品项时,您必须提供这些值。它们还应与您内部产品数据库中使用的值对应,并且应准确反映所表示的产品,因为它们包含在训练模型中。

在某些情况下,其他字段也是必填字段。请参阅 Product 参考页面上的所有产品字段的完整列表。

您提供的所有商品信息都可以用来提高推荐内容和搜索结果的质量。请务必提供尽可能多的字段。

字段 备注
name 产品的完整、唯一资源名称。除 import 以外的所有产品方法都需要此名称。在导入期间,该名称是自动生成的,不需要手动提供。
id 产品数据库使用的产品 ID。ID 字段在整个目录中必须是唯一的。记录用户事件时,也会使用同一个值,predictsearch 方法也会返回该值。
title 产品数据库中的产品标题。UTF-8 编码的字符串。字符数不得超过 1250 个。

商品特性

强烈建议您在 Product 中为预定义系统特性提供值,如品牌、颜色和尺寸。您还可以添加使用 Product.attributes 定义的自定义特性。

如果您使用的是 Retail Search,则搜索响应中会包含商品附带的特性(如果您在 Product.retrievableFields 中将这些特性标记为可检索)。然后这些特性可用于其他 Retail Search 功能,例如过滤和构面。

使用商品级别

首次导入目录时,您必须指定是仅提供主项还是提供主项及其变体。

  • 主要商品是 Retail API 在预测或搜索结果中返回的内容。主项可以是单独的(SKU 级别)项,也可以是一组类似项(SKU 组)。默认情况下,Retail API 配置为仅导入主项。
  • 变体项是一个主项的各个版本。变体只能是单独的(SKU 级别)项。例如,如果主商品是“V 领衬衫”,变体可能是“棕色 V 领衬衫,XL 码”和“白色 V 领衬衫,S 码”。主项和变体有时被称为“父项”和“子项”。导入变体是可选操作。

目录导入期间,使用 Catalog.patch 方法设置商品级别。例如:

curl -X PATCH 
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
-H "Content-Type: application/json; charset=utf-8"
--data '{ "productLevelConfig": { "ingestionProductType": "PRODUCT-TYPE", "merchantCenterProductIdField": "PRODUCT-ID-FIELD" } }'
"https://retail.googleapis.com/v2/projects/[PROJECT_ID]/locations/global/catalogs/default_catalog"

要确定实现的最佳商品级别选择,您需要查看目录数据和网站逻辑。捕获用户事件数据时,您可以使用哪些商品 ID?与预测或搜索结果一起返回的哪些商品 ID 最有效?这些 ID 是如何进行相互比较和关联的?

请根据您是否从 Merchant Center 导入,执行相应的步骤:

确定要从 Merchant Center 导入的商品级别

当您从 Merchant Center 导入目录数据时,Retail API 会使用 ingestionProductType 来帮助确定要上传为主项还是变体,并使用 merchantCenterProductIdField 字段来指定要使用 Merchant Center offer_id 还是 item_group_id 作为商品 ID

查看目录数据和网站逻辑以回答以下问题:

  • 我的目录中是否同时包含主项和变体?
  • 如果是,当我捕获用户事件数据时,我可以提供什么级别的项?
  • 我需要在结果中返回什么类型的项?

确定以下内容是否为真:

  1. 您的目录只有一个项级别。这意味着以下二者之一:

    • 您的所有商品和事件均为 SKU 级别,您需要 SKU 级别的预测。
    • 您的所有商品和事件均为组级别,您需要组级别的预测。

    如果是这样,则仅导入主项。这是默认的导入设置。

  2. 您需要组级别(主项)的预测,但您的 Merchant Center 商品是 SKU 级别。在这种情况下,您的导入决策取决于事件的捕获方式。

    1. 您的活动在组级别捕获。如果是这样,请在导入过程中使用以下设置:

      如果多个 Merchant Center 商品具有相同的 Merchant Center item_group_id,Retail 只导入其中一个商品作为主商品,并使用 item_group_id 作为商品 ID。在这种情况下,没有 item_group_id 的商品将无法导入。记录的事件必须引用主(组级别)商品 ID。

    2. 您的活动在 SKU 级别捕获。如果是这样,请在导入过程中使用以下设置:

      Retail 将您的商品作为变体导入,并使用 Merchant Center offer_id 作为商品 ID。记录的事件必须引用变体(SKU 级别)商品 ID。

确定不使用 Merchant Center 导入的商品级别

您的所有商品要么都必须具有 primaryProductId 值,要么都不具有该值。您无法导入有些项设置了 primaryProductId 有些项却没有设置的目录数据。

  1. 如果您的目录只有一个项级别,则可能意味着:

    • 您的所有商品和事件均为 SKU 级别,您需要 SKU 级别的结果。
    • 您的所有商品和事件均为组级别,您需要组级别的结果。

    如果是这样,则仅导入主项。这是默认的推荐导入设置。

  2. 如果您的事件和商品为 SKU 级别,您可以获取组级别结果。在导入过程中将 ingestionProductType 设置为 variant

如果只有组级别的事件和产品,则不支持 SKU 级别预测和搜索。

如果您打算将来从 Merchant Center 导入目录数据,请按照 Merchant Center 导入的说明检查数据,以确保您作出正确的选择。只能通过删除目录并重新上传来更改此配置(请参阅更改商品级别配置)。

目录数据质量指标

为了帮助您监控目录数据的搜索质量,Retail 会根据一组质量规则评估您的商品数据。您可以在 Retail 数据页面上查看符合每个质量规则的商品所占百分比。

下表介绍了 Retail 用于帮助您评估商品数据的质量指标:

目录质量指标 质量规则 备注
存在 URI 且可访问 商品具有有效的 Product.uri。URI 必须可访问且与您的网域匹配。 Cloud Retail Search 会使用通过此 URI 抓取的网络信号来提高搜索质量。
符合时间一致性 Product.availableTime 早于当前时间,Product.expireTime 晚于当前时间。 只有符合时间一致性的商品可供搜索。
存在可搜索特性 商品至少有一个设置为可搜索的 attribute 标记为可搜索的自定义特性可通过文本查询进行搜索。
说明存在 产品包含非空的 Product.description 全面的说明有助于提高搜索质量。
标题至少包含两个字词 Product.title 至少包含两个字词。 全面的标题有助于提高搜索质量。
包含不同的图片 variant 商品至少有一个 Product.image。如果您的所有商品均处于 primary 级别,则您可以忽略此指标。 该指标仅供参考,不会影响搜索质量。
包含不同的价格信息 variant 商品设置了 Product.priceInfo。如果您的所有商品均处于 primary 级别,则您可以忽略此指标。 该指标仅供参考,不会影响搜索质量。

Retail 架构

从 BigQuery 导入目录时,请使用下方的 Retail 架构创建具有正确格式的 BigQuery 表格,并将其与您的目录数据一起加载。然后,导入目录