Prise en main de la fonctionnalité multi-emplacement pour Azure AI Personalizer

Documentation de référence | Code source de la bibliothèque | Package (NuGet) | Informations conceptuelles sur les emplacements multiples | Exemples

Prérequis

• Abonnement Azure - En créer un gratuitement
• Version actuelle de .NET Core
• Une fois que vous avez votre abonnement Azure, créez une ressource Personalizer dans le portail Azure pour obtenir votre clé et votre point de terminaison. À la fin du déploiement, sélectionnez Accéder à la ressource.
  • Vous aurez besoin de la clé et du point de terminaison de la ressource que vous créez pour connecter votre application à l’API Personalizer. Collez votre clé et votre point de terminaison dans le code ci-dessous, plus loin dans le guide de démarrage rapide.
  • Vous pouvez utiliser le niveau tarifaire Gratuit (F0) pour tester le service, puis passer par la suite à un niveau payant pour la production.

Configuration

Mettre à niveau une instance Personalizer sur plusieurs emplacements

1. Désactivez l’optimisation automatique dans le portail Azure : dans la ressource Personalizer, sous Gestion des ressources, sur la page Paramètres de modèle et d’apprentissage, désactivez l’optimisation automatique et enregistrez.

2. Mettez à jour Personalizer sur plusieurs emplacements dans le portail Azure : dans la ressource Personalizer, sous Gestion des ressources, sur la page Paramètres de modèle et d’apprentissage, sélectionnez Exporter les paramètres d’apprentissage. Le champ arguments du fichier json téléchargé commencera par --cb_explore_adf. Remplacez cette valeur par --ccb_explore_adf et enregistrez le fichier. CB (Contextual Bandits) et CCB (Conditional Contextual Bandits) sont les algorithmes que Personalizer utilise pour la personnalisation à un seul emplacement et sur plusieurs emplacements, respectivement. Les ADF (fonctionnalités dépendantes d’action) signifient que les actions sont exprimées/identifiées avec des fonctionnalités.

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.

Changer la fréquence de mise à jour du modèle

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.

Modifier le temps d’attente de la récompense

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éer une application C#

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)
...

Installer la bibliothèque de client

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;

Modèle objet

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.

Exemples de code

Ces extraits de code montrent comment effectuer les tâches suivantes avec la bibliothèque de client Personalizer pour .NET :

• Créer un client Personalizer
• API Multi-Slot Rank
• API Multi-Slot Reward

Authentifier le client

Dans cette section, vous allez effectuer deux opérations :

• Spécifier votre clé et votre point de terminaison
• Créer un client Personalizer

Commencez par ajouter les lignes suivantes à votre classe Program. Veillez à ajouter votre clé et votre point de terminaison à partir de votre ressource Personalizer.

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));
}

Représenter les choix de contenu sous forme d’actions

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;
}

Accéder aux emplacements

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;
}

Obtenir les préférences utilisateur pour le contexte

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 }
    };
}

Créer la boucle d’apprentissage

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

Demander l’action la mieux adaptée

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);

Envoyer une récompense

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écuter le programme

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

Prérequis

• Abonnement Azure - En créer un gratuitement
• Installez Node.js et NPM (vérifié avec Node.js v14.16.0 et NPM 6.14.11).
• Une fois que vous avez votre abonnement Azure, créez une ressource Personalizer dans le portail Azure pour obtenir votre clé et votre point de terminaison. À la fin du déploiement, sélectionnez Accéder à la ressource.
  • Vous aurez besoin de la clé et du point de terminaison de la ressource que vous créez pour connecter votre application à l’API Personalizer. Collez votre clé et votre point de terminaison dans le code ci-dessous, plus loin dans le guide de démarrage rapide.
  • Vous pouvez utiliser le niveau tarifaire Gratuit (F0) pour tester le service, puis passer par la suite à un niveau payant pour la production.

Configuration

Mettre à niveau une instance Personalizer sur plusieurs emplacements

1. Désactivez l’optimisation automatique dans le portail Azure : dans la ressource Personalizer, sous Gestion des ressources, sur la page Paramètres de modèle et d’apprentissage, désactivez l’optimisation automatique et enregistrez.

