Introdução ao multislot para o Azure AI Personalizer

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

Pré-requisitos

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

Configuração

Atualizar instância do Personalizer para Multi-Slot

1. Desativar a Otimização Automática No portal do Azure, no recurso Personalizador, em Gestão de Recursos, na página Modelo e definições de aprendizagem, desative a Otimização Automática e guarde.

2. Atualizar o Personalizer para vários slots No portal do Azure, no recurso Personalizador, em Gerenciamento de Recursos, na página Configurações de modelo e aprendizagem , selecione Exportar configurações de aprendizagem. O campo de argumentos no arquivo json baixado começará com --cb_explore_adf. Altere para --ccb_explore_adf e salve o arquivo. CB (bandidos contextuais) e CCB (bandidos contextuais condicionais) são os algoritmos que o Personalizer usa para personalização de slot único e multislot, respectivamente. ADF (action dependent features) significa que as ações são expressas/identificadas com características.

Na mesma guia no portal, em importar configurações de aprendizagem, procure para encontrar seu arquivo json modificado recentemente e carregue-o. Isso atualizará sua instância do Personalizer para ser um Personalizador "Multi Slot" e agora suportará chamadas de Rank e Reward com vários slots.

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

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

Alterar o tempo de espera da recompensa

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

Criar um novo aplicativo C#

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

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

dotnet new console -n personalizer-quickstart

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

dotnet build

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

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

Instalar a biblioteca de cliente

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

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

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

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

Modelo de objeto

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

Para pedir o melhor item do conteúdo para cada slot, crie um objeto PersonalizerRankMultiSlotOptions e passe-o para PersonalizerClient.RankMultiSlot. O método RankMultiSlot retorna um PersonalizerMultiSlotRankResult.

Para enviar uma pontuação de recompensa para o Personalizer, crie um PersonalizerRewardMultiSlotOptions e, em seguida, passe-o para o método PersonalizerClient.RewardMultiSlot juntamente com o ID do evento correspondente.

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

Exemplos de código

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

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

Autenticar o cliente

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

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

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

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

Em seguida, construa os URLs de Classificação e Recompensa.

static PersonalizerClient InitializePersonalizerClient(Uri url)
{
    return new PersonalizerClient(url, new AzureKeyCredential(ResourceKey));
}

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

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

private static IList<PersonalizerRankableAction> GetActions()
{
    IList<PersonalizerRankableAction> actions = new List<PersonalizerRankableAction>
    {
        new PersonalizerRankableAction(
            id: "Red-Polo-Shirt-432",
            features:
            new List<object>() { new { onSale = "true", price = "20", category = "Clothing" } }
        ),

        new PersonalizerRankableAction(
            id: "Tennis-Racket-133",
            features:
            new List<object>() { new { onSale = "false", price = "70", category = "Sports" } }
        ),

        new PersonalizerRankableAction(
            id: "31-Inch-Monitor-771",
            features:
            new List<object>() { new { onSale = "true", price = "200", category = "Electronics" } }
        ),

        new PersonalizerRankableAction(
            id: "XBox-Series X-117",
            features:
            new List<object>() { new { onSale = "false", price = "499", category = "Electronics" } }
        )
    };

    return actions;
}

Obter slots

Os slots compõem a página com a qual o usuário irá interagir. O personalizador decidirá qual ação exibir em cada um dos slots definidos. As ações podem ser excluídas de slots específicos, mostradas como ExcludeActions. BaselineAction é a ação padrão para o slot, que teria sido exibido sem o uso do Personalizador.

Este guia de início rápido tem recursos de slot simples. Em sistemas de produção, determinar e avaliar características pode ser uma questão não trivial.

private static IList<PersonalizerSlotOptions> GetSlots()
{
    IList<PersonalizerSlotOptions> slots = new List<PersonalizerSlotOptions>
    {
        new PersonalizerSlotOptions(
            id: "BigHeroPosition",
            features: new List<object>() { new { size = "large", position = "left" } },
            excludedActions: new List<string>() { "31-Inch-Monitor-771" },
            baselineAction: "Red-Polo-Shirt-432"

        ),

        new PersonalizerSlotOptions(
            id: "SmallSidebar",
            features: new List<object>() { new { size = "small", position = "right" } },
            excludedActions: new List<string>() { "Tennis-Racket-133" },
            baselineAction: "XBox-Series X-117"
        ),
    };

    return slots;
}

