Entrainement
Module
Formuler des suggestions avec Azure AI Personalizer - Training
Dans ce module, découvrez comment utiliser Azure AI Personalizer pour formuler des recommandations.
Ce navigateur n’est plus pris en charge.
Effectuez une mise à niveau vers Microsoft Edge pour tirer parti des dernières fonctionnalités, des mises à jour de sécurité et du support technique.
Important
À compter du 20 septembre 2023, vous ne pourrez pas créer de ressources Personalizer. Le service Personalizer est mis hors service le 1er octobre 2026.
La personnalisation sur plusieurs emplacements (en préversion) vous permet de cibler du contenu dans des mises en page web, des carrousels et des listes où plusieurs actions (par exemple, un produit ou un élément de contenu) sont présentées à vos utilisateurs. Grâce aux API multi-emplacements de Personalizer, vous pouvez demander aux modèles IA de Personalizer d’apprendre quels sont les contextes d’utilisation et les produits qui suscitent certains comportements, en tenant compte du placement dans votre interface utilisateur et en en tirant des enseignements. Par exemple, Personalizer peut apprendre que certains produits ou contenus attirent davantage de clics dans une barre latérale ou un pied de page que dans la partie principale d’une page.
Dans ce guide, vous allez apprendre à utiliser les API multi-emplacements de Personalizer.
Documentation de référence | Code source de la bibliothèque | Package (NuGet) | Informations conceptuelles sur les emplacements multiples | Exemples
F0
) pour tester le service, puis passer par la suite à un niveau payant pour la production.Notes
La personnalisation sur plusieurs emplacements (préversion) a un impact sur les autres fonctionnalités du service Personalizer. Cette modification est irréversible. Avant d’activer la personnalisation sur plusieurs emplacements, consultez Personnalisation sur plusieurs emplacements (préversion).
Notes
La personnalisation sur plusieurs emplacements ne fonctionne pas si vous ne désactivez pas l’optimisation automatique. L’optimisation automatique pour la personnalisation sur plusieurs emplacements sera prise en charge à l’avenir.
Dans le même onglet sur le portail, sous Importer les paramètres d’apprentissage, recherchez votre fichier json récemment modifié et chargez-le. Votre instance Personalizer est ainsi mise à jour en Personalizer sur « plusieurs emplacements », elle prend désormais en charge les appels de classement et de récompense sur plusieurs emplacements.
Dans le portail Azure, accédez à la page Configuration de votre ressource Personalizer et passez la fréquence de mise à jour du modèle à 30 secondes. Ainsi, l’apprentissage du modèle est effectué rapidement, ce qui vous permet de voir comment l’action recommandée change pour chaque itération.
Dans le portail Azure, accédez à la page Configuration de votre ressource Personalizer et passez le temps d’attente de la récompense à 10 minutes. Cela détermine combien de temps le modèle doit attendre avant de recevoir des commentaires de récompense de la recommandation qui a été envoyée. L’apprentissage ne peut avoir lieu tant que le temps d’attente de la récompense n’est pas écoulé.
Créez une application .NET Core dans votre éditeur ou IDE favori.
Dans une fenêtre de console (par exemple cmd, PowerShell ou Bash), utilisez la commande new
dotnet pour créer une application console avec le nom personalizer-quickstart
. Cette commande crée un projet C# « Hello World » simple avec un seul fichier source : Program.cs
.
dotnet new console -n personalizer-quickstart
Déplacez vos répertoires vers le dossier d’application nouvellement créé. Vous pouvez générer l’application avec :
dotnet build
La sortie de génération ne doit contenir aucun avertissement ni erreur.
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
Dans le répertoire de l’application, installez la bibliothèque de client Personalizer pour .NET avec la commande suivante :
dotnet add package Azure.AI.Personalizer --version 2.0.0-beta.2
À partir du répertoire de projet, ouvrez le fichier Program.cs
dans votre éditeur ou IDE favori. Ajoutez les directives using suivantes :
using System;
using Azure;
using Azure.AI.Personalizer;
using System.Collections.Generic;
using System.Linq;
Le client Personalizer est un objet PersonalizerClient qui s’authentifie auprès d’Azure avec Azure.AzureKeyCredential, qui contient votre clé.
Pour demander le meilleur élément du contenu pour chaque emplacement, créez un objet PersonalizerRankMultiSlotOptions, puis passez-le à PersonalizerClient.RankMultiSlot. La méthode RankMultiSlot retourne un PersonalizerMultiSlotRankResult.
Pour envoyer un score de récompense à Personalizer, créez un objet PersonalizerRewardMultiSlotOptions, puis transmettez-le à la méthode PersonalizerClient.RewardMultiSlot avec l’ID d’événement correspondant.
Ce guide de démarrage rapide n’accorde pas d’importance au score de récompense. Dans un système de production, déterminer les éléments ayant un impact sur le score de récompense (et dans quelle mesure) peut être un processus complexe, que vous pouvez décider de modifier au fil du temps. Cette décision de conception doit être l’une des principales décisions à prendre pour votre architecture Personalizer.
Ces extraits de code montrent comment effectuer les tâches suivantes avec la bibliothèque de client Personalizer pour .NET :
Dans cette section, vous allez effectuer deux opérations :
Commencez par ajouter les lignes suivantes à votre classe Program. Veillez à ajouter votre clé et votre point de terminaison à partir de votre ressource Personalizer.
Important
Accédez au portail Azure. Si la ressource Personalizer que vous avez créée dans la section Prérequis a été déployée, cliquez sur le bouton Accéder à la ressource sous Étapes suivantes. La clé et le point de terminaison se trouvent dans la page Clé et point de terminaison de la ressource, sous Gestion des ressources.
N’oubliez pas de supprimer la clé de votre code une fois que vous avez terminé, et ne la postez jamais publiquement. Pour la production, envisagez d’utiliser une méthode de stockage et d’accès sécurisée pour vos informations d’identification. Par exemple, Azure Key Vault.
private const string ServiceEndpoint = "https://REPLACE-WITH-YOUR-PERSONALIZER-RESOURCE-NAME.cognitiveservices.azure.com";
private const string ResourceKey = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>";
Ensuite, construisez les URL de classement et de récompense.
static PersonalizerClient InitializePersonalizerClient(Uri url)
{
return new PersonalizerClient(url, new AzureKeyCredential(ResourceKey));
}
Les actions représentent les choix de contenu parmi lesquels Personalizer doit sélectionner l’élément de contenu le mieux adapté. Ajoutez les méthodes suivantes à la classe Program pour représenter l’ensemble d’actions et leurs caractéristiques.
private static IList<PersonalizerRankableAction> GetActions()
{
IList<PersonalizerRankableAction> actions = new List<PersonalizerRankableAction>
{
new PersonalizerRankableAction(
id: "Red-Polo-Shirt-432",
features:
new List<object>() { new { onSale = "true", price = "20", category = "Clothing" } }
),
new PersonalizerRankableAction(
id: "Tennis-Racket-133",
features:
new List<object>() { new { onSale = "false", price = "70", category = "Sports" } }
),
new PersonalizerRankableAction(
id: "31-Inch-Monitor-771",
features:
new List<object>() { new { onSale = "true", price = "200", category = "Electronics" } }
),
new PersonalizerRankableAction(
id: "XBox-Series X-117",
features:
new List<object>() { new { onSale = "false", price = "499", category = "Electronics" } }
)
};
return actions;
}
Les emplacements constituent la page avec laquelle l’utilisateur interagit. Personalizer décidera de l’action à afficher dans chacun des emplacements définis. Les actions peuvent être exclues d’emplacements spécifiques, comme ExcludeActions
. BaselineAction
est l’action par défaut pour l’emplacement qui aurait été affiché sans l’utilisation de Personalizer.
Ce guide de démarrage rapide offre des fonctionnalités d’emplacement simples. Dans les systèmes de production, il peut être important de déterminer et d’évaluer les caractéristiques.
private static IList<PersonalizerSlotOptions> GetSlots()
{
IList<PersonalizerSlotOptions> slots = new List<PersonalizerSlotOptions>
{
new PersonalizerSlotOptions(
id: "BigHeroPosition",
features: new List<object>() { new { size = "large", position = "left" } },
excludedActions: new List<string>() { "31-Inch-Monitor-771" },
baselineAction: "Red-Polo-Shirt-432"
),
new PersonalizerSlotOptions(
id: "SmallSidebar",
features: new List<object>() { new { size = "small", position = "right" } },
excludedActions: new List<string>() { "Tennis-Racket-133" },
baselineAction: "XBox-Series X-117"
),
};
return slots;
}
Ajoutez les méthodes suivantes à la classe Program pour obtenir une entrée d’utilisateur à partir de la ligne de commande pour l’heure de la journée et le type d’appareil sur lequel se trouve l’utilisateur. Ces méthodes sont utilisées comme des fonctionnalités de contexte.
static string GetTimeOfDayForContext()
{
string[] timeOfDayFeatures = new string[] { "morning", "afternoon", "evening", "night" };
Console.WriteLine("\nWhat time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night");
if (!int.TryParse(GetKey(), out int timeIndex) || timeIndex < 1 || timeIndex > timeOfDayFeatures.Length)
{
Console.WriteLine("\nEntered value is invalid. Setting feature value to " + timeOfDayFeatures[0] + ".");
timeIndex = 1;
}
return timeOfDayFeatures[timeIndex - 1];
}
static string GetDeviceForContext()
{
string[] deviceFeatures = new string[] { "mobile", "tablet", "desktop" };
Console.WriteLine("\nWhat is the device type (enter number)? 1. Mobile 2. Tablet 3. Desktop");
if (!int.TryParse(GetKey(), out int deviceIndex) || deviceIndex < 1 || deviceIndex > deviceFeatures.Length)
{
Console.WriteLine("\nEntered value is invalid. Setting feature value to " + deviceFeatures[0] + ".");
deviceIndex = 1;
}
return deviceFeatures[deviceIndex - 1];
}
Les deux méthodes utilisent la méthode GetKey
pour lire la sélection de l’utilisateur à partir de la ligne de commande.
private static string GetKey()
{
return Console.ReadKey().Key.ToString().Last().ToString().ToUpper();
}
private static IList<object> GetContext(string time, string device)
{
return new List<object>()
{
new { time = time },
new { device = device }
};
}
La boucle d’apprentissage Personalizer est un cycle d’appels RankMultiSlot et RewardMultiSlot. Dans ce guide de démarrage rapide, chaque appel Rank en vue de personnaliser le contenu est suivi d’un appel Reward qui indique à Personalizer l’efficacité du service.
Le code ci-après applique, en boucle, le cycle suivant : il demande à l’utilisateur d’indiquer ses préférences à partir de la ligne de commande, il envoie ces informations à Personalizer en vue de sélectionner le contenu le mieux adapté pour chaque emplacement, il présente la sélection au client qui peut faire son choix dans la liste, puis il envoie un score de récompense à Personalizer, en indiquant l’efficacité du service concernant le choix du contenu.
static void Main(string[] args)
{
Console.WriteLine($"Welcome to this Personalizer Quickstart!\n" +
$"This code will help you understand how to use the Personalizer APIs (multislot rank and multislot reward).\n" +
$"Each iteration represents a user interaction and will demonstrate how context, actions, slots, and rewards work.\n" +
$"Note: Personalizer AI models learn from a large number of user interactions:\n" +
$"You won't be able to tell the difference in what Personalizer returns by simulating a few events by hand.\n" +
$"If you want a sample that focuses on seeing how Personalizer learns, see the Python Notebook sample.");
int iteration = 1;
bool runLoop = true;
IList<PersonalizerRankableAction> actions = GetActions();
IList<PersonalizerSlotOptions> slots = GetSlots();
PersonalizerClient client = InitializePersonalizerClient(new Uri(ServiceEndpoint));
do
{
Console.WriteLine("\nIteration: " + iteration++);
string timeOfDayFeature = GetTimeOfDayForContext();
string deviceFeature = GetDeviceForContext();
IList<object> currentContext = GetContext(timeOfDayFeature, deviceFeature);
string eventId = Guid.NewGuid().ToString();
var multiSlotRankOptions = new PersonalizerRankMultiSlotOptions(actions, slots, currentContext, eventId);
PersonalizerMultiSlotRankResult multiSlotRankResult = client.RankMultiSlot(multiSlotRankOptions);
for (int i = 0; i < multiSlotRankResult.Slots.Count(); ++i)
{
string slotId = multiSlotRankResult.Slots[i].SlotId;
Console.WriteLine($"\nPersonalizer service decided you should display: { multiSlotRankResult.Slots[i].RewardActionId} in slot {slotId}. Is this correct? (y/n)");
string answer = GetKey();
if (answer == "Y")
{
client.RewardMultiSlot(eventId, slotId, 1f);
Console.WriteLine("\nGreat! The application will send Personalizer a reward of 1 so it learns from this choice of action for this slot.");
}
else if (answer == "N")
{
client.RewardMultiSlot(eventId, slotId, 0f);
Console.WriteLine("\nYou didn't like the recommended item. The application will send Personalizer a reward of 0 for this choice of action for this slot.");
}
else
{
client.RewardMultiSlot(eventId, slotId, 0f);
Console.WriteLine("\nEntered choice is invalid. Service assumes that you didn't like the recommended item.");
}
}
Console.WriteLine("\nPress q to break, any other key to continue:");
runLoop = !(GetKey() == "Q");
} while (runLoop);
}
Dans les sections suivantes, examinez de plus près les appels de classement et de récompense. Ajoutez les méthodes suivantes, qui obtiennent les choix de contenu, obtiennent des emplacements et envoient des requêtes de classement et de récompense à plusieurs emplacements avant d’exécuter le fichier de code :
GetActions
GetSlots
GetTimeOfDayForContext
GetDeviceForContext
GetKey
GetContext
Pour traiter la requête Rank, le programme demande les préférences de l’utilisateur afin de créer un Context
avec les choix de contenu. La demande contient le contexte, les actions et les emplacements avec leurs fonctionnalités respectives ainsi qu’un ID d’événement unique, pour recevoir une réponse.
Ce guide de démarrage rapide utilise des caractéristiques de contexte simples basées sur l’heure de la journée et l’appareil de l’utilisateur. Dans les systèmes de production, il peut être important de déterminer et d’évaluer les actions et caractéristiques.
string timeOfDayFeature = GetTimeOfDayForContext();
string deviceFeature = GetDeviceForContext();
IList<object> currentContext = GetContext(timeOfDayFeature, deviceFeature);
string eventId = Guid.NewGuid().ToString();
var multiSlotRankOptions = new PersonalizerRankMultiSlotOptions(actions, slots, currentContext, eventId);
PersonalizerMultiSlotRankResult multiSlotRankResult = client.RankMultiSlot(multiSlotRankOptions);
Pour obtenir le score de récompense pour la requête Reward, le programme récupère la sélection de l’utilisateur pour chaque emplacement à partir de la ligne de commande, attribue une valeur numérique (score de récompense) à la sélection, puis envoie à l’API Reward, l’ID d’événement unique et le score de récompense pour chaque emplacement sous la forme d’une valeur numérique. Une récompense n’a pas besoin d’être définie pour chaque emplacement.
Dans le cadre de ce guide de démarrage rapide, un simple numéro est attribué en tant que score de récompense : 0 ou 1. Dans les systèmes de production, il peut être important de déterminer ce qui doit être envoyé à l’appel Reward (et à quel moment) selon vos besoins.
for (int i = 0; i < multiSlotRankResult.Slots.Count(); ++i)
{
string slotId = multiSlotRankResult.Slots[i].SlotId;
Console.WriteLine($"\nPersonalizer service decided you should display: { multiSlotRankResult.Slots[i].RewardActionId} in slot {slotId}. Is this correct? (y/n)");
string answer = GetKey();
if (answer == "Y")
{
client.RewardMultiSlot(eventId, slotId, 1f);
Console.WriteLine("\nGreat! The application will send Personalizer a reward of 1 so it learns from this choice of action for this slot.");
}
else if (answer == "N")
{
client.RewardMultiSlot(eventId, slotId, 0f);
Console.WriteLine("\nYou didn't like the recommended item. The application will send Personalizer a reward of 0 for this choice of action for this slot.");
}
else
{
client.RewardMultiSlot(eventId, slotId, 0f);
Console.WriteLine("\nEntered choice is invalid. Service assumes that you didn't like the recommended item.");
}
}
Exécutez l’application avec la commande run
dotnet à partir de votre répertoire d’application.
dotnet run
Le code source associé à ce guide de démarrage rapide est disponible.
Documentation de référence | Conceptuel sur plusieurs emplacements | Exemples
F0
) pour tester le service, puis passer par la suite à un niveau payant pour la production.Notes
La personnalisation sur plusieurs emplacements (préversion) a un impact sur les autres fonctionnalités du service Personalizer. Cette modification est irréversible. Avant d’activer la personnalisation sur plusieurs emplacements, consultez Personnalisation sur plusieurs emplacements (préversion).
Notes
La personnalisation sur plusieurs emplacements ne fonctionne pas si vous ne désactivez pas l’optimisation automatique. L’optimisation automatique pour la personnalisation sur plusieurs emplacements sera prise en charge à l’avenir.
Dans le même onglet sur le portail, sous Importer les paramètres d’apprentissage, recherchez votre fichier json récemment modifié et chargez-le. Votre instance Personalizer est ainsi mise à jour en Personalizer sur « plusieurs emplacements », elle prend désormais en charge les appels de classement et de récompense sur plusieurs emplacements.
Dans le portail Azure, accédez à la page Configuration de votre ressource Personalizer et passez la fréquence de mise à jour du modèle à 30 secondes. Ainsi, l’apprentissage du modèle est effectué rapidement, ce qui vous permet de voir comment l’action recommandée change pour chaque itération.
Dans le portail Azure, accédez à la page Configuration de votre ressource Personalizer et passez le temps d’attente de la récompense à 10 minutes. Cela détermine combien de temps le modèle doit attendre avant de recevoir des commentaires de récompense de la recommandation qui a été envoyée. L’apprentissage ne peut avoir lieu tant que le temps d’attente de la récompense n’est pas écoulé.
Dans une fenêtre de console (telle que cmd, PowerShell ou bash), créez un répertoire pour votre application et accédez-y.
mkdir myapp && cd myapp
Exécutez la commande npm init -y
pour créer un fichier package.json
.
npm init -y
Créez une application Node.js dans l’éditeur ou IDE de votre choix, nommée sample.js
, puis créez des variables pour le point de terminaison et la clé d’abonnement de votre ressource.
Important
Accédez au portail Azure. Si la ressource Personalizer que vous avez créée dans la section Prérequis a été déployée, cliquez sur le bouton Accéder à la ressource sous Étapes suivantes. La clé et le point de terminaison se trouvent dans la page Clé et point de terminaison de la ressource, sous Gestion des ressources.
N’oubliez pas de supprimer la clé de votre code une fois que vous avez terminé, et ne la postez jamais publiquement. Pour la production, envisagez d’utiliser une méthode de stockage et d’accès sécurisée pour vos informations d’identification. Par exemple, Azure Key Vault.
const axios = require('axios');
const { v4: uuidv4 } = require('uuid');
const readline = require('readline-sync');
// The endpoint specific to your personalization service instance;
// e.g. https://<your-resource-name>.cognitiveservices.azure.com
const PersonalizationBaseUrl = '<REPLACE-WITH-YOUR-PERSONALIZER-ENDPOINT>';
// The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF"
const ResourceKey = '<REPLACE-WITH-YOUR-PERSONALIZER-KEY>';
npm install readline-sync uuid axios --save
Pour demander le seul meilleur élément du contenu pour chaque emplacement, créez un rankRequest, puis envoyez une demande de publication au point de terminaison multislot/rank. La réponse est ensuite analysée dans un rankResponse.
Pour envoyer un score de récompense à Personalizer, créez un rewards, puis envoyez une demande de publication à multislot/events/{eventId}/reward.
Ce guide de démarrage rapide n’accorde pas d’importance à la détermination du score de récompense. Dans un système de production, déterminer les éléments ayant un impact sur le score de récompense (et dans quelle mesure) peut être un processus complexe, que vous pouvez décider de modifier au fil du temps. Cette décision de conception doit être l’une des principales décisions à prendre pour votre architecture Personalizer.
Ces extraits de code vous montrent comment effectuer les tâches suivantes en envoyant des requêtes HTTP pour NodeJS :
Dans cette section, vous allez construire les URL de classement/récompense à l’aide de l’URL de base et des en-têtes de demande à l’aide de la clé de ressource.
const MultiSlotRankUrl = PersonalizationBaseUrl.concat('personalizer/v1.1-preview.1/multislot/rank');
const MultiSlotRewardUrlBase = PersonalizationBaseUrl.concat('personalizer/v1.1-preview.1/multislot/events/');
const Headers = {
'ocp-apim-subscription-key': ResourceKey,
'Content-Type': 'application/json'
};
Les actions représentent les choix de contenu parmi lesquels Personalizer doit sélectionner l’élément de contenu le mieux adapté. Ajoutez les méthodes suivantes au script pour représenter l’ensemble d’actions et leurs caractéristiques.
function getActions() {
return [
{
'id': 'Red-Polo-Shirt-432',
'features': [
{
'onSale': 'true',
'price': 20,
'category': 'Clothing'
}
]
},
{
'id': 'Tennis-Racket-133',
'features': [
{
'onSale': 'false',
'price': 70,
'category': 'Sports'
}
]
},
{
'id': '31-Inch-Monitor-771',
'features': [
{
'onSale': 'true',
'price': 200,
'category': 'Electronics'
}
]
},
{
'id': 'XBox-Series X-117',
'features': [
{
'onSale': 'false',
'price': 499,
'category': 'Electronics'
}
]
}
];
}
Ajoutez les méthodes suivantes au script pour obtenir une entrée d’utilisateur à partir de la ligne de commande pour l’heure de la journée et le type d’appareil sur lequel se trouve l’utilisateur. Elles seront utilisées comme des caractéristiques de contexte.
function getContextFeatures() {
const timeOfDayFeatures = ['morning', 'afternoon', 'evening', 'night'];
const deviceFeatures = ['mobile', 'tablet', 'desktop'];
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 device is the user on (enter number)? 1. mobile 2. tablet 3. desktop\n');
selection = parseInt(answer);
const device = selection >= 1 && selection <= 3 ? deviceFeatures[selection - 1] : deviceFeatures[0];
console.log('Selected features:\n');
console.log('Time of day: ' + timeOfDay + '\n');
console.log('Device: ' + device + '\n');
return [
{
'time': timeOfDay
},
{
'device': device
}
];
}
Les emplacements constituent la page avec laquelle l’utilisateur interagit. Personalizer décidera de l’action à afficher dans chacun des emplacements définis. Les actions peuvent être exclues d’emplacements spécifiques, comme ExcludeActions
. BaselineAction
est l’action par défaut pour l’emplacement qui aurait été affiché sans l’utilisation de Personalizer.
Ce guide de démarrage rapide offre des fonctionnalités d’emplacement simples. Dans les systèmes de production, il peut être important de déterminer et d’évaluer les caractéristiques.
function getSlots() {
return [
{
'id': 'BigHeroPosition',
'features': [
{
'size': 'large',
'position': 'left',
}
],
'excludedActions': ['31-Inch-Monitor-771'],
'baselineAction': 'Red-Polo-Shirt-432'
},
{
'id': 'SmallSidebar',
'features': [
{
'size': 'small',
'position': 'right',
}
],
'excludedActions': ['Tennis-Racket-133'],
'baselineAction': 'XBox-Series X-117'
}
];
}
Ajoutez ces fonctions pour envoyer des requêtes de publication au point de terminaison Personalizer pour les appels de classement et de récompense à plusieurs emplacements.
async function sendMultiSlotRank(rankRequest) {
try {
let response = await axios.post(MultiSlotRankUrl, rankRequest, { headers: Headers })
return response.data;
}
catch (err) {
if(err.response)
{
throw err.response.data
}
console.log(err)
throw err;
}
}
async function sendMultiSlotReward(rewardRequest, eventId) {
try {
let rewardUrl = MultiSlotRewardUrlBase.concat(eventId, '/reward');
let response = await axios.post(rewardUrl, rewardRequest, { headers: Headers })
}
catch (err) {
console.log(err);
throw err;
}
}
Ajoutez la méthode suivante au script. L’invite de la ligne de commande vous indiquera si Personalizer a pris une bonne décision pour chaque emplacement.
function getRewardForSlot() {
let answer = readline.question('\nIs this correct? (y/n)\n').toUpperCase();
if (answer === 'Y') {
console.log('\nGreat! The application will send Personalizer a reward of 1 so it learns from this choice of action for this slot.\n');
return 1;
}
else if (answer === 'N') {
console.log('\nYou didn\'t like the recommended item.The application will send Personalizer a reward of 0 for this choice of action for this slot.\n');
return 0;
}
console.log('\nEntered choice is invalid. Service assumes that you didn\'t like the recommended item.\n');
return 0;
}
La boucle d’apprentissage Personalizer est un cycle d’appels aux API Rank et Reward. Dans ce guide de démarrage rapide, chaque appel Rank en vue de personnaliser le contenu est suivi d’un appel Reward qui indique à Personalizer l’efficacité du service.
Le code ci-après applique, en boucle, le cycle suivant : il demande à l’utilisateur d’indiquer ses préférences à partir de la ligne de commande, il envoie ces informations à Personalizer en vue de sélectionner le contenu le mieux adapté pour chaque emplacement, il présente la sélection au client qui peut faire son choix dans la liste, puis il envoie un score de récompense à Personalizer, en indiquant l’efficacité du service concernant le choix du contenu.
let runLoop = true;
(async () => {
do {
let multiSlotRankRequest = {};
// Generate an ID to associate with the request.
multiSlotRankRequest.eventId = uuidv4();
// Get context information from the user.
multiSlotRankRequest.contextFeatures = getContextFeatures();
// Get the actions list to choose from personalization with their features.
multiSlotRankRequest.actions = getActions();
// Get the list of slots for which Personalizer will pick the best action.
multiSlotRankRequest.slots = getSlots();
multiSlotRankRequest.deferActivation = false;
try {
//Rank the actions for each slot
let multiSlotRankResponse = await sendMultiSlotRank(multiSlotRankRequest);
let multiSlotrewards = {};
multiSlotrewards.reward = [];
for (let i = 0; i < multiSlotRankResponse.slots.length; i++) {
console.log('\nPersonalizer service decided you should display: '.concat(multiSlotRankResponse.slots[i].rewardActionId, ' in slot ', multiSlotRankResponse.slots[i].id, '\n'));
let slotReward = {};
slotReward.slotId = multiSlotRankResponse.slots[i].id;
// User agrees or disagrees with Personalizer decision for slot
slotReward.value = getRewardForSlot();
multiSlotrewards.reward.push(slotReward);
}
// Send the rewards for the event
await sendMultiSlotReward(multiSlotrewards, multiSlotRankResponse.eventId);
let answer = readline.question('\nPress q to break, any other key to continue:\n').toUpperCase();
if (answer === 'Q') {
runLoop = false;
}
}
catch (err) {
console.log(err);
throw err;
}
} while (runLoop);
})()
Dans les sections suivantes, examinez de plus près les appels de classement et de récompense.
Ajoutez les méthodes suivantes, qui permettent d’obtenir les choix de contenu, d’obtenir les préférences de l’utilisateur pour le contexte, d’obtenir les emplacements, d’exécuter des requêtes HTTP, d’obtenir une récompense pour chaque emplacement avant d’exécuter le fichier de code :
Pour traiter la requête Rank, le programme demande les préférences de l’utilisateur pour créer des choix de contenu. Le corps de la requête contient le contexte, les actions et les emplacements avec leurs caractéristiques respectives. La méthode sendMultiSlotRank
prend un rankRequest et exécute la demande de classement sur plusieurs emplacements.
Ce guide de démarrage rapide utilise des caractéristiques de contexte simples basées sur l’heure de la journée et l’appareil de l’utilisateur. Dans les systèmes de production, il peut être important de déterminer et d’évaluer les actions et caractéristiques.
let multiSlotRankRequest = {};
// Generate an ID to associate with the request.
multiSlotRankRequest.eventId = uuidv4();
// Get context information from the user.
multiSlotRankRequest.contextFeatures = getContextFeatures();
// Get the actions list to choose from personalization with their features.
multiSlotRankRequest.actions = getActions();
// Get the list of slots for which Personalizer will pick the best action.
multiSlotRankRequest.slots = getSlots();
multiSlotRankRequest.deferActivation = false;
//Rank the actions for each slot
try {
let multiSlotRankResponse = await sendMultiSlotRank(multiSlotRankRequest);
}
catch (err) {
console.log(err);
throw err;
}
Pour obtenir le score de récompense pour la requête Reward, le programme récupère la sélection de l’utilisateur pour chaque emplacement à partir de la ligne de commande, attribue une valeur numérique (score de récompense) à la sélection, puis envoie à la méthode sendMultiSlotReward
l’ID d’événement unique et le score de récompense pour chaque emplacement. Une récompense n’a pas besoin d’être définie pour chaque emplacement.
Dans le cadre de ce guide de démarrage rapide, un simple numéro est attribué en tant que score de récompense : 0 ou 1. Dans les systèmes de production, il peut être important de déterminer ce qui doit être envoyé à l’appel Reward (et à quel moment) selon vos besoins.
let multiSlotrewards = {};
multiSlotrewards.reward = [];
for (i = 0; i < multiSlotRankResponse.slots.length; i++) {
console.log('\nPersonalizer service decided you should display: '.concat(multiSlotRankResponse.slots[i].rewardActionId, ' in slot ', multiSlotRankResponse.slots[i].id, '\n'));
let slotReward = {};
slotReward.slotId = multiSlotRankResponse.slots[i].id;
// User agrees or disagrees with Personalizer decision for slot
slotReward.value = getRewardForSlot();
multiSlotrewards.reward.push(slotReward);
}
// Send the rewards for the event
await sendMultiSlotReward(multiSlotrewards, multiSlotRankResponse.eventId);
Exécutez l’application avec Node.js à partir de votre répertoire d’application.
node sample.js
Le code source associé à ce guide de démarrage rapide est disponible.
Conceptuel sur plusieurs emplacements | Échantillons
F0
) pour tester le service, puis passer par la suite à un niveau payant pour la production.Notes
La personnalisation sur plusieurs emplacements (préversion) a un impact sur les autres fonctionnalités du service Personalizer. Cette modification est irréversible. Avant d’activer la personnalisation sur plusieurs emplacements, consultez Personnalisation sur plusieurs emplacements (préversion).
Notes
La personnalisation sur plusieurs emplacements ne fonctionne pas si vous ne désactivez pas l’optimisation automatique. L’optimisation automatique pour la personnalisation sur plusieurs emplacements sera prise en charge à l’avenir.
Dans le même onglet sur le portail, sous Importer les paramètres d’apprentissage, recherchez votre fichier json récemment modifié et chargez-le. Votre instance Personalizer est ainsi mise à jour en Personalizer sur « plusieurs emplacements », elle prend désormais en charge les appels de classement et de récompense sur plusieurs emplacements.
Dans le portail Azure, accédez à la page Configuration de votre ressource Personalizer et passez la fréquence de mise à jour du modèle à 30 secondes. Ainsi, l’apprentissage du modèle est effectué rapidement, ce qui vous permet de voir comment l’action recommandée change pour chaque itération.
Dans le portail Azure, accédez à la page Configuration de votre ressource Personalizer et passez le temps d’attente de la récompense à 10 minutes. Cela détermine combien de temps le modèle doit attendre avant de recevoir des commentaires de récompense de la recommandation qui a été envoyée. L’apprentissage ne peut avoir lieu tant que le temps d’attente de la récompense n’est pas écoulé.
Créez un fichier Python et des variables pour le point de terminaison et la clé d’abonnement de votre ressource.
Important
Accédez au portail Azure. Si la ressource Personalizer que vous avez créée dans la section Prérequis a été déployée, cliquez sur le bouton Accéder à la ressource sous Étapes suivantes. La clé et le point de terminaison se trouvent dans la page Clé et point de terminaison de la ressource, sous Gestion des ressources.
N’oubliez pas de supprimer la clé de votre code une fois que vous avez terminé, et ne la postez jamais publiquement. Pour la production, envisagez d’utiliser une méthode de stockage et d’accès sécurisée pour vos informations d’identification. Par exemple, Azure Key Vault.
import json, uuid, requests
# The endpoint specific to your personalization service instance;
# e.g. https://<your-resource-name>.cognitiveservices.azure.com
PERSONALIZATION_BASE_URL = "<REPLACE-WITH-YOUR-PERSONALIZER-ENDPOINT>"
# The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF"
RESOURCE_KEY = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>"
Pour demander le seul meilleur élément du contenu pour chaque emplacement, créez un rank_request, puis envoyez une demande de publication au point de terminaison multislot/rank. La réponse est ensuite analysée dans un rank_response.
Pour envoyer un score de récompense à Personalizer, créez un rewards, puis envoyez une demande de publication à multislot/events/{eventId}/reward.
Dans ce guide de démarrage rapide, il est facile de déterminer le score de récompense. Dans un système de production, déterminer les éléments ayant un impact sur le score de récompense (et dans quelle mesure) peut être un processus complexe, que vous pouvez décider de modifier au fil du temps. Cette décision de conception doit être l’une des principales décisions à prendre pour votre architecture Personalizer.
Ces extraits de code vous montrent comment effectuer les tâches suivantes en envoyant des requêtes HTTP pour Python :
Dans cette section, vous allez construire les URL de classement/récompense à l’aide de l’URL de base et des en-têtes de demande à l’aide de la clé de ressource.
MULTI_SLOT_RANK_URL = '{0}personalizer/v1.1-preview.1/multislot/rank'.format(PERSONALIZATION_BASE_URL)
MULTI_SLOT_REWARD_URL_BASE = '{0}personalizer/v1.1-preview.1/multislot/events/'.format(PERSONALIZATION_BASE_URL)
HEADERS = {
'ocp-apim-subscription-key': RESOURCE_KEY,
'Content-Type': 'application/json'
}
Les actions représentent les choix de contenu parmi lesquels Personalizer doit sélectionner l’élément de contenu le mieux adapté. Ajoutez les méthodes suivantes au script pour représenter l’ensemble d’actions et leurs caractéristiques.
def get_actions():
return [
{
"id": "Red-Polo-Shirt-432",
"features": [
{
"onSale": "true",
"price": 20,
"category": "Clothing"
}
]
},
{
"id": "Tennis-Racket-133",
"features": [
{
"onSale": "false",
"price": 70,
"category": "Sports"
}
]
},
{
"id": "31-Inch-Monitor-771",
"features": [
{
"onSale": "true",
"price": 200,
"category": "Electronics"
}
]
},
{
"id": "XBox-Series X-117",
"features": [
{
"onSale": "false",
"price": 499,
"category": "Electronics"
}
]
}
]
Ajoutez les méthodes suivantes au script pour obtenir une entrée d’utilisateur à partir de la ligne de commande pour l’heure de la journée et le type d’appareil sur lequel se trouve l’utilisateur. Elles seront utilisées comme des caractéristiques de contexte.
def get_context_features():
time_features = ["morning", "afternoon", "evening", "night"]
time_pref = input("What time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night\n")
try:
parsed_time = int(time_pref)
if(parsed_time <=0 or parsed_time > len(time_features)):
raise IndexError
time_of_day = time_features[parsed_time-1]
except (ValueError, IndexError):
print("Entered value is invalid. Setting feature value to", time_features[0] + ".")
time_of_day = time_features[0]
device_features = ['mobile', 'tablet', 'desktop']
device_pref = input("What type of device is the user on (enter number)? 1. mobile 2. tablet 3. desktop\n")
try:
parsed_device = int(device_pref)
if(parsed_device <=0 or parsed_device > len(device_features)):
raise IndexError
device = device_features[parsed_device-1]
except (ValueError, IndexError):
print("Entered value is invalid. Setting feature value to", device_features[0]+ ".")
device = device_features[0]
return [
{'time': time_of_day},
{'device': device}
]
Les emplacements constituent la page avec laquelle l’utilisateur interagit. Personalizer décidera de l’action à afficher dans chacun des emplacements définis. Les actions peuvent être exclues d’emplacements spécifiques, comme ExcludeActions
. BaselineAction
est l’action par défaut pour l’emplacement qui aurait été affiché sans l’utilisation de Personalizer.
Ce guide de démarrage rapide offre des fonctionnalités d’emplacement simples. Dans les systèmes de production, il peut être important de déterminer et d’évaluer les caractéristiques.
def get_slots():
return [
{
"id": "BigHeroPosition",
"features": [
{
"size": "large",
"position": "left",
}
],
"excludedActions": ["31-Inch-Monitor-771"],
"baselineAction": "Red-Polo-Shirt-432"
},
{
"id": "SmallSidebar",
"features": [
{
"size": "small",
"position": "right",
}
],
"excludedActions": ["Tennis-Racket-133"],
"baselineAction": "XBox-Series X-117"
}
]
Ajoutez ces fonctions pour envoyer des requêtes de publication au point de terminaison Personalizer pour les appels de classement et de récompense à plusieurs emplacements.
def send_multi_slot_rank(rank_request):
multi_slot_response = requests.post(MULTI_SLOT_RANK_URL, data=json.dumps(rank_request), headers=HEADERS)
if multi_slot_response.status_code != 201:
raise Exception(multi_slot_response.text)
return json.loads(multi_slot_response.text)
def send_multi_slot_reward(reward_request, event_id):
reward_url = '{0}{1}/reward'.format(MULTI_SLOT_REWARD_URL_BASE, event_id)
requests.post(reward_url, data=json.dumps(reward_request), headers=HEADERS)
Ajoutez la méthode suivante au script. L’invite de la ligne de commande vous indiquera si Personalizer a pris une bonne décision pour chaque emplacement.
def get_reward_for_slot():
answer = input('\nIs this correct? (y/n)\n').upper()
if (answer == 'Y'):
print('\nGreat! The application will send Personalizer a reward of 1 so it learns from this choice of action for this slot.\n')
return 1
elif (answer == 'N'):
print('\nYou didn\'t like the recommended item.The application will send Personalizer a reward of 0 for this choice of action for this slot.\n')
return 0
print('\nEntered choice is invalid. Service assumes that you didn\'t like the recommended item.\n')
return 0
La boucle d’apprentissage Personalizer est un cycle d’appels aux API Rank et Reward. Dans ce guide de démarrage rapide, chaque appel Rank en vue de personnaliser le contenu est suivi d’un appel Reward qui indique à Personalizer l’efficacité du service.
Le code ci-après applique, en boucle, le cycle suivant : il demande à l’utilisateur d’indiquer ses préférences à partir de la ligne de commande, il envoie ces informations à Personalizer en vue de sélectionner le contenu le mieux adapté pour chaque emplacement, il présente la sélection au client qui peut faire son choix dans la liste, puis il envoie un score de récompense à Personalizer, en indiquant l’efficacité du service concernant le choix du contenu.
run_loop = True
while run_loop:
eventId = str(uuid.uuid4())
context = get_context_features()
actions = get_actions()
slots = get_slots()
rank_request = {
"eventId": eventId,
"contextFeatures": context,
"actions": actions,
"slots": slots,
"deferActivation": False
}
#Rank the actions for each slot
multi_slot_rank_response = send_multi_slot_rank(rank_request)
multi_slot_rewards = {"reward": []}
for i in range(len(multi_slot_rank_response['slots'])):
print('\nPersonalizer service decided you should display: {0} in slot {1}\n'.format(multi_slot_rank_response['slots'][i]['rewardActionId'], multi_slot_rank_response['slots'][i]['id']))
slot_reward = {'slotId': multi_slot_rank_response['slots'][i]['id']}
# User agrees or disagrees with Personalizer decision for slot
slot_reward['value'] = get_reward_for_slot()
multi_slot_rewards['reward'].append(slot_reward)
# Send the rewards for the event
send_multi_slot_reward(multi_slot_rewards, multi_slot_rank_response['eventId'])
answer = input('\nPress q to break, any other key to continue:\n').upper()
if (answer == 'Q'):
run_loop = False
Dans les sections suivantes, examinez de plus près les appels de classement et de récompense.
Ajoutez les méthodes suivantes, qui permettent d’obtenir les choix de contenu, d’obtenir les préférences de l’utilisateur pour le contexte, d’obtenir les emplacements, d’exécuter des requêtes HTTP, d’obtenir une récompense pour chaque emplacement avant d’exécuter le fichier de code :
Pour traiter la requête Rank, le programme demande les préférences de l’utilisateur pour créer des choix de contenu. Le corps de la requête contient le contexte, les actions et les emplacements avec leurs caractéristiques respectives. La méthode send_multi_slot_rank
prend un rankRequest et exécute la demande de classement sur plusieurs emplacements.
Ce guide de démarrage rapide utilise des caractéristiques de contexte simples basées sur l’heure de la journée et l’appareil de l’utilisateur. Dans les systèmes de production, il peut être important de déterminer et d’évaluer les actions et caractéristiques.
eventId = str(uuid.uuid4())
context = get_context_features()
actions = get_actions()
slots = get_slots()
rank_request = {
"eventId": eventId,
"contextFeatures": context,
"actions": actions,
"slots": slots,
"deferActivation": False
}
#Rank the actions for each slot
multi_slot_rank_response = send_multi_slot_rank(rank_request)
Pour obtenir le score de récompense pour la requête Reward, le programme récupère la sélection de l’utilisateur pour chaque emplacement à partir de la ligne de commande, attribue une valeur numérique (score de récompense) à la sélection, puis envoie à la méthode send_multi_slot_reward
l’ID d’événement unique et le score de récompense pour chaque emplacement. Une récompense n’a pas besoin d’être définie pour chaque emplacement.
Dans le cadre de ce guide de démarrage rapide, un simple numéro est attribué en tant que score de récompense : 0 ou 1. Dans les systèmes de production, il peut être important de déterminer ce qui doit être envoyé à l’appel Reward (et à quel moment) selon vos besoins.
multi_slot_rewards = {"reward": []}
for i in range(len(multi_slot_rank_response['slots'])):
print('\nPersonalizer service decided you should display: {0} in slot {1}\n'.format(multi_slot_rank_response['slots'][i]['rewardActionId'], multi_slot_rank_response['slots'][i]['id']))
slot_reward = {'slotId': multi_slot_rank_response['slots'][i]['id']}
# User agrees or disagrees with Personalizer decision for slot
slot_reward['value'] = get_reward_for_slot()
multi_slot_rewards['reward'].append(slot_reward)
# Send the rewards for the event
send_multi_slot_reward(multi_slot_rewards, multi_slot_rank_response['eventId'])
Exécutez l’application avec Python à partir de votre répertoire d’application.
python sample.py
Le code source associé à ce guide de démarrage rapide est disponible.
Entrainement
Module
Formuler des suggestions avec Azure AI Personalizer - Training
Dans ce module, découvrez comment utiliser Azure AI Personalizer pour formuler des recommandations.
Documentation
Gérer les paramètres de modèle et d’apprentissage – Personalizer - Azure AI services
Les paramètres d’apprentissage et de modèle d’apprentissage automatique peuvent être exportés à des fins de sauvegarde dans votre propre système de contrôle de code source.
Configurer Personalizer - Azure AI services
La configuration du service porte sur la façon dont le service traite les récompenses, la fréquence à laquelle le service effectue une exploration, la fréquence à laquelle le modèle est réentraîné et la quantité de données stockées.
Mode Apprenti - Personalizer - Azure AI services
Découvrez comment utiliser le mode Apprenti pour gagner en confiance dans un modèle sans modifier le code.