Начало работы с локальным пакетом SDK вывода для Персонализатора ИИ Azure

Важно!

Начиная с 20 сентября 2023 г. вы не сможете создавать новые ресурсы Персонализатора. Служба Персонализатора отменяется 1 октября 2026 года.

Пакет SDK Персонализатора для локального вывода (предварительная версия) скачивает модель Персонализатора в локальную среду, что позволяет избавиться от сетевого взаимодействия при вызовах ранжирования, значительно сокращая задержку их выполнения. Каждую минуту этот клиент в фоновом режиме скачивает самую свежую версию модель, а затем использует ее для вывода.

В этом руководстве вы узнаете, как использовать пакет SDK Персонализатора для локального вывода.

Вам потребуется установить клиентскую библиотеку Персонализатора для .NET для выполнения следующих действий.

• Проверка подлинности для учебного примера клиента с помощью ресурса Персонализатора в Azure.
• Отправка функций контекста и действий в API вознаграждения, который вернет лучшее действие из модели Персонализатора.
• Отправка оценки вознаграждения в API ранжирования и обучение модели Персонализатора.

Справочная документация | Исходный код библиотеки | Пакет (NuGet).

Необходимые компоненты

• Подписка Azure — создайте бесплатную учетную запись.
• Текущая версия .NET Core.
• После получения подписки Azure создайте ресурс Персонализатора в портал Azure, чтобы получить ключ и конечную точку. После развертывания ресурса выберите элемент Перейти к ресурсу.
  • Для подключения приложения к API Персонализатора потребуется ключ и конечная точка из созданного ресурса. Ключ и конечная точка будут вставлены в приведенный ниже код в кратком руководстве.
  • Используйте бесплатную ценовую категорию (F0), чтобы опробовать службу, а затем выполните обновление до платного уровня для рабочей среды.

Установка

Изменение частоты обновления модели

В портал Azure перейдите на страницу конфигурации ресурса Персонализатора и измените частоту обновления модели на 30 секунд. Эта короткая длительность быстро обучит модель, позволяя увидеть, как рекомендуемые действия изменяются для каждой итерации.

Изменение времени ожидания при вознаграждении

В портал Azure перейдите на страницу конфигурации ресурса Персонализатора и измените время ожидания вознаграждения на 10 минут. Это определяет, сколько времени модель будет ждать после отправки рекомендации, чтобы получить отзыв о вознаграждениях от этой рекомендации. Обучение не будет происходить до тех пор, пока время ожидания вознаграждения прошло.

Создание нового приложения C#

Создайте консольное приложение .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