Associate a Product Recommendation (PR) model with a query pipeline

This is for:

Merchandising Hub Implementer System Administrator Developer
Important

Make sure to select the correct tab to view the content relevant to the context in which you’re associating your Product Recommendation model:

  • To associate the model to power recommendation slots configured through the Coveo Merchandising Hub (CMH), select the Coveo Merchandising Hub tab.

  • To associate the model to power a recommendation interface that isn’t configured through the CMH, select the Generic tab.

When a Coveo Machine Learning (Coveo ML) model has been created, it must be associated with a query pipeline to be effective in a Coveo-powered commerce interface.

Associate a PR model with a pipeline serving Coveo Merchandising Hub recommendation slots

When associating a Product Recommendation model with the query pipeline for recommendations, you must configure an association for each of the Coveo Merchandising Hub (CMH) recommendation strategies you want to use in your storefront. For example, if you use the Most purchased and Viewed together CMH strategies in your storefront, you must configure an association for each of these strategies.

This process involves:

  1. Creating query pipeline conditions to trigger the proper association based on the strategy used in the storefront.

  2. Associating the model with the query pipeline for recommendations.

Step 1: Create the query pipeline conditions:

You must create a query pipeline condition for each of the CMH recommendation strategies you want to use in your storefront.

The following table provides the conditions you must create based on the CMH strategy you want to use in your storefront:

CMH strategy Query pipeline condition

Viewed together

Recommendation is viewed_together

Purchased together

Recommendation is bought_together

Intent-aware

Recommendation is session_recommender_single_seed

Most viewed

Recommendation is popular_viewed

Most purchased

Recommendation is popular_bought

Recently viewed

Recommendation is recently_viewed

Recently purchased

Recommendation is recently_bought

Purchased with recently purchased

Recommendation is bought_with_recently_bought

Buy again

Recommendation is buy_again
Tip

If you have multiple recommendation slots configured with the same CMH strategy but need different underlying pipeline strategies, you must create more specific conditions that target both the CMH strategy and the slot ID.

For example, if you have two Purchased together CMH slots (one for product detail pages and one for cart recommendations), you’ll need conditions that use this format:

  • Recommendation is bought_together and (Context[commerce-slot-id] is <SLOT_ID_1> or Tab is <SLOT_ID_1>)

  • Recommendation is bought_together and (Context[commerce-slot-id] is <SLOT_ID_2> or Tab is <SLOT_ID_2>)

This lets you associate different pipeline strategies (such as Purchased together, same category vs. Purchased together - Cart) while making sure the correct underlying pipeline strategy is used for each slot.

You can find the slot ID by viewing the slot configuration in the CMH.

For instructions on how to create query pipeline conditions, see Manage query pipeline conditions.

Step 2: Associate a Product Recommendation model with the query pipeline for recommendations:

  1. In the Coveo Administration Console, access the Query Pipelines page.

  2. In the Query Pipelines page, click the query pipeline configured for recommendations, and then click Edit components.

  3. Click the Machine learning tab, and then click Associate model.

  4. Under Model, select the Product Recommendation model you want to associate with the query pipeline.

  5. Under Condition, select the query pipeline condition you created in Step 1 for the CMH strategy you want to associate with the model.

  6. Under Number of results, enter the maximum number of recommendations you want the model to return. Maximum value is 50.

  7. Under Strategy selection, select the product recommendation strategy you want to use for the model association. Refer to the following table for the mapping between CMH strategies and underlying pipeline strategies:

    CMH strategy Strategy to use

    Viewed together

    Viewed together

    Viewed together, same category

    Viewed together, different category

    Purchased together

    Purchased together

    Purchased together without fallback

    Purchased together, same category

    Purchased together, different category

    Purchased together - Cart

    Intent-aware

    Intent-aware, enriched - Homepage

    Intent-aware, most viewed

    Intent-aware, most viewed, enriched

    Most viewed

    Most viewed

    Most viewed, same category

    Most purchased

    Most purchased

    Most purchased, same category

    Recently viewed

    Recently viewed without fallback

    Recently purchased

    Recently purchased without fallback

    Purchased with recently purchased

    Purchased together with recently viewed

    Most viewed with last viewed
    Note

    If a strategy is greyed out, it means that the selected model wasn’t trained to support that strategy. You can edit the model to include the missing strategies.

  8. Click Associate model.

