提升和掩埋媒体推荐

本页介绍了如何使用提升服务控件（也称为控件）更改模型返回的媒体推荐的排名位置。

提升控制变量会在模型返回建议后更改建议的顺序。您可以将过滤表达式应用于结果，以确定要提升或掩埋哪些推荐内容，然后应用介于 -1 和 +1 之间的提升值。增强值为 +1 时，建议获得的增强效果最大，会显示在返回的建议顶部。值为 -1 会将建议埋藏在返回的建议列表的底部。

加推是一种投放时控制。首先，推荐模型会返回一个推荐列表。使用服务配置后，系统会将提升控制应用于该列表，以调整推荐内容的排名。提升控制功能不会添加或删除建议，但会控制向用户显示建议的顺序。

“提升”建议与过滤建议

提升是柔性过滤条件。而过滤建议中介绍的建议常规过滤条件是硬过滤条件。

如果您对建议应用硬过滤条件，则永远不会看到被过滤掉的文档。不过，使用软过滤条件时，您不会从推荐列表中移除文档。相反，过滤条件用于确定返回的推荐列表中的哪些文档应排在前面或后面。

避免推荐模型过载

应用提升或埋没过滤条件时，建议使用接近于零的小值。接近 +1 或 -1 的值可能会使推荐模型不堪重负，导致模型应用的推荐排名无法反映在用户看到的推荐顺序中。

例如，如果您将动画电影的权重设为 +1，用户只会看到推荐列表顶部的动画电影；这样一来，模型高度推荐的非动画电影就会被推到列表底部，用户可能看不到。

降级与隐藏

降级和埋藏都会将移动建议移至返回的建议列表中的较低位置，否则它们会显示在较高位置。

不过，降级是根据内容的年龄或用户是否已观看过部分内容来决定的。如需详细了解降位，请参阅将媒体推荐降位。

隐藏适用于通过过滤条件识别的内容。过滤条件可以是架构中标记为可过滤的任何数据字段。如需了解有关推荐过滤条件的一般信息（包括如何将字段标记为可过滤），请参阅过滤推荐。

提升控制和投放配置简介

每个加推投放控制变量都由一个过滤条件和一个加推值组成。例如，一个提升控制变量将标题中包含“圣诞节”的电影的提升值设为 0.1，另一个提升控制变量将恐怖电影的提升值设为 -0.2。

创建一项或多项加权控制后，您需要将这些控制附加到投放配置。创建任何 Vertex AI Search 应用时，系统还会自动创建默认的提供配置。在提供服务时，系统会引用投放配置来确定应用生成的结果。除了提升控件之外，投放配置还可以包含其他类型的控件，例如 diversify 和 demote 控件。

您可以在调用 recommend 方法时应用投放配置。然后，投放配置中的所有控制变量都会应用于方法调用返回的建议。

此外，您的应用可以关联多个投放配置。这样一来，您就可以在不同情况下应用不同的控件集。例如，如果推荐请求来自儿童账号，则提高适合儿童的电影类别的权重，并降低不适合的电影的权重。 同样，如果请求来自标记为成人的账号，则提升成人喜爱的影视内容或类别的排名。或者，您也可以选择针对不同的地理位置采用不同的投放配置，并根据区域热门程度来提升内容。如需详细了解媒体投放配置，请参阅创建和管理媒体投放配置。

提升值是累加的

如果您已将多个投放控制变量附加到投放配置，则提升和隐藏效果会叠加。

例如，如果您将动画儿童电影的加权系数设为 0.3，将动画冒险电影的加权系数设为 0.4，那么被归类为儿童动画冒险电影的电影的加权系数为 0.7。

同样，如果一部恐怖片在同一投放配置中被一个控制组提升了 0.2，又被另一个控制组埋没了 -0.3，那么最终结果是这部电影被埋没了 -0.1。

提升的加成总和可以超过 +1。例如，如果控制变量将动画儿童电影的提升幅度设为 0.6，将动画冒险电影的提升幅度设为 0.5，那么儿童动画冒险电影的提升幅度将为 +1.1。

