--- title: Associate an Automatic Relevance Tuning model with a query pipeline slug: l1ca1038 canonical_url: https://docs.coveo.com/en/l1ca1038/ collection: leverage-machine-learning source_format: adoc --- # Associate an Automatic Relevance Tuning model with a query pipeline When a [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [model](https://docs.coveo.com/en/1012/) has been created, it must be associated with a [query pipeline](https://docs.coveo.com/en/180/) to be effective in a [search interface](https://docs.coveo.com/en/2741/). [organization](https://docs.coveo.com/en/185/) [members](https://docs.coveo.com/en/2869/) with the [required privileges](#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 ART model, the leading practice is to test the model performance by doing an [A/B test](https://docs.coveo.com/en/3255/). 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](https://docs.coveo.com/en/3255#key-performance-indicators-section) with and without the model. Once satisfied with the model efficiency, you can [stop the A/B test](https://docs.coveo.com/en/3255#stop-an-ab-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](https://docs.coveo.com/en/mc2g0297/). ## Plan the usage of custom contexts While Coveo ML models can perform well without custom [context](https://docs.coveo.com/en/1345/) information, using custom contexts can take Coveo ML relevance one step further. You can [define custom contexts](https://docs.coveo.com/en/3389/) and then pass appropriate ones along with [Coveo Analytics events](https://docs.coveo.com/en/260/) and [queries](https://docs.coveo.com/en/231/) to allow Coveo ML to take them into account. > **Notes** > > * Custom context support is limited under the new [Event Protocol](https://docs.coveo.com/en/o88d0509#custom-context). > * 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. :leveloffset!: ## Associate an ART model > **Important** > > Follow the [model association leading practices](https://docs.coveo.com/en/l1ca1038#leading-practices) when associating your model with your query pipeline. . On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to associate the model, and then click **Edit components** in the Action bar. . On the subpage that opens, select the **Machine learning** tab, and then in the upper-right corner, click **Associate model**. . In the **Model** dropdown menu, select the desired model. . On the right side, under **Condition**, you can select a [query pipeline condition](https://docs.coveo.com/en/2793/) in the dropdown menu or [create a new one](https://docs.coveo.com/en/1959#create-a-condition). . In the **Advanced Configuration** section, you can optionally select or deselect the following parameters: ** [Ranking modifier](https://docs.coveo.com/en/l1ca1038#ranking-modifier) ** [Match the advanced query](https://docs.coveo.com/en/l1ca1038#match-the-advanced-query) ** [Match the query](https://docs.coveo.com/en/l1ca1038#match-the-query) ** [Comply with Intelligent Term Detection (ITD)](https://docs.coveo.com/en/l1ca1038#comply-with-intelligent-term-detection-itd) > **Important** > > For commerce use cases, a specific configuration is required when associating an ART [model](https://docs.coveo.com/en/1012/) with a query pipeline. > See [About ART for Coveo for Commerce](https://docs.coveo.com/en/o3m90077/) for details. . Click **Associate model**. ## Edit an ART model association > **Important** > > Follow the [model association leading practices](https://docs.coveo.com/en/l1ca1038#leading-practices) when associating your model with your query pipeline. . On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to edit a model association, and then click **Edit components** in the Action bar. . On the subpage that opens, select the **Machine learning** tab, click the desired model, and then click **Edit** in the Action bar. . On the right side, under **Condition**, you can select a [query pipeline condition](https://docs.coveo.com/en/2793/) in the dropdown menu or [create a new one](https://docs.coveo.com/en/1959#create-a-condition). . In the **Advanced Configuration** section, you can optionally select or deselect the following parameters: ** [Ranking modifier](https://docs.coveo.com/en/l1ca1038#ranking-modifier) ** [Match the advanced query](https://docs.coveo.com/en/l1ca1038#match-the-advanced-query) ** [Match the query](https://docs.coveo.com/en/l1ca1038#match-the-query) ** [Comply with Intelligent Term Detection (ITD)](https://docs.coveo.com/en/l1ca1038#comply-with-intelligent-term-detection-itd) > **Important** > > For commerce use cases, a specific configuration is required when associating an ART [model](https://docs.coveo.com/en/1012/) with a query pipeline. > See [About ART for Coveo for Commerce](https://docs.coveo.com/en/o3m90077/) for details. . Click **Save**. ## Associate an ART model via a JSON configuration Advanced users may want to manage a model association via a JSON configuration to specify [association parameters](https://docs.coveo.com/en//3397/) that don't fit with the parameters available in the [Administration Console](https://docs.coveo.com/en/183/). . On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to associate a model, and then click **Edit components** in the Action bar. . 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**. . On the **Associate a Model** subpage, in JSON view, replace the `` placeholder with the actual `ID` of the model you want to associate with the pipeline (see [Review model information](https://docs.coveo.com/en/1894/)). . Click **Associate model**. > **Leading practice** > > While you can specify [model association parameters](https://docs.coveo.com/en/l1ca1038#model-association-parameters) when creating a model association via a JSON configuration, the leading practice is to first create the association, and then [edit its configuration](https://docs.coveo.com/en/l1ca1038#edit-an-art-model-association-via-a-json-configuration) if needed. This allows you to easily tweak the entire configuration of the model association instead of creating it from scratch. ## Edit an ART model association via a JSON configuration Advanced users may want to manage a model association via a JSON configuration to specify [association parameters](https://docs.coveo.com/en//3397/) that don't fit with the parameters available in the [Administration Console](https://docs.coveo.com/en/183/). . On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to edit a model association, and then click **Edit components** in the Action bar. . On the **Machine learning** tab, double-click the desired model. . 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. . On the **Edit a Model Association** subpage, in JSON view, tune the JSON model association configuration as needed (see [Model association parameters](https://docs.coveo.com/en//3397/)). . Click **Save**. ## Dissociate a model . On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline from which you want to dissociate a model, and then click **Edit components** in the Action bar. . On the subpage that opens, select 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 order in which [models](https://docs.coveo.com/en/1012/) 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 . On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline in which you want to reorder model associations, and then click **Edit components** in the Action bar. . On the subpage that opens, select the **Machine learning** tab. . 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 ### ART advanced configuration options #### Ranking modifier The **Recommended** value of **250** typically modifies the ranking score of the ART results so that they appear among the top 10 search results. You should only consider reducing the default value when ART result ranking scores significantly exceed the [default ranking](https://docs.coveo.com/en/1624/), such as when ART results are always appearing among the top five results. You generally don't want ART results to completely override the normal search results ranking, but rather bring them among the first top 10 results. Typical ranking modifiers are between 50 and 250. Oppositely, you should only consider increasing the default value when the ART results generally don't appear within the first search result page. Increase the value until the ART results surface among the top 10 results. **Example** Many customers on a community search page start seeking help on a popular product by entering the part number. However, many useful items available about this product don't include that part number. Consequently, the initial search results don't return relevant items, but customers keep adapting their keywords or navigating in search results until they find an appropriate result for the product. Because ART learns that this result was useful in relation with this part number, when the **Match the query** checkbox is cleared, ART can now recommend it immediately, even if the result doesn't match the part number. #### Match the advanced query The **Match the advanced query** checkbox is selected by default because it's typically desirable for ART results to match search interface scope, [facet](https://docs.coveo.com/en/198/) selections, and [filters](https://docs.coveo.com/en/2736/). Items recommended by ART are typically not distinguishable from other results in search interfaces. If ART is allowed to inject results outside of the expected scope, the overall search experience may feel confusing for your users. **Example** On a community search page, an end user selects the **Knowledge Base Article** value in the **Item Type** facet, enters `acme television set` in the search box, and then submits the query. In the query pipeline, the query is processed by an ART model whose **Match the advanced query** option is enabled. Consequently, the model can only recommend knowledge base articles (that is, items whose `@documenttype` [field](https://docs.coveo.com/en/200/) value is equal to `kbarticle`). If the option was disabled, the model could also recommend items of a different type, such as videos and user manuals. However, the end user likely expects such [items](https://docs.coveo.com/en/210/) to be filtered out, resulting in a confusing experience. > **Important** > > Clearing the **Match the advanced query** checkbox could lead to security issues if the scope of the search interface that's served by the ART model is limited by a [filter rule](https://docs.coveo.com/en/3410/) that's based on the [`aq`](https://docs.coveo.com/en/13#operation/searchUsingPost-aq) query parameter. > > Therefore, you should only consider clearing the **Match the advanced query** checkbox for rare cases or when instructed to do so by Coveo Support. #### Match the query The **Match the query** checkbox is cleared by default because it's typically desirable for ART to be allowed to inject search results that don't necessarily match the keywords entered in the search box by the end user. Therefore, select the **Match the query** checkbox only if the negative side of ART appears to be more important than the benefits or when instructed to do so by Coveo Support. **Example** Many customers on a community search page start seeking help on a popular product by entering the part number. However, many useful items available about this product don't include that part number. Consequently, the initial search results don't return relevant items, but customers keep adapting their keywords or navigating in search results until they find an appropriate result for the product. Because ART learns that this result was useful in relation with this part number, when the **Match the query** checkbox is cleared, ART can now recommend it immediately, even if the result doesn't match the part number. However, the **Match the query** checkbox must be selected for ART models associated with query pipelines that serve [Coveo for Commerce](https://docs.coveo.com/en/1499/) interfaces. This allows the model to return only search results that match the keywords in the user's query, increasing search relevance. **Example** During a shopping session, a customer typically browses through multiple items after performing a query. For example, a user might search for a `red t-shirt`, then ultimately click a search result that depicts a blue t-shirt. Since ART learns from searches and clicks to boost search results, the model may learn a relation between the query `red t-shirt` and an index item that represents a blue t-shirt. By selecting the **Match the query** checkbox, you ensure search results boosted by the model match the keywords in the `red t-shirt` query. #### Comply with Intelligent Term Detection (ITD) Select the **Comply with Intelligent Term Detection (ITD)** checkbox when you want [large query expressions (`lq`)](https://docs.coveo.com/en/214/) (essentially support case descriptions) to be processed by ART to refine the query before it's sent to the index. This option is particularly useful when the Coveo ML model is used in [case deflection panels](https://docs.coveo.com/en/2897/) that may include long case descriptions in their queries. When [ITD](https://docs.coveo.com/en/207/) is enabled, ART selects and injects the most relevant keywords from the [large query expression (`lq`)](https://docs.coveo.com/en/214/) into the current [basic query expression (`q`)](https://docs.coveo.com/en/178/). By default, this selection is based on the average importance of each term, and on the longest substring from your search interface user queries that's part of a list of top user queries. The list contains the top user queries that have been submitted at least five times each in your search interface (see [How Does Intelligent Term Detection (ITD) Work?](https://docs.coveo.com/en/1803#how-does-intelligent-term-detection-itd-work)). ### Model association parameters You can use the following parameters when creating or editing a Coveo ML pass:q,a[ART] 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](#reorder-model-associations)). **Example**: `8` ## `modelId` (string) The unique identifier of the model (see [Review model information](https://docs.coveo.com/en/1894/)). **Example**: `c7ab60e2-e6b8-41e8-be6a-ad5c8edc662e` ## `modelDisplayName` (string) The name of the model as selected when [creating the model](https://docs.coveo.com/en/3397/). 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**: `pass:q,a[topclicks]` ## `modelStatus` (string) The [status](https://docs.coveo.com/en/3397#status-column) 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](https://docs.coveo.com/en/2793/) 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)](https://docs.coveo.com/en/1449/)). This field is automatically filled when a [`condition`](#condition-string) is specified. **Example**: `when $searchHub is \"internalSearch\"` ## `rankingModifier` (integer [int32]) The ranking score modifier the ML model should apply to each [item](https://docs.coveo.com/en/210/) it recommends (see [Ranking modifier](#ranking-modifier)). The rankingModifier value must be a number between 0 and 1,000 (for example, `100`). **Default**: `250` > **Leading practice** > > When associating an ART [model](https://docs.coveo.com/en/1012/) with a [query pipeline](https://docs.coveo.com/en/180/) that handles product listing queries, make sure to set the `rankingModifier` value to `500`. ## `maxRecommendations` (integer [int32]) The maximum number of ART-boosted items that the ML model should return in a results page. **Default**: `5` > **Note** > > The `maxRecommendations` parameter value indicates the maximum number of ART-boosted items that the model returns before the Coveo Search API and the index apply subsequent filters (for example, > query pipeline rules or item permission). > **Leading practice** > > When associating an ART [model](https://docs.coveo.com/en/1012/) with a [query pipeline](https://docs.coveo.com/en/180/) that handles product listing [queries](https://docs.coveo.com/en/231/), make sure to set the `maxRecommendations` value to `50`. ## `cacheMaximumAge` (string) The maximum age of cached [query](https://docs.coveo.com/en/231/) results the ML model should accept, in the [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601#Time_intervals) 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` ## `intelligentTermDetection` (boolean) Whether the model should use the [Intelligent Term Detection (ITD)](https://docs.coveo.com/en/207/) feature to refine queries by extracting relevant [keywords](https://docs.coveo.com/en/2738/) from the [large query expression (`lq`)](https://docs.coveo.com/en/214/) ([Comply with Intelligent Term Detection (ITD)](#comply-with-intelligent-term-detection-itd)). **Default**: `false` ## `intelligentTermDetectionPartialMatchThreshold` (string) An ART model that [complies with ITD](#comply-with-intelligent-term-detection-itd) extracts _refined keywords_ from the user's [`lq`](https://docs.coveo.com/en/214/) using the [partial match](https://docs.coveo.com/en/2858/) feature (see [How does Intelligent Term Detection (ITD) work?](https://docs.coveo.com/en/1803#how-does-intelligent-term-detection-itd-work)). By default, the partial match settings used for ITD has a [`partialMatchThreshold`](https://docs.coveo.com/en/13#operation/searchUsingPost-partialMatchThreshold) value of `60%`. The `intelligentTermDetectionPartialMatchThreshold` model association parameter allows you to modify that default value. **Default**: `60%` **Example**: `75%` ## `intelligentTermDetectionPartialMatchKeywords` (integer [int32]) An ART model that [complies with ITD](#comply-with-intelligent-term-detection-itd) extracts _refined keywords_ from the user's [`lq`](https://docs.coveo.com/en/214/) using the [partial match](https://docs.coveo.com/en/2858/) feature (see [How does Intelligent Term Detection (ITD) Work?](https://docs.coveo.com/en/1803#how-does-intelligent-term-detection-itd-work)). By default, the partial match settings used for ITD has a [`partialMatchKeywords`](https://docs.coveo.com/en/13#operation/searchUsingPost-partialMatchKeywords) value of `1`. The `intelligentTermDetectionPartialMatchKeywords` model association parameter lets you to modify that default value, allowing you to increase the number of keywords required for the partial match feature to be activated. This means that ITD can use a larger subset of the user's query. **Default**: `1` **Example**: `4` ## `matchBasicExpression` (boolean) Whether all items recommended by the ML model should match the [basic query expression (`q`)](https://docs.coveo.com/en/178/) (see [Match the query](#match-the-query)). **Default**: `false` ## `matchAdvancedExpression` (boolean) Whether all items recommended by the ML model should match the [advanced query expression (`aq`)](https://docs.coveo.com/en/175/) (see [Match the advanced query](#match-the-advanced-query)). **Default**: `true` ## `customQueryParameters` (JValue (object)) A JSON object representing the [additional parameters](https://docs.coveo.com/en/13#operation/searchUsingPost-mlParameters) to send to Coveo ML on all queries. ## `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`. :leveloffset!: ### Code sample The following code sample shows an [ART](https://docs.coveo.com/en/1013/) model association in JSON: ```json { "position": 1, "modelId": "XXXXXX_topclicks_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX", "condition": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "rankingModifier": 300, "intelligentTermDetection": true, "matchBasicExpression": true, "matchAdvancedExpression": true, "useAdvancedConfiguration": false } ``` For complete information on ART model available association parameters, see [ART Model association parameters reference](https://docs.coveo.com/en/l1ca1038#model-association-parameters). ## Required privileges By default, members with the [required privileges](https://docs.coveo.com/en/1832#required-privileges) can view and edit elements of the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page. The following table indicates the privileges required to use elements of the **Models** page and associated panels (see [Manage privileges](https://docs.coveo.com/en/3151/) and [Privilege reference](https://docs.coveo.com/en/1707/)). [cols="3",options="header"] |=== |Action |Service - Domain |Required access level |View model associations |Machine Learning - Models Organization - Organization Search - Query pipelines |View .2+|Edit model associations |Organization - Organization Machine Learning - Models |View |Search - Query pipelines |Edit |===