About serving configs

This page describes serving configs. A serving config is a serving entity that associates a model or a set of controls that are used to generate your recommendation or search results.

Relationship with models and controls

When you create a serving config, you select a model (for Recommendations AI) or controls (for Retail Search) to attach. Serving configs are invoked by your site when surfacing recommendations or search results. The Retail API references the serving config's associated model or controls at serving time to determine the recommendations or search results to generate.


A Recommendations AI serving config can have a single model associated with it. However, any model can be associated with multiple serving configurations, enabling you to deploy the same model on different pages via different serving configs.

Serving controls

Retail Search serving configs have a multi-to-multi relationship with serving controls. You can add multiple serving controls to a serving config, and a single serving control can be associated with multiple serving configs.

You can create serving controls and then add or swap them into a live Retail Search serving config.

API resource and permissions

A serving config is passed into the Retail API using the placements resource:

  • Recommendations AI uses the URL projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG_ID:predict.
  • Retail Search uses the URL projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG_ID:search.

The permissions used on these resources are the placements.search and placements.predict permissions.

Support for placements in the Retail API

Serving configurations are available as of Recommendations AI v2 and Retail Search v2alpha, using the Retail API.

The servingConfig resource is available in Retail API versions v2beta and v2alpha. You can use this resource to create, view, edit, and remove serving configurations.

If you have existing placements, or create new placements, the Retail API automatically creates a serving configuration associated with each placement. Creating a serving configuration does not create a corresponding placement.

Deleting a serving configuration deletes its corresponding placement, and deleting a placement deletes its corresponding serving configuration.

Serving configurations allow you to edit diversity and price reranking options and have them take effect in near real-time. With placements, diversity and pricing settings can only be changed from the recommendation model that the placement points to.

Placements are still supported, but using serving configurations instead is recommended.

Recommendations AI options for serving configs

The following options allow you to change the behavior of a Recommendations AI serving config.

These options were previously available when creating models; they are now associated with serving configs instead.

Price reranking

Price reranking causes recommended catalog items with a similar recommendation probability to be ordered by price, with the highest-priced items first. Price reranking is disabled by default.

Enabling price reranking helps balance conversion rates and average order values. Because relevance is also used to order the items returned, enabling price reranking is not the same as sorting by price.

This option can be edited after creating a serving config.


If you want to ensure that results returned from a single prediction request are more diversified rather than looking similar, you can enable diversification. Generally, diversification reduces the likelihood that similar products are shown in a recommendation panel, at the risk of removing some good recommendations. Diversification settings can be edited after creating a serving configuration. It is disabled by default.

Two types of diversification are available: rule-based diversity and data-driven diversity.

Rule-based diversity

Rule-based diversity relies on categories of your product catalog. Use rule-based diversity to recommend products from a variety of categories. Diversification is configured by level, with higher levels of diversification causing fewer items to be displayed per category. This diversification type works best if your catalog provides high-quality product categories.

Diversification level Max items per category
None Unlimited
Low 3
Medium 2
High 1
Auto Depends on catalog

Data-driven diversity

Use data-driven diversity to produce recommendations results that balance relevance and diversity. Data-driven diversity learns from product catalog metadata, such as titles or categories. Instead of relying on the title or category words, data-driven diversity captures semantic similarity to produce better-performing diversification.

Diversification level Max similar items
None Unlimited
Low 3
Medium 2
High 1
Auto Depends on catalog

Category matching

If the serving config includes a Similar Items model for Recommendations AI, you can enable category matching. When category matching is used, the Retail API returns only product results that share at least one category with the context product.

If your categories have deeply nested hierarchies, the Retail API truncates them using heuristics to improve the possibility of a match. For example, if the context product's categories are a > b > c > d > e >f, the Retail API can return results whose categories are a > b > c.

Category matching can be used in combination with other filtering options, such as price, availability, and filter tags. For example, if you use the filter tag fall_Sale and have category match enabled, the Retail API returns results that have both the required tag and a category match.

This option can be edited after creating a serving config. By default, category matching is disabled.

Dynamic faceting

You can turn on dynamic faceting when you create or edit a serving configuration.

When dynamic faceting is enabled for a serving config, Retail Search can automatically use attributes as dynamic facets in search results for this configuration, based on past user behavior such as facet clicks and views. Whether a given attribute can be used as a facet is by default defined by the product-level attribute configuration in the Retail API. Dynamic faceting settings in the API can be overwritten by site-wide attribute controls in the Google Cloud console. See Managing site-wide controls.

Note that dynamic facets can be created based just on accurate product catalog data. However, for the feature to work optimally for your site, the facet models need to learn from activity on your site. For this, you need to set query, category and filter fields in your search event uploads accurately.

Next steps