Associate a Relevance Generative Answering (RGA) 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.

When a Relevance Generative Answering (RGA) model is associated with a query pipeline, the model is used to generate answers for queries that are submitted in the search interface that’s associated with the query pipeline.

Notes

Associate an RGA 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.

    Note

    An RGA model must be associated with a Query is not empty condition.

  5. Click Associate Model.

Edit an RGA 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.

    Note

    An RGA model must be associated with a Query is not empty condition.

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

RGA model association advanced configuration

You can use the RGA model association advanced configuration to:

Important

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

Once you use the JSON view to set the association configuration for a given model, you must continue to use the JSON view for all future configurations for that model. If you switch back to the UI view and save your model association, you will lose all of your custom JSON model association configurations.

Maximum number of items to consider

RGA uses two stages of content retrieval. First-stage content retrieval identifies the most relevant items in the index, and second-stage content retrieval identifies the most relevant segments of text (chunks) from the items identified during first-stage content retrieval. The answer is generated using the most relevant chunks.

If you find that answers are being generated using text from low relevance documents, you can use the numberOfRankedResultsToConsider model association parameter to set a custom value for the maximum number of items considered during second-stage content retrieval. For example, if you set the maximum number of items to 20, the RGA model retrieves the most relevant chunks only from the 20 most relevant items that were retrieved during first-stage content retrieval.

Important

This is an advanced model association configuration that should be used by experienced Coveo administrators only.

The default setting of 100 provides good results in the majority of use cases. However, you can specify a custom value if you have a finely tuned query pipeline and you have a good understanding of the relevance hierarchy of the search results that are returned by your query pipeline configuration. Otherwise, if you set the value too low, there may not be enough relevant text (chunks) to generate an answer.

Modifying the default setting may result in unintended model behavior following a model version upgrade.

To set a custom value for the number of items to consider for RGA

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

  2. Select the Machine Learning tab.

  3. Double-click the RGA model.

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

    Warning

    Once you use the JSON view to set the association configuration for a given model, you must continue to use the JSON view for all future configurations for that model. If you switch back to the UI view and save your model association, you will lose all of your custom JSON model association configurations.

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

    The value must be an integer between 1 and 100 (default is 100).

    Example

    To set the custom value to 20, the JSON would be:

    {
  "customQueryParameters":{
    "numberOfRankedResultsToConsider": 20
  }
}

  6. Click Save.

RGA relevancy threshold

During second-stage content retrieval, RGA retrieves the most relevant segments of text (chunks) based on semantic similarity with the query. The relevancy threshold, however, determines whether or not a chunk is relevant enough to be considered by the RGA model for answer generation. Chunks that do not pass the relevancy threshold are not considered by the RGA model, and are not used to generate answers.

This setting essentially determines how strict the RGA model is in considering chunks for answer generation based on relevancy.

Depending on your indexed content, the default relevancy threshold may result in one of the following scenarios:

  • An answer isn’t generated due to a lack of relevant chunks (threshold value is too high).

  • An answer is generated, but some of the chunks used to generate the answer are of lower relevance (threshold value is too low).

If you find that answers aren’t being generated, or answers are generated with less relevant chunks, you can use the chunksSimilarityThreshold model association parameter to set a custom value for the relevancy threshold.

Important

This is an advanced model association configuration that should be used by experienced Coveo administrators only.

The default setting of 0.5, which is the midpoint of the allowable range, 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 relevancy threshold that’s used by the RGA model. If you set the value too high, there may not be enough relevant text (chunks) to generate an answer, but if you set the value too low, answers may be generated with less relevant chunks.

Modifying the default setting may result in unintended model behavior following a model version upgrade.

To set a custom value for the RGA relevancy threshold

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

  2. Select the Machine Learning tab.

  3. Double-click the RGA model.

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

    Warning

    Once you use the JSON view to set the association configuration for a given model, you must continue to use the JSON view for all future configurations for that model. If you switch back to the UI view and save your model association, you will lose all of your custom JSON model association configurations.

  5. In the JSON editor, add "chunksSimilarityThreshold": "<VALUE>" under customQueryParameters, where <VALUE> represents the threshold value.

    The value must be a floating-point number between 0 and 1.0 (default is 0.5).

    A higher threshold value means that a chunk needs to be highly similar to the query to be considered relevant. A lower threshold value means that chunks only need to be slightly similar to the query to be considered relevant.

    Example

    Answers aren’t being generated with expected regularity, so you decide to lower the relevancy threshold to 0.45. In this case, the JSON would be as follows:

    {
  "customQueryParameters":{
    "chunksSimilarityThreshold": 0.45
  }
}

  6. Click Save.

Rich text formatting

By default, the answers generated by RGA are displayed in the RGA search interface component using plain text. This means that the generated answers don’t include any rich text formatting, such as bold text, code blocks, or tables.

Rich text formatting makes the generated answers more visually appealing and easier to read. To enable rich text formatting for generated answers, you must enable the enableContentFormat model association parameter.

RGA supports the following rich text formatting:

  • Headings

  • Strong and emphasized text (bold/italic)

  • Inline and multi-line code blocks

  • Quote blocks

  • Ordered and unordered lists

  • Tables

Examples

The following are examples of a generated answer with rich text formatting:

Relevance Generative Answering rephrase
Relevance Generative Answering rephrase
Important

