Boost and bury media recommendations

This page explains how to change the ranking position of media recommendations returned by the model by using boost/bury serving controls.

A boost/bury control changes the order of the recommendations after those recommendations have been returned by the model. You apply a filter expression to the results to identify which recommendations you want to boost or bury, and then you apply a boost value between -1 and +1. A boost value of +1 gives the biggest boost to a recommendation, placing it at the top of recommendations returned. A value of -1 buries the recommendation towards the bottom of the list of recommendations returned.

Boost/bury is a post-model control. First, the recommendations model returns a list of recommendations. Using a serving config, the boost/bury control is then applied to that list to adjust the ranking of the recommendations. The boost/bury control doesn't add or delete recommendations, but it does control the order in which the recommendations are presented to the user.

Boost/bury versus filtering recommendations

Boost/bury is a soft filter. Whereas, the regular filter for recommendations, described in Filter recommendations is a hard filter.

If you apply a hard filter to recommendations, you'll never see the documents that are filtered out. However, with a soft filter, you don't remove documents from the list of recommendations. Instead, the filter is used to determine which documents should be higher or lower in the list of recommendations returned.

Avoid swamping your recommendations model

When applying a boost or bury filter, small values close to zero are recommended. Values close to +1 or -1 are likely to overwhelm the recommendations model, so that the recommendations ranking applied by the model is not reflected in the order that the user sees the recommendations.

For example, if you boost animated movies with +1, users would only see animated movies at the top of the recommendations list; these would push non-animated movies that were highly recommended by the model to the bottom of the list where the user might not see them.

Demoting versus burying

Demoting and burying both move recommendations to lower positions in the list of returned recommendations that they'd appear otherwise.

However, demotion is based on the age of the content or on whether the user has already watched some of the content. For more information about demotion, see Demote media recommendations.

Burying applies to content identified by a filter. The filter can be any data field marked as filterable in the schema. For general information about recommendation filters including how to mark a field as filterable, see Filter recommendations.

About boost/bury controls and serving configs

Each boost/bury serving control is made up of a filter and a boost value. For example, one boost control boosts movies with Christmas in the title with a value of 0.1 and another buries horror movies with a value of-0.2.

After creating one or more boost/bury controls, you add the controls to a serving config. When any Vertex AI Search app is created, a default serving config is also automatically created. The serving config is referenced at serving time to determine what results the app generates. In addition to boost/bury controls, the serving config can contain other types of controls, such as diversify and demote controls.

The serving config can be applied when you call the recommend method. All the controls in the serving config are then applied to recommendations returned by the method call.

Furthermore, you can have multiple serving configs associated with your app. This lets you apply different sets of controls in different circumstances. For example, if the recommendation request comes from a child's account, boost movies in categories suitable for children and bury unsuitable movies. Similarly, if the request comes from an account marked adult, boost titles or categories popular with adults. Alternatively, you might choose to have different serving configs for different geographic locations and boost/bury content according to what is regionally popular. For more information about serving configs, see Create and manage media serving configs.

Boost values are additive

If you have associated multiple serving controls to a serving config, boosts and buries become additive.

For example, if you boost animated children's movies by 0.3 and animated adventure movies by 0.4, then a movie that is categorized as a children's animated adventure is boosted by 0.7.

Similarly, if a horror movie was boosted by 0.2 by one control and buried by -0.3 by another control in the same serving config, the net result would be to bury the movie by -0.1.

The sum of the boosts can exceed +1. For example, if the controls boosted animated children's movies by 0.6 and animated adventure movies by 0.5, then a children's animated adventure movie would be boosted by +1.1.

Examples of filters

The following are some examples of filters that you could boost or bury media recommendations:

Boost movies with Christmas in the title.

filter: "title: ANY(\"Christmas\")"
Boost animated movies for kids:

filter: "categories: ANY(\"animation\") AND categories: ANY(\"children\")"
Bury scary movies:

filter: "categories: ANY(\"horror\", \"thriller\", \"crime\")

These must be exact matches. For example, a movie with "ChristMAS" in the title wouldn't be boosted.

Limitations on filterable fields

The following limitations apply to boost/bury serving controls:

Only property fields of types string and boolean can be used in filter expressions for boost/bury.
You can't filter on fields nested more than one level. For example, you can filter on persons.name but you couldn't filter on a field persons.name.stage (if such a field existed).

Before you begin

