提升和掩埋媒体推荐

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

提升控制功能会在模型返回推荐内容后更改推荐内容的顺序。您可以对结果应用过滤表达式，以确定要提升或掩埋哪些推荐，然后应用介于 -1 到 +1 之间的提升值。增强值为 +1 时，系统会对建议进行最大的增强，将其置于返回的建议顶部。值为 -1 表示将相应建议埋在返回的建议列表底部。

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

提升推荐功能与过滤推荐功能

提升是软过滤器。而过滤推荐中介绍的针对推荐的常规过滤器属于硬性过滤器。

如果您对推荐内容应用了硬性过滤条件，则永远不会看到被过滤掉的文档。不过，使用软过滤条件时，您不会从推荐列表中移除文档。而是用于确定哪些文档应在返回的推荐列表中排名更高或更低。

避免让推荐模型过载

应用提升或埋没过滤条件时，建议使用接近零的小值。接近 +1 或 -1 的值可能会使推荐模型过载，因此模型应用的推荐排名不会反映在用户看到推荐内容的顺序中。

例如，如果您使用“+1”提升动画电影的排名，用户在推荐列表顶部只会看到动画电影；这会将模型高度推荐的非动画电影推到列表底部，用户可能看不到这些电影。

降级与下架

降级和隐藏都会将推荐内容移至返回的推荐列表中的较低位置（否则，它们会显示在较高位置）。

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

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

关于提升效果控制功能和投放配置

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

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

您可以在调用 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\")

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

• images 数组中的第一项具有 name“沙滩球”的媒体：
  "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 方法。

补丁方法会将 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