本页面提供了创建目录信息和填充目录数据的最佳做法。
概览
目录是一系列产品对象的集合。
导入到 Vertex AI Search for commerce 的目录数据会直接影响生成的模型的质量，进而影响搜索和推荐结果的质量。通常，您提供的目录信息越准确、具体，您的模型质量就越高。
您的目录应保持最新。您可以根据需要随时上传目录更改；理想情况下，对于变化率较高的目录，每天都应该如此。您可以上传（修补）现有商品项；系统只会更新更改后的字段。上传目录信息不收取任何费用。如需了解详情，请参阅使目录保持最新状态。
目录分支
可搜索的目录分支
如果您使用搜索，可以使用目录分支测试您离线上传的新数据，然后在您的网站上发布。
您最多可以使用三个分支，标识为 0、1 和 2。实际网站指向其目录数据的 default_branch。使用 setDefaultBranch 或 Search for commerce 控制台中的“数据”标签页，指定是您实际 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。例如，T 恤最好以分层结构进行整理，作为主要商品及其相应的一组多款式商品。每个变体代表一个单独的 SKU（针对每种尺寸），而每个主商品代表一组 SKU，其中每个 SKU 都是一种总体 T 恤样式的不同尺寸。这种按 SKU 结构的组织方式可让搜索结果和推荐面板显示各种 T 恤款式。这样，买家就可以深入了解某个主要款式，选择要购买的变体（尺码）。
- 仅限主商品：根据这些商品指定类型，杂货商品最好归类为主商品，每种主商品都包含一个 SKU 商品，例如
"bananas, fresh"。 - 集合：集合用于将客户可能会购买的相关商品归为一组。为了在重新排名模型中准确表示这些商品，Vertex AI Search for commerce 采用了一种逻辑，可将购买行为归因于这些商品。例如：买家点击床单套装中的商品，然后将该套装中的主要商品添加到购物车或购买该商品。相应购买交易会归因于该集合，并且该模型可以准确反映集合的热门程度和价值。
包含款式的商品
对于有款式/规格的商品，请将其结构化为主要商品-款式/规格，因为这样做有多种优势，包括：
- 搜索页面包含可向最终用户显示的各种结果。否则，如果将款式视为主要商品，搜索结果页将显示相同的商品。
- 这些产品具有更丰富的排名方案，因为如果某个特定变体获得了更多互动，那么包含变体的主商品排名会更高。这有助于重新排名和优化收入。
- 易于维护目录。如果一组商品（仅尺寸不同）的某个属性发生了变化，则可以使用主款式/规格结构来实现，例如在主款式级别更改属性，而不是更改多个主款式。
- 变体的 API 功能和搜索响应字段（包括变体汇总键和可检索字段）仅适用于变体。
- 搜索响应包含主版本的最低详细信息和变体的更多详细信息。因此，您始终需要使用额外详细信息来扩充或丰富搜索响应，如果这些信息标记为可检索，则可由 Vertex AI Search for Commerce 返回。
设置商品清单
规划产品目录时，您需要决定其中包含的商品是仅指定为主项的商品、主项和变体，还是这两种安排的混合。您可以从产品 SKU 结构的角度来考虑。您的商品可以是主商品，也可以是主商品的变体。
根据商品 SKU 的指定方式，考虑设置商品目录的选项：
- 您希望将 SKU 显示为单独的搜索结果或推荐内容：SKU=primary
- 您的 SKU 应属于一组类似的 SKU：SKU=变体，一组 SKU=主项
- 混合使用这两种组合：SKU=主要、SKU=变体、一组 SKU=主要
如果您的商品详情页面显示了选项、尺码或颜色选择器，则这些选项通常会作为款式/规格上传到您的商品目录中。请考虑您是否希望具有不同属性（例如尺寸和颜色）的同类商品以单个搜索结果还是单独的搜索结果的形式显示。例如，对于一本书，您需要决定是希望精装版 SKU 和平装版 SKU 作为单独的搜索结果显示（SKU = 主要），还是作为同一个搜索结果显示（SKU = 多款式，SKU 组 = 主要）。
设置商品目录时，请注意推荐和搜索结果只会返回主项。
最少的主要产品
如果您确定自己的目录应同时包含主项和变体（即 SKU 组和 SKU），但目前只有 SKU，则需要为 SKU 组创建主项。这些主色有时称为虚拟主色或假主色。
这些主色只需要包含最少的信息：id、title 和 categories。
如果未指定 type，则产品类型默认为主要。如果您要导入，则无需指定 name。如需了解详情，请参阅上文中的必需的产品信息部分。
目录导入
如果您的目录位于 Cloud Storage、BigQuery 或其他存储空间中，请执行批量数据导入。
如需详细了解如何上传目录，请参阅导入目录信息。
商品网址的正确性
product.uri 字段是直接链接到商品详情页面的规范网址。它应该是可公开抓取的 URI，并且不应位于任何登录或授权墙后。这是因为后端会抓取 URI 网页并尽可能多地获取信息，这些信息会用于相关性和热度评分。后端还会确定 URI 在网络上的互动情况，包括反向链接。所有商品 URI 的顶级域名都相同。
如果您在多个横幅网站中列出了同一商品，请考虑使用多实体功能。请就此问题与客户支持团队联系。
Vertex AI Search for Commerce 使用商品网址来丰富商品说明。如果您在商品目录中使用的网址与实际网站中的网址不同，请确保这两个网址指向同一商品，并且包含的信息几乎完全相同。
商品网址可通过以下方式增强商品清单：
- 丰富商品数据：Vertex AI Search for Commerce 通过抓取商品 URI（网络上每件商品的确切位置 [网址] 背后唯一的资源标识符）来提取补充信息。此流程有助于从关联的网页中获取更多详细信息和信号。通过 URI 抓取更深入地了解产品，可直接提高目录数据的质量。
- 提高搜索质量和相关性：从抓取的 URI 收集的网络信号用于提高搜索质量。后端会利用抓取的信息（包括 URI 在网络上的互动方式，例如用户点击反向链接的时间），在搜索结果中进行相关性和热门程度评分。
- 为模型训练提供基础：除了商品 ID、标题、类别层次结构和价格之外，网址也被视为用作模型训练输入的主要字段之一。
为最大限度地发挥商品网址的优势，请遵循以下最佳实践：
- 所链接的网页必须可公开访问且能正确加载，而不能位于登录或身份验证墙后。
- 每个 URI 都应是唯一的，并且始终指向相应商品的正确网页。其内容应准确反映目录中的商品信息。在所有商品 URI 中保持相同顶级域名。
商品目录
商品目录包含：
价格，包括当前价格和原价
库存状况，例如有货、缺货、缺货待补和预订
可售数量
履单信息，例如“到店取货”“店内取货”和“次日送达”
商品目录分为两个级别：商品级和本地级。
产品级广告资源
对于仅在线销售的零售商，商品目录是在商品一级指定的。 为目录中的每件商品设置价格、库存状况和其他商品目录数据。
如需详细了解商品级商品目录（包括如何维护商品目录数据），请参阅更新 Vertex AI Search for commerce 的商品目录。
本地商品目录
拥有实体店和网店的零售商需要按实体店来维护库存信息。它们使用本地商品目录来执行此操作。
您可以使用两个商品字段来存储本地商品目录。这两个字段都是包含关联的广告资源信息的营业地点（地点 ID）列表：
Product.fulfillmentInfo. 各实体店的自提和配送方式
Product.localInventories. 每个商店位置的价格信息、商品属性以及自提和配送方式
您可以选择使用这两个字段中的一个或全部，来提供商店级信息。
如需详细了解本地产品目录，请参阅为 Vertex AI Search for Commerce 更新本地商品目录。
主变体商品目录结构
primary-variant-inventory 数据结构由主要商品、款式/规格商品和本地商品目录商品组成：
主要商品：主要商品数据存储时不包含价格。
款式/规格商品（在相应国家/地区具有最低价格）：例如，主要款式/规格（颜色、尺寸）的商品在相应国家/地区应具有最低价格。款式/规格价格数据会汇总到主要商品数据中，而主要价格则用于排名。系统会忽略特定于地理位置的价格。
本地商品目录（区域或实体店特定价格）：在投放时使用本地商品目录中的价格信息重新排名
主商品属性：主商品必须仅包含与其所有关联的款式/规格通用的属性。
商品库存状况的正确性
库存状况字段由库存更新系统在商品库存状态发生变化时设置。跟踪处于 IN_STOCK 和 OUT_OF_STOCK 状态的所有商品。
如果大部分商品的状态为 OUT_OF_STOCK，则搜索响应中会有许多缺货商品，添加过滤条件后，召回率会降低。如果商品已缺货，但目录状态为 IN_STOCK，那么用户会看到该商品有货，但在购买或添加到购物车时可能会遇到问题。这比模型训练对客户体验的影响更大。使用 patchProduct API 或导入具有 readMask 的 API，尽可能使 Product.availability 字段保持最新状态。
商品架构
从 BigQuery 导入目录时，请使用以下 Vertex AI Search for commerce 商品架构创建一个格式正确的 BigQuery 表，并将其与您的目录数据一起加载。然后，导入目录。
使用内置字段，而不是自定义属性
对于不属于商品信息架构的所有其他商品属性，请使用Product.attributes（自定义属性）。
与自定义属性相比，内置商品字段（例如商品名、说明和品牌）对可搜索性和可编入索引性有更大的影响。
换句话说，后端对内置字段的了解程度要高于自定义属性。后端会考虑内置字段信息以优化相关性。因此，请使用内置字段。这意味着，请尽可能将商品信息映射到内置字段，仅在必要时使用客户属性。
例如，在 Product.brands 字段中设置品牌对搜索和回想度的影响要远高于在自定义属性中设置相同的信息。对于像 sleeve length 这样不受原生支持的属性，最好使用自定义属性。
使用品牌字段
商品信息中的“品牌”字段（默认情况下可搜索、可编入索引且可用于过滤）是排名和相关性的重要信号。很大一部分搜索查询采用 brand query 或 query brand 形式，可以说，品牌是最常用的方面之一。
如果商品具有正确的品牌字段，点击和购买转化率会受到很大影响。因此，请务必在“品牌”字段中填写正确的信息，并尽可能不要留空。更糟糕的是，在品牌名称中随意填充 "NA"、"Not available" 或 "Miscellaneous" 等内容。这会将商品与品牌字段中提及的文本紧密关联起来，可能会导致对商品的理解有误，并影响回忆效果。
如果特定商品绝对不与任何品牌相关联，最好将相应字段留空。但请注意，这些品牌为空的商品在商品目录中所占的百分比应较小。
使用受众群体字段
商品信息的受众群体字段中有两个子字段。有 Audience.gender 和 Audience.ageGroup。更有效的做法是使用适当的数据填充这些字段，这有助于模型了解产品的目标受众群体。
启用个性化设置后，此功能会发挥重要作用。使用 gender 和 ageGroup 有助于更好地细分产品，并帮助模型为合适的用户召回合适的产品。
当您有“女士衬衫”或“男士袜子”之类的查询时，Audience 数据也很有用。填充了受众群体信息后，模型对产品的理解程度大大提高，并且在处理与性别相关的查询时，召回率也有所提升。
查找标题重复的商品
Product.title 可能是最重要的字段，因为大多数搜索查询与设置为 Product.title 的内容会有很大程度的重叠。这可能是最终用户在详情页面视图中看到并与之互动的第一条信息，因此最好让 product.title 保持唯一性，并包含与商品最相关的文字信息。
如果两个商品（主商品）的商品名相同，会影响搜索结果的可搜索性和相关性。如果两个主要商品存在显著差异，请保持商品名不同。如果商品相同，但仅在颜色、尺寸、结构等少数方面有所不同，请将商品归类为主要类型和款式类型。
语言设置
Vertex AI Search for commerce 支持多种语言。点击此处了解详情。需要注意的主要事项是，目录和搜索查询必须采用相同的语言。不会对查询或目录信息进行跨语言翻译。例如，如果您的目录是西班牙语，则搜索查询也需要是西班牙语。
因此，请务必在商品信息中相应地标记语言代码，否则系统会默认使用英语 (en-US)。这对于 spellCorrectionSpec 等搜索控件非常重要，如果未设置语言，会导致出现不必要的行为。这对于了解搜索查询意图也至关重要。
价格信息设置
Product.priceInfo 字段需要尽可能准确和完整。此价格信息用于推导与折扣相关的信号，并用于优化收入。对于浏览查询，这一点尤为重要。
对于主款式/规格商品结构，请填充至少一个款式/规格的价格。
对于没有商品级价格且所有价格都在本地商品目录中的商品（这意味着搜索始终与本地商品目录相关联），请在商品级价格信息中填写所有商品目录级价格的中位价格信息。
目录数据质量指标
在“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 级别，则您可以忽略此指标。 |
该指标仅供参考，不会影响搜索质量。 |