Guia de início rápido: introdução à biblioteca de clientes do Personalizador

Imagine um cenário em que um varejista de comércio eletrônico de supermercado quer aumentar a receita mostrando produtos relevantes e personalizados a cada cliente que visita o site. Na página principal, há uma seção "Produto em Destaque" que exibe um produto de refeição pronta para possíveis clientes. No entanto, o varejista de comércio eletrônico quer determinar como mostrar o produto certo ao cliente certo, a fim de maximizar a probabilidade de compra.

Neste guia de início rápido, você aprenderá a usar o serviço Personalizador do Azure para resolver esse problema de maneira automatizada, escalonável e adaptável usando o poder do aprendizado de reforço. Você aprenderá a criar ações e seus recursos, recursos de contexto e pontuações de recompensa. Você usará a biblioteca de clientes do Personalizador para fazer chamadas às APIs de classificação e recompensa. Você também executará um ciclo de chamadas de classificação e recompensa para três usuários de exemplo.

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) | Exemplo de código .NET

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, clique em Ir para o 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.

Ao configurar o

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

No portal do Azure, no recurso do Personalizador na página Configuração, altere a Frequência de atualização de modelo para 30 segundos. Essa duração curta treinará o serviço rapidamente, permitindo que você veja como a ação superior é alterada a cada iteração.

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

Quando o loop do Personalizador é instanciado pela primeira vez, não há modelo, pois não houve nenhuma chamada à API de Recompensa com base na qual treinar. Chamadas de classificação retornarão probabilidades iguais para cada item. Seu aplicativo ainda deve classificar sempre o conteúdo usando a saída de RewardActionId.

Alterar o tempo de espera da recompensa

No portal do Azure, no recurso do Personalizador na página Configuração, altera o Tempo de espera da recompensa para 10 segundos. Essa duração curta treinará o serviço rapidamente, permitindo que você veja como a ação superior é alterada a cada iteração.

Alterar tempo de espera para a 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 Microsoft.Azure.CognitiveServices.Personalizer --version 1.0.0

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 Microsoft.Azure.CognitiveServices.Personalizer;
using Microsoft.Azure.CognitiveServices.Personalizer.Models;

Modelo de objeto

O cliente é um objeto PersonalizerClient que se autentica no Azure usando Microsoft.Rest.ServiceClientCredentials, que contém sua chave.

Para solicitar a melhor ação do Personalizador, crie um RankRequest contendo uma lista de RankableActions que o Personalizador usará para escolher ações e os recursos de contexto. O RankRequest será passado para o método client.Rank, que retornará um RankResponse.

Para enviar uma pontuação de recompensa ao Personalizador, crie um RewardRequest com a ID do evento correspondente à chamada de Classificação que retornou a melhor ação e a pontuação de recompensa. Em seguida, passe-o para o método client.Reward.

Mais adiante neste guia de início rápido, definiremos uma pontuação de recompensa de exemplo. No entanto, a recompensa é uma das considerações mais importantes ao projetar a arquitetura do Personalizador. Em um sistema de produção, pode ser difícil determinar quais fatores afetam a pontuação de recompensa e é possível alterar a pontuação de recompensa conforme as mudanças no cenário ou nos negócios.

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:

  • 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.

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use um modo seguro de armazenar e acessar suas credenciais, como o Azure Key Vault. Confira o artigo segurança de Serviços Cognitivos para obter mais informações.

private static readonly string ApiKey = "REPLACE-WITH-YOUR-PERSONALIZER-KEY";
private static readonly string ServiceEndpoint = "https://REPLACE-WITH-YOUR-PERSONALIZER-RESOURCE-NAME.cognitiveservices.azure.com";

Em seguida, adicione um método ao seu programa para criar um cliente do Personalizador.

static PersonalizerClient InitializePersonalizerClient(string url)
{
    PersonalizerClient client = new PersonalizerClient(
        new ApiKeyServiceClientCredentials(ApiKey)) { Endpoint = url };

    return client;
}

Definir ações e seus recursos

As ações representam as opções entre as quais o Personalizador pode escolher a melhor a ser usada, considerando o contexto atual. O snippet de código a seguir cria um dicionário de quatro ações e os recursos (definidos na classe ActionFeatures) que as descrevem. A função GetActions() monta uma lista de objetos RankableAction usados para chamar a API de classificação para inferência mais tarde no guia de início rápido.

Lembre-se do cenário do site de supermercado, as ações são os possíveis itens alimentares a serem exibidos na seção "Produto em Destaque" no site. Os recursos aqui são exemplos simples que podem ser relevantes nesse cenário.

Obter itens de alimentos como ações classificáveis

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 Dictionary<string, ActionFeatures> actions = new Dictionary<string, ActionFeatures>
{
    {"pasta", new ActionFeatures(
                    new BrandInfo(company: "pasta_inc"),
                    new ItemAttributes(
                        quantity: 1,
                        category: "Italian",
                        price: 12),
                    new DietaryAttributes(
                        vegan: false,
                        lowCarb: false,
                        highProtein: false,
                        vegetarian: false,
                        lowFat: true,
                        lowSodium: true))},
    {"bbq", new ActionFeatures(
                    new BrandInfo(company: "ambisco"),
                    new ItemAttributes(
                        quantity: 2,
                        category: "bbq",
                        price: 20),
                    new DietaryAttributes(
                        vegan: false,
                        lowCarb: true,
                        highProtein: true,
                        vegetarian: false,
                        lowFat: false,
                        lowSodium: false))},
    {"bao", new ActionFeatures(
                    new BrandInfo(company: "bao_and_co"),
                    new ItemAttributes(
                        quantity: 4,
                        category: "Chinese",
                        price: 8),
                    new DietaryAttributes(
                        vegan: false,
                        lowCarb: true,
                        highProtein: true,
                        vegetarian: false,
                        lowFat: true,
                        lowSodium: false))},
    {"hummus", new ActionFeatures(
                    new BrandInfo(company: "garbanzo_inc"),
                    new ItemAttributes(
                        quantity: 1,
                        category: "Breakfast",
                        price: 5),
                    new DietaryAttributes(
                        vegan: true,
                        lowCarb: false,
                        highProtein: true,
                        vegetarian: true,
                        lowFat: false,
                        lowSodium: false))},
    {"veg_platter", new ActionFeatures(
                    new BrandInfo(company: "farm_fresh"),
                    new ItemAttributes(
                        quantity: 1,
                        category: "produce",
                        price: 7),
                    new DietaryAttributes(
                        vegan: true,
                        lowCarb: true,
                        highProtein: false,
                        vegetarian: true,
                        lowFat: true,
                        lowSodium: true ))},
};

