Erste Schritte mit dem SDK für lokale Rückschlüsse für die Azure KI Personalisierung

Wichtig

Ab dem 20. September 2023 können Sie keine neuen Personalisierungsressourcen mehr erstellen. Der Personalisierungsdienst wird am 1. Oktober 2026 eingestellt.

Das lokale Rückschluss-SDK der Personalisierung (Vorschau) lädt die Personalisierungsmodelle lokal herunter und verringert so die Wartezeit für Rangfolgeaufrufe durch Vermeidung von Netzwerkaufrufen. Der Client lädt jede Minute das neueste Modell im Hintergrund herunter und verwendet es für das Rückschließen.

In diesem Leitfaden erfahren Sie, wie Sie das Personalisierungs-SDK für lokales Rückschließen verwenden.

Sie müssen die Personalizer-Clientbibliothek für .NET installieren, um:

• den Schnellstartbeispielclient mit einer Personalizer-Ressource in Azure zu authentifizieren.
• Kontext- und Aktionsfeatures an die Belohnungs-API zu senden, die die beste Aktion aus dem Personalisierungsmodell zurückgibt
• eine Relevanzbewertung an die Rang-API zu senden und das Personalisierungsmodell zu trainieren.

Referenzdokumentation | Quellcode der Bibliothek | Paket (NuGet)

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.

Einrichten

Ä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. Sie können die Anwendung mit folgendem Befehl erstellen:

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 Azure.AI.Personalizer --version 2.0.0-beta.2

Tipp

Bei Verwendung der Visual Studio-IDE ist die Clientbibliothek als herunterladbares NuGet-Paket verfügbar.

Öffnen Sie über das Projektverzeichnis die Datei Program.cs in Ihrem bevorzugten Editor oder in Ihrer bevorzugten IDE. Fügen Sie die folgenden using-Direktiven hinzu:

using Azure;
using Azure.AI.Personalizer;
using System;
using System.Collections.Generic;
using System.Linq;

Objektmodell

Der Personalisierungsclient ist ein Objekt vom Typ PersonalizerClient, das mithilfe der Klasse Azure.AzureKeyCredential, die Ihren Schlüssel enthält, bei Azure authentifiziert wird.

Wenn Sie dazu auffordern möchten, dem Benutzer das beste einzelne Element anzuzeigen, erstellen Sie ein Objekt PersonalizerRankOptions, und übergeben Sie es der Methode PersonalizerClient.Rank. Die Rank-Methode gibt ein PersonalizerRankResult zurück.

Übergeben Sie zum Senden einer Relevanzbewertung an die Personalisierung die Ereignis-ID und die Relevanzbewertung an die Methode PersonalizerClient.Reward.

Im Rahmen dieser Schnellstartanleitung ist die Bestimmung der Relevanzbewertung ganz einfach. In einem Produktionssystem kann die Bestimmung der Einflussfaktoren für die Relevanzbewertung sowie deren jeweilige Gewichtung allerdings eine komplexe Angelegenheit sein und muss unter Umständen im Laufe der Zeit überarbeitet werden. Diese Entwurfsentscheidung sollte eine der wichtigsten Entscheidungen im Zusammenhang mit Ihrer Personalisierungsarchitektur sein.

Codebeispiele

In diesen Codeausschnitten werden folgende Aufgaben mit der Personalisierungsclientbibliothek für .NET veranschaulicht:

• Erstellen eines Personalisierungsclients
• Rangfolge-API mit mehreren Slots
• Belohnungs-API mit mehreren Slots

Authentifizieren des Clients

In diesem Abschnitt führen Sie zwei Aktionen aus:

• Angeben Ihres Schlüssels und Endpunkts
• Erstellen eines Personalisierungsclients

Fügen Sie zunächst der Program-Klasse die unten angegebenen Zeilen hinzu. Fügen Sie unbedingt den Schlüssel und Endpunkt Ihrer Personalisierungsressource hinzu.

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.

private const string ServiceEndpoint  = "https://REPLACE-WITH-YOUR-PERSONALIZER-RESOURCE-NAME.cognitiveservices.azure.com";
private const string ResourceKey = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>";

Erstellen Sie als Nächstes die Rangfolge- und Belohnungs-URLs. Beachten Sie, dass die Einstellung useLocalInference: true als Parameter für PersonalizerClientOptions erforderlich ist, um den lokalen Rückschluss zu ermöglichen.

static PersonalizerClient InitializePersonalizerClient(Uri url)
{
    // Set the local inference flag to true when initializing the client.
    return new PersonalizerClient(url, new AzureKeyCredential(ResourceKey), new PersonalizerClientOptions(useLocalInference: true));
}

Abrufen von Inhaltsoptionen, dargestellt als Aktionen

Aktionen stellen die Inhaltsoptionen dar, aus denen die Personalisierung das beste Inhaltselement auswählen soll. Fügen Sie der Klasse „Program“ die folgenden Methoden hinzu, um die Gruppe der Aktionen und deren Features darzustellen.

