To configure a Workflow for Amazon Personalize, you will need to:

  1. Create a new workflow and set a trigger schedule.
  2. Map your data from your Redshift table to the Personalize datasets 
  3. Configure the model training parameters
  4. Deploy an API endpoint (see below)


API Deployment workflow steps are used to deploy an API endpoint as part of workflow so that the results from your Amazon Personalize models can be exposed to an end user. 


Once created, you can manage your Personalize Workflow from the Workflows screen.

For more information, see Managing and controlling Workflows


From your workflow, add an APIs step and then configure it using the following guide.


Contents


Step Configuration


Fields

Step Name

  • Only alphanumeric characters and hyphens are allowed.
  • No spaces are allowed.
  • Up to 50 characters can be entered.
  • It must start and end with a letter.


Model dropdown

Select the application step that defines trained model (solution version) that you want to deploy.

For more information, see Workflows - Application Step


Deployment Type - Automatic

The default Deployment Type is automatic.

If Automatic is selected, the API will deploy the latest trained model (solution version) providing that any specified deployment metric rules are met. These are defined in the + ADD METRIC option (see below).

If the deployment metric rules are not met:

  • The API will continue on the last successfully deployed solution version.
  • On the Workflow listing page, the system will show the last workflow run status as ‘latest deployment failed’. 

If your deployment has failed, check the deployment metrics that you have specified.


+ ADD METRIC

From here you can add rules that will define which version of your model is deployed.

Adding more rules

To add more metrics, click ADD.

If you define more than one metric rule, the system will consider it to be AND join , and not OR join.

All of the rules must be true or the system will reject the new trained solution version and continue with the last solution version. 

For more information about specifying metrics for your application, refer to: Amazon Personalize: Configuring a Workflow Overview


Deployment Type - Manual

The default Deployment Type is automatic.

With Manual deployment, you can choose a specific solution version to deploy.

The Solution Versions drop-down shows all of the different versions of the selected model.


Minimum TPS Required

Transactions per second (TPS) is the throughput and unit of billing for Amazon Personalize.

From here you can define the minimum expected TPS so that you can manage both the fluctuating traffic and the cost.


Dependency

This lists all of the other steps within the workflow.

Select any steps that must be successfully run before this step can run.


Advanced Configuration (Optional)

From here you can define optional advanced configuration options for your API endpoint:

For more details, see below.


API Advanced Configuration 

You can only choose parameters that are allowed for the selected recipe.

You can add a maximum of 10 custom parameters in addition to the pre-defined Amazon Personalized campaign configuration parameters. 


Recipe Hyperparameters

Name

Description

Algorithm hyperparameters

hidden_dimension

The number of hidden variables used in the model. Hidden variables recreate users' purchase history and item statistics to generate ranking scores. Specify a greater number of hidden dimensions when your Interactions dataset includes more complicated patterns. Using more hidden dimensions requires a larger dataset and more time to process. To decide on the best value, use HPO. 

  • Default value: 149

  • Range: [32, 256]

  • Value type: Integer

  • HPO tunable: Yes

bptt

Determines whether to use the back-propagation through time technique. Back-propagation through time is a technique that updates weights in recurrent neural network-based algorithms. Use bptt for long-term credits to connect delayed rewards to early events. For example, a delayed reward can be a purchase made after several clicks. An early event can be an initial click. Even within the same event types, such as a click, it’s a good idea to consider long-term effects and maximize the total rewards. To consider long-term effects, use larger bptt values. Using a larger bptt value requires larger datasets and more time to process.

  • Default value: 32

  • Range: [2, 32]

  • Value type: Integer

  • HPO tunable: Yes

recency_mask

Determines whether the model should consider the latest popularity trends in the Interactions dataset. Latest popularity trends might include sudden changes in the underlying patterns of interaction events. To train a model that places more weight on recent events, set recency_mask to true. To train a model that equally weighs all past interactions, set recency_mask to false. To get good recommendations using an equal weight, you might need a larger training dataset.

  • Default value: True

  • Range: True or False

  • Value type: Boolean

  • HPO tunable: Yes

Featurization hyperparameters

min_user_history_length_percentile

The minimum percentile of user history lengths to include in model training. History length is the total amount of data about a user. Use min_user_history_length_percentile to exclude a percentage of users with short history lengths. Users with a short history often show patterns based on item popularity instead of the user's personal needs or wants. Removing them can train models with more focus on underlying patterns in your data. Choose an appropriate value after you review user history lengths, using a histogram or similar tool. We recommend setting a value that retains the majority of users, but removes the edge cases.

For example, setting min_user_history_length_percentile to 0.05 and max_user_history_length_percentile to 0.95 includes all users except those with history lengths at the bottom or top 5%.

  • Default value: 0.0

  • Range: [0.0, 1.0]

  • Value type: Float

  • HPO tunable: No

max_user_history_length_percentile