Obter preferências do usuário para contexto

Adicione os seguintes métodos à classe Program para obter a entrada de um usuário da linha de comando para a hora do dia e o tipo de dispositivo em que o usuário está. Esses métodos 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 GetDeviceForContext()
{
    string[] deviceFeatures = new string[] { "mobile", "tablet", "desktop" };

    Console.WriteLine("\nWhat is the device type (enter number)? 1. Mobile 2. Tablet 3. Desktop");
    if (!int.TryParse(GetKey(), out int deviceIndex) || deviceIndex < 1 || deviceIndex > deviceFeatures.Length)
    {
        Console.WriteLine("\nEntered value is invalid. Setting feature value to " + deviceFeatures[0] + ".");
        deviceIndex = 1;
    }

    return deviceFeatures[deviceIndex - 1];
}

Ambos os métodos usam o GetKey método para ler a seleção do usuário a partir da linha de comando.

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

private static IList<object> GetContext(string time, string device)
{
    return new List<object>()
    {
        new { time = time },
        new { device = device }
    };
}

Criar o ciclo de aprendizagem

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

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

static void Main(string[] args)
{
    Console.WriteLine($"Welcome to this Personalizer Quickstart!\n" +
    $"This code will help you understand how to use the Personalizer APIs (multislot rank and multislot reward).\n" +
    $"Each iteration represents a user interaction and will demonstrate how context, actions, slots, 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();
    IList<PersonalizerSlotOptions> slots = GetSlots();
    PersonalizerClient client = InitializePersonalizerClient(new Uri(ServiceEndpoint));

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

        string timeOfDayFeature = GetTimeOfDayForContext();
        string deviceFeature = GetDeviceForContext();

        IList<object> currentContext = GetContext(timeOfDayFeature, deviceFeature);

        string eventId = Guid.NewGuid().ToString();

        var multiSlotRankOptions = new PersonalizerRankMultiSlotOptions(actions, slots, currentContext, eventId);
        PersonalizerMultiSlotRankResult multiSlotRankResult = client.RankMultiSlot(multiSlotRankOptions);

        for (int i = 0; i < multiSlotRankResult.Slots.Count(); ++i)
        {
            string slotId = multiSlotRankResult.Slots[i].SlotId;
            Console.WriteLine($"\nPersonalizer service decided you should display: { multiSlotRankResult.Slots[i].RewardActionId} in slot {slotId}. Is this correct? (y/n)");

            string answer = GetKey();

            if (answer == "Y")
            {
                client.RewardMultiSlot(eventId, slotId, 1f);
                Console.WriteLine("\nGreat! The application will send Personalizer a reward of 1 so it learns from this choice of action for this slot.");
            }
            else if (answer == "N")
            {
                client.RewardMultiSlot(eventId, slotId, 0f);
                Console.WriteLine("\nYou didn't like the recommended item. The application will send Personalizer a reward of 0 for this choice of action for this slot.");
            }
            else
            {
                client.RewardMultiSlot(eventId, slotId, 0f);
                Console.WriteLine("\nEntered choice is invalid. Service assumes that you didn't like the recommended item.");
            }
        }

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

    } while (runLoop);
}

Dê uma olhada mais de perto nas chamadas de classificação e recompensa nas seções a seguir. Adicione os seguintes métodos, que obtêm as opções de conteúdo, obtêm slots e enviam solicitações de classificação e recompensa de vários slots antes de executar o arquivo de código:

• GetActions
• GetSlots
• GetTimeOfDayForContext
• GetDeviceForContext
• GetKey
• GetContext

Solicite a melhor ação

Para completar a solicitação de classificação, o programa pede as preferências do usuário para criar uma Context das opções de conteúdo. A solicitação contém o contexto, ações e slots com seus respetivos recursos e um ID de evento exclusivo, para receber uma resposta.

Este guia de início rápido tem recursos de contexto simples de hora do dia e dispositivo do usuário. Em sistemas de produção, determinar e avaliar ações e características pode ser uma questão não trivial.

string timeOfDayFeature = GetTimeOfDayForContext();
string deviceFeature = GetDeviceForContext();

