Начало работы с локальным пакетом SDK вывода для Персонализатора ИИ Azure
Важно!
Начиная с 20 сентября 2023 г. вы не сможете создавать новые ресурсы Персонализатора. Служба Персонализатора отменяется 1 октября 2026 года.
Пакет SDK Персонализатора для локального вывода (предварительная версия) скачивает модель Персонализатора в локальную среду, что позволяет избавиться от сетевого взаимодействия при вызовах ранжирования, значительно сокращая задержку их выполнения. Каждую минуту этот клиент в фоновом режиме скачивает самую свежую версию модель, а затем использует ее для вывода.
В этом руководстве вы узнаете, как использовать пакет SDK Персонализатора для локального вывода.
Вам потребуется установить клиентскую библиотеку Персонализатора для .NET для выполнения следующих действий.
- Проверка подлинности для учебного примера клиента с помощью ресурса Персонализатора в Azure.
- Отправка функций контекста и действий в API вознаграждения, который вернет лучшее действие из модели Персонализатора.
- Отправка оценки вознаграждения в API ранжирования и обучение модели Персонализатора.
Справочная документация | Исходный код библиотеки | Пакет (NuGet).
- Подписка Azure — создайте бесплатную учетную запись.
- Текущая версия .NET Core.
- После получения подписки Azure создайте ресурс Персонализатора в портал Azure, чтобы получить ключ и конечную точку. После развертывания ресурса выберите элемент Перейти к ресурсу.
- Для подключения приложения к API Персонализатора потребуется ключ и конечная точка из созданного ресурса. Ключ и конечная точка будут вставлены в приведенный ниже код в кратком руководстве.
- Используйте бесплатную ценовую категорию (
F0
), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.
В портал Azure перейдите на страницу конфигурации ресурса Персонализатора и измените частоту обновления модели на 30 секунд. Эта короткая длительность быстро обучит модель, позволяя увидеть, как рекомендуемые действия изменяются для каждой итерации.
В портал Azure перейдите на страницу конфигурации ресурса Персонализатора и измените время ожидания вознаграждения на 10 минут. Это определяет, сколько времени модель будет ждать после отправки рекомендации, чтобы получить отзыв о вознаграждениях от этой рекомендации. Обучение не будет происходить до тех пор, пока время ожидания вознаграждения прошло.
Создайте консольное приложение .NET Core на C# в предпочитаемой интегрированной среде разработки или редакторе.
В окне консоли (cmd, PowerShell или Bash) выполните команду dotnet new
, чтобы создать консольное приложение с именем personalizer-quickstart
. Эта команда создает простой проект Hello World на языке C# с одним файлом исходного кода: Program.cs
.
dotnet new console -n personalizer-quickstart
Измените каталог на созданную папку приложения. Чтобы создать приложение, выполните следующую команду:
dotnet build
Выходные данные сборки не должны содержать предупреждений или ошибок.
...
Build succeeded.
0 Warning(s)
0 Error(s)
...
В каталоге приложения установите клиентскую библиотеку Персонализатора для .NET с помощью следующей команды:
dotnet add package Azure.AI.Personalizer --version 2.0.0-beta.2
Совет
Если вы используете интегрированную среду разработки Visual Studio, клиентская библиотека доступна в виде загружаемого пакета NuGet.
В каталоге проекта откройте файл Program.cs
в предпочитаемом редакторе или интегрированной среде разработки. Добавьте следующие директивы using:
using Azure;
using Azure.AI.Personalizer;
using System;
using System.Collections.Generic;
using System.Linq;
Клиент Персонализатора — это объект PersonalizerClient, который проходит проверку подлинности в Azure с помощью объекта Azure.AzureKeyCredential, который содержит ваш ключ.
Чтобы запросить один лучший элемент для отображения пользователя, создайте персонализаторRankOptions, а затем передайте его в метод ПерсонализаторКлиент.Rank . Метод Rank возвращает PersonalizerRankResult.
Чтобы отправить оценку вознаграждения Персонализатору, передайте идентификатор события и оценку вознаграждения методу Персонализатор.Reward .
Определение результата вознаграждения в этом кратком руководстве тривиально. Со временем определение факторов влияния на оценку вознаграждения и сложность процесса в рабочей системе может измениться. Это решение должно быть одним из основных решений в вашей архитектуре Персонализатора.
Фрагменты кода по приведенным ниже ссылкам показывают, как выполнить следующие задачи с помощью клиентской библиотеки Персонализатора для .NET:
- создание клиента Персонализатора;
- API ранжирования для нескольких слотов
- API вознаграждений для нескольких слотов
В этом разделе показано, как выполнить два действия:
- определение ключа и конечной токи;
- создание клиента Персонализатора;
Начните с добавления следующих строк в класс Program. Не забудьте добавить ключ и конечную точку из ресурса Персонализатора.
Важно!
Перейдите на портал Azure. Если ресурс Персонализатора, созданный в соответствии с указаниями в разделе Предварительные требования, успешно развернут, нажмите кнопку Перейти к ресурсу в разделе Дальнейшие действия. Ключ и конечная точка располагаются на странице ключа и конечной точки ресурса в разделе управления ресурсами.
Обязательно удалите ключ из кода, когда завершите работу, и ни в коем случае не публикуйте его в открытом доступе. Для рабочей среды рекомендуется использовать безопасный способ хранения и доступа к учетным данным. Например, хранилище ключей Azure.
private const string ServiceEndpoint = "https://REPLACE-WITH-YOUR-PERSONALIZER-RESOURCE-NAME.cognitiveservices.azure.com";
private const string ResourceKey = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>";
Затем создайте URL-адреса ранжирования и вознаграждения. Обратите внимание, что для включения локального вывода требуется параметр useLocalInference: true
в качестве параметра PersonalizerClientOptions
.
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));
}
Действия представляют варианты содержимого, из которых Персонализатор должен выбрать лучший элемент содержимого. Добавьте следующие методы в класс Program, чтобы представить набор действий и их признаки.
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;
}
Добавьте следующие методы в класс Program, чтобы получить из командной строки введенные пользователем данные о времени суток и вкусовых предпочтениях. Они будут использоваться в качестве признаков контекста.
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];
}
Оба метода используют метод GetKey
для чтения выбора пользователя из командной строки.
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 }
};
}
Цикл обучения Персонализатора — это цикл вызовов ранжирования и вознаграждений. В этом кратком руководстве за каждым вызовом ранжирования для персонализации содержимого следует вызов вознаграждения. Это необходимо, чтобы определить, насколько хорошо сработала служба.
Нижеприведенный код выполняет цикл, в котором пользователь запрашивает его предпочтения через командную строку, отправляет данную информацию в Персонализатор для выбора наилучшего действия для каждого слота, представляет выбор клиенту для выбора из списка, после чего отправляет оценку вознаграждения в Персонализатор, свидетельствующую о том, насколько хорошо служба сделала свой выбор.
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);
}
Перейдите к каталогу приложения и запустите приложение с помощью команды dotnet run
.
dotnet run