Advanced Model Configurations API

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

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

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

While you can use the Machine Learning Advanced Model Configurations API to manage a model’s advanced configuration file, we recommend that you use the Advanced tab of a model configuration in the Coveo Administration Console instead (see Machine Learning Advanced Configuration).

Block Lists

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

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 terms knights, the whole query is ignored by the model.

Block Lists 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 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 website.

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 is no value, all queries are considered 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

Facet ID Mappings

Coveo ML models may learn from users interactions made within the facet component of a search interface. If you’re using an older version of the facet component, or if you have a custom integration, the facetField metadata could be missing from the received usage analytics events (see Implement Facets).

In that case, you can configure a Facet ID Mappings file that will link a facetId to a facetField. This is required for a DNE model to order facets and boost the ranking of search results.

A Facet ID Mappings file must therefore contain a map of facet IDs and facet fields (see Create or Update a Model’s Advanced Configuration File).

Facet 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 column must contain a facetId whereas the second column must contain the related facetField.

EXAMPLE
Color,color
Product Type,producttype
Brand,brand1234
Recommended Articles