Schnellstart: Personalisierungsclientbibliothek
Wichtig
Ab dem 20. September 2023 können Sie keine neuen Personalisierungsressourcen mehr erstellen. Der Personalisierungsdienst wird am 1. Oktober 2026 eingestellt.
Starten Sie mit den Clientbibliotheken für die Azure KI Personalisierung, und richten Sie eine grundlegende Lernschleife ein. Eine Lernschleife ist ein System aus Entscheidungen und Feedback: Eine Anwendung fordert vom Dienst ein Entscheidungsranking an, verwendet dann die bestplatzierte Wahl und errechnet aus dem Ergebnis eine Relevanzbewertung. Sie gibt die Relevanzbewertung an den Dienst zurück. Im Laufe der Zeit verwendet die Personalisierung KI-Algorithmen, um bessere Entscheidungen für einen bestimmten Kontext zu treffen. Folgen Sie diesen Schritten, um eine Beispielanwendung einzurichten.
Beispielszenario
In diesem Schnellstart möchte ein Onlineeinzelhändler seinen Umsatz steigern, indem er jedem Kunden auf seiner Website relevante und personalisierte Produkte anzeigt. Auf der Hauptseite gibt es einen Abschnitt für ein empfohlenes Produkt, in dem potenziellen Kunden ein fertiges Gericht angezeigt wird. Der Onlineeinzelhändler möchte herausfinden, wie er dem richtigen Kunden das richtige Produkt zeigen kann, um die Wahrscheinlichkeit eines Kaufs zu maximieren.
Der Personalisierungsdienst löst dieses Problem auf automatisierte, skalierbare und anpassbare Weise mithilfe des vertiefenden Lernens. Sie werden erfahren, wie Sie Aktionen und deren Features, Kontextfeatures und Relevanzbewertungen erstellen können. Sie verwenden die Personalisierungsclientbibliothek für Aufrufe der Rangfolge- und Relevanz-API.
Referenzdokumentation | Bibliothek-Quellcode | Paket (NuGet) | .NET-Codebeispiel
Voraussetzungen
- Azure-Abonnement – Erstellen eines kostenlosen Kontos
- Aktuelle Version von .NET Core.
- Sobald Sie über Ihr Azure-Abonnement verfügen, sollten Sie im Azure-Portal eine Personalisierung-Ressource erstellen, um Ihren Schlüssel und Endpunkt abzurufen. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
- Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Personalisierungs-API zu verbinden. Der Schlüssel und der Endpunkt werden weiter unten in der Schnellstartanleitung in den Code eingefügt.
- Sie können den kostenlosen Tarif (
F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.
Modellkonfiguration
Ändern der Häufigkeit der Modellaktualisierung
Wechseln Sie im Azure-Portal zur Seite Konfiguration Ihrer Personalisierungsressource, und ändern Sie Häufigkeit der Modellaktualisierung auf 30 Sekunden. Mit dieser kurzen Dauer wird das Modell schnell trainiert, und Sie können sehen, wie sich die empfohlene Aktion für jede Iteration ändert.
Ändern der Belohnungswartezeit
Wechseln Sie im Azure-Portal zur Seite Konfiguration Ihrer Personalisierungsressource, und ändern Sie die Belohnungswartezeit in 10 Minuten. Dadurch wird bestimmt, wie lange das Modell nach dem Senden einer Empfehlung wartet, um das Belohnungsfeedback für diese Empfehlung zu erhalten. Das Training findet erst statt, wenn die Belohnungswartezeit verstrichen ist.
Erstellen einer neuen C#-Anwendung
Erstellen Sie eine neue .NET Core-Anwendung in Ihrem bevorzugten Editor oder Ihrer bevorzugten IDE.
Verwenden Sie in einem Konsolenfenster (z. B. cmd, PowerShell oder Bash) den Befehl dotnet new zum Erstellen einer neuen Konsolen-App mit dem Namen personalizer-quickstart. Dieser Befehl erstellt ein einfaches „Hallo Welt“-C#-Projekt mit einer einzigen Quelldatei: Program.cs.
dotnet new console -n personalizer-quickstart
Wechseln Sie zum Ordner der neu erstellten App. Erstellen Sie dann die Anwendung mit folgendem Befehl:
dotnet build
Die Buildausgabe sollte keine Warnungen oder Fehler enthalten.
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
Installieren der Clientbibliothek
Installieren Sie im Anwendungsverzeichnis mit dem folgenden Befehl die Personalisierungsclientbibliothek für .NET:
dotnet add package Microsoft.Azure.CognitiveServices.Personalizer --version 1.0.0
Tipp
Bei Verwendung der Visual Studio-IDE ist die Clientbibliothek als herunterladbares NuGet-Paket verfügbar.
Codeblock 1: Generieren von Beispieldaten
Die Personalisierung ist für die Ausführung in Anwendungen gedacht, die Echtzeitdaten empfangen und interpretieren. In diesem Schnellstart verwenden Sie Beispielcode, um imaginäre Aktionen von Kunden auf einer Website für Lebensmittelgeschäfte zu generieren. Der folgende Codeblock definiert drei wichtige Methoden: GetActions, GetContext und GetRewardScore.
GetActions gibt eine Liste der Optionen zurück, die die Website für Lebensmittelgeschäfte für die Bewertung benötigt. In diesem Beispiel sind die Aktionen Nahrungsprodukte. Jede Aktionsauswahl verfügt über Details (Features), die das spätere Verhalten des Benutzers beeinflussen können. Aktionen werden als Eingabe für die Bewertungs-API verwendet.
GetContext gibt einen simulierten Besuch eines Kunden zurück. Es wählt nach dem Zufallsprinzip Details aus (Kontextfeatures), z. B. welcher Kunde anwesend ist und zu welcher Tageszeit der Besuch erfolgt. Im Allgemeinen stellt ein Kontext den aktuellen Zustand Ihrer Anwendung, Ihres Systems, Ihrer Umgebung oder Ihres Benutzers dar. Das Kontextobjekt wird als Eingabe für die Bewertungs-API verwendet.
Die Kontextfeatures in diesem Schnellstart sind sehr einfach gehalten. In einem echten Produktionssystem ist es jedoch wichtig, Ihre Features zu entwerfen und ihre Wirksamkeit zu bewerten. Eine Anleitung finden Sie in der verlinkten Dokumentation.
GetRewardScore gibt einen Wert zwischen null und eins zurück, der den Erfolg einer Interaktion mit einem Kunden darstellt. Es verwendet eine einfache Logik, um festzustellen, wie verschiedene Kontexte auf verschiedene Aktionsoptionen reagieren. Ein bestimmter Benutzer wird z. B. immer eine 1,0 für vegetarische und vegane Produkte vergeben und eine 0,0 für andere Produkte. In einem echten Szenario lernt die Personalisierung Benutzerpräferenzen anhand der Daten, die in Rangfolge- und Relevanz-API-Aufrufen gesendet werden. Sie werden nicht wie im Beispielcode explizit definiert.
In einem echten Produktionssystem muss die Relevanzbewertung auf Ihre Geschäftsziele und KPIs abgestimmt werden. Die Ermittlung, wie Sie die Metrik für die Relevanz berechnen können, erfordert möglicherweise ein gewisses Experimentieren.
Im Code weiter unten sind zu Demonstrationszwecken die Präferenzen der Benutzer sowie ihre Reaktionen auf die Aktionen als eine Reihe bedingter Anweisungen hartcodiert. Außerdem enthält der Code erklärenden Text.
Finden Sie Ihren Schlüssel und Endpunkt.
Wichtig
Öffnen Sie das Azure-Portal. Wenn die im Abschnitt Voraussetzungen erstellte Personalisierungsressource erfolgreich bereitgestellt wurde, klicken Sie unter Nächste Schritte auf die Schaltfläche Zu Ressource wechseln. Schlüssel und Endpunkt finden Sie auf der Seite mit dem Schlüssel und dem Endpunkt der Ressource unter Ressourcenverwaltung.
Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. In der Produktionsumgebung sollten Sie eine sichere Methode zum Speichern Ihrer Anmeldeinformationen sowie zum Zugriff darauf verwenden. Beispielsweise Azure Key Vault.
Öffnen Sie Program.cs in einem Text-Editor oder einer IDE, und fügen Sie den folgenden Code ein.
using Microsoft.Azure.CognitiveServices.Personalizer; using Microsoft.Azure.CognitiveServices.Personalizer.Models; class Program { private static readonly string ApiKey = "REPLACE_WITH_YOUR_PERSONALIZER_KEY"; private static readonly string ServiceEndpoint = "REPLACE_WITH_YOUR_ENDPOINT_URL"; static PersonalizerClient InitializePersonalizerClient(string url) { PersonalizerClient client = new PersonalizerClient( new ApiKeyServiceClientCredentials(ApiKey)) { Endpoint = url }; return client; } static Dictionary<string, ActionFeatures> actions = new Dictionary<string, ActionFeatures> { {"pasta", new ActionFeatures( new BrandInfo(company: "pasta_inc"), new ItemAttributes( quantity: 1, category: "Italian", price: 12), new DietaryAttributes( vegan: false, lowCarb: false, highProtein: false, vegetarian: false, lowFat: true, lowSodium: true))}, {"bbq", new ActionFeatures( new BrandInfo(company: "ambisco"), new ItemAttributes( quantity: 2, category: "bbq", price: 20), new DietaryAttributes( vegan: false, lowCarb: true, highProtein: true, vegetarian: false, lowFat: false, lowSodium: false))}, {"bao", new ActionFeatures( new BrandInfo(company: "bao_and_co"), new ItemAttributes( quantity: 4, category: "Chinese", price: 8), new DietaryAttributes( vegan: false, lowCarb: true, highProtein: true, vegetarian: false, lowFat: true, lowSodium: false))}, {"hummus", new ActionFeatures( new BrandInfo(company: "garbanzo_inc"), new ItemAttributes( quantity: 1, category: "Breakfast", price: 5), new DietaryAttributes( vegan: true, lowCarb: false, highProtein: true, vegetarian: true, lowFat: false, lowSodium: false))}, {"veg_platter", new ActionFeatures( new BrandInfo(company: "farm_fresh"), new ItemAttributes( quantity: 1, category: "produce", price: 7), new DietaryAttributes( vegan: true, lowCarb: true, highProtein: false, vegetarian: true, lowFat: true, lowSodium: true ))}, }; static IList<RankableAction> GetActions() { IList<RankableAction> rankableActions = new List<RankableAction>(); foreach (var action in actions) { rankableActions.Add(new RankableAction { Id = action.Key, Features = new List<object>() { action.Value } }); } return rankableActions; } public class BrandInfo { public string Company { get; set; } public BrandInfo(string company) { Company = company; } } public class ItemAttributes { public int Quantity { get; set; } public string Category { get; set; } public double Price { get; set; } public ItemAttributes(int quantity, string category, double price) { Quantity = quantity; Category = category; Price = price; } } public class DietaryAttributes { public bool Vegan { get; set; } public bool LowCarb { get; set; } public bool HighProtein { get; set; } public bool Vegetarian { get; set; } public bool LowFat { get; set; } public bool LowSodium { get; set; } public DietaryAttributes(bool vegan, bool lowCarb, bool highProtein, bool vegetarian, bool lowFat, bool lowSodium) { Vegan = vegan; LowCarb = lowCarb; HighProtein = highProtein; Vegetarian = vegetarian; LowFat = lowFat; LowSodium = lowSodium; } } public class ActionFeatures { public BrandInfo BrandInfo { get; set; } public ItemAttributes ItemAttributes { get; set; } public DietaryAttributes DietaryAttributes { get; set; } public ActionFeatures(BrandInfo brandInfo, ItemAttributes itemAttributes, DietaryAttributes dietaryAttributes) { BrandInfo = brandInfo; ItemAttributes = itemAttributes; DietaryAttributes = dietaryAttributes; } } public static Context GetContext() { return new Context( user: GetRandomUser(), timeOfDay: GetRandomTimeOfDay(), location: GetRandomLocation(), appType: GetRandomAppType()); } static string[] timesOfDay = new string[] { "morning", "afternoon", "evening" }; static string[] locations = new string[] { "west", "east", "midwest" }; static string[] appTypes = new string[] { "edge", "safari", "edge_mobile", "mobile_app" }; static IList<UserProfile> users = new List<UserProfile> { new UserProfile( name: "Bill", dietaryPreferences: new Dictionary<string, bool> { { "low_carb", true } }, avgOrderPrice: "0-20"), new UserProfile( name: "Satya", dietaryPreferences: new Dictionary<string, bool> { { "low_sodium", true} }, avgOrderPrice: "201+"), new UserProfile( name: "Amy", dietaryPreferences: new Dictionary<string, bool> { { "vegan", true }, { "vegetarian", true } }, avgOrderPrice: "21-50") }; static string GetRandomTimeOfDay() { var random = new Random(); var timeOfDayIndex = random.Next(timesOfDay.Length); Console.WriteLine($"TimeOfDay: {timesOfDay[timeOfDayIndex]}"); return timesOfDay[timeOfDayIndex]; } static string GetRandomLocation() { var random = new Random(); var locationIndex = random.Next(locations.Length); Console.WriteLine($"Location: {locations[locationIndex]}"); return locations[locationIndex]; } static string GetRandomAppType() { var random = new Random(); var appIndex = random.Next(appTypes.Length); Console.WriteLine($"AppType: {appTypes[appIndex]}"); return appTypes[appIndex]; } static UserProfile GetRandomUser() { var random = new Random(); var userIndex = random.Next(users.Count); Console.WriteLine($"\nUser: {users[userIndex].Name}"); return users[userIndex]; } public class UserProfile { // Mark name as non serializable so that it is not part of the context features [NonSerialized()] public string Name; public Dictionary<string, bool> DietaryPreferences { get; set; } public string AvgOrderPrice { get; set; } public UserProfile(string name, Dictionary<string, bool> dietaryPreferences, string avgOrderPrice) { Name = name; DietaryPreferences = dietaryPreferences; AvgOrderPrice = avgOrderPrice; } } public class Context { public UserProfile User { get; set; } public string TimeOfDay { get; set; } public string Location { get; set; } public string AppType { get; set; } public Context(UserProfile user, string timeOfDay, string location, string appType) { User = user; TimeOfDay = timeOfDay; Location = location; AppType = appType; } } public static float GetRewardScore(Context context, string actionId) { float rewardScore = 0.0f; string userName = context.User.Name; ActionFeatures actionFeatures = actions[actionId]; if (userName.Equals("Bill")) { if (actionFeatures.ItemAttributes.Price < 10 && !context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill likes to be economical when he's not in the midwest visiting his friend Warren. He bought {actionId} because it was below a price of $10."); } else if (actionFeatures.DietaryAttributes.LowCarb && context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill is visiting his friend Warren in the midwest. There he's willing to spend more on food as long as it's low carb, so Bill bought {actionId}."); } else if (actionFeatures.ItemAttributes.Price >= 10 && !context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill didn't buy {actionId} because the price was too high when not visting his friend Warren in the midwest."); } else if (actionFeatures.DietaryAttributes.LowCarb && context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill didn't buy {actionId} because it's not low-carb, and he's in the midwest visitng his friend Warren."); } } else if (userName.Equals("Satya")) { if (actionFeatures.DietaryAttributes.LowSodium) { rewardScore = 1.0f; Console.WriteLine($"\nSatya is health conscious, so he bought {actionId} since it's low in sodium."); } else { Console.WriteLine($"\nSatya did not buy {actionId} because it's not low sodium."); } } else if (userName.Equals("Amy")) { if (actionFeatures.DietaryAttributes.Vegan || actionFeatures.DietaryAttributes.Vegetarian) { rewardScore = 1.0f; Console.WriteLine($"\nAmy likes to eat plant-based foods, so she bought {actionId} because it's vegan or vegetarian friendly."); } else { Console.WriteLine($"\nAmy did not buy {actionId} because it's not vegan or vegetarian."); } } return rewardScore; } // ...Fügen Sie Ihren Schlüssel und Endpunkt an der angegeben Stelle in den Code ein. Ihr Endpunkt hat die Form
https://<your_resource_name>.cognitiveservices.azure.com/.Wichtig
Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. Verwenden Sie für die Produktion eine sichere Art der Speicherung und des Zugriffs auf Ihre Anmeldeinformationen wie Azure Key Vault. Weitere Informationen finden Sie im Artikel zur Azure KI Services-Sicherheit.
Codeblock 2: Durchlaufen der Lernschleife
Der nächste Codeblock definiert die Hauptmethode und schließt das Skript ab. Er führt eine Iteration in einer Lernschleife aus, in der er einen Kontext (einschließlich eines Kunden) generiert, eine Bewertung der Aktionen in diesem Kontext mithilfe der Bewertungs-API anfordert, die Relevanzbewertung berechnet und diese Bewertung mithilfe der Relevanz-API an den Personalisierungsdienst zurückgibt. Er gibt bei jedem Schritt relevante Informationen auf der Konsole aus.
In dem Beispiel wird mit dem Bewertungsaufruf jeweils bestimmt, welches Produkt im Abschnitt mit dem empfohlenen Produkt angezeigt werden soll. Anschließend gibt der Relevanzaufruf an, ob das empfohlene Produkt vom Benutzer erworben wurde. Relevanzen sind ihren Entscheidungen durch einen gemeinsamen EventId-Wert zugeordnet.
static void Main(string[] args)
{
int iteration = 1;
bool runLoop = true;
// Get the actions list to choose from personalizer with their features.
IList<RankableAction> actions = GetActions();
// Initialize Personalizer client.
PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);
do
{
Console.WriteLine("\nIteration: " + iteration++);
// Get context information.
Context context = GetContext();
// Create current context from user specified data.
IList<object> currentContext = new List<object>() {
context
};
// Generate an ID to associate with the request.
string eventId = Guid.NewGuid().ToString();
// Rank the actions
var request = new RankRequest(actions: actions, contextFeatures: currentContext, eventId: eventId);
RankResponse response = client.Rank(request);
Console.WriteLine($"\nPersonalizer service thinks {context.User.Name} would like to have: {response.RewardActionId}.");
float reward = GetRewardScore(context, response.RewardActionId);
// Send the reward for the action based on user response.
client.Reward(response.EventId, new RewardRequest(reward));
Console.WriteLine("\nPress q to break, any other key to continue:");
runLoop = !(GetKey() == "Q");
} while (runLoop);
}
private static string GetKey()
{
return Console.ReadKey().Key.ToString().Last().ToString().ToUpper();
}
}
Ausführen des Programms
Führen Sie die Anwendung mit dem Befehl dotnet dotnet run über das Anwendungsverzeichnis aus.
dotnet run
Bei der ersten Iteration wird die Personalisierung eine zufällige Aktion empfehlen, da sie noch kein Training durchgeführt hat. Optional können Sie weitere Iterationen ausführen. Nach etwa zehn Minuten wird der Dienst beginnen, Verbesserungen in seinen Empfehlungen zu zeigen.
Generieren Sie viele Ereignisse für die Analyse (optional)
Sie können mit diesem Schnellstartszenario leicht 5.000 Ereignisse generieren, was ausreicht, um Erfahrungen mit dem Ausbildungs- und dem Onlinemodus, dem Ausführen von Offlineauswertungen und dem Erstellen von Featureauswertungen zu sammeln. Ersetzen Sie die obige Hauptmethode durch Folgendes:
static void Main(string[] args)
{
int iteration = 1;
int runLoop = 0;
// Get the actions list to choose from personalizer with their features.
IList<RankableAction> actions = GetActions();
// Initialize Personalizer client.
PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);
do
{
Console.WriteLine("\nIteration: " + iteration++);
// Get context information.
Context context = GetContext();
// Create current context from user specified data.
IList<object> currentContext = new List<object>() {
context
};
// Generate an ID to associate with the request.
string eventId = Guid.NewGuid().ToString();
// Rank the actions
var request = new RankRequest(actions: actions, contextFeatures: currentContext, eventId: eventId);
RankResponse response = client.Rank(request);
Console.WriteLine($"\nPersonalizer service thinks {context.User.Name} would like to have: {response.RewardActionId}.");
float reward = GetRewardScore(context, response.RewardActionId);
// Send the reward for the action based on user response.
client.Reward(response.EventId, new RewardRequest(reward));
runLoop = runLoop + 1;
} while (runLoop < 1000);
}
Der Quellcode für diesen Schnellstart ist auf GitHub verfügbar.
Referenzdokumentation |Quellcode der Bibliothek | Paket (npm) | Schnellstart-Codebeispiel
Voraussetzungen
- Azure-Abonnement – Erstellen eines kostenlosen Kontos
- Installieren von Node.js und npm (überprüft mit Node.js v14.16.0 und npm 6.14.11).
- Sobald Sie über Ihr Azure-Abonnement verfügen, sollten Sie im Azure-Portal eine Personalisierung-Ressource erstellen, um Ihren Schlüssel und Endpunkt abzurufen. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
- Sie benötigen den Schlüssel und Endpunkt der von Ihnen erstellten Ressource, um Ihre Anwendung mit der Personalisierungs-API zu verbinden. Der Schlüssel und der Endpunkt werden weiter unten in der Schnellstartanleitung in den Code eingefügt.
- Sie können den kostenlosen Tarif (
F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.
Modellkonfiguration
Ändern der Häufigkeit der Modellaktualisierung
Wechseln Sie im Azure-Portal zur Seite Konfiguration Ihrer Personalisierungsressource, und ändern Sie Häufigkeit der Modellaktualisierung auf 30 Sekunden. Mit dieser kurzen Dauer wird das Modell schnell trainiert, und Sie können sehen, wie sich die empfohlene Aktion für jede Iteration ändert.
Ändern der Belohnungswartezeit
Wechseln Sie im Azure-Portal zur Seite Konfiguration Ihrer Personalisierungsressource, und ändern Sie die Belohnungswartezeit in 10 Minuten. Dadurch wird bestimmt, wie lange das Modell nach dem Senden einer Empfehlung wartet, um das Belohnungsfeedback für diese Empfehlung zu erhalten. Das Training findet erst statt, wenn die Belohnungswartezeit verstrichen ist.
Erstellen einer neuen Node.js-Anwendung
Erstellen Sie in einem Konsolenfenster (etwa cmd, PowerShell oder Bash) ein neues Verzeichnis für Ihre App, und rufen Sie es auf.
mkdir myapp && cd myapp
Führen Sie den Befehl npm init -y aus, um die Datei package.json zu erstellen.
npm init -y
Erstellen Sie ein neues Node.js-Skript in Ihrem bevorzugten Editor oder IDE mit dem Namen personalizer-quickstart.js, und erstellen Sie Variablen für den Endpunkt Ihrer Ressource und den Abonnementschlüssel.
Installieren der Clientbibliothek
Installieren Sie mit dem folgenden Befehl die Personalisierungsclientbibliothek für Node.js:
npm install @azure/cognitiveservices-personalizer --save
Installieren Sie die verbleibenden npm-Pakete für diese Schnellstartanleitung:
npm install @azure/ms-rest-azure-js @azure/ms-rest-js readline-sync uuid --save
Codeblock 1: Generieren von Beispieldaten
Die Personalisierung ist für die Ausführung in Anwendungen gedacht, die Echtzeitdaten empfangen und interpretieren. In diesem Schnellstart verwenden Sie Beispielcode, um imaginäre Aktionen von Kunden auf einer Website für Lebensmittelgeschäfte zu generieren. Der folgende Codeblock definiert drei wichtige Methoden: getActionsList, getContextFeaturesList und getReward.
getActionsList gibt eine Liste der Optionen zurück, die die Website für Lebensmittelgeschäfte für die Bewertung benötigt. In diesem Beispiel sind die Aktionen Nahrungsprodukte. Jede Aktionsauswahl verfügt über Details (Features), die das spätere Verhalten des Benutzers beeinflussen können. Aktionen werden als Eingabe für die Bewertungs-API verwendet.
getContextFeaturesList gibt einen simulierten Besuch des Kunden zurück. Es wählt nach dem Zufallsprinzip Details aus (Kontextfeatures), z. B. welcher Kunde anwesend ist und zu welcher Tageszeit der Besuch erfolgt. Im Allgemeinen stellt ein Kontext den aktuellen Zustand Ihrer Anwendung, Ihres Systems, Ihrer Umgebung oder Ihres Benutzers dar. Das Kontextobjekt wird als Eingabe für die Bewertungs-API verwendet.
Die Kontextfeatures in diesem Schnellstart sind sehr einfach gehalten. In einem echten Produktionssystem ist es jedoch wichtig, Ihre Features zu entwerfen und ihre Wirksamkeit zu bewerten. Eine Anleitung finden Sie in der verlinkten Dokumentation.
getReward fordert den Benutzer auf, die Empfehlung des Diensts als Erfolg oder Misserfolg zu bewerten. Es gibt einen Wert zwischen null und eins zurück, der den Erfolg einer Interaktion mit einem Kunden darstellt. In einem realen Szenario lernt die Personalisierung die Präferenzen des Benutzers aus den Interaktionen mit dem Kunden in Echtzeit.
In einem echten Produktionssystem muss die Relevanzbewertung auf Ihre Geschäftsziele und KPIs abgestimmt werden. Die Ermittlung, wie Sie die Metrik für die Relevanz berechnen können, erfordert möglicherweise ein gewisses Experimentieren.
Öffnen Sie personalizer-quickstart.js in einem Text-Editor oder einer IDE, und fügen Sie den nachfolgenden Code ein.
const uuidv1 = require('uuid/v1');
const Personalizer = require('@azure/cognitiveservices-personalizer');
const CognitiveServicesCredentials = require('@azure/ms-rest-azure-js').CognitiveServicesCredentials;
const readline = require('readline-sync');
function getReward() {
const answer = readline.question("\nIs this correct (y/n)\n");
if (answer.toLowerCase() === 'y') {
console.log("\nGreat| Enjoy your food.");
return 1;
}
console.log("\nYou didn't like the recommended food choice.");
return 0;
}
function getContextFeaturesList() {
const timeOfDayFeatures = ['morning', 'afternoon', 'evening', 'night'];
const tasteFeatures = ['salty', 'sweet'];
let answer = readline.question("\nWhat time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night\n");
let selection = parseInt(answer);
const timeOfDay = selection >= 1 && selection <= 4 ? timeOfDayFeatures[selection - 1] : timeOfDayFeatures[0];
answer = readline.question("\nWhat type of food would you prefer (enter number)? 1. salty 2. sweet\n");
selection = parseInt(answer);
const taste = selection >= 1 && selection <= 2 ? tasteFeatures[selection - 1] : tasteFeatures[0];
console.log("Selected features:\n");
console.log("Time of day: " + timeOfDay + "\n");
console.log("Taste: " + taste + "\n");
return [
{
"time": timeOfDay
},
{
"taste": taste
}
];
}
function getExcludedActionsList() {
return [
"juice"
];
}
function getActionsList() {
return [
{
"id": "pasta",
"features": [
{
"taste": "salty",
"spiceLevel": "medium"
},
{
"nutritionLevel": 5,
"cuisine": "italian"
}
]
},
{
"id": "ice cream",
"features": [
{
"taste": "sweet",
"spiceLevel": "none"
},
{
"nutritionalLevel": 2
}
]
},
{
"id": "juice",
"features": [
{
"taste": "sweet",
"spiceLevel": "none"
},
{
"nutritionLevel": 5
},
{
"drink": true
}
]
},
{
"id": "salad",
"features": [
{
"taste": "salty",
"spiceLevel": "low"
},
{
"nutritionLevel": 8
}
]
}
];
}
Codeblock 2: Durchlaufen der Lernschleife
Der nächste Codeblock definiert die Hauptmethode und schließt das Skript ab. Er führt eine Lernschleife aus, in der es den Benutzer in der Befehlszeile nach seinen Präferenzen fragt und diese Informationen an die Personalisierung sendet, um die beste Aktion auszuwählen. Er präsentiert dem Benutzer die ausgewählte Aktion, die er über die Befehlszeile auswählen kann. Dann sendet er eine Relevanzbewertung an den Personalisierungsdienst, um zu signalisieren, wie gut der Dienst bei seiner Auswahl abgeschnitten hat.
Die Lernschleife der Personalisierung ist ein Zyklus aus Rangfolge- und Relevanzaufrufen. In dieser Schnellstartanleitung folgt auf jeden Rangfolgeaufruf zur Personalisierung des Inhalts ein Relevanzaufruf, um der Personalisierung mitzuteilen, wie gut der Dienst abgeschnitten hat.
Fügen Sie den nachstehenden Code zur Datei personalizer-quickstart.js hinzu.
Finden Sie Ihren Schlüssel und Endpunkt. Ihr Endpunkt hat die Form
https://<your_resource_name>.cognitiveservices.azure.com/.Wichtig
Öffnen Sie das Azure-Portal. Wenn die im Abschnitt Voraussetzungen erstellte Personalisierungsressource erfolgreich bereitgestellt wurde, klicken Sie unter Nächste Schritte auf die Schaltfläche Zu Ressource wechseln. Schlüssel und Endpunkt finden Sie auf der Seite mit dem Schlüssel und dem Endpunkt der Ressource unter Ressourcenverwaltung.
Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. In der Produktionsumgebung sollten Sie eine sichere Methode zum Speichern Ihrer Anmeldeinformationen sowie zum Zugriff darauf verwenden. Beispielsweise Azure Key Vault.
Fügen Sie Ihren Schlüssel und Endpunkt an der angegeben Stelle in den Code ein.
Wichtig
Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. Verwenden Sie für die Produktion eine sichere Art der Speicherung und des Zugriffs auf Ihre Anmeldeinformationen wie Azure Key Vault. Weitere Informationen zur Sicherheit finden Sie im Azure KI Services-Artikel Sicherheit.
async function main() { // The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF" const serviceKey = "PASTE_YOUR_PERSONALIZER_SUBSCRIPTION_KEY_HERE"; // The endpoint specific to your personalization service instance; // e.g. https://<your-resource-name>.cognitiveservices.azure.com const baseUri = "PASTE_YOUR_PERSONALIZER_ENDPOINT_HERE"; const credentials = new CognitiveServicesCredentials(serviceKey); // Initialize Personalization client. const personalizerClient = new Personalizer.PersonalizerClient(credentials, baseUri); let runLoop = true; do { let rankRequest = {} // Generate an ID to associate with the request. rankRequest.eventId = uuidv1(); // Get context information from the user. rankRequest.contextFeatures = getContextFeaturesList(); // Get the actions list to choose from personalization with their features. rankRequest.actions = getActionsList(); // Exclude an action for personalization ranking. This action will be held at its current position. rankRequest.excludedActions = getExcludedActionsList(); rankRequest.deferActivation = false; // Rank the actions const rankResponse = await personalizerClient.rank(rankRequest); console.log("\nPersonalization service thinks you would like to have:\n") console.log(rankResponse.rewardActionId); // Display top choice to user, user agrees or disagrees with top choice const reward = getReward(); console.log("\nPersonalization service ranked the actions with the probabilities as below:\n"); for (let i = 0; i < rankResponse.ranking.length; i++) { console.log(JSON.stringify(rankResponse.ranking[i]) + "\n"); } // Send the reward for the action based on user response. const rewardRequest = { value: reward } await personalizerClient.events.reward(rankRequest.eventId, rewardRequest); runLoop = continueLoop(); } while (runLoop); } function continueLoop() { const answer = readline.question("\nPress q to break, any other key to continue.\n") if (answer.toLowerCase() === 'q') { return false; } return true; } main() .then(result => console.log("done")) .catch(err=> console.log(err));
Ausführen des Programms
Führen Sie die Anwendung mit dem Node.js-Befehl aus dem Anwendungsverzeichnis aus.
node personalizer-quickstart.js
Durchlaufen Sie ein paar Lernschleifen. Nach etwa zehn Minuten wird der Dienst beginnen, Verbesserungen in seinen Empfehlungen zu zeigen.
Der Quellcode für diesen Schnellstart ist auf GitHub verfügbar.
Referenzdokumentation | Quellcode der Bibliothek | Paket (pypi) | Schnellstart-Codebeispiel
Voraussetzungen
- Azure-Abonnement – Erstellen eines kostenlosen Kontos
- Python 3.x
- Wenn Sie über Ihr Azure-Abonnement verfügen, können Sie im Azure-Portal eine Personalisierungsressource erstellen und Ihren Schlüssel und Endpunkt abrufen. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
- Sie benötigen den Schlüssel und den Endpunkt aus der erstellten Ressource, um Ihre Anwendung mit der Personalisierungs-API zu verbinden. Beides wird weiter unten in den Schnellstartcode eingefügt.
- Sie können den kostenlosen Tarif (
F0) verwenden, um den Dienst zu testen, und später für die Produktion auf einen kostenpflichtigen Tarif upgraden.
Modellkonfiguration
Ändern der Häufigkeit der Modellaktualisierung
Wechseln Sie im Azure-Portal zur Seite Konfiguration Ihrer Personalisierungsressource, und ändern Sie Häufigkeit der Modellaktualisierung auf 30 Sekunden. Mit dieser kurzen Dauer wird das Modell schnell trainiert, und Sie können sehen, wie sich die empfohlene Aktion für jede Iteration ändert.
Ändern der Belohnungswartezeit
Wechseln Sie im Azure-Portal zur Seite Konfiguration Ihrer Personalisierungsressource, und ändern Sie die Belohnungswartezeit in 10 Minuten. Dadurch wird bestimmt, wie lange das Modell nach dem Senden einer Empfehlung wartet, um das Belohnungsfeedback für diese Empfehlung zu erhalten. Das Training findet erst statt, wenn die Belohnungswartezeit verstrichen ist.
Erstellen einer neuen Python-Anwendung
Erstellen Sie eine neue Python-Datei namens personalizer-quickstart.py.
Installieren der Clientbibliothek
Installieren Sie die Clientbibliothek der Personalisierung mit pip:
pip install azure-cognitiveservices-personalizer
Codeblock 1: Generieren von Beispieldaten
Die Personalisierung ist für die Ausführung in Anwendungen gedacht, die Echtzeitdaten empfangen und interpretieren. Für diesen Schnellstart verwenden Sie Beispielcode, um imaginäre Aktionen von Kunden auf einer Website für Lebensmittelgeschäfte zu generieren. Der folgende Codeblock definiert drei wichtige Funktionen: get_actions, get_context und get_reward_score.
get_actions gibt eine Liste der Optionen zurück, die die Website für Lebensmittelgeschäfte für die Bewertung benötigt. In diesem Beispiel sind die Aktionen Nahrungsprodukte. Jede Aktionsauswahl verfügt über Details (Features), die das spätere Verhalten des Benutzers beeinflussen können. Aktionen werden als Eingabe für die Bewertungs-API verwendet.
get_context gibt einen simulierten Besuch eines Kunden zurück. Es wählt nach dem Zufallsprinzip Details aus (Kontextfeatures), z. B. welcher Kunde anwesend ist und zu welcher Tageszeit der Besuch erfolgt. Im Allgemeinen stellt ein Kontext den aktuellen Zustand Ihrer Anwendung, Ihres Systems, Ihrer Umgebung oder Ihres Benutzers dar. Das Kontextobjekt wird als Eingabe für die Bewertungs-API verwendet.
Die Kontextfeatures in diesem Schnellstart sind sehr einfach gehalten. In einem echten Produktionssystem ist es jedoch sehr wichtig, Ihre Features zu entwerfen und ihre Wirksamkeit zu bewerten. Eine Anleitung finden Sie in der verlinkten Dokumentation.
get_reward_score gibt einen Wert zwischen null und eins zurück, der den Erfolg einer Interaktion mit einem Kunden darstellt. Es verwendet eine einfache Logik, um festzustellen, wie verschiedene Kontexte auf verschiedene Aktionsoptionen reagieren. Ein bestimmter Benutzer wird z. B. immer eine 1,0 für vegetarische und vegane Produkte vergeben und eine 0,0 für andere Produkte. In einem echten Szenario lernt die Personalisierung Benutzerpräferenzen anhand der Daten, die in Rangfolge- und Relevanz-API-Aufrufen gesendet werden. Sie werden nicht wie im Beispielcode explizit definiert.
In einem echten Produktionssystem muss die Relevanzbewertung auf Ihre Geschäftsziele und KPIs abgestimmt werden. Die Ermittlung, wie Sie die Metrik für die Relevanz berechnen können, erfordert möglicherweise ein gewisses Experimentieren.
Im Code weiter unten sind zu Demonstrationszwecken die Präferenzen der Benutzer sowie ihre Reaktionen auf die Aktionen als eine Reihe bedingter Anweisungen hartcodiert. Außerdem enthält der Code erklärenden Text.
Folgen Sie diesen Schritten, um das Personalisierungsskript einzurichten.
Finden Sie Ihren Schlüssel und Endpunkt.
Wichtig
Öffnen Sie das Azure-Portal. Wenn die im Abschnitt Voraussetzungen erstellte Personalisierungsressource erfolgreich bereitgestellt wurde, klicken Sie unter Nächste Schritte auf die Schaltfläche Zu Ressource wechseln. Schlüssel und Endpunkt finden Sie auf der Seite mit dem Schlüssel und dem Endpunkt der Ressource unter Ressourcenverwaltung.
Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. In der Produktionsumgebung sollten Sie eine sichere Methode zum Speichern Ihrer Anmeldeinformationen sowie zum Zugriff darauf verwenden. Beispielsweise Azure Key Vault.
Öffnen Sie personalizer-quickstart.py in einem Text-Editor oder einer IDE, und fügen Sie den nachfolgenden Code ein.
Fügen Sie Ihren Schlüssel und Endpunkt an der angegeben Stelle in den Code ein. Ihr Endpunkt hat die Form
https://<your_resource_name>.cognitiveservices.azure.com/.Wichtig
Denken Sie daran, den Schlüssel aus Ihrem Code zu entfernen, wenn Sie fertig sind, und ihn niemals zu veröffentlichen. Verwenden Sie in der Produktion eine sichere Speicher- und Zugriffsmethode für Ihre Anmeldeinformationen (beispielsweise Azure Key Vault). Weitere Informationen finden Sie Azure KI Services-Artikel Sicherheit.
from azure.cognitiveservices.personalizer import PersonalizerClient
from azure.cognitiveservices.personalizer.models import RankableAction, RewardRequest, RankRequest
from msrest.authentication import CognitiveServicesCredentials
import datetime, json, os, time, uuid, random
key = "paste_your_personalizer_key_here"
endpoint = "paste_your_personalizer_endpoint_here"
# Instantiate a Personalizer client
client = PersonalizerClient(endpoint, CognitiveServicesCredentials(key))
actions_and_features = {
'pasta': {
'brand_info': {
'company':'pasta_inc'
},
'attributes': {
'qty':1, 'cuisine':'italian',
'price':12
},
'dietary_attributes': {
'vegan': False,
'low_carb': False,
'high_protein': False,
'vegetarian': False,
'low_fat': True,
'low_sodium': True
}
},
'bbq': {
'brand_info' : {
'company': 'ambisco'
},
'attributes': {
'qty': 2,
'category': 'bbq',
'price': 20
},
'dietary_attributes': {
'vegan': False,
'low_carb': True,
'high_protein': True,
'vegetarian': False,
'low_fat': False,
'low_sodium': False
}
},
'bao': {
'brand_info': {
'company': 'bao_and_co'
},
'attributes': {
'qty': 4,
'category': 'chinese',
'price': 8
},
'dietary_attributes': {
'vegan': False,
'low_carb': True,
'high_protein': True,
'vegetarian': False,
'low_fat': True,
'low_sodium': False
}
},
'hummus': {
'brand_info' : {
'company': 'garbanzo_inc'
},
'attributes' : {
'qty': 1,
'category': 'breakfast',
'price': 5
},
'dietary_attributes': {
'vegan': True,
'low_carb': False,
'high_protein': True,
'vegetarian': True,
'low_fat': False,
'low_sodium': False
}
},
'veg_platter': {
'brand_info': {
'company': 'farm_fresh'
},
'attributes': {
'qty': 1,
'category': 'produce',
'price': 7
},
'dietary_attributes': {
'vegan': True,
'low_carb': True,
'high_protein': False,
'vegetarian': True,
'low_fat': True,
'low_sodium': True
}
}
}
def get_actions():
res = []
for action_id, feat in actions_and_features.items():
action = RankableAction(id=action_id, features=[feat])
res.append(action)
return res
user_profiles = {
'Bill': {
'dietary_preferences': 'low_carb',
'avg_order_price': '0-20',
'browser_type': 'edge'
},
'Satya': {
'dietary_preferences': 'low_sodium',
'avg_order_price': '201+',
'browser_type': 'safari'
},
'Amy': {
'dietary_preferences': {
'vegan', 'vegetarian'
},
'avg_order_price': '21-50',
'browser_type': 'edge'},
}
def get_context(user):
location_context = {'location': random.choice(['west', 'east', 'midwest'])}
time_of_day = {'time_of_day': random.choice(['morning', 'afternoon', 'evening'])}
app_type = {'application_type': random.choice(['edge', 'safari', 'edge_mobile', 'mobile_app'])}
res = [user_profiles[user], location_context, time_of_day, app_type]
return res
def get_random_users(k = 5):
return random.choices(list(user_profiles.keys()), k=k)
def get_reward_score(user, actionid, context):
reward_score = 0.0
action = actions_and_features[actionid]
if user == 'Bill':
if action['attributes']['price'] < 10 and (context[1]['location'] != "midwest"):
reward_score = 1.0
print("Bill likes to be economical when he's not in the midwest visiting his friend Warren. He bought", actionid, "because it was below a price of $10.")
elif (action['dietary_attributes']['low_carb'] == True) and (context[1]['location'] == "midwest"):
reward_score = 1.0
print("Bill is visiting his friend Warren in the midwest. There he's willing to spend more on food as long as it's low carb, so Bill bought" + actionid + ".")
elif (action['attributes']['price'] >= 10) and (context[1]['location'] != "midwest"):
print("Bill didn't buy", actionid, "because the price was too high when not visting his friend Warren in the midwest.")
elif (action['dietary_attributes']['low_carb'] == False) and (context[1]['location'] == "midwest"):
print("Bill didn't buy", actionid, "because it's not low-carb, and he's in the midwest visitng his friend Warren.")
elif user == 'Satya':
if action['dietary_attributes']['low_sodium'] == True:
reward_score = 1.0
print("Satya is health conscious, so he bought", actionid,"since it's low in sodium.")
else:
print("Satya did not buy", actionid, "because it's not low sodium.")
elif user == 'Amy':
if (action['dietary_attributes']['vegan'] == True) or (action['dietary_attributes']['vegetarian'] == True):
reward_score = 1.0
print("Amy likes to eat plant-based foods, so she bought", actionid, "because it's vegan or vegetarian friendly.")
else:
print("Amy did not buy", actionid, "because it's not vegan or vegetarian.")
return reward_score
# ...
Codeblock 2: Durchlaufen der Lernschleife
Der nächste Codeblock definiert die Funktion run_personalizer_cycle und ruft sie in einer einfachen Benutzerfeedbackschleife auf. Er führt eine Iteration in einer Lernschleife aus, in der er einen Kontext (einschließlich eines Kunden) generiert, eine Bewertung der Aktionen in diesem Kontext mithilfe der Bewertungs-API anfordert, die Relevanzbewertung berechnet und diese Bewertung mithilfe der Relevanz-API an den Personalisierungsdienst zurückgibt. Er gibt bei jedem Schritt relevante Informationen auf der Konsole aus.
In dem Beispiel wird mit dem Bewertungsaufruf jeweils bestimmt, welches Produkt im Abschnitt mit dem empfohlenen Produkt angezeigt werden soll. Anschließend gibt der Relevanzaufruf an, ob das empfohlene Produkt vom Benutzer erworben wurde. Relevanzen sind ihren Entscheidungen durch einen gemeinsamen EventId-Wert zugeordnet.
def run_personalizer_cycle():
actions = get_actions()
user_list = get_random_users()
for user in user_list:
print("------------")
print("User:", user, "\n")
context = get_context(user)
print("Context:", context, "\n")
rank_request = RankRequest(actions=actions, context_features=context)
response = client.rank(rank_request=rank_request)
print("Rank API response:", response, "\n")
eventid = response.event_id
actionid = response.reward_action_id
print("Personalizer recommended action", actionid, "and it was shown as the featured product.\n")
reward_score = get_reward_score(user, actionid, context)
client.events.reward(event_id=eventid, value=reward_score)
print("\nA reward score of", reward_score , "was sent to Personalizer.")
print("------------\n")
continue_loop = True
while continue_loop:
run_personalizer_cycle()
br = input("Press Q to exit, or any other key to run another loop: ")
if(br.lower()=='q'):
continue_loop = False
Ausführen des Programms
Sobald der gesamte obige Code in Ihrer Python-Datei enthalten ist, können Sie sie in Ihrem Anwendungsverzeichnis ausführen.
python personalizer-quickstart.py
Bei der ersten Iteration wird die Personalisierung eine zufällige Aktion empfehlen, da sie noch kein Training durchgeführt hat. Optional können Sie weitere Iterationen ausführen. Nach etwa zehn Minuten wird der Dienst beginnen, Verbesserungen in seinen Empfehlungen zu zeigen.
Generieren Sie viele Ereignisse für die Analyse (optional)
Sie können mit diesem Schnellstartszenario leicht 5.000 Ereignisse generieren, was ausreicht, um Erfahrungen mit dem Ausbildungsmodus, dem Onlinemodus, dem Ausführen von Offlineauswertungen und dem Erstellen von Featureauswertungen zu sammeln. Ersetzen Sie die while-Schleife im obigen Codeblock durch den folgenden Code.
for i in range(0,1000):
run_personalizer_cycle()
Der Quellcode für diesen Schnellstart ist auf GitHub verfügbar.
Herunterladen des trainierten Modells
Wenn Sie ein Personalisierungsmodell herunterladen möchten, das anhand von 5.000 Ereignissen aus dem obigen Beispiel trainiert wurde, besuchen Sie das Repository für die Personalisierungsbeispiele, und laden Sie die Datei Personalizer_QuickStart_Model.zip herunter. Gehen Sie dann zu Ihrer Personalizer-Ressource im Azure-Portal, wechseln Sie zur Seite Setup und der Registerkarte Import/Export, und importieren Sie die Datei.
Bereinigen von Ressourcen
Um Ihr Azure KI Services-Abonnement zu bereinigen, können Sie die Ressource oder die Ressourcengruppe löschen. Bei Letzterem werden alle zugeordneten Ressourcen gelöscht.