2. Mettez à jour Personalizer sur plusieurs emplacements dans le portail Azure : dans la ressource Personalizer, sous Gestion des ressources, sur la page Paramètres de modèle et d’apprentissage, sélectionnez Exporter les paramètres d’apprentissage. Le champ arguments du fichier json téléchargé commencera par --cb_explore_adf. Remplacez cette valeur par --ccb_explore_adf et enregistrez le fichier. CB (Contextual Bandits) et CCB (Conditional Contextual Bandits) sont les algorithmes que Personalizer utilise pour la personnalisation à un seul emplacement et sur plusieurs emplacements, respectivement. Les ADF (fonctionnalités dépendantes d’action) signifient que les actions sont exprimées/identifiées avec des fonctionnalités.

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.

Changer la fréquence de mise à jour du modèle

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.

Modifier le temps d’attente de la récompense

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éation d’une application Node.js

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.

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>';

Installer les packages NPM pour le démarrage rapide

npm install readline-sync uuid axios --save

Modèle objet

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.

Exemples de code

Ces extraits de code vous montrent comment effectuer les tâches suivantes en envoyant des requêtes HTTP pour NodeJS :

• Créer des URL de base
• API Rank
• API Reward

Créer des URL de base

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'
};

Représenter les choix de contenu sous forme d’actions

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'
                }
            ]
        }
    ];
}

Obtenir les préférences utilisateur pour le contexte

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
        }
    ];
}

Accéder aux emplacements

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'
        }
    ];
}

Effectuer des requêtes HTTP

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;
    }
}

Obtenir des commentaires pour les décisions de Personalizer

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;
}

Créer la boucle d’apprentissage

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 :

• getActions
• getContextFeatures
• getSlots
• sendRank
• sendReward
• getRewardForSlot

Demander l’action la mieux adaptée

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;
}

Envoyer une récompense

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écuter le programme

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

Prérequis

• Abonnement Azure - En créer un gratuitement
• Python 3.x
• Une fois que vous avez votre abonnement Azure, créez une ressource Personalizer dans le portail Azure pour obtenir votre clé et votre point de terminaison. À la fin du déploiement, sélectionnez Accéder à la ressource.
  • Vous aurez besoin de la clé et du point de terminaison de la ressource que vous créez pour connecter votre application à l’API Personalizer. Collez votre clé et votre point de terminaison dans le code ci-dessous, plus loin dans le guide de démarrage rapide.
  • Vous pouvez utiliser le niveau tarifaire Gratuit (F0) pour tester le service, puis passer par la suite à un niveau payant pour la production.

Configuration

Mettre à niveau une instance Personalizer sur plusieurs emplacements

1. Désactivez l’optimisation automatique dans le portail Azure : dans la ressource Personalizer, sous Gestion des ressources, sur la page Paramètres de modèle et d’apprentissage, désactivez l’optimisation automatique et enregistrez.

2. Mettez à jour Personalizer sur plusieurs emplacements dans le portail Azure : dans la ressource Personalizer, sous Gestion des ressources, sur la page Paramètres de modèle et d’apprentissage, sélectionnez Exporter les paramètres d’apprentissage. Le champ arguments du fichier json téléchargé commencera par --cb_explore_adf. Remplacez cette valeur par --ccb_explore_adf et enregistrez le fichier. CB (Contextual Bandits) et CCB (Conditional Contextual Bandits) sont les algorithmes que Personalizer utilise pour la personnalisation à un seul emplacement et sur plusieurs emplacements, respectivement. Les ADF (fonctionnalités dépendantes d’action) signifient que les actions sont exprimées/identifiées avec des fonctionnalités.

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.

Changer la fréquence de mise à jour du modèle

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.

Modifier le temps d’attente de la récompense

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éer une application Python

Créez un fichier Python et des variables pour le point de terminaison et la clé d’abonnement de votre ressource.

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>"

Modèle objet

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.

Exemples de code

Ces extraits de code vous montrent comment effectuer les tâches suivantes en envoyant des requêtes HTTP pour Python :

• Créer des URL de base
• API Rank
• API Reward

Créer des URL de base

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'
}

Représenter les choix de contenu sous forme d’actions

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"
                }
            ]
        }
    ]

Obtenir les préférences utilisateur pour le contexte

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}
        ]

Accéder aux emplacements

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"
        }
    ]

Effectuer des requêtes HTTP

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)

Obtenir des commentaires pour les décisions de Personalizer

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

Créer la boucle d’apprentissage

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 :

• get_actions
• get_context_features
• get_slots
• send_rank
• send_reward
• get_reward_for_dsot

Demander l’action la mieux adaptée

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)

Envoyer une récompense

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écuter le programme

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.