IList<object> currentContext = GetContext(timeOfDayFeature, deviceFeature);

string eventId = Guid.NewGuid().ToString();

var multiSlotRankOptions = new PersonalizerRankMultiSlotOptions(actions, slots, currentContext, eventId);
PersonalizerMultiSlotRankResult multiSlotRankResult = client.RankMultiSlot(multiSlotRankOptions);

Envie uma recompensa

Para obter a pontuação de recompensa para a solicitação de recompensa, o programa obtém a seleção do usuário para cada slot através da linha de comando, atribui um valor numérico (pontuação de recompensa) à seleção e, em seguida, envia o ID de evento exclusivo, o ID do slot e a pontuação de recompensa para cada slot como o valor numérico para a API de recompensa. Não é necessário definir uma recompensa para cada slot.

Este guia de início rápido atribui um número simples como uma pontuação de recompensa, seja 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 de suas necessidades específicas.

for (int i = 0; i < multiSlotRankResult.Slots.Count(); ++i)
{
    string slotId = multiSlotRankResult.Slots[i].SlotId;
    Console.WriteLine($"\nPersonalizer service decided you should display: { multiSlotRankResult.Slots[i].RewardActionId} in slot {slotId}. Is this correct? (y/n)");

    string answer = GetKey();

    if (answer == "Y")
    {
        client.RewardMultiSlot(eventId, slotId, 1f);
        Console.WriteLine("\nGreat! The application will send Personalizer a reward of 1 so it learns from this choice of action for this slot.");
    }
    else if (answer == "N")
    {
        client.RewardMultiSlot(eventId, slotId, 0f);
        Console.WriteLine("\nYou didn't like the recommended item. The application will send Personalizer a reward of 0 for this choice of action for this slot.");
    }
    else
    {
        client.RewardMultiSlot(eventId, slotId, 0f);
        Console.WriteLine("\nEntered choice is invalid. Service assumes that you didn't like the recommended item.");
    }
}

Execute o programa

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

dotnet run

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

Documentação | de referência Amostras conceptuais | de vários ranhuras

Pré-requisitos

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

Configuração

Atualizar instância do Personalizer para Multi-Slot

1. Desativar a Otimização Automática No portal do Azure, no recurso Personalizador, em Gestão de Recursos, na página Modelo e definições de aprendizagem, desative a Otimização Automática e guarde.

2. Atualizar o Personalizer para vários slots No portal do Azure, no recurso Personalizador, em Gerenciamento de Recursos, na página Configurações de modelo e aprendizagem , selecione Exportar configurações de aprendizagem. O campo de argumentos no arquivo json baixado começará com --cb_explore_adf. Altere para --ccb_explore_adf e salve o arquivo. CB (bandidos contextuais) e CCB (bandidos contextuais condicionais) são os algoritmos que o Personalizer usa para personalização de slot único e multislot, respectivamente. ADF (action dependent features) significa que as ações são expressas/identificadas com características.

Na mesma guia no portal, em importar configurações de aprendizagem, procure para encontrar seu arquivo json modificado recentemente e carregue-o. Isso atualizará sua instância do Personalizer para ser um Personalizador "Multi Slot" e agora suportará chamadas de Rank e Reward com vários slots.

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

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

Alterar o tempo de espera da recompensa

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

Criar uma nova aplicação Node.js

Numa janela de consola (como cmd, PowerShell ou Bash), crie um novo diretório para a sua aplicação e navegue para a mesma.

mkdir myapp && cd myapp

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

npm init -y

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

const axios = require('axios');
const { v4: uuidv4 } = require('uuid');
const readline = require('readline-sync');
// The endpoint specific to your personalization service instance; 
// e.g. https://<your-resource-name>.cognitiveservices.azure.com
const PersonalizationBaseUrl = '<REPLACE-WITH-YOUR-PERSONALIZER-ENDPOINT>';
// The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF"
const ResourceKey = '<REPLACE-WITH-YOUR-PERSONALIZER-KEY>';

Instalar os pacotes NPM para início rápido

npm install readline-sync uuid axios --save

Modelo de objeto

