Introdução ao SDK de inferência local para o Azure AI Personalizer

Importante

A partir de 20 de setembro de 2023, você não poderá criar novos recursos do Personalizador. O serviço de Personalizador será aposentado no dia 1º de outubro de 2026.

O SDK de inferência local do Personalizer (Preview) baixa o modelo do Personalizer localmente e, assim, reduz significativamente a latência das chamadas de Rank eliminando as chamadas de rede. A cada minuto, o cliente baixará o modelo mais recente em segundo plano e o usará para inferência.

Neste guia, você aprenderá a usar o SDK de inferência local do Personalizer.

Você precisará instalar a biblioteca de cliente do Personalizer para .NET para:

• Autentique o cliente de exemplo de início rápido com um recurso do Personalizador no Azure.
• Envie recursos de contexto e ação para a API de recompensa, que retornará a melhor ação do modelo do Personalizador
• Envie uma pontuação de recompensa para a API de classificação e treine o modelo do personalizador.

Documentação | de referência Pacote de código-fonte | da biblioteca (NuGet)

Pré-requisitos

• Subscrição do Azure - Criar uma gratuitamente
• A versão atual do .NET Core.
• Depois de ter sua assinatura do Azure, crie um recurso do Personalizador no portal do Azure para obter sua chave e ponto de extremidade. Depois de implantar, selecione Ir para recurso.
  • Você precisará da chave e do ponto de extremidade do recurso criado para conectar seu aplicativo à API do Personalizador. Você colará sua chave e ponto de extremidade no código abaixo mais adiante no início rápido.
  • Você pode usar o nível de preço gratuito (F0) para experimentar o serviço e atualizar posteriormente para um nível pago para produção.

Configuração

Alterar a frequência de atualização do modelo

No portal do Azure, vá para a página Configuração do recurso Personalizador e altere a frequência de atualização do modelo para 30 segundos. Essa curta duração treinará o modelo rapidamente, permitindo que você veja como a ação recomendada muda para cada iteração.

Alterar o tempo de espera da recompensa

No portal do Azure, vá para a página Configuração do recurso Personalizador e altere o tempo de espera do Reward para 10 minutos. Isso determina quanto tempo o modelo esperará após o envio de uma recomendação, para receber o feedback da recompensa dessa recomendação. O treinamento não ocorrerá até que o tempo de espera da recompensa tenha passado.

Criar um novo aplicativo C#

Crie um novo aplicativo .NET Core em seu editor ou IDE preferido.

Em uma janela de console (como cmd, PowerShell ou Bash), use o comando dotnet new para criar um novo aplicativo de console com o nome personalizer-quickstart. Este comando cria um projeto C# "Hello World" simples com um único arquivo de origem: Program.cs.

dotnet new console -n personalizer-quickstart

Altere seu diretório para a pasta do aplicativo recém-criada. Você pode criar o aplicativo com:

dotnet build

A saída da compilação não deve conter avisos ou erros.

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

Instalar a biblioteca de cliente

Dentro do diretório do aplicativo, instale a biblioteca de cliente do Personalizer para .NET com o seguinte comando:

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

Gorjeta

Se você estiver usando o IDE do Visual Studio, a biblioteca de cliente estará disponível como um pacote NuGet para download.

No diretório do projeto, abra o Program.cs arquivo em seu editor ou IDE preferido. Adicione o seguinte usando diretivas:

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

Modelo de objeto

O cliente Personalizer é um objeto PersonalizerClient que se autentica no Azure usando Azure.AzureKeyCredential, que contém sua chave.

Para pedir o melhor item para mostrar ao usuário, crie um PersonalizerRankOptions e, em seguida, passe-o para o método PersonalizerClient.Rank . O método Rank retorna um PersonalizerRankResult.

Para enviar uma pontuação de recompensa para o Personalizador, passe o ID do evento e a pontuação de recompensa para o método PersonalizerClient.Reward .

Determinar a pontuação de recompensa, neste início rápido, é trivial. Em um sistema de produção, a determinação do que impacta a pontuação de recompensa e por quanto pode ser um processo complexo, que você pode decidir mudar ao longo do tempo. Esta decisão de design deve ser uma das principais decisões na sua arquitetura do Personalizador.

Exemplos de código

Esses trechos de código mostram como executar as seguintes tarefas com a biblioteca de cliente do Personalizer para .NET:

• Criar um cliente Personalizador
• API de classificação de vários slots
• API de recompensa multi-slot

Autenticar o cliente

Nesta seção, você fará duas coisas:

• Especifique sua chave e ponto de extremidade
• Criar um cliente Personalizador

Comece adicionando as seguintes linhas à sua classe Program. Certifique-se de adicionar sua chave e ponto de extremidade do seu recurso Personalizador.

Importante

Aceda ao portal do Azure. Se o recurso Personalizador criado na seção Pré-requisitos for implantado com êxito, clique no botão Ir para Recurso em Próximas etapas. Você pode encontrar sua chave e ponto de extremidade na página de chave e ponto de extremidade do recurso, em Gerenciamento de recursos.

Lembre-se de remover a chave do seu código quando terminar e nunca publicá-la publicamente. Para produção, considere usar uma maneira segura de armazenar e acessar suas credenciais. Por exemplo, o cofre de chaves do Azure.

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

Em seguida, construa os URLs de Classificação e Recompensa. Observe que a configuração useLocalInference: true como um parâmetro para PersonalizerClientOptions é necessária para habilitar a inferência local.

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

Obter opções de conteúdo representadas como ações

As ações representam as opções de conteúdo das quais você deseja que o Personalizador selecione o melhor item de conteúdo. Adicione os seguintes métodos à classe Program para representar o conjunto de ações e seus recursos.

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

Obter preferências do usuário para contexto

Adicione os seguintes métodos à classe Program para obter a entrada de um usuário da linha de comando para a hora do dia e a preferência de gosto do usuário. Estes serão usados como recursos de contexto.

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

Ambos os métodos usam o GetKey método para ler a seleção do usuário a partir da linha de 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 }
    };
}

Criar o ciclo de aprendizagem

O ciclo de aprendizagem do Personalizador é um ciclo de chamadas de Classificação e Recompensa. Neste início rápido, cada chamada de Classificação, para personalizar o conteúdo, é seguida por uma chamada de Recompensa para informar ao Personalizador como o serviço foi executado.

O código a seguir percorre um ciclo de perguntar ao usuário suas preferências através da linha de comando, enviando essas informações para o Personalizer selecionar a melhor ação para cada slot, apresentando a seleção para o cliente escolher entre a lista e, em seguida, enviando uma pontuação de recompensa para o Personalizer sinalizando o quão bem o serviço se saiu em sua seleção.

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

Execute o programa

Execute o aplicativo com o comando dotnet run do diretório do aplicativo.

dotnet run