Začínáme s místní sadou SDK pro odvozování pro Azure AI Personalizátor

Důležité

Od 20. září 2023 nebudete moct vytvářet nové prostředky personalizace. Služba Personalizace se vyřadí z provozu 1. října 2026.

Sada SDK pro místní odvozování personalizace (Preview) stáhne model Personalizace místně, a tím výrazně snižuje latenci volání pořadí odstraněním síťových volání. Klient si každou minutu stáhne nejnovější model na pozadí a použije ho k odvozování.

V této příručce se dozvíte, jak používat sadu SDK pro odvození místního odvozovače Personalizace.

Pro .NET budete muset nainstalovat klientskou knihovnu Personalizace, aby:

• Ověřte ukázkového klienta rychlého startu pomocí prostředku Personalizace v Azure.
• Odeslání kontextových funkcí a funkcí akcí do rozhraní API odměny, které vrátí nejlepší akci z modelu Personalizace
• Pošlete skóre odměny do rozhraní Rank API a vytrénujte model Personalizace.

Referenční dokumentace | – Balíček zdrojového kódu | knihovny (NuGet)

Požadavky

• Předplatné Azure: Můžete si ho vytvořit zdarma.
• Aktuální verze .NET Core.
• Jakmile budete mít předplatné Azure, vytvořte na webu Azure Portal prostředek Personalizace, abyste získali svůj klíč a koncový bod. Po nasazení vyberte Přejít k prostředku.
  • K připojení aplikace k rozhraní API personalizace budete potřebovat klíč a koncový bod z prostředku, který vytvoříte. Klíč a koncový bod vložíte do kódu níže v rychlém startu.
  • K vyzkoušení služby můžete použít cenovou úroveňF0 Free a později upgradovat na placenou úroveň pro produkční prostředí.

Nastavení

Změna frekvence aktualizace modelu

Na webu Azure Portal přejděte na stránku Konfigurace prostředku Personalizace a změňte frekvenci aktualizace modelu na 30 sekund. Tato krátká doba trvání model rychle vytrénuje a umožní vám zjistit, jak se doporučené akce mění pro každou iteraci.

Změna doby čekání na odměnu

Na webu Azure Portal přejděte na stránku Konfigurace prostředku Personalizace a změňte dobu čekání na odměnu na 10 minut. To určuje, jak dlouho bude model čekat po odeslání doporučení, aby od tohoto doporučení obdržel zpětnou vazbu o odměně. Trénování se neprojeví, dokud nepřejde doba čekání na odměnu.

Vytvoření nové aplikace jazyka C#

V preferovaném editoru nebo integrovaném vývojovém prostředí (IDE) vytvořte novou aplikaci .NET Core.

V okně konzoly (například cmd, PowerShell nebo Bash) pomocí příkazu dotnet new vytvořte novou konzolovou aplikaci s názvem personalizer-quickstart. Tento příkaz vytvoří jednoduchý projekt "Hello World" C# s jedním zdrojovým souborem: Program.cs.

dotnet new console -n personalizer-quickstart

Změňte adresář na nově vytvořenou složku aplikace. Aplikaci můžete sestavit pomocí následujících:

dotnet build

Výstup sestavení by neměl obsahovat žádná upozornění ani chyby.

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

Instalace klientské knihovny

V adresáři aplikace nainstalujte klientskou knihovnu Personalizace pro .NET pomocí následujícího příkazu:

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

Tip

Pokud používáte integrované vývojové prostředí sady Visual Studio, je klientská knihovna k dispozici jako balíček NuGet ke stažení.

V adresáři projektu otevřete Program.cs soubor v preferovaném editoru nebo integrovaném vývojovém prostředí (IDE). Přidejte následující direktivy using:

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

Objektový model

Klient Personalizace je objekt PersonalizaceClient , který se ověřuje v Azure pomocí Azure.AzureKeyCredential, který obsahuje váš klíč.

Pokud chcete požádat o jednu nejlepší položku k zobrazení uživatele, vytvořte PersonalizaceRankOptions a pak ji předejte metodě PersonalrClient.Rank. Metoda Rank vrátí PersonalrRankResult.

Pokud chcete odeslat skóre odměny personalizaci, předejte ID události a skóre odměny metodě PersonalizaceClient.Rewards .

Určení skóre odměny je v tomto rychlém startu triviální. V produkčním systému se určení toho, co má vliv na skóre odměny, a o tom, kolik může být složitým procesem, se můžete rozhodnout změnit v průběhu času. Toto rozhodnutí o návrhu by mělo být jedním z hlavních rozhodnutí v architektuře Personalizace.

Příklady kódu

Tyto fragmenty kódu ukazují, jak provádět následující úlohy s klientskou knihovnou Personalizace pro .NET:

• Vytvoření klienta personalizace
• Rozhraní API pro řazení více slotů
• Rozhraní API odměn pro více slotů

Ověření klienta

V této části provedete dvě věci:

• Zadání klíče a koncového bodu
• Vytvoření klienta personalizace

Začněte přidáním následujících řádků do třídy Program. Nezapomeňte přidat klíč a koncový bod z prostředku Personalizace.

Důležité

Přejděte na Azure Portal. Pokud se prostředek Personalizace, který jste vytvořili v části Požadavky, úspěšně nasadil, klikněte v části Další kroky na tlačítko Přejít k prostředku. Klíč a koncový bod najdete na stránce klíče a koncového bodu prostředku v části Správa prostředků.

Nezapomeňte klíč z kódu odebrat, až to budete hotovi, a nikdy ho veřejně neposílejte. V produkčním prostředí zvažte použití zabezpečeného způsobu ukládání a přístupu k vašim přihlašovacím údajům. Například 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>";

Dále vytvořte adresy URL pořadí a odměny. Mějte na paměti, že nastavení useLocalInference: true jako parametr pro PersonalizerClientOptions je nutné povolit místní odvozování.

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

Získání možností obsahu reprezentovaných jako akcí

Akce představují volby obsahu, ze kterých chcete personalizaci vybrat nejlepší položku obsahu. Do třídy Program přidejte následující metody, které představují sadu akcí a jejich funkcí.

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

Získání uživatelských předvoleb pro kontext

Přidejte do třídy Program následující metody, abyste získali vstup uživatele z příkazového řádku pro denní a uživatelskou chuť. Tyto funkce se použijí jako kontextové funkce.

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

Obě metody používají metodu GetKey ke čtení výběru uživatele z příkazového řádku.

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

Vytvoření smyčky učení

Smyčka učení Personalizace je cyklus volání Rank a Rewards. V tomto rychlém startu je za každým voláním pořadí přizpůsobení obsahu následovat volání odměny, které personalizátoru sdělí, jak dobře služba fungovala.

Následující kód prochází cyklus dotazování uživatele na jeho předvolby prostřednictvím příkazového řádku, odesláním těchto informací personalizaci vybrat nejlepší akci pro každý slot, prezentovat výběr zákazníkovi, který si vybere ze seznamu, a pak odeslat skóre odměny personalizaci signalizuje, jak dobře služba ve výběru udělala.

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

Spuštění programu

Spusťte aplikaci příkazem dotnet run z adresáře vaší aplikace.

dotnet run