Prise en main du kit de développement logiciel (SDK) d’inférence locale pour Azure AI Personalizer
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.
Le Kit de développement logiciel (SDK) d’inférence locale Personalizer (préversion) télécharge le modèle Personalizer localement, ce qui réduit sensiblement la latence des appels de classement en éliminant les appels réseau. Chaque minute, le client télécharge le modèle le plus récent en arrière-plan et l’utilise pour l’inférence.
Ce guide explique comment utiliser le Kit de développement logiciel (SDK) d’inférence locale Personalizer.
Vous devez installer la bibliothèque cliente Personalizer pour .NET sur :
- Authentifiez l’exemple de client de démarrage rapide avec une ressource Personalizer dans Azure.
- Envoyer des fonctionnalités de contexte et d’action à l’API Reward, qui retourne la meilleure action du modèle Personalizer
- Envoyez un score de récompense à l’API Rank et entraînez le modèle Personalizer.
Documentation de référence | Code source de la bibliothèque | Package (NuGet)
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. Vous collerez 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
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
Conseil
Si vous utilisez l’IDE Visual Studio, la bibliothèque de client est disponible sous forme de package NuGet téléchargeable.
À partir du répertoire de projet, ouvrez le fichier Program.cs dans votre éditeur ou IDE favori. Ajoutez les directives using suivantes :
using Azure;
using Azure.AI.Personalizer;
using System;
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 pour afficher l’utilisateur, créez un PersonalizerRankOptions, puis passez-le à la méthode PersonalizerClient.Rank. La méthode de classement retourne un PersonalizerRankResult.
Pour envoyer un score de récompense à Personalizer, transmettez l’ID d’événement et le score de récompense à la méthode PersonalizerClient.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 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.
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. Notez que la définition useLocalInference: true en tant que paramètre pour PersonalizerClientOptions est nécessaire pour activer l’inférence locale.
static PersonalizerClient InitializePersonalizerClient(Uri url)
{
// Set the local inference flag to true when initializing the client.
return new PersonalizerClient(url, new AzureKeyCredential(ResourceKey), new PersonalizerClientOptions(useLocalInference: true));
}
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.
static IList<PersonalizerRankableAction> GetActions()
{
IList<PersonalizerRankableAction> actions = new List<PersonalizerRankableAction>
{
new PersonalizerRankableAction(
id: "pasta",
features: new List<object>() { new { taste = "salty", spiceLevel = "medium" }, new { nutritionLevel = 5, cuisine = "italian" } }
),
new PersonalizerRankableAction(
id: "ice cream",
features: new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionalLevel = 2 } }
),
new PersonalizerRankableAction(
id: "juice",
features: new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionLevel = 5 }, new { drink = true } }
),
new PersonalizerRankableAction(
id: "salad",
features: new List<object>() { new { taste = "salty", spiceLevel = "low" }, new { nutritionLevel = 8 } }
)
};
return actions;
}
Obtenir les préférences utilisateur pour le contexte
Ajoutez les méthodes suivantes à la classe Program pour obtenir les entrées d’un utilisateur à partir de la ligne de commande pour l’heure de la journée et la préférence de l’utilisateur. Elles seront utilisées comme des caractéristiques 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 GetUsersTastePreference()
{
string[] tasteFeatures = new string[] { "salty", "sweet" };
var random = new Random();
var taste = random.Next(1, 2);
Console.WriteLine("\nWhat type of food would you prefer (enter number)? 1. salty 2. sweet");
if (!int.TryParse(GetKey(), out int tasteIndex) || tasteIndex < 1 || tasteIndex > tasteFeatures.Length)
{
Console.WriteLine("\nEntered value is invalid. Setting feature value to " + tasteFeatures[0] + ".");
tasteIndex = 1;
}
return tasteFeatures[taste - 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 taste)
{
return new List<object>()
{
new { time = time },
new { taste = taste }
};
}
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.
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 (rank and reward).\n" +
$"Each iteration represents a user interaction and will demonstrate how context, actions, 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();
PersonalizerClient client = InitializePersonalizerClient(new Uri(ServiceEndpoint));
do
{
Console.WriteLine("\nIteration: " + iteration++);
string timeOfDayFeature = GetTimeOfDayForContext();
string deviceFeature = GetUsersTastePreference();
IList<object> currentContext = GetContext(timeOfDayFeature, deviceFeature);
string eventId = Guid.NewGuid().ToString();
var rankOptions = new PersonalizerRankOptions(actions: actions, contextFeatures: currentContext, eventId: eventId);
PersonalizerRankResult rankResult = client.Rank(rankOptions);
Console.WriteLine("\nPersonalizer service thinks you would like to have: " + rankResult.RewardActionId + ". Is this correct? (y/n)");
float reward = 0.0f;
string answer = GetKey();
if (answer == "Y")
{
reward = 1.0f;
Console.WriteLine("\nGreat! Enjoy your food.");
}
else if (answer == "N")
{
reward = 0.0f;
Console.WriteLine("\nYou didn't like the recommended food choice.");
}
else
{
Console.WriteLine("\nEntered choice is invalid. Service assumes that you didn't like the recommended food choice.");
}
client.Reward(rankResult.EventId, reward);
Console.WriteLine("\nPress q to break, any other key to continue:");
runLoop = !(GetKey() == "Q");
} while (runLoop);
}
Exécuter le programme
Exécutez l’application avec la commande run dotnet à partir de votre répertoire d’application.
dotnet run
