Quickstart: Personalizer client library
Important
Starting on the 20th of September, 2023 you won’t be able to create new Personalizer resources. The Personalizer service is being retired on the 1st of October, 2026.
Get started with the Azure AI Personalizer client libraries to set up a basic learning loop. A learning loop is a system of decisions and feedback: an application requests a decision ranking from the service, then it uses the top-ranked choice and calculates a reward score from the outcome. It returns the reward score to the service. Over time, Personalizer uses AI algorithms to make better decisions for any given context. Follow these steps to set up a sample application.
Example scenario
In this quickstart, a grocery e-retailer wants to increase revenue by showing relevant and personalized products to each customer on its website. On the main page, there's a "Featured Product" section that displays a prepared meal product to prospective customers. The e-retailer would like to determine how to show the right product to the right customer in order to maximize the likelihood of a purchase.
The Personalizer service solves this problem in an automated, scalable, and adaptable way using reinforcement learning. You'll learn how to create actions and their features, context features, and reward scores. You'll use the Personalizer client library to make calls to the Rank and Reward APIs.
Reference documentation | Library source code | Package (NuGet) | .NET code sample
Prerequisites
- Azure subscription - Create one for free
- The current version of .NET Core.
- Once you have your Azure subscription, create a Personalizer resource in the Azure portal to get your key and endpoint. After it deploys, select Go to resource.
- You'll need the key and endpoint from the resource you create to connect your application to the Personalizer API. You'll paste your key and endpoint into the code below later in the quickstart.
- You can use the free pricing tier (
F0) to try the service, and upgrade later to a paid tier for production.
Model configuration
Change the model update frequency
In the Azure portal, go to your Personalizer resource's Configuration page, and change the Model update frequency to 30 seconds. This short duration will train the model rapidly, allowing you to see how the recommended action changes for each iteration.
Change the reward wait time
In the Azure portal, go to your Personalizer resource's Configuration page, and change the Reward wait time to 10 minutes. This determines how long the model will wait after sending a recommendation, to receive the reward feedback from that recommendation. Training won't occur until the reward wait time has passed.
Create a new C# application
Create a new .NET Core application in your preferred editor or IDE.
In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name personalizer-quickstart. This command creates a simple "Hello World" C# project with a single source file: Program.cs.
dotnet new console -n personalizer-quickstart
Change your directory to the newly created app folder. Then build the application with:
dotnet build
The build output should contain no warnings or errors.
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
Install the client library
Within the application directory, install the Personalizer client library for .NET with the following command:
dotnet add package Microsoft.Azure.CognitiveServices.Personalizer --version 1.0.0
Tip
If you're using the Visual Studio IDE, the client library is available as a downloadable NuGet package.
Code block 1: Generate sample data
Personalizer is meant to run on applications that receive and interpret real-time data. In this quickstart, you'll use sample code to generate imaginary customer actions on a grocery website. The following code block defines three key methods: GetActions, GetContext and GetRewardScore.
GetActions returns a list of the choices that the grocery website needs to rank. In this example, the actions are meal products. Each action choice has details (features) that may affect user behavior later on. Actions are used as input for the Rank API
GetContext returns a simulated customer visit. It selects randomized details (context features) like which customer is present and what time of day the visit is taking place. In general, a context represents the current state of your application, system, environment, or user. The context object is used as input for the Rank API.
The context features in this quickstart are simplistic. However, in a real production system, designing your features and evaluating their effectiveness is important. Refer to the linked documentation for guidance.
GetRewardScore returns a score between zero and one that represents the success of a customer interaction. It uses simple logic to determine how different contexts respond to different action choices. For example, a certain user will always give a 1.0 for vegetarian and vegan products, and a 0.0 for other products. In a real scenario, Personalizer will learn user preferences from the data sent in Rank and Reward API calls. You won't define these explicitly as in the example code.
In a real production system, the reward score should be designed to align with your business objectives and KPIs. Determining how to calculate the reward metric may require some experimentation.
In the code below, the users' preferences and responses to the actions is hard-coded as a series of conditional statements, and explanatory text is included in the code for demonstrative purposes.
Find your key and endpoint.
Important
Go to the Azure portal. If the Personalizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint in the resource's key and endpoint page, under resource management.
Remember to remove the key from your code when you're done, and never post it publicly. For production, consider using a secure way of storing and accessing your credentials. For example, Azure key vault.
Open Program.cs in a text editor or IDE and paste in the following code.
using Microsoft.Azure.CognitiveServices.Personalizer; using Microsoft.Azure.CognitiveServices.Personalizer.Models; class Program { private static readonly string ApiKey = "REPLACE_WITH_YOUR_PERSONALIZER_KEY"; private static readonly string ServiceEndpoint = "REPLACE_WITH_YOUR_ENDPOINT_URL"; static PersonalizerClient InitializePersonalizerClient(string url) { PersonalizerClient client = new PersonalizerClient( new ApiKeyServiceClientCredentials(ApiKey)) { Endpoint = url }; return client; } static Dictionary<string, ActionFeatures> actions = new Dictionary<string, ActionFeatures> { {"pasta", new ActionFeatures( new BrandInfo(company: "pasta_inc"), new ItemAttributes( quantity: 1, category: "Italian", price: 12), new DietaryAttributes( vegan: false, lowCarb: false, highProtein: false, vegetarian: false, lowFat: true, lowSodium: true))}, {"bbq", new ActionFeatures( new BrandInfo(company: "ambisco"), new ItemAttributes( quantity: 2, category: "bbq", price: 20), new DietaryAttributes( vegan: false, lowCarb: true, highProtein: true, vegetarian: false, lowFat: false, lowSodium: false))}, {"bao", new ActionFeatures( new BrandInfo(company: "bao_and_co"), new ItemAttributes( quantity: 4, category: "Chinese", price: 8), new DietaryAttributes( vegan: false, lowCarb: true, highProtein: true, vegetarian: false, lowFat: true, lowSodium: false))}, {"hummus", new ActionFeatures( new BrandInfo(company: "garbanzo_inc"), new ItemAttributes( quantity: 1, category: "Breakfast", price: 5), new DietaryAttributes( vegan: true, lowCarb: false, highProtein: true, vegetarian: true, lowFat: false, lowSodium: false))}, {"veg_platter", new ActionFeatures( new BrandInfo(company: "farm_fresh"), new ItemAttributes( quantity: 1, category: "produce", price: 7), new DietaryAttributes( vegan: true, lowCarb: true, highProtein: false, vegetarian: true, lowFat: true, lowSodium: true ))}, }; static IList<RankableAction> GetActions() { IList<RankableAction> rankableActions = new List<RankableAction>(); foreach (var action in actions) { rankableActions.Add(new RankableAction { Id = action.Key, Features = new List<object>() { action.Value } }); } return rankableActions; } public class BrandInfo { public string Company { get; set; } public BrandInfo(string company) { Company = company; } } public class ItemAttributes { public int Quantity { get; set; } public string Category { get; set; } public double Price { get; set; } public ItemAttributes(int quantity, string category, double price) { Quantity = quantity; Category = category; Price = price; } } public class DietaryAttributes { public bool Vegan { get; set; } public bool LowCarb { get; set; } public bool HighProtein { get; set; } public bool Vegetarian { get; set; } public bool LowFat { get; set; } public bool LowSodium { get; set; } public DietaryAttributes(bool vegan, bool lowCarb, bool highProtein, bool vegetarian, bool lowFat, bool lowSodium) { Vegan = vegan; LowCarb = lowCarb; HighProtein = highProtein; Vegetarian = vegetarian; LowFat = lowFat; LowSodium = lowSodium; } } public class ActionFeatures { public BrandInfo BrandInfo { get; set; } public ItemAttributes ItemAttributes { get; set; } public DietaryAttributes DietaryAttributes { get; set; } public ActionFeatures(BrandInfo brandInfo, ItemAttributes itemAttributes, DietaryAttributes dietaryAttributes) { BrandInfo = brandInfo; ItemAttributes = itemAttributes; DietaryAttributes = dietaryAttributes; } } public static Context GetContext() { return new Context( user: GetRandomUser(), timeOfDay: GetRandomTimeOfDay(), location: GetRandomLocation(), appType: GetRandomAppType()); } static string[] timesOfDay = new string[] { "morning", "afternoon", "evening" }; static string[] locations = new string[] { "west", "east", "midwest" }; static string[] appTypes = new string[] { "edge", "safari", "edge_mobile", "mobile_app" }; static IList<UserProfile> users = new List<UserProfile> { new UserProfile( name: "Bill", dietaryPreferences: new Dictionary<string, bool> { { "low_carb", true } }, avgOrderPrice: "0-20"), new UserProfile( name: "Satya", dietaryPreferences: new Dictionary<string, bool> { { "low_sodium", true} }, avgOrderPrice: "201+"), new UserProfile( name: "Amy", dietaryPreferences: new Dictionary<string, bool> { { "vegan", true }, { "vegetarian", true } }, avgOrderPrice: "21-50") }; static string GetRandomTimeOfDay() { var random = new Random(); var timeOfDayIndex = random.Next(timesOfDay.Length); Console.WriteLine($"TimeOfDay: {timesOfDay[timeOfDayIndex]}"); return timesOfDay[timeOfDayIndex]; } static string GetRandomLocation() { var random = new Random(); var locationIndex = random.Next(locations.Length); Console.WriteLine($"Location: {locations[locationIndex]}"); return locations[locationIndex]; } static string GetRandomAppType() { var random = new Random(); var appIndex = random.Next(appTypes.Length); Console.WriteLine($"AppType: {appTypes[appIndex]}"); return appTypes[appIndex]; } static UserProfile GetRandomUser() { var random = new Random(); var userIndex = random.Next(users.Count); Console.WriteLine($"\nUser: {users[userIndex].Name}"); return users[userIndex]; } public class UserProfile { // Mark name as non serializable so that it is not part of the context features [NonSerialized()] public string Name; public Dictionary<string, bool> DietaryPreferences { get; set; } public string AvgOrderPrice { get; set; } public UserProfile(string name, Dictionary<string, bool> dietaryPreferences, string avgOrderPrice) { Name = name; DietaryPreferences = dietaryPreferences; AvgOrderPrice = avgOrderPrice; } } public class Context { public UserProfile User { get; set; } public string TimeOfDay { get; set; } public string Location { get; set; } public string AppType { get; set; } public Context(UserProfile user, string timeOfDay, string location, string appType) { User = user; TimeOfDay = timeOfDay; Location = location; AppType = appType; } } public static float GetRewardScore(Context context, string actionId) { float rewardScore = 0.0f; string userName = context.User.Name; ActionFeatures actionFeatures = actions[actionId]; if (userName.Equals("Bill")) { if (actionFeatures.ItemAttributes.Price < 10 && !context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill likes to be economical when he's not in the midwest visiting his friend Warren. He bought {actionId} because it was below a price of $10."); } else if (actionFeatures.DietaryAttributes.LowCarb && context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill is visiting his friend Warren in the midwest. There he's willing to spend more on food as long as it's low carb, so Bill bought {actionId}."); } else if (actionFeatures.ItemAttributes.Price >= 10 && !context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill didn't buy {actionId} because the price was too high when not visting his friend Warren in the midwest."); } else if (actionFeatures.DietaryAttributes.LowCarb && context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill didn't buy {actionId} because it's not low-carb, and he's in the midwest visitng his friend Warren."); } } else if (userName.Equals("Satya")) { if (actionFeatures.DietaryAttributes.LowSodium) { rewardScore = 1.0f; Console.WriteLine($"\nSatya is health conscious, so he bought {actionId} since it's low in sodium."); } else { Console.WriteLine($"\nSatya did not buy {actionId} because it's not low sodium."); } } else if (userName.Equals("Amy")) { if (actionFeatures.DietaryAttributes.Vegan || actionFeatures.DietaryAttributes.Vegetarian) { rewardScore = 1.0f; Console.WriteLine($"\nAmy likes to eat plant-based foods, so she bought {actionId} because it's vegan or vegetarian friendly."); } else { Console.WriteLine($"\nAmy did not buy {actionId} because it's not vegan or vegetarian."); } } return rewardScore; } // ...Paste your key and endpoint into the code where indicated. Your endpoint has the form
https://<your_resource_name>.cognitiveservices.azure.com/.Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. See the Azure AI services security article for more information.
Code block 2: Iterate the learning loop
The next block of code defines the main method and closes out the script. It runs a learning loop iteration, in which it generates a context (including a customer), requests a ranking of actions in that context using the Rank API, calculates the reward score, and passes that score back to the Personalizer service using the Reward API. It prints relevant information to the console at each step.
In this example, each Rank call is made to determine which product should be displayed in the "Featured Product" section. Then the Reward call indicates whether or not the featured product was purchased by the user. Rewards are associated with their decisions through a common EventId value.
static void Main(string[] args)
{
int iteration = 1;
bool runLoop = true;
// Get the actions list to choose from personalizer with their features.
IList<RankableAction> actions = GetActions();
// Initialize Personalizer client.
PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);
do
{
Console.WriteLine("\nIteration: " + iteration++);
// Get context information.
Context context = GetContext();
// Create current context from user specified data.
IList<object> currentContext = new List<object>() {
context
};
// Generate an ID to associate with the request.
string eventId = Guid.NewGuid().ToString();
// Rank the actions
var request = new RankRequest(actions: actions, contextFeatures: currentContext, eventId: eventId);
RankResponse response = client.Rank(request);
Console.WriteLine($"\nPersonalizer service thinks {context.User.Name} would like to have: {response.RewardActionId}.");
float reward = GetRewardScore(context, response.RewardActionId);
// Send the reward for the action based on user response.
client.Reward(response.EventId, new RewardRequest(reward));
Console.WriteLine("\nPress q to break, any other key to continue:");
runLoop = !(GetKey() == "Q");
} while (runLoop);
}
private static string GetKey()
{
return Console.ReadKey().Key.ToString().Last().ToString().ToUpper();
}
}
Run the program
Run the application with the dotnet dotnet run command from your application directory.
dotnet run
On the first iteration, Personalizer will recommend a random action, because it hasn't done any training yet. You can optionally run more iterations. After about 10 minutes, the service will start to show improvements in its recommendations.
Generate many events for analysis (optional)
You can easily generate, say, 5,000 events from this quickstart scenario, which is sufficient to get experience using Apprentice mode and Online mode, running offline evaluations, and creating feature evaluations. Replace the main method above with:
static void Main(string[] args)
{
int iteration = 1;
int runLoop = 0;
// Get the actions list to choose from personalizer with their features.
IList<RankableAction> actions = GetActions();
// Initialize Personalizer client.
PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);
do
{
Console.WriteLine("\nIteration: " + iteration++);
// Get context information.
Context context = GetContext();
// Create current context from user specified data.
IList<object> currentContext = new List<object>() {
context
};
// Generate an ID to associate with the request.
string eventId = Guid.NewGuid().ToString();
// Rank the actions
var request = new RankRequest(actions: actions, contextFeatures: currentContext, eventId: eventId);
RankResponse response = client.Rank(request);
Console.WriteLine($"\nPersonalizer service thinks {context.User.Name} would like to have: {response.RewardActionId}.");
float reward = GetRewardScore(context, response.RewardActionId);
// Send the reward for the action based on user response.
client.Reward(response.EventId, new RewardRequest(reward));
runLoop = runLoop + 1;
} while (runLoop < 1000);
}
The source code for this quickstart is available on GitHub.
Reference documentation | Package (npm) | Quickstart code sample
Prerequisites
- Azure subscription - Create one for free
- Install Node.js and npm (verified with Node.js v14.16.0 and npm 6.14.11).
- Once you have your Azure subscription, create a Personalizer resource in the Azure portal to get your key and endpoint. After it deploys, select Go to resource.
- You'll need the key and endpoint from the resource you create to connect your application to the Personalizer API. You'll paste your key and endpoint into the code below later in the quickstart.
- You can use the free pricing tier (
F0) to try the service, and upgrade later to a paid tier for production.
Model configuration
Change the model update frequency
In the Azure portal, go to your Personalizer resource's Configuration page, and change the Model update frequency to 30 seconds. This short duration will train the model rapidly, allowing you to see how the recommended action changes for each iteration.
Change the reward wait time
In the Azure portal, go to your Personalizer resource's Configuration page, and change the Reward wait time to 10 minutes. This determines how long the model will wait after sending a recommendation, to receive the reward feedback from that recommendation. Training won't occur until the reward wait time has passed.
Create a new Node.js application
In a console window (such as cmd, PowerShell, or Bash), create a new directory for your app, and navigate to it.
mkdir myapp && cd myapp
Run the npm init -y command to create a package.json file.
npm init -y
Create a new Node.js script in your preferred editor or IDE named personalizer-quickstart.js and create variables for your resource's endpoint and subscription key.
Install the client library
Install the Personalizer client library for Node.js with the following command:
npm install @azure/cognitiveservices-personalizer --save
Install the remaining npm packages for this quickstart:
npm install @azure/ms-rest-azure-js @azure/ms-rest-js readline-sync uuid --save
Code block 1: Generate sample data
Personalizer is meant to run on applications that receive and interpret real-time data. In this quickstart, you'll use sample code to generate imaginary customer actions on a grocery website. The following code block defines three key methods: getActionsList, getContextFeaturesList and getReward.
getActionsList returns a list of the choices that the grocery website needs to rank. In this example, the actions are meal products. Each action choice has details (features) that may affect user behavior later on. Actions are used as input for the Rank API
getContextFeaturesList returns a simulated customer visit. It selects randomized details (context features) like which customer is present and what time of day the visit is taking place. In general, a context represents the current state of your application, system, environment, or user. The context object is used as input for the Rank API.
The context features in this quickstart are simplistic. However, in a real production system, designing your features and evaluating their effectiveness is important. Refer to the linked documentation for guidance.
getReward prompts the user to score the service's recommendation as a success or failure. It returns a score between zero and one that represents the success of a customer interaction. In a real scenario, Personalizer will learn user preferences from real-time customer interactions.
In a real production system, the reward score should be designed to align with your business objectives and KPIs. Determining how to calculate the reward metric may require some experimentation.
Open personalizer-quickstart.js in a text editor or IDE and paste in the code below.
const uuidv1 = require('uuid/v1');
const Personalizer = require('@azure/cognitiveservices-personalizer');
const CognitiveServicesCredentials = require('@azure/ms-rest-azure-js').CognitiveServicesCredentials;
const readline = require('readline-sync');
function getReward() {
const answer = readline.question("\nIs this correct (y/n)\n");
if (answer.toLowerCase() === 'y') {
console.log("\nGreat| Enjoy your food.");
return 1;
}
console.log("\nYou didn't like the recommended food choice.");
return 0;
}
function getContextFeaturesList() {
const timeOfDayFeatures = ['morning', 'afternoon', 'evening', 'night'];
const tasteFeatures = ['salty', 'sweet'];
let answer = readline.question("\nWhat time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night\n");
let selection = parseInt(answer);
const timeOfDay = selection >= 1 && selection <= 4 ? timeOfDayFeatures[selection - 1] : timeOfDayFeatures[0];
answer = readline.question("\nWhat type of food would you prefer (enter number)? 1. salty 2. sweet\n");
selection = parseInt(answer);
const taste = selection >= 1 && selection <= 2 ? tasteFeatures[selection - 1] : tasteFeatures[0];
console.log("Selected features:\n");
console.log("Time of day: " + timeOfDay + "\n");
console.log("Taste: " + taste + "\n");
return [
{
"time": timeOfDay
},
{
"taste": taste
}
];
}
function getExcludedActionsList() {
return [
"juice"
];
}
function getActionsList() {
return [
{
"id": "pasta",
"features": [
{
"taste": "salty",
"spiceLevel": "medium"
},
{
"nutritionLevel": 5,
"cuisine": "italian"
}
]
},
{
"id": "ice cream",
"features": [
{
"taste": "sweet",
"spiceLevel": "none"
},
{
"nutritionalLevel": 2
}
]
},
{
"id": "juice",
"features": [
{
"taste": "sweet",
"spiceLevel": "none"
},
{
"nutritionLevel": 5
},
{
"drink": true
}
]
},
{
"id": "salad",
"features": [
{
"taste": "salty",
"spiceLevel": "low"
},
{
"nutritionLevel": 8
}
]
}
];
}
Code block 2: Iterate the learning loop
The next block of code defines the main method and closes out the script. It runs a learning loop iteration, in which it asks the user their preferences at the command line and sends that information to Personalizer to select the best action. It presents the selected action to the user, who makes a choice using the command-line. Then it sends a reward score to the Personalizer service to signal how well the service did in its selection.
The Personalizer learning loop is a cycle of Rank and Reward calls. In this quickstart, each Rank call, to personalize the content, is followed by a Reward call to tell Personalizer how well the service performed.
Add the code below to personalizer-quickstart.js.
Find your key and endpoint. Your endpoint has the form
https://<your_resource_name>.cognitiveservices.azure.com/.Important
Go to the Azure portal. If the Personalizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint in the resource's key and endpoint page, under resource management.
Remember to remove the key from your code when you're done, and never post it publicly. For production, consider using a secure way of storing and accessing your credentials. For example, Azure key vault.
Paste your key and endpoint into the code where indicated.
Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure way of storing and accessing your credentials like Azure Key Vault. For more information about security, see the Azure AI services security article.
async function main() { // The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF" const serviceKey = "PASTE_YOUR_PERSONALIZER_SUBSCRIPTION_KEY_HERE"; // The endpoint specific to your personalization service instance; // e.g. https://<your-resource-name>.cognitiveservices.azure.com const baseUri = "PASTE_YOUR_PERSONALIZER_ENDPOINT_HERE"; const credentials = new CognitiveServicesCredentials(serviceKey); // Initialize Personalization client. const personalizerClient = new Personalizer.PersonalizerClient(credentials, baseUri); let runLoop = true; do { let rankRequest = {} // Generate an ID to associate with the request. rankRequest.eventId = uuidv1(); // Get context information from the user. rankRequest.contextFeatures = getContextFeaturesList(); // Get the actions list to choose from personalization with their features. rankRequest.actions = getActionsList(); // Exclude an action for personalization ranking. This action will be held at its current position. rankRequest.excludedActions = getExcludedActionsList(); rankRequest.deferActivation = false; // Rank the actions const rankResponse = await personalizerClient.rank(rankRequest); console.log("\nPersonalization service thinks you would like to have:\n") console.log(rankResponse.rewardActionId); // Display top choice to user, user agrees or disagrees with top choice const reward = getReward(); console.log("\nPersonalization service ranked the actions with the probabilities as below:\n"); for (let i = 0; i < rankResponse.ranking.length; i++) { console.log(JSON.stringify(rankResponse.ranking[i]) + "\n"); } // Send the reward for the action based on user response. const rewardRequest = { value: reward } await personalizerClient.events.reward(rankRequest.eventId, rewardRequest); runLoop = continueLoop(); } while (runLoop); } function continueLoop() { const answer = readline.question("\nPress q to break, any other key to continue.\n") if (answer.toLowerCase() === 'q') { return false; } return true; } main() .then(result => console.log("done")) .catch(err=> console.log(err));
Run the program
Run the application with the Node.js command from your application directory.
node personalizer-quickstart.js
Iterate through a few learning loops. After about 10 minutes, the service will start to show improvements in its recommendations.
The source code for this quickstart is available on GitHub.
Reference documentation | Library source code | Package (pypi) | Quickstart code sample
Prerequisites
- Azure subscription - Create one for free
- Python 3.x
- Once your Azure subscription is set up, create a Personalizer resource in the Azure portal and obtain your key and endpoint. After it deploys, select Go to resource.
- You'll need the key and endpoint from the created resource to connect your application to the Personalizer API, which you'll paste into the quick-start code below.
- You can use the free pricing tier (
F0) to try the service, then upgrade to a paid tier for production at a later time.
Model configuration
Change the model update frequency
In the Azure portal, go to your Personalizer resource's Configuration page, and change the Model update frequency to 30 seconds. This short duration will train the model rapidly, allowing you to see how the recommended action changes for each iteration.
Change the reward wait time
In the Azure portal, go to your Personalizer resource's Configuration page, and change the Reward wait time to 10 minutes. This determines how long the model will wait after sending a recommendation, to receive the reward feedback from that recommendation. Training won't occur until the reward wait time has passed.
Create a new Python application
Create a new Python file named personalizer-quickstart.py.
Install the client library
Install the Personalizer client library with pip:
pip install azure-cognitiveservices-personalizer
Code block 1: Generate sample data
Personalizer is meant to run on applications that receive and interpret real-time data. For the purpose of this quickstart, you'll use sample code to generate imaginary customer actions on a grocery website. The following code block defines three key functions: get_actions, get_context and get_reward_score.
get_actions returns a list of the choices that the grocery website needs to rank. In this example, the actions are meal products. Each action choice has details (features) that may affect user behavior later on. Actions are used as input for the Rank API
get_context returns a simulated customer visit. It selects randomized details (context features) like which customer is present and what time of day the visit is taking place. In general, a context represents the current state of your application, system, environment, or user. The context object is used as input for the Rank API.
The context features in this quickstart are simplistic. However, in a real production system, designing your features and evaluating their effectiveness is very important. Refer to the linked documentation for guidance.
get_reward_score returns a score between zero and one that represents the success of a customer interaction. It uses simple logic to determine how different contexts will respond to different action choices. For example, a certain user will always give a 1.0 for vegetarian and vegan products, and a 0.0 for other products. In a real scenario, Personalizer will learn user preferences from the data sent in Rank and Reward API calls. You won't define these explicitly as in the example code.
In a real production system, the reward score should be designed to align with your business objectives and KPIs. Determining how to calculate the reward metric may require some experimentation.
In the code below, the users' preferences and responses to the actions is hard-coded as a series of conditional statements, and explanatory text is included in the code for demonstrative purposes.
Follow these steps to set up the Personalizer script.
Find your key and endpoint.
Important
Go to the Azure portal. If the Personalizer resource you created in the Prerequisites section deployed successfully, click the Go to Resource button under Next Steps. You can find your key and endpoint in the resource's key and endpoint page, under resource management.
Remember to remove the key from your code when you're done, and never post it publicly. For production, consider using a secure way of storing and accessing your credentials. For example, Azure key vault.
Open personalizer-quickstart.py in a text editor or IDE and paste in the code below.
Paste your key and endpoint into the code where indicated. Your endpoint has the form
https://<your_resource_name>.cognitiveservices.azure.com/.Important
Remember to remove the key from your code when you're done, and never post it publicly. For production, use a secure method to store and access your credentials like Azure Key Vault. For more information, see the Azure AI services security.
from azure.cognitiveservices.personalizer import PersonalizerClient
from azure.cognitiveservices.personalizer.models import RankableAction, RewardRequest, RankRequest
from msrest.authentication import CognitiveServicesCredentials
import datetime, json, os, time, uuid, random
key = "paste_your_personalizer_key_here"
endpoint = "paste_your_personalizer_endpoint_here"
# Instantiate a Personalizer client
client = PersonalizerClient(endpoint, CognitiveServicesCredentials(key))
actions_and_features = {
'pasta': {
'brand_info': {
'company':'pasta_inc'
},
'attributes': {
'qty':1, 'cuisine':'italian',
'price':12
},
'dietary_attributes': {
'vegan': False,
'low_carb': False,
'high_protein': False,
'vegetarian': False,
'low_fat': True,
'low_sodium': True
}
},
'bbq': {
'brand_info' : {
'company': 'ambisco'
},
'attributes': {
'qty': 2,
'category': 'bbq',
'price': 20
},
'dietary_attributes': {
'vegan': False,
'low_carb': True,
'high_protein': True,
'vegetarian': False,
'low_fat': False,
'low_sodium': False
}
},
'bao': {
'brand_info': {
'company': 'bao_and_co'
},
'attributes': {
'qty': 4,
'category': 'chinese',
'price': 8
},
'dietary_attributes': {
'vegan': False,
'low_carb': True,
'high_protein': True,
'vegetarian': False,
'low_fat': True,
'low_sodium': False
}
},
'hummus': {
'brand_info' : {
'company': 'garbanzo_inc'
},
'attributes' : {
'qty': 1,
'category': 'breakfast',
'price': 5
},
'dietary_attributes': {
'vegan': True,
'low_carb': False,
'high_protein': True,
'vegetarian': True,
'low_fat': False,
'low_sodium': False
}
},
'veg_platter': {
'brand_info': {
'company': 'farm_fresh'
},
'attributes': {
'qty': 1,
'category': 'produce',
'price': 7
},
'dietary_attributes': {
'vegan': True,
'low_carb': True,
'high_protein': False,
'vegetarian': True,
'low_fat': True,
'low_sodium': True
}
}
}
def get_actions():
res = []
for action_id, feat in actions_and_features.items():
action = RankableAction(id=action_id, features=[feat])
res.append(action)
return res
user_profiles = {
'Bill': {
'dietary_preferences': 'low_carb',
'avg_order_price': '0-20',
'browser_type': 'edge'
},
'Satya': {
'dietary_preferences': 'low_sodium',
'avg_order_price': '201+',
'browser_type': 'safari'
},
'Amy': {
'dietary_preferences': {
'vegan', 'vegetarian'
},
'avg_order_price': '21-50',
'browser_type': 'edge'},
}
def get_context(user):
location_context = {'location': random.choice(['west', 'east', 'midwest'])}
time_of_day = {'time_of_day': random.choice(['morning', 'afternoon', 'evening'])}
app_type = {'application_type': random.choice(['edge', 'safari', 'edge_mobile', 'mobile_app'])}
res = [user_profiles[user], location_context, time_of_day, app_type]
return res
def get_random_users(k = 5):
return random.choices(list(user_profiles.keys()), k=k)
def get_reward_score(user, actionid, context):
reward_score = 0.0
action = actions_and_features[actionid]
if user == 'Bill':
if action['attributes']['price'] < 10 and (context[1]['location'] != "midwest"):
reward_score = 1.0
print("Bill likes to be economical when he's not in the midwest visiting his friend Warren. He bought", actionid, "because it was below a price of $10.")
elif (action['dietary_attributes']['low_carb'] == True) and (context[1]['location'] == "midwest"):
reward_score = 1.0
print("Bill is visiting his friend Warren in the midwest. There he's willing to spend more on food as long as it's low carb, so Bill bought" + actionid + ".")
elif (action['attributes']['price'] >= 10) and (context[1]['location'] != "midwest"):
print("Bill didn't buy", actionid, "because the price was too high when not visting his friend Warren in the midwest.")
elif (action['dietary_attributes']['low_carb'] == False) and (context[1]['location'] == "midwest"):
print("Bill didn't buy", actionid, "because it's not low-carb, and he's in the midwest visitng his friend Warren.")
elif user == 'Satya':
if action['dietary_attributes']['low_sodium'] == True:
reward_score = 1.0
print("Satya is health conscious, so he bought", actionid,"since it's low in sodium.")
else:
print("Satya did not buy", actionid, "because it's not low sodium.")
elif user == 'Amy':
if (action['dietary_attributes']['vegan'] == True) or (action['dietary_attributes']['vegetarian'] == True):
reward_score = 1.0
print("Amy likes to eat plant-based foods, so she bought", actionid, "because it's vegan or vegetarian friendly.")
else:
print("Amy did not buy", actionid, "because it's not vegan or vegetarian.")
return reward_score
# ...
Code block 2: Iterate the learning loop
The next block of code defines the run_personalizer_cycle function and calls it in a simple user feedback loop. It runs a learning loop iteration, in which it generates a context (including a customer), requests a ranking of actions in that context using the Rank API, calculates the reward score, and passes that score back to the Personalizer service using the Reward API. It prints relevant information to the console at each step.
In this example, each Rank call is made to determine which product should be displayed in the "Featured Product" section. Then the Reward call indicates whether or not the featured product was purchased by the user. Rewards are associated with their decisions through a common EventId value.
def run_personalizer_cycle():
actions = get_actions()
user_list = get_random_users()
for user in user_list:
print("------------")
print("User:", user, "\n")
context = get_context(user)
print("Context:", context, "\n")
rank_request = RankRequest(actions=actions, context_features=context)
response = client.rank(rank_request=rank_request)
print("Rank API response:", response, "\n")
eventid = response.event_id
actionid = response.reward_action_id
print("Personalizer recommended action", actionid, "and it was shown as the featured product.\n")
reward_score = get_reward_score(user, actionid, context)
client.events.reward(event_id=eventid, value=reward_score)
print("\nA reward score of", reward_score , "was sent to Personalizer.")
print("------------\n")
continue_loop = True
while continue_loop:
run_personalizer_cycle()
br = input("Press Q to exit, or any other key to run another loop: ")
if(br.lower()=='q'):
continue_loop = False
Run the program
Once all the above code is included in your Python file, you can run it from your application directory.
python personalizer-quickstart.py
On the first iteration, Personalizer will recommend a random action, because it hasn't done any training yet. You can optionally run more iterations. After about 10 minutes, the service will start to show improvements in its recommendations.
Generate many events for analysis (optional)
You can easily generate, say, 5,000 events from this quickstart scenario, which is sufficient to get experience using Apprentice mode, Online mode, running offline evaluations, and creating feature evaluations. Replace the while loop in the above code block with the following code.
for i in range(0,1000):
run_personalizer_cycle()
The source code for this quickstart is available on GitHub.
Download the trained model
If you'd like download a Personalizer model that has been trained on 5,000 events from the example above, visit the Personalizer Samples repository and download the Personalizer_QuickStart_Model.zip file. Then go to your Personalizer resource in the Azure portal, go to the Setup page and the Import/export tab, and import the file.
Clean up resources
To clean up your Azure AI services subscription, you can delete the resource or delete the resource group, which will delete any associated resources.