Advanced ML

How to Play Advanced

This section is devoted to users that want to create their own models and adjust their parameters and functions. There are two key elements in our models:

target and output_type.

target represents what you query with and output_type is what you want returned by your query

Other elements that can be set to optimize the model are features and model_type.features define which attributes of your object the model will use, i.e. tags, name and description. The model_type (not to be confused with the model_namethat is used in the Out of the Box models discussed in the Simple ML section) defines the mathematical model used to optimise your ML model’s performance, depending on your data.

  • target is the element you want to give your model while output_type is the element you want to get back from your model.

  • features can be any combination of tags, name or description.

  • model_type is the mathematical model the prediction is based on.

When you build a Product Recommendation for Users, you give the recommender a userand get back aproduct. In this case theuser is set as thetargetand productis set as theoutput_type.

Custom Recommendation Models

Recommendation models by nature are dependant upon the transaction history you have of your customers’ purchases or behavior. You can combine the target and output_type to build any type of recommender.

We provide four recommendation models: Collaborative Filtering, Ranking, Content and Popularity. You can set these as the model_type to create a variety of recommenders.

Note that for a recommender, the target and output_type must be different elements. For Content Similarity models, they must be the same.

Examples:

  • The simple_product_recommender can also be implemented setting user as target, product as output_type and collaborative_filtering_recommender as model_type.

  • In this demo, the target is a user and the output_type is a product (or movies in this case), the model_type is ranking_recommenderand there are no features included.

Custom Similarity Models

There are two types of Similarity models; those that compare content of features and those that are based on the transaction history.

Content Similarity Models

You can create a Content Similarity model based on the features of the User or Product Building Blocks. Pick an output_type and at least one feature from tags, name and description, and set the model_name to content_similarity_model.

  • When you query a model, you will always get the output_type back, i.e., Product or User. But, you can also query the actual features of those Blocks themselves by providing those instead of an object id.

    • If you build a User Similarity model based on tags, you can query any set of tags to get users with similar tags.

Transaction Similarity Models

This model uses similarity in the same manner as the Collaborative Filtering model to return similar modules when the target module and the output_type module are different. In this case, provide a target and output_typejust like in the Recommendation Engines section, but set the model_name to transactions_similarity_model.

Examples:

  • Get similar products based on their names by setting output_type as products, model_name as similarity_model and features as name.

Model Making

These are the methods you use to create, retrieve, train and invoke your models.

To programmatically create or train AI models you need to use a service account. See Service Account section for more information.

To invoke a model, you can use the normal API Keys. See Authentication section for more information.

Create a model

Parameters
Request
Response

Body Parameters

Type

Description

model_type

string

The model type

description

string

The model description.

features

array

An array of strings with features.

target

string

What is used to query with.

output_type

string

The result of the query.

POST /ai/models HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
{
"model_type": "content_recommender",
"target": "user",
"output_type": "product",
"features": []
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {
"$oid": "5cfa49d41be8db000bc3ae79"
},
"_cls": "DataScienceBaseModel.SimilarityModel.ContentSimilarityModel.SimpleProductRecommender",
"created": {
"$date": 1559906772294
},
"modified": {
"$date": 1559912009907
},
"active": true,
"deleted": false,
"company": {
"$oid": "5cef78afa6db93000e64816c"
},
"features": [],
"live": false,
"training_status": "SUCCEEDED",
"current_version": {
"$oid": "5cfa5d671be8db000a4b2993"
},
"versions": [
{
"$oid": "5cfa5d671be8db000a4b2993"
}
],
"model_type": "content_recommender",
"target": "user",
"output_type": "product"
}

Train a model

Parameters
Request
Response

Path Parameter

Type

Description

model_id

string

The ID of the model to train.

POST /ai/models/<model-id>/train HTTP/1.1
Content-Type: application/json
Authorization: Bearer <service-account-key>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {
"$oid": "5cfa49d41be8db000bc3ae79"
},
"_cls": "DataScienceBaseModel.SimilarityModel.ContentSimilarityModel.SimpleProductRecommender",
"created": {
"$date": 1559906772294
},
"modified": {
"$date": 1559912009907
},
"active": true,
"deleted": false,
"company": {
"$oid": "5cef78afa6db93000e64816c"
},
"features": [],
"live": false,
"training_status": "SUCCEEDED",
"current_version": {
"$oid": "5cfa5d671be8db000a4b2993"
},
"versions": [
{
"$oid": "5cfa5d671be8db000a4b2993"
},
{
"$oid": "5cfa49d41be8db000bc3ae7a"
}
],
"model_type": "content_recommender",
"target": "user",
"output_type": "product"
}

Retrieve a model

Parameters
Request
Response

Path Parameter

Type

Description

model_id

string

The ID of the model to train.

GET /ai/models/<model-id> HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
{
"_id": {
"$oid": "5cfa49d41be8db000bc3ae79"
},
"_cls": "DataScienceBaseModel.SimilarityModel.ContentSimilarityModel.SimpleProductRecommender",
"created": {
"$date": 1559906772294
},
"modified": {
"$date": 1559912009907
},
"active": true,
"deleted": false,
"company": {
"$oid": "5cef78afa6db93000e64816c"
},
"features": [],
"live": false,
"training_status": "SUCCEEDED",
"current_version": {
"$oid": "5cfa5d671be8db000a4b2993"
},
"versions": [
{
"$oid": "5cfa5d671be8db000a4b2993"
},
{
"$oid": "5cfa49d41be8db000bc3ae7a"
}
],
"model_type": "content_recommender",
"target": "user",
"output_type": "product"
}

Invoke a model

When you invoke a model, you send in an array of one or more ids of the models target , for example if your model's target is User and output_type is Product, you could invoke the model with data: [<user_id>] . You would than get Products relative to that User's order history

Parameters
Request
Response

Body Parameters

Type

Description

data

array

One or more ids to invoke your model with

options

object

Options to specify how you want the result to look like

options.size

number

Number of returned items

GET /ai/models/<model-id>/invoke HTTP/1.1
Content-Type: application/json
Authorization: Bearer <jwt>
X-Builton-Api-Key: <builton-api-key>
Host: api.builton.dev
HTTP/1.1 200 OK
Content-Type: application/json
{
"result": [
{
"user": "5cef91e45070e859b9b3bdd4",
"recommendations": [
{
"product": "5cef92595070e859b9b3be7e",
"rank": 1,
"score": 0.02
},
{
"product": "5cef924c5070e859b9b3be68",
"rank": 2,
"score": 0.02
},
{
"product": "5cef92425070e859b9b3be58",
"rank": 3,
"score": 0.02
}
]
}
],
"model_name": "simple_product_recommender"
}