Wprowadzenie do lokalnego zestawu SDK wnioskowania dla usługi Azure AI 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.
Lokalny zestaw SDK wnioskowania usługi Personalizacja (wersja zapoznawcza) pobiera model personalizacji lokalnie, co znacznie zmniejsza opóźnienie wywołań rangi przez wyeliminowanie wywołań sieciowych. Co minutę klient pobierze najnowszy model w tle i użyje go do wnioskowania.
Z tego przewodnika dowiesz się, jak używać lokalnego zestawu SDK wnioskowania usługi Personalizacja.
Należy zainstalować bibliotekę klienta usługi Personalizacja dla platformy .NET, aby:
- Uwierzytelnij przykładowego klienta przewodnika Szybki start przy użyciu zasobu usługi Personalizacja na platformie Azure.
- Wysyłanie funkcji kontekstu i akcji do interfejsu API programu Reward, który zwróci najlepszą akcję z modelu personalizacji
- Wyślij wynik nagrody do interfejsu API rangi i wytrenuj model personalizacji.
Dokumentacja referencyjna | Pakiet kodu | źródłowego biblioteki źródłowej (NuGet)
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.
Konfigurowanie
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 polecenia dotnet new , 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. Aplikację można skompilować 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 Azure.AI.Personalizer --version 2.0.0-beta.2
Napiwek
Jeśli używasz środowiska IDE programu Visual Studio, biblioteka klienta jest dostępna jako pakiet NuGet do pobrania.
W katalogu projektu otwórz Program.cs plik w preferowanym edytorze lub środowisku IDE. Dodaj następujące dyrektywy using:
using Azure;
using Azure.AI.Personalizer;
using System;
using System.Collections.Generic;
using System.Linq;
Model obiektów
Klient personalizacji to obiekt PersonalrClient , który uwierzytelnia się na platformie Azure przy użyciu elementu Azure.AzureKeyCredential, który zawiera klucz.
Aby poprosić o wyświetlenie jednego najlepszego elementu, utwórz element PersonalrRankOptions, a następnie przekaż go do metody PersonalrClient.Rank . Metoda Rank zwraca element PersonalrRankResult.
Aby wysłać wynik nagrody do usługi Personalizacja, przekaż identyfikator zdarzenia i wynik nagrody do metody PersonalrClient.Reward .
Określenie wyniku nagrody w tym przewodniku Szybki start jest proste. W systemie produkcyjnym określenie, co ma wpływ na wynik nagrody i ile może być złożonym procesem, który można zmienić w czasie. Ta decyzja projektowa powinna być jedną z głównych decyzji w architekturze personalizacji.
Przykłady kodu
Te fragmenty kodu pokazują, jak wykonać następujące zadania za pomocą biblioteki klienta personalizacji dla platformy .NET:
- Tworzenie klienta usługi Personalizacja
- Interfejs API klasyfikacji wielu miejsc
- Interfejs API nagród z wieloma miejscami
Uwierzytelnianie użytkownika
W tej sekcji wykonasz dwie czynności:
- Określanie klucza i punktu końcowego
- Tworzenie klienta usługi Personalizacja
Zacznij od dodania następujących wierszy do klasy Program. Pamiętaj, aby dodać klucz i punkt końcowy z zasobu usługi Personalizacja.
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.
private const string ServiceEndpoint = "https://REPLACE-WITH-YOUR-PERSONALIZER-RESOURCE-NAME.cognitiveservices.azure.com";
private const string ResourceKey = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>";
Następnie skonstruuj adresy URL rangi i nagrody. Należy pamiętać, że ustawienie useLocalInference: true jako parametr dla PersonalizerClientOptions parametru jest wymagane do włączenia wnioskowania lokalnego.
static PersonalizerClient InitializePersonalizerClient(Uri url)
{
// Set the local inference flag to true when initializing the client.
return new PersonalizerClient(url, new AzureKeyCredential(ResourceKey), new PersonalizerClientOptions(useLocalInference: true));
}
Pobieranie opcji zawartości reprezentowanych jako akcje
Akcje reprezentują opcje zawartości, z których usługa Personalizacja ma wybrać najlepszy element zawartości. Dodaj następujące metody do klasy Program, aby reprezentować zestaw akcji i ich funkcje.
static IList<PersonalizerRankableAction> GetActions()
{
IList<PersonalizerRankableAction> actions = new List<PersonalizerRankableAction>
{
new PersonalizerRankableAction(
id: "pasta",
features: new List<object>() { new { taste = "salty", spiceLevel = "medium" }, new { nutritionLevel = 5, cuisine = "italian" } }
),
new PersonalizerRankableAction(
id: "ice cream",
features: new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionalLevel = 2 } }
),
new PersonalizerRankableAction(
id: "juice",
features: new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionLevel = 5 }, new { drink = true } }
),
new PersonalizerRankableAction(
id: "salad",
features: new List<object>() { new { taste = "salty", spiceLevel = "low" }, new { nutritionLevel = 8 } }
)
};
return actions;
}
Pobieranie preferencji użytkownika dla kontekstu
Dodaj następujące metody do klasy Program, aby uzyskać dane wejściowe użytkownika z wiersza polecenia dla godziny dnia i preferencji smaku użytkownika. Będą one używane jako funkcje kontekstowe.
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 GetUsersTastePreference()
{
string[] tasteFeatures = new string[] { "salty", "sweet" };
var random = new Random();
var taste = random.Next(1, 2);
Console.WriteLine("\nWhat type of food would you prefer (enter number)? 1. salty 2. sweet");
if (!int.TryParse(GetKey(), out int tasteIndex) || tasteIndex < 1 || tasteIndex > tasteFeatures.Length)
{
Console.WriteLine("\nEntered value is invalid. Setting feature value to " + tasteFeatures[0] + ".");
tasteIndex = 1;
}
return tasteFeatures[taste - 1];
}
Obie metody używają GetKey metody , aby odczytać wybór użytkownika z wiersza polecenia.
private static string GetKey()
{
return Console.ReadKey().Key.ToString().Last().ToString().ToUpper();
}
private static IList<object> GetContext(string time, string taste)
{
return new List<object>()
{
new { time = time },
new { taste = taste }
};
}
Tworzenie pętli uczenia
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.
Poniższy kod przechodzi przez cykl z pytaniem użytkownika o preferencje za pośrednictwem wiersza polecenia, wysyłając te informacje do personalizacji, aby wybrać najlepszą akcję dla każdego miejsca, przedstawiając wybór klientowi do wyboru spośród listy, a następnie wysyłając ocenę nagrody do personalizacji sygnalizując, jak dobrze usługa wykonała wybór.
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 (rank and reward).\n" +
$"Each iteration represents a user interaction and will demonstrate how context, actions, 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();
PersonalizerClient client = InitializePersonalizerClient(new Uri(ServiceEndpoint));
do
{
Console.WriteLine("\nIteration: " + iteration++);
string timeOfDayFeature = GetTimeOfDayForContext();
string deviceFeature = GetUsersTastePreference();
IList<object> currentContext = GetContext(timeOfDayFeature, deviceFeature);
string eventId = Guid.NewGuid().ToString();
var rankOptions = new PersonalizerRankOptions(actions: actions, contextFeatures: currentContext, eventId: eventId);
PersonalizerRankResult rankResult = client.Rank(rankOptions);
Console.WriteLine("\nPersonalizer service thinks you would like to have: " + rankResult.RewardActionId + ". Is this correct? (y/n)");
float reward = 0.0f;
string answer = GetKey();
if (answer == "Y")
{
reward = 1.0f;
Console.WriteLine("\nGreat! Enjoy your food.");
}
else if (answer == "N")
{
reward = 0.0f;
Console.WriteLine("\nYou didn't like the recommended food choice.");
}
else
{
Console.WriteLine("\nEntered choice is invalid. Service assumes that you didn't like the recommended food choice.");
}
client.Reward(rankResult.EventId, reward);
Console.WriteLine("\nPress q to break, any other key to continue:");
runLoop = !(GetKey() == "Q");
} while (runLoop);
}
Uruchamianie programu
Uruchom aplikację za pomocą polecenia dotnet run z katalogu aplikacji.
dotnet run