Para pedir o melhor item do conteúdo para cada slot, crie um rankRequest e, em seguida, envie uma solicitação de postagem para multislot/rank. A resposta é então analisada em um rankResponse.

Para enviar uma pontuação de recompensa para o Personalizador, crie uma recompensa e, em seguida, envie uma solicitação de publicação para multislot/events/{eventId}/reward.

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

Exemplos de código

Esses trechos de código mostram como executar as seguintes tarefas enviando solicitações HTTP para NodeJS:

• Criar URLs base
• Rank API
• API de recompensa

Criar URLs base

Nesta seção, você construirá as URLs de Classificação/Recompensa usando a URL base e os cabeçalhos de solicitação usando a chave de recurso.

const MultiSlotRankUrl = PersonalizationBaseUrl.concat('personalizer/v1.1-preview.1/multislot/rank');
const MultiSlotRewardUrlBase = PersonalizationBaseUrl.concat('personalizer/v1.1-preview.1/multislot/events/');
const Headers = {
    'ocp-apim-subscription-key': ResourceKey,
    'Content-Type': 'application/json'
};

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

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

function getActions() {
    return [
        {
            'id': 'Red-Polo-Shirt-432',
            'features': [
                {
                    'onSale': 'true',
                    'price': 20,
                    'category': 'Clothing'
                }
            ]
        },
        {
            'id': 'Tennis-Racket-133',
            'features': [
                {
                    'onSale': 'false',
                    'price': 70,
                    'category': 'Sports'
                }
            ]
        },
        {
            'id': '31-Inch-Monitor-771',
            'features': [
                {
                    'onSale': 'true',
                    'price': 200,
                    'category': 'Electronics'
                }
            ]
        },
        {
            'id': 'XBox-Series X-117',
            'features': [
                {
                    'onSale': 'false',
                    'price': 499,
                    'category': 'Electronics'
                }
            ]
        }
    ];
}

Obter preferências do usuário para contexto

Adicione os seguintes métodos ao script para obter a entrada de um usuário da linha de comando para a hora do dia e o tipo de dispositivo em que o usuário está. Estes serão usados como recursos de contexto.

function getContextFeatures() {
    const timeOfDayFeatures = ['morning', 'afternoon', 'evening', 'night'];
    const deviceFeatures = ['mobile', 'tablet', 'desktop'];

    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 device is the user on (enter number)? 1. mobile 2. tablet 3. desktop\n');
    selection = parseInt(answer);
    const device = selection >= 1 && selection <= 3 ? deviceFeatures[selection - 1] : deviceFeatures[0];

    console.log('Selected features:\n');
    console.log('Time of day: ' + timeOfDay + '\n');
    console.log('Device: ' + device + '\n');

    return [
        {
            'time': timeOfDay
        },
        {
            'device': device
        }
    ];
}

Obter slots

Os slots compõem a página com a qual o usuário irá interagir. O personalizador decidirá qual ação exibir em cada um dos slots definidos. As ações podem ser excluídas de slots específicos, mostradas como ExcludeActions. BaselineAction é a ação padrão para o slot que teria sido exibido sem o uso do Personalizador.

Este guia de início rápido tem recursos de slot simples. Em sistemas de produção, determinar e avaliar características pode ser uma questão não trivial.

function getSlots() {
    return [
        {
            'id': 'BigHeroPosition',
            'features': [
                {
                    'size': 'large',
                    'position': 'left',
                }
            ],
            'excludedActions': ['31-Inch-Monitor-771'],
            'baselineAction': 'Red-Polo-Shirt-432'
        },
        {
            'id': 'SmallSidebar',
            'features': [
                {
                    'size': 'small',
                    'position': 'right',
                }
            ],
            'excludedActions': ['Tennis-Racket-133'],
            'baselineAction': 'XBox-Series X-117'
        }
    ];
}

Fazer solicitações HTTP

Adicione essas funções para enviar solicitações de postagem para o ponto de extremidade do Personalizador para chamadas de classificação e recompensa com vários slots.

async function sendMultiSlotRank(rankRequest) {
    try {
        let response = await axios.post(MultiSlotRankUrl, rankRequest, { headers: Headers })
        return response.data;
    }
    catch (err) {
        if(err.response)
        {
            throw err.response.data
        }
        console.log(err)
        throw err;
    }
}