static IList<RankableAction> GetActions()
{
    IList<RankableAction> rankableActions = new List<RankableAction>();
    foreach (var action in actions)
    {
        rankableActions.Add(new RankableAction
        {
            Id = action.Key,
            Features = new List<object>() { action.Value }
        });
    }
    
    return rankableActions;
}

public class BrandInfo
{
    public string Company { get; set; }
    public BrandInfo(string company)
    {
        Company = company;
    }
}

public class ItemAttributes
{
    public int Quantity { get; set; }
    public string Category { get; set; }
    public double Price { get; set; }
    public ItemAttributes(int quantity, string category, double price)
    {
        Quantity = quantity;
        Category = category;
        Price = price;
    }
}

public class DietaryAttributes
{
    public bool Vegan { get; set; }
    public bool LowCarb { get; set; }
    public bool HighProtein { get; set; }
    public bool Vegetarian { get; set; }
    public bool LowFat { get; set; }
    public bool LowSodium { get; set; }
    public DietaryAttributes(bool vegan, bool lowCarb, bool highProtein, bool vegetarian, bool lowFat, bool lowSodium)
    {
        Vegan = vegan;
        LowCarb = lowCarb;
        HighProtein = highProtein;
        Vegetarian = vegetarian;
        LowFat = lowFat;
        LowSodium = lowSodium;

    }
}

public class ActionFeatures
{
    public BrandInfo BrandInfo { get; set; }
    public ItemAttributes ItemAttributes { get; set; }
    public DietaryAttributes DietaryAttributes { get; set; }
    public ActionFeatures(BrandInfo brandInfo, ItemAttributes itemAttributes, DietaryAttributes dietaryAttributes)
    {
        BrandInfo = brandInfo;
        ItemAttributes = itemAttributes;
        DietaryAttributes = dietaryAttributes;
    }
}

Definir usuários e seus recursos de contexto

O contexto pode representar o estado atual de seu aplicativo, sistema, ambiente ou usuário. O código a seguir cria uma lista com as preferências do usuário e a função GetContext() seleciona um usuário aleatório, uma hora aleatória do dia, um local aleatório e um tipo de aplicativo aleatório e monta os recursos em um objeto Context, que será usado posteriormente ao chamar a API de Classificação. No cenário do site de supermercado, as informações do usuário consistem em preferências alimentares, uma média histórica do preço do pedido. Vamos supor que os usuários estejam sempre em movimento e incluam um local, uma hora do dia e um tipo de aplicativo, escolhido aleatoriamente, para simular a alteração de contextos sempre GetContext() que é chamado.

public static Context GetContext()
{
    return new Context(
            user: GetRandomUser(),
            timeOfDay: GetRandomTimeOfDay(),
            location: GetRandomLocation(),
            appType: GetRandomAppType());
}

static string[] timesOfDay = new string[] { "morning", "afternoon", "evening" };

static string[] locations = new string[] { "west", "east", "midwest" };

static string[] appTypes = new string[] { "edge", "safari", "edge_mobile", "mobile_app" };

static IList<UserProfile> users = new List<UserProfile>
{
    new UserProfile(
        name: "Bill",
        dietaryPreferences: new Dictionary<string, bool> { { "low_carb", true } },
        avgOrderPrice: "0-20"),
    new UserProfile(
        name: "Satya",
        dietaryPreferences: new Dictionary<string, bool> { { "low_sodium", true} },
        avgOrderPrice: "201+"),
    new UserProfile(
        name: "Amy",
        dietaryPreferences: new Dictionary<string, bool> { { "vegan", true }, { "vegetarian", true } },
        avgOrderPrice: "21-50")
};

static string GetRandomTimeOfDay()
{
    var random = new Random();
    var timeOfDayIndex = random.Next(timesOfDay.Length);
    Console.WriteLine($"TimeOfDay: {timesOfDay[timeOfDayIndex]}");
    return timesOfDay[timeOfDayIndex];
}

static string GetRandomLocation()
{
    var random = new Random();
    var locationIndex = random.Next(locations.Length);
    Console.WriteLine($"Location: {locations[locationIndex]}");
    return locations[locationIndex];
}

static string GetRandomAppType()
{
    var random = new Random();
    var appIndex = random.Next(appTypes.Length);
    Console.WriteLine($"AppType: {appTypes[appIndex]}");
    return appTypes[appIndex];
}

static UserProfile GetRandomUser()
{
    var random = new Random();
    var userIndex = random.Next(users.Count);
    Console.WriteLine($"\nUser: {users[userIndex].Name}");
    return users[userIndex];
}

public class UserProfile
{
    // Mark name as non serializable so that it is not part of the context features
    [NonSerialized()]
    public string Name;
    public Dictionary<string, bool> DietaryPreferences { get; set; }
    public string AvgOrderPrice { get; set; }

    public UserProfile(string name, Dictionary<string, bool> dietaryPreferences, string avgOrderPrice)
    {
        Name = name;
        DietaryPreferences = dietaryPreferences;
        AvgOrderPrice = avgOrderPrice;
    }
}

