Introduzione all'SDK di inferenza locale per Personalizza esperienze di intelligenza artificiale di Azure

Importante

A partire dal 20 settembre 2023 non sarà possibile creare nuove risorse di Personalizza esperienze. Il servizio Personalizza esperienze viene ritirato il 1° ottobre 2026.

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

Nella portale di Azure passare alla pagina Configurazione della risorsa personalizza esperienze e modificare la frequenza di aggiornamento del modello in 30 secondi. Questa breve durata eseguirà rapidamente il training del modello, consentendo di vedere come cambia l'azione consigliata per ogni iterazione.

Modificare il tempo di attesa della ricompensa

Nella portale di Azure passare alla pagina Configurazione della risorsa personalizza esperienze e modificare il tempo di attesa 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

Suggerimento

Se si usa l'ambiente di sviluppo integrato di Visual Studio, la libreria client è disponibile come pacchetto NuGet scaricabile.

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 Personalizza esperienzeClient 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 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.

Importante

Vai al portale di Azure. Se la risorsa Personalizza esperienze creata nella sezione Prerequisiti è stata distribuita correttamente, fare clic sul pulsante Vai alla risorsa in Passaggi successivi. La chiave e l'endpoint saranno disponibili nella pagina Chiavi ed endpoint della risorsa in Gestione risorse.

Al termine, ricordarsi di rimuovere la chiave dal codice e non renderlo mai pubblico. Per la produzione, è consigliabile usare un modo sicuro per archiviare e accedere alle credenziali, ad esempio 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>";

Creare quindi gli URL di classificazione e ricompensa. Si noti che l'impostazione useLocalInference: true come parametro per è necessaria per PersonalizerClientOptions 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 scorre un ciclo di richiesta all'utente delle proprie preferenze tramite la riga di comando, inviando tali informazioni a Personalizza esperienze per selezionare l'azione migliore per ogni slot, presentando la selezione al cliente da scegliere tra l'elenco, quindi inviando un punteggio di ricompensa a Personalizza esperienze segnalando quanto sia stato eseguito il 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