Schnellstart: Personalisierungsclientbibliothek

Referenzdokumentation | Bibliotheksquellcode | Package (NuGet) | .NET Codebeispiel

Voraussetzungen

• Azure-Abonnement – Create one for free
• Die aktuelle Version von .NET Core.
• Sobald Sie Ihr Azure-Abonnement haben, erstellen Sie eine Personalizer-Ressource im Azure-Portal, um Ihren Schlüssel und Endpunkt zu erhalten. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
  • Sie benötigen den Schlüssel und Endpunkt der erstellten Ressource, um Ihre Anwendung mit der Personalisierungs-API zu verbinden. Sie fügen Ihren Schlüssel und Endpunkt weiter unten im Schnellstart in den Code ein.
  • 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 Ihrer Personalizer-Ressource Configuration, und ändern Sie die Modellaktualisierungshäufigkeit 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 Configuration-Seite Ihrer Personalizer-Ressource, und ändern Sie die Wartezeit Reward-Wartezeit auf 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. Mit diesem Befehl wird ein einfaches C#-Projekt "Hallo Welt" mit einer einzelnen Quelldatei erstellt: 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 die Personalizer-Clientbibliothek für .NET mit dem folgenden Befehl:

dotnet add package Microsoft.Azure.CognitiveServices.Personalizer --version 1.0.0

Codeblock 1: Generieren von Beispieldaten

Personalizer ist darauf ausgelegt, in Anwendungen zu laufen, die Echtzeitdaten empfangen und interpretieren. In diesem Schnellstart verwenden Sie Beispielcode, um imaginäre Kundenaktionen 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 Kontextmerkmale in diesem Schnellstart sind einfach. 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 der Personalizer die Benutzerpräferenzen anhand der Daten, die in Rank- und Reward-API-Aufrufen gesendet werden. Sie werden nicht wie im Beispielcode explizit definiert.

  In einem echten Produktionssystem sollte die Belohnungspunktzahl so gestaltet werden, dass sie mit Ihren Geschäftszielen und KPIs übereinstimmt. Die Bestimmung, wie Sie die Belohnungsmetrik 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.

1. Finden Sie Ihren Schlüssel und Endpunkt.

   Wichtig

   Wechseln Sie zum 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 API-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.

2. Ö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;
       }
       // ...
   

3. Fügen Sie Ihren Schlüssel und Endpunkt an der angegebenen Stelle in den Code ein. Ihr Endpunkt hat die Form https://<your_resource_name>.cognitiveservices.azure.com/.

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. Der Belohnungsaufruf gibt an, ob das vorgestellte Produkt vom Benutzer erworben wurde oder nicht. Belohnungen sind mit ihren Entscheidungen durch einen gemeinsamen EventId-Wert verbunden.

    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 empfiehlt der Personalizer eine zufällige Aktion, da noch kein Training durchgeführt wurde. 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 diese Schnellstartanleitung ist auf GitHub verfügbar.

Reference-Dokumentation | Package (npm) | Quickstart-Codebeispiel

Voraussetzungen

• Azure-Abonnement – Create one for free
• Installieren von Node.js und npm (überprüft mit Node.js v14.16.0 und npm 6.14.11).
• Sobald Sie Ihr Azure-Abonnement haben, erstellen Sie eine Personalizer-Ressource im Azure-Portal, um Ihren Schlüssel und Endpunkt zu erhalten. 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. Sie werden Ihren Schlüssel und Endpunkt weiter unten im Schnellstart in den Code einfügen.
  • 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 Ihrer Personalizer-Ressource Configuration, und ändern Sie die Modellaktualisierungshäufigkeit 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 Configuration-Seite Ihrer Personalizer-Ressource, und ändern Sie die Wartezeit Reward-Wartezeit auf 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