Leading practices

When associating a PR model, consider the following leading practices:

  • When associating a PR model which will be used to power recommendation slots configured through the Coveo Merchandising Hub (CMH), select the Coveo Merchandising Hub tab at the top of this article to follow the relevant instructions.

  • You should have a query pipeline dedicated to product recommendations. This pipeline must be used solely to route recommendation queries.

  • PR models shouldn’t be associated with pipelines that contain other model types.

About query pipeline conditions

query pipeline conditions route recommendation queries to the correct query pipeline and trigger the appropriate PR model association. To route recommendation queries to this query pipeline, use the recommended condition-based routing mechanism. The recommended condition to use at the query pipeline level is:

Recommendation is not empty

This condition uses the recommendation query parameter of a Search API request. It ensures that any query containing this parameter is handled by your dedicated recommendations pipeline.

Next, within that pipeline, you must create a PR model association for each strategy you want to use. The condition for each association must check for a specific value in the recommendation query parameter.

For example, to trigger the "Frequently bought together" association, your component might send frequentBought in the recommendation parameter. The corresponding association condition would be:

Recommendation is frequentBought
Important

The value used in an association condition (for example, frequentBought) is custom and must match the value sent by your recommendation component.

For example, if you’re using the generic Headless RecommendationList controller, this value is what you define in the id option of the controller.

Associate a PR model

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to associate the model, and then click Edit components in the Action bar.

  2. On the subpage that opens, select the Machine learning tab, and then in the upper-right corner, click Associate model.

  3. In the Model dropdown menu, select the desired model.

  4. On the right side, under Condition, you can select a query pipeline condition in the dropdown menu or create a new one.

  5. In the Advanced Configuration section, select a recommendation strategy. Refer to Product Recommendation strategies for more details.

    Note

    If the strategy you want to use isn’t available in the Advanced Configuration section, you must choose an available strategy and then update the model association JSON configuration to mention the desired strategy key as the value of the strategy key. For example:

    [...]
"customQueryParameters": {
    "strategy": "recommendationsUsingRecentlyViewed"
},
[...]

  6. Click Associate model.

Edit a PR model association

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to edit a model association, and then click Edit components in the Action bar.

  2. On the subpage that opens, select the Machine learning tab, click the desired model, and then click Edit in the Action bar.

  3. On the right side, under Condition, you can select a query pipeline condition in the dropdown menu or create a new one.

  4. In the Advanced Configuration section, select a recommendation strategy. Refer to Product Recommendation strategies for more details.

    Note

    If the strategy you want to use isn’t available in the Advanced Configuration section, you must choose an available strategy and then update the model association JSON configuration to mention the desired strategy key as the value of the strategy key. For example:

    [...]
"customQueryParameters": {
    "strategy": "recommendationsUsingRecentlyViewed"
},
[...]

  5. Click Save.

Dissociate a model

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline from which you want to dissociate a model, and then click Edit components in the Action bar.

  2. On the subpage that opens, select the Machine learning tab.

  3. Click the model you want to dissociate from the pipeline, and then click Dissociate in the Action bar.

Reorder model associations

The order in which models appear in the query pipeline Machine learning tab is only relevant when multiple models of the same type are present. If there are no duplicate model types in the list, the model order has no effect as each model will either execute or not based on its individual condition.

However, when multiple models of the same type are present, the models are evaluated sequentially from top to bottom. The first model with a satisfied condition is executed, and all subsequent models of the same type are ignored.

