本页面提供了创建目录信息和填充目录数据的最佳做法。
概览
您导入适用于零售业的 Vertex AI Search 的目录数据会直接影响所生成模型的质量，进而影响搜索和推荐结果的质量。通常，您提供的目录信息越准确、具体，您的模型质量就越高。
您的目录应保持最新。您可以根据需要随时上传目录更改；理想情况下，对于变化率较高的目录，每天都应该如此。您可以上传（补丁）现有产品项；系统只会更新更改后的字段。上传目录信息不收取任何费用。如需了解详情，请参阅使目录保持最新状态。
目录分支
如果您使用搜索，则可以使用目录分支来测试离线上传的新数据，然后再将其发布到网站上。
您最多可以使用三个分支，分别是 0、1 和 2。实际网站指向其目录数据的 default_branch。使用 setDefaultBranch 或 Search for Retail 控制台中的“数据”标签页指定当前是您的当前 default_branch 的分支（默认设置为 0 分支）。然后，您的网站会使用 default_branch 指向的分支提供的目录数据。
例如，假设 default_branch 当前设置为分支 ID 0，因此您的网站正在使用已上传到该分支的目录数据。您可以将新的目录数据上传到分支 1 并进行预览。在确认目录已正确上传后，您可以将分支 1 切换为实时 default_branch。
切换分支后，目录缓存最多可能需要 30 分钟才会更新。
如果您使用建议，我们建议您仅使用默认分支，因为分支切换期间会有更新延迟。如果分支之间的数据差异很大，更新延迟可能会对预测结果产生负面影响。
产品
目录是一系列产品对象的集合。
必需的产品信息
以下字段为必填字段；在目录中创建产品项时，您必须提供这些值。它们还应与您内部产品数据库中使用的值对应，并且应准确反映所表示的产品，因为它们包含在训练模型中。
在某些情况下，还需要填写其他字段。请参阅 Product 参考页面上所有商品字段的完整列表。
您提供的所有商品信息都可以用来提高推荐内容和搜索结果的质量。请务必提供尽可能多的字段。
| 字段 | 备注 |
|---|---|
name
|
产品的完整、唯一资源名称。除 import 外，其他所有 Product 方法都是必需的。导入期间，系统会自动生成名称，无需手动提供。 |
id
|
产品数据库使用的产品 ID。ID 字段在整个目录中必须是唯一的。记录用户事件时，也会使用同一个值，predict 和 search 方法也会返回该值。 |
title
|
产品数据库中的产品标题。UTF-8 编码的字符串。字符数不得超过 1250 个。 |
categories
|
产品类别。每个商品都必须指定至少一个类别。
如果某件商品属于多个类别，请针对每个类别重复此字段。
值必须是一个非空的 UTF-8 编码字符串，长度上限为 5,000 个字符。始终指定完整的类别路径，例如：["Sports & Fitness > Athletic Clothing > Shoes"]。
|
商品特性
强烈建议您在 Product 中为预定义系统特性提供值，如品牌、颜色和尺寸。您还可以添加使用 Product.attributes 定义的自定义特性。
如果您使用搜索，并且您在 Product.retrievableFields 中将属性标记为可检索，则属性会包含在搜索响应中。然后，它们可用于其他搜索功能，例如过滤和分面。
如需了解详情，请参阅商品属性简介。
商品级别
产品级别决定了目录中的层次结构。通常，您需要在单级目录或两级目录之间进行选择。
例如，您可以创建一个单级清单，其中每个商品都有一个 SKU。或者，您也可以选择同时包含 SKU 组和各个 SKU 的两级目录。
产品级类型
商品级分为三种类型：
主要项会在推荐或搜索结果中返回。主实例可以是单独的（SKU 级）项，也可以是包含类似项（SKU 组）的组。
款式/规格商品是 SKU 组主要商品的不同版本。变体只能是单个（SKU 级）商品。例如，如果主要商品是“V 领衬衫”，变体可以是“棕色 V 领衬衫，尺码 XL”和“白色 V 领衬衫，尺码 S”。原初和变体有时被描述为父项和子项。parentparent
集合项是商品的集合。合集是主要商品或多款式商品的套装。例如，集合可以是包含项链、耳环和戒指的珠宝套装。集合仅可用于搜索，并不广泛使用。
目录层次结构简介
在规划目录层次结构时，您需要确定目录应仅包含原版还是原版和变体。需要注意的要点是，预测结果和搜索结果只会返回主要项。
例如，仅主要目录可能非常适合用于销售图书，在这种情况下，推荐面板会返回一系列图书，其中每本图书都有自己的 SKU。但是，如果一个主要的 T 恤目录，则可能会在推荐面板中以每种可用尺寸显示同一款 T 恤。
T 恤目录中最好同时包含原色和变体，并以 SKU 作为变体（每种尺寸对应一个变体），原色代表每种样式的 T 恤尺码的 SKU 组。通过这个两级目录，推荐面板可以显示一系列类似的 T 恤样式。买家可以深入了解特定的主款式（款式），以选择要购买的款式/规格（尺寸）。
此外，还有一种仅限变体的目录类型，现已废弃。此目录类型只能与建议一起使用。对于仅变体目录，ingestionProductType 在导入期间会设置为 variant。系统会根据为每个款式/规格指定的主要商品 ID 推断每个款式/规格的主要商品 ID。
最低一级商品
如果您确定目录应同时具有原版和变体（即 SKU 群组和 SKU），但您现在只有 SKU，则需要为 SKU 群组创建原版。这些原初被称为“虚拟原初”或“伪原初”。
这些主实例只需包含最少的信息：id、title 和 categories。
如果未指定 type，则商品类型默认为主要类型。如果要导入，则无需指定 name。如需了解详情，请参阅上一部分必需的产品信息。
类型不可变
您不能更改商品的类型，例如，从款式更改为主要或从主要款式更改为款式。
如果确实需要更改产品的类型，请删除产品，然后使用其他类型重新创建产品。您必须先删除关联的款式/规格，然后才能删除主要商品。
目录导入
如果您目前在 Merchant Center 中有目录，我们建议您通过关联 Merchant Center 帐号来导入目录。
如果您的目录不在 Merchant Center 中，但位于 Cloud Storage、BigQuery 或其他一些存储空间中，请执行批量数据导入。
如果您日后计划从 Merchant Center 导入清单数据，请按照 Merchant Center 导入的说明检查您的数据，以确保您对清单做出正确的选择。这一点非常重要，因为更改现有清单的配置需要删除目录并重新上传（请参阅更改产品级配置）。
如需详细了解如何上传目录，请参阅导入目录信息。
商品目录
商品目录包括：
价格（包括当前价格和原价）
库存状况，例如“有货”“缺货”“缺货待补”和“预订”
可售数量
履单信息，例如门店自提、店内取货和次日送达
商品目录分为两个级别：商品级和本地商品目录。
商品级商品目录
对于仅在线销售商品的零售商，商品目录在商品级别指定。您需要为目录中的每个商品设置价格、库存状况和其他商品目录数据。
如需详细了解商品级商品目录，包括如何维护商品目录数据，请参阅更新适用于零售业的 Vertex AI Search 的商品目录。
本地商品目录
拥有实体店和网店的零售商需要保留每个商店的商品目录信息。为此，他们使用本地商品目录。
有两个商品字段可用于存储本地商品目录。这两个字段都是包含相关商品目录信息的地理位置（地点 ID）列表：
Product.fulfillmentInfo。每个商店的自提和送货方式
Product.localInventories。每个商店的价格信息、商品属性以及提货和送货方式
您可以使用其中任一字段提供商店级信息，也可以同时使用这两个字段。
如需详细了解本地商品目录，请参阅更新适用于零售业的 Vertex AI Search 的本地商品目录。
目录数据质量指标
Search for Retail 控制台中的数据质量页面会评估是否需要更新目录数据，以提高搜索结果质量并解锁搜索性能层级。
下表介绍了适用于零售业的 Vertex AI Search 帮助您评估商品数据的质量指标。如需详细了解如何在 Search for Retail 控制台中查看数据质量指标和搜索性能层级，请参阅解锁搜索性能层级。
| 目录质量指标 | 质量规则 | Notes |
|---|---|---|
| 存在 URI 且可访问 | 商品具有有效的 Product.uri。URI 必须可访问且与您的网域匹配。 |
Google 搜索会使用通过此 URI 抓取的网页信号来提高搜索质量。 |
| 符合时间一致性 | Product.availableTime 早于当前时间，Product.expireTime 晚于当前时间。 |
只有符合时间一致性的商品可供搜索。 |
| 存在可搜索特性 | 商品至少有一个设置为可搜索的 attribute。 |
标记为可搜索的自定义特性可通过文本查询进行搜索。 |
| 说明存在 | 产品包含非空的 Product.description。 |
全面的说明有助于提高搜索质量。 |
| 标题至少包含两个字词 | Product.title 至少包含两个字词。 |
全面的标题有助于提高搜索质量。 |
| 包含不同的图片 | variant 商品至少有一个 Product.image。如果您的所有商品均处于 primary 级别，则您可以忽略此指标。 |
该指标仅供参考，不会影响搜索质量。 |
| 包含不同的价格信息 | variant 商品设置了 Product.priceInfo。如果您的所有商品均处于 primary 级别，则您可以忽略此指标。 |
该指标仅供参考，不会影响搜索质量。 |
适用于零售业的 Vertex AI Search 的产品架构
从 BigQuery 导入清单时，请使用下面的适用于零售业的 Vertex AI Search 产品架构创建具有正确格式的 BigQuery 表，并使用您的清单数据加载该表。然后，导入目录。