搜索自动补全

本页介绍自动补全功能及其使用方法。搜索功能提供自动补全功能，用于强化搜索框的预输入建议。

自动补全功能用于预测用户正在输入的查询的其余部分，从而改善用户搜索体验并加快结账前的购物流程。它还可以通过提供格式良好的查询来提高搜索响应质量，从而创造更高的收入。

概览

当最终用户在您的网站上开始输入搜索字词时，搜索功能可以提供该用户可能需要的建议列表。例如，当用户输入 sh 时，可能会建议输入 shoes 和 shirts。

数据源

您可以选择以下任一数据源来预测建议：

您上传的 BigQuery 数据集。
使用机器学习根据用户事件和其他元数据生成的数据集。

已上传的数据集

您作为数据集上传的 BigQuery 建议表，用于建议查询。如需了解如何上传数据集，请参阅导入自动补全数据。

自动学习数据集

搜索功能根据用户搜索事件生成的机器学习支持的建议数据集。

如需启用自动学习，请执行以下操作：

Cloud 控制台

转到“控件”页面
前往自动补全控件 标签页。
点击修改设置 。
开启自动学习 。
点击保存设置 。

自动学习可能需要 1-2 天才能更新。

cURL

curl -X PATCH -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  "https://retail.googleapis.com/v2beta/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionConfig?update_mask.paths=auto_learning"  --data "{auto_learning: true}"

自动学习数据集的前提条件

自动学习功能会根据搜索类型用户事件 (eventType = "search") 生成建议。生成过程会使用过去 180 天的用户事件。它需要导入的用户事件具有良好的质量和数量。

自动学习功能会过滤掉罕见的建议，因此，如果搜索类型用户事件数量过少（少于 20,000 个），则可能会过滤掉许多建议候选。在这种情况下，您可能需要先使用更频繁的搜索查询测试自动补全功能。

自动学习数据集发布时间表

自动学习数据集每天生成，然后推送到索引编制和发布。整个周期大约需要两天。

自动学习功能

搜索功能仅对自动学习数据集应用机器学习技术来清理和格式化查询和建议数据。

功能	说明	示例
移除无结果搜索	移除搜索结果为零的查询。	对于杂货零售商，“Gucci 手提包”的搜索结果为 0，因此系统会将其移除。
更正拼写错误	更正拼写错误的字词。在匹配之前，还会清理实时输入查询。	“Milc”→“Milk ”
添加许可名单查询	您明确允许的查询会被添加。	查看“更多信息”部分
移除屏蔽名单查询	您明确屏蔽的查询会被移除。	查看“更多信息”部分
移除不安全的字词	使用 Google 安全搜索。移除不当的查询。	色情、露骨、粗俗或暴力内容
移除非常罕见的字词	AI 系统会根据查询统计信息调整截止值。如果字词异常罕见，则会被移除。	“74x39x9 英寸双层双人充气床垫，配有 120V 手持泵。”
术语去重	基于 AI 驱动的语义理解对于近乎相同的字词，任一字词都可匹配，但系统只会建议更热门的字词。	“女鞋”“womens shoes”和“womans shoes”会被去重，因此系统只会建议其中一个。

获取补全建议

使用 completeQuery API 提取建议。

示例：

cURL

curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog:completeQuery?query=sho&dataset=user-data&deviceType=DESKTOP&maxSuggestions=5"

对建议结果实现过滤

使用 cloud-retail 数据集时，AI Commerce Search 可以返回匹配的属性（例如热门品牌和类别）以及标准文本建议。您可以使用这些 attributeResults 来丰富自动补全界面，并允许用户选择预过滤的搜索路径。

例如，如果用户输入“sho”，您可以显示查询建议“shoe”，以及分类过滤建议（例如“in Nike”或“in Women's Shoes”）。

包含可过滤属性的自动补全响应示例

{
  "completionResults": [
    {
      "suggestion": "shoe",
      "attributes": {}
    }
  ],
  "attributeResults": {
    "brands": {
      "suggestions": ["Nike", "Adidas"]
    },
    "categories": {
      "suggestions": ["Shoes", "Women's Shoes"]
    }
  }
}

当用户选择其中一个包含属性的建议（例如“shoe in Nike”）时，您的应用必须同时捕获查询（“shoe”）和属性（“Nike”），以便在后续对核心 Search API 的调用中将其用作过滤条件。

（可选）过滤建议本身：如果您需要完全过滤或屏蔽特定短语，使其不显示在自动补全建议结果中，可以导入 denylist 数据集。这样，您就可以应用 EXACT_MATCH 或 CONTAINS 运算符，以阻止向用户建议不需要的短语。

自动补全选项和控件

本部分介绍了自动补全功能可用的选项和控件。请参阅下表中的概览和更多详细信息。

