Szybki start: biblioteka klienta usługi Personalizacja
Ważne
Od 20 września 2023 r. nie będzie można tworzyć nowych zasobów usługi Personalizacja. Usługa Personalizacja jest wycofywana 1 października 2026 r.
Rozpocznij pracę z bibliotekami klienta usługi Azure AI Personalizator, aby skonfigurować podstawową pętlę szkoleniową. Pętla szkoleniowa to system podejmowania decyzji i opinii: aplikacja żąda klasyfikacji decyzji z usługi, a następnie używa najlepszego wyboru i oblicza wynik nagrody. Zwraca wynik nagrody do usługi. W czasie usługa Personalizacja używa algorytmów sztucznej inteligencji do podejmowania lepszych decyzji w danym kontekście. Wykonaj następujące kroki, aby skonfigurować przykładową aplikację.
Przykładowy scenariusz
W tym przewodniku Szybki start sprzedawca detaliczny chce zwiększyć przychody, pokazując odpowiednie i spersonalizowane produkty każdemu klientowi na swojej stronie internetowej. Na stronie głównej znajduje się sekcja "Polecane produkty", która wyświetla przygotowany produkt posiłku dla potencjalnych klientów. Sprzedawca internetowy chce określić, jak pokazać właściwy produkt właściwemu klientowi, aby zmaksymalizować prawdopodobieństwo zakupu.
Usługa Personalizacja rozwiązuje ten problem w zautomatyzowany, skalowalny i dostosowywany sposób przy użyciu uczenia wzmacniania. Dowiesz się, jak tworzyć akcje i ich funkcje, funkcje kontekstowe i oceny nagród. Użyjesz biblioteki klienta personalizacji do wykonywania wywołań do interfejsów API rangi i nagrody.
Przykład kodu | źródłowego biblioteki referencyjnej | (NuGet) | .NET
Wymagania wstępne
- Subskrypcja platformy Azure — utwórz bezpłatnie
- Bieżąca wersja platformy .NET Core.
- Po utworzeniu subskrypcji platformy Azure utwórz zasób usługi Personalizacja w witrynie Azure Portal, aby uzyskać klucz i punkt końcowy. Po wdrożeniu wybierz pozycję Przejdź do zasobu.
- Będziesz potrzebować klucza i punktu końcowego z utworzonego zasobu, aby połączyć aplikację z interfejsem API usługi Personalizacja. W dalszej części przewodnika Szybki start wklejesz klucz i punkt końcowy do poniższego kodu.
- Możesz użyć warstwy cenowej bezpłatna (
F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.
Konfiguracja modelu
Zmienianie częstotliwości aktualizacji modelu
W witrynie Azure Portal przejdź do strony Konfiguracja zasobu usługi Personalizacja i zmień częstotliwość aktualizacji modelu na 30 sekund. Ten krótki czas trwania będzie szybko trenował model, co pozwala zobaczyć, jak zmienia się zalecana akcja dla każdej iteracji.
Zmienianie czasu oczekiwania na nagrodę
W witrynie Azure Portal przejdź do strony Konfiguracja zasobu usługi Personalizacja i zmień czas oczekiwania na nagrodę na 10 minut. Określa to, jak długo model będzie czekał po wysłaniu rekomendacji, aby otrzymać opinię na temat nagrody od tego zalecenia. Trenowanie nie nastąpi, dopóki czas oczekiwania na nagrodę nie upłynął.
Tworzenie nowej aplikacji w języku C#
Utwórz nową aplikację platformy .NET Core w preferowanym edytorze lub środowisku IDE.
W oknie konsoli (takim jak cmd, PowerShell lub Bash) użyj dotnet new polecenia , aby utworzyć nową aplikację konsolową o nazwie personalizer-quickstart. To polecenie tworzy prosty projekt języka C# "Hello World" z jednym plikiem źródłowym: Program.cs.
dotnet new console -n personalizer-quickstart
Zmień katalog na nowo utworzony folder aplikacji. Następnie skompiluj aplikację za pomocą następujących funkcji:
dotnet build
Dane wyjściowe kompilacji nie powinny zawierać żadnych ostrzeżeń ani błędów.
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
Instalowanie biblioteki klienta
W katalogu aplikacji zainstaluj bibliotekę klienta usługi Personalizacja dla platformy .NET za pomocą następującego polecenia:
dotnet add package Microsoft.Azure.CognitiveServices.Personalizer --version 1.0.0
Napiwek
Jeśli używasz środowiska IDE programu Visual Studio, biblioteka klienta jest dostępna jako pakiet NuGet do pobrania.
Blok kodu 1: Generowanie przykładowych danych
Usługa Personalizacja ma być uruchamiana w aplikacjach, które odbierają i interpretują dane w czasie rzeczywistym. W tym przewodniku Szybki start użyjesz przykładowego kodu, aby wygenerować wyimaginowane akcje klientów w witrynie internetowej sklepu spożywczego. Poniższy blok kodu definiuje trzy kluczowe metody: GetActions, GetContext i GetRewardScore.
Funkcja GetActions zwraca listę opcji, które witryna internetowa artykułów spożywczych musi sklasyfikować. W tym przykładzie akcje to produkty posiłek. Każdy wybór akcji zawiera szczegóły (funkcje), które mogą mieć wpływ na zachowanie użytkownika później. Akcje są używane jako dane wejściowe dla interfejsu API rangi
Funkcja GetContext zwraca symulowaną wizytę klienta. Wybiera losowe szczegóły (funkcje kontekstowe), takie jak ten, który klient jest obecny i o jakiej porze dnia odbywa się wizyta. Ogólnie rzecz biorąc, kontekst reprezentuje bieżący stan aplikacji, systemu, środowiska lub użytkownika. Obiekt kontekstu jest używany jako dane wejściowe dla interfejsu API rangi.
Funkcje kontekstowe w tym przewodniku Szybki start są uproszczone. Jednak w rzeczywistym systemie produkcyjnym projektowanie funkcji i ocenianie ich skuteczności jest ważne. Aby uzyskać wskazówki, zapoznaj się z połączoną dokumentacją.
Funkcja GetRewardScore zwraca wynik z zakresu od zera do jednego, który reprezentuje sukces interakcji z klientem. Używa prostej logiki, aby określić, jak różne konteksty reagują na różne opcje akcji. Na przykład określony użytkownik zawsze da 1,0 dla produktów wegetariańskich i wegańskich oraz 0,0 dla innych produktów. W rzeczywistym scenariuszu usługa Personalizacja będzie uczyć się preferencji użytkownika na podstawie danych wysyłanych w wywołaniach interfejsu API rangi i nagrody. Nie zdefiniujesz tych jawnie, tak jak w przykładowym kodzie.
W rzeczywistym systemie produkcyjnym wskaźnik nagrody powinien być zaprojektowany tak, aby był zgodny z celami biznesowymi i wskaźnikami KPI. Określenie sposobu obliczania metryki nagrody może wymagać eksperymentowania.
W poniższym kodzie preferencje i odpowiedzi użytkowników dotyczące akcji są zakodowane jako seria instrukcji warunkowych, a tekst objaśniający jest zawarty w kodzie w celach demonstracyjnych.
Znajdź klucz i punkt końcowy.
Ważne
Przejdź do portalu Azure Portal. Jeśli zasób personalizacji utworzony w sekcji Wymagania wstępne został wdrożony pomyślnie, kliknij przycisk Przejdź do zasobu w obszarze Następne kroki. Klucz i punkt końcowy można znaleźć na stronie klucza i punktu końcowego zasobu w obszarze zarządzanie zasobami.
Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego rozważ użycie bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń. Na przykład usługa Azure Key Vault.
Otwórz plik Program.cs w edytorze tekstów lub środowisku IDE i wklej następujący kod.
using Microsoft.Azure.CognitiveServices.Personalizer; using Microsoft.Azure.CognitiveServices.Personalizer.Models; class Program { private static readonly string ApiKey = "REPLACE_WITH_YOUR_PERSONALIZER_KEY"; private static readonly string ServiceEndpoint = "REPLACE_WITH_YOUR_ENDPOINT_URL"; static PersonalizerClient InitializePersonalizerClient(string url) { PersonalizerClient client = new PersonalizerClient( new ApiKeyServiceClientCredentials(ApiKey)) { Endpoint = url }; return client; } static Dictionary<string, ActionFeatures> actions = new Dictionary<string, ActionFeatures> { {"pasta", new ActionFeatures( new BrandInfo(company: "pasta_inc"), new ItemAttributes( quantity: 1, category: "Italian", price: 12), new DietaryAttributes( vegan: false, lowCarb: false, highProtein: false, vegetarian: false, lowFat: true, lowSodium: true))}, {"bbq", new ActionFeatures( new BrandInfo(company: "ambisco"), new ItemAttributes( quantity: 2, category: "bbq", price: 20), new DietaryAttributes( vegan: false, lowCarb: true, highProtein: true, vegetarian: false, lowFat: false, lowSodium: false))}, {"bao", new ActionFeatures( new BrandInfo(company: "bao_and_co"), new ItemAttributes( quantity: 4, category: "Chinese", price: 8), new DietaryAttributes( vegan: false, lowCarb: true, highProtein: true, vegetarian: false, lowFat: true, lowSodium: false))}, {"hummus", new ActionFeatures( new BrandInfo(company: "garbanzo_inc"), new ItemAttributes( quantity: 1, category: "Breakfast", price: 5), new DietaryAttributes( vegan: true, lowCarb: false, highProtein: true, vegetarian: true, lowFat: false, lowSodium: false))}, {"veg_platter", new ActionFeatures( new BrandInfo(company: "farm_fresh"), new ItemAttributes( quantity: 1, category: "produce", price: 7), new DietaryAttributes( vegan: true, lowCarb: true, highProtein: false, vegetarian: true, lowFat: true, lowSodium: true ))}, }; static IList<RankableAction> GetActions() { IList<RankableAction> rankableActions = new List<RankableAction>(); foreach (var action in actions) { rankableActions.Add(new RankableAction { Id = action.Key, Features = new List<object>() { action.Value } }); } return rankableActions; } public class BrandInfo { public string Company { get; set; } public BrandInfo(string company) { Company = company; } } public class ItemAttributes { public int Quantity { get; set; } public string Category { get; set; } public double Price { get; set; } public ItemAttributes(int quantity, string category, double price) { Quantity = quantity; Category = category; Price = price; } } public class DietaryAttributes { public bool Vegan { get; set; } public bool LowCarb { get; set; } public bool HighProtein { get; set; } public bool Vegetarian { get; set; } public bool LowFat { get; set; } public bool LowSodium { get; set; } public DietaryAttributes(bool vegan, bool lowCarb, bool highProtein, bool vegetarian, bool lowFat, bool lowSodium) { Vegan = vegan; LowCarb = lowCarb; HighProtein = highProtein; Vegetarian = vegetarian; LowFat = lowFat; LowSodium = lowSodium; } } public class ActionFeatures { public BrandInfo BrandInfo { get; set; } public ItemAttributes ItemAttributes { get; set; } public DietaryAttributes DietaryAttributes { get; set; } public ActionFeatures(BrandInfo brandInfo, ItemAttributes itemAttributes, DietaryAttributes dietaryAttributes) { BrandInfo = brandInfo; ItemAttributes = itemAttributes; DietaryAttributes = dietaryAttributes; } } public static Context GetContext() { return new Context( user: GetRandomUser(), timeOfDay: GetRandomTimeOfDay(), location: GetRandomLocation(), appType: GetRandomAppType()); } static string[] timesOfDay = new string[] { "morning", "afternoon", "evening" }; static string[] locations = new string[] { "west", "east", "midwest" }; static string[] appTypes = new string[] { "edge", "safari", "edge_mobile", "mobile_app" }; static IList<UserProfile> users = new List<UserProfile> { new UserProfile( name: "Bill", dietaryPreferences: new Dictionary<string, bool> { { "low_carb", true } }, avgOrderPrice: "0-20"), new UserProfile( name: "Satya", dietaryPreferences: new Dictionary<string, bool> { { "low_sodium", true} }, avgOrderPrice: "201+"), new UserProfile( name: "Amy", dietaryPreferences: new Dictionary<string, bool> { { "vegan", true }, { "vegetarian", true } }, avgOrderPrice: "21-50") }; static string GetRandomTimeOfDay() { var random = new Random(); var timeOfDayIndex = random.Next(timesOfDay.Length); Console.WriteLine($"TimeOfDay: {timesOfDay[timeOfDayIndex]}"); return timesOfDay[timeOfDayIndex]; } static string GetRandomLocation() { var random = new Random(); var locationIndex = random.Next(locations.Length); Console.WriteLine($"Location: {locations[locationIndex]}"); return locations[locationIndex]; } static string GetRandomAppType() { var random = new Random(); var appIndex = random.Next(appTypes.Length); Console.WriteLine($"AppType: {appTypes[appIndex]}"); return appTypes[appIndex]; } static UserProfile GetRandomUser() { var random = new Random(); var userIndex = random.Next(users.Count); Console.WriteLine($"\nUser: {users[userIndex].Name}"); return users[userIndex]; } public class UserProfile { // Mark name as non serializable so that it is not part of the context features [NonSerialized()] public string Name; public Dictionary<string, bool> DietaryPreferences { get; set; } public string AvgOrderPrice { get; set; } public UserProfile(string name, Dictionary<string, bool> dietaryPreferences, string avgOrderPrice) { Name = name; DietaryPreferences = dietaryPreferences; AvgOrderPrice = avgOrderPrice; } } public class Context { public UserProfile User { get; set; } public string TimeOfDay { get; set; } public string Location { get; set; } public string AppType { get; set; } public Context(UserProfile user, string timeOfDay, string location, string appType) { User = user; TimeOfDay = timeOfDay; Location = location; AppType = appType; } } public static float GetRewardScore(Context context, string actionId) { float rewardScore = 0.0f; string userName = context.User.Name; ActionFeatures actionFeatures = actions[actionId]; if (userName.Equals("Bill")) { if (actionFeatures.ItemAttributes.Price < 10 && !context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill likes to be economical when he's not in the midwest visiting his friend Warren. He bought {actionId} because it was below a price of $10."); } else if (actionFeatures.DietaryAttributes.LowCarb && context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill is visiting his friend Warren in the midwest. There he's willing to spend more on food as long as it's low carb, so Bill bought {actionId}."); } else if (actionFeatures.ItemAttributes.Price >= 10 && !context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill didn't buy {actionId} because the price was too high when not visting his friend Warren in the midwest."); } else if (actionFeatures.DietaryAttributes.LowCarb && context.Location.Equals("midwest")) { rewardScore = 1.0f; Console.WriteLine($"\nBill didn't buy {actionId} because it's not low-carb, and he's in the midwest visitng his friend Warren."); } } else if (userName.Equals("Satya")) { if (actionFeatures.DietaryAttributes.LowSodium) { rewardScore = 1.0f; Console.WriteLine($"\nSatya is health conscious, so he bought {actionId} since it's low in sodium."); } else { Console.WriteLine($"\nSatya did not buy {actionId} because it's not low sodium."); } } else if (userName.Equals("Amy")) { if (actionFeatures.DietaryAttributes.Vegan || actionFeatures.DietaryAttributes.Vegetarian) { rewardScore = 1.0f; Console.WriteLine($"\nAmy likes to eat plant-based foods, so she bought {actionId} because it's vegan or vegetarian friendly."); } else { Console.WriteLine($"\nAmy did not buy {actionId} because it's not vegan or vegetarian."); } } return rewardScore; } // ...Wklej klucz i punkt końcowy we wskazanym miejscu w kodzie. Punkt końcowy ma formularz
https://<your_resource_name>.cognitiveservices.azure.com/.Ważne
Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń, takich jak usługa Azure Key Vault. Aby uzyskać więcej informacji, zobacz artykuł Dotyczący zabezpieczeń usług Azure AI.
Blok kodu 2: iterowanie pętli uczenia
Następny blok kodu definiuje metodę main i zamyka skrypt. Uruchamia iterację pętli uczenia, w której generuje kontekst (w tym klient), żąda klasyfikacji akcji w tym kontekście przy użyciu interfejsu API rangi, oblicza wynik nagrody i przekazuje ten wynik z powrotem do usługi Personalizacja przy użyciu interfejsu API programu Reward. Wyświetla odpowiednie informacje do konsoli w każdym kroku.
W tym przykładzie każde wywołanie rangi jest wykonywane w celu określenia, który produkt powinien być wyświetlany w sekcji "Polecany produkt". Następnie wywołanie nagrody wskazuje, czy proponowany produkt został zakupiony przez użytkownika. Nagrody są związane z ich decyzjami za pośrednictwem wspólnej EventId wartości.
static void Main(string[] args)
{
int iteration = 1;
bool runLoop = true;
// Get the actions list to choose from personalizer with their features.
IList<RankableAction> actions = GetActions();
// Initialize Personalizer client.
PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);
do
{
Console.WriteLine("\nIteration: " + iteration++);
// Get context information.
Context context = GetContext();
// Create current context from user specified data.
IList<object> currentContext = new List<object>() {
context
};
// Generate an ID to associate with the request.
string eventId = Guid.NewGuid().ToString();
// Rank the actions
var request = new RankRequest(actions: actions, contextFeatures: currentContext, eventId: eventId);
RankResponse response = client.Rank(request);
Console.WriteLine($"\nPersonalizer service thinks {context.User.Name} would like to have: {response.RewardActionId}.");
float reward = GetRewardScore(context, response.RewardActionId);
// Send the reward for the action based on user response.
client.Reward(response.EventId, new RewardRequest(reward));
Console.WriteLine("\nPress q to break, any other key to continue:");
runLoop = !(GetKey() == "Q");
} while (runLoop);
}
private static string GetKey()
{
return Console.ReadKey().Key.ToString().Last().ToString().ToUpper();
}
}
Uruchamianie programu
Uruchom aplikację za pomocą polecenia dotnet dotnet run z katalogu aplikacji.
dotnet run
W pierwszej iteracji usługa Personalizacja zaleci losową akcję, ponieważ nie wykonała jeszcze żadnych szkoleń. Opcjonalnie można uruchamiać więcej iteracji. Po około 10 minutach usługa zacznie wyświetlać ulepszenia w zaleceniach.
Generowanie wielu zdarzeń na potrzeby analizy (opcjonalnie)
Z tego scenariusza szybkiego startu można łatwo wygenerować 5000 zdarzeń, co jest wystarczające do uzyskania doświadczenia przy użyciu trybu praktykanta i trybu online, uruchamiania ocen offline i tworzenia ocen funkcji. Zastąp metodę main powyżej:
static void Main(string[] args)
{
int iteration = 1;
int runLoop = 0;
// Get the actions list to choose from personalizer with their features.
IList<RankableAction> actions = GetActions();
// Initialize Personalizer client.
PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);
do
{
Console.WriteLine("\nIteration: " + iteration++);
// Get context information.
Context context = GetContext();
// Create current context from user specified data.
IList<object> currentContext = new List<object>() {
context
};
// Generate an ID to associate with the request.
string eventId = Guid.NewGuid().ToString();
// Rank the actions
var request = new RankRequest(actions: actions, contextFeatures: currentContext, eventId: eventId);
RankResponse response = client.Rank(request);
Console.WriteLine($"\nPersonalizer service thinks {context.User.Name} would like to have: {response.RewardActionId}.");
float reward = GetRewardScore(context, response.RewardActionId);
// Send the reward for the action based on user response.
client.Reward(response.EventId, new RewardRequest(reward));
runLoop = runLoop + 1;
} while (runLoop < 1000);
}
Kod źródłowy tego przewodnika Szybki start jest dostępny w witrynie GitHub.
Dokumentacja referencyjna — przykładowy |kod | źródłowy biblioteki źródłowej (npm) | Szybki start
Wymagania wstępne
- Subskrypcja platformy Azure — utwórz bezpłatnie
- Zainstaluj środowisko Node.js i narzędzie npm (zweryfikowane przy użyciu biblioteki Node.js w wersji 14.16.0 i npm 6.14.11).
- Po utworzeniu subskrypcji platformy Azure utwórz zasób usługi Personalizacja w witrynie Azure Portal, aby uzyskać klucz i punkt końcowy. Po wdrożeniu wybierz pozycję Przejdź do zasobu.
- Będziesz potrzebować klucza i punktu końcowego z utworzonego zasobu, aby połączyć aplikację z interfejsem API usługi Personalizacja. W dalszej części przewodnika Szybki start wklejesz klucz i punkt końcowy do poniższego kodu.
- Możesz użyć warstwy cenowej bezpłatna (
F0), aby wypróbować usługę, a następnie uaktualnić ją do warstwy płatnej dla środowiska produkcyjnego.
Konfiguracja modelu
Zmienianie częstotliwości aktualizacji modelu
W witrynie Azure Portal przejdź do strony Konfiguracja zasobu usługi Personalizacja i zmień częstotliwość aktualizacji modelu na 30 sekund. Ten krótki czas trwania będzie szybko trenował model, co pozwala zobaczyć, jak zmienia się zalecana akcja dla każdej iteracji.
Zmienianie czasu oczekiwania na nagrodę
W witrynie Azure Portal przejdź do strony Konfiguracja zasobu usługi Personalizacja i zmień czas oczekiwania na nagrodę na 10 minut. Określa to, jak długo model będzie czekał po wysłaniu rekomendacji, aby otrzymać opinię na temat nagrody od tego zalecenia. Trenowanie nie nastąpi, dopóki czas oczekiwania na nagrodę nie upłynął.
Tworzenie nowej aplikacji Node.js
W oknie konsoli (na przykład cmd, PowerShell lub Bash) utwórz nowy katalog dla aplikacji i przejdź do niego.
mkdir myapp && cd myapp
Uruchom polecenie , npm init -y aby utworzyć package.json plik.
npm init -y
Utwórz nowy skrypt Node.js w preferowanym edytorze lub środowisku IDE o nazwie personalizer-quickstart.js i utwórz zmienne dla punktu końcowego zasobu i klucza subskrypcji.
Instalowanie biblioteki klienta
Zainstaluj bibliotekę klienta usługi Personalizacja dla środowiska Node.js za pomocą następującego polecenia:
npm install @azure/cognitiveservices-personalizer --save
Zainstaluj pozostałe pakiety npm dla tego przewodnika Szybki start:
npm install @azure/ms-rest-azure-js @azure/ms-rest-js readline-sync uuid --save
Blok kodu 1: Generowanie przykładowych danych
Usługa Personalizacja ma być uruchamiana w aplikacjach, które odbierają i interpretują dane w czasie rzeczywistym. W tym przewodniku Szybki start użyjesz przykładowego kodu, aby wygenerować wyimaginowane akcje klientów w witrynie internetowej sklepu spożywczego. Poniższy blok kodu definiuje trzy kluczowe metody: getActionsList, getContextFeaturesList i getReward.
getActionsList zwraca listę opcji, które witryna internetowa sklepu spożywczego musi sklasyfikować. W tym przykładzie akcje to produkty posiłek. Każdy wybór akcji zawiera szczegóły (funkcje), które mogą mieć wpływ na zachowanie użytkownika później. Akcje są używane jako dane wejściowe dla interfejsu API rangi
metoda getContextFeaturesList zwraca symulowaną wizytę klienta. Wybiera losowe szczegóły (funkcje kontekstowe), takie jak ten, który klient jest obecny i o jakiej porze dnia odbywa się wizyta. Ogólnie rzecz biorąc, kontekst reprezentuje bieżący stan aplikacji, systemu, środowiska lub użytkownika. Obiekt kontekstu jest używany jako dane wejściowe dla interfejsu API rangi.
Funkcje kontekstowe w tym przewodniku Szybki start są uproszczone. Jednak w rzeczywistym systemie produkcyjnym projektowanie funkcji i ocenianie ich skuteczności jest ważne. Aby uzyskać wskazówki, zapoznaj się z połączoną dokumentacją.
Polecenie getReward monituje użytkownika o ocenę rekomendacji usługi jako powodzenia lub niepowodzenia. Zwraca ona wynik z zakresu od zera do jednego, który reprezentuje sukces interakcji z klientem. W rzeczywistym scenariuszu usługa Personalizacja będzie uczyć się preferencji użytkownika z interakcji z klientami w czasie rzeczywistym.
W rzeczywistym systemie produkcyjnym wskaźnik nagrody powinien być zaprojektowany tak, aby był zgodny z celami biznesowymi i wskaźnikami KPI. Określenie sposobu obliczania metryki nagrody może wymagać eksperymentowania.
Otwórz plik personalr-quickstart.js w edytorze tekstów lub środowisku IDE i wklej poniższy kod.
const uuidv1 = require('uuid/v1');
const Personalizer = require('@azure/cognitiveservices-personalizer');
const CognitiveServicesCredentials = require('@azure/ms-rest-azure-js').CognitiveServicesCredentials;
const readline = require('readline-sync');
function getReward() {
const answer = readline.question("\nIs this correct (y/n)\n");
if (answer.toLowerCase() === 'y') {
console.log("\nGreat| Enjoy your food.");
return 1;
}
console.log("\nYou didn't like the recommended food choice.");
return 0;
}
function getContextFeaturesList() {
const timeOfDayFeatures = ['morning', 'afternoon', 'evening', 'night'];
const tasteFeatures = ['salty', 'sweet'];
let answer = readline.question("\nWhat time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night\n");
let selection = parseInt(answer);
const timeOfDay = selection >= 1 && selection <= 4 ? timeOfDayFeatures[selection - 1] : timeOfDayFeatures[0];
answer = readline.question("\nWhat type of food would you prefer (enter number)? 1. salty 2. sweet\n");
selection = parseInt(answer);
const taste = selection >= 1 && selection <= 2 ? tasteFeatures[selection - 1] : tasteFeatures[0];
console.log("Selected features:\n");
console.log("Time of day: " + timeOfDay + "\n");
console.log("Taste: " + taste + "\n");
return [
{
"time": timeOfDay
},
{
"taste": taste
}
];
}
function getExcludedActionsList() {
return [
"juice"
];
}
function getActionsList() {
return [
{
"id": "pasta",
"features": [
{
"taste": "salty",
"spiceLevel": "medium"
},
{
"nutritionLevel": 5,
"cuisine": "italian"
}
]
},
{
"id": "ice cream",
"features": [
{
"taste": "sweet",
"spiceLevel": "none"
},
{
"nutritionalLevel": 2
}
]
},
{
"id": "juice",
"features": [
{
"taste": "sweet",
"spiceLevel": "none"
},
{
"nutritionLevel": 5
},
{
"drink": true
}
]
},
{
"id": "salad",
"features": [
{
"taste": "salty",
"spiceLevel": "low"
},
{
"nutritionLevel": 8
}
]
}
];
}
Blok kodu 2: iterowanie pętli uczenia
Następny blok kodu definiuje metodę main i zamyka skrypt. Uruchamia iterację pętli uczenia, w której prosi użytkownika o ich preferencje w wierszu polecenia i wysyła te informacje do personalizacji, aby wybrać najlepszą akcję. Przedstawia wybraną akcję użytkownikowi, który dokonuje wyboru przy użyciu wiersza polecenia. Następnie wysyła wynik nagrody do usługi Personalizacja, aby zasygnalizować, jak dobrze usługa wykonała wybór.
Pętla szkoleniowa Personalizacja to cykl wywołań rangi i nagrody . W tym przewodniku Szybki start każde wywołanie rangi, aby spersonalizować zawartość, następuje wywołanie nagrody, aby poinformować personalizację o tym, jak dobrze działa usługa.
Dodaj poniższy kod, aby personalizator-quickstart.js.
Znajdź klucz i punkt końcowy. Punkt końcowy ma formularz
https://<your_resource_name>.cognitiveservices.azure.com/.Ważne
Przejdź do portalu Azure Portal. Jeśli zasób personalizacji utworzony w sekcji Wymagania wstępne został wdrożony pomyślnie, kliknij przycisk Przejdź do zasobu w obszarze Następne kroki. Klucz i punkt końcowy można znaleźć na stronie klucza i punktu końcowego zasobu w obszarze zarządzanie zasobami.
Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego rozważ użycie bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń. Na przykład usługa Azure Key Vault.
Wklej klucz i punkt końcowy we wskazanym miejscu w kodzie.
Ważne
Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń, takich jak usługa Azure Key Vault. Aby uzyskać więcej informacji na temat zabezpieczeń, zobacz artykuł Zabezpieczenia usług Azure AI.
async function main() { // The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF" const serviceKey = "PASTE_YOUR_PERSONALIZER_SUBSCRIPTION_KEY_HERE"; // The endpoint specific to your personalization service instance; // e.g. https://<your-resource-name>.cognitiveservices.azure.com const baseUri = "PASTE_YOUR_PERSONALIZER_ENDPOINT_HERE"; const credentials = new CognitiveServicesCredentials(serviceKey); // Initialize Personalization client. const personalizerClient = new Personalizer.PersonalizerClient(credentials, baseUri); let runLoop = true; do { let rankRequest = {} // Generate an ID to associate with the request. rankRequest.eventId = uuidv1(); // Get context information from the user. rankRequest.contextFeatures = getContextFeaturesList(); // Get the actions list to choose from personalization with their features. rankRequest.actions = getActionsList(); // Exclude an action for personalization ranking. This action will be held at its current position. rankRequest.excludedActions = getExcludedActionsList(); rankRequest.deferActivation = false; // Rank the actions const rankResponse = await personalizerClient.rank(rankRequest); console.log("\nPersonalization service thinks you would like to have:\n") console.log(rankResponse.rewardActionId); // Display top choice to user, user agrees or disagrees with top choice const reward = getReward(); console.log("\nPersonalization service ranked the actions with the probabilities as below:\n"); for (let i = 0; i < rankResponse.ranking.length; i++) { console.log(JSON.stringify(rankResponse.ranking[i]) + "\n"); } // Send the reward for the action based on user response. const rewardRequest = { value: reward } await personalizerClient.events.reward(rankRequest.eventId, rewardRequest); runLoop = continueLoop(); } while (runLoop); } function continueLoop() { const answer = readline.question("\nPress q to break, any other key to continue.\n") if (answer.toLowerCase() === 'q') { return false; } return true; } main() .then(result => console.log("done")) .catch(err=> console.log(err));
Uruchamianie programu
Uruchom aplikację za pomocą polecenia Node.js z katalogu aplikacji.
node personalizer-quickstart.js
Iteruj przez kilka pętli uczenia. Po około 10 minutach usługa zacznie wyświetlać ulepszenia w zaleceniach.
Kod źródłowy tego przewodnika Szybki start jest dostępny w witrynie GitHub.
Dokumentacja referencyjna — przykładowy | kod | źródłowy biblioteki źródłowej (pypi) | Szybki start
Wymagania wstępne
- Subskrypcja platformy Azure — utwórz bezpłatnie
- Python 3.x
- Po skonfigurowaniu subskrypcji platformy Azure utwórz zasób usługi Personalizacja w witrynie Azure Portal i uzyskaj klucz i punkt końcowy. Po wdrożeniu wybierz pozycję Przejdź do zasobu.
- Klucz i punkt końcowy z utworzonego zasobu będą potrzebne, aby połączyć aplikację z interfejsem API personalizacji, który wklejasz do poniższego kodu Szybkiego startu.
- Możesz użyć warstwy cenowej bezpłatna (
F0), aby wypróbować usługę, a następnie przeprowadzić uaktualnienie do warstwy płatnej dla środowiska produkcyjnego w późniejszym czasie.
Konfiguracja modelu
Zmienianie częstotliwości aktualizacji modelu
W witrynie Azure Portal przejdź do strony Konfiguracja zasobu usługi Personalizacja i zmień częstotliwość aktualizacji modelu na 30 sekund. Ten krótki czas trwania będzie szybko trenował model, co pozwala zobaczyć, jak zmienia się zalecana akcja dla każdej iteracji.
Zmienianie czasu oczekiwania na nagrodę
W witrynie Azure Portal przejdź do strony Konfiguracja zasobu usługi Personalizacja i zmień czas oczekiwania na nagrodę na 10 minut. Określa to, jak długo model będzie czekał po wysłaniu rekomendacji, aby otrzymać opinię na temat nagrody od tego zalecenia. Trenowanie nie nastąpi, dopóki czas oczekiwania na nagrodę nie upłynął.
Tworzenie nowej aplikacji w języku Python
Utwórz nowy plik w języku Python o nazwie personalizer-quickstart.py.
Instalowanie biblioteki klienta
Zainstaluj bibliotekę klienta usługi Personalizacja za pomocą narzędzia pip:
pip install azure-cognitiveservices-personalizer
Blok kodu 1: Generowanie przykładowych danych
Usługa Personalizacja ma być uruchamiana w aplikacjach, które odbierają i interpretują dane w czasie rzeczywistym. Na potrzeby tego przewodnika Szybki start użyjesz przykładowego kodu, aby wygenerować wyimaginowane akcje klientów w witrynie internetowej sklepu spożywczego. Poniższy blok kodu definiuje trzy kluczowe funkcje: get_actions, get_context i get_reward_score.
get_actions zwraca listę wyborów, które witryna internetowa artykułów spożywczych musi sklasyfikować. W tym przykładzie akcje to produkty posiłek. Każdy wybór akcji zawiera szczegóły (funkcje), które mogą mieć wpływ na zachowanie użytkownika później. Akcje są używane jako dane wejściowe dla interfejsu API rangi
get_context zwraca symulowaną wizytę klienta. Wybiera losowe szczegóły (funkcje kontekstowe), takie jak ten, który klient jest obecny i o jakiej porze dnia odbywa się wizyta. Ogólnie rzecz biorąc, kontekst reprezentuje bieżący stan aplikacji, systemu, środowiska lub użytkownika. Obiekt kontekstu jest używany jako dane wejściowe dla interfejsu API rangi.
Funkcje kontekstowe w tym przewodniku Szybki start są uproszczone. Jednak w rzeczywistym systemie produkcyjnym projektowanie funkcji i ocenianie ich skuteczności jest bardzo ważne. Aby uzyskać wskazówki, zapoznaj się z połączoną dokumentacją.
get_reward_score zwraca wynik z zakresu od zera do jednego, który reprezentuje sukces interakcji z klientem. Używa prostej logiki, aby określić, jak różne konteksty będą reagować na różne wybory akcji. Na przykład określony użytkownik zawsze da 1,0 dla produktów wegetariańskich i wegańskich oraz 0,0 dla innych produktów. W rzeczywistym scenariuszu usługa Personalizacja będzie uczyć się preferencji użytkownika na podstawie danych wysyłanych w wywołaniach interfejsu API rangi i nagrody. Nie zdefiniujesz tych jawnie, tak jak w przykładowym kodzie.
W rzeczywistym systemie produkcyjnym wskaźnik nagrody powinien być zaprojektowany tak, aby był zgodny z celami biznesowymi i wskaźnikami KPI. Określenie sposobu obliczania metryki nagrody może wymagać eksperymentowania.
W poniższym kodzie preferencje i odpowiedzi użytkowników dotyczące akcji są zakodowane jako seria instrukcji warunkowych, a tekst objaśniający jest zawarty w kodzie w celach demonstracyjnych.
Wykonaj następujące kroki, aby skonfigurować skrypt personalizacji.
Znajdź klucz i punkt końcowy.
Ważne
Przejdź do portalu Azure Portal. Jeśli zasób personalizacji utworzony w sekcji Wymagania wstępne został wdrożony pomyślnie, kliknij przycisk Przejdź do zasobu w obszarze Następne kroki. Klucz i punkt końcowy można znaleźć na stronie klucza i punktu końcowego zasobu w obszarze zarządzanie zasobami.
Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego rozważ użycie bezpiecznego sposobu przechowywania i uzyskiwania dostępu do poświadczeń. Na przykład usługa Azure Key Vault.
Otwórz personalizer-quickstart.py w edytorze tekstów lub środowisku IDE i wklej poniższy kod.
Wklej klucz i punkt końcowy we wskazanym miejscu w kodzie. Punkt końcowy ma formularz
https://<your_resource_name>.cognitiveservices.azure.com/.Ważne
Pamiętaj, aby usunąć klucz z kodu po zakończeniu i nigdy nie publikować go publicznie. W przypadku środowiska produkcyjnego użyj bezpiecznej metody do przechowywania poświadczeń i uzyskiwania do nich dostępu, takich jak usługa Azure Key Vault. Aby uzyskać więcej informacji, zobacz Zabezpieczenia usług Azure AI.
from azure.cognitiveservices.personalizer import PersonalizerClient
from azure.cognitiveservices.personalizer.models import RankableAction, RewardRequest, RankRequest
from msrest.authentication import CognitiveServicesCredentials
import datetime, json, os, time, uuid, random
key = "paste_your_personalizer_key_here"
endpoint = "paste_your_personalizer_endpoint_here"
# Instantiate a Personalizer client
client = PersonalizerClient(endpoint, CognitiveServicesCredentials(key))
actions_and_features = {
'pasta': {
'brand_info': {
'company':'pasta_inc'
},
'attributes': {
'qty':1, 'cuisine':'italian',
'price':12
},
'dietary_attributes': {
'vegan': False,
'low_carb': False,
'high_protein': False,
'vegetarian': False,
'low_fat': True,
'low_sodium': True
}
},
'bbq': {
'brand_info' : {
'company': 'ambisco'
},
'attributes': {
'qty': 2,
'category': 'bbq',
'price': 20
},
'dietary_attributes': {
'vegan': False,
'low_carb': True,
'high_protein': True,
'vegetarian': False,
'low_fat': False,
'low_sodium': False
}
},
'bao': {
'brand_info': {
'company': 'bao_and_co'
},
'attributes': {
'qty': 4,
'category': 'chinese',
'price': 8
},
'dietary_attributes': {
'vegan': False,
'low_carb': True,
'high_protein': True,
'vegetarian': False,
'low_fat': True,
'low_sodium': False
}
},
'hummus': {
'brand_info' : {
'company': 'garbanzo_inc'
},
'attributes' : {
'qty': 1,
'category': 'breakfast',
'price': 5
},
'dietary_attributes': {
'vegan': True,
'low_carb': False,
'high_protein': True,
'vegetarian': True,
'low_fat': False,
'low_sodium': False
}
},
'veg_platter': {
'brand_info': {
'company': 'farm_fresh'
},
'attributes': {
'qty': 1,
'category': 'produce',
'price': 7
},
'dietary_attributes': {
'vegan': True,
'low_carb': True,
'high_protein': False,
'vegetarian': True,
'low_fat': True,
'low_sodium': True
}
}
}
def get_actions():
res = []
for action_id, feat in actions_and_features.items():
action = RankableAction(id=action_id, features=[feat])
res.append(action)
return res
user_profiles = {
'Bill': {
'dietary_preferences': 'low_carb',
'avg_order_price': '0-20',
'browser_type': 'edge'
},
'Satya': {
'dietary_preferences': 'low_sodium',
'avg_order_price': '201+',
'browser_type': 'safari'
},
'Amy': {
'dietary_preferences': {
'vegan', 'vegetarian'
},
'avg_order_price': '21-50',
'browser_type': 'edge'},
}
def get_context(user):
location_context = {'location': random.choice(['west', 'east', 'midwest'])}
time_of_day = {'time_of_day': random.choice(['morning', 'afternoon', 'evening'])}
app_type = {'application_type': random.choice(['edge', 'safari', 'edge_mobile', 'mobile_app'])}
res = [user_profiles[user], location_context, time_of_day, app_type]
return res
def get_random_users(k = 5):
return random.choices(list(user_profiles.keys()), k=k)
def get_reward_score(user, actionid, context):
reward_score = 0.0
action = actions_and_features[actionid]
if user == 'Bill':
if action['attributes']['price'] < 10 and (context[1]['location'] != "midwest"):
reward_score = 1.0
print("Bill likes to be economical when he's not in the midwest visiting his friend Warren. He bought", actionid, "because it was below a price of $10.")
elif (action['dietary_attributes']['low_carb'] == True) and (context[1]['location'] == "midwest"):
reward_score = 1.0
print("Bill is visiting his friend Warren in the midwest. There he's willing to spend more on food as long as it's low carb, so Bill bought" + actionid + ".")
elif (action['attributes']['price'] >= 10) and (context[1]['location'] != "midwest"):
print("Bill didn't buy", actionid, "because the price was too high when not visting his friend Warren in the midwest.")
elif (action['dietary_attributes']['low_carb'] == False) and (context[1]['location'] == "midwest"):
print("Bill didn't buy", actionid, "because it's not low-carb, and he's in the midwest visitng his friend Warren.")
elif user == 'Satya':
if action['dietary_attributes']['low_sodium'] == True:
reward_score = 1.0
print("Satya is health conscious, so he bought", actionid,"since it's low in sodium.")
else:
print("Satya did not buy", actionid, "because it's not low sodium.")
elif user == 'Amy':
if (action['dietary_attributes']['vegan'] == True) or (action['dietary_attributes']['vegetarian'] == True):
reward_score = 1.0
print("Amy likes to eat plant-based foods, so she bought", actionid, "because it's vegan or vegetarian friendly.")
else:
print("Amy did not buy", actionid, "because it's not vegan or vegetarian.")
return reward_score
# ...
Blok kodu 2: iterowanie pętli uczenia
Następny blok kodu definiuje funkcję run_personalizer_cycle i wywołuje ją w prostej pętli opinii użytkownika. Uruchamia iterację pętli uczenia, w której generuje kontekst (w tym klient), żąda klasyfikacji akcji w tym kontekście przy użyciu interfejsu API rangi, oblicza wynik nagrody i przekazuje ten wynik z powrotem do usługi Personalizacja przy użyciu interfejsu API programu Reward. Wyświetla odpowiednie informacje do konsoli w każdym kroku.
W tym przykładzie każde wywołanie rangi jest wykonywane w celu określenia, który produkt powinien być wyświetlany w sekcji "Polecany produkt". Następnie wywołanie nagrody wskazuje, czy proponowany produkt został zakupiony przez użytkownika. Nagrody są związane z ich decyzjami za pośrednictwem wspólnej EventId wartości.
def run_personalizer_cycle():
actions = get_actions()
user_list = get_random_users()
for user in user_list:
print("------------")
print("User:", user, "\n")
context = get_context(user)
print("Context:", context, "\n")
rank_request = RankRequest(actions=actions, context_features=context)
response = client.rank(rank_request=rank_request)
print("Rank API response:", response, "\n")
eventid = response.event_id
actionid = response.reward_action_id
print("Personalizer recommended action", actionid, "and it was shown as the featured product.\n")
reward_score = get_reward_score(user, actionid, context)
client.events.reward(event_id=eventid, value=reward_score)
print("\nA reward score of", reward_score , "was sent to Personalizer.")
print("------------\n")
continue_loop = True
while continue_loop:
run_personalizer_cycle()
br = input("Press Q to exit, or any other key to run another loop: ")
if(br.lower()=='q'):
continue_loop = False
Uruchamianie programu
Po dołączeniu całego powyższego kodu do pliku języka Python możesz go uruchomić z katalogu aplikacji.
python personalizer-quickstart.py
W pierwszej iteracji usługa Personalizacja zaleci losową akcję, ponieważ nie wykonała jeszcze żadnych szkoleń. Opcjonalnie można uruchamiać więcej iteracji. Po około 10 minutach usługa zacznie wyświetlać ulepszenia w zaleceniach.
Generowanie wielu zdarzeń na potrzeby analizy (opcjonalnie)
Z tego scenariusza szybkiego startu można łatwo wygenerować 5000 zdarzeń, co jest wystarczające do uzyskania doświadczenia przy użyciu trybu praktykanta, trybu online, uruchamiania ocen offline i tworzenia ocen funkcji. Zastąp pętlę while w powyższym bloku kodu następującym kodem.
for i in range(0,1000):
run_personalizer_cycle()
Kod źródłowy tego przewodnika Szybki start jest dostępny w witrynie GitHub.
Pobieranie wytrenowanego modelu
Jeśli chcesz pobrać model personalizacji, który został wytrenowany na 5000 zdarzeń z powyższego przykładu, odwiedź repozytorium Personalr Samples i pobierz plik Personalizer_QuickStart_Model.zip . Następnie przejdź do zasobu Personalizacja w witrynie Azure Portal, przejdź do strony Konfiguracja i karty Importowanie/eksportowanie i zaimportuj plik.
Czyszczenie zasobów
Aby wyczyścić subskrypcję usług Azure AI, możesz usunąć zasób lub usunąć grupę zasobów, co spowoduje usunięcie wszelkich skojarzonych zasobów.