过滤建议

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

您可以在预测请求中指定过滤表达式，以过滤预测结果。过滤条件表达式是一种逻辑表达式，系统会针对每件商品对其进行求值。响应中的商品列表会缩小到表达式计算结果为 true 的商品。

推荐内容过滤功能有两个版本：

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

本操作指南中的部分内容仅适用于过滤条件版本 2，该版本使用商品属性过滤推荐内容。

建议过滤，版本 2

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

当您使用属性过滤商品时，预测响应会返回包含至少一个属性值与过滤表达式匹配的主要商品或款式/规格商品的主要商品。如需详细了解主商品和款式/规格商品，请参阅商品级别。

以下过滤表达式示例还会过滤设为“新品”且未设为促销的任何红色或蓝色商品：

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

如需针对建议使用过滤条件版本 2，请按照以下步骤操作。本页稍后会介绍每种方法。

1. 为模型启用推荐内容过滤，以便提供经过过滤的推荐内容。
2. 为您计划用作过滤条件的商品属性开启推荐过滤。
3. 在预测请求中使用可过滤的商品属性。

推荐过滤条件，版本 1（已废弃）

版本 1 使用手动创建的过滤条件标记。过滤条件表达式基于过滤条件标记，您必须将过滤条件标记手动添加到目录中您计划过滤的所有商品。

以下过滤表达式示例使用过滤标记来指定标记为“红色”或“蓝色”以及标记为“新品”且未标记为“促销”的商品：

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 亿个可过滤的属性值。

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

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

  如果您同时使用版本 1 和版本 2 的建议过滤功能，过滤条件标记的数量会计入配额。请确保添加的过滤条件标记数量加上属性值总数小于 100,000,000。

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

标记总数是在模型训练期间计算的。如果总数超出限制，模型训练将会失败。如果在模型训练期间发现超过 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) 格式。支持的逻辑表达式中最复杂的表达式可以是仅包含 OR 运算符且通过 AND 连接的子句列表，例如：(... 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") 有三个实参。

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

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

按商品目录相关属性过滤时，系统会根据商品的实时状态进行过滤。对于 availability: ANY("IN_STOCK") 过滤，预测响应会返回主商品，其中主商品或变体商品具有匹配的 IN_STOCK 值。如需详细了解主商品和款式/规格商品，请参阅商品级别。我们不支持 Primary only 或 Variant only 过滤。

IN_STOCK 是推荐过滤功能版本 2 支持的唯一 availability 属性值。

与商品目录相关的属性可在 AND 子句中使用，但不能在 OR 子句中使用。

支持的字段

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

推荐内容的提升/隐藏功能支持标准推荐内容过滤功能不支持的其他字段。如需查看推荐功能支持的其他字段列表，请参阅“提升/埋没”支持的字段。

支持提升/掩埋的字段

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

除了支持的字段中列出的字段之外，用于推荐的提升/埋没功能还支持以下字段：

文本字段

数字字段

为模型设置推荐过滤条件

您可以使用 Retail Search 控制台或 Models API 资源为推荐启用过滤功能。

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

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

请注意，如果返回预测结果的广告投放配置启用了类别匹配，则过滤“categories”属性不起作用，因为响应只会返回与情境商品具有相同类别的商品结果。

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

在使用零售搜索控制台创建模型时，选择自动生成代码选项，以允许对该模型进行推荐过滤。

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

• 例如，将基于规则的 diversity-level 和 category attribute filtering 组合使用通常会导致输出为空。
  • diversity-level=high-diversity 会强制模型限制同一类别字符串的结果数量上限。例如，category1 有 1 个结果，category2 有 1 个结果，依此类推。
  • 使用类别元数据 (Product.categories = ANY ("category2")) 进行属性过滤会导致模型舍弃不匹配的项。
  • 最终输出结果少于 3 个。
• 对于 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"

将属性设置为可过滤

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

请勿将可过滤的属性数量超出需要。可过滤的属性数量存在限制。

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

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

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

2. 前往属性控件标签页。

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

3. 点击 edit 修改控件。

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 示例显示了 filterSyntaxV2 已设为 true，以及使用商品属性 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"

除了过滤条件之外，广告投放配置的多样化设置也可能会影响响应返回的结果数量。