控制	详细信息	位置
拒绝名单	手动从建议数据中移除查询。	API 请求：CompletionData:import。如需了解详情，请参阅导入自动补全数据。
许可名单	手动将查询添加到建议数据中。	API 请求：CompletionData:import（另请参阅导入自动补全数据）
触发自动补全的最小长度	控制触发自动补全之前的字符数。	Google Cloud 控制台 > 控件
匹配顺序	匹配顺序决定了用户查询和建议的匹配方式。	Google Cloud 控制台 > 控件
建议数量	这是自动补全功能将返回的建议数量。	Google Cloud 控制台 > 控件或 API 请求：completeQuery.maxSuggestions
设备类型	指定设备类型后，系统会根据给定设备类型的热门程度生成建议。如果不指定此项，系统会根据所有设备类型的综合热门程度返回建议。	API 请求：completeQuery.deviceType
建议数据源	如果您同时拥有自动生成的数据源和上传的数据源，则可以在查询时选择要使用的数据源。	API 请求：completeQuery.dataset
语言	您可以指定建议所用的语言。	API 请求：completeQuery.languageCodes[]

许可名单（请勿移除列表）

搜索功能会对自动补全建议数据进行后处理，例如拼写更正。您可以创建搜索功能在后处理时跳过的术语许可名单。

列入许可名单的术语绝不会从建议中过滤掉。许可名单同时适用于上传的数据集和自动学习数据集。

示例：有一些有意拼错的品牌名称，例如“froot loops”而不是“fruit”或“foot”。请参阅导入补全数据中的详细上传说明。

对于数据导入，您可以使用 Google Cloud 控制台 > 控件 > 自动补全控件 > 请勿移除列表 ，也可以在 API 中使用 CompletionData:import。

更改大约会在 2 天内生效。

拒绝名单

拒绝名单仅适用于自动学习数据集。拒绝名单不适用于上传的数据集。

拒绝名单中的术语绝不会出现在建议中。

如需导入拒绝名单，您可以使用 Google Cloud 控制台 > 控件 > 自动补全控件 > 拒绝名单 ，也可以使用 API CompletionData:import。如需详细了解如何导入拒绝名单，请参阅导入补全数据。

更改大约会在 2 天内生效。

触发的最小长度

您可以设置必须至少输入多少字符，自动补全的查询才会返回结果。您可以在Google Cloud 控制台 > 控件 > 自动补全控件 > 触发的最小长度 中找到此设置。

更改会立即生效。

匹配顺序

此设置决定了如何将建议与用户输入术语进行匹配。

如果设置为建议以术语开头，自动补全功能会将用户输入术语作为建议的确切前缀进行匹配。例如，用户输入“sh”与建议“shoes”和“shirts”匹配，但不与建议“red shoes”匹配。

如果设置为建议可以从术语中的任何位置开始，自动补全功能会将用户输入术语标记为字词，并将其与建议中的字词进行匹配，而无论字词顺序如何。例如，用户输入术语“red sh”与建议“shirts red”“red shoes”和“kid red shoes”匹配。但是，输入术语“hoes”与这些建议不匹配，因为建议中的任何字词都不是以“hoes”开头。

您可以在Google Cloud 控制台 > 控件 > 自动补全控件 > 匹配顺序 中找到此设置。

更改会立即生效。

建议数量

这是自动补全查询将返回的建议数量，不得超过 20。您可以在 Google Cloud 控制台 > 控件 > 自动补全控件 > 建议数量 中找到此设置，也可以在 completeQuery 中进行设置。

更改会立即生效。

设备类型

搜索自动补全功能支持不同的设备类型，例如 mobile 和 desktop。您可以根据设备类型上传或获取不同的建议。如果未在 completeQuery中指定deviceType，则建议将适用于所有设备类型。

对于基于搜索用户事件的自动学习数据集，请在 user_agent in UserEvent.user_info 中设置以支持不同的设备类型。请参阅 Wiki 中的用户代理。

高级功能

本部分介绍了搜索功能提供的高级自动补全功能。例如，您可以将查询自动补全建议与其他建议（例如品牌和类别）结合使用。

这些高级功能仅适用于自动学习数据集。

建议 FeatureSet

我们为每个查询建议术语提供了一个额外的 FeatureSet，以便客户在其网站上显示高级功能。

FeatureSet 在响应中显示为键值对映射。 AI Commerce Search 会在 completeQuery.completionResults.attributes API 响应中返回与每个查询建议相关的最多五个热门类别和品牌。FeatureSet 建议不必与最终用户输入的查询字符串匹配。

您可以使用响应中的 FeatureSet 来丰富搜索建议。例如：

汇总并创建热门品牌 和热门类别 部分，这些部分会显示在搜索建议列表下方。
在搜索建议术语旁边显示最热门的品牌或类别。

对目录进行更改（例如更改产品的类别）后，您需要等待 2 周到 30 天，FeatureSet 建议才会反映商品清单的更改。之所以需要等待这么长时间，是因为自动学习功能会根据过去 30 天的搜索事件数据进行训练。

属性建议

搜索功能会提供与用户输入字符串匹配的属性建议。支持的属性建议类型包括品牌和类别。

