Tutorial: Adicionar personalizador a uma aplicação web .NET

Personalize uma aplicação web C# .NET com um ciclo Personalizador para fornecer o conteúdo correto ao utilizador com base em ações (com funcionalidades) e funcionalidades contextuais.

Neste tutorial, vai aprender a:

Selecione o melhor conteúdo para um aplicativo Web

Um aplicativo Web deve usar o Personalizador quando há uma lista de ações (algum tipo de conteúdo) na página da Web que precisa ser personalizada para um único item superior (rewardActionId) para exibição. Exemplos de listas de ações incluem artigos de notícias, locais de posicionamento de botões e opções de palavras para nomes de produtos.

Você envia a lista de ações, juntamente com os recursos de contexto, para o loop do Personalizador. O Personalizador seleciona a melhor ação e, em seguida, seu aplicativo Web exibe essa ação.

Neste tutorial, as ações são tipos de alimentos:

• pasta
• Gelado
• sumo
• salada
• pipoca
• café
• sopa

Para ajudar o Personalizador a saber mais sobre as suas ações, envie ambas as ações com características e características de contexto com cada pedido à API Rank.

Um recurso do modelo é a informação sobre a ação ou o contexto que pode ser agregada (agrupada) entre os membros da sua base de utilizadores do aplicativo Web. Um recurso não é específico individualmente (como um ID de usuário) ou altamente específico (como uma hora exata do dia).

Ações com funcionalidades

Cada ação (item de conteúdo) tem recursos para ajudar a distinguir o item alimentar.

As funcionalidades não estão configuradas como parte da configuração do loop no portal do Azure. Em vez disso, eles são enviados como um objeto JSON com cada chamada de API de classificação. Isso permite flexibilidade para que as ações e seus recursos cresçam, mudem e diminuam ao longo do tempo, o que permite que o Personalizer siga as tendências.

 /// <summary>
  /// Creates personalizer actions feature list.
  /// </summary>
  /// <returns>List of actions for personalizer.</returns>
  private IList<RankableAction> GetActions()
  {
      IList<RankableAction> actions = new List<RankableAction>
      {
          new RankableAction
          {
              Id = "pasta",
              Features =
              new List<object>() { new { taste = "savory", spiceLevel = "medium" }, new { nutritionLevel = 5, cuisine = "italian" } }
          },

          new RankableAction
          {
              Id = "ice cream",
              Features =
              new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionalLevel = 2 } }
          },

          new RankableAction
          {
              Id = "juice",
              Features =
              new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionLevel = 5 }, new { drink = true } }
          },

          new RankableAction
          {
              Id = "salad",
              Features =
              new List<object>() { new { taste = "sour", spiceLevel = "low" }, new { nutritionLevel = 8 } }
          },

          new RankableAction
          {
              Id = "popcorn",
              Features =
              new List<object>() { new { taste = "salty", spiceLevel = "none" }, new { nutritionLevel = 3 } }
          },

          new RankableAction
          {
              Id = "coffee",
              Features =
              new List<object>() { new { taste = "bitter", spiceLevel = "none" }, new { nutritionLevel = 3 }, new { drink = true } }
          },

          new RankableAction
          {
              Id = "soup",
              Features =
              new List<object>() { new { taste = "sour", spiceLevel = "high" }, new { nutritionLevel =  7} }
          }
      };

      return actions;
  }

Recursos de contexto

Os recursos de contexto ajudam o Personalizer a entender o contexto das ações. O contexto para este aplicativo de exemplo inclui:

• Hora do dia - manhã, tarde, fim da tarde, noite
• preferência do utilizador pelo sabor - salgado, doce, amargo, azedo ou salgado
• contexto do navegador - agente do usuário, localização geográfica, referenciador

/// <summary>
/// Get users time of the day context.
/// </summary>
/// <returns>Time of day feature selected by the user.</returns>
private string GetUsersTimeOfDay()
{
    Random rnd = new Random();
    string[] timeOfDayFeatures = new string[] { "morning", "noon", "afternoon", "evening", "night", "midnight" };
    int timeIndex = rnd.Next(timeOfDayFeatures.Length);
    return timeOfDayFeatures[timeIndex];
}

/// <summary>
/// Gets user food preference.
/// </summary>
/// <returns>Food taste feature selected by the user.</returns>
private string GetUsersTastePreference()
{
    Random rnd = new Random();
    string[] tasteFeatures = new string[] { "salty", "bitter", "sour", "savory", "sweet" };
    int tasteIndex = rnd.Next(tasteFeatures.Length);
    return tasteFeatures[tasteIndex];
}

Como é que a aplicação Web utiliza o Personalizador?

