过滤建议

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

您可以通过在预测中指定过滤表达式来过滤预测结果 请求。过滤器表达式是一个逻辑表达式，用于计算 。响应中的商品列表已缩小为商品 其中表达式的计算结果为 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 映射中的任意键。

提升/掩埋支持的字段

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

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

文本字段

字段	说明
“代码”	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 的 model.

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"

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