Ismerkedés az Azure AI Personalizer helyi következtetési SDK-jával

Fontos

2023. szeptember 20-tól nem hozhat létre új Personalizer-erőforrásokat. A Personalizer szolgáltatás 2026. október 1-jén megszűnik.

A Personalizer helyi következtetési SDK (előzetes verzió) helyileg letölti a Personalizer-modellt, és így jelentősen csökkenti a rangsorolt hívások késését a hálózati hívások kiiktatásával. Az ügyfél percenként letölti a legújabb modellt a háttérben, és következtetésre használja.

Ebben az útmutatóban megtudhatja, hogyan használhatja a Personalizer helyi következtetési SDK-t.

A .NET-hez készült Personalizer ügyfélkódtárat a következőre kell telepítenie:

• Hitelesítse a gyorsútmutató példaügyfélt egy Personalizer-erőforrással az Azure-ban.
• Környezet- és műveletfunkciók küldése a Reward API-nak, amely a Legjobb műveletet adja vissza a Personalizer-modellből
• Küldjön jutalompontot a Rank API-nak, és tanítsa be a Personalizer-modellt.

Referenciadokumentáció Kódtár forráskódcsomagja | (NuGet) |

Előfeltételek

• Azure-előfizetés – Ingyenes létrehozás
• A .NET Core aktuális verziója.
• Miután megkapta az Azure-előfizetését, hozzon létre egy Personalizer-erőforrást az Azure Portalon a kulcs és a végpont lekéréséhez. Az üzembe helyezés után válassza az Ugrás az erőforrásra lehetőséget.
  • Az alkalmazás a Personalizer API-hoz való csatlakoztatásához szüksége lesz a létrehozott erőforrás kulcsára és végpontjára. A rövid útmutató későbbi részében illessze be a kulcsot és a végpontot az alábbi kódba.
  • Az ingyenes tarifacsomag (F0) használatával kipróbálhatja a szolgáltatást, és később frissíthet egy fizetős szintre az éles környezetben.

Beállítás

A modellfrissítés gyakoriságának módosítása

Az Azure Portalon nyissa meg a Personalizer-erőforrás konfigurációs oldalát, és módosítsa a modellfrissítés gyakoriságát 30 másodpercre. Ez a rövid időtartam gyorsan betaníthatja a modellt, így láthatja, hogyan változik az egyes iterációkhoz javasolt művelet.

A jutalom várakozási idejének módosítása

Az Azure Portalon nyissa meg a Personalizer-erőforrás konfigurációs oldalát, és módosítsa a Reward várakozási idejét 10 percre. Ez határozza meg, hogy a modell mennyi ideig fog várni a javaslat elküldése után, hogy megkapja a javaslat jutalom-visszajelzését. A betanítás addig nem történik meg, amíg a jutalom várakozási ideje el nem telik.

Új C#-alkalmazás létrehozása

Hozzon létre egy új .NET Core-alkalmazást az előnyben részesített szerkesztőben vagy IDE-ben.

Egy konzolablakban (például parancsmag, PowerShell vagy Bash) a dotnet new paranccsal hozzon létre egy új, a névvel personalizer-quickstartellátott konzolalkalmazást. Ez a parancs egy egyszerű ""Helló világ!" alkalmazás" C#-projektet hoz létre egyetlen forrásfájllal: Program.cs.

dotnet new console -n personalizer-quickstart

Módosítsa a könyvtárat az újonnan létrehozott alkalmazásmappára. Az alkalmazást a következőkkel hozhatja létre:

dotnet build

A buildkimenet nem tartalmazhat figyelmeztetést vagy hibát.

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

Telepítse az ügyfélkódtárat

Az alkalmazáskönyvtárban telepítse a .NET-hez készült Personalizer ügyfélkódtárat a következő paranccsal:

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

Tipp.

Ha a Visual Studio IDE-t használja, az ügyfélkódtár letölthető NuGet-csomagként érhető el.

Nyissa meg a fájlt a projektkönyvtárban az Program.cs előnyben részesített szerkesztőben vagy IDE-ben. Adja hozzá az alábbi irányelveket:

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

Objektummodell