async function sendMultiSlotReward(rewardRequest, eventId) {
    try {
        let rewardUrl = MultiSlotRewardUrlBase.concat(eventId, '/reward');
        let response = await axios.post(rewardUrl, rewardRequest, { headers: Headers })
    }
    catch (err) {
        console.log(err);
        throw err;
    }
}

Obter feedback sobre as decisões do Personalizador

Adicione o seguinte método ao script. Você sinalizará se o Personalizer tomou uma boa decisão para cada slot através do prompt de linha de comando.

function getRewardForSlot() {
    let answer = readline.question('\nIs this correct? (y/n)\n').toUpperCase();
    if (answer === 'Y') {
        console.log('\nGreat! The application will send Personalizer a reward of 1 so it learns from this choice of action for this slot.\n');
        return 1;
    }
    else if (answer === 'N') {
        console.log('\nYou didn\'t like the recommended item.The application will send Personalizer a reward of 0 for this choice of action for this slot.\n');
        return 0;
    }
    console.log('\nEntered choice is invalid. Service assumes that you didn\'t like the recommended item.\n');
    return 0;
}

Criar o ciclo de aprendizagem

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

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

let runLoop = true;

(async () => {
    do {

        let multiSlotRankRequest = {};

        // Generate an ID to associate with the request.
        multiSlotRankRequest.eventId = uuidv4();

        // Get context information from the user.
        multiSlotRankRequest.contextFeatures = getContextFeatures();

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

        // Get the list of slots for which Personalizer will pick the best action.
        multiSlotRankRequest.slots = getSlots();

        multiSlotRankRequest.deferActivation = false;

        try {
            //Rank the actions for each slot
            let multiSlotRankResponse = await sendMultiSlotRank(multiSlotRankRequest);
            let multiSlotrewards = {};
            multiSlotrewards.reward = [];
    
            for (let i = 0; i < multiSlotRankResponse.slots.length; i++) {
                console.log('\nPersonalizer service decided you should display: '.concat(multiSlotRankResponse.slots[i].rewardActionId, ' in slot ', multiSlotRankResponse.slots[i].id, '\n'));
    
                let slotReward = {};
                slotReward.slotId = multiSlotRankResponse.slots[i].id;
                // User agrees or disagrees with Personalizer decision for slot
                slotReward.value = getRewardForSlot();
                multiSlotrewards.reward.push(slotReward);
            }
    
            // Send the rewards for the event
            await sendMultiSlotReward(multiSlotrewards, multiSlotRankResponse.eventId);
    
            let answer = readline.question('\nPress q to break, any other key to continue:\n').toUpperCase();
            if (answer === 'Q') {
                runLoop = false;
            }
        }
        catch (err) {
            console.log(err);
            throw err;
        }



    } while (runLoop);
})()

Dê uma olhada mais de perto nas chamadas de classificação e recompensa nas seções a seguir.

Adicione os seguintes métodos, que obtêm as opções de conteúdo, obtêm as preferências do usuário para o contexto, obtêm os slots, fazem solicitações HTTP, obtêm recompensa por cada slot antes de executar o arquivo de código:

• getActions
• getContextFeatures
• getSlots
• sendRank
• sendReward
• getRewardForSlot

Solicite a melhor ação

Para completar a solicitação de classificação, o programa solicita as preferências do usuário para criar opções de conteúdo. O corpo da solicitação contém o contexto, as ações e os slots com seus respetivos recursos. O sendMultiSlotRank método recebe um rankRequest e executa a solicitação de classificação de vários slots.

Este guia de início rápido tem recursos de contexto simples de hora do dia e dispositivo do usuário. Em sistemas de produção, determinar e avaliar ações e características pode ser uma questão não trivial.

let multiSlotRankRequest = {};

// Generate an ID to associate with the request.
multiSlotRankRequest.eventId = uuidv4();

// Get context information from the user.
multiSlotRankRequest.contextFeatures = getContextFeatures();

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

// Get the list of slots for which Personalizer will pick the best action.
multiSlotRankRequest.slots = getSlots();

multiSlotRankRequest.deferActivation = false;

//Rank the actions for each slot
try {
    let multiSlotRankResponse = await sendMultiSlotRank(multiSlotRankRequest);
}
catch (err) {
    console.log(err);
    throw err;
}