过滤条件示例

以下是一些媒体推荐过滤条件示例。

基于常见键属性的过滤条件

有关常见键字符串属性（category、image_name、image_uri、language、title 和 uri）的过滤条件示例。

• 儿童动画：
  "filter": "categories: ANY(\"animation\") AND categories: ANY(\"children\")"

• 令人害怕的媒体内容：
  "filter": "categories: ANY(\"horror\", \"thriller\", \"crime\")

• 标题为“圣诞节”的媒体：
  "filter": "title: ANY(\"Christmas\")"

• images 数组中第一个元素的 name 为“beach ball”的媒体：
  "filter": "images[0].name: ANY(\"beach ball\")"

按媒体键属性过滤

媒体密钥属性的过滤条件示例。媒体键属性以 media_ 开头，在过滤条件语法中，字段名称以 media_key_properties. 开头。如需查看媒体键属性的列表，请参阅 Google 预定义架构与自定义架构。

• 类型为 audio 的媒体：
  "filter": "media_key_properties.media_type: ANY(\"audio\")"

• hash_tags 数组包含字符串 #winter 的媒体：
  "filter": "media_key_properties.hash_tags: ANY(\"#winter\")"

• hash_tags 数组的第一个元素为字符串 #winter 的媒体：
  "filter": "media_key_properties.hash_tags[0]: ANY(\"#winter\")"

自定义字段

自定义字段过滤器的示例。对于自定义属性，请在字段名称前添加 attributes.。

• 您的架构中有一个自定义字符串字段 festival，用于表示电影的首映电影节。如需仅过滤在戛纳电影节首映的电影，请执行以下操作：
  "filter": "attributes.festival: ANY(\"Cannes\")

• 您有一个自定义布尔值字段 audio_desc，当媒体包含面向视障观众的音频描述时，该字段为 true。如需过滤出带有音频描述的媒体，请执行以下操作：
  "filter": "attributes.audio_desc: ANY(true)"

可过滤字段的限制

以下限制适用于提升投放控件：

• 只有字符串类型和布尔值类型的属性字段可用于提升的过滤表达式。

• 您无法对嵌套超过一级的字段进行过滤。例如，您可以按 persons.name 进行过滤，但无法按字段 persons.name.stage（即使存在此类字段）进行过滤。

• 过滤条件必须完全匹配。这意味着，在示例中，名为“Christmas Story”或“CHRISTMAS”的电影不会获得加推。

准备工作

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

• 可选：如果您不想使用默认的投放配置，请按照创建投放配置中的步骤 1-5 和 7 创建新的投放配置。如果您的应用已投入生产，Google 建议您先创建一个单独的投放配置来测试加推控制，然后再将这些控制应用于生产投放配置。

• 确保您要在提升控制中使用的任何字段在架构中标记为可过滤。如需了解详情，请参阅配置字段设置。另请参阅过滤条件限制。

提升或掩埋建议

此过程介绍了如何创建提升控制变量并将这些控制变量附加到投放配置。

将控制变量附加到服务配置后，您可以在调用 servingConfigs.recommend 方法时指定服务配置，系统将使用提升控制变量来影响返回的推荐的顺序。

更新了强化控制

此过程介绍了如何更新现有提升控制设置，以更改提升值或过滤条件。

测试提升控制功能后，您可能会发现自己希望增强或减弱提升效果。或者，您可能需要更改过滤字符串。

更新加权值或过滤条件时，您需要调用 engines.controls.patch 方法。

patch 方法会将 boost 和 filter 的值替换为您提供的新值。此过程展示了如何分别修改 boost 值（第 3 步）和 filter 值（第 4 步）。不过，如果您想同时修改这两个值，可以在单个 curl 命令中完成。

删除加推控制

此过程介绍了如何删除提升控制变量。 如果您未使用提升控制，最佳做法是将其删除，以免达到或超过允许的控制数量配额。

删除提升控制时，您需要调用 engines.controls.delete 方法。

