此页面由 Cloud Translation API 翻译。

过滤建议

如果您有使用结构化数据的推荐应用，则可以使用文档字段来过滤推荐结果。本页介绍了如何使用文档字段将推荐范围限定为特定的一组文档。虽然本页中的示例适用于媒体推荐，但此处所示的原则也适用于一般性推荐。如需详细了解请参阅适用于 Vertex AI Search 的媒体。

过滤建议和数据存储区更新

更新任何数据存储区后，您需要等待长达 8 个小时，才能将模型重新训练。这是因为模型需要知道文档元数据，以及哪些字段配置为可过滤。您需要等待文档更改和架构更改传播。对于推荐内容（与搜索不同），过滤操作并非实时进行。

过滤条件和多样化设置（仅限媒体推荐）

除了过滤器之外，应用的多样化设置还会影响返回媒体推荐响应中返回的结果。过滤器和分散投资的效果相结合。多元化是先完成过滤，然后再过滤。

结合了基于规则的高多样性和基于类别的属性过滤通常会导致空输出。这是因为高度多样性会限制应用只能为每个类别返回一个结果。

例如，您想根据《玩具总动员》推荐电影。您可以设置基于规则的多样性级别增至高。由于多样性级别较高，尽管许多电影可能只推荐一部电影（例如《WALL·E》）。当过滤条件是针对儿童则系统仅返回 WALLE 作为推荐。

有关多元化的一般信息，请参阅媒体多元化建议。

准备工作

确保您已创建推荐应用和数据存储区。有关相关信息，请参阅创建媒体应用或创建通用推荐数据存储区。

文件示例

请查看以下媒体文件示例。您可以参阅这些示例这些文档。