A aplicação Web utiliza o Personalizador para selecionar a melhor ação a partir da lista de opções alimentares. Ele faz isso enviando as seguintes informações com cada chamada de API de classificação:

• ações com as suas características, tais como taste e spiceLevel
• recursos de contexto como hora do dia, preferência do time utilizador e informações do agente de utilizador do navegador, e recursos de contexto
• ações a excluir como sumo
• eventId, que é diferente para cada chamada para Rank API.

Recursos de modelo do personalizador em uma aplicação web

O personalizador precisa de recursos para as ações (conteúdo) e o contexto atual (usuário e ambiente). Os recursos são usados para alinhar as ações ao contexto atual no modelo. O modelo é uma representação do conhecimento passado do Personalizer sobre ações, contexto e suas características que lhe permite tomar decisões informadas.

O modelo, incluindo as funcionalidades, é atualizado num calendário baseado na sua definição de frequência de atualização modelo no portal Azure.

Planear funcionalidades e os seus valores

Os recursos devem ser selecionados com o mesmo planejamento e design que você aplicaria a qualquer esquema ou modelo em sua arquitetura técnica. Os valores das funcionalidades podem ser definidos com lógica de negócios ou sistemas de terceiros. Os valores de recursos não devem ser tão específicos que não se apliquem a um grupo ou classe de recursos.

Generalizar valores de características

Generalizar em categorias

Este aplicativo usa time como um recurso, mas agrupa o tempo em categorias como morning, afternoon, eveninge night. Este é um exemplo de utilização da informação do tempo, mas não de uma forma muito específica, como 10:05:01 UTC+2.

Generalizar em partes

Este aplicativo usa os recursos de solicitação HTTP do navegador. Isso começa com uma cadeia de caracteres muito específica com todos os dados, por exemplo:

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/530.99 (KHTML, like Gecko) Chrome/80.0.3900.140 Safari/537.36

A biblioteca de classes HttpRequestFeatures generaliza essa cadeia de caracteres em um objeto userAgentInfo com valores individuais. Todos os valores que são muito específicos são definidos como uma cadeia de caracteres vazia. Quando os recursos de contexto para a solicitação são enviados, ele tem o seguinte formato JSON:

{
  "httpRequestFeatures": {
    "_synthetic": false,
    "OUserAgent": {
      "_ua": "",
      "_DeviceBrand": "",
      "_DeviceFamily": "Other",
      "_DeviceIsSpider": false,
      "_DeviceModel": "",
      "_OSFamily": "Windows",
      "_OSMajor": "10",
      "DeviceType": "Desktop"
    }
  }
}

Utilizando a aplicação web de exemplo

O aplicativo Web baseado em navegador de exemplo (todo o código é fornecido) precisa dos seguintes aplicativos instalados para executar o aplicativo.

Instale o seguinte software:

• .NET Core 2.1 - o servidor back-end de exemplo usa .NET core
• Node.js - o cliente/front-end depende desta aplicação
• Visual Studio 2019, ou .NET Core CLI - use o ambiente de desenvolvimento de Visual Studio 2019 ou o .NET Core CLI para construir e executar a aplicação

Configurar o exemplo

1. Clone o repositório Personalizador de IA do Azure Samples.

   git clone https://github.com/Azure-Samples/cognitive-services-personalizer-samples.git
   

2. Navegue até samples/HttpRequestFeatures para abrir a solução, HttpRequestFeaturesExample.sln.

   Se solicitado, permita que o Visual Studio atualize o pacote .NET para o Personalizer.

Configurar o Personalizador de IA do Azure Service

1. Criar um recurso Personalizador no portal Azure.

2. No portal Azure, encontre o Endpoint e Key1 ou Key2 (ambos funcionam) no separador Keys and Endpoints. Estes são o teu PersonalizerServiceEndpoint e o teu PersonalizerApiKey.

3. Preencha o PersonalizerServiceEndpointappsettings.json.

4. Configure o PersonalizerApiKey como segredos da aplicação de uma das seguintes maneiras:

   • Se estiveres a usar a CLI .NET Core, podes usar o comando dotnet user-secrets set "PersonalizerApiKey" "<API Key>".
   • Se estiver a usar Visual Studio, pode clicar com o botão direito no projeto e selecionar a opção de menu Gerir Segredos de Utilizador para configurar as teclas Personalizador. Ao fazer isto, Visual Studio abrirá um ficheiro secrets.json onde pode adicionar as chaves da seguinte forma:

   {
     "PersonalizerApiKey": "<your personalizer key here>",
   }
   

Executar o exemplo

Crie e execute HttpRequestFeaturesExample com um dos seguintes métodos:

• Visual Studio 2019: Pressione F5
• .NET Core CLI: dotnet build depois dotnet run

