概览

导入 Recommendations AI 的目录数据会直接影响生成的模型的质量，进而影响 Recommendations AI 提供的预测质量。通常，您提供的目录信息越准确、具体，您的模型质量就越高。

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

产品

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

必需的产品信息

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

在某些情况下，您还需要填写其他字段。请参阅 Product 参考页面上所有产品字段的完整列表。

您提供的所有商品信息都可用于提高建议的质量。请务必提供尽可能多的字段。

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

使用商品级别

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

主项是 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。

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

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

确定以下内容是否为真：

您的目录只有一个项级别。这意味着以下二者之一：
- 您的所有商品和事件均为 SKU 级别，您需要 SKU 级别的预测。
- 您的所有商品和事件均为组级别，您需要组级别的预测。
如果是这样，则仅导入主项。这是默认的导入设置。
您需要组级别（主项）的预测，但您的 Merchant Center 商品是 SKU 级别。在这种情况下，您的导入决策取决于事件的捕获方式。
1. 您的活动在组级别捕获。如果是这样，请在导入过程中使用以下设置：
  - ingestionProductType 设为 primary（默认）
  - merchantCenterProductIdField 设为 itemGroupId。
  如果多个 Merchant Center 商品具有相同的 Merchant Center item_group_id，Recommendations AI 只导入其中一个商品作为主商品，并使用 item_group_id 作为商品 ID。在这种情况下，没有 item_group_id 的商品将无法导入。记录的事件必须引用主（组级别）商品 ID。
2. 您的活动在 SKU 级别捕获。如果是这样，请在导入过程中使用以下设置：
  - ingestionProductType 设为 variant。
  - merchantCenterProductIdField 设为 offerId（默认）。
  Recommendations AI 会将商品导入为变体，并使用 Merchant Center offer_id 作为其商品 ID。记录的事件必须引用变体（SKU 级别）商品 ID。

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

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

如果您的目录只有一个项级别，则可能意味着：
- 您的所有商品和事件均为 SKU 级别，您需要 SKU 级别的预测。
- 您的所有商品和事件均为组级别，您需要组级别的预测。
如果是这样，则仅导入主项。这是默认的推荐导入设置。
如果您的事件和商品为 SKU 级别，您可以获取组级别预测。在导入过程中将 ingestionProductType 设置为 variant。

如果您只有组级别事件和商品，则不支持 SKU 级别预测。

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

Recommendations AI 架构

从 BigQuery 导入目录时，请使用以下 Recommendations AI 架构创建一个格式正确的 BigQuery 表，并将其与您的目录数据一起加载。然后，导入目录。

Recommendations AI 架构 JSON

JSON

[
 {
   "name": "name",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "id",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "primaryProductId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "categories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "title",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "description",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "attributes",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "key",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "value",
       "type": "RECORD",
       "mode": "NULLABLE",
       "fields": [
         {
           "name": "text",
           "type": "STRING",
           "mode": "REPEATED"
         },
         {
           "name": "numbers",
           "type": "FLOAT",
           "mode": "REPEATED"
         }
       ]
     }
   ]
 },
 {
   "name": "tags",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "priceInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "currencyCode",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "price",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "originalPrice",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "cost",
       "type": "FLOAT",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "availableTime",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "availability",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "availableQuantity",
   "type": "INTEGER",
   "mode": "NULLABLE"
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "images",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "uri",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "height",
       "type": "INTEGER",
       "mode": "NULLABLE"
     },
     {
       "name": "width",
       "type": "INTEGER",
       "mode": "NULLABLE"
     }
   ]
 }
]