Aan de slag met de lokale deductie-SDK voor Azure AI Personalizer

Belangrijk

Vanaf 20 september 2023 kunt u geen nieuwe Personalizer-resources maken. De Personalizer-service wordt op 1 oktober 2026 buiten gebruik gesteld.

De personalizer lokale deductie-SDK (preview) downloadt het Personalizer-model lokaal en vermindert zo de latentie van Rank-aanroepen aanzienlijk door netwerkoproepen te elimineren. Elke minuut downloadt de client het meest recente model op de achtergrond en gebruikt het voor deductie.

In deze handleiding leert u hoe u de locale deductie-SDK van Personalizer gebruikt.

U moet de Personalizer-clientbibliotheek voor .NET installeren om:

• Verifieer de quickstart-voorbeeldclient met een Personalizer-resource in Azure.
• Context- en actiefuncties verzenden naar de Reward-API, die de beste actie van het Personalizer-model retourneert
• Verzend een beloningsscore naar de Rank-API en train het Personalizer-model.

Broncodepakket voor referentiedocumentatiebibliotheek | | (NuGet)

Vereisten

• Azure-abonnement: Krijg een gratis abonnement
• De huidige versie van .NET Core.
• Zodra u uw Azure-abonnement hebt, maakt u een Personalizer-resource in Azure Portal om uw sleutel en eindpunt op te halen. Nadat de app is geïmplementeerd, selecteert u Ga naar resource.
  • U hebt de sleutel en het eindpunt nodig van de resource die u maakt, om de toepassing te verbinden met de Personalizer-API. Later in de quickstart plakt u uw sleutel en eindpunt in de onderstaande code.
  • U kunt de gratis prijscategorie (F0) gebruiken om de service uit te proberen, en later upgraden naar een betaalde laag voor productie.

Instellen

Bijwerkfrequentie voor model wijzigen

Ga in Azure Portal naar de configuratiepagina van uw Personalizer-resource en wijzig de frequentie van de modelupdate in 30 seconden. Met deze korte duur wordt het model snel getraind, zodat u kunt zien hoe de aanbevolen actie voor elke iteratie verandert.

De beloningswachttijd wijzigen

Ga in Azure Portal naar de configuratiepagina van uw Personalizer-resource en wijzig de wachttijd voor beloning in 10 minuten. Dit bepaalt hoe lang het model wacht na het verzenden van een aanbeveling, om de beloningsfeedback van die aanbeveling te ontvangen. Training vindt pas plaats als de wachttijd voor de beloning is verstreken.

Een nieuwe C#-toepassing maken

Maak een nieuwe .NET Core-toepassing in uw favoriete editor of IDE.

Gebruik in een consolevenster (zoals cmd, PowerShell of Bash) de opdracht dotnet new om een nieuwe console-app te maken met de naam personalizer-quickstart. Met deze opdracht maakt u een eenvoudig Hallo wereld-C#-project met één bronbestand: Program.cs.

dotnet new console -n personalizer-quickstart

Wijzig uw map in de zojuist gemaakte app-map. U kunt de toepassing maken met:

dotnet build

De build-uitvoer mag geen waarschuwingen of fouten bevatten.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

De clientbibliotheek installeren

Installeer in de toepassingsmap de Personalizer-clientbibliotheek voor .NET met de volgende opdracht:

dotnet add package Azure.AI.Personalizer --version 2.0.0-beta.2

Tip

Als u de Visual Studio-IDE, gebruikt, is de clientbibliotheek beschikbaar als downloadbaar NuGet-pakket.

Open vanuit de projectmap bestand Program.cs in uw favoriete editor of IDE. Voeg het volgende toe met behulp van de instructies:

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

Objectmodel

De Personalizer-client is een PersonalizerClient-object dat wordt geverifieerd bij Azure met behulp van Azure.AzureKeyCredential, die uw sleutel bevat.

Als u het beste item wilt vragen om de gebruiker weer te geven, maakt u een PersonalizerRankOptions en geeft u het vervolgens door aan de methode PersonalizerClient.Rank . De rank-methode retourneert een PersonalizerRankResult.

Als u een beloningsscore naar Personalizer wilt verzenden, geeft u de gebeurtenis-id en de beloningsscore door aan de methode PersonalizerClient.Reward .

Het bepalen van de beloningsscore in deze quickstart is triviaal. In een productiesysteem kan de bepaling wat van invloed is op de beloningsscore en in welke mate, een complex proces zijn, dat u in de loop van de tijd zou kunnen wijzigen. Deze ontwerpbeslissing moet een van de belangrijkste beslissingen in uw Personalizer-architectuur zijn.

Codevoorbeelden

Deze codefragmenten laten zien hoe u de volgende taken kunt uitvoeren met de Personalizer-clientbibliotheek voor .NET:

• Personalizer-client maken
• Rank-API met meerdere sleuf
• Reward-API voor meerdere sleufs

De client verifiëren

In deze sectie doet u twee dingen:

• Uw sleutel en eindpunt opgeven
• Personalizer-client maken

Voeg eerst de volgende regels toe aan de klasse Programma. Denk erom dat u de sleutel en het eindpunt van uw Personalizer-resource toevoegt.

Belangrijk

Ga naar de Azure Portal. Als de Personalizer-resource die u in de sectie Vereisten hebt gemaakt, succesvol is geïmplementeerd, klikt u op de knop Ga naar resource onder Volgende stappen. U vindt uw sleutel en eindpunt op de pagina Sleutel en eindpunt van de resource, onder Resourcebeheer.

Vergeet niet de sleutel uit uw code te verwijderen wanneer u klaar bent, en maak deze sleutel nooit openbaar. Overweeg om voor productie een veilige manier te gebruiken voor het opslaan en openen van uw referenties. Bijvoorbeeld 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>";

Vervolgens maakt u de RANK- en Reward-URL's. Houd er rekening mee dat de instelling useLocalInference: true als parameter PersonalizerClientOptions is vereist om lokale deductie in te schakelen.

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

Inhoudskeuzes ophalen die worden weergegeven als acties

Acties vertegenwoordigen de inhoudskeuzes waaruit Personalizer het beste inhoudsitem moet selecteren. Voeg de volgende methoden aan de klasse Programma toe om de reeks acties en hun functies te representeren.

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

Gebruikersvoorkeuren voor context ophalen

Voeg de volgende methoden toe aan de klasse Program om de invoer van een gebruiker op te halen vanaf de opdrachtregel voor het tijdstip van de dag en de voorkeur voor de smaak van de gebruiker. Deze worden als contextkenmerken gebruikt.

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

Beide methoden maken gebruik van de methode GetKey om de vanaf de opdrachtregel selectie van de gebruiker te lezen.

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

De leerlus maken

De Personalizer-leerlus is een cyclus van Positie- en Beloning-aanroepen. In deze quickstart wordt elke Positie-oproep, voor het personaliseren van de inhoud, gevolgd door een Beloning-oproep om Personalizer te laten weten hoe goed de service is uitgevoerd.

De volgende code doorloopt een cyclus van het vragen van de gebruikers hun voorkeuren via de opdrachtregel, het verzenden van die informatie naar Personalizer om de beste actie voor elke site te selecteren, de selectie aan de klant te presenteren uit de lijst en vervolgens een beloningsscore te verzenden naar Personalizer die aangeeft hoe goed de service in de selectie heeft gedaan.

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

Het programma uitvoeren

Voer de toepassing uit vanuit uw toepassingsmap met de opdracht dotnet run.

dotnet run