Introdução ao SDK de inferência local para Personalizador de IA do Azure

Importante

A partir de 20 de setembro de 2023, você não pode criar novos recursos do Personalizador. O serviço Personalizador está sendo desativado em 25 de agosto de 2026. Recomendamos migrar para o software livre microsoft/learning-loop.

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 de clientes do Personalizador para .NET para:

  • Autentique o cliente de exemplo de início rápido com um recurso personalizador em 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

  • Azure assinatura – Criar uma gratuitamente
  • A versão atual do .NET Core.
  • Depois de obter sua assinatura do Azure, crie um recurso do Personalizer no portal do Azure para obter sua chave e 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 Azure, acesse a página Configuration do recurso personalizador e altere a frequência de atualização Model 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 a frequência de atualização do modelo

Alterar o tempo de espera da recompensa

No portal Azure, acesse a página Configuration do recurso personalizador e altere o tempo de espera Reward 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.

Alterar tempo de espera para a recompensa

Criar um aplicativo em C#

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

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 C# "Olá, Mundo" simples com um único arquivo de origem: 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

No 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 Visual Studio IDE, a biblioteca de clientes estará disponível como um pacote NuGet para download.

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 personalizador é um objeto PersonalizerClient que se autentica para 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:

Autenticar o cliente

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

  • Especifique sua chave e o endpoint
  • 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

Vá para 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 de API do 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, 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 com o comando dotnet run no diretório do seu aplicativo.

dotnet run

O programa de Início Rápido faz algumas perguntas para coletar as preferências do usuário, conhecidas como recursos e, em seguida, fornece a ação principal.

  • Last updated on