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:
Status | Description |
---|---|
queued | The training request has been logged, but it has not been processed yet. |
processing | The training request is being processed. |
canceled | The training request has been canceled at the request of the user. |
error | An error occurred while training the model. No changes have been applied. |
completed_with_errors | The training did not complete successfully. Some of the interactions could not be processed. Recommendations can be made but the output will not be optimal. |
completed | The training completed successfully. |
training_time_out | Training 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:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
Fields to be included in the request body:
Field | Mandatory | Type | Description |
---|---|---|---|
engine | ✓ | String | Engine to perform the training: content_based or hybrid. |
interactionsFilter | Set<String> | List of interaction identifiers for training. If no filter values are present, all interactions will be trained. | |
configuration | Map<String, Object> | Training configuration. |
Configuration map available parameters:
Configuration parameter | Mandatory | Type | Description |
---|---|---|---|
before | Long | Timestamp from which interactions will be taken for training | |
after | Long | Timestamp until which interactions will be taken for training | |
itemFilter | String | RSQL expression to filter items used for training | |
userFilter | String | RSQL expression to filter users used for training | |
itemAttributes | Set<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 | |
userAttributes | Set<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 | |
popularFilter | String | An integer number or a percentage of the most popular entities (those which have more interactions) to be omitted in the training |
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
Code | Name | Description |
---|---|---|
202 | Accepted | |
400 | Bad Request | |
401 | Unauthorized | |
403 | Forbidden | Training time is over. |
404 | Not Found | |
500 | Internal Server Error | |
503 | Service 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:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
requestId | ✓ | String | ID returned by a training request |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
429 | Too Many Requests |
500 | Internal Server Error |
503 | Service 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:
Parameter | Mandatory | Type | Description |
---|---|---|---|
tableId | ✓ | String | ID of the table |
requestId | ✓ | String | ID returned by a training request |
Response
Code | Name |
---|---|
200 | OK |
400 | Bad Request |
401 | Unauthorized |
404 | Not Found |
500 | Internal Server Error |
503 | Service 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"
}