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