Create and Manage a Product Recommendations Model
Coveo Machine Learning (Coveo ML) Product Recommendations (PR) models suggest to end users products that suit their profile, context, and buying behaviors. The results that are returned by the Coveo ML PR service can be integrated in a Coveo for Commerce search interface.
To take advantage of Coveo ML PR, members with the required privileges must first create their PR models.
Prerequisites
Coveo Machine Learning (Coveo ML) Product Recommendations (PR) models use usage analytics (UA) events to relevantly target and suggest products to your customers.
Before creating your PR model, make sure that the commerce interfaces in which you want to implement the models properly collect commerce usage analytics events. |
If there are less than 100 events available for your PR model, the model is empty and doesn’t provide recommendations. With 100 events or more, your model starts to learn and improve.
Create a PR Model
-
On the Models page, in the upper-right corner, click Add Model to open the Add a Machine Learning Model panel.
-
Under Name, enter a meaningful display name for the model.
-
Under Model type, select Product Recommendations, and then click Next.
-
(Optional) In the Learning Interval section, change the default Frequency and Data period values, and then click Next.
-
(Optional) In the Learn From section, add filters to refine the data that the model uses to make its recommendations.
-
Click Add Model.
-
On the Models page, under the Status column, in the model row, the value is most probably Inactive.
The model value will change to Active when the model creation is complete (typically within 30 minutes, depending on the amount of usage analytics data to process). The model can only return recommendations when its status is Active.
For more information on Coveo ML model statuses, see the Status column reference.
-
Once the model is Active, you must associate the model with a pipeline to take advantage of the model in a search interface.
Make sure to follow the model association leading practices before associating your model with your production query pipeline.
Edit a PR Model
-
On the Models page, click the model you want to edit, and then in the Action bar, click Edit.
-
On the subpage that opens, select the Configuration tab.
-
Under Name, you can optionally edit the model’s display name.
-
(Optional) In the Learning Interval section, change the default Frequency and Data period values.
-
(Optional) In the Learn From section, add filters to refine the data that the model uses to make its recommendations.
-
Click Save.
-
On the Models page, under the Status column, in the model row, the value is most probably Updating.
The model value will change to Active when the model edition is complete (typically within 30 minutes, depending on the amount of usage analytics data to process). The model can only return recommendations when its status is Active.
For more information on Coveo ML model statuses, see the Status column reference.
-
Once the model is Active, you must associate the model with a pipeline to take advantage of the model in a search interface.
Make sure to follow the model association leading practices before associating your model with your production query pipeline.
Create a PR Model With JSON
Advanced users who are members of the Administrators and Relevance Managers built-in groups may want to create a model using a JSON configuration.
-
Access the Models page.
-
On the right-hand side of the page, click
, and then select Add model with JSON.
-
In the Add a Model With JSON panel that appears, modify the model placeholder configuration:
{ "engineId": "ecommerce", "modelName": "<MODEL_NAME>", "modelDisplayName": "<MODEL_DISPLAY_NAME>", "exportPeriod": "<EXPORT_PERIOD>", "intervalTime": <INTERVAL_TIME>, "intervalUnit": "<INTERVAL_UNIT>" }
Where:
-
modelName
(string, required) is the name of the model, which must be unique in your Coveo organization. -
modelDisplayName
(string) is the name of the model appearing on the Models page. -
exportPeriod
(ISO-8601 string, required) is the period defining the age of the usage analytics data used to build the model. Must be in the ISO8601 period format (e.g.,PyYmMwWdDThHmMsS
).Unless an
exportOffset
is specified, theexportPeriod
uses the moment when the model was generated as a base. -
intervalTime
(integer, required) is the number ofintervalUnit
(e.g.,DAY
,WEEK
, orMONTH
) between each update of the model. Must be between1
and30
inclusively. -
intervalUnit
(string enum, required) is the duration unit of the interval between each update of the model. SeeintervalTime
. Accepted values are:DAY
,WEEK
, andMONTH
.
-
-
Click Add Model.
The model now appears on the Models page.
|
Edit a PR Model JSON Configuration
-
Access the Models page.
-
Click the desired model.
-
In the Action bar, click More, and then select Edit JSON.
-
In the Edit a Model JSON Configuration panel that appears, modify the existing model configuration:
{ "modelDisplayName": "<MODEL_DISPLAY_NAME>", "exportPeriod": "<EXPORT_PERIOD>", "intervalTime": <INTERVAL_TIME>, "intervalUnit": "<INTERVAL_UNIT>", "commandLineParameters": [<ADVANCED_ML_PARAMETERS>], "commonFilter": "<COMMON_FILTER>", "customEventFilter": "<CUSTOM_EVENT_FILTER>", "exportOffset": "<EXPORT_OFF_SET>", "searchEventFilter": "<SEARCH_EVENT_FILTER>", "viewEventFilter": "<VIEW_EVENT_FILTER>" }
Where:
-
modelDisplayName
(string) is the name of the model appearing on the Models page. -
exportPeriod
(ISO-8601 string, required) is the period defining the age of the usage analytics data used to build the model. Must be in the ISO8601 period format (i.e.,PyYmMwWdDThHmMsS
).Unless an
exportOffset
is specified, theexportPeriod
uses the moment when the model was generated as a base. -
intervalTime
(integer, required) is the number ofintervalUnit
(i.e.,DAY
,WEEK
, orMONTH
) between each update of the model. Must be between1
and30
inclusively. -
intervalUnit
(string enum, required) is the duration unit of the interval between each update of the model. SeeintervalTime
. Accepted values are:DAY
,WEEK
, andMONTH
. -
commandLineParameters
(array of string) are additional parameters used to tailor the model to your use case (see Custom Model Parameters). -
commonFilter
(string) is the filter to apply to the common event dimensions (shared by all event types) in the export. Multiple filter parameters are joined with theAND
operator. -
customEventFilter
(string) is the filter to apply to the custom event dimensions in the export. Multiple filter parameters are joined with theAND
operator. -
exportOffset
(ISO-8601 string) is the offset of the usage analytics data used to build the model. Must be in the ISO8601 period format (i.e.,PyYmMwWdDThHmMsS
). The default value isPT0S
, meaning that all events are considered when building a model (theexportPeriod
is based on the moment the model was generated).EXAMPLEYou want to ignore events that occur on the current day, so you set the
exportOffset
value toP1D
. -
searchEventFilter
(string) is the filter to apply to the click and search event dimensions in the export. Multiple filter parameters are joined with theAND
operator. -
viewEventFilter
(string) is the filter to apply to the view event dimensions (shared by all event types) in the export. Multiple filter parameters are joined with theAND
operator.
-
-
Click Save to apply your changes.
Delete a PR Model
You must dissociate a model from all of the query pipelines with which it’s associated before deleting it. Models aren’t automatically dissociated from pipelines when they’re deleted. |
-
On the Models page, click the ML model that you want to delete.
-
In the Action bar, click More, and then click Delete.
-
In the Delete a Model panel that appears, click Delete model.
Review Active Model Information
On the Models page, click the desired model (must be Active), and then in the Action bar, click Open (see Reviewing Coveo Machine Learning Model Information).
Reference
"Status" Column
On the Models page of the Administration Console, the Status column indicates the current state of your Coveo ML models.
The following table lists the possible model statuses, their definitions, and their status colors as shown in the Administration Console:
Status | Definition | Status color |
---|---|---|
Active |
The model is active and available. |
Green |
Update in queue |
Waiting to process a scheduled update or configuration change. |
Green |
Updating |
The model is being rebuilt based on a new configuration. |
Green |
Waiting |
The model is in the building queue. |
Blue |
Building |
The model is currently being processed. |
Blue |
Failed |
The model couldn’t be built with the requested configuration. See Edit a PR Model for information on how to edit a model configuration. |
Red |
Update failed |
The model couldn’t be updated with the requested configuration. |
Red |
Inactive |
The model is not available. |
Gray |
Unknown |
An error prevented the model from being built successfully. |
Gray |
“Learning Interval” Section
In this section, you can modify the following:
|
For more information on Coveo ML data learning behavior, see Training and Retraining.
“Learn From” Section
The Learn From section allows you to refine the data that the model uses to make its recommendations. By narrowing down the set of data that a model uses, you can better customize relevancy for specific user groups and use cases. You can apply filters on all events, or on every event that belongs to a specific category (i.e., search, click, view, or custom events).
You want your PR model to return recommendations that pertain to a specific user group, so you add a data filter to ensure that only a specific set of analytics are used by the model for training purposes.
To add a filter:
-
Click
.
-
In the Select a dimension drop-down menu, select the dimension on which you want to base the learning of the model.
-
In the Select an operator drop-down menu, select the appropriate operator.
-
In the Select value(s) drop-down menu, add, type, or select the appropriate value.
-
Click Add Filter.
Required Privileges
By default, members of the Administrators and Relevance Managers built-in groups can view and edit elements of the Models 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 models |
Machine Learning - Models Search - Query pipelines |
View |
Edit models |
Machine Learning - Models |
Edit |
Search - Query pipelines |
View |