A Personalizer-ügyfél egy PersonalizerClient objektum, amely az Azure-ban az Azure.AzureKeyCredential használatával hitelesíti a kulcsot.

Ha egyetlen legjobb elemet szeretne kérni a felhasználó megjelenítéséhez, hozzon létre egy PersonalizerRankOptions elemet, majd adja át a PersonalizerClient.Rank metódusnak. A Rank metódus egy PersonalizerRankResult értéket ad vissza.

Ha jutalompontot szeretne küldeni a Personalizernek, adja át az eseményazonosítót és a jutalompontszámot a PersonalizerClient.Reward metódusnak.

A jutalompont meghatározása ebben a rövid útmutatóban triviális. Egy éles rendszerben annak meghatározása, hogy mi befolyásolja a jutalompontszámot , és hogy mennyi lehet egy összetett folyamat, amelyet idővel megváltoztathat. Ennek a tervezési döntésnek kell lennie a Personalizer-architektúra egyik elsődleges döntésének.

Kódpéldák

Ezek a kódrészletek bemutatják, hogyan végezheti el a következő feladatokat a .NET-hez készült Personalizer ügyfélkódtárral:

• Personalizer-ügyfél létrehozása
• Többhelyes Rangsor API
• Többhelyes Reward API

Az ügyfél hitelesítése

Ebben a szakaszban két dolgot fog elvégezni:

• A kulcs és a végpont megadása
• Personalizer-ügyfél létrehozása

Először adja hozzá a következő sorokat a Program osztályhoz. Mindenképpen adja hozzá a kulcsot és a végpontot a Personalizer-erőforrásból.

Fontos

Nyissa meg az Azure Portalt. Ha az Előfeltételek szakaszban létrehozott Personalizer-erőforrás sikeresen üzembe lett helyezve, kattintson az Ugrás az erőforrásra gombra a Következő lépések csoportban. A kulcsot és a végpontot az erőforrás kulcs- és végpontoldalán, az erőforrás-kezelés alatt találja.

Ne felejtse el eltávolítani a kulcsot a kódból, amikor elkészült, és soha ne tegye közzé nyilvánosan. Éles környezetben fontolja meg a hitelesítő adatok biztonságos tárolását és elérését. Például az 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>";

Ezután hozza létre a Rangsor és a Reward URL-címeket. Vegye figyelembe, hogy a helyi következtetés engedélyezéséhez PersonalizerClientOptions paraméterként való beállítás useLocalInference: true szükséges.

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

Tartalomválasztási lehetőségek lekérése műveletként

A műveletek azokat a tartalomválasztásokat jelölik, amelyek közül a Personalizer a legjobb tartalomelemet szeretné kiválasztani. Adja hozzá a következő metódusokat a Program osztályhoz a műveletek és azok funkcióinak megjelenítéséhez.

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

Felhasználói beállítások lekérése a környezethez

Adja hozzá a következő metódusokat a Program osztályhoz, hogy lekérje a felhasználó bemenetét a parancssorból a nap és a felhasználó ízlésének megfelelően. Ezek környezeti funkciókként lesznek használva.

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

Mindkét módszer a GetKey metódus használatával olvassa be a felhasználó kijelölését a parancssorból.

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

A tanulási ciklus létrehozása

A Personalizer tanulási ciklus a Rang- és Reward-hívások ciklusa. Ebben a rövid útmutatóban a tartalom személyre szabása érdekében minden Rang-hívást egy Reward-hívás követ, amely tájékoztatja a Személyreszabót a szolgáltatás teljesítményéről.

A következő kód végighalad egy cikluson, amely során megkérdezi a felhasználót a beállításokról a parancssoron keresztül, és elküldi ezeket az információkat a Personalizernek, hogy az egyes pontokhoz a legjobb műveletet válassza ki, és a listából válassza ki az ügyfelet, majd küldjön egy jutalompontszámot a Personalizernek, jelezve, hogy a szolgáltatás milyen jól teljesített a kiválasztás során.

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

A program futtatása

Futtassa az alkalmazást a dotnet run paranccsal az alkalmazáskönyvtárból.

dotnet run