Comece a usar o SDK de inferência local para o Personalizador de IA do Azure

Importante

A partir de 20 de setembro de 2023, não será mais possível criar novos recursos do Personalizador. O serviço Personalizador está sendo desativado no dia 1º de outubro de 2026.

O SDK de inferência local do Personalizador (versão prévia) baixa o modelo do Personalizador localmente e, portanto, reduz significativamente a latência de chamadas de classificação eliminando 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 Personalizador.

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

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

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

Pré-requisitos

• Assinatura do Azure – Criar uma gratuitamente
• A versão atual do .NET Core.
• Depois de obter a assinatura do Azure, criar um recurso do Personalizador no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, selecione Ir para recurso.
  • Você precisará da chave e do ponto de extremidade do recurso que você criar para conectar o seu aplicativo à API do Personalizador. Cole a chave e o ponto de extremidade no código abaixo mais adiante no guia de início rápido.
  • Use o tipo de preço gratuito (F0) para experimentar o serviço e atualizar mais tarde para um nível pago para produção.

Configurando

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 é alterada a cada iteração.

Alterar o tempo de espera da recompensa

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

Criar um aplicativo em C#

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

Em uma janela de console (como cmd, PowerShell ou Bash), use o comando new para criar um novo aplicativo do console com o nome personalizer-quickstart. Esse comando cria um projeto simples em C# do tipo "Olá, Mundo" com um arquivo de origem único: Program.cs.

dotnet new console -n personalizer-quickstart

Altere o diretório para a pasta do aplicativo recém-criado. É possível criar o aplicativo com:

dotnet build

A saída de compilação não deve conter nenhum aviso ou erro.

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

Instalar a biblioteca de clientes

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

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

Dica

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

No diretório do projeto, abra o arquivo Program.cs no IDE ou no editor de sua preferência. Adicione o seguinte usando as orientações:

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

Modelo de objeto

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

Para solicitar o melhor item para mostrar ao usuário, crie um PersonalizerRankOptions e passe-o para o método PersonalizerClient.Rank. O Método de classificação retorna um PersonalizerRankResult.

Para enviar uma pontuação de recompensa ao 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 afeta a pontuação de recompensa e em que medida pode ser um processo complexo; você pode decidir alterá-lo ao longo do tempo. Essa decisão de design deve ser uma das principais decisões na arquitetura do Personalizador.

Exemplos de código

Esses snippets de código mostram como realizar as seguintes tarefas com a biblioteca de clientes do Personalizador para .NET:

• Criar um cliente do Personalizador
• API de Classificação de Vários Slots
• API de Recompensa de Vários Slots

Autenticar o cliente

Nesta seção, você executará duas etapas:

• Especificar a sua chave e o ponto de extremidade
• Criar um cliente do Personalizador

Comece adicionando as linhas a seguir à sua classe do Programa. Certifique-se de adicionar a sua chave e o ponto de extremidade do recurso do Personalizador.

Importante

Acesse o portal do Azure. Se o recurso do Personalizador que você criou na seção Pré-requisitos tiver sido implantado com êxito, clique no botão Acessar o Recurso em Próximas Etapas. Encontre a chave e o ponto de extremidade na página da chave e do ponto de extremidade do recurso, em gerenciamento de recursos.

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, considere o uso de uma maneira segura de armazenar e acessar suas credenciais. Por exemplo, o 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>";

Em seguida, construir as 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 entre as quais você deseja que o Personalizador selecione o melhor item de conteúdo. Adicione os métodos a seguir à classe Program para representar o conjunto de ações e os 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 o contexto

Adicione os seguintes métodos à classe do programa 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. Eles 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];
}

Os dois métodos usam o método GetKey para ler a seleção do usuário na 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 loop de aprendizado

O loop de aprendizado 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 o nível de desempenho do serviço.

O código a seguir executa um loop em um ciclo que inclui perguntas sobre as preferências do usuário através da linha de comando, envio dessas informações ao Personalizador para seleção da melhor ação de cada slot, apresentação da seleção ao cliente para escolha de uma opção na lista e, em seguida, envio de uma pontuação de recompensa ao Personalizador, sinalizando o nível de desempenho do serviço na 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 em seu próprio diretório com o comando run de dotnet.

dotnet run