public class Context
{
    public UserProfile User { get; set; }
    public string TimeOfDay { get; set; }
    public string Location { get; set; }
    public string AppType { get; set; }

    public Context(UserProfile user, string timeOfDay, string location, string appType)
    {
        User = user;
        TimeOfDay = timeOfDay;
        Location = location;
        AppType = appType;
    }
}

Os recursos de contexto neste guia de início rápido são simplistas, no entanto, em um sistema de produção real, o projeto dos recursos e a avaliação de sua eficácia pode não ser tão simples. Confira a documentação mencionada acima para obter diretrizes.

Definir uma pontuação de recompensa com base no comportamento do usuário

A pontuação de recompensa pode ser considerada uma indicação de quão "boa" é a ação personalizada. Em um sistema de produção real, a pontuação de recompensa deve ser projetada para se alinhar aos objetivos de negócios e KPIs. Por exemplo, o código do aplicativo pode ser instrumentado para detectar um comportamento de usuário desejado (por exemplo, uma compra) que se alinhe ao objetivo de negócios (por exemplo, aumento da receita).

No cenário do site de supermercado, temos três usuários: Bill, Satya e Amy, cada um com as próprias preferências. Se um usuário comprar o produto escolhido pelo Personalizador, a pontuação de recompensa 1,0 será enviada à API de recompensa. Caso contrário, a recompensa padrão 0,0 será usada. Em um sistema de produção real, pode ser necessário fazer experimentações para determinar como projetar a recompensa.

No código abaixo, as preferências e as respostas dos usuários às ações são embutidas em código como uma série de instruções condicionais, e o texto explicativo é incluído no código para fins demonstrativos. Em um cenário real, o Personalizador aprenderá as preferências do usuário com base nos dados enviados em chamadas à API de classificação e recompensa. Você não as definirá explicitamente como no código de exemplo.

As preferências embutidas em código e a recompensa podem ser descritas de maneira sucinta como:

  • Bill vai comprar qualquer produto abaixo de US$ 10, desde que ele não esteja no centro-oeste.
  • Quando Bill estiver no centro-oeste, ele vai comprar qualquer produto que tenha baixo teor de carboidratos.
  • Satya vai comprar qualquer produto que tenha baixo teor de sódio.
  • Amy vai comprar qualquer produto que seja vegano ou vegetariano.
public static float GetRewardScore(Context context, string actionId)
{
    float rewardScore = 0.0f;
    string userName = context.User.Name;
    ActionFeatures actionFeatures = actions[actionId];
    if (userName.Equals("Bill"))
    {
        if (actionFeatures.ItemAttributes.Price < 10 && !context.Location.Equals("midwest"))
        {
            rewardScore = 1.0f;
            Console.WriteLine($"\nBill likes to be economical when he's not in the midwest visiting his friend Warren. He bought {actionId} because it was below a price of $10.");
        }
        else if (actionFeatures.DietaryAttributes.LowCarb && context.Location.Equals("midwest"))
        {
            rewardScore = 1.0f;
            Console.WriteLine($"\nBill is visiting his friend Warren in the midwest. There he's willing to spend more on food as long as it's low carb, so Bill bought {actionId}.");
        }
        else if (actionFeatures.ItemAttributes.Price >= 10 && !context.Location.Equals("midwest"))
        {
            rewardScore = 1.0f;
            Console.WriteLine($"\nBill didn't buy {actionId} because the price was too high when not visting his friend Warren in the midwest.");
        }
        else if (actionFeatures.DietaryAttributes.LowCarb && context.Location.Equals("midwest"))
        {
            rewardScore = 1.0f;
            Console.WriteLine($"\nBill didn't buy {actionId} because it's not low-carb, and he's in the midwest visitng his friend Warren.");
        }
    }
    else if (userName.Equals("Satya"))
    {
        if (actionFeatures.DietaryAttributes.LowSodium)
        {
            rewardScore = 1.0f;
            Console.WriteLine($"\nSatya is health conscious, so he bought {actionId} since it's low in sodium.");
        }
        else
        {
            Console.WriteLine($"\nSatya did not buy {actionId} because it's not low sodium.");
        }
    }
    else if (userName.Equals("Amy"))
    {
        if (actionFeatures.DietaryAttributes.Vegan || actionFeatures.DietaryAttributes.Vegetarian)
        {
            rewardScore = 1.0f;
            Console.WriteLine($"\nAmy likes to eat plant-based foods, so she bought {actionId} because it's vegan or vegetarian friendly.");
        }
        else
        {
            Console.WriteLine($"\nAmy did not buy {actionId} because it's not vegan or vegetarian.");
        }
    }
    return rewardScore;
}

Executar chamadas de classificação e recompensa para cada usuário

Um ciclo de eventos do Personalizador consiste em chamadas à API de classificação e recompensa. No cenário do site de supermercado, cada chamada de classificação é feita para determinar qual produto deve ser exibido na seção "Produto em Destaque". Depois, a chamada de recompensa informa ao Personalizador se o produto em destaque foi comprado ou não pelo usuário.

Solicitar a melhor ação

Em uma chamada de classificação, você precisa fornecer pelo menos dois argumentos: uma lista de RankableActions (ações e seus recursos) e uma lista de recursos (contexto). A resposta incluirá a RewardActionId, que é a ID da ação que o Personalizador determinou como a melhor para o contexto fornecido. A resposta também inclui o EventId, que é necessário na API de recompensa para que o Personalizador saiba como vincular os dados das chamadas de recompensa e classificação correspondentes. Para obter mais informações, confira os Classificar documentos da API.

Enviar uma recompensa

