过滤建议

本页面介绍了如何使用商品属性过滤推荐结果。

您可以通过在预测请求中指定过滤表达式来过滤预测结果。过滤条件表达式是针对每个产品进行求值的逻辑表达式。响应中的商品列表已缩小为表达式计算结果为 true 的商品。

注意 ：标记表达式更新最长可能需要 8 小时才能用于 v1 和 v2 中的过滤预测结果，包括用于过滤和产品级元数据更改的属性配置。只有 Availability 字段具有实时更新。

建议过滤有两种版本：

• 建议使用版本 2。
• 版本 1 已被弃用，但可能仍在使用中。

本方法指南中的部分仅适用于过滤版本 2，该版本使用商品属性来过滤推荐。

建议过滤（版本 2）

版本 2 使用产品属性。过滤表达式基于产品属性。这些属性可以是预定义的系统属性（如 categories 和 colors），也可以是您定义的自定义属性（如 attributes.styles）。将商品属性设置为可过滤后，推荐可自动使用这些属性作为推荐过滤的标记，而无需您手动添加过滤标记。

使用属性过滤商品时，预测响应会返回主要商品，此类商品至少包含一种主要商品或款式/规格商品，并且其属性值与过滤条件表达式相匹配。如需详细了解主要商品和多款式商品，请参阅商品级别。

以下过滤条件表达式示例也会过滤设置为“New-Arrival”但未设置为“promotions”的任何红色或蓝色商品：

colors: ANY("red", "blue") AND attributes.status: ANY("New-Arrival") AND NOT attributes.is_promotional: ANY("true")

如需使用建议过滤的版本 2，请按以下流程操作。本页面的后面部分会介绍每个过程。

1. 为模型启用推荐过滤功能，该模型将提供过滤后的建议。
2. 为您计划用作过滤依据的商品属性开启推荐过滤功能。
3. 在预测请求中使用可过滤的商品属性。

建议过滤，版本 1（已弃用）

版本 1 使用手动创建的过滤器标记。过滤表达式基于过滤代码，您必须手动将此类代码添加到目录中要过滤的任何产品。

以下过滤条件表达式示例使用过滤条件标记来指定标记为“红色”或“蓝色”以及标记“New-Arrival”且不标记为“促销”的商品：

tag=("Red" OR "Blue") tag="New-Arrival" tag=(NOT "promotional")

请参阅 Product.tags[] 字段的 API 参考文档。

标记表达式可以包含布尔运算符 OR 或 NOT，并且必须用一个或多个空格将其与标记值分隔开来。标记值也可以在前面加上短划线 (-)，它相当于 NOT 运算符。使用布尔运算符的标记表达式必须用英文括号括起来。

除了标记之外，您还可以按 filterOutOfStockItems 过滤。filterOutOfStockItems 标志会过滤掉 stockState 为 OUT_OF_STOCK 的所有商品。

您可以将代码过滤条件和缺货过滤条件结合使用，以便系统仅返回满足所有指定过滤条件表达式的商品。

以下是一些示例过滤字符串：

"filter": "tag=\"spring-sale\""

"filter": "filterOutOfStockItems"

"filter": "tag=\"spring-sale\" tag=\"exclusive\" filterOutOfStockItems"

以下示例仅返回有 spring-sale 和/或 exclusive 标记且没有 items-to-exclude 标记有货的商品。

"filter": "tag=(\"spring-sale\" OR \"exclusive\") tag=(-\"items-to-exclude\") filterOutOfStockItems"

属性过滤器和标记过滤器兼容性

如果模型同时包含手动创建的代码和可过滤的商品属性，则可以使用任一版本的过滤来处理预测请求。但是，不能在同一个预测请求中同时包含 v1 过滤表达式和 v2 过滤表达式。

建议过滤限制

在每个模型中，每个可过滤属性都会占用一些内存。以下限制有助于防止对投放性能产生不利影响：

• 您可以在目录中将最多 10 个自定义属性设置为可过滤。

