Set advanced ART model configurations using the API

This is for:

Developer System Administrator

The Machine Learning Advanced Model Configurations API lets you manage the following advanced configurations for your ART model:

To set an advanced configuration using the API

  1. Create or update an advanced configuration file.

  2. Upload the advanced configuration file to the model.

Tip

You can also get a list of advanced configuration files currently used by the model, or delete a configuration file from the model.

Prerequisites

Create or update an advanced configuration file

Setting an advanced configuration using the API requires an advanced configuration file.

You can create a new configuration file from scratch, or download an existing file that you previously uploaded to a model to edit its configuration.

  1. If required, to edit an advanced configuration file that’s currently used by a model, first download the file using the Swagger UI as follows:

    1. Access the Advanced Model Configurations section of the Swagger UI that’s associated with your Coveo organization region (US | CA | EU | AU).

    2. Click Authorize and authenticate using your Coveo organization account credentials.

      Note

      The Coveo organization account you use for authentication must have the Machine learning - Models - Edit privilege.

    3. Use the configs/{configurationType} GET operation to download an existing configuration file that you want to edit:

      Use Swagger UI to download a model advanced configuration file | Coveo

      1. Enter the required parameters for the model and configuration type that you want to download.

      2. Once you’ve entered the parameters, click Execute.

      3. Click Download file in the response body to download the file.

  2. Use your preferred text editor to either modify the downloaded advanced configuration file or create a new file from scratch. The advanced configuration file must not exceed 10 MB. The configuration file requirements and formatting depends on the configuration type:

  3. Upload the advanced configuration file to the model.

Upload an advanced configuration file

Once you’ve created the configuration file, use the Swagger UI to upload it to a model to apply the advanced configuration to that model.

The advanced configuration file must not exceed 10 MB.

  1. Access the Advanced Model Configurations section of the Swagger UI that’s associated with your Coveo organization region (US | CA | EU | AU).

  2. Click Authorize and authenticate using your Coveo organization account credentials.

    Note

    The Coveo organization account you use for authentication must have the Machine learning - Models - Edit privilege.

  3. Use the configs/{configurationType} PUT operation to upload a configuration file to the model that you want to configure:

    Use Swagger UI to upload a model advanced configuration file | Coveo

    1. Enter the required parameters for the model to which you want to upload the file, as well as the configuration type.

    2. For configFile, click Choose File to select the configuration file.

    3. Click Execute.

Reference

Blocklist

Configure a blocklist file that lists the terms to be ignored by the model.

If a blocklisted term appears in a query, the model ignores the entire query. This means the model won’t use the query to learn from, and the query won’t be used by the model to influence the relevance of results.

Note

A blocklist shouldn’t be used for language-based filtering, such as to specify terms using a language that you don’t want the model to learn from. Instead, to restrict the model to a specific language, use a custom filter.

A blocklist is meant to prevent queries that contain undesirable terms, such as to protect against offensive words or for brand protection, from influencing a model output.

Blocklist file configuration

The blocklist file must be a UTF-8 encoded CSV file, with each term listed as a separate row in a single column.

Once the blocklist file is ready, you can upload it to your model.

Note

The CSV file must contain only the terms to block, and shouldn’t contain headers. Every term in the file is treated as a term to block. In the example CSV file below, knight will be blocked even if it’s intended to be a header in the CSV file.

knight
black knight
dark knight
sword
sabre

Stop words

Configure a stop words file that lists the words to be ignored by the model when analyzing user queries.

Stop words are typically common words, such as articles (a, an, the, etc.), prepositions (on, in, at, etc.), and pronouns (he, she, it, etc.). This is done to reduce the impact of common words on the relevance of the model output. However, given a lack of sufficient relevant content, there’s the possibility that the output of your model is influenced by stop words.

Example

You configured a stop words file that contains the following terms: do, I, my, for, the.

A user performs the following query: How do I change my password for the intranet.

Since the stop words file contains the words do, I, my, for, and the, the query is analyzed as follows by the model:

how change password intranet.

Stop words file configuration

The stop words file must be a UTF-8 encoded CSV file, with each word listed as a separate row in a single column.

Once the stop words file is ready, you can upload it to your model.

Note

The CSV file must contain only a list of stop words, and shouldn’t contain headers. Every term in the file is treated as a stop word. In the example CSV file below, how is considered to be a stop word even if it’s intended to be a header in the CSV file.