Em uma chamada de recompensa, você precisa fornecer dois argumentos: o EventId, que vincula as chamadas de Recompensa e Classificação ao mesmo evento exclusivo e a value (pontuação de recompensa). Lembre-se de que a pontuação de recompensa é um sinal que informa ao Personalizador se a decisão tomada na chamada de classificação foi boa ou não. Uma pontuação de recompensa normalmente é um número entre 0,0 e 1,0. Vale a pena salientar que pode não ser fácil determinar como projetar a recompensa.

Executar um ciclo classificação e recompensa

O código a seguir percorre um único ciclo de chamadas de Classificação e Recompensa para um usuário selecionado aleatoriamente e depois imprime informações relevantes no console em cada etapa.

static void Main(string[] args)
{
    int iteration = 1;
    bool runLoop = true;

    // Get the actions list to choose from personalizer with their features.
    IList<RankableAction> actions = GetActions();

    // Initialize Personalizer client.
    PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);

    do
    {
        Console.WriteLine("\nIteration: " + iteration++);

        // <rank>
        // Get context information.
        Context context = GetContext();

        // Create current context from user specified data.
        IList<object> currentContext = new List<object>() {
            context
        };

        // Generate an ID to associate with the request.
        string eventId = Guid.NewGuid().ToString();

        // Rank the actions
        var request = new RankRequest(actions: actions, contextFeatures: currentContext, eventId: eventId);
        RankResponse response = client.Rank(request);
        // </rank>

        Console.WriteLine($"\nPersonalizer service thinks {context.User.Name} would like to have: {response.RewardActionId}.");

        // <reward>
        float reward = GetRewardScore(context, response.RewardActionId);

        // Send the reward for the action based on user response.
        client.Reward(response.EventId, new RewardRequest(reward));
        // </reward>

        Console.WriteLine("\nPress q to break, any other key to continue:");
        runLoop = !(GetKey() == "Q");

    } while (runLoop);
}

private static string GetKey()
{
    return Console.ReadKey().Key.ToString().Last().ToString().ToUpper();
}

Execute o programa

Execute o aplicativo em seu próprio diretório com o comando run de dotnet.

dotnet run

Gerar exemplo de eventos para análise (opcional)

Você pode gerar facilmente cinco mil eventos deste cenário de demonstração de início rápido, o que é suficiente para obter experiência com o uso do modo Aprendiz, modo Online, execução de avaliações offline e criação de avaliações de recursos. Basta substituir o método Main() do código acima na seção Run a Rank and Reward cycle por:


   static void Main(string[] args)
{
    int iteration = 1;
    int runLoop = 0;

    // Get the actions list to choose from personalizer with their features.
    IList<RankableAction> actions = GetActions();

    // Initialize Personalizer client.
    PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);

    do
    {
        Console.WriteLine("\nIteration: " + iteration++);

        // <rank>
        // Get context information.
        Context context = GetContext();

        // Create current context from user specified data.
        IList<object> currentContext = new List<object>() {
            context
        };

        // Generate an ID to associate with the request.
        string eventId = Guid.NewGuid().ToString();

        // Rank the actions
        var request = new RankRequest(actions: actions, contextFeatures: currentContext, eventId: eventId);
        RankResponse response = client.Rank(request);
        // </rank>

        Console.WriteLine($"\nPersonalizer service thinks {context.User.Name} would like to have: {response.RewardActionId}.");

        // <reward>
        float reward = GetRewardScore(context, response.RewardActionId);

        // Send the reward for the action based on user response.
        client.Reward(response.EventId, new RewardRequest(reward));
        // </reward>

        runLoop = runLoop + 1;

    } while (runLoop < 1000);
}

em seguida, execute o programa.

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.

O código-fonte desse início rápido está disponível.

Você precisará instalar a biblioteca cliente do Personalizador para Node.js 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 (npm) | Exemplos de código de Início Rápido

Pré-requisitos

  • Assinatura do Azure – Criar uma gratuitamente
  • Instale o Node.js e o NPM (verificado com o Node.js v14.16.0 e o npm 6.14.11).
  • 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.

Ao configurar o

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

No portal do Azure, no recurso do Personalizador na página Configuração, altere a Frequência de atualização de modelo para 30 segundos. Essa duração curta treinará o serviço rapidamente, permitindo que você veja como a ação superior é alterada a cada iteração.

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

Quando o loop do Personalizador é instanciado pela primeira vez, não há modelo, pois não houve nenhuma chamada à API de Recompensa com base na qual treinar. Chamadas de classificação retornarão probabilidades iguais para cada item. Seu aplicativo ainda deve classificar sempre o conteúdo usando a saída de RewardActionId.

Alterar o tempo de espera da recompensa

No portal do Azure, no recurso do Personalizador na página Configuração, altera o Tempo de espera da recompensa para 10 segundos. Essa duração curta treinará o serviço rapidamente, permitindo que você veja como a ação superior é alterada a cada iteração.

Alterar tempo de espera para a recompensa

Criar um novo aplicativo do Node.js

Em uma janela de console (como cmd, PowerShell ou Bash), crie um novo diretório para seu aplicativo e navegue até ele.

mkdir myapp && cd myapp

Execute o comando npm init -y para criar um arquivo package.json.

npm init -y

Crie um aplicativo Node.js no seu editor ou IDE preferencial chamado sample.js e crie variáveis para o ponto de extremidade e a chave de assinatura do recurso.

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.

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use uma maneira segura de armazenar e acessar suas credenciais, como o Azure Key Vault. Para saber mais sobre segurança, confira o artigo segurança dos Serviços Cognitivos.

const uuidv1 = require('uuid/v1');
const Personalizer = require('@azure/cognitiveservices-personalizer');
const CognitiveServicesCredentials = require('@azure/ms-rest-azure-js').CognitiveServicesCredentials;
const readline = require('readline-sync');

// The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF"
const serviceKey = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>";

