Introdução ao multislot para o Azure AI Personalizer
Importante
A partir de 20 de setembro de 2023, você não poderá criar novos recursos do Personalizador. O serviço de Personalizador será aposentado no dia 1º de outubro de 2026.
A personalização de vários slots (Visualização) permite segmentar conteúdo em layouts da Web, carrosséis e listas onde mais de uma ação (como um produto ou parte do conteúdo) é mostrada aos usuários. Com as APIs de vários slots do Personalizer, você pode fazer com que os modelos de IA no Personalizer aprendam quais contextos de usuário e produtos impulsionam determinados comportamentos, considerando e aprendendo com o posicionamento em sua interface de usuário. Por exemplo, o Personalizador pode aprender que determinados produtos ou conteúdo geram mais cliques como barra lateral ou rodapé do que como destaque principal em uma página.
Neste guia, você aprenderá a usar as APIs de vários slots do 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
Nota
A personalização de vários slots (Visualização) afeta outras funcionalidades do serviço Personalizador. Esta alteração não pode ser desfeita. Antes de ativar a personalização de vários slots, consulte Personalização de vários slots (Pré-visualização).
- 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.
Nota
A personalização de vários slots não funcionará a menos que você desative a Otimização automática. A otimização automática para personalização de vários slots será suportada no futuro.
- 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:
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.
Importante
Aceda ao portal do Azure. Se o recurso Personalizador criado na seção Pré-requisitos for implantado com êxito, clique no botão Ir para Recurso em Próximas etapas. Você pode encontrar sua chave e ponto de extremidade na página de chave e ponto de extremidade do recurso, em Gerenciamento de recursos.
Lembre-se de remover a chave do seu código quando terminar e nunca publicá-la publicamente. Para produção, considere usar uma maneira segura de armazenar e acessar suas credenciais. Por exemplo, o cofre de chaves do Azure.
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:
GetActionsGetSlotsGetTimeOfDayForContextGetDeviceForContextGetKeyGetContext
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
Nota
A personalização de vários slots (Visualização) afeta outras funcionalidades do serviço Personalizador. Esta alteração não pode ser desfeita. Antes de ativar a personalização de vários slots, consulte Personalização de vários slots (Pré-visualização).
- 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.
Nota
A personalização de vários slots não funcionará a menos que você desative a Otimização automática. A otimização automática para personalização de vários slots será suportada no futuro.
- 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.
Importante
Aceda ao portal do Azure. Se o recurso Personalizador criado na seção Pré-requisitos for implantado com êxito, clique no botão Ir para Recurso em Próximas etapas. Você pode encontrar sua chave e ponto de extremidade na página de chave e ponto de extremidade do recurso, em Gerenciamento de recursos.
Lembre-se de remover a chave do seu código quando terminar e nunca publicá-la publicamente. Para produção, considere usar uma maneira segura de armazenar e acessar suas credenciais. Por exemplo, o cofre de chaves do Azure.
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
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
Nota
A personalização de vários slots (Visualização) afeta outras funcionalidades do serviço Personalizador. Esta alteração não pode ser desfeita. Antes de ativar a personalização de vários slots, consulte Personalização de vários slots (Pré-visualização).
- 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.
Nota
A personalização de vários slots não funcionará a menos que você desative a Otimização automática. A otimização automática para personalização de vários slots será suportada no futuro.
- 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.
Importante
Aceda ao portal do Azure. Se o recurso Personalizador criado na seção Pré-requisitos for implantado com êxito, clique no botão Ir para Recurso em Próximas etapas. Você pode encontrar sua chave e ponto de extremidade na página de chave e ponto de extremidade do recurso, em Gerenciamento de recursos.
Lembre-se de remover a chave do seu código quando terminar e nunca publicá-la publicamente. Para produção, considere usar uma maneira segura de armazenar e acessar suas credenciais. Por exemplo, o cofre de chaves do Azure.
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
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.