Vertex AI Search for Retail 将重命名为 Vertex AI Search for Commerce。我们正在更新内容，以反映新品牌。

此页面由 Cloud Translation API 翻译。

过滤建议

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

您可以在预测请求中指定过滤表达式，以过滤预测结果。过滤表达式是一种针对每件商品进行评估的逻辑表达式。响应中的商品列表会缩减为表达式的计算结果为 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（已弃用）

版本 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 过滤表达式。

建议过滤限制

手动添加过滤条件，以限制向最终用户返回的建议集。您可以使用 Vertex AI Search for Commerce 应用业务规则来精细调整客户看到的推荐，包括按商品库存状况、自定义标签和其他条件进行过滤的选项。

每个可过滤的属性都会消耗每个模型中的一些内存。以下限制有助于防止对投放效果产生不利影响：

您最多可以在目录中将 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)。支持的最复杂的逻辑表达式可以是仅包含 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") 有三个实参。对于 Vertex AI Search for Commerce 应用场景，您可以将实参视为属性值。

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

表达式	有效	备注
`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`。商品的评分总数。

为模型设置推荐过滤条件

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

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

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

请注意，如果返回预测结果的投放配置启用了类别匹配，则过滤“类别”属性将不起作用，因为响应只会返回与上下文商品共享类别的商品结果。

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

使用“面向商业的搜索”控制台，在创建模型期间选择自动生成标记选项，以允许对该模型进行推荐过滤。

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

例如，结合使用基于规则的 diversity-level 和 category attribute filtering 通常会导致输出为空。
- diversity-level=high-diversity 强制模型限制相同类别字符串的最大结果数。即，类别 1 有 1 个结果，类别 2 有 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"

将属性设置为可过滤

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

不要将过多的属性设置为可过滤。可过滤的属性数量存在限制。

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

您可以在商业搜索控制台的“控件”页面中将属性设置为可过滤。

前往 Search for Commerce 控制台中的控件页面。

转到“控件”页面
前往属性控件标签页。

此标签页会显示一个表，其中包含您可以为其设置网站级控件的所有产品特性。
点击 修改控件。
将商品属性的 Filterable 设置为 True。
点击保存控件 (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"

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