过滤建议

本页面介绍了如何根据以下内容过滤推荐结果： 商品属性。

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

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

建议过滤有两种版本：

• 建议使用版本 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 作为过滤依据， 过滤器标记的数量会计入您的配额。请确保输入的 过滤标记的属性值总数小于 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") 有三个实参。

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

表达式	有效	备注
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 映射中的任意键。

支持提升/掩埋的字段

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

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

文本字段

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

数字字段

字段	说明
"price"	PriceInfo.price。商品的价格。
"discount"	产品折扣。此字段是使用原价计算得出的 和价格字段值（来自 PriceInfo）。
"rating"	Product.rating。商品的评分总数。
"ratingCount"	rating.ratingCount。以下各项中的评分总数 产品。

为模型设置推荐过滤条件

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

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

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

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

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

使用 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")) 进行属性过滤会导致模型舍弃不匹配的项。
  • 最终输出结果少于 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 的 模型。

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. 点击 修改控件。

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"

除了过滤器之外，服务配置的 多样化设置也可能会影响 返回的内容。