// The endpoint specific to your personalization service instance; 
// e.g. https://<your-resource-name>.cognitiveservices.azure.com
const baseUri = "https://<REPLACE-WITH-YOUR-PERSONALIZER-ENDPOINT>.cognitiveservices.azure.com";

Instalar a biblioteca do Node.js para o Personalizador

Instale a biblioteca de clientes do Personalizador para Node.js com o seguinte comando:

npm install @azure/cognitiveservices-personalizer --save

Instale os pacotes npm restantes para este início rápido:

npm install @azure/ms-rest-azure-js @azure/ms-rest-js readline-sync uuid --save

Modelo de objeto

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

Para solicitar o melhor item do conteúdo, crie uma RankRequest e, em seguida, transmita-a para o método client.Rank. O método Rank retornará uma RankResponse.

Para enviar uma recompensa ao Personalizador, crie uma RewardRequest e, em seguida, transmita-a para método Reward na classe Events.

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. A pontuação de recompensa deve ser uma das principais decisões de design 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 Node.js:

Autenticar o cliente

Crie uma instância do PersonalizerClient com o serviceKey e o baseUri que você criou anteriormente.

const credentials = new CognitiveServicesCredentials(serviceKey);

// Initialize Personalization client.
const personalizerClient = new Personalizer.PersonalizerClient(credentials, baseUri);

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.

function getContextFeaturesList() {
  const timeOfDayFeatures = ['morning', 'afternoon', 'evening', 'night'];
  const tasteFeatures = ['salty', 'sweet'];

  let answer = readline.question("\nWhat time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night\n");
  let selection = parseInt(answer);
  const timeOfDay = selection >= 1 && selection <= 4 ? timeOfDayFeatures[selection - 1] : timeOfDayFeatures[0];

  answer = readline.question("\nWhat type of food would you prefer (enter number)? 1. salty 2. sweet\n");
  selection = parseInt(answer);
  const taste = selection >= 1 && selection <= 2 ? tasteFeatures[selection - 1] : tasteFeatures[0];

  console.log("Selected features:\n");
  console.log("Time of day: " + timeOfDay + "\n");
  console.log("Taste: " + taste + "\n");

  return [
    {
      "time": timeOfDay
    },
    {
      "taste": taste
    }
  ];
}
function getActionsList() {
  return [
    {
      "id": "pasta",
      "features": [
        {
          "taste": "salty",
          "spiceLevel": "medium"
        },
        {
          "nutritionLevel": 5,
          "cuisine": "italian"
        }
      ]
    },
    {
      "id": "ice cream",
      "features": [
        {
          "taste": "sweet",
          "spiceLevel": "none"
        },
        {
          "nutritionalLevel": 2
        }
      ]
    },
    {
      "id": "juice",
      "features": [
        {
          "taste": "sweet",
          "spiceLevel": "none"
        },
        {
          "nutritionLevel": 5
        },
        {
          "drink": true
        }
      ]
    },
    {
      "id": "salad",
      "features": [
        {
          "taste": "salty",
          "spiceLevel": "low"
        },
        {
          "nutritionLevel": 8
        }
      ]
    }
  ];
}

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 na linha de comando, envio dessas informações ao Personalizador para seleção da melhor ação, apresentação da seleção ao cliente para escolha de uma opção na lista e, em seguida, envio de uma recompensa ao Personalizador, sinalizando o nível de desempenho do serviço na seleção.

let runLoop = true;

do {

  let rankRequest = {}

  // Generate an ID to associate with the request.
  rankRequest.eventId = uuidv1();

  // Get context information from the user.
  rankRequest.contextFeatures = getContextFeaturesList();

  // Get the actions list to choose from personalization with their features.
  rankRequest.actions = getActionsList();

  // Exclude an action for personalization ranking. This action will be held at its current position.
  rankRequest.excludedActions = getExcludedActionsList();

  rankRequest.deferActivation = false;

  // Rank the actions
  const rankResponse = await personalizerClient.rank(rankRequest);

  console.log("\nPersonalization service thinks you would like to have:\n")
  console.log(rankResponse.rewardActionId);

  // Display top choice to user, user agrees or disagrees with top choice
  const reward = getReward();

  console.log("\nPersonalization service ranked the actions with the probabilities as below:\n");
  for (let i = 0; i < rankResponse.ranking.length; i++) {
    console.log(JSON.stringify(rankResponse.ranking[i]) + "\n");
  }

  // Send the reward for the action based on user response.

  const rewardRequest = {
    value: reward
  }

  await personalizerClient.events.reward(rankRequest.eventId, rewardRequest);

  runLoop = continueLoop();

} while (runLoop);

Examine mais detalhadamente as chamadas de classificação e de recompensa nas seções a seguir.

Adicione os seguintes métodos, que obtêm as opções de conteúdo, antes de executar o arquivo de código:

  • getActionsList
  • getContextFeaturesList

Solicitar a melhor ação

Para fazer uma solicitação de classificação, você precisará fornecer: uma lista de 'RankActions' ( actions ), uma lista de recursos de contexto ( context ), uma lista opcional de ações ( excludeActions ) a serem removidas da consideração do Personalizador e um evento exclusivo ID para receber a resposta.

Este início rápido tem recursos de contexto simples da hora do dia e da preferência de alimentos do usuário. Em sistemas de produção, determinar e avaliarações e recursos pode ser uma questão não trivial.

let rankRequest = {}

// Generate an ID to associate with the request.
rankRequest.eventId = uuidv1();

// Get context information from the user.
rankRequest.contextFeatures = getContextFeaturesList();

// Get the actions list to choose from personalization with their features.
rankRequest.actions = getActionsList();

// Exclude an action for personalization ranking. This action will be held at its current position.
rankRequest.excludedActions = getExcludedActionsList();

rankRequest.deferActivation = false;

// Rank the actions
const rankResponse = await personalizerClient.rank(rankRequest);

