Your First Model
Shaped provides two APIs that you should be familiar with to get started:
The Model API allows you to manage your ranking models. It provides endpoints to create, list and delete your models. You can use Shaped's CLI or REST APIs to make requests.
Installing the CLI
To get started using the CLI to create a model, first install the Shaped CLI from PyPi as follows:
pip install shaped
Initialize the client
You can then initialize the shaped client with your API key. If you don't have an API key yet, check out this to get one page.
shaped init --api-key <YOUR_API_KEY>
Creating your first model
Let's say you want to build a video recommendation model and you have your event data (containing clicks and impression events) stored in BigQuery. We could imagine the video table having the following columns:
- user_id: the user triggering the interaction event.
- item_id: the video id that was interacted with.
- created_at: the timestamp of the event.
- event: the event type with values: 'click' and 'impression'
To create a model from this table you need to add your BigQuery connection details and write a select query to choose the user_id, item_id, created_at and label columns. Shaped's event label column expects numerical values, where anything greater than 0 is positive and anything less than or equal to 0 is negative. For this use-case, we'll make clicks: positive (i.e. label=1) and impressions negative (i.e. label=0). Putting it all together here's a query that would work:
- type: BigQuery
SELECT user_id, item_id, created_at, (CASE WHEN event = 'click' THEN 1 ELSE 0 END) as label
shaped create-model --file interaction_video_recommendations.yaml
The Rank API is what's used to retrieve your recommendation results. It's a real-time, high performance endpoint designed to be integrated directly into your application and supports 1000s of requests a second. Much like the Model API we provide a CLI and REST API to make rank requests. The Rank API supports several discovery endpoints and argument combinations that handle your use-case whether it be a recommendation feed, a similar items carousels or personalized search.
Here's how you can use the rank endpoint to retrieve personalized results for the user with user_id=3.
shaped rank --model_name interaction_video_recommendations --user_id 3 --limit 5
The response contains a list of "ids", which in this case is the unique identifiers for the video (item_ids) that are most relevant to this user. Because we trained the models with 'click' as the positive interaction, these videos are what we predict the user to most likely want to click next.
The response also contains a parallel list of "scores", which has the respective relevance confidence we have that this item is relevant to the query user. You can use this to get a bit more of an understanding of how the relevancy estimates change throughout the ranking.
To learn more about using and evaluating results from the rank endpoint, take a look at some of specific guides on your use-case.
Although this video recommendation model is a good starting place, there's a lot of ways we can improve it with Shaped. Notably,
- Enriching your model with user and item attribute features to improve cold-start performance.
- Creating personalized item filters that better represent your business logic.
- Real-time connectors and session-based ranking
We recommend going through the rest of our guides to find out more!