本页面提供了创建目录信息和填充目录数据的最佳做法。
概览
目录是一系列产品对象的集合。
导入到 Vertex AI Search 商务解决方案的目录数据会直接影响生成的模型的质量，进而影响搜索和推荐结果的质量。通常，您提供的目录信息越准确、具体，您的模型质量就越高。
您的目录应保持最新。您可以根据需要随时上传目录更改；理想情况下，对于变化率较高的目录，每天都应该如此。您可以上传（补丁）现有产品项；系统只会更新更改后的字段。上传目录信息不收取任何费用。如需了解详情，请参阅使目录保持最新状态。
目录分支
可搜索的目录分支
如果您使用搜索，可以使用目录分支测试您离线上传的新数据，然后在您的网站上发布。
您最多可以使用三个分支，标识为 0、1 和 2。实际网站指向其目录数据的 default_branch。使用 setDefaultBranch 或商业控制台中的“数据”标签页，指定哪个分支是您的实际 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"]。
|
目录类别
本部分介绍了目录结构，以及如何指定目录以用于分类和过滤。
目录结构
目录中的 categories 字段应包含每个商品的最精细类别路径。父类别不是必需的，不应包含。
以下是目录结构的示例：
- 正确：
categories: ["Flowers, Cards, Occasion > Seasonal Items > Christmas"] - 不正确：
categories: ["Flowers, Cards, Occasion", "Flowers, Cards, Occasion > Seasonal Items", "Flowers, Cards, Occasion > Seasonal Items > Christmas"]
父级类别
给定商品的父类别不应包含在 categories 字段中。浏览过滤应使用其他自定义属性来处理。
类别命名
应谨慎选择类别名称，以免引入错误的关键字并提升效果。使用更具体、更准确的术语可提高相关性并减少问题。
- 推荐：冷冻食品 > 冷冻水果
- 不推荐：冷冻水果与蔬菜 > 冷冻水果
项目专用的目录级结构
为每种语言创建一个目录。如果您在多个国家/地区开展业务，则可以使用同一目录在不同国家/地区提供搜索结果。
以相同的币种提供价格，这些价格通过本地商品目录确定。如果价格因国家/地区而异，请为每个国家/地区创建本地商品目录。在其中指定价格。
为了优化搜索结果，请将每个国家/地区名称分别作为 SearchRequest.entity 和 UserEvent.entity 提供。仅出于排名目的使用国家/地区实体。
产品层次结构概览
在 Vertex AI Search 商务解决方案中管理商品目录时，了解如何处理主商品和变体商品的属性对于实现有效的搜索和推荐至关重要。商品 SKU 指定项决定了目录层次结构。
产品指定类型
产品指定类型有三种：
主要商品或父商品会在推荐或搜索结果中返回，并充当类似商品的逻辑容器或群组。主项可以是单独的（SKU 级别）商品，也可以是一组类似商品（SKU 群组）。
变体或子项是 SKU 群组主商品的特定版本。例如，如果主商品是 V 领衬衫，变体可能是棕色 V 领衬衫，XL 码和白色 V 领衬衫，S 码。
合集项是主商品或变体商品的套装，例如包含项链、耳环和戒指的珠宝套装。与商品和款式/规格类似的层次结构，合集用于将相关的主商品归为一组。客户无法直接购买，使用范围不广，并且仅在搜索广告中提供。
商品示例
举例来说，根据这些商品指定类型，食品杂货最好归类为主要商品，每种食品杂货都包含一个 SKU 商品，例如"bananas, fresh"。
另一方面，T 恤最好以分层方式进行结构化，作为具有相应变体的主要商品。每个变体代表一个单独的 SKU（针对每种尺寸），而每个主商品代表一组 SKU，其中每个 SKU 都是一种总体 T 恤样式的不同尺寸。这种按 SKU 结构的组织方式可让搜索结果和推荐面板显示各种 T 恤款式。这样，买家就可以深入了解某个主要款式（样式），选择要购买的变体（尺寸）。
合集可将客户可能会购买的相关产品归为一组。为了在重新排名模型中准确表示这些商品，Vertex AI Search for Commerce 采用了一种逻辑，可将购买行为归因于这些商品。例如：买家点击床单套装中的商品，然后将该套装中的主要商品添加到购物车或购买该商品。相应购买交易会归因于该集合，并且该模型可以准确反映集合的热门程度和价值。
此外，还有一种仅包含变体的目录类型，但该类型现已弃用。此目录类型只能与推荐搭配使用。对于仅包含变体的目录，系统会在导入期间将 ingestionProductType 设置为 variant。系统会根据为每个变体指定的主要产品 ID，为每个变体推断出一个主要产品。
设置商品清单
规划产品目录时，您需要决定其中包含的商品是仅指定为主项的商品、主项和变体，还是这两种安排的混合。您可以从产品 SKU 结构的角度来考虑。您的商品可以是主商品，主商品可能包含变体，也可能不包含变体。
根据商品 SKU 的指定方式，考虑设置商品目录的选项：
- 您希望将 SKU 显示为单独的搜索结果或推荐内容：SKU=primary
- 您的 SKU 应属于一组类似的 SKU：SKU=变体，一组 SKU=主 SKU
- 混合使用这两种组合：SKU=主要、SKU=变体、一组 SKU=主要
如果您的商品详情页面显示了选项、尺码或颜色选择器，则这些选项通常会作为款式/规格上传到您的商品目录中。请考虑您是否希望同一商品的不同类型（具有不同的属性，例如尺寸和颜色）显示为单个搜索结果或单独的搜索结果。例如，对于一本书，您需要决定是希望精装版 SKU 和平装版 SKU 作为单独的搜索结果显示（SKU = 主），还是作为同一个搜索结果显示（SKU = 多款式，SKU 组 = 主）。
设置商品目录时，请注意推荐内容和搜索结果只会返回主项。
最少的主要产品
如果您确定自己的目录应同时包含主项和变体（即 SKU 组和 SKU），但目前只有 SKU，则需要为 SKU 组创建主项。这些主色有时称为虚拟主色或假主色。
这些主广告素材只需包含最少的信息：id、title 和 categories。
如果未指定 type，则产品类型默认为主要。如果您要导入，则无需指定 name。如需了解详情，请参阅上文中的必需的产品信息部分。
目录导入
如果您的目录位于 Cloud Storage、BigQuery 或其他存储空间中，请执行批量数据导入。
如需详细了解如何上传目录，请参阅导入目录信息。
商品目录
商品目录包含：
价格，包括当前价格和原价
库存状况，例如有货、缺货、缺货待补和已预订
可售数量
履单信息，例如“到店取货”“店内取货”和“次日送达”
商品目录分为两个级别：商品级和本地级。
产品级广告资源
对于仅在线销售商品的零售商，商品目录是在商品级指定的。 为目录中的每件商品设置价格、库存状况和其他商品目录数据。
如需详细了解商品级商品目录（包括如何维护商品目录数据），请参阅更新 Vertex AI Search 商务解决方案的商品目录。
本地商品目录
拥有实体店和网店的零售商需要按实体店来维护库存信息。它们使用本地商品目录来执行此操作。
您可以使用两个商品字段来存储本地商品目录。这两个字段都是包含关联的广告资源信息的营业地点（地点 ID）列表：
Product.fulfillmentInfo. 各实体店的自提和配送方式
Product.localInventories. 每个实体店位置的价格信息、商品属性以及自提和送货方式
您可以为商店级信息使用这两个字段中的一个或全部。
如需详细了解本地商品目录，请参阅为 Vertex AI Search for Commerce 更新本地商品目录。
主变体商品目录结构
主商品-款式/规格-本地商品目录数据结构由主商品、款式/规格商品和本地商品目录商品组成：
主要商品：主要商品数据存储时不包含价格。
款式/规格商品（在相应国家/地区具有最低价格）：例如，主要款式/规格（颜色、尺寸）的商品在相应国家/地区应具有最低价格。款式/规格价格数据会汇总到主要商品数据中，而主要价格则用于排名。系统会忽略特定于位置的价格。
本地商品目录（区域或实体店特定价格）：在投放时使用本地商品目录中的价格信息重新排名
主要商品属性：主要商品必须仅包含与其所有关联的款式/规格通用的属性。
目录数据质量指标
在“Search for commerce”管理中心内的数据质量页面中，系统会评估您是否需要更新目录数据，以提高搜索结果质量并解锁搜索效果层级。
下表介绍了 Vertex AI Search 商务解决方案用于帮助您评估商品数据的质量指标。如需详细了解如何在“面向商业的搜索”控制台中查看数据质量指标和搜索性能层级，请参阅解锁搜索性能层级。
| 目录质量指标 | 质量规则 | 备注 |
|---|---|---|
| 存在 URI 且可访问 | 商品具有有效的 Product.uri。URI 必须可访问且与您的网域匹配。 |
Google 搜索会使用通过此 URI 抓取的网络信号来提高搜索质量。 |
| 符合时间一致性 | Product.availableTime 早于当前时间，Product.expireTime 晚于当前时间。 |
只有符合时间一致性的商品可供搜索。 |
| 存在可搜索特性 | 商品至少有一个设置为可搜索的 attribute。 |
标记为可搜索的自定义特性可通过文本查询进行搜索。 |
| 说明存在 | 产品包含非空的 Product.description。 |
全面的说明有助于提高搜索质量。 |
| 标题至少包含两个字词 | Product.title 至少包含两个字词。 |
全面的标题有助于提高搜索质量。 |
| 包含不同的图片 | variant 商品至少有一个 Product.image。如果您的所有商品均处于 primary 级别，则您可以忽略此指标。 |
该指标仅供参考，不会影响搜索质量。 |
| 包含不同的价格信息 | variant 商品设置了 Product.priceInfo。如果您的所有商品均处于 primary 级别，则您可以忽略此指标。 |
该指标仅供参考，不会影响搜索质量。 |
商品架构
从 BigQuery 导入目录时，请使用以下 Vertex AI Search for Commerce 商品架构创建一个格式正确的 BigQuery 表，并将其与您的目录数据一起加载。然后，导入目录。