Boosting Promoted Items

Shaped allows you to boost items that you want to promote to your users, natively mixing in boosted items with personalized items. Shaped provides a simple interface to easily specify the set of items that you want to boost, fine-tuned control over the balance of boosting and personalization, and an option to override the number of items being boosted.

This guide explains how to specify a set of items to boost, leverage the boosting_factor parameter to control the magnitude of the boost, and modify the number of items being boosted.

Specifying Items to Boost: The `boost` Column

Shaped reserves a special boost column on the items table for boosting, similar to the label column for events. Items to be boosted are specified by having a value of boost = 1.

Controlling Boosting: The `boosting_factor` Parameter

Shaped utilizes the boosting_factor parameter to allow you to configure the magnitude of the boost. This parameter, ranging from 0 to 1, dictates the proportion of recommendations that are boosted items:

0: Ignores boosting, essentially recommending items solely based on their predicted relevance scores.
1: Maximizes boosting, recommending primarily boosted items to users before their personalized items.

Values between 0 and 1 allow you to fine-tune the magnitude of the boost, finding the optimal balance for your boosting use case.

Overriding the Number of Boosted Items

By default, Shaped will boost all items with boost = 1 if boosting_factor > 0. However, you may want to override this behavior, by having a large pool of boosted items and only promoting a fraction of them to each user.

This can be done by configuring the number of items to be retrieved by the boosted retriever -- which Shaped uses under the hood to fetch boosted items -- using the retriever_k_override option. If the number of items to boost is set to a value k that is less than the total number of items in the boosted item pool, the user will receieve a personalized boost, promoting the top k boosted items that are most relevant to the user.

Configuring Boosting

1. During Model Creation

Putting the above steps together, you can specify the items to boost with the boost column, set the default boosting_factor, and optionally set the number of boosted items to promote for your recommendation model when creating it via the Model API:

my_boosting_model.yaml
model:
    name: my_boosting_model
    inference_config:
        boosting_factor: 0.5
        # retriever_k_override:
        #    boosted: 10     
connectors:
    - type: Dataset
      id: my_file_connector
      name: my_file_connector
fetch:
    events: |
        SELECT user_id, item_id, label, created_at
        FROM my_file_connector
    items: |
        SELECT DISTINCT
        item_id,
        brand,
        CASE
            WHEN brand LIKE 'my_promoted_brand' THEN 1
            ELSE 0
        END as boost
        FROM my_file_connector

This configures the model to dedicate roughly 50% of recommendations to boosted items, and boosts all items where the brand name contains my_promoted_brand. The retriever_k_override is commented out as it is optional, but it can be uncommented to set the number of boosted items to 10. The default value is -1, which promotes all boosted items.

2. At Inference Time (Rank API)

You can override the model's default boosting_factor at inference time using the Rank API:

curl https://api.shaped.ai/v1/models/{model_name}/rank \
  -X POST \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json"
  -d '{
    "user_id": "XA123F2",
    "config": {
      "boosting_factor": 0.3
      }
    },
  }'

This example overrides the model's default boosting_factor and sets it to 0.3 for this specific ranking request, increasing the magnitude of the boost for this user in this particular context.

You can also override the number of boosted items at inference time:

curl https://api.shaped.ai/v1/models/{model_name}/rank \
  -X POST \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json"
  -d '{
    "user_id": "XA123F2",
    "config": {
      "retriever_k_override": {
        "boosted": 20
      }
    },
  }'

This example overrides the number of boosted items to 20 for this specific rank request. Currently, you cannot change the overall set of items being boosted at inference time.

Epsilon-Greedy Boosting

Under the hood, Shaped employs the Epsilon-Greedy algorithm to control the magnitude of the boost. The Epsilon-Greedy algorithm for boosting can be thought of as:

With probability epsilon (boosting_factor), recommend the user a boosted item.
With probability 1-epsilon (inverse of boosting_factor), recommend the user a personalized item.

This approach makes it easy to understand and configure how items are being boosted to users, seamlessly interleaving boosting with personalization.

Conclusion

Boosting promoted items is built directly into Shaped. By utilizing the boost column in the items table, configuring the boosting_factor parameter, and overriding the number of boosted items to retrieve, Shaped empowers you to seamlessly interleave boosting of promoted items with personalized recommendations.

Boosting Promoted Items

Specifying Items to Boost: The boost Column​

Controlling Boosting: The boosting_factor Parameter​

Overriding the Number of Boosted Items​

Configuring Boosting​

1. During Model Creation​

2. At Inference Time (Rank API)​

Epsilon-Greedy Boosting​

Conclusion​