注意：Vertex AI Search 即将更名为 Agent Search。我们正在更新内容，以反映新品牌。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

过滤建议

如果您有推荐应用，可以使用文档字段过滤推荐结果。本页介绍了如何使用文档字段将推荐内容过滤到特定的一组文档。虽然本页中的示例适用于媒体推荐，但此处显示的原则与自定义推荐相同。如需详细了解媒体推荐，请参阅媒体的 Agent Search 简介。

过滤推荐内容和数据存储区更新

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

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

除了过滤条件之外，应用的多样化设置也会影响媒体推荐响应中返回的结果。过滤条件和多样化的效果是结合在一起的。多样化先完成，过滤条件后完成。

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

例如，您想要根据《玩具总动员》推荐电影。您将基于规则的多样性级别设置为“高”。由于多样性级别较高，因此虽然可能会推荐许多电影，但儿童电影类别中只会返回一部电影（例如《机器人总动员》）。然后，当应用儿童电影的过滤条件时，只会返回《机器人总动员》作为推荐内容。

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

准备工作

确保您已创建推荐应用和数据存储区。如需了解更多信息，请参阅创建媒体应用或创建自定义推荐数据存储区。

示例文档

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

{"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。如果您省略此过滤条件，则可能会返回已过期的文档和尚未提供的文档作为推荐内容。

available 字段映射到以下逻辑：

datetime.now >= available_time AND datetime.now <= expire_time

如果未设置 expire_time，则 datetime.now <= expire_time 解析为 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)`	否	将 `available` 与 `OR` 表达式中的其他条件组合。

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

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

过滤限制

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

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

如果在应用训练期间发现 10 个以上的自定义字段，则仅使用 10 个。
您的架构中最多可以有 100,000,000 个可过滤的字段值。

您可以通过将架构中的文档数量乘以可过滤字段的数量来估算架构中可过滤字段值的总数。如果超出这些限制，则会发生以下情况：
- 您无法将其他字段设置为可过滤。
- 应用训练失败。

过滤推荐内容

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

查找您的数据存储区 ID。如果您已有数据存储区 ID，请跳至下一步。
1. 在 Google Cloud 控制台中，前往 AI Applications 页面，然后在导航菜单中点击 数据存储区。
  
  前往“数据存储区”页面
2. 点击您的数据存储区的名称。
3. 在数据存储区的数据页面上，获取数据存储区 ID。
确定要过滤的文档字段。例如，对于准备工作中的文档，您可以使用 categories 字段作为过滤条件。
如需使 categories 字段可过滤，请执行以下操作：
1. 在 Google Cloud 控制台中，前往 AI Applications 页面。
  
  AI Applications
2. 点击您的推荐应用。
3. 点击架构标签页。此标签页显示当前的字段设置。
4. 点击修改。
5. 如果尚未选中，请选中 categories 行中的可过滤 复选框，然后点击保存。
6. 等待 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：一个 UTF-8 编码的字符串，用作跟踪用户的唯一假名化标识符。长度上限为 128 个字符。Google 强烈建议使用此字段，因为它可以提高模型性能和个性化质量。您可以为此字段使用 HTTP Cookie，该 Cookie 可唯一标识单个设备上的访问者。以下是一些重要注意事项：
  - 当访问者登录或退出网站时，此标识符不会发生变化。
  - 不得为多个用户设置相同的标识符。否则，为多个用户使用同一 User-ID 可能会合并不同用户的事件历史记录，从而降低模型质量。
  - 此字段不得包含个人身份信息 (PII)。
  如需了解详情，请参阅 userPseudoId.
- 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"
}
```