Associate a Dynamic Navigation Experience (DNE) model with a query pipeline

This is for:

Developer System Administrator

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

organization members with the required privileges can access the Machine Learning tab of a query pipeline configuration page to manage Coveo ML model associations for that query pipeline.

Leading practices

Test the model efficiency

Once you’ve created a Coveo ML DNE model, the leading practice is to test the model performance by doing an A/B test.

This allows you to test the model on a chosen proportion of the traffic passing through a given query pipeline. You can then assess the impact of the model by comparing the query pipeline search performance metrics with and without the model.

Once satisfied with the model efficiency, you can stop the A/B test to make the model effective for all the traffic passing through the query pipeline.

Validate that the model is effective

To validate that your Coveo ML models work as expected, you can inspect your models.

Plan the usage of custom contexts

While Coveo ML models can perform well without custom context information, using custom contexts can take Coveo ML relevance one step further.

You can define custom contexts and then pass appropriate ones along with usage analytics events and queries to allow Coveo ML to take them into account.

Notes

  • Custom context support is limited under the new Event Protocol.

  • If you’re just getting started with Coveo ML, you can skip this step to take advantage of Coveo ML model types more quickly and easily, and consider using custom contexts in a second phase.

Associate a DNE model

Important

Follow the model association leading practices when associating your model with your query pipeline.

  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, you can optionally tune the following parameters:

  6. Click Associate Model.

Important

When the DNE model has been associated with a query pipeline, make sure that the search interfaces in which you want to deploy the model use dynamic facets.

Edit a DNE model association

Important

Follow the model association leading practices when associating your model with your query pipeline.

  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, you can optionally tune the following parameters:

  5. Click Save.

Important

When the DNE model has been associated with a query pipeline, make sure that the search interfaces in which you want to deploy the model use dynamic facets.

Associate a DNE model via a JSON configuration

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 associate a 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 dots, and select Associate a model in JSON view.

  3. On the Associate a Model subpage, in JSON view, replace the <Model_ID> placeholder with the actual ID of the model you want to associate with the pipeline (see Review model information).

    Note

    Once you have accessed the Associate a Model subpage in JSON view:

    • You can always go back to the Associate a Model subpage in the UI view and use the available options. However, all unsaved changes made on the Associate a Model subpage in JSON view will be lost.

    • The Associate a Model subpage in JSON view becomes the default model association view for that model. In other words, the Associate a Model subpage in JSON view is now automatically displayed when you access this model association.

  4. Click Associate Model.

When the DNE model has been associated with a query pipeline, make sure that the search interfaces in which you want to deploy the model use dynamic facets.

Edit a DNE model association via a JSON configuration

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. In the Machine Learning tab, click the desired model, and then click Edit in the Action bar.

  3. On the Edit a Model Association subpage, click dots, and then select Switch to JSON view.

  4. On the Switch to JSON view? panel that appears, click Switch to JSON view.

    Important

    Switching to the JSON view of the Edit a Model Association subpage cancels unsaved configuration changes made on the Model Association page.

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

    Note

    Once you have accessed the Associate a Model subpage in JSON view:

    • You can always go back to the Edit a Model Association subpage in the UI view and use the available options. However, all unsaved changes made on the Associate a Model subpage in JSON view will be lost.

    • If you specified non-default parameters in JSON view of the Edit a Model Association subpage, the complete configuration will be reset to the default one when switching back to the UI view of the Edit a Model Association subpage.

    • The Edit a Model Association subpage in JSON view becomes the default model association view for that model. In other words, the Edit a Model Association subpage in JSON view is now automatically displayed when you access this model association.

  6. Click Save.

When the DNE model has been associated with a query pipeline, make sure that the search interfaces in which you want to deploy the model use dynamic facets.

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. In the Machine Learning tab, click the model you want to dissociate from the pipeline, and then click Dissociate in the Action bar.

Reorder model associations

The Coveo ML models of a given type are executed in the order in which they appear on the page until a condition is satisfied.

Important

The first model on the list will be used if no conditions are met.

  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. In the Machine Learning tab of the desired query pipeline, 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.

Reference

DNE advanced configuration options

Facet ordering

Specifies whether to enable facet ordering for this model association.

This checkbox is selected by default because it’s typically desirable for DNE models to display the most relevant facets first.

You can however deselect this checkbox if you want to take advantage of the other DNE model options, without having your facets automatically ranked.

Facet value ordering

Specifies whether to enable facet value ordering for this model association.

This checkbox is selected by default because it’s typically desirable for DNE models to display the most relevant facet values within a given facet first.

You can however deselect this checkbox if you want to take advantage of the other DNE model options, without having your facet values automatically ranked.

Facet value selection

Specifies whether to enable automatic selection of facet values for this model association.

This checkbox is selected by default for models with the automatic selection of facet values enabled.[1]

When this option is selected, the fields to which the automatic selection of facet values is applied are displayed underneath.

You can however deselect this checkbox if you don’t want the automatic selection of facet values to apply for this model association.

Ranking boost

Specifies whether to enable ranking boost for items that match facet values determined as relevant by the model.

This checkbox is selected by default because it’s typically desirable for DNE models to boost items that match facet values determined as relevant by the model. You can however:

  • Deselect this checkbox if you want to take advantage of the other DNE model options, without having search results that correspond to relevant facets boosted.

  • Adjust the default boosting value applied to items matching relevant facet values.

Notes

  • When a result item is boosted by a DNE model, the rankingModifier query response property takes the Coveo DNE value.

  • Increasing the ranking modifier above the recommended value can considerably alter your search results.

Model association parameters

You can use the following parameters when creating or editing a Coveo ML DNE 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: facetsense

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

locale (string)

The locale of the current user. Adding a locale parameter to a model association allows Coveo ML to provide more relevant recommendations by taking into account the user’s language and regional preferences.

Example

The locale for a user in the United States would be: en-US.

rankingModifier (integer [int32])

The ranking score modifier the ML model should apply to each search result that matches relevant facet values (see Ranking boost).

The rankingModifier value must be a number between 5 and 100 (for example, 75).

Default: 50

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 facetAutoSelect, facetOrdering, facetValueOrdering, and rankingBoost DNE model association parameters.

facetAutoSelect (boolean)

Whether to enable automatic selection of facet values for this model association.

Default:

facetOrdering (boolean)

Whether the model influences facet ordering according to the user query (see Facet ordering).

Default: true

maxRecommendations (integer [int32])

The maximum number of facets that the model can expand and order when the facetOrdering parameter is set to true.

Default: 4

facetValueOrdering (boolean)

Whether the model influences facet values ordering according to the user query (see Facet value ordering).

Default: true

maxRecommendations (integer [int32])

The maximum number of facet values that the model can expand and order within a facet when the facetValueOrdering parameter is set to true.

Default: 8

rankingBoost (boolean)

Whether the search results matching relevant facet values are boosted (see Ranking boost).

Note

If set to false, the boost specified in the rankingModifier parameter isn’t applied.

Default: true

Code sample

The following code sample shows a DNE model association configuration in JSON:

{
  "position": 1,
  "modelId": "XXXXXX_facetsense_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
  "condition": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "rankingModifier": 75,
  "customQueryParameters": {
    "facetOrdering": {
      "isEnabled": true
    },
    "facetValueOrdering": {
      "isEnabled": true
    },
    "rankingBoost": {
      "isEnabled": true
    }
  },
  "useAdvancedConfiguration": true
}

For complete information on DNE model available association parameters, see DNE 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
1. This checkbox is grayed and irresponsive for DNE models that don’t have the facet autoselect option configured.