If you’re using the Coveo Headless library for your search interface, besides enabling rich text formatting as detailed in this section, you must also set text/markdown as the first value in the contentFormat property array for GeneratedResponseFormat. The answer is generated using the first format in the contentFormat property array, from left to right, that’s supported by the RGA component. Coveo recommends that you include text/plain as the last value in the array as a fallback.

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

  2. Select the Machine Learning tab.

  3. Click the RGA model.

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

    Warning

    Once you use the JSON view to set the association configuration for a given model, you must continue to use the JSON view for all future configurations for that model. If you switch back to the UI view and save your model association, you will lose all of your custom JSON model association configurations.

  5. In the JSON editor, add "enableContentFormat": true under customQueryParameters to enable rich text formatting.

    Example

    To enable rich text formatting, the JSON would be as follows:

    {
  "customQueryParameters":{
    "enableContentFormat": true
  }
}

  6. Click Save.

Prevent duplicate GQPM when using the Answer Manager

If you associated your RGA-enabled search interface with an answer configuration in the Answer Manager, add the answerAPI condition to the query pipeline’s RGA model association to prevent duplicate generative queries per month (GQPM).

When a search interface is linked to an answer configuration, the query goes through the Search API as all queries do normally. However, in addition to the Search API, the query also goes through the Answer API. The Answer API is used by the answer configuration to collect feedback on the generated answers, and to apply any rules that were created in the answer configuration that impact the generated answers.

Adding an answerAPI condition to the query pipeline’s RGA model association ensures that only the query in the Answer API is used to request generated answers from RGA. Otherwise, both query streams would make requests to the RGA model, which results in a duplicate generative query.

Important

If an RGA-enabled search interface is no longer associated with an answer configuration, remove the answerAPI condition for your RGA model in your query pipeline. Otherwise, your search interface won’t use the RGA model and answers won’t be generated.

To add the answerAPI condition

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

  2. Select the Machine Learning tab.

  3. Double-click the RGA model.

  4. The procedure on how to add the condition depends on if the Edit a Model Association subpage opens in UI view or JSON view.

    UI vs JSON view | Coveo Machine Learning
    Warning

    Once you use the JSON view to set the association configuration for a given model, you must continue to use the JSON view for all future configurations for that model. If you switch back to the UI view and save your model association, you will lose all of your custom JSON model association configurations.

    • If the subpage opens in UI view:

      1. On the Edit a Model Association subpage, under Condition, add a Context[answerAPI] is true condition. To do so, either select the condition from the dropdown menu if it was created previously, or click Create a new condition and perform the following steps:

        1. In the Add a condition panel, click the first dropdown menu, and then select Context.

        2. For Context key, enter answerAPI.

        3. For Context type, select Boolean.

        4. Click the second dropdown menu, and then select the Is operator.

        5. Select True.

          Relevance Generative Answering condition | Coveo Administration Console

        6. Click Add condition.

      2. Click Save.

    • If the subpage opens in JSON view:

      1. Access the Conditions (platform-ca | platform-eu | platform-au) page of the Administration Console.

      2. If you haven’t yet created a Context[answerAPI] is true condition, click Add condition, and perform the following steps:

        1. In the Add a condition panel, click the first dropdown menu, and then select Context.

        2. For Context key, enter answerAPI.

        3. For Context type, select Boolean.

        4. Click the second dropdown menu, and then select the Is operator.

        5. Select True.

          UI vs JSON view | Coveo Machine Learning

        6. Click Add condition.

      3. On the Conditions (platform-ca | platform-eu | platform-au) page, double-click the Context[answerAPI] is true condition.

      4. The Edit a condition subpage opens, and the condition ID appears as the last segment of the URL. Copy the condition ID from the URL, and paste it into a temporary location, such as a text file. You’ll need this ID later when adding the condition to the RGA model association.

        Condition ID | Coveo Machine Learning

      5. Click Cancel to close the Edit a condition subpage.

      6. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline to which the RGA model is associated, and then click Edit components in the Action bar.

      7. Select the Machine Learning tab, and then double-click the RGA model.

      8. In the JSON editor, add "condition": "<VALUE>", where <VALUE> is the ID of the Context[answerAPI] is true condition.

        Example

        If the condition ID is abcdefgh-123-456-ijkl-mnop7890, the JSON would be:

        {
  "condition": "abcdefgh-123-456-ijkl-mnop7890"
}

      9. Click Save.

        Note

        After specifying a condition ID and saving, "conditionDefinition": "when $context [answerAPI] is true" is automatically added to the JSON. This indicates the condition that’s defined for the model association.

Remove the answerAPI condition

If an RGA-enabled search interface is no longer associated with an answer configuration, remove the answerAPI condition for your RGA model in your query pipeline. Otherwise, your search interface won’t use the RGA model and answers won’t be generated.

To remove the answerAPI condition

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

  2. Select the Machine Learning tab.

  3. Double-click the RGA model.

  4. The procedure to remove a condition depends on if the Edit a Model Association subpage opens in UI view or JSON view.

    UI vs JSON view | Coveo Machine Learning
    Warning

    Once you use the JSON view to set the association configuration for a given model, you must continue to use the JSON view for all future configurations for that model. If you switch back to the UI view and save your model association, you will lose all of your custom JSON model association configurations.

    • If the subpage opens in UI view, under Condition, remove the Context[answerAPI] is true condition.

    • If the subpage opens in JSON view, delete the "condition" and "conditionDefinition" parameters from the JSON editor.

  5. Click Save.

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

What’s next?

Enable the RGA component in your search interface.