Envie uma recompensa

Para obter a pontuação de recompensa para a solicitação de recompensa, o programa obtém a seleção do usuário para cada slot através da linha de comando, atribui um valor numérico (pontuação de recompensa) à seleção e, em seguida, envia o ID de evento exclusivo, o ID do slot e a pontuação de recompensa para cada slot para o sendMultiSlotReward método. Não é necessário definir uma recompensa para cada slot.

Este guia de início rápido atribui um número simples como uma pontuação de recompensa, seja 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 de suas necessidades específicas.

let multiSlotrewards = {};
multiSlotrewards.reward = [];

for (i = 0; i < multiSlotRankResponse.slots.length; i++) {
    console.log('\nPersonalizer service decided you should display: '.concat(multiSlotRankResponse.slots[i].rewardActionId, ' in slot ', multiSlotRankResponse.slots[i].id, '\n'));

    let slotReward = {};
    slotReward.slotId = multiSlotRankResponse.slots[i].id;
    // User agrees or disagrees with Personalizer decision for slot
    slotReward.value = getRewardForSlot();
    multiSlotrewards.reward.push(slotReward);
}

// Send the rewards for the event
await sendMultiSlotReward(multiSlotrewards, multiSlotRankResponse.eventId);

Execute o programa

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

node sample.js

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

Amostras conceituais | de vários slots

Pré-requisitos

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

Configuração

Atualizar instância do Personalizer para Multi-Slot

1. Desativar a Otimização Automática No portal do Azure, no recurso Personalizador, em Gestão de Recursos, na página Modelo e definições de aprendizagem, desative a Otimização Automática e guarde.

2. Atualizar o Personalizer para vários slots No portal do Azure, no recurso Personalizador, em Gerenciamento de Recursos, na página Configurações de modelo e aprendizagem , selecione Exportar configurações de aprendizagem. O campo de argumentos no arquivo json baixado começará com --cb_explore_adf. Altere para --ccb_explore_adf e salve o arquivo. CB (bandidos contextuais) e CCB (bandidos contextuais condicionais) são os algoritmos que o Personalizer usa para personalização de slot único e multislot, respectivamente. ADF (action dependent features) significa que as ações são expressas/identificadas com características.

Na mesma guia no portal, em importar configurações de aprendizagem, procure para encontrar seu arquivo json modificado recentemente e carregue-o. Isso atualizará sua instância do Personalizer para ser um Personalizador "Multi Slot" e agora suportará chamadas de Rank e Reward com vários slots.

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

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

Alterar o tempo de espera da recompensa

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

Criar uma aplicação Python nova

Crie um novo arquivo Python e crie variáveis para o ponto de extremidade e a chave de assinatura do seu recurso.

import json, uuid, requests

# The endpoint specific to your personalization service instance; 
# e.g. https://<your-resource-name>.cognitiveservices.azure.com
PERSONALIZATION_BASE_URL = "<REPLACE-WITH-YOUR-PERSONALIZER-ENDPOINT>"
# The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF"
RESOURCE_KEY = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>"

Modelo de objeto

Para pedir o melhor item do conteúdo para cada slot, crie um rank_request e, em seguida, envie uma solicitação de postagem para multislot/rank. A resposta é então analisada em um rank_response.

Para enviar uma pontuação de recompensa para o Personalizador, crie uma recompensa e, em seguida, envie uma solicitação de publicação para multislot/events/{eventId}/reward.

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

Exemplos de código

Esses trechos de código mostram como executar as seguintes tarefas enviando solicitações HTTP para Python:

• Criar URLs base
• Rank API
• API de recompensa

Criar URLs base

Nesta seção, você construirá as URLs de Classificação/Recompensa usando a URL base e os cabeçalhos de solicitação usando a chave de recurso.

MULTI_SLOT_RANK_URL = '{0}personalizer/v1.1-preview.1/multislot/rank'.format(PERSONALIZATION_BASE_URL)
MULTI_SLOT_REWARD_URL_BASE = '{0}personalizer/v1.1-preview.1/multislot/events/'.format(PERSONALIZATION_BASE_URL)
HEADERS = {
    'ocp-apim-subscription-key': RESOURCE_KEY,
    'Content-Type': 'application/json'
}

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

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