The maximum percentile of user history lengths to include in model training. History length is the total amount of data about a user. Use max_user_history_length_percentile to exclude a percentage of users with long history lengths because data for these users tend to contain noise. For example, a robot might have a long list of automated interactions. Removing these users limits noise in training. Choose an appropriate value after you review user history lengths using a histogram or similar tool. We recommend setting a value that retains the majority of users but removes the edge cases.

For example, setting min_user_history_length_percentile to 0.05 and max_user_history_length_percentile to 0.95 includes all users except those with history lengths at the bottom or top 5%.

  • Default value: 0.99

  • Range: [0.0, 1.0]

  • Value type: Float

  • HPO tunable: No

Item exploration campaign configuration hyperparameters

exploration_weight

Determines how frequently recommendations include items with less interactions data or relevance. The closer the value is to 1.0, the more exploration. At zero, no exploration occurs and recommendations are based on current data (relevance). 

  • Default value: 0.3

  • Range: [0.0, 1.0]

  • Value type: Float

  • HPO tunable: No

exploration_item_age_cut_off

Determines items to be explored based on time frame since latest interaction. Provide the maximum item age, in days since the latest interaction, to define the scope of item exploration. The larger the value, the more items are considered during exploration. 

  • Default value: 30.0

  • Range: Positive floats

  • Value type: Float

  • HPO tunable: No


Metrics

These are used to evaluate the performance of your solution:

  • Online metrics are the empirical results you observe in your users' interactions with real-time recommendations. For example, you might record your users' click-through rate as they browse your catalog. You are responsible for generating and recording any online metrics.
  • Offline metrics are the metrics Amazon Personalize generates when you train a solution version. You can use offline metrics to evaluate the performance of the model before you create a campaign and provide recommendations. 

For more information, see Amazon Personalize: Evaluating a solution version with metrics

  

Offline Metrics Default Values

These metrics are used as a default for all Amazon Personalized recipe deployments.

Accepted Value range is 0 to 1 for all metrics, monotonically increasing.


Metric

K value

Coverage

An evaluation metric that tells you the proportion of unique items that Amazon Personalize might recommend using your model out of the total number of unique items in Interactions and Items datasets. To make sure Amazon Personalize recommends more of your items, use a model with a higher coverage score. Recipes that feature item exploration, such as User-Personalization, have higher coverage than those that don’t, such as popularity-count.

N/A

Mean reciprocal rank at 25

An evaluation metric that assesses the relevance of a model’s highest ranked recommendation. Amazon Personalize calculates this metric using the average accuracy of the model when ranking the most relevant recommendation out of the top 25 recommendations over all requests for recommendations.

This metric is useful if you're interested in the single highest ranked recommendation.

25

Normalized discounted cumulative gain (NCDG) at K

An evaluation metric that tells you about the relevance of your model’s highly ranked recommendations, where K is a sample size of 5, 10, or 25 recommendations. Amazon Personalize calculates this by assigning weight to recommendations based on their position in a ranked list, where each recommendation is discounted (given a lower weight) by a factor dependent on its position. The normalized discounted cumulative gain at K assumes that recommendations that are lower on a list are less relevant than recommendations higher on the list.

Amazon Personalize uses a weighting factor of 1/log(1 + position), where the top of the list is position 1.

This metric rewards relevant items that appear near the top of the list, because the top of a list usually draws more attention.

5/10/25

Precision at K

An evaluation metric that tells you how relevant your model’s recommendations are based on a sample size of K (5, 10, or 25) recommendations. Amazon Personalize calculates this metric based on the number of relevant recommendations out of the top K recommendations, divided by K, where K is 5, 10, or 25.

This metric rewards precise recommendation of the relevant items.

5/10/25


Publishing your Workflow

Amazon Personalize workflows can be named, saved and published in the same way as other workflows.

Once published, the workflow will appear on the Workflows page along with the status of its last run. 

For more information on this process, see What are Workflows?.


Endpoint URLs

Once your AWS Personalize workflow has been run successfully and any API Steps have been successfully deployed, the URL for each of the deployed APIs is shown in the workflow’s Info tab.


Tracking Personalize Experiments

You can track and monitor your Amazon Personalize experiments from Peak’s Model Management function. 

After your Personalize workflow has run successfully, the system fetches the offline metric for the solution version and then creates a listing in the Model management Experiments screen.


To get to the screens:

  • Click Factory > Model Management
  • Click on an experiment to view full details of the experiment and runs.


Naming Conventions

The following naming conventions are used for AWS Personalize experiments in Peak:


Experiment List Page

workflowname_Personalizedstepname

Runs Tab

The system captures the Solution Version number and AWS ARN and displays them in the RUNID column.

AWS ARN: 

arn:aws:personalize:eu-west-1:122403041129:solution/user-personalization_modelTrain 

Experiment run name: 

user-personalization_modelTrain/800f2108