{"id":"1","schemaId":"default_schema","structData":{"title":"Toy Story (1995)","categories":["Adventure","Animation","Children","Comedy","Fantasy"],"uri":"http://mytestdomain.movie/content/1","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}
{"id":"88125","schemaId":"default_schema","structData":{"title":"Harry Potter and the Deathly Hallows: Part 2 (2011)","categories":["Action","Adventure","Drama","Fantasy","Mystery","IMAX"],"uri":"http://mytestdomain.movie/content/88125","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}
{"id":"2857","schemaId":"default_schema","structData":{"title":"Yellow Submarine (1968)","categories":["Adventure","Animation","Comedy","Fantasy","Musical"],"uri":"http://mytestdomain.movie/content/2857","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}
{"id":"60069","schemaId":"default_schema","structData":{"title":"WALL·E (2008)","categories":["Adventure","Animation","Children","Romance","Sci-Fi"],"uri":"http://mytestdomain.movie/content/60069","available_time":"2023-01-01T00:00:00Z","media_type":"movie"}}

过滤表达式

使用过滤表达式定义推荐内容过滤条件。

过滤器表达式语法

下面的扩展 Backus–Naur 形式总结了过滤条件表达式语法，用于定义建议过滤条件。

  # 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 }, ")"
    # OR filter by "available"
    available, ":", "true",
  # A literal is any double-quoted string. You must escape backslash (\) and
  # quote (") characters.
  literal = double-quoted string;
  textual_field = see the tables below;

过滤表达式限制

以下限制适用于建议的过滤表达式：

括号中嵌入的 AND 和 OR 运算符的深度有限制。过滤条件中的逻辑表达式必须采用析取范式 (CNF) 的形式。受支持的最复杂的逻辑表达式可以是以 AND 相连且仅包含 OR 的子句列表运算符，例如：(... OR ... OR ...) AND (... OR ...) AND (... OR ...)
可以使用 NOT 关键字或 - 来否定表达式。这仅适用于可与具有单个参数的 ANY() 表达式搭配使用。
available 限制必须位于顶级。它们不能用作是 OR 子句的一部分或否定 (NOT)。您只能使用 available: true。
顶级 AND 子句中的字词数上限为 20。
OR 子句最多可以有 100 个包含在 ANY() 表达式中的参数。如果 OR 子句有多个 ANY() 表达式，则它们的参数均会计入此限制。例如，categories: ANY("drama", "comedy") OR categories: ANY("adventure") 有三个参数。

过滤表达式示例

下表显示了有效和无效过滤条件表达式的示例。它还会说明无效示例无效的原因。

表达式	有效	备注
`language_code: ANY("en", "fr")`	是
`NOT language_code: ANY("en")`	是
`NOT language_code: ANY("en", "fr")`	否	对具有多个参数的 `ANY()` 求否。
`language_code: ANY("en", "fr") OR categories: ANY("drama")`	是
`(language_code: ANY("en") OR language_code: ANY("fr")) AND categories: ANY("drama")`	是
`(language_code: ANY("en") AND language_code: ANY("fr")) OR categories: ANY("drama")`	否	不采用析取范式。
`(language_code: ANY("en")) AND (available: true)`	是
`(language_code: ANY("en")) OR (available: true)`	否	将 `OR` 表达式中的 `available` 与其他条件组合使用。

以下过滤表达式用于过滤剧情片或动作片类别、非英语且可用的文档：

categories: ANY("drama", "action") AND NOT language_code: ANY("en") AND available: true

过滤限制

每个可过滤的文档字段都会在每个模型中占用一些内存。以下限制有助于防止对投放效果产生不利影响：

您最多可以在架构中将 10 个自定义字段设为可过滤。

如果在应用训练期间发现的自定义字段超过 10 个，则只有 10 个。
您的架构。

您可以估算架构中的文档数量乘以数字一系列可过滤字段如果您超过了这些限制，会出现以下情况：
- 您无法将其他字段设为可过滤。
- 应用训练失败。

过滤建议

如需过滤媒体推荐内容，请按以下步骤操作：

查找数据存储区 ID。如果您已有数据存储区 ID，请跳至下一步。
1. 在 Google Cloud 控制台中，前往 Agent Builder 页面，然后在导航菜单中点击数据存储区。
  
  转到“数据存储区”页面
2. 点击您的数据存储区的名称。
3. 在数据存储区的数据页面上，获取数据存储区 ID。
确定要作为过滤条件的文档字段。对于例如，对于准备工作部分中的文档，可以使用categories字段作为过滤条件。
如需使 categories 字段可过滤，请执行以下操作：
1. 在 Google Cloud 控制台中，前往 Agent Builder 页面。
  
  Agent Builder
2. 点击您的推荐应用。
3. 点击架构标签页。此标签页显示的是当前字段设置。
4. 点击修改。
5. 如果尚未选中，请选中可过滤复选框类别行，然后点击保存。
6. 请等待 6 小时，以便架构修改生效。六小时后，您可以继续执行下一步。

如需获取建议并过滤 categories 字段，请运行请在命令行中输入以下代码：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
     "userEvent": {
       "eventType": "EVENT_TYPE",
       "userPseudoId": "USER_PSEUDO_ID",
       "documents": {
         "id": "DOCUMENT_ID"
       }
     },
     "params": {
       "returnDocument": true,
       "attributeFilteringSyntax": true,
       "strictFiltering": true
     },
     "filter": "FILTER"
   }' \
"https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/SERVING_CONFIG_ID:recommend"

PROJECT_ID：您的项目的 ID。
DATA_STORE_ID：数据存储区的 ID。
DOCUMENT_ID：您要预览建议的文件的 ID。使用您在提取数据时为此文档使用的 ID。
EVENT_TYPE：用户事件的类型。如需了解 eventType 值，请参阅 UserEvent。
USER_PSEUDO_ID：用户的假名化标识符。您可以为此字段使用 HTTP Cookie，该 Cookie 可唯一标识单个设备上的访问者。请勿将此字段设置为相同的值标识符。这会合并其事件历史记录并降低模型质量。请勿包含个人身份信息个人身份信息 (PII) 的。
SERVING_CONFIG_ID：服务配置的 ID。您的广告投放配置 ID 与引擎 ID 相同，因此请在此处使用引擎 ID。
FILTER：一个文本字段，可让您使用过滤表达式语法按指定的一组字段进行过滤。默认值为空字符串，这意味着未应用任何过滤条件。

例如，假设您希望针对特定媒体播放用户事件获得建议，并且希望过滤建议结果，使其仅包含满足以下条件的文档：(1) 属于“儿童”类别，并且 (2) 当前可用。为此，您需要在调用中添加以下语句：

"eventType": "media-play"
"filter": "categories: ANY(\"Children\") AND available: true"

如需了解详情，请参阅 recommend 方法。

点击查看示例回复。

如果您发出与上述请求类似的建议请求，则可能会收到类似于以下内容的响应。请注意，响应包含两个文档，其中 categories 值为 Children，availability_start_time 值晚于当前日期。

{
"results": [
  {
    "id":"1",
    "schemaId":"default_schema",
    "structData":{"title":"Toy Story (1995)","categories":["Adventure","Animation","Children","Comedy","Fantasy"],"uri":"http://mytestdomain.movie/content/1",
    "availability_start_time":"2023-01-01T00:00:00Z",
    "media_type":"movie"
    }
  },
  {
    "id":"60069",
    "schemaId":"default_schema",
    "structData":{"title":"WALL·E (2008)","categories":["Adventure","Animation","Children","Romance","Sci-Fi"],"uri":"http://mytestdomain.movie/content/60069",
    "availability_start_time":"2023-01-01T00:00:00Z",
    "media_type":"movie"
    }
  }
],
"attributionToken": "ChMzMDk3NTQ4MzQxOTcxOTE0ODM1GglhZi10ZXN0LTEiDmFmLXRlc3QtMTE0NTE0KAAwBg",
"debugInfo": {
  "fallbackModelInvoked": false
}
}