[TRANSLATION ERROR] There are no messages for this key

Training

When the elements (items, users, or user-item interactions) are updated, it may be desirable to perform model training, aimed at making accurate recommendations with the latest data. The training endpoint allows a model to be trained on-demand.

There are seven possible statuses for the training process:

StatusDescription
queuedThe training request has been logged, but it has not been processed yet.
processingThe training request is being processed.
canceledThe training request has been canceled at the request of the user.
errorAn error occurred while training the model. No changes have been applied.
completed_with_errorsThe training did not complete successfully. Some of the interactions could not be processed. Recommendations can be made but the output will not be optimal.
completedThe training completed successfully.
training_time_outTraining could not be conducted: free tier training time is over.

When training is requested for the first time (see Schedule Training), the API automatically assigns queued status. To check the updated status, please refer to Get Training Status.

Schedule Training

The training of the model for the given table will be scheduled.

Note: Interactions with less than 500 entries will be ignored.

URL
POST /{tableId}/train

Parameters

URL parameters:

ParameterMandatoryTypeDescription
tableIdStringID of the table

Fields to be included in the request body:

FieldMandatoryTypeDescription
engineStringEngine to perform the training: content_based, hybrid, fm, isvd, or popular.
interactionsFilterSet<String>List of interaction identifiers for training. If no filter values are present, all interactions will be trained.
configurationMap<String, Object>Training configuration.

Configuration map available parameters:

Configuration parameterMandatoryTypeDescription
beforeLongUTC timestamp (as epoch time in milliseconds) from which interactions will be taken for training
afterLongUTC timestamp (as epoch time in milliseconds) until which interactions will be taken for training
itemFilterStringRSQL expression to filter items used for training
userFilterStringRSQL expression to filter users used for training
itemAttributesSet<String>Item attributes filter to take care on training. If not set use all, an empty list to exclude all, and a set of values to only use a subset of attributes
userAttributesSet<String>User attributes filter to take care on training. If not set use all, an empty list to exclude all, and a set of values to only use a subset of attributes
popularFilterStringAn integer number or a percentage of the most popular entities (those which have more interactions) to be omitted in the training. It requires the Most Popular Recommender Engine to be trained.

Engine
A valid recommendation engine must be provided.

Example:

{
    "engine" : "content_based"
}

Example 2:

{
    "engine" : "hybrid",
    "interactionsFilter":["rating"],
    "configuration" : {
        "itemFilter" : "firstPublishDate=gt=1605135600000",
        "userFilter" : "subscribed==1",
        "after" : 1615244400000,
        "popularFilter":20,
        "itemAttributes":[],
        "userAttributes":[]
    }
}

Interactions Filter
Optional parameter to explicitly indicate a sublist of interactions to train. If no value is provided, all interactions will be trained. Only applies on interactions based recommendation engines. The interaction id must exist on the referenced table.

Example:

{
    "engine" : "hybrid",
    "interactionsFilter" : ["rating", "share"]
}

Response

CodeNameDescription
202Accepted
400Bad Request
401Unauthorized
403ForbiddenTraining time is over.
404Not Found
500Internal Server Error
503Service Unavailable

JSON that includes the ID and the status of the request.

Example
Schedule content_based training of the products table.

curl -X POST "https://recom.sherpa.ai/v2/recomm/products/train" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******" \
-d  "{\"engine\":\"content_based\"}"
{
    "requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
    "status": "queued"
}

Get Training Status

Items

Return the status of a training request.

URL
GET /{tableId}/train/{requestId}

Parameters

URL parameters:

ParameterMandatoryTypeDescription
tableIdStringID of the table
requestIdStringID returned by a training request

Response

CodeName
200OK
400Bad Request
401Unauthorized
404Not Found
429Too Many Requests
500Internal Server Error
503Service Unavailable

JSON that includes the current status of the request.

Example
Get the current status of the request 0f1105ed-9b09-42d9-a377-635ea44d2519.

curl -X GET "https://recom.sherpa.ai/v2/recomm/products/train/0f1105ed-9b09-42d9-a377-635ea44d2519" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******"
{
    "requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
    "status": "completed"
}

Cancel Training

Cancel a training request. This can only be done when the status of the request is queued.

URL
DELETE /{tableId}/train/{requestId}

Parameters

URL parameters:

ParameterMandatoryTypeDescription
tableIdStringID of the table
requestIdStringID returned by a training request

Response

CodeName
200OK
400Bad Request
401Unauthorized
404Not Found
500Internal Server Error
503Service Unavailable

JSON that includes the current status of the request.

Example
Cancel the request 0f1105ed-9b09-42d9-a377-635ea44d2519.

curl -X DELETE "https://recom.sherpa.ai/v2/recomm/products/train/0f1105ed-9b09-42d9-a377-635ea44d2519" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******"
{
    "requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
    "status": "canceled"
}