Enviar uma recompensa

Para obter a pontuação de recompensa a ser enviada na solicitação de Recompensa, o programa obtém a seleção do usuário na linha de comando, atribui um valor numérico a cada seleção e, em seguida, envia uma ID exclusiva do evento e a pontuação de recompensa como o valor numérico para a API de Recompensa.

Este início rápido atribui um número simples como uma pontuação de recompensa, um zero ou um 1. Em sistemas de produção, determinar quando e o que enviar para a chamada de Recompensa pode ser uma questão não trivial, dependendo das suas necessidades específicas.

const rewardRequest = {
  value: reward
}

await personalizerClient.events.reward(rankRequest.eventId, rewardRequest);

Execute o programa

Execute o aplicativo com o Node.js no diretório do aplicativo.

node sample.js

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.

Você precisará instalar a biblioteca de clientes do Personalizador para Python para:

  • Autenticar o cliente de exemplo do guia de início rápido em um recurso Personalizador no Azure.
  • Enviar recursos de contexto e ação para a API de classificação, que retornará a melhor ação do Personalizador.
  • Enviar uma pontuação de recompensa à API de classificação e treinar o modelo do Personalizador.

Documentação de referência | Código-fonte da biblioteca | Pacote (pypi) | Exemplos de código de Início Rápido

Pré-requisitos

  • Assinatura do Azure – Criar uma gratuitamente
  • Python 3.x
  • Depois que sua assinatura do Azure estiver configurada, crie um recurso do Personalizador no portal do Azure para obter a chave e o ponto de extremidade. Após a implantação, clique em Ir para o recurso.
    • Você precisará da chave e do ponto de extremidade do recurso criado para conectar o aplicativo à API do Personalizador, que você colará no código do guia de início rápido abaixo.
    • Você pode usar o tipo de preço gratuito (F0) para experimentar o serviço e atualizar para um nível pago de produção mais tarde.

Ao configurar o

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

No portal do Azure, no recurso do Personalizador na página Configuração, altere a Frequência de atualização de modelo para 30 segundos. Essa duração curta treinará o serviço rapidamente, permitindo que você veja como a ação superior é alterada a cada iteração.

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

Quando o loop do Personalizador é instanciado pela primeira vez, não há modelo, pois não houve nenhuma chamada à API de Recompensa com base na qual treinar. Chamadas de classificação retornarão probabilidades iguais para cada item. Seu aplicativo ainda deve classificar sempre o conteúdo usando a saída de RewardActionId.

Alterar o tempo de espera da recompensa

No portal do Azure, no recurso do Personalizador na página Configuração, altera o Tempo de espera da recompensa para 10 segundos. Essa duração curta treinará o serviço rapidamente, permitindo que você veja como a ação superior é alterada a cada iteração.

Alterar tempo de espera para a recompensa

Instalar a biblioteca de clientes

Depois de instalar o Python, você poderá instalar a biblioteca de clientes do Personalizador com o pip:

pip install azure-cognitiveservices-personalizer

Criar um novo aplicativo Python

Crie um arquivo de aplicativo Python chamado "personalizer_quickstart.py". Esse aplicativo processará a lógica do cenário de exemplo e chamará as APIs do Personalizador.

No arquivo, crie variáveis para a chave de assinatura e o ponto de extremidade do recurso.

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.

Importante

Lembre-se de remover a chave do seu código quando terminar e nunca poste-a publicamente. Para produção, use um modo seguro para armazenar e acessar as credenciais, como o Azure Key Vault. Para obter mais informações, confira segurança dos Serviços Cognitivos.

from azure.cognitiveservices.personalizer import PersonalizerClient
from azure.cognitiveservices.personalizer.models import RankableAction, RewardRequest, RankRequest
from msrest.authentication import CognitiveServicesCredentials

import datetime, json, os, time, uuid, random

key = "<paste-your-personalizer-key-here>"
endpoint = "<paste-your-personalizer-endpoint-here>"

Modelo de objeto

O cliente é um objeto PersonalizerClient que se autentica no Azure usando Microsoft.Rest.ServiceClientCredentials, que contém sua chave.

Para solicitar a melhor ação do Personalizador, crie um RankRequest contendo o conjunto de RankableActions que o Personalizador usará para escolher ações e um conjunto de recursos de contexto. O RankRequest será passado para o método client.Rank, que retornará um RankResponse contendo uma ID de evento.

Para enviar uma pontuação de recompensa ao Personalizador, use o método Reward na classe EventOperations e inclua a ID do evento correspondente à chamada de Rank que retornou a melhor ação e a pontuação de recompensa.

Mais adiante neste guia de início rápido, definiremos uma pontuação de recompensa de exemplo. No entanto, a recompensa é uma das considerações mais importantes ao projetar a arquitetura do Personalizador. Em um sistema de produção, pode ser difícil determinar quais fatores afetam a pontuação de recompensa e é possível alterar a pontuação de recompensa conforme as mudanças no cenário ou nos negócios.

Exemplos de código

Esses snippets de código demonstram como usar a biblioteca de clientes do Personalizador para Python para:

Autenticar o cliente

Crie uma instância de PersonalizerClient com o key e o endpoint que você obteve do recurso personalizador.

# Instantiate a Personalizer client
client = PersonalizerClient(endpoint, CognitiveServicesCredentials(key))

Definir ações e seus recursos

As ações representam as opções entre as quais o Personalizador pode escolher a melhor a ser usada, considerando o contexto atual. O snippet de código a seguir cria um dicionário de quatro ações e os recursos que as descrevem. A função get_actions() monta uma lista de objetos RankableAction usados para chamar a API de classificação para inferência mais tarde no guia de início rápido.

Lembre-se do cenário do site de supermercado, as ações são os possíveis itens alimentares a serem exibidos na seção "Produto em Destaque" no site. Os recursos aqui são exemplos simples que podem ser relevantes nesse cenário.