def get_actions():
    return [
        {
            "id": "Red-Polo-Shirt-432",
            "features": [
                {
                    "onSale": "true",
                    "price": 20,
                    "category": "Clothing"
                }
            ]
        },
        {
            "id": "Tennis-Racket-133",
            "features": [
                {
                    "onSale": "false",
                    "price": 70,
                    "category": "Sports"
                }
            ]
        },
        {
            "id": "31-Inch-Monitor-771",
            "features": [
                {
                    "onSale": "true",
                    "price": 200,
                    "category": "Electronics"
                }
            ]
        },
        {
            "id": "XBox-Series X-117",
            "features": [
                {
                    "onSale": "false",
                    "price": 499,
                    "category": "Electronics"
                }
            ]
        }
    ]

Obter preferências do usuário para contexto

Adicione os seguintes métodos ao script para obter a entrada de um usuário da linha de comando para a hora do dia e o tipo de dispositivo em que o usuário está. Estes serão usados como recursos de contexto.

def get_context_features():
    time_features = ["morning", "afternoon", "evening", "night"]
    time_pref = input("What time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night\n")
    try:
        parsed_time = int(time_pref)
        if(parsed_time <=0 or parsed_time > len(time_features)):
            raise IndexError
        time_of_day = time_features[parsed_time-1]
    except (ValueError, IndexError):
        print("Entered value is invalid. Setting feature value to", time_features[0] + ".")
        time_of_day = time_features[0]

    device_features = ['mobile', 'tablet', 'desktop']
    device_pref = input("What type of device is the user on (enter number)? 1. mobile 2. tablet 3. desktop\n")
    try:
        parsed_device = int(device_pref)
        if(parsed_device <=0 or parsed_device > len(device_features)):
            raise IndexError
        device = device_features[parsed_device-1]
    except (ValueError, IndexError):
        print("Entered value is invalid. Setting feature value to", device_features[0]+ ".")
        device = device_features[0]

    return [
        {'time': time_of_day},
        {'device': device}
        ]

Obter slots

Os slots compõem a página com a qual o usuário irá interagir. O personalizador decidirá qual ação exibir em cada um dos slots definidos. As ações podem ser excluídas de slots específicos, mostradas como ExcludeActions. BaselineAction é a ação padrão para o slot que teria sido exibido sem o uso do Personalizador.

Este guia de início rápido tem recursos de slot simples. Em sistemas de produção, determinar e avaliar características pode ser uma questão não trivial.

def get_slots():
    return [
        {
            "id": "BigHeroPosition",
            "features": [
                {
                    "size": "large",
                    "position": "left",
                }
            ],
            "excludedActions": ["31-Inch-Monitor-771"],
            "baselineAction": "Red-Polo-Shirt-432"
        },
        {
            "id": "SmallSidebar",
            "features": [
                {
                    "size": "small",
                    "position": "right",
                }
            ],
            "excludedActions": ["Tennis-Racket-133"],
            "baselineAction": "XBox-Series X-117"
        }
    ]

Fazer solicitações HTTP

Adicione essas funções para enviar solicitações de postagem para o ponto de extremidade do Personalizador para chamadas de classificação e recompensa com vários slots.

def send_multi_slot_rank(rank_request):
multi_slot_response = requests.post(MULTI_SLOT_RANK_URL, data=json.dumps(rank_request), headers=HEADERS)
if multi_slot_response.status_code != 201:
    raise Exception(multi_slot_response.text)
return json.loads(multi_slot_response.text)

def send_multi_slot_reward(reward_request, event_id):
    reward_url = '{0}{1}/reward'.format(MULTI_SLOT_REWARD_URL_BASE, event_id)
    requests.post(reward_url, data=json.dumps(reward_request), headers=HEADERS)

Obter feedback sobre as decisões do Personalizador

Adicione o seguinte método ao script. Você sinalizará se o Personalizer tomou uma boa decisão para cada slot através do prompt de linha de comando.

