This is the unified documentation for Retail API. This includes Recommendations AI, Retail Search, and the unified Retail console (which is applicable to both Recommendations AI and Retail Search users). To use the new console or Retail Search while they are in the restricted GA phase, submit a form here to contact Cloud sales. If you are using the v1beta version of Recommendations AI, migrate to the GA version: Migrating to the Retail API from beta.

To see documentation for only Recommendations AI and the Recommendations AI-only console, go to the How-to guides for Recommendations AI and the API reference documentation for Recommendations AI.

Creating models

This page describes how to create a new Recommendations AI model.

If you already have a recommendation model of the correct type, and you want to get predictions from it from a different location in your site, you can create a new serving configuration for it rather than creating a new model. Learn more.

Introduction

When you want to use a new recommendation type for getting predictions, you must create a new recommendation model and provide sufficient user event data for it to be trained. You create serving configurations for your new model, and when the model has finished training, request predictions from those serving configurations.

For an overview of the process of working with Retail, see Implementing a Retail solution.

Creating a recommendation model

Add a new recommendation model by using the Google Cloud Console. You can have up to 20 models per project, and up to 10 of them can be active (not paused) at any time. Learn more about pausing a model.

You can start up to 5 model operations per minute. Limited model operations include creation, deletion, pause, and resume.

Before you can create a new model, you must have met the requirements for creating a new model.

To create a new model:

  1. Go to the Retail Models page in the Google Cloud Console.

    Go to the Models page

  2. Click Create model.

  3. Enter a name for your model.

    The name must be 1024 characters or less, and can contain only alphanumeric characters, underscores, hyphens, and spaces.

  4. Choose the recommendation type you want this model to be trained to provide, and its business objective (if available for that model).

  5. Click Create to create the new recommendation model.

    If you have uploaded sufficient user event data of the required type, the initial model training and tuning begins. Initial model training and tuning takes 2-5 days to complete.

    You can create serving configurations for your new model before training completes, but they will serve only "dry run" predictions until the initial training and tuning completes and the model becomes active.

Requirements for creating a new recommendation model

The first time you use a specific recommendation type for your site, you are training a new machine learning model, which requires sufficient training data, as well as time to train and tune the model. The following steps are required to start using a new recommendation type:

  1. Import your catalog to Retail, if you haven't already, and implement processes to keep the uploaded catalog up to date.
  2. Start recording user events to Retail, if you haven't already, making sure to follow the best practices for recording user event data.
  3. Identify the recommendation type and optimization objective you want to use.
  4. Determine the user event data requirement for your desired recommendation type and objective.
  5. Import historical user event data to meet the minimum event data requirements, or wait until the user event data collection meets the minimum requirements.
  6. Create your model and your serving configurations.

    At this point, Retail initiates model training and tuning. Initial model training and tuning takes 2-5 days to complete.

  7. Confirm that your model is working correctly using prediction preview.

  8. Create your A/B experiment.

User event data requirements

The type of user events you import, and the amount of data you need, depends on your recommendation (model) type and your optimization objective. When you reach the minimum data requirement, you can begin model training.

The data collection window represents the maximum length of time the Retail API looks back for user events; importing more historical data has no effect on model quality.

Model type Optimization objective User event types Minimum data requirement Data collection window
Recommended for You Click-through rate detail-page-view
add-to-cart
purchase-complete
home-page-view

10,000 detail-page-view events that include at least 100 unique visitor IDs; and 10,000 home-page-view events.

AND

(1 week, with an average of 10 detail-page-view events per joined catalog item.

OR

60 days with at least one joined detail-page-view event.)

3 months
Recommended for You Conversion rate detail-page-view
add-to-cart
purchase-complete
home-page-view

10,000 add-to-cart events that include at least 100 unique visitor IDs; 10,000 detail-page-view events; and 10,000 home-page-view events.

AND

(1 week, with an average of 10 add-to-cart events per joined catalog item.

OR

60 days with at least one joined add-to-cart event.)

3 months
Others You May Like Click-through rate detail-page-view

10,000 detail-page-view events that include at least 100 unique visitor IDs.

AND

(1 week, with an average of 10 detail-page-view events per joined catalog item.

OR

60 days with at least one joined detail-page-view event.)

3 months
Others You May Like Conversion rate add-to-cart
detail-page-view

10,000 add-to-cart events that include at least 100 unique visitor IDs; and 10,000 detail-page-view events.

AND

(1 week, with an average of 10 add-to-cart events per joined catalog item.

OR

60 days with at least one joined add-to-cart event.)

3 months
Frequently Bought Together Any purchase-complete
detail-page-view

1000 purchase events that include at least 100 unique visitor IDs.

AND

(An average of 10 purchase-complete events per joined catalog item.

OR

90 days of purchase-complete events.)

12 months
Similar Items Click-through rate None required.

At least 100 in-stock product SKUs must be present in catalog branch 0. No user events are required.

N/A

What's next