Make sure that you have created a media recommendations app and data store. For more information, see Create a media recommendations app and data store.
Optional: If you don't want to use the default serving config, create a new serving config by following steps 1-5 and 7 in Create a serving config. If your app is in production, Google recommends that you create a separate serving config for testing boost/bury before applying the serving controls to your production serving config.
Make sure that any fields that you want to use in your boost/bury control are marked as Filterable in the schema. For more information, see Configure field settings. See also Filtering limits.

Boost or bury recommendations

This procedure describes how to create boost/bury serving controls and associate the controls with a serving config.

After the controls have been added to the serving config, you can specify the serving config when calling the servingConfigs.recommend method and the boost/bury control will be used to influence the order of the recommendations returned.

REST

To create boost/bury serving controls and add them to a serving config, follow these steps:

Find your app ID. If you already have your app ID, skip to the next step.
1. In the Google Cloud console, go to the Agent Builder page.
  
  Go to Apps
2. On the Apps page, find the name of your app and get the app's ID from the ID column.
Find your data store ID. If you already have your data store ID, skip to the next step.
1. In the Google Cloud console, go to the Agent Builder page and in the navigation menu, click Data Stores.
  
  Go to the Data Stores page
2. Click the name of your data store.
3. On the Data page for your data store, get the data store ID.

Create a boost control:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/controls?controlId=CONTROL_ID" \
-d '{
      "displayName": "CONTROL_DISPLAY_NAME",
          "solutionType": "SOLUTION_TYPE_RECOMMENDATION",
          "boostAction": {
               "dataStore": "projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID",
               "boost" :  BOOST_VALUE,
               "filter": "FILTER"
          }
    }'

PROJECT_ID: the ID of your Google Cloud project.
CONTROL_DISPLAY_NAME: a human-readable name to identify the control. Must be a UTF-8 string with a maximum length of 128 characters.
CONTROL_ID: a unique identifier (within a data store) for the control. The ID can contain lowercase letters, digits, hyphens, and underscores.
APP_ID: the ID of the Vertex AI Search app.
DATA_STORE_ID: the ID of the Vertex AI Search data store.
BOOST_VALUE: a floating point number between -1 and 1. When the value is negative, recommendations are demoted (they appear lower down in the results). When the value is positive, recommendations are promoted (they appear higher up in the results).
FILTER: the filter expression that describes what documents will be boosted or buried. For detailed information about how to formulate the filter expression, see Filter expressions.

Example command

curl -X POST \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 -H "X-Goog-User-Project: my-project-123" \
 "https://discoveryengine.googleapis.com/v1alpha/projects/my-project-123/locations/global/collections/default_collection/engines/my-app/controls?controlId=boost-kids" \
 -d '{
      "displayName": "Boost children's category by 0.6",
      "solutionType": "SOLUTION_TYPE_RECOMMENDATION",
      "boostAction": {
           "dataStore": "projects/123456/locations/global/dataStores/my-data-store",
           "boost" :  0.3,
           "filter": "categories: ANY(\"Children\")"
      }
}'

This command boost documents that are categorized for children.

Repeat step 3 for each boost/bury control that you want to apply to your recommendations. For example, you might want one boost control that boosts movies for children, boost-kids and a second control that buries horror films, bury-horror.
Find the ID of the serving config. If you already have your serving config ID, skip to the next step.
1. In the Google Cloud console, go to the Agent Builder page.
  
  Go to Apps
2. On the Apps page, click the name of your app.
3. Go to the Configurations page and click the Serving tab.
4. Get the serving config ID from the ID column.

Add the new boost serving control to the serving config with an update request:

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/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores/DATA_STORE_ID/servingConfigs/CONFIG_ID?update_mask=boost_control_ids"}}" \
-d '{
  "boostControlIds": ["CONTROL_ID"]
}'

CONFIG_ID: the ID of the serving config that you want to add the boost/bury controls to. See the previous step.

Example command

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/v1alpha/projects/my-project-123/locations/global/collections/default_collection/dataStores/my-data-store/servingConfigs/my_app-1234567_id?update_mask=boost_control_ids" \
-d '{
 "boostControlIds": ["boost-kids", "bury-horror"]
}'

This command adds two boost controls to the default serving config of the my-app app.

Wait 5 minutes for the results to take effect.
Preview the effects of your boost/bury control. See Get media recommendations.