---
title: Associate a Semantic Encoder (SE) model with a query pipeline
slug: nb8b0088
canonical_url: https://docs.coveo.com/en/nb8b0088/
collection: leverage-machine-learning
source_format: adoc
---
# Associate a Semantic Encoder (SE) model with a query pipeline
> **Important**
>
> * A [Semantic Encoder (SE)](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) is only supported for use as part of a [Relevance Generative Answering (RGA)](https://docs.coveo.com/en/n9de0370/) or [Passage Retrieval (CPR)](https://docs.coveo.com/en/oaie5277/) implementation.
> 
> * The [Semantic Encoder (SE)](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) is available as a paid product extension.
> Contact [Coveo Sales](https://www.coveo.com/en/contact) or your Account Manager to add SE to your [organization](https://docs.coveo.com/en/185/) license.

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.

When an [Semantic Encoder (SE)](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) is associated with a query pipeline, the model adds [vector](https://docs.coveo.com/en/nccf9008/) search capabilities to the Coveo-powered search interface or LLM-powered application that's associated with the query pipeline.
Vector search uses [embeddings](https://docs.coveo.com/en/n9de0370#embeddings) to find items with high semantic similarity with the query.

> **Important**
>
> The [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) must be associated to the same query pipeline as the [RGA](https://docs.coveo.com/en/nbtb6010/) or [CPR](https://docs.coveo.com/en/oaie9196/) [model](https://docs.coveo.com/en/1012/).

> **Note**
>
> Query pipeline [thesaurus](https://docs.coveo.com/en/3405/) and [stop word](https://docs.coveo.com/en/3406/) rules are not applied to the query that's used by the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/).
> The [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) always uses the raw [basic query expression (`q`)](https://docs.coveo.com/en/178/) entered by the user without any transformations or modifications.

## Associate an SE model

> **Important**
>
> Follow the [model association leading practices](https://docs.coveo.com/en/nb8b0088#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).

. Click **Associate model**.

## Edit an SE association

> **Important**
>
> Follow the [model association leading practices](https://docs.coveo.com/en/nb8b0088#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).

. 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.

## SE model association advanced configuration

You can use the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) association advanced configuration to:

* [Modify the minimum semantic similarity threshold](#se-minimum-semantic-similarity-threshold) that's used by the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) to determine whether an indexed item is relevant to the query.

* [Modify the minimum and maximum ranking modifier values](#minimum-and-maximum-ranking-modifiers) to apply to items returned by the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/).

* [Modify the maximum number of retrieved items to use](#maximum-number-of-items) by the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/).

> **Important**
>
> Modifying the default values for the model association advanced parameters may result in unintended model behavior following a model version upgrade.

### SE minimum semantic similarity threshold

When a user enters a query in a Coveo-powered search interface or an LLM-powered application, the query passes through a query pipeline where traditional lexical (keyword) search, pipeline rules, and machine learning are applied to find relevant items.
However, in addition to this, the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) uses [vector](https://docs.coveo.com/en/nccf9008/)-based search to find items in the index that are semantically similar to the query.
The search results show the most relevant items from both search capabilities (traditional and [vector](https://docs.coveo.com/en/nccf9008/)-based).

A preset minimum similarity threshold determines whether an item is considered semantically relevant by the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/).
Depending on your indexed content, however, the default minimum similarity threshold value may be too high or too low.
If it's too high, not enough items are returned by the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) as the threshold is too strict.
Conversely, too low of a value can result in items being returned that have little relevance to the query.

> **Note**
>
> The [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) applies a [ranking modifier value](#minimum-and-maximum-ranking-modifiers) to a retrieved item to boost the item's relevancy in the search results.

> **Important**
>
> This is an advanced [model](https://docs.coveo.com/en/1012/) association configuration that should be used by experienced Coveo administrators only.
> 
> The default setting of `0.80` provides good results in the majority of use cases.
> However, you can specify a custom value if you have a good understanding of your indexed content and want to fine-tune the semantic similarity threshold that's used by the [SE](https://docs.coveo.com/en/nbtb0041/) model to retrieve items.
> If you set the value too high, semantically relevant items might not be returned, but if you set the value too low, items being returned may have little relevance with the query.

You can use the `minCosine` model association parameter to modify the [SE](https://docs.coveo.com/en/nbtb0041/) minimum similarity threshold.

To set a custom value for the [SE](https://docs.coveo.com/en/nbtb0041/) minimum semantic similarity threshold

. 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 to which the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) is associated, and then click **Edit components** in the Action bar.

. Select the **Machine learning** tab.

. Double-click the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/).

. 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.

. In the JSON editor, add `"minCosine": "<VALUE>"` under `customQueryParameters`, where `<VALUE>` is the threshold value.

The value must be a floating-point number between `-1.0` and `1.0` (excluded).
The default value is `0.80`.

The higher the value, the more semantically similar to the query an item needs to be for the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) to consider the item as relevant.

**Example**

Items that should be returned as semantically relevant don't appear in the search results, so you decide to lower the minimum semantic similarity threshold to `0.65`.
In this case, the JSON would look like this:

```json
{
  "customQueryParameters":{
    "minCosine": 0.65
  }
}
```

### Minimum and maximum ranking modifiers

The [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) applies a ranking modifier value to the indexed items that are retrieved based on the [minimum semantic similarity threshold](#se-minimum-semantic-similarity-threshold).
The ranking modifier value boosts the item's relevance in the search results.

The minimum and maximum ranking modifier values essentially set a range of modifier values that the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) will use for retrieved items.
To determine the actual modifier value for an item, the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) applies linear scaling between the semantic similarity threshold range and the ranking modifier range.
The ranking modifier value that's used is based on the item's semantic similarity score that's scaled to the ranking modifier range.

**Example**

Given the following settings:

* Minimum semantic similarity threshold value (`minCosine`) set to `0.80`.

* Minimum and maximum ranking modifier values set to `100` and `4500` respectively.

For an item with a semantic similarity score of `0.85`, applying linear scaling results in a ranking modifier value of `1200` for the item.

![Semantic Encoder model ranking modifier](https://docs.coveo.com/en/assets/images/leverage-machine-learning/se-model-min-max-ranking.png)

To set custom values for the [SE](https://docs.coveo.com/en/nbtb0041/) minimum and maximum ranking modifiers

. 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 to which the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) is associated, and then click **Edit components** in the Action bar.

. Select the **Machine learning** tab.

. Double-click the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/).

. 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.

. In the JSON editor, under `customQueryParameters`:

* Add `"minRankingModifier": "<VALUE>"`, where `<VALUE>` is the minimum modifier value.

The value must be between `0` and `infinity` (default is `100`).

* Add `"maxRankingModifier": "<VALUE>"`, where `<VALUE>` is the maximum modifier value.

The value must be between `1` and `infinity`, and greater than `minRankingModifier` (default is `4500`).

**Example**

To set the minimum ranking modifier value to `250` and the maximum ranking modifier value to `3000`, the JSON would be as follows:

```json
{
  "customQueryParameters":{
    "minRankingModifier": 250,
    "maxRankingModifier": 3000
  }
}
```

### Maximum number of items

When a user enters a query in a Coveo-powered search interface, the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) retrieves items from the index that are semantically similar to the query based on if the item meets the [minimum semantic similarity threshold](#se-minimum-semantic-similarity-threshold).
The [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) then applies a ranking modifier value to each retrieved item based on the item's similarity score to boost the item's relevance in the search results.

By default, just the top `500` retrieved items based on semantic similarity score are taken into consideration by the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/).
The default setting of `500` provides good results in the majority of use cases.
However, you can modify the setting to increase or decrease the maximum number of items the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) considers.
For example, you can lower the value if the maximum number of retrieved items used by the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) is too high for your specific dataset.

To set a custom value for the maximum number of items for SE

. 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 to which the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) is associated, and then click **Edit components** in the Action bar.

. Select the **Machine learning** tab.

. Double-click the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/).

. 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.

. In the JSON editor, add `"topK": "<VALUE>"` under `customQueryParameters`, where `<VALUE>` is the maximum number of items.

The value must a number between `1` and `infinity` (default is `500`).

**Example**

To set the maximum number of retrieved items for the [SE](https://docs.coveo.com/en/nbtb0041/) [model](https://docs.coveo.com/en/1012/) to `350`, the JSON would be as follows:

```json
{
  "customQueryParameters":{
    "topK": 350
  }
}
```


## 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
|===