To reorder model associations in a query pipeline

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline in which you want to reorder model associations, and then click Edit components in the Action bar.

  2. On the subpage that opens, select the Machine learning tab.

  3. Click the model whose position you want to change, and then use the Move up or Move down arrows in the Action bar to change the position of the model.

Edit a PR model association via JSON

Advanced users may want to manage a model association via a JSON configuration to specify association parameters that don’t fit with the parameters available in the Administration Console.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to edit a model association, and then click Edit components in the Action bar.

  2. On the Machine learning tab, double-click the desired model.

  3. If the Edit a Model Association subpage opens in JSON view, proceed to the next step. Otherwise, in the upper-right corner, click dots, click Switch to JSON view, and then click Switch to JSON view in the confirmation window.

  4. On the Edit a Model Association subpage, in JSON view, tune the JSON model association configuration as needed (see Model association parameters).

  5. Click Save.

Model association parameters

You can use the following parameters when creating or editing a Coveo ML PR model association.

id (string)

The unique identifier of the model association (automatically generated by the Coveo Search API).

Example: 62579f33-a505-4d07-b77d-545aefb2eea1

position (integer [int32])

The position of the model in the order of execution (see Reorder model associations).

Example: 8

modelId (string)

The unique identifier of the model (see Review model information).

Example: c7ab60e2-e6b8-41e8-be6a-ad5c8edc662e

modelDisplayName (string)

The name of the model as selected when creating the model. This field is automatically filled with the name of the Coveo ML model.

Example: MyModelName

modelEngine (string)

The ID of the Coveo ML model. This field is automatically filled with the ID of the Coveo ML model.

Example: ecommerce

modelStatus (string)

The status of the model. This field is automatically generated according to the current ML model status.

Example: ONLINE

condition (string)

The unique identifier of the condition that must be satisfied for a request to be processed by the ML model.

Example: c7ab60e2-e6b8-41e8-be6a-ad5c8edc662e

conditionDefinition (string)

The QPL expression that indicates the condition defined for the model association (see Query Pipeline Language (QPL)). This field is automatically filled when a condition is specified.

Example: when $searchHub is \"internalSearch\"

cacheMaximumAge (string)

The maximum age of cached query results the ML model should accept, in the ISO-8601 format only including the seconds and milliseconds part.

For each incoming query to be processed by the ML model, if a result set for an identical previously made query is available in the cache and this result set isn’t older than the specified value, the ML model makes recommendations based on that cached query result set. Otherwise, the query is executed against the index.

Default: PT105

rankingModifier (integer [int32])

The ranking score modifier the ML model should apply to each item it recommends.

Default: 0

exclusive (boolean)

Whether the Search API should only return items which were recommended by the ML model, even if other items matching the query were found in the index.

Default: true

customQueryParameters (JValue (object))

A JSON object representing the additional parameters to send to Coveo ML on all queries.

This object allows you to specify the key of the strategy you want to use for the model association.

strategy (string)

The strategy used by the model to provide its recommendations.

See Product recommendation strategies to know which key to use depending on the strategy you want to use.

Default: popularViewed

useAdvancedConfiguration (boolean)

Whether the model association specifies an advanced configuration.

Default: false

Code sample

The following code sample shows a Product Recommendation (PR) model association in JSON:

{
  "position": 1,
  "modelId": "XXXXXX_ecommerce_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
  "condition": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "exclusive": true,
  "customQueryParameters": {
    "strategy": "frequentViewed"
  },
  "useAdvancedConfiguration": false
}

For complete information on PR model available association parameters, see PR model association parameters reference.

Required privileges

By default, members with the required privileges can view and edit elements of the Models (platform-ca | platform-eu | platform-au) page.

The following table indicates the privileges required to use elements of the Models page and associated panels (see Manage privileges and Privilege reference).

Action Service - Domain Required access level

View model associations

Machine Learning - Models
Organization - Organization
Search - Query pipelines

View

Edit model associations

Organization - Organization
Machine Learning - Models

View

Search - Query pipelines

Edit