• 您的目录中最多可包含 1 亿个可过滤的属性值。

  目录中的属性值的总数可通过将目录中的商品数量乘以可过滤属性的数量来估算。

  例如，如果您的目录包含 1000 个商品，有 3 个属性设为可过滤，则属性值的总数可以估算为 3*1000=3000。

  如果您将版本 1 的建议过滤与版本 2 搭配使用，则过滤标记的数量会计入您的配额。请确保添加到属性值总数中的过滤器标记数量小于 1 亿。

如果超出限制，您将无法将其他属性设置为可过滤。如果您需要超过这些限制，可以申请增加配额。

标签的总数在模型训练期间计算。如果总数超过该限制，模型训练将会失败。如果在模型训练期间发现的可过滤自定义属性超过 10 个，则系统只会使用 10 个。

建议过滤条件表达式语法

搜索和建议的过滤条件表达式语法类似。不过，这些建议存在一些限制。

推荐过滤条件表达式语法可以总结为以下 EBNF：

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };

  # An expression can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
                    # A parenthesized expression
                    | "(", expression, ")"
                    # A simple expression applying to a textual field.
                    # Function "ANY" returns true if the field contains any of the literals.
                    ( textual_field, ":", "ANY", "(", literal, { ",", literal }, ")"

  # A literal is any double-quoted case sensitive string. You must escape backslash (\) and
  # quote (") characters. We do not support textual values containing `/` characters, or partial string matches.

  # The literal must be an exact match for products in the catalog. The Predict
  # API returns empty results when no possible matches exist.

  literal = double-quoted string;

  textual_field = see the tables below;

过滤器语法限制

需要遵循以下限制：

• 括号中嵌入的 AND 和 OR 运算符的深度有限制。过滤器中的逻辑表达式必须采用合取范式 (CNF)。最复杂的受支持逻辑表达式可以是以 AND 连接且仅包含 OR 运算符的子句列表，例如：(... OR ... OR ...) AND (... OR ...) AND (... OR ...)
• 可以使用 NOT 关键字或 - 来否定表达式。这仅适用于具有单个参数且不包含商品目录相关属性的 ANY() 表达式。
• 基于 availability 的限制必须位于顶级。它们不能用作 OR 子句或否定 (NOT) 的一部分。
• 由于标准推荐过滤仅支持文本字段，因此标准推荐过滤不支持小于、大于和范围检查操作。小于和大于运算只能与建议提升/掩埋控制条件一起使用，这些条件支持某些数值字段（请参阅提升/掩埋支持的字段）。
• 顶级 AND 子句中的字词数上限为 20。
• OR 子句最多可以有 100 个包含在 ANY() 表达式中的参数。如果 OR 子句包含多个 ANY() 表达式，则其参数均计入此限制。例如，colors: ANY("red", "green") OR colors: ANY("blue") 有三个参数。

下表显示了有效的过滤条件表达式示例、无效示例及其无效的原因。

表达式	有效	Notes
colors: ANY("red", "green")	是
NOT colors: ANY("red")	是
NOT colors: ANY("red", green")	否	使用多个参数对“ANY()”进行求反。
colors: ANY("red", "green") OR categories: ANY(\"Phone > Android > Pixel\")	是
(colors: ANY("red") OR colors: ANY("green")) AND categories: ANY(\"Phone > Android > Pixel\")	是
(colors: ANY("red") AND colors: ANY("green")) OR categories: ANY(\"Phone > Android > Pixel\")	否	不采用合取范式。
(colors: ANY("red")) AND (availability: ANY("IN_STOCK")	是
(colors: ANY("red")) OR (availability: ANY("IN_STOCK"))	否	将 OR 表达式中的 availability 与其他条件进行组合。

与商品目录相关的属性过滤

对库存相关属性的过滤基于商品的实时状态。对于 availability: ANY("IN_STOCK") 过滤，预测响应会返回主要商品或变体商品匹配值为 IN_STOCK 的主要商品。如需详细了解主要商品和多款式商品，请参阅商品级别。我们不支持 Primary only 或 Variant only 过滤。

IN_STOCK 是建议过滤版本 2 支持的唯一 availability 属性值。

库存相关属性可用在 AND 子句中，但不能用在 OR 子句中。

支持的字段

下表汇总了支持的文本字段。

提升/掩埋推荐功能支持标准推荐过滤不支持的其他字段。如需查看建议以提升/掩埋功能支持的其他字段的列表，请参阅提升/掩埋支持的字段。

字段	说明
"productId"	产品 ID（Product.name 最后一段）。
"brands"	Product.brands。
"categories"	Product.categories。
"genders"	Audience.genders。
"ageGroups"	Audience.age_groups。
"colorFamilies"	ColorInfo.color_families。
"colors"	ColorInfo.colors。
"sizes"	Product.sizes。
"materials"	Product.materials。
"patterns"	Product.patterns。
"conditions"	Product.conditions。
"attributes.key"	Product 对象中的文本自定义属性。如果属性值是文本，则该键可以是 Product.attributes 映射中的任意键。

提升/掩埋支持的字段

提升/掩埋支持标准推荐过滤不支持的一些其他字段，包括数值字段。

除了支持的字段中列出的字段之外，对建议进行提升/掩埋还支持以下字段：

文本字段

字段	说明
“代码”	Product.tags[]。与商品关联的自定义代码。

数字字段

字段	说明
"price"	PriceInfo.price：商品的价格。
"discount"	产品折扣。此字段使用 PriceInfo 中的原始价格和价格字段值计算得出。
"rating"	Product.rating。商品的评分总数。
"ratingCount"	rating.ratingCount。商品的评分总数。

为模型设置推荐过滤

您可以使用 Search for Retail 控制台或 Models API 资源启用针对推荐商品的过滤。

您可以在控制台中创建已启用推荐过滤的新模型。您还可以为现有模型更新此选项。

借助 Models API 资源，您可以创建一个开启了推荐过滤功能的新模型，也可以使用 models.Patch 为现有模型更新此设置。

请注意，如果返回预测结果的服务配置启用了类别匹配，则过滤功能对“类别”属性不起作用，因为响应仅返回与上下文产品共用同一类别的产品结果。

使用控制台为模型设置过滤条件

使用 Search for Retail 控制台，在创建模型期间选择自动生成标记选项，以允许对该模型进行推荐过滤。

请仔细检查与其他设置（例如 diversity-level 和 category-match-level 等）的兼容性，因为所有效果都会合并在一起，最后过滤。

• 例如，将基于规则的 diversity-level 和 category attribute filtering 结合使用经常会导致输出为空。
  • diversity-level=high-diversity 可强制模型限制同一类别字符串的结果数上限。例如，“category1”有 1 条结果，“category2”有 1 条结果，依此类推。
  • 使用类别元数据 (Product.categories = ANY ("category2")) 进行属性过滤会导致模型舍弃不匹配的项。
  • 最终输出的结果少于三个。
• 对于 similar-items 模型，它已包含使用默认 category-match-level = relaxed-category-match 提升类别相关性的额外类别。切换到 category-match-level=no-category-match 可停用该行为并使用自定义过滤规则。

如需了解如何使用控制台创建推荐模型，请参阅创建推荐模型。

您无法在控制台中为现有模型更新此设置。如需为模型更新此设置，请使用 models.Patch API 方法。

使用 API 为模型设置过滤条件

您可以在创建新模型时使用 models.Create 或更新现有模型时使用 models.Patch 为模型启用推荐过滤功能。

如需允许过滤，请为模型设置 filteringOption 字段。此字段允许的值包括：

• RECOMMENDATIONS_FILTERING_DISABLED（默认）：系统会关闭模型的过滤功能。
• RECOMMENDATIONS_FILTERING_ENABLED：主商品已启用过滤功能。

以下 curl 示例创建了一个启用了建议过滤功能的新模型。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'name': 'MODEL_NAME',
       'displayName': 'MODEL_DISPLAY_NAME',
       'type': 'home-page',
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models"

以下 curl 示例更新现有模型的过滤选项设置。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models/MODEL_ID?updateMask=filteringOption"

将属性设置为可过滤

如需过滤推荐的商品，请为将在过滤表达式中使用的商品属性开启过滤功能。您可以使用 Search for Retail 控制台或 Attributes API 资源更新此设置。

请勿设置超出所需数量的属性可过滤。可过滤属性的数量有限制。

使用控制台将属性设置为可过滤

您可以在 Search for Retail 控制台中将属性设置为可过滤的“控件”页面。

1. 前往 Search for Retail 控制台中的控件页面。
   
   转到“控件”页面

2. 转到属性控件标签页。

   此标签页会显示一个表，其中包含您可以为其设置网站级控件的所有产品特性。

3. 点击 修改控件。

4. 将商品属性的可过滤设置为 True。

5. 点击保存控件 (Save Controls)。

下一个模型训练周期完成后，您可以开始使用该属性进行过滤。

使用 API 将属性设置为可过滤

AttributesConfig 表示目录的属性列表。

为 CatalogAttribute 设置 AttributesConfig.filteringOption 字段。此字段允许的值包括：

• RECOMMENDATIONS_FILTERING_DISABLED（默认）：对属性关闭过滤功能。
• RECOMMENDATIONS_FILTERING_ENABLED：已为属性开启过滤功能。

以下 curl 示例查询您现有的商品属性。

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \ "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

以下 curl 示例将商品属性 categories 设置为可过滤。

更新现有属性时，请保留属性的 indexableOption、dynamicFacetableOption 和 searchableOption 的原始值，与上一步中显示的值一致。如果在查看 attributesConfig 时没有显示您选择的属性（如上例所示），请使用默认设置，如以下示例所示。

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'name': 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/attributesConfig',
        'catalogAttributes': {
          'categories': {
            'key': 'categories',
            'indexableOption': 'INDEXABLE_ENABLED',
            'dynamicFacetableOption': 'DYNAMIC_FACETABLE_DISABLED',
            'searchableOption': 'SEARCHABLE_DISABLED',
            'recommendationsFilteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED'
          }
        },
        'attributeConfigLevel': 'CATALOG_LEVEL_ATTRIBUTE_CONFIG'
     }" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

下一个模型训练周期完成后，您可以开始使用该属性进行过滤。通常情况下，这至少需要 8 个小时。

在预测请求中使用可过滤的属性

重新训练模型后，您可以在预测请求中使用可过滤的商品属性。

将请求参数值 filterSyntaxV2 设置为 true，以启用版本 2 建议过滤。如果未设置该参数，则版本 1 过滤仍然有效。如果模型同时包含手动创建的代码和可过滤的商品属性，则可以使用任一版本的过滤来处理预测请求。但是，不能在同一个预测请求中同时包含 v1 过滤表达式和 v2 过滤表达式。

以下部分 curl 示例显示了设置为 true 的 filterSyntaxV2，以及使用商品属性 colors 和 categories 的过滤条件表达式。此示例假定 colors 和 categories 设置为可过滤。

"params": {
  "filterSyntaxV2": true
},
"filter": "(categories: ANY(\"Phone > Android > Pixel\") OR colors: ANY(\"red\", \"green\")) AND (availability: ANY(\"IN_STOCK\"))"

以下 curl 示例展示了一个完整的预测请求。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'userEvent': {
          'eventType': 'detail-page-view',
          'visitorId': 'VISITOR_ID',
          'productDetails': {
            'product': {
              'id': 'PRODUCT_ID'
            }
          }
        },
        'params': {
          'returnProduct': true,
          'filterSyntaxV2': true,
          'strictFiltering': true,
        },
        'filter': 'categories: ANY(\"xyz\")'
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG:predict"

除了过滤条件之外，服务配置的多样化设置也会影响响应返回的结果数。