actions_and_features = {
    'pasta': {
        'brand_info': {
            'company':'pasta_inc'
        }, 
        'attributes': {
            'qty':1, 'cuisine':'italian',
            'price':12
        },
        'dietary_attributes': {
            'vegan': False,
            'low_carb': False,
            'high_protein': False,
            'vegetarian': False,
            'low_fat': True,
            'low_sodium': True
        }
    },
    'bbq': {
        'brand_info' : {
            'company': 'ambisco'
        },
        'attributes': {
            'qty': 2,
            'category': 'bbq',
            'price': 20
        }, 
        'dietary_attributes': {
            'vegan': False,
            'low_carb': True,
            'high_protein': True,
            'vegetarian': False,
            'low_fat': False,
            'low_sodium': False
        }
    },
    'bao': {
        'brand_info': {
            'company': 'bao_and_co'
        },
        'attributes': {
            'qty': 4,
            'category': 'chinese',
            'price': 8
        }, 
        'dietary_attributes': {
            'vegan': False,
            'low_carb': True,
            'high_protein': True,
            'vegetarian': False,
            'low_fat': True,
            'low_sodium': False
        }
    },
    'hummus': {
        'brand_info' : { 
            'company': 'garbanzo_inc'
        },
        'attributes' : {
            'qty': 1,
            'category': 'breakfast',
            'price': 5
        }, 
        'dietary_attributes': {
            'vegan': True, 
            'low_carb': False,
            'high_protein': True,
            'vegetarian': True,
            'low_fat': False, 
            'low_sodium': False
        }
    },
    'veg_platter': {
        'brand_info': {
            'company': 'farm_fresh'
        }, 
        'attributes': {
            'qty': 1,
            'category': 'produce', 
            'price': 7
        },
        'dietary_attributes': {
            'vegan': True,
            'low_carb': True,
            'high_protein': False,
            'vegetarian': True,
            'low_fat': True,
            'low_sodium': True
        }
    }
}

def get_actions():
    res = []
    for action_id, feat in actions_and_features.items():
        action = RankableAction(id=action_id, features=[feat])
        res.append(action)
    return res

Definir usuários e seus recursos de contexto

O contexto pode representar o estado atual de seu aplicativo, sistema, ambiente ou usuário. O código a seguir cria um dicionário com preferências de usuário e a função get_context() reúne os recursos em uma lista para um usuário específico, que será usada mais tarde ao chamar a API de classificação. No cenário do site de supermercado, o contexto consiste em preferências alimentares, uma média histórica do preço do pedido. Vamos supor que os usuários estejam sempre em movimento e incluam um local, uma hora do dia e um tipo de aplicativo, escolhido aleatoriamente, para simular a alteração de contextos sempre get_context() que é chamado. Por fim, get_random_users() cria um conjunto aleatório de cinco nomes de usuário dos perfis de usuário, que serão usados para simular chamadas de classificação e recompensa mais tarde.

user_profiles = {
    'Bill': {
        'dietary_preferences': 'low_carb', 
        'avg_order_price': '0-20',
        'browser_type': 'edge'
    },
    'Satya': {
        'dietary_preferences': 'low_sodium',
        'avg_order_price': '201+',
        'browser_type': 'safari'
    },
    'Amy': {
        'dietary_preferences': {
            'vegan', 'vegetarian'
        },
        'avg_order_price': '21-50',
        'browser_type': 'edge'},
    }

def get_context(user):
    location_context = {'location': random.choice(['west', 'east', 'midwest'])}
    time_of_day = {'time_of_day': random.choice(['morning', 'afternoon', 'evening'])}
    app_type = {'application_type': random.choice(['edge', 'safari', 'edge_mobile', 'mobile_app'])}
    res = [user_profiles[user], location_context, time_of_day, app_type]
    return res

def get_random_users(k = 5):
    return random.choices(list(user_profiles.keys()), k=k)

Os recursos de contexto neste guia de início rápido são simplistas, no entanto, em um sistema de produção real, o projeto dos recursos e a avaliação de sua eficácia pode não ser tão simples. Confira a documentação mencionada acima para obter diretrizes.

Definir uma pontuação de recompensa com base no comportamento do usuário

A pontuação de recompensa pode ser considerada uma indicação de quão "boa" é a ação personalizada. Em um sistema de produção real, a pontuação de recompensa deve ser projetada para se alinhar aos objetivos de negócios e KPIs. Por exemplo, o código do aplicativo pode ser instrumentado para detectar um comportamento de usuário desejado (por exemplo, uma compra) que se alinhe ao objetivo de negócios (por exemplo, aumento da receita).

No cenário do site de supermercado, temos três usuários: Bill, Satya e Amy, cada um com as próprias preferências. Se um usuário comprar o produto escolhido pelo Personalizador, a pontuação de recompensa 1,0 será enviada à API de recompensa. Caso contrário, a recompensa padrão 0,0 será usada. Em um sistema de produção real, pode ser necessário fazer experimentações para determinar como projetar a recompensa.

No código abaixo, as preferências e as respostas dos usuários às ações são embutidas em código como uma série de instruções condicionais, e o texto explicativo é incluído no código para fins demonstrativos. Em um cenário real, o Personalizador aprenderá as preferências do usuário com base nos dados enviados em chamadas à API de classificação e recompensa. Você não as definirá explicitamente como no código de exemplo.

As preferências embutidas em código e a recompensa podem ser descritas de maneira sucinta como:

  • Bill vai comprar qualquer produto abaixo de US$ 10, desde que ele não esteja no centro-oeste.
  • Quando Bill estiver no centro-oeste, ele vai comprar qualquer produto que tenha baixo teor de carboidratos.
  • Satya vai comprar qualquer produto que tenha baixo teor de sódio.
  • Amy vai comprar qualquer produto que seja vegano ou vegetariano.
