Note: This feature is a Preview offering, subject to the "Pre-GA Offerings Terms"of theGCP Service Specific Terms.Pre-GA products and features may have limited support, andchanges to pre-GA products and features may not be compatible with other pre-GAversions. For more information, see thelaunch stage descriptions.Further, by using this feature, you agree to theGenerative AI Preview terms and conditions("Preview Terms"). For this feature, you can process personal data as outlined in theCloud Data Processing Addendum,subject to applicable restrictions and obligations in the Agreement (as defined in the Preview Terms).

This page explains how to change the ranking position of media recommendationsreturned by the model by using boost serving controls (also calledcontrols).

A boost control changes the order of the recommendations after thoserecommendations have been returned by the model. You apply a filter expressionto the results to identify which recommendations you want to boost or bury, andthen you apply a boost value between -1 and +1. A boost value of +1 gives thebiggestboost to a recommendation, placing it at the top of recommendationsreturned. A value of -1buries the recommendation towards the bottom of thelist of recommendations returned.

Boost is aserving-time control. First, the recommendations model returns alist of recommendations. Using a serving config, the boost control is thenapplied to that list to adjust the ranking of the recommendations. Theboost control doesn't add or delete recommendations, but it does controlthe order in which the recommendations are presented to the user.

Boost versus filtering recommendations

Boost is asoft filter. Whereas, the regular filter for recommendations,described inFilter recommendations is ahardfilter.

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

Avoid swamping your recommendations model

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

For example, if you boost animated movies with +1, users would only see animatedmovies at the top of the recommendations list; these would push non-animatedmovies that were highly recommended by the modelto 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 ofreturned recommendations that they'd appear otherwise.

However,demotion is based on the age of the content or on whether the userhas already watched some of the content. For more information about demotion,seeDemote media recommendations.

Burying applies to content identified by a filter. The filter can be anydata field marked as filterable in the schema. For general information aboutrecommendation filters including how to mark a field as filterable, seeFilterrecommendations.

About boost controls and serving configs

Each boostserving control is made up of a filter and a boost value. Forexample, one boost control boosts movies with Christmas in the title with avalue of0.1 and another buries horror movies with a value of-0.2.

After creating one or more boost controls, you attach the controls to aserving config. When any Vertex AI Search app is created, a defaultserving config is also automatically created. The serving config is referencedat serving time to determine what results the app generates. In addition toboost controls, the serving config can contain other types of controls,such asdiversify anddemote controls.

The serving config can be applied when you call therecommend method. All the controls in the serving config are then applied torecommendations 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. Forexample, if the recommendation request comes from a child's account, boostmovies in categories suitable for children and bury unsuitable movies.Similarly, if the request comes from an account marked adult, boost titles orcategories popular with adults. Alternatively, you might choose to havedifferent serving configs for different geographic locations and boostcontent according to what is regionally popular. For more information aboutserving configs, seeCreate and manage media serving configs.

Boost values are additive

If you have attached multiple serving controls to a serving config, boosts andburies become additive.

For example, if you boost animated children's movies by 0.3 and animatedadventure movies by 0.4, then a movie that is categorized as a children's animatedadventure 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 tobury the movie by -0.1.

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

Examples of filters

The following are some examples of filters for media recommendations.

Filters on common key properties

Examples of filters on common key string properties (category,image_name,image_uri,language,title, anduri).

• Animations for kids:
  "filter": "categories: ANY(\"animation\") AND categories: ANY(\"children\")"

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

• Media where the title is "Christmas":
  "filter": "title: ANY(\"Christmas\")"

• Media where the first item in theimages array has thename "beachball":
  "filter": "images[0].name: ANY(\"beach ball\")"

Filters on media key properties

Examples of filters on media key properties. Media key properties begin withmedia_, and, in the filter syntax, the field name is prefaced withmedia_key_properties.. For a list of media key properties, seeGooglepredefined schema versus custom schema.

• Media where the type isaudio:
  "filter": "media_key_properties.media_type: ANY(\"audio\")"

• Media where the hash_tags array contains a string#winter:
  "filter": "media_key_properties.hash_tags: ANY(\"#winter\")"

• Media where the first element of the hash_tags array is the string#winter:
  "filter": "media_key_properties.hash_tags[0]: ANY(\"#winter\")"

Custom fields