属性建议与建议 FeatureSet 不同。属性建议是建议的产品属性（例如品牌和类别）列表，类似于查询建议是建议的查询列表。属性建议可以独立于查询建议使用。建议 FeatureSet 是查询建议的元数据，因此依赖于查询建议。

如需启用属性建议，请将 enableAttributeSuggestions 设置为 true，以修补 completionConfig。

cURL

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
"https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionConfig?updateMask=enable_attribute_suggestions" \
-d '{ "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/completionConfig", "enableAttributeSuggestions": "true" }'

属性建议可用于自动补全最终用户正在输入的品牌或类别，这些品牌或类别会显示在搜索建议列表下方的单独部分中。结果会在 completeQuery 响应的 attributeResults 字段中返回，如以下使用 brands 和 categories 键的示例所示：

cURL

{
"completionResults": [
{
  "suggestion": "shoe",
  "attributes": {}
}
],
"attributionToken": "example_attribution_token",
"attributeResults": {
"brands": {
  "suggestions": [
    "Nike",
    "Adidas"
  ]
},
"categories": {
  "suggestions": [
    "Shoes",
    "Men's Shoes"
  ]
}
}
}

包含产品数量的建议构面

启用包含产品数量的建议构面功能后，返回的 completeQuery.completionResults 会像往常一样提供自动补全建议列表，但还会提供每个建议的产品数量，包括总数量和按构面（例如 color, category）划分的产品数量。

例如，如果搜索查询是“shoe”，则返回的自动补全建议可能是：

womens shoes
mens shoes

此外，如果感兴趣的构面键是 color，则每个自动补全建议还会返回产品数量和按颜色划分的产品数量：

womens shoes (32)
- black (10)
- taupe (16)
- white (10)
mens shoes (43)
- black (10)
- brown (5)
- green (17)

作为零售商，您无需向购物者展示产品数量，但您可以决定根据产品数量（而不是 completeQuery.completionResults 中返回的顺序）对建议列表进行排序。例如，您可能希望鼓励购物者查看男士绿色鞋子，因此即使绿色鞋子不是最热门的商品，您也希望它们显示在建议框的顶部。

例如：

{
  "completion_results": [{ 
    "suggestion": "womens shoes"
    "facets": [ 
      {
        "key": "color"
        "values": [ 
          {
            "value": "black"
            "count": 10
          }
          {
            "value": "taupe"
            "count": 16
          }
          {
            "value": "white"
            "count": 10
          }
        ]
      }
    ]
    "total_product_count": 32
  },
  (...)
  ],
}

构面数量信息会显示为每个建议的搜索查询的 completeQuery.completionResults.facets 中的 Facets列表。每个构面都有一个 FacetValues列表，其中包含每个构面值的产品数量。每个建议的搜索查询的总产品数量会在 completeQuery.completionResults.totalProductCount中返回。

如需启用并使用包含产品数量的建议构面，请确保在使用 search API 时，在 FacetSpecs 和 search.searchRequest.facetSpecs 中包含构面键，且至少持续七天。指定您希望获取产品数量的 FacetKeys 。仅允许使用 textual_fields 构面。

之所以需要等待这么长时间，是因为构面信息是使用过去一周的搜索记录数据计算得出的。

completeQuery API 返回的建议包含按构面和按建议划分的产品数量。

按实体过滤的建议

借助实体，您可以过滤自动补全搜索建议。实体可以是不同品牌或区域的网站。您希望自动补全功能能够最好地反映购物特定品牌或区域网站的用户的行为。如需详细了解实体，请参阅实体。

请注意，实体过滤仅适用于 completion_results（与 UserEvent 相关）。此过滤条件不适用于 attribute_results（与 Product 相关）。因此，无论 entity 的值如何，attribute_results 都是相同的。

如需在自动补全建议中添加实体，请执行以下操作：

在搜索用户事件 (eventType = "search") 中添加 entity 字段。如需了解相关信息，请参阅 Search 用户事件的完整对象示例。
在 CompleteQuery API 请求中设置 entity 字段，以便仅获取该实体的建议。

用户事件和 API 请求中的实体字符串必须完全匹配。否则，自动补全功能会返回空建议。
确保实体（无论是在搜索用户事件中还是在自动补全请求中）最多包含 256 个字符。如果实体字符串较长，则在处理事件或请求时会被截断为 256 个字符，从而导致不匹配的风险。

通常，需要 30-90 天的用户事件数据，实体功能才能返回最佳自动补全建议。

搜索自动补全 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

概览

数据源

已上传的数据集

自动学习数据集

Cloud 控制台

cURL

自动学习数据集的前提条件

自动学习数据集发布时间表

自动学习功能

获取补全建议

cURL

对建议结果实现过滤

包含可过滤属性的自动补全响应示例

自动补全选项和控件

许可名单（请勿移除列表）

拒绝名单

触发的最小长度

匹配顺序

建议数量

设备类型

高级功能

建议 FeatureSet

属性建议

cURL

cURL

包含产品数量的建议构面

按实体过滤的建议

搜索自动补全