def get_reward_score(user, actionid, context):
    reward_score = 0.0
    action = actions_and_features[actionid]
    
    if user == 'Bill':
        if action['attributes']['price'] < 10 and (context[1]['location'] !=  "midwest"):
            reward_score = 1.0
            print("Bill likes to be economical when he's not in the midwest visiting his friend Warren. He bought", actionid, "because it was below a price of $10.")
        elif (action['dietary_attributes']['low_carb'] == True) and (context[1]['location'] ==  "midwest"):
            reward_score = 1.0
            print("Bill is visiting his friend Warren in the midwest. There he's willing to spend more on food as long as it's low carb, so Bill bought" + actionid + ".")
            
        elif (action['attributes']['price'] >= 10) and (context[1]['location'] != "midwest"):
            print("Bill didn't buy", actionid, "because the price was too high when not visting his friend Warren in the midwest.")
            
        elif (action['dietary_attributes']['low_carb'] == False) and (context[1]['location'] ==  "midwest"):
            print("Bill didn't buy", actionid, "because it's not low-carb, and he's in the midwest visitng his friend Warren.")
             
    elif user == 'Satya':
        if action['dietary_attributes']['low_sodium'] == True:
            reward_score = 1.0
            print("Satya is health conscious, so he bought", actionid,"since it's low in sodium.")
        else:
            print("Satya did not buy", actionid, "because it's not low sodium.")   
            
    elif user == 'Amy':
        if (action['dietary_attributes']['vegan'] == True) or (action['dietary_attributes']['vegetarian'] == True):
            reward_score = 1.0
            print("Amy likes to eat plant-based foods, so she bought", actionid, "because it's vegan or vegetarian friendly.")       
        else:
            print("Amy did not buy", actionid, "because it's not vegan or vegetarian.")
                
    return reward_score

Executar chamadas de classificação e recompensa para cada usuário

Um ciclo de eventos do Personalizador consiste em chamadas à API de classificação e recompensa. No cenário do site de supermercado, cada chamada de classificação é feita para determinar qual produto deve ser exibido na seção "Produto em Destaque". Depois, a chamada de recompensa informa ao Personalizador se o produto em destaque foi comprado ou não pelo usuário.

Solicitar a melhor ação

Em uma chamada de classificação, você precisa fornecer pelo menos dois argumentos: uma lista de RankableActions (ações e seus recursos) e uma lista de recursos (contexto). A resposta incluirá a reward_action_id, que é a ID da ação que o Personalizador determinou como a melhor para o contexto fornecido. A resposta também inclui o event_id, que é necessário na API de recompensa para que o Personalizador saiba como vincular os dados das chamadas de recompensa e classificação. Para obter mais informações, confira os Classificar documentos da API.

Enviar uma recompensa

Em uma chamada de recompensa, você precisa fornecer dois argumentos: o event_id, que vincula as chamadas de recompensa e classificação ao mesmo evento exclusivo e a value (pontuação de recompensa). Lembre-se de que a pontuação de recompensa é um sinal que informa ao Personalizador se a decisão tomada na chamada de classificação foi boa ou não. Uma pontuação de recompensa normalmente é um número entre 0,0 e 1,0. Vale a pena salientar que pode não ser fácil determinar como projetar a recompensa.

Executar um ciclo classificação e recompensa

O código a seguir percorre cinco ciclos de chamadas de classificação e recompensa para um conjunto selecionado aleatoriamente de usuários de exemplo e depois imprime informações relevantes no console em cada etapa.

def run_personalizer_cycle():
    actions = get_actions()
    user_list = get_random_users()
    for user in user_list:
        print("------------")
        print("User:", user, "\n")
        context = get_context(user)
        print("Context:", context, "\n")
        
        rank_request = RankRequest(actions=actions, context_features=context)
        response = client.rank(rank_request=rank_request)
        print("Rank API response:", response, "\n")
        
        eventid = response.event_id
        actionid = response.reward_action_id
        print("Personalizer recommended action", actionid, "and it was shown as the featured product.\n")
        
        reward_score = get_reward_score(user, actionid, context)
        client.events.reward(event_id=eventid, value=reward_score)     
        print("\nA reward score of", reward_score , "was sent to Personalizer.")
        print("------------\n")

continue_loop = True
while continue_loop:
    run_personalizer_cycle()
    
    br = input("Press Q to exit, or any other key to run another loop: ")
    if(br.lower()=='q'):
        continue_loop = False

Execute o programa

Depois que todo o código acima for incluído no arquivo Python, você poderá executá-lo no diretório do aplicativo.

python personalizer_quickstart.py

Gerar exemplo de eventos para análise (opcional)

Você pode gerar facilmente cinco mil eventos deste cenário de demonstração de início rápido, o que é suficiente para obter experiência com o uso do modo Aprendiz, modo Online, execução de avaliações offline e criação de avaliações de recursos. Basta substituir esse código acima:

continue_loop = True
while continue_loop:
    run_personalizer_cycle()
    
    br = input("Press Q to exit, or any other key to run another loop: ")
    if(br.lower()=='q'):
        continue_loop = False

pelo seguinte:

for i in range(0,1000):
    run_personalizer_cycle()

em seguida, execute o programa.

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.

Limpar recursos

Para limpar a assinatura dos Serviços Cognitivos, você pode excluir o recurso ou o grupo de recursos, que também exclui todos os outros recursos associados.

Baixar o modelo treinado do início rápido

Se você quiser baixar um modelo do Personalizador que foi treinado em 5.000 eventos do exemplo de Início Rápido, visite o repositório Azure-Samples e baixe o arquivo zip do modelo e carregue-o na instância do Personalizador na seção "Instalação" –> "Importação/Exportação de Modelos".

Próximas etapas