how
a
in
to
Example
how
a
in
to
for
on
the
and
I
is
of
do
can
not
or
isn't

ID mappings

Each indexed item is assigned a permanentid that shouldn’t change in time. However, in some situations, most commonly when the source is changed, a document may be assigned a new permanentid. In this situation, the model would require an ID Mappings file linking the old IDs to the new ones. This ensures that the model can use the Coveo Analytics events that were recorded using the old IDs.

You can configure an ID mapping file for any type of model.

ID mapping file configuration

The ID mapping file must be a UTF-8 encoded CSV file. The mappings must be listed in a two-column table, where the columns are separated by a comma (,).

The first row of the table consists of a header for which the first entry must contain the old field name (urihash in the example below). The second header entry must contain the new field name (permanentid in the example below). For the other rows, the first column must contain the older item ID whereas the second column must contain the one that should now be used by the model.

Once the ID mapping file is ready, you can upload it to your model.

Note

The first row of the CSV file for ID mapping must be a header row.
Example
urihash,permanentid
waF9ZfCfOtNtLBrw,4897a0839e4f5fdb757050bb9c7e9128d3b30a6064656001c5e1dceb922a
naQndYJbCSR0iXAk,d2cd76589dd14f0cd6b430cb241af55010737023ddb7eb68796759d7edeb

Retrieve a list of advanced configuration files used by the model

Get a list of advanced configuration files currently used by a model.

  1. Access the Advanced Model Configurations section of the Swagger UI that’s associated with your Coveo organization region (US | CA | EU | AU).

  2. Click Authorize and authenticate using your Coveo organization account credentials.

    Note

    The Coveo organization account you use for authentication must have the Machine learning - Models - View privilege.

  3. Use the configs/status GET operation to get a list of advanced configuration files currently used by a model:

    Use Swagger UI to get a list of advanced configuration files used by a model | Coveo

    1. Enter the required parameters for the model.

    2. Click Execute. The response body shows a list of the advanced configuration files currently used by the model.

Delete an advanced configuration file from a model

Delete an advanced configuration file attached to a model.

  1. Access the Advanced Model Configurations section of the Swagger UI that’s associated with your Coveo organization region (US | CA | EU | AU).

  2. Click Authorize and authenticate using your Coveo organization account credentials.

    Note

    The Coveo organization account you use for authentication must have the Machine learning - Models - Edit privilege.

  3. Use the configs/{configurationType} DELETE operation to delete an advanced configuration file attached to a model:

    Use Swagger UI to delete an advanced configuration file attached to a model | Coveo

    1. Enter the required parameters for the model and configuration type.

    2. Click Execute. The response body shows a list of the advanced configuration files currently used by the model.

Advanced model configuration API parameters

The following parameters are used in the advanced model configuration API. Not all parameters are required for every request. The parameters to use depend on the specific operation being performed.

configurationType (string) - required

Parameter type: query

The type of advanced configuration file. Available values are:

  • BLOCKLISTS

  • STOPWORDS

  • DEFAULT_QUERIES

  • ID_MAPPING

languageCode (string) - optional

Parameter type: query

The language of the configuration file. It must be an ISO 639-1 code, or the string commons.

Important

For a configuration file that uses the commons language value, the queries in that file are automatically added to every other language-specific default queries files in your model. Languages without a default queries file aren’t affected by the commons file.

For example, your model processes queries in English (en), French (fr), and Spanish (es), but your model includes only en and fr default queries configuration files. Uploading a commons file will add its list of queries to the en and fr configuration files, but not to any other language.

modelId (string) - required

Parameter type: path

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

Example
myOrganization_topclicks_22ec9966_0f8b_4adc_967d_65219552192a

organizationId (string) - required

Parameter type: path

The unique identifier of the target Coveo organization (see Retrieve the organization ID).

Example
myorg6j53h4

configFile (file) - required

Note

This applies only when uploading a model’s advanced configuration file.

Parameter type: formData

The configuration file to be uploaded.

Required privileges

The following table indicates the privileges required to manage models (see Manage privileges and Privilege reference).

Action Service Domain Required access level

View models

Machine Learning

Models

View

Organization

Organization

View

Search

Query pipelines

View

Edit models

Machine Learning

Models

Edit

Organization

Organization

View

Search

Query pipelines

View