Kom igång med flera platser för Azure AI Personalizer
Viktigt!
Från och med den 20 september 2023 kommer du inte att kunna skapa nya personaliseringsresurser. Personanpassningstjänsten dras tillbaka den 1 oktober 2026.
Med anpassning av flera platser (förhandsversion) kan du rikta innehåll i webblayouter, karuseller och listor där fler än en åtgärd (till exempel en produkt eller innehåll) visas för dina användare. Med Personanpassnings-API:er för flera platser kan du låta AI-modellerna i Personalizer lära dig vilka användarkontexter och produkter som driver vissa beteenden, överväger och lär dig av placeringen i användargränssnittet. Personanpassning kan till exempel lära sig att vissa produkter eller innehåll gör fler klick som sidofält eller sidfot än som en huvudmarkering på en sida.
I den här guiden får du lära dig hur du använder API:erna för personanpassning med flera platser.
Referensdokumentation Bibliotek källkodspaket | (NuGet) | Konceptexempel | för flera platser |
Förutsättningar
- Azure-prenumeration – Skapa en kostnadsfritt
- Den aktuella versionen av .NET Core.
- När du har din Azure-prenumeration skapar du en Personalizer-resurs i Azure-portalen för att hämta din nyckel och slutpunkt. När den har distribuerats väljer du Gå till resurs.
- Du behöver nyckeln och slutpunkten från resursen som du skapar för att ansluta ditt program till Personanpassnings-API:et. Klistra in din nyckel och slutpunkt i koden nedan senare i snabbstarten.
- Du kan använda den kostnadsfria prisnivån (
F0) för att prova tjänsten och uppgradera senare till en betald nivå för produktion.
Konfigurera
Uppgradera Personalizer-instansen till Multi-Slot
Kommentar
Anpassning av flera platser (förhandsversion) påverkar andra funktioner i personanpassningstjänsten. Det går inte att ångra den här ändringen. Innan du aktiverar anpassning av flera platser kan du läsa Mer information om anpassning av flera platser (förhandsversion).)
- Inaktivera Automatisk optimering I Azure-portalen går du till Personalizer-resursen under Resurshantering på sidan Modell- och inlärningsinställningar och inaktiverar automatisk optimering och sparar.
Kommentar
Anpassning med flera platser fungerar inte om du inte inaktiverar automatisk optimering. Automatisk optimering för anpassning av flera platser kommer att stödjas i framtiden.
- Uppdatera Personanpassning till flera platser I Azure-portalen går du till Personalizer-resursen och går till Resurshantering och väljer Exportera utbildningsinställningar på sidan Modell- och inlärningsinställningar. Argumentfältet i den nedladdade json-filen börjar med --cb_explore_adf. Ändra detta till --ccb_explore_adf och spara filen. CB (kontextuella banditer) och CCB (villkorliga kontextbaserade banditer) är de algoritmer som Personanpassning använder för personanpassning med en eller flera platser. ADF (åtgärdsberoende funktioner) innebär att åtgärderna uttrycks/identifieras med funktioner.
På samma flik i portalen bläddrar du under importinlärningsinställningar för att hitta din nyligen ändrade json-fil och ladda upp den. Detta uppdaterar din personanpassningsinstans så att den blir en "Multi Slot"-personanpassning och stöder nu ranknings- och belöningssamtal med flera platser.
Ändra uppdateringsfrekvensen för modellen
I Azure-portalen går du till personaliserarresursens konfigurationssida och ändrar uppdateringsfrekvensen för modell till 30 sekunder. Den här korta varaktigheten tränar modellen snabbt, så att du kan se hur den rekommenderade åtgärden ändras för varje iteration.
Ändra väntetiden för belöningen
I Azure-portalen går du till personaliserarresursens konfigurationssida och ändrar väntetiden för belöningen till 10 minuter. Detta avgör hur länge modellen väntar efter att ha skickat en rekommendation för att få belöningsfeedback från den rekommendationen. Träningen sker inte förrän belöningens väntetid har passerat.
Skapa ett nytt C#-program
Skapa ett nytt .NET Core-program i önskad redigerare eller IDE.
I ett konsolfönster (till exempel cmd, PowerShell eller Bash) använder du dotnet-kommandot new för att skapa en ny konsolapp med namnet personalizer-quickstart. Det här kommandot skapar ett enkelt "Hello World"-C#-projekt med en enda källfil: Program.cs.
dotnet new console -n personalizer-quickstart
Ändra katalogen till den nyligen skapade appmappen. Du kan skapa programmet med:
dotnet build
Kompileringsutdata får inte innehålla några varningar eller fel.
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
Installera klientbiblioteket
I programkatalogen installerar du Personalizer-klientbiblioteket för .NET med följande kommando:
dotnet add package Azure.AI.Personalizer --version 2.0.0-beta.2
Öppna filen i önskad redigerare eller IDE från projektkatalogen Program.cs . Lägg till följande med hjälp av direktiv:
using System;
using Azure;
using Azure.AI.Personalizer;
using System.Collections.Generic;
using System.Linq;
Objektmodell
Personanpassningsklienten är ett PersonalizerClient-objekt som autentiserar till Azure med hjälp av Azure.AzureKeyCredential, som innehåller din nyckel.
Om du vill be om det enskilt bästa objektet i innehållet för varje fack skapar du ett PersonalizerRankMultiSlotOptions-objekt och skickar det sedan till PersonalizerClient.RankMultiSlot. Metoden RankMultiSlot returnerar en PersonalizerMultiSlotRankResult.
Om du vill skicka en belöningspoäng till Personanpassning skapar du en PersonalizerRewardMultiSlotOptions och skickar den sedan till metoden PersonalizerClient.RewardMultiSlot tillsammans med motsvarande händelse-ID.
Belöningspoängen i den här snabbstarten är trivial. I ett produktionssystem kan du bestämma vad som påverkar belöningspoängen och hur mycket som kan vara en komplex process, som du kan besluta att ändra över tid. Det här designbeslutet bör vara ett av de viktigaste besluten i din personanpassningsarkitektur.
Kodexempel
De här kodfragmenten visar hur du utför följande uppgifter med Personalizer-klientbiblioteket för .NET:
Autentisera klienten
I det här avsnittet gör du två saker:
- Ange din nyckel och slutpunkt
- Skapa en personanpassningsklient
Börja med att lägga till följande rader i klassen Program. Se till att lägga till din nyckel och slutpunkt från personaliserarresursen.
Viktigt!
Gå till Azure-portalen. Om personanpassningsresursen som du skapade i avsnittet Förutsättningar har distribuerats klickar du på knappen Gå till resurs under Nästa steg. Du hittar din nyckel och slutpunkt på resursens nyckel- och slutpunktssida under resurshantering.
Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion bör du överväga att använda ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter. Till exempel Azure Key Vault.
private const string ServiceEndpoint = "https://REPLACE-WITH-YOUR-PERSONALIZER-RESOURCE-NAME.cognitiveservices.azure.com";
private const string ResourceKey = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>";
Skapa sedan URL:erna Rank och Reward.
static PersonalizerClient InitializePersonalizerClient(Uri url)
{
return new PersonalizerClient(url, new AzureKeyCredential(ResourceKey));
}
Hämta innehållsval som representeras som åtgärder
Åtgärder representerar de innehållsval som du vill att Personanpassning ska välja det bästa innehållsobjektet från. Lägg till följande metoder i klassen Program för att representera uppsättningen med åtgärder och deras funktioner.
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;
}
Hämta fack
Facken utgör sidan som användaren ska interagera med. Personanpassningen bestämmer vilken åtgärd som ska visas i var och en av de definierade platserna. Åtgärder kan undantas från specifika platser, som visas som ExcludeActions. BaselineAction är standardåtgärden för facket, som skulle ha visats utan att personanpassning används.
Den här snabbstarten har enkla fackfunktioner. I produktionssystem kan det vara en icke-trivial sak attfastställa och utvärdera funktioner.
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;
}
Hämta användarinställningar för kontext
Lägg till följande metoder i klassen Program för att hämta en användares indata från kommandoraden för tid på dagen och vilken typ av enhet användaren är på. Dessa metoder kommer att användas som kontextfunktioner.
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];
}
Båda metoderna använder GetKey metoden för att läsa användarens val från kommandoraden.
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 }
};
}
Skapa inlärningsloopen
Personalizer-inlärningsloopen är en cykel med RankMultiSlot - och RewardMultiSlot-anrop . I den här snabbstarten följs varje Rank-anrop, för att anpassa innehållet, av ett Reward-anrop för att berätta för Personanpassning hur väl tjänsten har utförts.
Följande kod loopar igenom en cykel där användaren uppmanas sina inställningar via kommandoraden, skickar informationen till Personanpassning för att välja den bästa åtgärden för varje fack, presenterar valet för kunden att välja bland listan och skickar sedan en belöningspoäng till Personanpassning som signalerar hur bra tjänsten gjorde i sitt val.
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);
}
Ta en närmare titt på ranknings- och belöningssamtalen i följande avsnitt. Lägg till följande metoder som hämtar innehållsval, hämtar platser och skickar ranknings- och belöningsbegäranden för flera platser innan du kör kodfilen:
GetActionsGetSlotsGetTimeOfDayForContextGetDeviceForContextGetKeyGetContext
Begär den bästa åtgärden
För att slutföra rankningsbegäran ber programmet användarens inställningar att skapa en Context av innehållsvalen. Begäran innehåller kontext, åtgärder och platser med respektive funktioner och ett unikt händelse-ID för att få ett svar.
Den här snabbstarten har enkla kontextfunktioner för tid på dagen och användarenheter. I produktionssystem kan det vara en icke-trivial sak attfastställa och utvärdera åtgärder och funktioner.
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);
Skicka en belöning
För att få belöningspoängen för reward-begäran hämtar programmet användarens val för varje fack via kommandoraden, tilldelar ett numeriskt värde (belöningspoäng) till valet och skickar sedan det unika händelse-ID:t, slot-ID:t och belöningspoängen för varje fack som det numeriska värdet till Reward API. En belöning behöver inte definieras för varje fack.
Den här snabbstarten tilldelar ett enkelt tal som belöningspoäng, antingen en nolla eller en 1. I produktionssystem kan det vara en icke-trivial fråga att avgöra när och vad du ska skicka till Reward-anropet , beroende på dina specifika behov.
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.");
}
}
Köra programmet
Kör programmet med dotnet-kommandot run från programkatalogen.
dotnet run
Källkoden för den här snabbstarten är tillgänglig.
Referensdokumentation Konceptexempel | för flera platser |
Förutsättningar
- Azure-prenumeration – Skapa en kostnadsfritt
- Installera Node.js och NPM (verifierat med Node.js v14.16.0 och NPM 6.14.11).
- När du har din Azure-prenumeration skapar du en Personalizer-resurs i Azure-portalen för att hämta din nyckel och slutpunkt. När den har distribuerats väljer du Gå till resurs.
- Du behöver nyckeln och slutpunkten från den resurs som du skapar för att ansluta ditt program till Personanpassnings-API:et. Klistra in din nyckel och slutpunkt i koden nedan senare i snabbstarten.
- Du kan använda den kostnadsfria prisnivån (
F0) för att prova tjänsten och uppgradera senare till en betald nivå för produktion.
Konfigurera
Uppgradera Personalizer-instansen till Multi-Slot
Kommentar
Anpassning av flera platser (förhandsversion) påverkar andra funktioner i personanpassningstjänsten. Det går inte att ångra den här ändringen. Innan du aktiverar anpassning av flera platser kan du läsa Mer information om anpassning av flera platser (förhandsversion).)
- Inaktivera Automatisk optimering I Azure-portalen går du till Personalizer-resursen under Resurshantering på sidan Modell- och inlärningsinställningar och inaktiverar automatisk optimering och sparar.
Kommentar
Anpassning med flera platser fungerar inte om du inte inaktiverar automatisk optimering. Automatisk optimering för anpassning av flera platser kommer att stödjas i framtiden.
- Uppdatera Personanpassning till flera platser I Azure-portalen går du till Personalizer-resursen och går till Resurshantering och väljer Exportera utbildningsinställningar på sidan Modell- och inlärningsinställningar. Argumentfältet i den nedladdade json-filen börjar med --cb_explore_adf. Ändra detta till --ccb_explore_adf och spara filen. CB (kontextuella banditer) och CCB (villkorliga kontextbaserade banditer) är de algoritmer som Personanpassning använder för personanpassning med en eller flera platser. ADF (åtgärdsberoende funktioner) innebär att åtgärderna uttrycks/identifieras med funktioner.
På samma flik i portalen bläddrar du under importinlärningsinställningar för att hitta din nyligen ändrade json-fil och ladda upp den. Detta uppdaterar din personanpassningsinstans så att den blir en "Multi Slot"-personanpassning och stöder nu ranknings- och belöningssamtal med flera platser.
Ändra uppdateringsfrekvensen för modellen
I Azure-portalen går du till personaliserarresursens konfigurationssida och ändrar uppdateringsfrekvensen för modell till 30 sekunder. Den här korta varaktigheten tränar modellen snabbt, så att du kan se hur den rekommenderade åtgärden ändras för varje iteration.
Ändra väntetiden för belöningen
I Azure-portalen går du till personaliserarresursens konfigurationssida och ändrar väntetiden för belöningen till 10 minuter. Detta avgör hur länge modellen väntar efter att ha skickat en rekommendation för att få belöningsfeedback från den rekommendationen. Träningen sker inte förrän belöningens väntetid har passerat.
Skapa ett nytt Node.js-program
Skapa en ny katalog för din app i ett konsolfönster (till exempel cmd, PowerShell eller bash) och navigera till den.
mkdir myapp && cd myapp
npm init -y Kör kommandot för att skapa en package.json fil.
npm init -y
Skapa ett nytt Node.js-program i önskad redigerare eller IDE med namnet sample.js och skapa variabler för resursens slutpunkt och prenumerationsnyckel.
Viktigt!
Gå till Azure-portalen. Om personanpassningsresursen som du skapade i avsnittet Förutsättningar har distribuerats klickar du på knappen Gå till resurs under Nästa steg. Du hittar din nyckel och slutpunkt på resursens nyckel- och slutpunktssida under resurshantering.
Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion bör du överväga att använda ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter. Till exempel Azure Key Vault.
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>';
Installera NPM-paketen för snabbstart
npm install readline-sync uuid axios --save
Objektmodell
Om du vill be om det enskilt bästa objektet i innehållet för varje fack skapar du en rankRequest och skickar sedan en postbegäran till multislot/rank. Svaret parsas sedan till en rankResponse.
Om du vill skicka en belöningspoäng till Personanpassning skapar du en belöning och skickar sedan en postbegäran till multislot/events/{eventId}/reward.
Att fastställa belöningspoängen i den här snabbstarten är trivialt. I ett produktionssystem kan du bestämma vad som påverkar belöningspoängen och hur mycket som kan vara en komplex process, som du kan besluta att ändra över tid. Det här designbeslutet bör vara ett av de viktigaste besluten i din personanpassningsarkitektur.
Kodexempel
De här kodfragmenten visar hur du utför följande uppgifter genom att skicka HTTP-begäranden för NodeJS:
Skapa bas-URL:er
I det här avsnittet konstruerar du URL:er för rankning/belöning med hjälp av bas-URL:en och begärandehuvudena med hjälp av resursnyckeln.
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'
};
Hämta innehållsval som representeras som åtgärder
Åtgärder representerar de innehållsval som du vill att Personanpassning ska välja det bästa innehållsobjektet från. Lägg till följande metoder i skriptet för att representera uppsättningen åtgärder och deras funktioner.
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'
}
]
}
];
}
Hämta användarinställningar för kontext
Lägg till följande metoder i skriptet för att hämta en användares indata från kommandoraden för tiden på dagen och vilken typ av enhet användaren är på. Dessa används som kontextfunktioner.
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
}
];
}
Hämta fack
Facken utgör sidan som användaren ska interagera med. Personanpassningen bestämmer vilken åtgärd som ska visas i var och en av de definierade platserna. Åtgärder kan undantas från specifika platser, som visas som ExcludeActions. BaselineAction är standardåtgärden för facket som skulle ha visats utan att personanpassning används.
Den här snabbstarten har enkla fackfunktioner. I produktionssystem kan det vara en icke-trivial sak attfastställa och utvärdera funktioner.
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'
}
];
}
Skapa HTTP-begäranden
Lägg till dessa funktioner för att skicka postbegäranden till personaliserarens slutpunkt för ranknings- och belöningssamtal med flera platser.
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;
}
}
Få feedback om personanpassningsbeslut
Lägg till följande metod i skriptet. Du kommer att signalera om Personanpassning har fattat ett bra beslut för varje fack via kommandotolken.
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;
}
Skapa inlärningsloopen
Personalizer-inlärningsloopen är en cykel med ranknings- och belöningsanrop . I den här snabbstarten följs varje Rank-anrop, för att anpassa innehållet, av ett Reward-anrop för att berätta för Personanpassning hur väl tjänsten har utförts.
Följande kod loopar igenom en cykel där användaren uppmanas sina inställningar via kommandoraden, skickar informationen till Personanpassning för att välja den bästa åtgärden för varje fack, presenterar valet för kunden att välja bland listan och skickar sedan en belöningspoäng till Personanpassning som signalerar hur bra tjänsten gjorde i sitt val.
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);
})()
Ta en närmare titt på ranknings- och belöningssamtalen i följande avsnitt.
Lägg till följande metoder, som hämtar innehållsvalen, hämtar användarinställningar för kontext, hämtar facken, Gör HTTP-begäranden, Få belöning för varje fack innan du kör kodfilen:
- getActions
- getContextFeatures
- getSlots
- sendRank
- sendReward
- getRewardForSlot
Begär den bästa åtgärden
För att slutföra rankningsbegäran ber programmet användarens inställningar att skapa innehållsval. Begärandetexten innehåller kontext, åtgärder och platser med respektive funktion. Metoden sendMultiSlotRank tar in en rankRequest och kör rangordningsbegäran för flera platser.
Den här snabbstarten har enkla kontextfunktioner för tid på dagen och användarenheter. I produktionssystem kan det vara en icke-trivial sak attfastställa och utvärdera åtgärder och funktioner.
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;
}
Skicka en belöning
För att få belöningspoängen för reward-begäran hämtar programmet användarens val för varje fack via kommandoraden, tilldelar ett numeriskt värde (belöningspoäng) till valet och skickar sedan det unika händelse-ID:t, slot-ID:t och belöningspoängen för varje fack till sendMultiSlotReward metoden. En belöning behöver inte definieras för varje fack.
Den här snabbstarten tilldelar ett enkelt tal som belöningspoäng, antingen en nolla eller en 1. I produktionssystem kan det vara en icke-trivial fråga att avgöra när och vad du ska skicka till Reward-anropet , beroende på dina specifika behov.
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);
Köra programmet
Kör programmet med Node.js från programkatalogen.
node sample.js
Källkoden för den här snabbstarten är tillgänglig.
Konceptexempel | för flera platser
Förutsättningar
- Azure-prenumeration – Skapa en kostnadsfritt
- Python 3.x
- När du har din Azure-prenumeration skapar du en Personalizer-resurs i Azure-portalen för att hämta din nyckel och slutpunkt. När den har distribuerats väljer du Gå till resurs.
- Du behöver nyckeln och slutpunkten från den resurs som du skapar för att ansluta ditt program till Personanpassnings-API:et. Klistra in din nyckel och slutpunkt i koden nedan senare i snabbstarten.
- Du kan använda den kostnadsfria prisnivån (
F0) för att prova tjänsten och uppgradera senare till en betald nivå för produktion.
Konfigurera
Uppgradera Personalizer-instansen till Multi-Slot
Kommentar
Anpassning av flera platser (förhandsversion) påverkar andra funktioner i personanpassningstjänsten. Det går inte att ångra den här ändringen. Innan du aktiverar anpassning av flera platser kan du läsa Mer information om anpassning av flera platser (förhandsversion).)
- Inaktivera Automatisk optimering I Azure-portalen går du till Personalizer-resursen under Resurshantering på sidan Modell- och inlärningsinställningar och inaktiverar automatisk optimering och sparar.
Kommentar
Anpassning med flera platser fungerar inte om du inte inaktiverar automatisk optimering. Automatisk optimering för anpassning av flera platser kommer att stödjas i framtiden.
- Uppdatera Personanpassning till flera platser I Azure-portalen går du till Personalizer-resursen och går till Resurshantering och väljer Exportera utbildningsinställningar på sidan Modell- och inlärningsinställningar. Argumentfältet i den nedladdade json-filen börjar med --cb_explore_adf. Ändra detta till --ccb_explore_adf och spara filen. CB (kontextuella banditer) och CCB (villkorliga kontextbaserade banditer) är de algoritmer som Personanpassning använder för personanpassning med en eller flera platser. ADF (åtgärdsberoende funktioner) innebär att åtgärderna uttrycks/identifieras med funktioner.
På samma flik i portalen bläddrar du under importinlärningsinställningar för att hitta din nyligen ändrade json-fil och ladda upp den. Detta uppdaterar din personanpassningsinstans så att den blir en "Multi Slot"-personanpassning och stöder nu ranknings- och belöningssamtal med flera platser.
Ändra uppdateringsfrekvensen för modellen
I Azure-portalen går du till personaliserarresursens konfigurationssida och ändrar uppdateringsfrekvensen för modell till 30 sekunder. Den här korta varaktigheten tränar modellen snabbt, så att du kan se hur den rekommenderade åtgärden ändras för varje iteration.
Ändra väntetiden för belöningen
I Azure-portalen går du till personaliserarresursens konfigurationssida och ändrar väntetiden för belöningen till 10 minuter. Detta avgör hur länge modellen väntar efter att ha skickat en rekommendation för att få belöningsfeedback från den rekommendationen. Träningen sker inte förrän belöningens väntetid har passerat.
Skapa ett nytt Python-program
Skapa en ny Python-fil och skapa variabler för resursens slutpunkt och prenumerationsnyckel.
Viktigt!
Gå till Azure-portalen. Om personanpassningsresursen som du skapade i avsnittet Förutsättningar har distribuerats klickar du på knappen Gå till resurs under Nästa steg. Du hittar din nyckel och slutpunkt på resursens nyckel- och slutpunktssida under resurshantering.
Kom ihåg att ta bort nyckeln från koden när du är klar och publicera den aldrig offentligt. För produktion bör du överväga att använda ett säkert sätt att lagra och komma åt dina autentiseringsuppgifter. Till exempel Azure Key Vault.
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>"
Objektmodell
Om du vill be om det enskilt bästa objektet i innehållet för varje fack skapar du en rank_request och skickar sedan en postbegäran till multislot/rank. Svaret parsas sedan till en rank_response.
Om du vill skicka en belöningspoäng till Personanpassning skapar du en belöning och skickar sedan en postbegäran till multislot/events/{eventId}/reward.
I den här snabbstarten är det trivialt att fastställa belöningspoängen. I ett produktionssystem avgör du vad som påverkar belöningspoängen och hur mycket som kan vara en komplex process som du kan besluta att ändra över tid. Det här designbeslutet bör vara ett av de viktigaste besluten i din personanpassningsarkitektur.
Kodexempel
De här kodfragmenten visar hur du utför följande uppgifter genom att skicka HTTP-begäranden för Python:
Skapa bas-URL:er
I det här avsnittet konstruerar du URL:er för rankning/belöning med hjälp av bas-URL:en och begärandehuvudena med hjälp av resursnyckeln.
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'
}
Hämta innehållsval som representeras som åtgärder
Åtgärder representerar de innehållsval som du vill att Personanpassning ska välja det bästa innehållsobjektet från. Lägg till följande metoder i skriptet för att representera uppsättningen åtgärder och deras funktioner.
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"
}
]
}
]
Hämta användarinställningar för kontext
Lägg till följande metoder i skriptet för att hämta en användares indata från kommandoraden för tiden på dagen och vilken typ av enhet användaren är på. Dessa används som kontextfunktioner.
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}
]
Hämta fack
Facken utgör sidan som användaren ska interagera med. Personanpassningen bestämmer vilken åtgärd som ska visas i var och en av de definierade platserna. Åtgärder kan undantas från specifika platser, som visas som ExcludeActions. BaselineAction är standardåtgärden för facket som skulle ha visats utan att personanpassning används.
Den här snabbstarten har enkla fackfunktioner. I produktionssystem kan det vara en icke-trivial sak attfastställa och utvärdera funktioner.
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"
}
]
Skapa HTTP-begäranden
Lägg till dessa funktioner för att skicka postbegäranden till personaliserarens slutpunkt för ranknings- och belöningssamtal med flera platser.
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)
Få feedback om personanpassningsbeslut
Lägg till följande metod i skriptet. Du kommer att signalera om Personanpassning har fattat ett bra beslut för varje fack via kommandotolken.
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
Skapa inlärningsloopen
Personalizer-inlärningsloopen är en cykel med ranknings- och belöningsanrop . I den här snabbstarten följs varje Rank-anrop, för att anpassa innehållet, av ett Reward-anrop för att berätta för Personanpassning hur väl tjänsten har utförts.
Följande kod loopar igenom en cykel där användaren uppmanas sina inställningar via kommandoraden, skickar informationen till Personanpassning för att välja den bästa åtgärden för varje fack, presenterar valet för kunden att välja bland listan och skickar sedan en belöningspoäng till Personanpassning som signalerar hur bra tjänsten gjorde i sitt val.
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
Ta en närmare titt på ranknings- och belöningssamtalen i följande avsnitt.
Lägg till följande metoder, som hämtar innehållsvalen, hämtar användarinställningar för kontext, hämtar facken, Gör HTTP-begäranden, Få belöning för varje fack innan du kör kodfilen:
- get_actions
- get_context_features
- get_slots
- send_rank
- send_reward
- get_reward_for_dsot
Begär den bästa åtgärden
För att slutföra rankningsbegäran ber programmet användarens inställningar att skapa innehållsval. Begärandetexten innehåller kontext, åtgärder och platser med respektive funktion. Metoden send_multi_slot_rank tar in en rankRequest och kör rangordningsbegäran för flera platser.
Den här snabbstarten har enkla kontextfunktioner för tid på dagen och användarenheter. I produktionssystem kan det vara en icke-trivial sak attfastställa och utvärdera åtgärder och funktioner.
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)
Skicka en belöning
För att få belöningspoängen för reward-begäran hämtar programmet användarens val för varje fack via kommandoraden, tilldelar ett numeriskt värde (belöningspoäng) till valet och skickar sedan det unika händelse-ID:t, slot-ID:t och belöningspoängen för varje fack till send_multi_slot_reward metoden. En belöning behöver inte definieras för varje fack.
Den här snabbstarten tilldelar ett enkelt tal som belöningspoäng, antingen en nolla eller en 1. I produktionssystem kan det vara en icke-trivial fråga att avgöra när och vad du ska skicka till Reward-anropet , beroende på dina specifika behov.
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'])
Köra programmet
Kör programmet med Python från programkatalogen.
python sample.py
Källkoden för den här snabbstarten är tillgänglig.