Introduzione all'SDK di inferenza locale per Personalizza esperienze di Azure AI

L'SDK di inferenza locale di Personalizza esperienze (anteprima) scarica il modello di Personalizza esperienze in locale e quindi riduce significativamente la latenza delle chiamate di classificazione eliminando le chiamate di rete. Ogni minuto il client scaricherà il modello più recente in background e lo userà per l'inferenza.

In questa guida si apprenderà come usare l'SDK di inferenza locale di Personalizza esperienze.

È necessario installare la libreria client di Personalizza esperienze per .NET per:

• Autenticare il client di esempio di avvio rapido con una risorsa personalizza esperienze in Azure.
• Inviare funzionalità di contesto e azione all'API Ricompensa, che restituirà l'azione migliore dal modello di Personalizza esperienze
• Inviare un punteggio di ricompensa all'API Classificazione ed eseguire il training del modello di Personalizza esperienze.

Documentazione di riferimento | Codice sorgente della libreria | Pacchetto (NuGet)

Prerequisiti

• Sottoscrizione di Azure: creare un account gratuito
• Versione corrente di .NET Core
• Dopo aver creato la sottoscrizione di Azure, creare una risorsa Personalizza esperienze nel portale di Azure per ottenere la chiave e l'endpoint. Al termine della distribuzione, fare clic su Vai alla risorsa.
  • La chiave e l'endpoint della risorsa creata sono necessari per connettere l'applicazione all'API Personalizza esperienze. La chiave e l'endpoint verranno incollati nel codice riportato di seguito nell'argomento di avvio rapido.
  • È possibile usare il piano tariffario gratuito (F0) per provare il servizio ed eseguire in un secondo momento l'aggiornamento a un livello a pagamento per la produzione.

Configurazione

Modificare la frequenza di aggiornamento del modello

Nel portale di Azure, andare alla pagina Configurazione di Personalizza esperienze e modificare la Frequenza di aggiornamento del modello impostandola su 30 secondi. Con questa breve durata il training del modello verrà eseguito rapidamente e sarà possibile visualizzare il cambiamento dell'azione suggerita per ogni iterazione.

Modificare il tempo di attesa della ricompensa

Nel portale di Azure, andare alla pagina Configurazione di Personalizza esperienze e impostare Tempo di attesa della ricompensa su 10 minuti. Ciò determina per quanto tempo il modello attenderà dopo l'invio di una raccomandazione, per ricevere il feedback sulla ricompensa da tale raccomandazione. Il training non verrà eseguito fino a quando non è trascorso il tempo di attesa della ricompensa.

Creare una nuova applicazione C#

Creare una nuova applicazione .NET Core nell'ambiente di sviluppo integrato o nell'editor preferito.

Nella finestra di una console (ad esempio cmd, PowerShell o Bash) usare il comando dotnet new per creare una nuova app console con il nome personalizer-quickstart. Questo comando crea un semplice progetto C# "Hello World" con un singolo file di origine: Program.cs.

dotnet new console -n personalizer-quickstart

Spostarsi nella cartella dell'app appena creata. È possibile compilare l'applicazione con il comando seguente:

dotnet build

L'output di compilazione non deve contenere alcun avviso o errore.

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

Installare la libreria client

Nella directory dell'applicazione installare la libreria client di Personalizza esperienze per .NET con il comando seguente:

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

Dalla directory del progetto aprire il file Program.cs nell'editor o nell'IDE preferito. Aggiungere le direttive using seguenti:

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

Modello a oggetti

Il client di Personalizza esperienze è un oggetto PersonalizerClient che esegue l'autenticazione in Azure usando Azure.AzureKeyCredential, che contiene la chiave.

Per richiedere il singolo elemento migliore per visualizzare l'utente, creare un oggetto Personalizza esperienzeRankOptions e quindi passarlo al metodo Personalizza esperienzeClient.Rank. Il metodo Rank restituisce un oggetto Personalizza esperienzeRankResult.

Per inviare un punteggio di ricompensa a Personalizza esperienze, passare l'ID evento e il punteggio di ricompensa al metodo Personalizza esperienzeClient.Reward.

In questo argomento di avvio rapido, determinare il punteggio di ricompensa è semplice. In un sistema di produzione invece, stabilire cosa influisce sul punteggio di ricompensa e in quale misura può essere un processo complesso, che si può decidere di cambiare nel tempo. Questa dovrebbe essere una delle principali decisioni di progettazione da prendere nell'architettura di Personalizza esperienze.

Esempi di codice

Questi frammenti di codice mostrano come eseguire le operazioni seguenti con la libreria client di Personalizza esperienze per .NET:

• Creare un client di Personalizza esperienze
• API di classificazione multi-slot
• API ricompensa multi-slot

Autenticare il client

In questa sezione verranno eseguite due operazioni:

• Specificare la chiave e l'endpoint
• Creare un client di Personalizza esperienze

Per iniziare, aggiungere le righe seguenti alla classe Program. Assicurarsi di aggiungere la chiave e l'endpoint dalla risorsa Personalizza esperienze.

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

Creare quindi gli URL di classificazione e ricompensa. Si noti che l'impostazione useLocalInference: true come parametro per PersonalizerClientOptions è necessaria per abilitare l'inferenza locale.

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

Ottenere scelte di contenuto rappresentate come azioni

Le azioni rappresentano le scelte di contenuto da cui si vuole che Personalizza esperienze selezioni l'elemento di contenuto migliore. Aggiungere i metodi seguenti alla classe Program per rappresentare il set di azioni e le relative caratteristiche.

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

Recuperare le preferenze dell'utente per il contesto

Aggiungere i metodi seguenti alla classe Program per ottenere l'input di un utente dalla riga di comando per l'ora del giorno e le preferenze di gusto dell’utente. Si useranno come caratteristiche del contesto.

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

Entrambi i metodi usano il metodo GetKey per leggere la selezione dell'utente dalla riga di comando.

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

Creare il ciclo di apprendimento

Il ciclo di apprendimento di Personalizza esperienze è un ciclo di chiamate Rank e Reward. In questo argomento di avvio rapido ogni chiamata Rank per personalizzare il contenuto è seguita da una chiamata Reward per indicare a Personalizza esperienze il livello di prestazioni del servizio.

Il codice seguente esegue un ciclo in cui chiede all'utente di indicare le proprie preferenze tramite la riga di comando, invia tali informazioni a Personalizza esperienze per la selezione dell'azione migliore per ogni slot, presenta all'utente una selezione sotto forma di elenco da cui scegliere e quindi invia un punteggio di ricompensa a Personalizza esperienze per segnalare l'accuratezza del servizio nella selezione.

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

Eseguire il programma

Eseguire l'applicazione con il comando dotnet run dalla directory dell'applicazione.

dotnet run