Examples of filters on custom fields. For custom attributes, preface the fieldname withattributes..

• You have a custom string field,festival, in your schema to represent whatfilm festival a movie premiered at. To filter on only those movies thatpremiered at Cannes:
  "filter": "attributes.festival: ANY(\"Cannes\")

• You have a custom boolean field,audio_desc, that is true when the mediaincludes an audio description for visually impaired viewers.To filter on media with an audio descripton:
  "filter": "attributes.audio_desc: ANY(true)"

Limitations on filterable fields

The following limitations apply to boost serving controls:

• Only property fields of types string and boolean can be used in filterexpressions for boost.

• You can't filter on fields nested more than one level. For example, you canfilter onpersons.name but you couldn't filter on a fieldpersons.name.stage (even if such a field existed).

• Filters must be exact matches. This means that inexamples, amovie called "Christmas Story" or "CHRISTMAS" wouldn't be boosted.

Before you begin

• Make sure that you have created a media recommendations app and data store.For more information, seeCreate a media recommendations app and data store.

• Optional: If you don't want to use the default serving config, create a newserving config by following steps 1-5 and 7 inCreate a servingconfig. If your app is in production, Googlerecommends that you create a separate serving config for testingboost controls before applying the controls to your production servingconfig.

• Make sure that any fields that you want to use in your boost control aremarked asFilterable in the schema. For more information, seeConfigurefield settings. See alsoFilteringlimits.

Boost or bury recommendations

This procedure describes how to create boost controls and attachthe controls to a serving config.

After the controls have been attached to the serving config, you can specify theserving config when calling theservingConfigs.recommend method and the boostcontrol will be used to influence the order of the recommendations returned.

Update the boost control

This procedure describes how to update an existing boost control to change thevalue of the boost or the filter.

After you have tested the boost control, you might discover that you want tomake the boost stronger or weaker. Alternatively, you might want to change thefilter string.

When updating a boost value or filter, you call theengines.controls.patch method.

The patch method replaces the values ofboost andfilter with the new valuesthat you provide. This procedure shows how to edit theboost value (step 3)and thefilter value (step 4) separately. However, you want to edit both, youcan do that in a single curl command.

Delete a boost control

This procedure describes how to delete a boost control.If you're not using a boost control, best practice is to delete it so that youdon't reach or exceed thequota for the number of controls allowed.

When deleting a boost control, you call theengines.controls.delete method.

Boost controls that are attached to a serving config can't be deleted. If youtry to delete a boost control, an error message gives you the name of theserving config. You then need todelete that servingconfig ordetach that control from the serving config.

Update a serving config to remove a boost control

Before you can delete a boost control, you have to detach it from all servingcontrols. Do this by patching the serving controls to remove the ID of the boostcontrol.

To detach boost controls from a serving config, follow these steps:

1. Find out which boost controls are attached to the serving config by making aengines.servingConfigs.get request and lookingat theboostControlIds field in the response.

   curl-XGET\-H"Authorization: Bearer$(gcloudauthprint-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"

   Replace the following:

   • PROJECT_ID: the ID of your Google Cloud project.

   • APP_ID: the ID of the Vertex AI Search app.

   • CONFIG_ID: the ID of the serving configthat you want to know more about.

   Example command and result

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

   This command lists information about the serving configmy_app-1234567_id, in particular, it shows that the serving config has two boost controls attached to it:boost-kids andbury-horror.

2. To update the serving config to remove one boost control,use theengines.servingConfigs.patch method.

   curl-XPATCH-H"Authorization: Bearer$(gcloudauthprint-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"]}'

   Replace the following:

   • CONFIG_ID: the ID of the serving configthat you want to attach the boost controls to—for example,my_app-1234567_id. See the previous step.

   • CONTROL_ID: contains the IDs one or more of theboost control that you want the serving config to have. Make sure toomit any boost controls that you want to delete. This is an array ofstrings. If you have more than one ID, don't forget to use separatingquotes and commas—for example,boost-1","boost-2.

   Example command and result: leaves one control

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

   This command keeps thebury-horror boost control attached to the serving config and removes theboost-kids control. Assuming thatboost-kids isn't attached to any other serving config, it can now be deleted. SeeDelete a boost control.

   Example command and result: removes all controls

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

   This command removes all boost controls from the serving config,my_app-1234567_id