过滤建议

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

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

更新任何数据存储区后，您最多需要等待 8 小时，以便模型重新训练。这是因为该模型需要了解文档元数据中的当前值，以及哪些字段配置为可过滤。您需要等待文档更改和架构更改传播。对于推荐内容（与搜索不同），过滤操作并非实时进行。

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

除了过滤条件之外，应用的多元化设置也会影响媒体推荐响应中返回的结果。过滤器和分散投资的效果相结合。系统会先进行多样化处理，然后再进行过滤。

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

例如，您想根据《玩具总动员》推荐电影。您将基于规则的多样性级别设为高。由于多样性水平较高，虽然系统可能会推荐很多电影，但在儿童电影类别中，系统只会返回一部电影（例如《机器人瓦力》）。然后，应用儿童电影过滤条件后，系统会仅将《WALL·E》作为推荐内容返回。

如需了解有关多样性的一般信息，请参阅媒体推荐多样化。

准备工作

确保您已创建推荐应用和数据存储区。如需了解详情，请参阅创建媒体应用或创建通用推荐数据存储区。

文件示例

请查看以下媒体文件示例。在阅读本页内容时，您可以随时参考这些示例文档。

{"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"}}

过滤条件表达式

使用过滤条件表达式定义建议过滤条件。

过滤器表达式语法

以下扩展巴科斯范式总结了可用于定义推荐过滤条件的过滤表达式语法。

  # 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) 的形式。支持的逻辑表达式中最复杂的表达式可以是仅包含 OR 运算符且通过 AND 连接的子句列表，例如：(... 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 个。

  • 架构中最多可包含 1 亿个可过滤的字段值。

    您可以通过将架构中的文档数量乘以可过滤字段的数量来估算架构中可过滤字段值的总数。如果您超出这些限制，会出现以下情况：

    • 您无法将其他字段设为可过滤。
    • 应用训练失败。

过滤建议

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

  1. 找到您的数据存储区 ID。如果您已拥有数据存储区 ID，请跳至下一步。

    1. 在 Google Cloud 控制台中，前往 Agent Builder 页面，然后在导航菜单中点击数据存储区。

      前往“数据存储区”页面

    2. 点击您的数据存储区的名称。

    3. 在数据存储区的数据页面上，获取数据存储区 ID。

  2. 确定要按哪个/哪些文档字段进行过滤。例如，对于准备工作中的文档，您可以使用 categories 字段作为过滤条件。

  3. 如需使 categories 字段可过滤，请执行以下操作：

    1. 在 Google Cloud 控制台中，前往 Agent Builder 页面。

      Agent Builder

    2. 点击您的推荐应用。

    3. 点击架构标签页。此标签页会显示当前的字段设置。

    4. 点击修改。

    5. 如果尚未选中，请选中类别行中的可过滤复选框，然后点击保存。

    6. 请等待 6 小时，以便架构修改生效。六小时后，您可以继续执行下一步。

  4. 如需获取建议并按 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"
}