Advanced Model Configurations API

This is for:

Developer System Administrator

The Machine Learning Advanced Model Configurations API exposes services which let you create and manage advanced configuration files for your Coveo Machine Learning (Coveo ML) models.

Note

All REST API string fields are case-sensitive unless otherwise specified. For example, search queries aren’t case-sensitive.

To keep behavior consistent across the Coveo Platform, the same value passed to different REST APIs must always be passed using the same case. For example, if the unique product identifier, such as ec_product_id, is passed to the Commerce API in lowercase, then it should also be passed to the Usage Analytics Write API in lowercase.

This API lets you specify additional configurations to further tailor the way your Coveo ML models provide recommendations. It lets you download, upload, and delete files for the following advanced model configuration types:

Note that interactive generated reference documentation is available through Swagger UI (see Coveo Machine Learning API - Advanced Model Configurations API).

Advanced configuration - deprecated

Important

This method is deprecated. To add an advanced configuration to your model, you must either use the advanced configuration parameters available in the Coveo Administration Console, or use the model’s JSON editor.

An Advanced Configuration file must contain an advanced model configuration in JSON format.

This file can be added to any type of model (see Create a model’s advanced configuration).

Blocklists

Blocklists are terms that, when part of a user query, make the whole query unusable by the model. This prevents queries containing undesirable words from influencing recommendations made by a Coveo ML model.

Important

Terms defined in Default queries files override those defined in Blocklists files.

If a term appears in both a Blocklists and a Default queries file, it won’t be blocked by the model and can still be used or suggested.
Example

You configured a Blocklists file that contains the following terms: knights, sabres, and horse.

A user performs the following query: Why do knights use swords?.

Since the Blocklists file contains the term knights, the whole query is ignored by the model.

This file can be added to an Automatic Relevance Tuning (ART) or Query Suggestions (QS) (see Create or update a model’s advanced configuration file).

Blocklists file configuration

The terms must appear in CSV format and be listed in a single column of expressions.

Example
knight
black knight
dark knight
sword
sabre

Stop words

Stop words are typically very common words that must be ignored by an ART or QS model when analyzing queries such as articles, prepositions, and pronouns. You can configure a Stopwords file to specify stop word terms for a specific model. Note that these terms can still be suggested by a QS model.

Example

You configured a Stopwords 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 Stopwords file contains the following terms do, I, my, for, the, the query is analyzed as follows by the model:

how change password intranet.

This file can be added to an ART or QS model (see Create or Update a Model’s Advanced Configuration File).

Stop words file configuration

The terms must appear in CSV format and be listed in a single column of expressions.

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

Default queries

A Default Queries file lets you pre-populate queries to be suggested by a Coveo ML QS model. It must contain a list of queries to be added as suggestion candidates for a Coveo ML QS model (see Create or Update a Model’s Advanced Configuration File).

This is useful in test environments to make sure that a QS model makes suggestions or to help a new model provide suggestions by including queries originating from an existing site.

Note

The limit of default queries is 5,000 per language. If the file contains more than 5,000 queries for a given language, the model only considers the 5,000 most performed queries.
Important

Terms defined in Default queries files override those defined in Blocklists files.

If a term appears in both a Blocklists and a Default queries file, it won’t be blocked by the model and can still be used or suggested.
Note

To ensure optimal performance, a Query Suggestion (QS) model limits the number of possible suggestions per language to a preset maximum. The limit is enforced after the most relevant query suggestions are identified and ranked, and after any manually defined default query suggestions are applied. The enforced limit is large enough to not negatively impact the quality of the suggestions. The most relevant suggestions are always recommended to the user, regardless of the enforced limit. The limit, however, may explain why a query that appears as a candidate in your data isn’t suggested for a given user query.

Default queries file configuration

The queries must appear in CSV format and be listed in a two-column table, where the columns are separated by a comma (,). The first column must contain the desired queries, whereas the second column can optionally contain an integer value representing the relative importance of each query. For example, a common value would be the past occurrence count of these queries. If there’s no value, all queries are considered to be of equal importance.

Example
knight,1200
black knight
dark knight,400
sword,250
sabre

ID mappings

Each indexed item is assigned a permanentid that should not 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 usage analytics events that were recorded using the old IDs.

An ID Mappings file must contain a map of item unique identifiers along with their equivalents. This file can be added to any type of model (see Create or Update a Model’s Advanced Configuration File).

ID mapping file configuration

The IDs must appear in CSV format and 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.

Example
urihash,permanentid
waF9ZfCfOtNtLBrw,4897a0839e4f5fdb757050bb9c7e9128d3b30a6064656001c5e1dceb922a
naQndYJbCSR0iXAk,d2cd76589dd14f0cd6b430cb241af55010737023ddb7eb68796759d7edeb