# Choosing a recipe
When you create a custom solution, you specify a recipe and configure training parameters. *Recipes* are Amazon Personalize algorithms that are prepared for specific use cases. Amazon Personalize provides recipes, based on common use cases, for training models. When you create a solution version for the solution, Amazon Personalize trains the models backing the solution version based on the recipe and training configuration.
Amazon Personalize recipes use the following during training:
+ Predefined attributes of your data
+ Predefined feature transformations
+ Predefined algorithms
+ Initial parameter settings for the algorithms
To optimize your model, you can override many of these parameters when you create a solution. For more information, see [Hyperparameters and HPO](customizing-solution-config-hpo.md).
**Topics**
+ [Amazon Personalize recipe types by use case](#use-cases)
+ [Amazon Personalize recipes](#recipe-categories)
+ [Viewing available Amazon Personalize recipes](#listing-recipes)
+ [User-Personalization-v2 recipe](native-recipe-user-personalization-v2.md)
+ [User-Personalization recipe](native-recipe-new-item-USER_PERSONALIZATION.md)
+ [Trending-Now recipe](native-recipe-trending-now.md)
+ [Popularity-Count recipe](native-recipe-popularity.md)
+ [Personalized-Ranking-v2 recipe](native-recipe-personalized-ranking-v2.md)
+ [Personalized-Ranking recipe](native-recipe-search.md)
+ [Semantic-Similarity recipe](native-recipe-semantic-similarity.md)
+ [Similar-Items recipe](native-recipe-similar-items.md)
+ [SIMS recipe](native-recipe-sims.md)
+ [Next-Best-Action recipe](native-recipe-next-best-action.md)
+ [Item-Affinity recipe](item-affinity-recipe.md)
+ [Item-Attribute-Affinity recipe](item-attribute-affinity-recipe.md)
+ [Legacy HRNN recipes](legacy-user-personalization-recipes.md)
## Amazon Personalize recipe types by use case
To choose your recipe, first choose your use case from the following and note its corresponding recipe type.
+ Recommending items for users (USER\$1PERSONALIZATION recipes)
To provide personalized recommendations for your users, train your model with a USER\$1PERSONALIZATION recipe. Personalized recommendations help drive better engagement and conversion.
+ Ranking items for a user (PERSONALIZED\$1RANKING recipes)
To personalize the order of curated lists or search results for your users, train your model with a PERSONALIZED\$1RANKING recipe. PERSONALIZED\$1RANKING recipes create a personalized list by re-ranking a collection of input items based on predicted interest level for a given user. Personalized lists improve the customer experience and increase customer loyalty and engagement.
+ Recommending trending or popular items (POPULAR\$1ITEMS recipes)
To recommend trending or popular items use a POPULAR\$1ITEMS recipe. You might use a POPULAR\$1ITEMS if your customers highly value what other users are interacting with. Common uses include recommending viral social media content, breaking news articles, or recent sports videos.
+ Recommending similar items (RELATED\$1ITEMS recipes)
To recommend similar items, such as items frequently bought together or movies that other users have also watched, you should use a RELATED\$1ITEMS recipe. Recommending similar items can help your customers discover items and can increase user conversion rate.
+ Recommending the next best action (PERSONALIZED\$1ACTIONS recipes)
To recommend the next best action for your users in real time, such as signing up for your loyalty program or applying for a credit card, you should use a PERSONALIZED\$1ACTIONS recipe. Recommending the next best action can increase customer loyalty, generate more revenue, and improve your users' experience.
+ Getting user segments (USER\$1SEGMENTATION recipes)
To get segments of users based on item input data, such as users who will most likely interact with items with a certain attribute, you should use a USER\$1SEGMENTATION recipe. Getting user segments can help you create advanced marketing campaigns that promote different items to different user segments based on the likelihood that they will take an action.
## Amazon Personalize recipes
Amazon Personalize provides the following types of recipes. Besides behavioral differences, each type has different requirements for getting recommendations, as shown in the following table.
| Recipe type | Recipes | API | API requirements |
| --- | --- | --- | --- |
| USER\$1PERSONALIZATION | [User-Personalization-v2](native-recipe-user-personalization-v2.md) [User-Personalization](native-recipe-new-item-USER_PERSONALIZATION.md) [HRNN recipe (legacy)](native-recipe-hrnn.md) [HRNN-Metadata recipe (legacy)](native-recipe-hrnn-metadata.md) [HRNN-Coldstart recipe (legacy)](native-recipe-hrnn-coldstart.md) | [GetRecommendations](API_RS_GetRecommendations.md) | `userId`: Required `itemId`: Not used `inputList`: NA |
| POPULAR\$1ITEMS | [Trending-Now](native-recipe-trending-now.md) [Popularity-Count](native-recipe-popularity.md) | [GetRecommendations](API_RS_GetRecommendations.md) | `userId`: Required only if you apply a filter that requires it `itemId`: Not used `inputList`: NA |
| PERSONALIZED\$1RANKING | [Personalized-Ranking-v2](native-recipe-personalized-ranking-v2.md) [Personalized-Ranking](native-recipe-search.md) | [GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md) | `userId`: Required `itemId`: NA `inputList`: list of itemId's |
| RELATED\$1ITEMS | [Similar-Items](native-recipe-similar-items.md) [SIMS](native-recipe-sims.md) [Semantic-Similarity recipe](native-recipe-semantic-similarity.md) | [GetRecommendations](API_RS_GetRecommendations.md) | `userId`: Required only if you apply a filter that requires it `itemId`: Required `inputList`: NA |
| PERSONALIZED\$1ACTIONS | [Next-Best-Action](native-recipe-next-best-action.md) | [GetActionRecommendations](API_RS_GetActionRecommendations.md) | `userId`: Required `actionId`: Not used `itemId`: Not used `inputList`: NA |
| USER\$1SEGMENTATION | [Item-Affinity](item-affinity-recipe.md) [Item-Attribute-Affinity](item-attribute-affinity-recipe.md) | [CreateBatchSegmentJob](API_CreateBatchSegmentJob.md) | For batch workflow requirements, see [Getting user segments with a batch segment job](creating-batch-seg-job.md). |
## Viewing available Amazon Personalize recipes
To see a list of available recipes:
+ In the Amazon Personalize console, choose a dataset group. From the navigation pane, choose **Solutions and recipes**, and choose the **Recipes** tab.
+ With the AWS SDK for Python (Boto3), call the [ListRecipes](API_ListRecipes.md) API.
+ With the AWS CLI, use the following command.
```
aws personalize list-recipes
```
To get information about a recipe using the SDK for Python (Boto3), call the [DescribeRecipe](API_DescribeRecipe.md) API. To get information about a recipe using the AWS CLI, use the following command.
```
aws personalize describe-recipe --recipe-arn recipe_arn
```
# User-Personalization-v2 recipe
The User-Personalization-v2 (aws-user-personalization-v2) recipe recommends items a user will interact with based on their preferences. For example, you might use User-Personalization-v2 to generate personalized movie recommendations for a streaming app, or personalized product recommendations for a retail app. Other use cases include generating real-time recommendations for a news site or batch recommendations for a personalized marketing campaign.
User-Personalization-v2 can train on up to 5 million items from Item interactions and Items datasets. And it generates more relevant recommendations with lower latency than [User-Personalization](native-recipe-new-item-USER_PERSONALIZATION.md).
Because User-Personalization-v2 recommends the most relevant items to users based on your data, it more frequently recommends existing items with interactions data. To make sure recommendations include new items, you can use a promotion that includes some items based on creation timestamp. For more information about promotions, see [Promoting items in real-time recommendations](promoting-items.md).
This recipe uses a transformer-based architecture to train a model that learns context and tracks relationships and patterns in your data. *Transformers* are a type of neural network architecture that transforms or changes an input sequence into an output sequence. For Amazon Personalize, the input sequence is a user's item interaction history in your data. The output sequence is their personalized recommendations. For more information about transformers, see [What Are Transformers In Artificial Intelligence?](https://aws.amazon.com/what-is/transformers-in-artificial-intelligence/) in the AWS Cloud Computing Concepts Hub.
User-Personalization-v2 uses a different pricing model than other recipes. For more information about pricing, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).
**Topics**
+ [Recipe features](#user-personalization-v2-features)
+ [Required and optional datasets](#user-personalization-v2-datasets)
+ [Properties and hyperparameters](#user-personalization-v2-hyperparameters)
## Recipe features
User-Personalization-v2 uses the following Amazon Personalize recipe features when generating item recommendations:
+ Real-time personalization – With real-time personalization, Amazon Personalize updates and adapts item recommendations according to a user's evolving interest. For more information, see [Real-time personalization](use-case-recipe-features.md#about-real-time-personalization).
+ Exploration – With exploration, recommendations include items with less interactions data or relevance to the user. With User-Personalization-v2, Amazon Personalize handles exploration configuration for you. To make sure recommendations include new items, you can use promotions to include new items based on their creation timestamp. For more information about promotions, see [Promoting items in real-time recommendations](promoting-items.md).
+ Automatic updates – With automatic updates, Amazon Personalize automatically updates the latest model (solution version) every two hours to consider new items for recommendations. For more information, see [Automatic updates](use-case-recipe-features.md#automatic-updates).
+ Metadata with recommendations – With the User-Personalization-v2 recipe, if you have an Items dataset with at minimum one column of metadata, campaigns automatically have the option to include item metadata with recommendation results. You don't have manually enable metadata for your campaign. You might use metadata to enrich recommendations in your user interface, such as adding the genres for movies to carousels. For more information, see [Item metadata in recommendations](campaigns.md#create-campaign-return-metadata).
## Required and optional datasets
To use the User-Personalization-v2, you must create an Item interactions dataset and import at minimum 1000 item interactions. Amazon Personalize generates recommendations primarily based on item interaction data. For more information, see [Item interaction data](interactions-datasets.md). User-Personalization-v2 can train on up to 5 million items across Item interactions and Items datasets.
With User-Personalization-v2, Amazon Personalize can use Item interactions data that includes the following:
+ Event type and event value data – Amazon Personalize uses event type data, such as click or watch event types, to identify user intent and interest through any patterns in their behavior. Also, you can use event type and event value data to filter records before training. For more information, see [Event type and event value data](interactions-datasets.md#event-type-and-event-value-data).
**Note**
With User-Personalization-v2, your training cost is based on your interactions data before filtering by event type or value. For more information about pricing, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).
+ Contextual metadata – Contextual metadata is interactions data you collect on the user's environment at the time of an event, such as their location or device type. For more information, see [Contextual metadata](interactions-datasets.md#interactions-contextual-metadata).
The following datasets are optional and can improve recommendations:
+ Users dataset – Amazon Personalize can use data in your Users dataset to better understand your users and their interests. You can also use data in a Users dataset to filter recommendations. For information about the user data you can import, see [User metadata](users-datasets.md).
+ Items dataset – Amazon Personalize can use data in your Items dataset to identify connections and patterns in their behavior. This helps Amazon Personalize understand your users and their interests. You can also use data in a Items dataset to filter recommendations. For information about the item data you can import, see [Item metadata](items-datasets.md).
## Properties and hyperparameters
The User-Personalization-v2 recipe has the following properties:
+ **Name** – `aws-user-personalization-v2`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-user-personalization-v2`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-user-personalization-v2`
For more information, see [Choosing a recipe](working-with-predefined-recipes.md).
The following table describes the hyperparameters for the User-Personalization-v2 recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. The process of choosing the best value for a hyperparameter is called hyperparameter optimization (HPO). With User-Personalization-v2, if you turn on automatic training, Amazon Personalize automatically performs HPO every 90 days. Without automatic training, no HPO occurs.
The table provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
| Name | Description |
| --- | --- |
| Algorithm hyperparameters |
| apply\$1recency\$1bias | Determines whether the model should give more weight to the most recent item interactions data in your Item interactions dataset. The most recent interactions data might include sudden changes in the underlying patterns of interaction events. To train a model that places more weight on recent events, set `apply_recency_bias` to `true`. To train a model that equally weighs all past interactions, set `apply_recency_bias` to `false`. Default value: `true` Range: `true` or `false` Value type: Boolean HPO tunable: No |
# User-Personalization recipe
**Important**
We recommend using the [User-Personalization-v2](native-recipe-user-personalization-v2.md) recipe. It can consider up to 5 million items with faster training, and generate more relevant recommendations with lower latency.
The User-Personalization (aws-user-personalization) recipe is optimized for all personalized recommendation scenarios. It predicts the items that a user will most likely interact with. You might use User-Personalization to generate personalized movie recommendations for a streaming app or personalized product recommendations for a retail app.
With User-Personalization, Amazon Personalize generates recommendations primarily based on user item interaction data in an Item interactions dataset. It can also use any item and user metadata in your Items and Users datasets. For more information about the data it uses, see [Required and optional datasets](#user-personalization-datasets).
**Topics**
+ [Recipe features](#user-personalization-features)
+ [Required and optional datasets](#user-personalization-datasets)
+ [Properties and hyperparameters](#bandit-hyperparameters)
+ [Training with the User-Personalization recipe (console)](#training-user-personalization-recipe-console)
+ [Training with the User-Personalization recipe (Python SDK)](#training-user-personalization-recipe)
+ [Getting recommendations and recording impressions (SDK for Python (Boto3))](#user-personalization-get-recommendations-recording-impressions)
+ [Sample Jupyter notebook](#bandits-sample-notebooks)
## Recipe features
User-Personalization uses the following Amazon Personalize recipe features when generating item recommendations:
+ Real-time personalization – With real-time personalization, Amazon Personalize updates and adapts item recommendations according to a user's evolving interest. For more information, see [Real-time personalization](use-case-recipe-features.md#about-real-time-personalization).
+ Exploration – With exploration, recommendations include new items or items with less interactions data. This improves item discovery and engagement when you have a fast-changing catalog, or when new items, such as news articles or promotions, are more relevant to users when fresh. For more information about exploration, see [Exploration](use-case-recipe-features.md#about-exploration).
+ Automatic updates – With automatic updates, Amazon Personalize automatically updates the latest model (solution version) every two hours to consider new items for recommendations. For more information, see [Automatic updates](use-case-recipe-features.md#automatic-updates).
## Required and optional datasets
To use the User-Personalization, you must create an [Item interactions dataset](interactions-datasets.md) and import at minimum 1000 item interactions. Amazon Personalize generates recommendations primarily based on item interaction data.
With User-Personalization, Amazon Personalize can use Item interactions data that includes the following:
+ Event type and event value data – Amazon Personalize uses event type data, such as click or watch event types, to identify user intent and interest through any patterns in their behavior. Also, you can use event type and event value data to filter records before training. For more information, see [Event type and event value data](interactions-datasets.md#event-type-and-event-value-data).
+ Contextual metadata – Contextual metadata is interactions data you collect on the user's environment at the time of an event, such as their location or device type. For more information, see [Contextual metadata](interactions-datasets.md#interactions-contextual-metadata).
+ Impressions data – Impressions are lists of items that were visible to a user when they interacted with (clicked, watched, purchased, and so on) a particular item. For more information, see [Impressions data](interactions-datasets.md#interactions-impressions-data).
The following datasets are optional and can improve recommendations:
+ Users dataset – Amazon Personalize can use data in your Users dataset to better understand your users and their interests. You can also use data in a Users dataset to filter recommendations. For information about the user data you can import, see [User metadata](users-datasets.md).
+ Items dataset – Amazon Personalize can use data in your Items dataset to identify connections and patterns in their behavior. This helps Amazon Personalize understand your users and their interests. You can also use data in a Items dataset to filter recommendations. For information about the item data you can import, see [Item metadata](items-datasets.md).
## Properties and hyperparameters
The User-Personalization recipe has the following properties:
+ **Name** – `aws-user-personalization`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-user-personalization`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-user-personalization`
For more information, see [Choosing a recipe](working-with-predefined-recipes.md).
The following table describes the hyperparameters for the User-Personalization recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. Featurization hyperparameters control how to filter the data to use in training. The process of choosing the best value for a hyperparameter is called hyperparameter optimization (HPO). For more information, see [Hyperparameters and HPO](customizing-solution-config-hpo.md).
The table provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
+ **HPO tunable**: Can the parameter participate in HPO?
| Name | Description |
| --- | --- |
| Algorithm hyperparameters |
| hidden\$1dimension | 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 Item 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. To use HPO, set `performHPO` to `true` when you call [CreateSolution](API_CreateSolution.md) and [CreateSolutionVersion](API_CreateSolutionVersion.md) operations. 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\$1mask | Determines whether the model should consider the latest popularity trends in the Item 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\$1user\$1history\$1length\$1percentile | 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\$1user\$1history\$1length\$1percentile | 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\$1weight | Determines how frequently recommendations include items with less item interaction 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). For more information see [CampaignConfig](API_CampaignConfig.md). Default value: 0.3 Range: [0.0, 1.0] Value type: Float HPO tunable: No |
| exploration\$1item\$1age\$1cut\$1off | Specify the maximum item age in days since the latest interaction across all items in the Item interactions dataset. This defines the scope of item exploration based on item age. Amazon Personalize determines an item's age based on its creation timestamp or, if creation timestamp data is missing, item interaction data. For more information how Amazon Personalize determines an item's age, see [Creation timestamp data](items-datasets.md#creation-timestamp-data). To increase the items Amazon Personalize considers during exploration, enter a greater value. The minimum is 1 day and the default is 30 days. Recommendations might include items that are older than the item age cut off you specify. This is because these items are relevant to the user and exploration didn't identify them. Default value: 30.0 Range: Positive floats Value type: Float HPO tunable: No |
## Training with the User-Personalization recipe (console)
To use the User-Personalization recipe to generate recommendations in the console, first train a new solution version using the recipe. Then deploy a campaign using the solution version and use the campaign to get recommendations.
**Training a new solution version with the User-Personalization recipe (console)**
1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home) and sign into your account.
1. Create a Custom dataset group with a new schema and upload your dataset with impressions data. Optionally include [CREATION\$1TIMESTAMP]() and [Unstructured text metadata](items-datasets.md#text-data) data in your Items dataset so Amazon Personalize can more accurately calculate the age of an item and identify cold items.
For more information on importing data, see [Importing training data into Amazon Personalize datasets](import-data.md).
1. On the **Dataset groups** page, choose the new dataset group that contains the dataset or datasets with impressions data.
1. In the navigation pane, choose **Solutions and recipes** and choose **Create solution**.
1. On the **Create solution** page, for the **Solution name**, enter the name of your new solution.
1. For **Solution type**, choose **Item recommendation** to get item recommendations for your users.
1. For **Recipe**, choose **aws-user-personalization**. The **Solution configuration** section appears providing several configuration options.
1. In **Event configuration**, if your Item interactions dataset has EVENT\$1TYPE or both EVENT\$1TYPE and EVENT\$1VALUE columns, optionally use the **Event type** and **Event value threshold** fields to choose the item interactions data that Amazon Personalize uses when training the model. For more information, see [Choosing the item interaction data used for training](event-values-types.md).
If you have multiple event types and use the User-Personalization-v2 recipe or Personalized-Ranking-v2 recipe, you can also specify different weights for different types. For example, you can configure a solution to give more weight to purchase events than click events. For more information, see [Optimizing a solution with events configuration](optimizing-solution-events-config.md).
1. Optionally configure hyperparameters for your solution. For a list of User-Personalization recipe properties and hyperparameters, see [Properties and hyperparameters](#bandit-hyperparameters).
1. Choose **Create and train solution** to start training. The **Dashboard** page displays.
You can navigate to the solution details page to track training progress in the **Solution versions** section. When training is complete, the status is **Active**.
**Creating a campaign and getting recommendations (console)**
When your solution version status is **Active** you are ready to create your campaign and get recommendations as follows:
1. On either the solution details page or the **Campaigns** page, choose **Create new campaign**.
1. On the **Create new campaign** page, for **Campaign details**, provide the following information:
+ **Campaign name:** Enter the name of the campaign. The text you enter here appears on the Campaign dashboard and details page.
+ **Solution:** Choose the solution that you just created.
+ **Solution version ID:** Choose the ID of the solution version that you just created.
+ **Minimum provisioned transactions per second:** Set the minimum provisioned transactions per second that Amazon Personalize supports. For more information, see the [CreateCampaign](API_CreateCampaign.md) operation.
1. For **Campaign configuration**, provide the following information:
+ **Exploration weight:** Configure how much to explore, where recommendations include items with less item interaction data or relevance more frequently the more exploration you specify. The closer the value is to 1, the more exploration. At zero, no exploration occurs and recommendations are based on current data (relevance).
+ **Exploration item age cut off**: Enter the maximum item age, in days since the latest interaction, to define the scope of item exploration. To increase the number of items Amazon Personalize considers during exploration, enter a greater value.
For example, if you enter 10, only items with item interaction data from the 10 days since the latest interaction in the dataset are considered during exploration.
**Note**
Recommendations might include items without item interaction data from outside this time frame. This is because these items are relevant to the user's interests, and exploration wasn't required to identify them.
1. Choose **Create campaign**.
1. On the campaign details page, when the campaign status is **Active**, you can use the campaign to get recommendations and record impressions. For more information, see [Step 5: Get recommendations](getting-started-console.md#getting-started-console-get-recommendations) in "Getting Started."
Amazon Personalize automatically updates your latest solution version every two hours to include new data. Your campaign automatically uses the updated solution version. For more information, see [Automatic updates](use-case-recipe-features.md#automatic-updates).
To manually update the campaign, you first create and train a new solution version using the console or the [CreateSolutionVersion](API_CreateSolutionVersion.md) operation, with `trainingMode` set to `update`. You then manually update the campaign on the **Campaign** page of the console or by using the [UpdateCampaign](API_UpdateCampaign.md) operation.
**Note**
Amazon Personalize doesn't automatically update solution versions you created before November 17, 2020.
## Training with the User-Personalization recipe (Python SDK)
When you have created a dataset group and uploaded your dataset(s) with impressions data, you can train a solution with the User-Personalization recipe. Optionally include [CREATION\$1TIMESTAMP]() and [Unstructured text metadata](items-datasets.md#text-data) data in your Items dataset so Amazon Personalize can more accurately calculate the age of an item and identify cold items. For more information on creating dataset groups and uploading training data see [Creating schema JSON files for Amazon Personalize schemas](how-it-works-dataset-schema.md).
**To train a solution with the User-Personalization recipe using the AWS SDK**
1. Create a new solution using the `create_solution` method.
Replace `solution name` with your solution name and `dataset group arn` with the Amazon Resource Name (ARN) of your dataset group.
```
import boto3
personalize = boto3.client('personalize')
print('Creating solution')
create_solution_response = personalize.create_solution(name = 'solution name',
recipeArn = 'arn:aws:personalize:::recipe/aws-user-personalization',
datasetGroupArn = 'dataset group arn',
)
solution_arn = create_solution_response['solutionArn']
print('solution_arn: ', solution_arn)
```
For a list of aws-user-personalization recipe properties and hyperparameters, see [Properties and hyperparameters](#bandit-hyperparameters).
1. Create a new *solution version* with the updated training data and set `trainingMode` to `FULL` using the following code snippet. Replace the `solution arn` with the ARN of your solution.
```
import boto3
personalize = boto3.client('personalize')
create_solution_version_response = personalize.create_solution_version(solutionArn = 'solution arn',
trainingMode='FULL')
new_solution_version_arn = create_solution_version_response['solutionVersionArn']
print('solution_version_arn:', new_solution_version_arn)
```
1. When Amazon Personalize is finished creating your solution version, create your campaign with the following parameters:
+ Provide a new `campaign name` and the `solution version arn` generated in step 2.
+ Modify the `explorationWeight` item exploration configuration hyperparameter to configure how much to explore. Items with less item interaction data or relevance are recommended more frequently the closer the value is to 1.0. The default value is 0.3.
+ Modify the `explorationItemAgeCutOff` item exploration configuration hyperparameter parameter to provide the maximum duration, in days relative to the latest interaction, for which items should be explored. The larger the value, the more items are considered during exploration.
Use the following Python snippet to create a new campaign with an emphasis on exploration with exploration cut-off at 30 days. Creating a campaign usually takes a few minutes but can take over an hour.
```
import boto3
personalize = boto3.client('personalize')
create_campaign_response = personalize.create_campaign(
name = 'campaign name',
solutionVersionArn = 'solution version arn',
minProvisionedTPS = 1,
campaignConfig = {"itemExplorationConfig": {"explorationWeight": "0.3", "explorationItemAgeCutOff": "30"}}
)
campaign_arn = create_campaign_response['campaignArn']
print('campaign_arn:', campaign_arn)
```
With User-Personalization, Amazon Personalize automatically updates your solution version every two hours to include new data. Your campaign automatically uses the updated solution version. For more information, see [Automatic updates](use-case-recipe-features.md#automatic-updates).
To manually update the campaign, you first create and train a new solution version using the console or the [CreateSolutionVersion](API_CreateSolutionVersion.md) operation, with `trainingMode` set to `update`. You then manually update the campaign on the **Campaign** page of the console or by using the [UpdateCampaign](API_UpdateCampaign.md) operation.
**Note**
Amazon Personalize doesn't automatically update solution versions you created before November 17, 2020.
## Getting recommendations and recording impressions (SDK for Python (Boto3))
When your campaign is created, you can use it to get recommendations for a user and record impressions. For information on getting batch recommendations using the AWS SDKs see [Creating a batch inference job (AWS SDKs)](creating-batch-inference-job.md#batch-sdk).
**To get recommendations and record impressions**
1. Call the `get_recommendations` method. Change the `campaign arn` to the ARN of your new campaign and `user id` to the userId of the user.
```
import boto3
rec_response = personalize_runtime.get_recommendations(campaignArn = 'campaign arn', userId = 'user id')
print(rec_response['recommendationId'])
```
1. Create a new event tracker for sending PutEvents requests. Replace `event tracker name` with the name of your event tracker and `dataset group arn` with the ARN of your dataset group.
```
import boto3
personalize = boto3.client('personalize')
event_tracker_response = personalize.create_event_tracker(
name = 'event tracker name',
datasetGroupArn = 'dataset group arn'
)
event_tracker_arn = event_tracker_response['eventTrackerArn']
event_tracking_id = event_tracker_response['trackingId']
print('eventTrackerArn:{},\n eventTrackingId:{}'.format(event_tracker_arn, event_tracking_id))
```
1. Use the `recommendationId` from step 1 and the `event tracking id` from step 2 to create a new `PutEvents` request. This request logs the new impression data from the user’s session. Change the `user id` to the ID of the user.
```
import boto3
personalize_events.put_events(
trackingId = 'event tracking id',
userId= 'user id',
sessionId = '1',
eventList = [{
'sentAt': datetime.now().timestamp(),
'eventType' : 'click',
'itemId' : rec_response['itemList'][0]['itemId'],
'recommendationId': rec_response['recommendationId'],
'impression': [item['itemId'] for item in rec_response['itemList']],
}]
)
```
## Sample Jupyter notebook
For a sample Jupyter notebook that shows how to use the User-Personalization recipe, see [User Personalization with Exploration](https://github.com/aws-samples/amazon-personalize-samples/blob/master/next_steps/core_use_cases/user_personalization/user-personalization-with-exploration.ipynb).
# Trending-Now recipe
The Trending-Now recipe (aws-trending-now) generates recommendations for items that are rapidly becoming more popular with your users. You might use the Trending-Now recipe if items gaining in popularity are more relevant to your customers. For example, your customers might highly value what other users are interacting with. Common uses include recommending viral social media content, breaking news articles, or recent sports videos.
Trending-Now automatically identifies the top trending items by calculating the increase in interactions that each item has over configurable intervals of time. The items with highest rate of increase are considered trending items. The time is based on timestamp data in your Item interactions dataset. The items considered come from the interactions data you imported in bulk and incrementally. You don't have to manually create a new solution version for Trending-Now to consider new items in interactions data.
You can specify the time interval by providing a `Trend discovery frequency` when you create your solution. For example, if you specify `30 minutes` for `Trend discovery frequency`, for every 30 minutes of data, Amazon Personalize identifies the items with the greatest rate of increase in interactions since the last evaluation. Possible frequencies include 30 minutes, 1 hour, 3 hours, and 1 day. Choose a frequency that aligns with the distribution of your interactions data. Missing data over the interval you choose can reduce recommendation accuracy. If you import zero interactions over the last two time intervals, Amazon Personalize recommends only popular items instead of trending items.
With Trending-Now, you call the [GetRecommendations](API_RS_GetRecommendations.md) operation or get recommendations on the **Test campaign** page of the Amazon Personalize console. Amazon Personalize returns the top trending items. You pass a `userId` in your request only if you apply a filter that requires it. With the GetRecommendations API, you can configure the number of trending items returned with the `numResults` parameter. You can't get batch recommendations with the Trending-Now recipe.
To use Trending-Now, you must create an Item interactions dataset with at least 1000 unique historical and event interactions combined (after filtering by eventType and eventValueThreshold, if provided). When generating trending item recommendations, Trending-Now doesn't use data in Items or Users datasets. However, you can still filter recommendations based on data in these datasets. For more information, see [Filtering recommendations and user segments](filter.md).
**Topics**
+ [Properties and hyperparameters](#trending-now-hyperparameters)
+ [Creating a solution (SDK for Python (Boto3))](#trending-now-python)
+ [Sample Jupyter notebook](#trending-now-sample-notebooks)
## Properties and hyperparameters
The Trending-Now recipe has the following properties:
+ **Name** – `aws-trending-now`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-trending-now`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-trending-now-custom`
For more information, see [Choosing a recipe](working-with-predefined-recipes.md).
The following table describes the hyperparameters for the Trending-Now recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. The process of choosing the best value for a hyperparameter is called hyperparameter optimization (HPO). For more information, see [Hyperparameters and HPO](customizing-solution-config-hpo.md).
The table also provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
+ **HPO tunable**: Can the parameter participate in HPO?
| Name | Description |
| --- | --- |
| Feature transformation hyperparameters |
| Trend discovery frequency | Specify how often Amazon Personalize evaluates your interactions data and identifies trending items. For example, if you specify `30 minutes` for `Trend discovery frequency`, every 30 minutes Amazon Personalize identifies items with the greatest rate of increase in interactions over 30-minute intervals. Available frequencies include 30 minutes, 1 hour, 2 hours, 3 hours, and 1 day. Choose a frequency that aligns with the distribution of your interactions data. Missing data over the interval you choose can reduce recommendation accuracy. If you use the CreateSolution API operation and don't specify a value, the default is every 2 hours. For any parameter values that are greater than 2 hours, Amazon Personalize automatically refreshes the trending item recommendations every 2 hours to account for new interactions and new items. Default value: 2 hours Possible values: 30 minutes, 1 hour, 2 hours, 3 hours, and 1 day. Value type: String HPO tunable: No |
## Creating a solution (SDK for Python (Boto3))
The following code shows how to create a solution with the Trending-Now recipe using the SDK for Python (Boto3). Possible values for `trend_discovery_frequency` are `30 minutes`, `1 hour`, `3 hours`, and `1 day`. For information about creating a solution with the console, see [Creating a solution (console)](create-solution.md#configure-solution-console).
```
import boto3
personalize = boto3.client("personalize")
create_solution_response = personalize_client.create_solution(
name="solution name",
recipeArn="arn:aws:personalize:::recipe/aws-trending-now",
datasetGroupArn="dataset group ARN",
solutionConfig={
"featureTransformationParameters": {
"trend_discovery_frequency": "1 hour"
}
}
)
print(create_solution_response['solutionArn'])
```
## Sample Jupyter notebook
For a sample Jupyter notebook that shows how to use the Trending-Now recipe, see [trending\$1now\$1example.ipynb](https://github.com/aws-samples/amazon-personalize-samples/blob/master/next_steps/core_use_cases/trending_now/trending_now_example.ipynb) in the Amazon Personalize samples GitHub repository.
# Popularity-Count recipe
Popularity-Count recommends the most popular items based your interactions data. The most popular items are the items with the most interactions data from unique users. The recipe returns the same popular items for all users. Popularity-Count is a good baseline for comparing with other recipes using the evaluation metrics Amazon Personalize generates when you create a solution version. For more information, see [Evaluating an Amazon Personalize solution version with metrics](working-with-training-metrics.md).
After you create a solution version, make sure you keep your solution version and data up to date. With Popularity-Count, you must manually create a new solution version (retrain the model) for Amazon Personalize to consider new items for recommendations and update the model with your user’s most recent behavior. Then you must update any campaign using the solution version. For more information, see [Maintaining recommendation relevance](maintaining-relevance.md).
This predefined recipe has the following properties:
+ **Name** – `aws-popularity-count`
+ **Recipe ARN** – `arn:aws:personalize:::recipe/aws-popularity-count`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-popularity-count`
+ **Feature transformation ARN** – `arn:aws:personalize:::feature-transformation/sims`
+ **Recipe type** – `USER_PERSONALIZATION`
Popularity-Count has no exposed hyperparameters.
# Personalized-Ranking-v2 recipe
The Personalized-Ranking-v2 recipe generates personalized rankings of items. A *personalized ranking* is a list of recommended items that are re-ranked by relevance for a specific user. This is useful if you have a collection of ordered items, such as search results, promotions, or curated lists, and you want to provide a personalized re-ranking for each of your users.
Personalized-Ranking-v2 can train on up to 5 million items from Item interactions and Items datasets. And it generates more accurate rankings with lower latency than [Personalized-Ranking](native-recipe-search.md).
When you use Personalized-Ranking-v2, you specify the items to rank in a [GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md) API operation. If you specify items without interactions data, Amazon Personalize will return these items without a recommendation score in the GetPersonalizedRanking API response.
This recipe uses a transformer-based architecture to train a model that learns context and tracks relationships and patterns in your data. *Transformers* are a type of neural network architecture that transforms or changes an input sequence into an output sequence. For Amazon Personalize, the input sequence is a user's item interaction history in your data. The output sequence is their personalized recommendations. For more information about transformers, see [What Are Transformers In Artificial Intelligence?](https://aws.amazon.com/what-is/transformers-in-artificial-intelligence/) in the AWS Cloud Computing Concepts Hub.
Personalized-Ranking-v2 uses a different pricing model than other recipes. For more information about pricing, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).
**Topics**
+ [Recipe features](#personalized-ranking-v2-features)
+ [Required and optional datasets](#personalized-ranking-v2-datasets)
+ [Properties and hyperparameters](#personalized-ranking-v2-hyperparameters)
## Recipe features
Personalized-Ranking-v2 uses the following Amazon Personalize recipe features when ranking items:
+ Real-time personalization – With real-time personalization, Amazon Personalize updates and adapts item recommendations according to a user's evolving interest. For more information, see [Real-time personalization](use-case-recipe-features.md#about-real-time-personalization).
+ Metadata with recommendations – With the Personalized-Ranking-v2 recipe, if you have an Items dataset with at minimum one column of metadata, campaigns automatically have the option to include item metadata with recommendation results. You don't have manually enable metadata for your campaign. You might use metadata to enrich recommendations in your user interface, such as adding the genres for movies to carousels. For more information, see [Item metadata in recommendations](campaigns.md#create-campaign-return-metadata).
## Required and optional datasets
To use the Personalized-Ranking-v2, you must create an Item interactions dataset and import at minimum 1000 item interactions. Amazon Personalize generates rankings primarily based on item interaction data. For more information, see [Item interaction data](interactions-datasets.md). Personalized-Ranking-v2 can train on up to 5 million items across Item interactions and Items datasets.
With Personalized-Ranking-v2, Amazon Personalize can use Item interactions data that includes the following:
+ Event type and event value data – Amazon Personalize uses event type data, such as click or watch event types, to identify user intent and interest through any patterns in their behavior. Also, you can use event type and event value data to filter records before training. For more information, see [Event type and event value data](interactions-datasets.md#event-type-and-event-value-data).
**Note**
With Personalized-Ranking-v2, your training cost is based on your interactions data before filtering by event type or value. For more information about pricing, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).
+ Contextual metadata – Contextual metadata is interactions data you collect on the user's environment at the time of an event, such as their location or device type. For more information, see [Contextual metadata](interactions-datasets.md#interactions-contextual-metadata).
The following datasets are optional and can improve recommendations:
+ Users dataset – Amazon Personalize can use data in your Users dataset to better understand your users and their interests. You can also use data in a Users dataset to filter recommendations. For information about the user data you can import, see [User metadata](users-datasets.md).
+ Items dataset – Amazon Personalize can use data in your Items dataset to identify connections and patterns in their behavior. This helps Amazon Personalize understand your users and their interests. You can also use data in a Items dataset to filter recommendations. For information about the item data you can import, see [Item metadata](items-datasets.md).
## Properties and hyperparameters
The Personalized-Ranking-v2 recipe has the following properties:
+ **Name** – `aws-personalized-ranking-v2`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-personalized-ranking-v2`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-personalized-ranking-v2`
For more information, see [Choosing a recipe](working-with-predefined-recipes.md).
The following table describes the hyperparameters for the Personalized-Ranking-v2 recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. The process of choosing the best value for a hyperparameter is called hyperparameter optimization (HPO). With Personalized-Ranking-v2, if you turn on automatic training, Amazon Personalize automatically performs HPO every 90 days. Without automatic training, no HPO occurs.
The table provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
| Name | Description |
| --- | --- |
| Algorithm hyperparameters |
| apply\$1recency\$1bias | Determines whether the model should give more weight to the most recent item interactions data in your Item interactions dataset. The most recent interactions data might include sudden changes in the underlying patterns of interaction events. To train a model that places more weight on recent events, set `apply_recency_bias` to `true`. To train a model that equally weighs all past interactions, set `apply_recency_bias` to `false`. Default value: `true` Range: `true` or `false` Value type: Boolean HPO tunable: No |
# Personalized-Ranking recipe
**Important**
We recommend using the [Personalized-Ranking-v2](native-recipe-personalized-ranking-v2.md) recipe. It can consider up to 5 million items with faster training, and generate more accurate rankings with lower latency.
The Personalized-Ranking recipe generates personalized rankings of items. A *personalized ranking* is a list of recommended items that are re-ranked for a specific user. This is useful if you have a collection of ordered items, such as search results, promotions, or curated lists, and you want to provide a personalized re-ranking for each of your users. For example, with Personalized-Ranking, Amazon Personalize can re-rank search results that you generate with [OpenSearch](personalize-opensearch.md).
To train a model, the Personalized-Ranking recipe uses the data in your Item interactions dataset, and if you created them, the Items dataset and Users dataset in your dataset group (these datasets are optional). With Personalized-Ranking, your Items dataset can include [Unstructured text metadata](items-datasets.md#text-data) and your Item interactions dataset can include [Contextual metadata](interactions-datasets.md#interactions-contextual-metadata). To get a personalized ranking, use the [GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md) API.
After you create a solution version, make sure you keep your solution version and data up to date. With Personalized-Ranking, you must manually create a new solution version (retrain the model) for Amazon Personalize to consider new items for recommendations and update the model with your user’s most recent behavior. Then you must update any campaign using the solution version. For more information, see [Maintaining recommendation relevance](maintaining-relevance.md).
**Note**
If you provide items without interactions data for ranking, Amazon Personalize will return these items without a recommendation score in the GetPersonalizedRanking API response.
This recipe has the following properties:
+ **Name** – `aws-personalized-ranking`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-personalized-ranking`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-personalized-ranking`
+ **Feature transformation ARN** – `arn:aws:personalize:::feature-transformation/JSON-percentile-filtering`
+ **Recipe type** – `PERSONALIZED_RANKING`
## Hyperparameters
The following table describes the hyperparameters for the Personalize-Ranking recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. Featurization hyperparameters control how to filter the data to use in training. The process of choosing the best value for a hyperparameter is called hyperparameter optimization (HPO). For more information, see [Hyperparameters and HPO](customizing-solution-config-hpo.md).
The table also provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
+ **HPO tunable**: Can the parameter participate in hyperparameter optimization (HPO)?
| Name | Description |
| --- | --- |
| Algorithm hyperparameters |
| hidden\$1dimension | 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 Item interactions dataset includes more complicated patterns. Using more hidden dimensions requires a larger dataset and more time to process. To decide on the optimal value, use HPO. To use HPO, set `performHPO` to `true` when you call [CreateSolution](API_CreateSolution.md) and [CreateSolutionVersion](API_CreateSolutionVersion.md) operations. 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\$1mask | Determines whether the model should consider the latest popularity trends in the Item 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\$1user\$1history\$1length\$1percentile | 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\$1user\$1history\$1length\$1percentile | 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 |
## Personalized-Ranking sample notebook
For a sample Jupyter notebook that shows how to use the Personalized-Ranking recipe, see [Personalize Ranking Example](https://github.com/aws-samples/amazon-personalize-samples/blob/master/next_steps/core_use_cases/personalized_ranking/personalize_ranking_example.ipynb).
# Semantic-Similarity recipe
The Semantic-Similarity recipe (aws-semantic-similarity) generates recommendations for items that are semantically similar to a given item based on textual content. Unlike traditional similarity recipes that rely on user-item interactions, this recipe analyzes the textual descriptions and attributes of items to generate embeddings and identify semantically similar items
This recipe is ideal for scenarios where you want to recommend items based on content similarity, such as recommending books with similar themes, articles on related topics, or products with similar descriptions. It works particularly well for new items with limited interaction history (cold-start scenarios) and for catalogs where semantic relationships are more important than co-occurrence patterns.
With Semantic-Similarity, you provide an item ID in a [GetRecommendations](https://docs.aws.amazon.com/personalize/latest/dg/API_RS_GetRecommendations.html) operation (or the Amazon Personalize console) and Amazon Personalize returns a list of similar items. Or you can use a batch workflow to get similar items for all of the items in your inventory (see [Getting batch item recommendations](https://docs.aws.amazon.com/personalize/latest/dg/getting-batch-recommendations.html)).
**Topics**
+ [Recipe features](#semantic-similarity-features)
+ [Required and optional datasets](#semantic-similarity-datasets)
+ [Properties and hyperparameters](#semantic-similarity-hyperparameters)
## Recipe features
Semantic-Similarity uses the following Amazon Personalize recipe features when generating item recommendations:
+ Real-time personalization – With the Semantic-Similarity recipe, Amazon Personalize automatically keeps your item catalog up to date. When you add new items to your Items dataset or update existing item metadata, these changes are reflected in your recommendations within approximately 30 minutes when using incremental training. This ensures that your customers always see the most current items available in your catalog without requiring manual intervention or waiting for a full retraining cycle. This is particularly valuable for catalogs that change frequently, such as news articles, blog posts, or seasonal product offerings. To enable incremental updates, customers must:
+ Set `performIncrementalUpdate` to `true` for the solution in the API
+ Choose either "Full and Incremental training" or "Incremental training" option under Training method in the UI
Note that enabling incremental updates will incur additional costs whenever an update is being performed.
+ Metadata with recommendations – With the Semantic-Similarity recipe, campaigns automatically have the option to include item metadata with recommendation results. You don't have manually enable metadata for your campaign. You might use metadata to enrich recommendations in your user interface, such as adding the genres for movies to carousels. For more information, see [Item metadata in recommendations](https://docs.aws.amazon.com/personalize/latest/dg/campaigns.html#create-campaign-return-metadata).
## Required and optional datasets
To use the Semantic-Similarity recipe, you must create an Items dataset. Amazon Personalize generates recommendations based on the semantic meaning of item metadata. For more information, see [Item metadata](https://docs.aws.amazon.com/personalize/latest/dg/items-datasets.html). Semantic-Similarity can train on up to 10 million items in your Items dataset.
With Semantic-Similarity, Amazon Personalize requires Items data that includes the following
+ itemName field – One string field with `itemName` set to `true`. This field should contain the title or name of the item.
+ Textual description field – At least one string field marked as `textual` that contains the description of the item. This should be the field that best describes and represents the item.
Amazon Personalize uses this field to generate semantic embeddings that capture the meaning and content of your items.
Additionally, the reserved CREATION\$1TIMESTAMP field should be set if you want to use freshness-based ranking. For more information, see [Properties and hyperparameters](#semantic-similarity-hyperparameters).
The following datasets are optional and can improve recommendations:
+ Interactions dataset– Amazon Personalize can use data in your Interactions dataset to calculate popularity scores based on user engagement with items. You can use popularity scores to rank similar items by how popular they are among users. You must provide an Interactions dataset if you want to use popularity-based ranking. You can also use data in an Interactions dataset to filter recommendations. For information about the interaction data you can import, see [Item interaction data](https://docs.aws.amazon.com/personalize/latest/dg/interactions-datasets.html)
## Properties and hyperparameters
The Semantic-Similarity recipe has the following properties:
+ **Name** – `aws-semantic-similarity`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-semantic-similarity`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-semantic-similarity`
+ **Feature transformation ARN** – `arn:aws:personalize:::feature-transformation/aws-semantic-similarity`
+ **Recipe type** – `RELATED_ITEMS`
For more information, see [Choosing a recipe](working-with-predefined-recipes.md).
The Semantic-Similarity recipe has no exposed hyperparameters but you can configure popularity and freshness factors when you create a campaign to influence the ranking of similar items.
The table provides the following information for each factor:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
| Name | Description |
| --- | --- |
| Freshness | The freshness factor represents how recent an item is. Freshness is computed by normalizing the age of the item based on its CREATION\$1TIMESTAMP. To use the freshness factor, you must include the CREATION\$1TIMESTAMP field in your Items dataset schema. Higher values of freshness factor will prioritize newer items among semantically similar recommendations Default value: `0.0` Range: ` [0.0, 1.0]` Value type: Double |
| Popularity | The popularity factor represents how popular an item is based on user interactions. Popularity is computed by normalizing the number of interactions each item received. To use the popularity factor, you must include an Interactions dataset when creating your dataset group. Higher values of popularity factor prioritize items with more customer interactions among semantically similar recommendations. Default value: `0.0` Range: ` [0.0, 1.0]` Value type: Double |
Note that freshness and popularity scores are computed at training and incremental updates will not update popularity and freshness scores. For the most recent popularity and freshness factors to influence the ranking of recommended items, either use automatic retraining or manually retrain the solution and update the campaign with the new solution version.
# Similar-Items recipe
**Note**
All RELATED\$1ITEMS recipes use interactions data. Choose Similar-Items if you have also have item metadata and want Amazon Personalize to use it to find similar items. Or choose the [SIMS recipe](native-recipe-sims.md) if you want to configure more hyperparameters for the model.
The Similar-Items (aws-similar-items) recipe generates recommendations for items that are similar to an item you specify. Use Similar-Items to help customers discover new items in your catalog based on their previous behavior and item metadata. Recommending similar items can increase user engagement, click-through rate, and conversion rate for your application.
Similar-Items calculates similarity based on interactions data and any item metadata you provide. It takes into account the co-occurrence of the item in user histories in your Interaction dataset, and any item metadata similarities. For example, with Similar-Items, Amazon Personalize could recommend items customers frequently bought together with a similar style ([Categorical metadata](items-datasets.md#item-categorical-data)), or movies that different users also watched with a similar description ([Unstructured text metadata](items-datasets.md#text-data)).
With Similar-Items, you provide an item ID in a [GetRecommendations](API_RS_GetRecommendations.md) operation (or the Amazon Personalize console) and Amazon Personalize returns a list of similar items. Or you can use a batch workflow to get similar items for all of the items in your inventory (see [Getting batch item recommendations](getting-batch-recommendations.md)). When you get similar items, you can filter the items based on an attribute of the item you specify in your request. You do this by adding a `CurrentItem`.`attribute` element to your filter. For an example, see [item data filter examples](item-recommendation-filter-examples.md#item-examples).
To use Similar-Items, you must create an Item interactions dataset with at least 1000 unique historical and event interactions (combined). For more accurate predictions, we recommend that you also create an Items dataset and import metadata about items in your catalog. Similar-Items doesn't use data in a Users dataset when generating recommendations. You can still filter recommendations based on data in a Users dataset. For more information, see [Filtering recommendations and user segments](filter.md).
If you have an Items dataset with textual data and item title data, you can generate themes for related items in batch recommendations. For more information, see [Batch recommendations with themes from Content Generator](themed-batch-recommendations.md)
You can get recommendations for items that are similar to a cold item (an item with fewer than five interactions). If Amazon Personalize can't find the item ID that you specify in your recommendation request or batch input file, the recipe returns popular items as recommendations.
After you create a solution version, make sure you keep your solution version and data up to date. With Similar-Items, you must manually create a new solution version (retrain the model) for Amazon Personalize to consider new items for recommendations and update the model with your user’s most recent behavior. Then you must update any campaign using the solution version. For more information, see [Maintaining recommendation relevance](maintaining-relevance.md).
## Properties and hyperparameters
The Similar-Items recipe has the following properties:
+ **Name** – `aws-similar-items`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-similar-items`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-similar-items`
For more information, see [Choosing a recipe](working-with-predefined-recipes.md).
The following table describes the hyperparameters for the Similar-Items recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. The process of choosing the best value for a hyperparameter is called hyperparameter optimization (HPO). For more information, see [Hyperparameters and HPO](customizing-solution-config-hpo.md).
The table also provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
+ **HPO tunable**: Can the parameter participate in HPO?
| Name | Description |
| --- | --- |
| Algorithm hyperparameters |
| popularity\$1discount\$1factor | Configure how popularity influences recommendations. Specify a value closer to zero to include more popular items. Specify a value closer to one for less emphasis on popularity. Default value: 0.0 Range: [0.0, 1.0] Value type: Float HPO tunable: No |
| item\$1id\$1hidden\$1dim | The number of hidden variables Amazon Personalize uses to model item ID embeddings based on interactions data. *Hidden variables* recreate users' purchase history and item statistics to generate ranking scores. To use `item_id_hidden_dim`, you must use HPO and provide minimum and maximum range values. Amazon Personalize uses HPO to find the best value within the range you specify. Specify a greater maximum value when you have a large Item interactions dataset. Using a greater maximum value requires more time to process. To use HPO, set `performHPO` to `true` when you call the [CreateSolution](API_CreateSolution.md) operation. Default value: 100 Range: [30, 200] Value type: Integer HPO tunable: Yes |
| item\$1metadata\$1hidden\$1dim | The number of hidden variables Amazon Personalize uses to model item metadata. To use `item_metadata_hidden_dim`, you must use HPO and provide minimum and maximum range values. Amazon Personalize uses HPO to find the best value within the range you specify. Specify a greater maximum value when you have a large Item interactions dataset. Using a greater maximum requires more time to process. To use HPO, set `performHPO` to `true` when you call the [CreateSolution](API_CreateSolution.md) operation. Default value: 100 Range: [30, 200] Value type: Integer HPO tunable: Yes |
# SIMS recipe
**Note**
All RELATED\$1ITEMS recipes use interactions data. Choose SIMS if you want to configure more hyperparameters for the model. Choose the [Similar-Items recipe](native-recipe-similar-items.md) if you have item metadata and want Amazon Personalize to use it to find similar items.
The Item-to-item similarities (SIMS) recipe uses collaborative filtering to recommend items that are most similar to an item you specify when you get recommendations. SIMS uses your Item interactions dataset, not item metadata such as color or price, to determine similarity. SIMS identifies the co-occurrence of the item in user histories in your Interaction dataset to recommend similar items. For example, with SIMS Amazon Personalize could recommend coffee shop items customers frequently bought together or movies that different users also watched.
When you get similar item recommendations, you can filter the items based on an attribute of the item you specify in your request. You do this by adding a `CurrentItem`.`attribute` element to your filter. For an example, see [item data filter examples](item-recommendation-filter-examples.md#item-examples).
To use SIMS, you must create an Item interactions dataset with at least 1000 unique historical and event interactions (combined). SIMS doesn't use data in a Users or Items dataset when generating recommendations. You can still filter recommendations based on data in a these datasets. For more information, see [Filtering recommendations and user segments](filter.md).
If there isn't sufficient user behavior data for an item or the item ID you provide isn't found, SIMS recommends popular items. After you create a solution version, make sure you keep your solution version and data up to date. With SIMS, you must manually create a new solution version (retrain the model) for Amazon Personalize to consider new items for recommendations and update the model with your user’s most recent behavior. Then you must update any campaign using the solution version. For more information, see [Maintaining recommendation relevance](maintaining-relevance.md).
The SIMS recipe has the following properties:
+ **Name** – `aws-sims`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-sims`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-sims`
+ **Feature transformation ARN** – `arn:aws:personalize:::feature-transformation/sims`
+ **Recipe type** – `RELATED_ITEMS`
The following table describes the hyperparameters for the SIMS recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. Featurization hyperparameters control how to filter the data to use in training. The process of choosing the best value for a hyperparameter is called hyperparameter optimization (HPO). For more information, see [Hyperparameters and HPO](customizing-solution-config-hpo.md).
The table also provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
+ **HPO tunable**: Can the parameter participate in hyperparameter optimization (HPO)?
| Name | Description |
| --- | --- |
| Algorithm hyperparameters |
| popularity\$1discount\$1factor | Configure how popularity influences recommendations. Specify a value closer to zero to include more popular items. Specify a value closer to one for less emphasis on popularity. Default value: 0.5 Range: [0.0, 1.0] Value type: Float HPO tunable: Yes |
| min\$1cointeraction\$1count | The minimum number of co-interactions you need to calculate the similarity between a pair of items. For example, a value of `3` means that you need three or more users who interacted with both items for the algorithm to calculate their similarity. Default value: 3 Range: [0, 10] Value type: Integer HPO tunable: Yes |
| Featurization hyperparameters |
| min\$1user\$1history\$1length\$1percentile | The minimum percentile of user history lengths to include in model training. *History length* is the total amount of available data on 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. Default value: 0.005 Range: [0.0, 1.0] Value type: Float HPO tunable: No |
| max\$1user\$1history\$1length\$1percentile | The maximum percentile of user history lengths to include in model training. History length is the total amount of available data on a user. Use `max_user_history_length_percentile` to exclude a percentage of users with long history lengths. Users with a long history 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, `min_hist_length_percentile = 0.05` and `max_hist_length_percentile = 0.95` includes all users except ones with history lengths at the bottom or top 5%. Default value: 0.995 Range: [0.0, 1.0] Value type: Float HPO tunable: No |
| min\$1item\$1interaction\$1count\$1percentile | The minimum percentile of item interaction counts to include in model training. Use `min_item_interaction_count_percentile` to exclude a percentage of items with a short history of interactions. Items with a short history often are new items. Removing them can train models with more focus on items with a known history. 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 items, but removes the edge cases. Default value: 0.01 Range: [0.0, 1.0] Value type: Float HPO tunable: No |
| max\$1item\$1interaction\$1count\$1percentile | The maximum percentile of item interaction counts to include in model training. Use `max_item_interaction_count_percentile` to exclude a percentage of items with a long history of interactions. Items with a long history tend to be older and might be out of date. For example, a movie release that is out of print. Removing these items can focus on more relevant items. 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 items but removes the edge cases. For example, `min_item_interaction_count_percentile = 0.05` and `max_item_interaction_count_percentile = 0.95` includes all items except ones with an interaction count at the bottom or top 5%. Default value: 0.9 Range: [0.0, 1.0] Value type: Float HPO tunable: No |
## SIMS sample notebook
For a sample Jupyter notebook that shows you how to use the SIMS recipe, see [Finding similar items \$1 HPO](https://github.com/aws-samples/amazon-personalize-samples/blob/master/next_steps/core_use_cases/related_items/personalize_sims_example.ipynb).
# Next-Best-Action recipe
The Next-Best-Action (aws-next-best-action) recipe generates real-time recommendations for the next best actions for your users. The next best action for a user is the action that they will most likely take. For example, enrolling in your loyalty program, downloading your app, or applying for a credit card.
With Next-Best-Action, you can provide personalized action recommendations for your users as they use your application. Suggesting the right action for a user can result in more users taking your actions. Depending on the actions you want to recommend, you can increase customer loyalty, generate more revenue, and improve the user experience of your application. For a use case example that describes how personalized action recommendations can benefit an ecommerce application, see [Use case example](#nba-use-case-example).
Amazon Personalize predicts the next best action from the actions you import into your Actions dataset. It identifies the actions that a user will most likely take based on their interactions with actions and items. If your action data includes the value of the action, Amazon Personalize accounts for the action's value. If a user is equally likely to take two different actions, Amazon Personalize ranks the action with the greater value higher.
When you get real-time action recommendations for a user, Amazon Personalize returns a list of actions that the user will most likely take within a configurable period of time (the `action optimization period`). For example, the actions they will most likely take in the next 14 days. The list is sorted in descending order by propensity score. This score represents the likelihood that the user will take the action.
Until you import action interaction data, Amazon Personalize recommends actions in your without personalization, and propensity scores are 0.0. An action will have a score after the action has the following:
+ At least 50 action interactions with the TAKEN event type.
+ At least 50 action interactions with the NOT\$1TAKEN or VIEWED event type.
These action interactions must be present at the latest solution version training, and must occur within a span of 6 weeks from the latest interaction timestamp in the Action interactions dataset.
For more information about the data the Next-Best-Action recipe uses, see [Required and optional datasets](#nba-datasets).
When you create a solution with the Next-Best-Action recipe, you can configure the window of time Amazon Personalize uses when predicting actions by using the `action optimization period` featurization hyperparameter. For more information, see [Properties and hyperparameters](#nba-hyperparameters).
**Topics**
+ [Use case example](#nba-use-case-example)
+ [Recipe features](#nba-recipe-features)
+ [Required and optional datasets](#nba-datasets)
+ [Properties and hyperparameters](#nba-hyperparameters)
## Use case example
Suggesting the right action for a user can result in more users taking your actions. Depending on the actions you want to recommend, you can potentially increase customer loyalty, generate more revenue, and improve the user experience of your application.
For example, you might have an ecommerce application that suggests the following different actions:
+ Subscribe to loyalty program
+ Download mobile app
+ Purchase in *Jewelry* category
+ Purchase in *Beauty and grooming* category
You might have a user who frequently shops at your site and has repeatedly taken the *Jewelry* and *Beauty and grooming* purchase actions. For this user, Amazon Personalize action recommendations and their scores might include the following:
+ Subscribe to loyalty program
Propensity score – 1.00
+ Purchase in *Jewelry* category
Propensity score – 0.86
+ Purchase in *Beauty and grooming* category
Propensity score – 0.85
With these action recommendations, you know to prompt the user to enroll in your loyalty program. This action has the highest propensity score and it is the action the user will most likely take. This is because the user frequently shops at your store and is likely to engage with the benefits from your loyalty program.
## Recipe features
The Next-Best-Action recipe uses the following Amazon Personalize recipe features when generating action recommendations:
+ Real-time personalization: Amazon Personalize uses real-time personalization to update and adapt action recommendations according to a user's evolving interest. For more information, see [Real-time personalization](use-case-recipe-features.md#about-real-time-personalization).
+ Exploration: With exploration, recommendations include new actions or actions with less interactions data. For more information about exploration, see [Exploration](use-case-recipe-features.md#about-exploration).
+ Automatic updates: With automatic updates, Amazon Personalize automatically updates the latest model (solution version) every two hours to include new actions in recommendations through exploration. For more information, see [Automatic updates](use-case-recipe-features.md#automatic-updates).
## Required and optional datasets
To use the Next-Best-Action recipe, you must create the following datasets:
+ Actions: You import data about your actions, such as their value, into an Amazon Personalize Actions dataset.
In your actions data, you can provide an EXPIRATION\$1TIMESTAMP for each action. If an action has expired, Amazon Personalize won't include it in recommendations. You can also provide a REPEAT\$1FREQUENCY for each action. This indicates how long Amazon Personalize should wait before recommending an action again after a user interacts with it. For information about the data an Actions dataset can store, see [Action metadata](actions-datasets.md).
+ Item interactions: Your Item interactions dataset must have at minimum 1000 item interactions. Amazon Personalize uses item interactions to understand your users' current state and their interests. For information about the item interactions data, see [Item interaction data](interactions-datasets.md).
The following datasets are optional:
+ Action interactions dataset: An *action interaction* is an interaction involving a user and an action in your Actions dataset. You can import Taken, Not taken, and Viewed action interactions. Although this data is optional, we recommend that you import action interaction data for quality recommendations. If you don't have action interaction data, you can create an empty Action interactions dataset and record your customers' interactions with actions by using the [PutActionInteractions](API_UBS_PutActionInteractions.md) API operation.
Until you import action interaction data, Amazon Personalize recommends actions in your without personalization, and propensity scores are 0.0. An action will have a score after the action has the following:
+ At least 50 action interactions with the TAKEN event type.
+ At least 50 action interactions with the NOT\$1TAKEN or VIEWED event type.
These action interactions must be present at the latest solution version training, and must occur within a span of 6 weeks from the latest interaction timestamp in the Action interactions dataset.
For information about the action interactions data you can import, see [Action interaction data](action-interactions-datasets.md). For information about recording action interaction events, see [Recording real-time action interaction eventsRecording action interaction events](recording-action-interaction-events.md).
**Note**
With Next-Best-Action, Amazon Personalize doesn't use impressions data or contextual metadata in an Action interactions dataset.
+ Users: Amazon Personalize uses any data in your Users dataset to better understand your users and their interests. You can also use data in a Users dataset to filter action recommendations. For information about the user data you can import, see [User metadata](users-datasets.md).
+ Items: Amazon Personalize uses any data in your Items dataset along with your Item interactions dataset to identify connections and patterns in their behavior. This helps Amazon Personalize understand your users and their interests. For information about the item data you can import, see [Item metadata](items-datasets.md).
## Properties and hyperparameters
The Next-Best-Action recipe doesn't support hyperparameter optimization. The Next-Best-Action recipe has the following properties:
+ **Name** – `aws-next-best-action`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-next-best-action`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-next-best-action`
The following table describes the featurization hyperparameters for the aws-next-best-action recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Featurization hyperparameters control how to filter the data to use in training.
The table also provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
+ **HPO tunable**: Whether the parameter can participate in HPO
| Name | Description |
| --- | --- |
| Featurization hyperparameters |
| action\$1optimization\$1period | The window of time Amazon Personalize uses when predicting the next best actions for a user. For example, the actions the user will most likely take in the next 14 days. If you don’t have much action interaction data, specify a larger value. If you aren’t sure what value to specify, use the default. Default value: 14 Range: [7, 28] Value type: Integer HPO tunable: No |
# Item-Affinity recipe
The Item-Affinity (aws-item-affinity) recipe is a USER\$1SEGMENTATION recipe that creates a user segment (group of users) for each item that you specify. These are the users Amazon Personalize predicts will most likely interact with each item. Use Item-Affinity to learn more about your users and take actions based on their respective user segments.
For example, you might want to create a marketing campaign for your retail application based on user preferences for items in your catalog. Item-Affinity would create a user segment for each item based on data in your Interactions and Items datasets. You could use this to promote different items to different user segments based on the likelihood that they will take an action (for example, click an item or purchase an item). Other uses might include cross-selling products to different sets of users or identifying prospective job applicants.
To get user segments based on items, you create a solution and a solution version with the Item-Affinity recipe, then add a list of items in JSON format to an Amazon S3 bucket and create a [batch segment job](creating-batch-seg-job.md). Amazon Personalize outputs a user segment for each item to your output location in Amazon S3. Your input data can have a maximum of 500 items to get user segments for. For information about preparing input data for a batch segment job, see [Preparing input data for batch recommendations](batch-data-upload.md).
You must have an Item interactions dataset to use Item-Affinity. Items and Users datasets are optional. You can get user segments with batch segment jobs. For more information, see [Getting batch user segments](getting-user-segments.md).
After you create a solution version, make sure you keep your solution version and data up to date. With Item-Affinity, you must create a new solution version for Amazon Personalize to consider new users for user segments and update the model with your users' most recent behavior. To get a user segment for an item, the item must have been present when you created the solution version.
The Item-Affinity recipe has the following properties:
+ **Name** – `aws-item-affinity`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-item-affinity`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-item-affinity`
+ **Feature transformation ARN** – `arn:aws:personalize:::feature-transformation/item-affinity`
+ **Recipe type** – `USER_SEGMENTATION`
The following table describes the hyperparameters for the Item-Affinity recipe. A *hyperparameter* is an algorithm parameter that you adjust to improve model performance. Algorithm hyperparameters control how the model performs. You can't use hyperparameter optimization (HPO) with the Item-Affinity recipe.
The table also provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
| Name | Description |
| --- | --- |
| Algorithm hyperparameters |
| hidden\$1dimension | 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. Default value: 149 Range: [32, 256] Value type: Integer |
# Item-Attribute-Affinity recipe
The Item-Attribute-Affinity (aws-item-attribute-affinity) recipe is a USER\$1SEGMENTATION recipe that creates a user segment (group of users) for each item attribute that you specify. These are the users Amazon Personalize predicts will most likely interact with items with the particular attribute. Use Item-Attribute-Affinity to learn more about your users and take actions based on their respective user segments.
For example, you might want to create a marketing campaign for your retail application based on user preferences for shoe types in your catalog. Item-Attribute-Affinity would create a user segment for each shoe type based data in your Interactions and Items datasets. You could use this to promote different shoes to different user segments based on the likelihood that they will take an action (for example, click a shoe or purchase a shoe). Other uses might include promoting different movie genres to different users or identifying prospective job applicant based on job type.
To get user segments based on item attributes, you create a solution and a solution version with the Item-Attribute-Affinity recipe, then add a list of item attributes in JSON format to an Amazon S3 bucket and create a [batch segment job](creating-batch-seg-job.md). Amazon Personalize outputs a user segment for each item to your output location in Amazon S3. Your input data can have a maximum of 10 queries, where each query is one or more item attributes. For information about preparing input data for a batch segment job, see [Preparing input data for batch recommendations](batch-data-upload.md).
You must have an Item interactions dataset and an Items dataset to use Item-Attribute-Affinity. Your Items dataset must have at least one column that is a non-textual, non-reserved metadata column. You can get user segments with batch segment jobs. For more information, see [Getting batch user segments with custom resources](getting-user-segments.md).
After you create a solution version, make sure you keep your solution version and data up to date. With Item-Attribute-Affinity, you must create a new solution version for Amazon Personalize to consider new users for user segments and update the model with your users' most recent behavior. To get a user segment for an item attribute, the item attribute must have been present when you created the solution version.
The Item-Attribute-Affinity recipe has the following properties:
+ **Name** – `aws-item-attribute-affinity`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-item-attribute-affinity`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-item-attribute-affinity`
+ **Feature transformation ARN** – `arn:aws:personalize:::feature-transformation/item-attribute-affinity`
+ **Recipe type** – `USER_SEGMENTATION`
The following table describes the hyperparameters for the Item-Attribute-Affinity recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. You can't use hyperparameter optimization (HPO) with the Item-Attribute-Affinity recipe.
The table also provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
| Name | Description |
| --- | --- |
| Algorithm hyperparameters |
| hidden\$1dimension | 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. Default value: 149 Range: [32, 256] Value type: Integer |
# Legacy HRNN recipes
Legacy HRNN recipes are no longer available. This documentation is for reference purposes.
We recommend using the aws-user-personalizaton (User-Personalization) recipe over the legacy HRNN recipes. User-Personalization improves upon and unifies the functionality offered by the HRNN recipes. For more information, see [User-Personalization recipe](native-recipe-new-item-USER_PERSONALIZATION.md).
Amazon Personalize can automatically choose the most appropriate hierarchical recurrent neural network (HRNN) recipe based on its analysis of the input data. This option is called AutoML. For more information, see [Using AutoML to choose an HRNN recipe (API only)](training-solution-auto-ml.md).
**Topics**
+ [Using AutoML to choose an HRNN recipe (API only)](training-solution-auto-ml.md)
+ [HRNN recipe (legacy)](native-recipe-hrnn.md)
+ [HRNN-Metadata recipe (legacy)](native-recipe-hrnn-metadata.md)
+ [HRNN-Coldstart recipe (legacy)](native-recipe-hrnn-coldstart.md)
# Using AutoML to choose an HRNN recipe (API only)
Amazon Personalize can automatically choose the most appropriate hierarchical recurrent neural network (HRNN) recipe based on its analysis of the input data. This option is called AutoML. To perform AutoML, set the `performAutoML` parameter to `true` when you call the [CreateSolution](API_CreateSolution.md) API.
You can also specify the list of recipes that Amazon Personalize examines to determine the optimal recipe, based on a metric you specify. In this case, you call the `CreateSolution` operation, specify `true` for the `performAutoML` parameter, omit the `recipeArn` parameter, and include the `solutionConfig` parameter, specifying the `metricName` and `recipeList` as part of the `autoMLConfig` object.
How a recipe is chosen is shown in the following table. Either `performAutoML`or `recipeArn` must be specified but not both. AutoML is only performed using the HRNN recipes.
| performAutoML | recipeArn | solutionConfig | Result |
| --- | --- | --- | --- |
| true | omit | omitted | Amazon Personalize chooses the recipe |
| true | omit | autoMLConfig: metricName and recipeList specified | Amazon Personalize chooses a recipe from the list that optimizes the metric |
| omit | specified | omitted | You specify the recipe |
| omit | specified | specified | You specify the recipe and override the default training properties |
**Note**
When `performAutoML` is `true`, all parameters of the `solutionConfig` object are ignored except for `autoMLConfig`.
# HRNN recipe (legacy)
**Note**
Legacy HRNN recipes are no longer available. This documentation is for reference purposes.
We recommend using the aws-user-personalizaton (User-Personalization) recipe over the legacy HRNN recipes. User-Personalization improves upon and unifies the functionality offered by the HRNN recipes. For more information, see [User-Personalization recipe](native-recipe-new-item-USER_PERSONALIZATION.md).
The Amazon Personalize hierarchical recurrent neural network (HRNN) recipe models changes in user behavior to provide recommendations during a session. A session is a set of user interactions within a given timeframe with a goal of finding a specific item to fill a need, for example. By weighing a user's recent interactions higher, you can provide more relevant recommendations during a session.
HRNN accommodates user intent and interests, which can change over time. It takes ordered user histories and automatically weights them to make better inferences. HRNN uses a gating mechanism to model the discount weights as a learnable function of the items and timestamps.
Amazon Personalize derives the features for each user from your dataset. If you have done real-time data integration, these features are updated in real time according to user activity. To get a recommendation, you provide only the `USER_ID`. If you also provide an `ITEM_ID`, Amazon Personalize ignores it.
The HRNN recipe has the following properties:
+ **Name** – `aws-hrnn`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-hrnn`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-hrnn`
+ **Feature transformation ARN** – `arn:aws:personalize:::feature-transformation/JSON-percentile-filtering`
+ **Recipe type** – `USER_PERSONALIZATION`
The following table describes the hyperparameters for the HRNN recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. Featurization hyperparameters control how to filter the data to use in training. The process of choosing the best value for a hyperparameter is called hyperparameter optimization (HPO). For more information, see [Hyperparameters and HPO](customizing-solution-config-hpo.md).
The table also provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
+ **HPO tunable**: Can the parameter participate in HPO?
| Name | Description |
| --- | --- |
| Algorithm hyperparameters |
| hidden\$1dimension | 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 Item interactions dataset includes more complicated patterns. Using more hidden dimensions requires a larger dataset and more time to process. To decide on the optimal value, use HPO. To use HPO, set `performHPO` to `true` when you call [CreateSolution](API_CreateSolution.md) and [CreateSolutionVersion](API_CreateSolutionVersion.md) operations. Default value: 43 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\$1mask | Determines whether the model should consider the latest popularity trends in the Item 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\$1user\$1history\$1length\$1percentile | 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\$1user\$1history\$1length\$1percentile | 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 |
# HRNN-Metadata recipe (legacy)
**Note**
Legacy HRNN recipes are no longer available. This documentation is for reference purposes.
We recommend using the aws-user-personalizaton (User-Personalization) recipe over the legacy HRNN recipes. User-Personalization improves upon and unifies the functionality offered by the HRNN recipes. For more information, see [User-Personalization recipe](native-recipe-new-item-USER_PERSONALIZATION.md).
The HRNN-Metadata recipe predicts the items that a user will interact with. It is similar to the [HRNN](native-recipe-hrnn.md) recipe, with additional features derived from contextual, user, and item metadata (from Interactions, Users, and Items datasets, respectively). HRNN-Metadata provides accuracy benefits over non-metadata models when high quality metadata is available. Using this recipe might require longer training times.
The HRNN-Metadata recipe has the following properties:
+ **Name** – `aws-hrnn-metadata`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-hrnn-metadata`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-hrnn-metadata`
+ **Feature transformation ARN** – `arn:aws:personalize:::feature-transformation/featurize_metadata`
+ **Recipe type** – `USER_PERSONALIZATION`
The following table describes the hyperparameters for the HRNN-Metadata recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. Featurization hyperparameters control how to filter the data to use in training. The process of choosing the best value for a hyperparameter is called hyperparameter optimization (HPO). For more information, see [Hyperparameters and HPO](customizing-solution-config-hpo.md).
The table also provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
+ **HPO tunable**: Can the parameter participate in hyperparameter optimization (HPO)?
| Name | Description |
| --- | --- |
| Algorithm Hyperparameters |
| hidden\$1dimension | 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 Item interactions dataset includes more complicated patterns. Using more hidden dimensions requires a larger dataset and more time to process. To decide on the optimal value, use HPO. To use HPO, set `performHPO` to `true` when you call [CreateSolution](API_CreateSolution.md) and [CreateSolutionVersion](API_CreateSolutionVersion.md) operations. Default value: 43 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\$1mask | Determines whether the model should consider the latest popularity trends in the Item 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\$1user\$1history\$1length\$1percentile | 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\$1user\$1history\$1length\$1percentile | 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 |
# HRNN-Coldstart recipe (legacy)
**Note**
Legacy HRNN recipes are no longer available. This documentation is for reference purposes.
We recommend using the aws-user-personalizaton (User-Personalization) recipe over the legacy HRNN recipes. User-Personalization improves upon and unifies the functionality offered by the HRNN recipes. For more information, see [User-Personalization recipe](native-recipe-new-item-USER_PERSONALIZATION.md).
Use the HRNN-Coldstart recipe to predict the items that a user will interact with when you frequently add new items and interactions and want to get recommendations for those items immediately. The HRNN-Coldstart recipe is similar to the [HRNN-Metadata](native-recipe-hrnn-metadata.md) recipe, but it allows you to get recommendations for new items.
In addition, you can use the HRNN-Coldstart recipe when you want to exclude from training items that have a long list of interactions either because of a recent popularity trend or because the interactions might be highly unusual and introduce noise in training. With HRNN-Coldstart, you can filter out less relevant items to create a subset for training. The subset of items, called *cold items*, are items that have related interaction events in the Item interactions dataset. An item is considered a cold item when it has the following:
+ Fewer interactions than a specified number of maximum interactions. You specify this value in the recipe's `cold_start_max_interactions` hyperparameter.
+ A shorter relative duration than the maximum duration. You specify this value in the recipe's `cold_start_max_duration` hyperparameter.
To reduce the number of cold items, set a lower value for `cold_start_max_interactions` or `cold_start_max_duration`. To increase the number of cold items, set a greater value for `cold_start_max_interactions` or `cold_start_max_duration`.
HRNN-Coldstart has the following cold item limits:
+ `Maximum cold start items`: 80,000
+ `Minimum cold start items`: 100
If the number of cold items is outside this range, attempts to create a solution will fail.
The HRNN-Coldstart recipe has the following properties:
+ **Name** – `aws-hrnn-coldstart`
+ **Recipe Amazon Resource Name (ARN)** – `arn:aws:personalize:::recipe/aws-hrnn-coldstart`
+ **Algorithm ARN** – `arn:aws:personalize:::algorithm/aws-hrnn-coldstart`
+ **Feature transformation ARN** – `arn:aws:personalize:::feature-transformation/featurize_coldstart`
+ **Recipe type** – `USER_PERSONALIZATION`
For more information, see [Choosing a recipe](working-with-predefined-recipes.md).
The following table describes the hyperparameters for the HRNN-Coldstart recipe. A *hyperparameter* is an algorithm parameter that you can adjust to improve model performance. Algorithm hyperparameters control how the model performs. Featurization hyperparameters control how to filter the data to use in training. The process of choosing the best value for a hyperparameter is called hyperparameter optimization (HPO). For more information, see [Hyperparameters and HPO](customizing-solution-config-hpo.md).
The table also provides the following information for each hyperparameter:
+ **Range**: [lower bound, upper bound]
+ **Value type**: Integer, Continuous (float), Categorical (Boolean, list, string)
+ **HPO tunable**: Can the parameter participate in HPO?
| Name | Description |
| --- | --- |
| Algorithm hyperparameters |
| hidden\$1dimension | 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 Item interactions dataset includes more complicated patterns. Using more hidden dimensions requires a larger dataset and more time to process. To decide on the optimal value, use HPO. To use HPO, set `performHPO` to `true` when you call [CreateSolution](API_CreateSolution.md) and [CreateSolutionVersion](API_CreateSolutionVersion.md) operations. 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\$1mask | Determines whether the model should consider the latest popularity trends in the Item 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 |
| cold\$1start\$1max\$1interactions | The maximum number of user-item interactions an item can have to be considered a cold item. Default value: 15 Range: Positive integers Value type: Integer HPO tunable: No |
| cold\$1start\$1max\$1duration | The maximum duration in days relative to the starting point for a user-item interaction to be considered a cold start item. To set the starting point of the user-item interaction, set the `cold_start_relative_from` hyperparameter. Default value: 5.0 Range: Positive floats Value type: Float HPO tunable: No |
| cold\$1start\$1relative\$1from | Determines the starting point for the HRNN-Coldstart recipe to calculate `cold_start_max_duration`. To calculate from the current time, choose `currentTime`. To calculate `cold_start_max_duration` from the timestamp of the latest item in the Item interactions dataset, choose `latestItem`. This setting is useful if you frequently add new items. Default value: `latestItem` Range: `currentTime`, `latestItem` Value type: String HPO tunable: No |
| min\$1user\$1history\$1length\$1percentile | 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\$1user\$1history\$1length\$1percentile | 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 |