Personalizer ist darauf ausgelegt, in Anwendungen zu laufen, 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 Kontextmerkmale in diesem Schnellstart sind einfach. 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 sollte die Belohnungspunktzahl so gestaltet werden, dass sie mit Ihren Geschäftszielen und KPIs übereinstimmt. Die Bestimmung, wie Sie die Belohnungsmetrik 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, wobei der Benutzer in der Befehlszeile nach seinen Präferenzen gefragt wird. Diese Informationen werden dann an den Personalizer gesendet, 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 des Personalizers ist ein Zyklus aus Rank-Aufrufen und Belohnungsaufrufen. In dieser Schnellstartanleitung folgt auf jeden Rank-Aufruf zur Personalisierung des Inhalts ein Reward-Aufruf, um dem Personalizer mitzuteilen, wie gut der Dienst funktioniert hat.

1. Fügen Sie den nachstehenden Code zur Datei personalizer-quickstart.js hinzu.

2. Finden Sie Ihren Schlüssel und Endpunkt. Ihr Endpunkt hat die Form https://<your_resource_name>.cognitiveservices.azure.com/.

   Wichtig

   Wechseln Sie zum 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 API-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.

3. Fügen Sie Ihren Schlüssel und Endpunkt an der angegebenen Stelle in den Code ein.

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 diese Schnellstartanleitung ist auf GitHub verfügbar.

Referenzdokumentation | Quellcode | Package (PyPI) | Quickstart-Codebeispiel

Voraussetzungen

• Azure-Abonnement – Create one for free
• Python 3.x
• Nachdem Ihr Azure-Abonnement eingerichtet wurde, Erstellen Sie eine Personalizer-Ressource im Azure-Portal und erhalten Sie Ihren Schlüssel und Endpunkt. Wählen Sie nach Abschluss der Bereitstellung Zu Ressource wechseln aus.
  • Sie benötigen den Schlüssel und den Endpunkt 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 Ihrer Personalizer-Ressource Configuration, und ändern Sie die Modellaktualisierungshäufigkeit 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 Configuration-Seite Ihrer Personalizer-Ressource, und ändern Sie die Wartezeit Reward-Wartezeit auf 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 mit dem Namen personalizer-quickstart.py.

Installieren der Clientbibliothek

Installieren Sie die Personalizer-Clientbibliothek mit pip:

pip install azure-cognitiveservices-personalizer

Codeblock 1: Generieren von Beispieldaten

Personalizer ist darauf ausgelegt, in Anwendungen zu laufen, die Echtzeitdaten empfangen und interpretieren. In diesem Schnellstart verwenden Sie Beispielcode, um imaginäre Kundenaktionen 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 Kontextmerkmale in diesem Schnellstart sind einfach. 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.

• 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 der Personalizer die Benutzerpräferenzen anhand der Daten, die in Rank- und Reward-API-Aufrufen gesendet werden. Sie werden nicht wie im Beispielcode explizit definiert.

  In einem echten Produktionssystem sollte die Belohnungspunktzahl so gestaltet werden, dass sie mit Ihren Geschäftszielen und KPIs übereinstimmt. Die Bestimmung, wie Sie die Belohnungsmetrik 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.

1. Finden Sie Ihren Schlüssel und Endpunkt.

   Wichtig

   Wechseln Sie zum 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 API-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.

2. Öffnen Sie personalizer-quickstart.py in einem Text-Editor oder einer IDE, und fügen Sie den nachfolgenden Code ein.

3. Fügen Sie Ihren Schlüssel und Endpunkt an der angegebenen Stelle in den Code ein. Ihr Endpunkt hat die Form https://<your_resource_name>.cognitiveservices.azure.com/.

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. Der Belohnungsaufruf gibt an, ob das vorgestellte Produkt vom Benutzer erworben wurde oder nicht. Belohnungen sind mit ihren Entscheidungen durch einen gemeinsamen EventId-Wert verbunden.

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 oben genannte Code in Ihrer Python Datei enthalten ist, können Sie ihn aus Ihrem Anwendungsverzeichnis ausführen.

python personalizer-quickstart.py

Bei der ersten Iteration empfiehlt der Personalizer eine zufällige Aktion, da noch kein Training durchgeführt wurde. 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 diese Schnellstartanleitung ist auf GitHub verfügbar.