无法删除附加到投放配置的提升控件。如果您尝试删除提升控制，系统会显示一条错误消息，其中包含服务配置的名称。然后，您需要删除该投放配置，或从该投放配置中分离该控件。

更新投放配置以移除提升控制变量

在删除加推控制之前，您必须先将其与所有投放控制分离。为此，请修补投放控件以移除提升控件的 ID。

如需从投放配置中分离加权控制，请按以下步骤操作：

1. 通过发出 engines.servingConfigs.get 请求并查看响应中的 boostControlIds 字段，了解哪些加推控件附加到了投放配置。

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID"
   

   替换以下内容：

   • PROJECT_ID：您的 Google Cloud 项目的 ID。

   • APP_ID：Vertex AI Search 应用的 ID。

   • CONFIG_ID：您想详细了解的投放配置的 ID。

   命令和结果示例

   curl -X GET \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: my-project-123" \
   "https://discoveryengine.googleapis.com/v1beta/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id"
   

   {
     "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id",
     "displayName": "jane-day-test-serving-config-for-boost-bury",
     "solutionType": "SOLUTION_TYPE_RECOMMENDATION",
     "modelId": "my-app",
     "diversityLevel": "no-diversity",
     "diversityType": "RULE_BASED_DIVERSITY",
     "mediaConfig": {},
     "createTime": "2024-11-22T23:54:45.613178Z",
     "updateTime": "2024-11-26T20:28:11.967439Z",
     "boostControlIds": [
       "boost-kids",
       "bury-horror"
     ]
   }
   

   此命令会列出投放配置 my_app-1234567_id 的相关信息，特别是显示该投放配置附加了两个加权控制变量：boost-kids 和 bury-horror。

2. 如需更新投放配置以移除一个提升控制变量，请使用 engines.servingConfigs.patch 方法。

   curl -X PATCH -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://discoveryengine.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/CONFIG_ID?update_mask=boost_control_ids" \
   -d '{
     "boostControlIds": ["CONTROL_ID"]
   }'
   

   替换以下内容：

   • CONFIG_ID：您要将加权控制变量附加到的投放配置的 ID，例如 my_app-1234567_id。请参阅上一步。

   • CONTROL_ID：包含您希望服务配置具有的一个或多个提升控制的 ID。请务必省略要删除的所有加推控制变量。这是一个字符串数组。如果您有多个 ID，请务必使用分隔引号和英文逗号，例如 boost-1", "boost-2。

   命令和结果示例：保留一个控件

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: my-project-123" \
   "https://discoveryengine.googleapis.com/v1beta/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id?update_mask=boost_control_ids" \
   -d '{
     "boostControlIds": ["bury-horror"]
   }'
   

   {
     "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id",
     "displayName": "jane-day-test-serving-config-for-boost-bury",
     "solutionType": "SOLUTION_TYPE_RECOMMENDATION",
     "modelId": "my-app",
     "diversityLevel": "no-diversity",
     "diversityType": "RULE_BASED_DIVERSITY",
     "mediaConfig": {},
     "boostControlIds": [
       "bury-horror"
     ]
   }
   

   此命令会保留附加到投放配置的 bury-horror 提升控制变量，并移除 boost-kids 控制变量。假设 boost-kids 未附加到任何其他服务配置，现在可以将其删除。请参阅删除提升控制变量。

   示例命令和结果：移除所有控件

   curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: my-project-123" \
   "https://discoveryengine.googleapis.com/v1beta/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id?update_mask=boost_control_ids" \
   -d '{
   "boostControlIds": []
   }'
   

   {
   "name": "projects/123456/locations/global/collections/default_collection/engines/my-app/servingConfigs/my_app-1234567_id",
   "displayName": "jane-day-test-serving-config-for-boost-bury",
   "solutionType": "SOLUTION_TYPE_RECOMMENDATION",
   "modelId": "my-app",
   "diversityLevel": "no-diversity",
   "diversityType": "RULE_BASED_DIVERSITY",
   "mediaConfig": {}
   }
   

   此命令会从服务配置中移除所有加推控制变量， my_app-1234567_id