Através de um navegador da web, você pode enviar uma solicitação de classificação e uma solicitação de recompensa e ver suas respostas, bem como os recursos de solicitação http extraídos do seu ambiente.

Demonstrar o loop do Personalizador

1. Selecione o botão Gerar nova solicitação de classificação para criar um novo objeto JSON para a chamada da API de classificação. Isso cria as ações (com recursos) e os recursos de contexto e exibe os valores para que você possa ver a aparência do JSON.

   Para sua própria aplicação futura, a geração de ações e recursos pode acontecer no cliente, no servidor, uma mistura dos dois, ou com chamadas para outros serviços.

2. Selecione Enviar solicitação de classificação para enviar o objeto JSON para o servidor. O servidor chama a API Personalizer Rank. O servidor recebe a resposta e retorna a ação mais bem classificada para o cliente exibir.

3. Defina o valor da recompensa e, em seguida, selecione o botão Enviar Pedido de Recompensa . Se você não alterar o valor da recompensa, o aplicativo cliente sempre enviará o valor de 1 para o Personalizador.

   

   Para sua própria aplicação futura, a geração da pontuação de recompensa pode acontecer após a coleta de informações do comportamento do usuário no cliente, juntamente com a lógica de negócios no servidor.

Compreender a aplicação Web de exemplo

A aplicação web de exemplo tem um servidor C# .NET, que gere a coleção de funcionalidades e o envio e receção de chamadas HTTP para o seu endpoint Personalizer.

A aplicação web de exemplo utiliza uma aplicação cliente front-end knockout para capturar funcionalidades e processar ações da interface de utilizador, como clicar em botões e enviar dados para o servidor .NET.

As seções a seguir explicam as partes do servidor e do cliente que um desenvolvedor precisa entender para usar o Personalizador.

Rank API: O aplicativo cliente envia contexto para o servidor

A aplicação cliente coleta o agente de utilizador do navegador.

Rank API: O aplicativo de servidor chama o Personalizer

Esta é uma típica aplicação web .NET com uma aplicação cliente, grande parte do código padrão é fornecido para si. Qualquer código não específico do Personalizer é removido dos seguintes trechos de código para que você possa se concentrar no código específico do Personalizador.

Criar Cliente Personalizer

No Startup.cs do servidor, o endpoint e a chave do Personalizer são usados para criar o Personalizer client. O aplicativo cliente não precisa se comunicar com o Personalizer neste aplicativo, em vez disso, depende do servidor para fazer essas chamadas SDK.

O código de arranque .NET do servidor web é:

using Microsoft.Azure.CognitiveServices.Personalizer;
// ... other using statements removed for brevity

namespace HttpRequestFeaturesExample
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            string personalizerApiKey = Configuration.GetSection("PersonalizerApiKey").Value;
            string personalizerEndpoint = Configuration.GetSection("PersonalizerConfiguration:ServiceEndpoint").Value;
            if (string.IsNullOrEmpty(personalizerEndpoint) || string.IsNullOrEmpty(personalizerApiKey))
            {
                throw new ArgumentException("Missing Azure AI Personalizer endpoint and/or api key.");
            }
            services.AddSingleton(client =>
            {
                return new PersonalizerClient(new ApiKeyServiceClientCredentials(personalizerApiKey))
                {
                    Endpoint = personalizerEndpoint
                };
            });

            services.AddMvc();
        }

        // ... code removed for brevity
    }
}

Selecione a melhor ação

No PersonalizerController.cs do servidor, a API GenerateRank do servidor resume a preparação para chamar a API Rank.

• Criar novo eventId para a chamada Rank
• Obter a lista de ações
• Obter a lista de recursos do usuário e criar recursos de contexto
• Opcionalmente, defina todas as ações excluídas
• API de classificação de chamadas, retornar resultados para o cliente

/// <summary>
/// Creates a RankRequest with user time of day, HTTP request features,
/// and taste as the context and several different foods as the actions
/// </summary>
/// <returns>RankRequest with user info</returns>
[HttpGet("GenerateRank")]
public RankRequest GenerateRank()
{
    string eventId = Guid.NewGuid().ToString();

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

    // Get context information from the user.
    HttpRequestFeatures httpRequestFeatures = GetHttpRequestFeaturesFromRequest(Request);
    string timeOfDayFeature = GetUsersTimeOfDay();
    string tasteFeature = GetUsersTastePreference();

    // Create current context from user specified data.
    IList<object> currentContext = new List<object>() {
            new { time = timeOfDayFeature },
            new { taste = tasteFeature },
            new { httpRequestFeatures }
    };

    // Exclude an action for personalizer ranking. This action will be held at its current position.
    IList<string> excludeActions = new List<string> { "juice" };

    // Rank the actions
    return new RankRequest(actions, currentContext, excludeActions, eventId);
}