def get_reward_for_slot():
    answer = input('\nIs this correct? (y/n)\n').upper()
    if (answer == 'Y'):
        print('\nGreat! The application will send Personalizer a reward of 1 so it learns from this choice of action for this slot.\n')
        return 1
    elif (answer == 'N'):
        print('\nYou didn\'t like the recommended item.The application will send Personalizer a reward of 0 for this choice of action for this slot.\n')
        return 0
    print('\nEntered choice is invalid. Service assumes that you didn\'t like the recommended item.\n')
    return 0

Criar o ciclo de aprendizagem

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

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

run_loop = True

while run_loop:

    eventId = str(uuid.uuid4())
    context = get_context_features()
    actions = get_actions()
    slots = get_slots()

    rank_request = {
        "eventId": eventId,
        "contextFeatures": context,
        "actions": actions,
        "slots": slots,
        "deferActivation": False
      }

    #Rank the actions for each slot
    multi_slot_rank_response = send_multi_slot_rank(rank_request)
    multi_slot_rewards = {"reward": []}

    for i in range(len(multi_slot_rank_response['slots'])):
        print('\nPersonalizer service decided you should display: {0} in slot {1}\n'.format(multi_slot_rank_response['slots'][i]['rewardActionId'], multi_slot_rank_response['slots'][i]['id']))

        slot_reward = {'slotId': multi_slot_rank_response['slots'][i]['id']}
        # User agrees or disagrees with Personalizer decision for slot
        slot_reward['value'] = get_reward_for_slot()
        multi_slot_rewards['reward'].append(slot_reward)

    # Send the rewards for the event
    send_multi_slot_reward(multi_slot_rewards, multi_slot_rank_response['eventId'])

    answer = input('\nPress q to break, any other key to continue:\n').upper()
    if (answer == 'Q'):
        run_loop = False

Dê uma olhada mais de perto nas chamadas de classificação e recompensa nas seções a seguir.

Adicione os seguintes métodos, que obtêm as opções de conteúdo, obtêm as preferências do usuário para o contexto, obtêm os slots, fazem solicitações HTTP, obtêm recompensa por cada slot antes de executar o arquivo de código:

• get_actions
• get_context_features
• get_slots
• send_rank
• send_reward
• get_reward_for_dsot

Solicite a melhor ação

Para completar a solicitação de classificação, o programa solicita as preferências do usuário para criar opções de conteúdo. O corpo da solicitação contém o contexto, as ações e os slots com seus respetivos recursos. O send_multi_slot_rank método recebe um rankRequest e executa a solicitação de classificação de vários slots.

Este guia de início rápido tem recursos de contexto simples de hora do dia e dispositivo do usuário. Em sistemas de produção, determinar e avaliar ações e características pode ser uma questão não trivial.

eventId = str(uuid.uuid4())
context = get_context_features()
actions = get_actions()
slots = get_slots()

rank_request = {
    "eventId": eventId,
    "contextFeatures": context,
    "actions": actions,
    "slots": slots,
    "deferActivation": False
    }

#Rank the actions for each slot
multi_slot_rank_response = send_multi_slot_rank(rank_request)

Envie uma recompensa

Para obter a pontuação de recompensa para a solicitação de recompensa, o programa obtém a seleção do usuário para cada slot através da linha de comando, atribui um valor numérico (pontuação de recompensa) à seleção e, em seguida, envia o ID de evento exclusivo, o ID do slot e a pontuação de recompensa para cada slot para o send_multi_slot_reward método. Não é necessário definir uma recompensa para cada slot.

Este guia de início rápido atribui um número simples como uma pontuação de recompensa, seja 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 de suas necessidades específicas.

multi_slot_rewards = {"reward": []}

for i in range(len(multi_slot_rank_response['slots'])):
    print('\nPersonalizer service decided you should display: {0} in slot {1}\n'.format(multi_slot_rank_response['slots'][i]['rewardActionId'], multi_slot_rank_response['slots'][i]['id']))

    slot_reward = {'slotId': multi_slot_rank_response['slots'][i]['id']}
    # User agrees or disagrees with Personalizer decision for slot
    slot_reward['value'] = get_reward_for_slot()
    multi_slot_rewards['reward'].append(slot_reward)

# Send the rewards for the event
send_multi_slot_reward(multi_slot_rewards, multi_slot_rank_response['eventId'])

Execute o programa

Execute o aplicativo com o Python a partir do diretório do aplicativo.

python sample.py

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