static IList<PersonalizerRankableAction> GetActions()
{
    IList<PersonalizerRankableAction> actions = new List<PersonalizerRankableAction>
    {
        new PersonalizerRankableAction(
            id: "pasta",
            features: new List<object>() { new { taste = "salty", spiceLevel = "medium" }, new { nutritionLevel = 5, cuisine = "italian" } }
        ),

        new PersonalizerRankableAction(
            id: "ice cream",
            features: new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionalLevel = 2 } }
        ),

        new PersonalizerRankableAction(
            id: "juice",
            features: new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionLevel = 5 }, new { drink = true } }
        ),

        new PersonalizerRankableAction(
            id: "salad",
            features: new List<object>() { new { taste = "salty", spiceLevel = "low" }, new { nutritionLevel = 8 } }
        )
    };

    return actions;
}

Abrufen von Benutzerwünschen für den Kontext

Fügen Sie der Klasse „Program“ die folgenden Methoden hinzu, um die Benutzereingaben für Tageszeit und geschmackliche Vorlieben aus der Befehlszeile abzurufen. Diese werden als Kontextfeatures verwendet.

static string GetTimeOfDayForContext()
{
    string[] timeOfDayFeatures = new string[] { "morning", "afternoon", "evening", "night" };

    Console.WriteLine("\nWhat time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night");
    if (!int.TryParse(GetKey(), out int timeIndex) || timeIndex < 1 || timeIndex > timeOfDayFeatures.Length)
    {
        Console.WriteLine("\nEntered value is invalid. Setting feature value to " + timeOfDayFeatures[0] + ".");
        timeIndex = 1;
    }

    return timeOfDayFeatures[timeIndex - 1];
}

static string GetUsersTastePreference()
{
    string[] tasteFeatures = new string[] { "salty", "sweet" };
    var random = new Random();
    var taste = random.Next(1, 2);

    Console.WriteLine("\nWhat type of food would you prefer (enter number)? 1. salty 2. sweet");
    if (!int.TryParse(GetKey(), out int tasteIndex) || tasteIndex < 1 || tasteIndex > tasteFeatures.Length)
    {
        Console.WriteLine("\nEntered value is invalid. Setting feature value to " + tasteFeatures[0] + ".");
        tasteIndex = 1;
    }

    return tasteFeatures[taste - 1];
}

Bei beiden Methoden wird die Methode GetKey verwendet, um die Auswahl des Benutzers aus der Befehlszeile zu lesen.

private static string GetKey()
{
    return Console.ReadKey().Key.ToString().Last().ToString().ToUpper();
}

private static IList<object> GetContext(string time, string taste)
{
    return new List<object>()
    {
        new { time = time },
        new { taste = taste }
    };
}

Erstellen der Lernschleife

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.

Der folgende Code durchläuft einen Zyklus durch eine Schleife: Der Benutzer wird an der Befehlszeile nach seinen Präferenzen befragt, die Angaben werden zur Wahl der besten Aktion für jeden Slot an die Personalisierung gesendet, die Auswahl wird dem Kunden in einer Auswahlliste angezeigt, und anschließend wird eine Relevanzbewertung an die Personalisierung gesendet, die angibt, wie gut die Wahl des Diensts war.

static void Main(string[] args)
{
    Console.WriteLine($"Welcome to this Personalizer Quickstart!\n" +
    $"This code will help you understand how to use the Personalizer APIs (rank and reward).\n" +
    $"Each iteration represents a user interaction and will demonstrate how context, actions, and rewards work.\n" +
    $"Note: Personalizer AI models learn from a large number of user interactions:\n" +
    $"You won't be able to tell the difference in what Personalizer returns by simulating a few events by hand.\n" +
    $"If you want a sample that focuses on seeing how Personalizer learns, see the Python Notebook sample.");

    int iteration = 1;
    bool runLoop = true;

    IList<PersonalizerRankableAction> actions = GetActions();
    PersonalizerClient client = InitializePersonalizerClient(new Uri(ServiceEndpoint));

    do
    {
        Console.WriteLine("\nIteration: " + iteration++);

        string timeOfDayFeature = GetTimeOfDayForContext();
        string deviceFeature = GetUsersTastePreference();

        IList<object> currentContext = GetContext(timeOfDayFeature, deviceFeature);

        string eventId = Guid.NewGuid().ToString();

        var rankOptions = new PersonalizerRankOptions(actions: actions, contextFeatures: currentContext, eventId: eventId);
        PersonalizerRankResult rankResult = client.Rank(rankOptions);

        Console.WriteLine("\nPersonalizer service thinks you would like to have: " + rankResult.RewardActionId + ". Is this correct? (y/n)");

        float reward = 0.0f;
        string answer = GetKey();

        if (answer == "Y")
        {
            reward = 1.0f;
            Console.WriteLine("\nGreat! Enjoy your food.");
        }
        else if (answer == "N")
        {
            reward = 0.0f;
            Console.WriteLine("\nYou didn't like the recommended food choice.");
        }
        else
        {
            Console.WriteLine("\nEntered choice is invalid. Service assumes that you didn't like the recommended food choice.");
        }

        client.Reward(rankResult.EventId, reward);

        Console.WriteLine("\nPress q to break, any other key to continue:");
        runLoop = !(GetKey() == "Q");

    } while (runLoop);
}

Ausführen des Programms

Führen Sie die Anwendung mit dem Befehl dotnet run über das Anwendungsverzeichnis aus.

dotnet run