O JSON enviado para o Personalizer, contendo ações (com recursos) e os recursos de contexto atual, tem a seguinte aparência:

{
    "contextFeatures": [
        {
            "time": "morning"
        },
        {
            "taste": "savory"
        },
        {
            "httpRequestFeatures": {
                "_synthetic": false,
                "MRefer": {
                    "referer": "http://localhost:51840/"
                },
                "OUserAgent": {
                    "_ua": "",
                    "_DeviceBrand": "",
                    "_DeviceFamily": "Other",
                    "_DeviceIsSpider": false,
                    "_DeviceModel": "",
                    "_OSFamily": "Windows",
                    "_OSMajor": "10",
                    "DeviceType": "Desktop"
                }
            }
        }
    ],
    "actions": [
        {
            "id": "pasta",
            "features": [
                {
                    "taste": "savory",
                    "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": "sour",
                    "spiceLevel": "low"
                },
                {
                    "nutritionLevel": 8
                }
            ]
        },
        {
            "id": "popcorn",
            "features": [
                {
                    "taste": "salty",
                    "spiceLevel": "none"
                },
                {
                    "nutritionLevel": 3
                }
            ]
        },
        {
            "id": "coffee",
            "features": [
                {
                    "taste": "bitter",
                    "spiceLevel": "none"
                },
                {
                    "nutritionLevel": 3
                },
                {
                    "drink": true
                }
            ]
        },
        {
            "id": "soup",
            "features": [
                {
                    "taste": "sour",
                    "spiceLevel": "high"
                },
                {
                    "nutritionLevel": 7
                }
            ]
        }
    ],
    "excludedActions": [
        "juice"
    ],
    "eventId": "82ac52da-4077-4c7d-b14e-190530578e75",
    "deferActivation": null
}

Devolver Personalizer rewardActionId ao cliente

A API Rank retorna a melhor ação selecionada rewardActionId para o servidor.

Exiba a ação retornada em rewardActionId.

{
    "ranking": [
        {
            "id": "popcorn",
            "probability": 0.833333254
        },
        {
            "id": "salad",
            "probability": 0.03333333
        },
        {
            "id": "juice",
            "probability": 0
        },
        {
            "id": "soup",
            "probability": 0.03333333
        },
        {
            "id": "coffee",
            "probability": 0.03333333
        },
        {
            "id": "pasta",
            "probability": 0.03333333
        },
        {
            "id": "ice cream",
            "probability": 0.03333333
        }
    ],
    "eventId": "82ac52da-4077-4c7d-b14e-190530578e75",
    "rewardActionId": "popcorn"
}

O cliente exibe a ação rewardActionId

Neste tutorial, o rewardActionId valor é exibido.

Em seu próprio aplicativo futuro, isso pode ser algum texto exato, um botão ou uma seção da página da Web destacada. A lista é retornada para qualquer pós-análise de pontuações, não para uma ordenação do conteúdo. Apenas o rewardActionId conteúdo deve ser exibido.

API de recompensa: coletar informações para recompensa

A pontuação de recompensa deve ser cuidadosamente planeada, tal como as funcionalidades são planeadas. A pontuação de recompensa normalmente deve ser um valor de 0 a 1. O valor pode ser calculado parcialmente no aplicativo cliente, com base nos comportamentos do usuário, e parcialmente no servidor, com base na lógica de negócios e metas.

Se o servidor não chamar a API de Recompensas dentro do tempo de espera Reward configurado no portal Azure para o seu recurso Personalizer, então o Default reward (também configurado no portal Azure) é usado para esse evento.

Neste aplicativo de exemplo, você pode selecionar um valor para ver como a recompensa afeta as seleções.

Outras formas de aprender com este exemplo

O exemplo utiliza vários eventos baseados no tempo configurados no portal do Azure para o seu recurso Personalizer. Jogue com esses valores e retorne a este aplicativo Web de exemplo para ver como as alterações afetam as chamadas de Classificação e Recompensa:

• Tempo de espera de recompensa
• Frequência de atualização do modelo

As configurações adicionais para jogar incluem:

• Recompensa padrão
• Percentagem de exploração

Limpar recursos

Quando terminar este tutorial, limpe os seguintes recursos:

• Exclua o diretório de projeto de exemplo.
• Exclua o seu recurso do Personalizador - pense num recurso do Personalizador como dedicado às ações e ao contexto - só reutilize o recurso se ainda estiver a usar os alimentos como domínio de assuntos das ações.

Próximos passos

• Como funciona o Personalizer
• Funcionalidades: aprenda conceitos sobre funcionalidades através de ações e contexto
• Recompensas: saiba mais sobre como calcular recompensas