ابدأ باستخدام SDK للاستدلال المحلي ل Azure الذكاء الاصطناعي Personalizer

هام

اعتبارا من 20 سبتمبر 2023، لن تتمكن من إنشاء موارد Personalizer جديدة. يتم إيقاف خدمة Personalizer في 1 أكتوبر 2026.

يقوم SDK للاستدلال المحلي لـ Personalizer (معاينة) بتنزيل نموذج Personalizer محليًا، وبالتالي يقلل بشكل كبير من زمن انتقال استدعاءات Rank عن طريق إزالة استدعاءات الشبكة. في كل دقيقة سيقوم العميل بتنزيل أحدث نموذج في الخلفية واستخدامه للاستدلال.

في هذا الدليل، ستتعلم كيفية استخدام SDK للاستدلال المحلي لـ Personalizer.

ستحتاج إلى تثبيت مكتبة عميل Personalizer لـ .NET من أجل:

• مصادقة عميل مثال التشغيل السريع باستخدام مورد Personalizer في Azure.
• إرسال ميزات السياق والإجراءات إلى واجهة برمجة تطبيقات Reward، والتي ستعيد أفضل إجراء من نموذج Personalizer
• إرسال درجة مكافأة إلى واجهة برمجة تطبيقات Rank وتدريب نموذج Personalizer.

الوثائق المرجعية | التعليمة البرمجية المصدر للمكتبة | الحزمة (NuGet)

المتطلبات الأساسية

• اشتراك Azure - إنشاء اشتراك مجانًا
• الإصدار الحالي من .NET Core.
• بمجرد حصولك على اشتراك Azure، قم بإنشاء مورد Personalizer في مدخل Microsoft Azure للحصول على المفتاح ونقطة النهاية. بعد انتشاره، حدد "Go to resource".
  • ستحتاج إلى المفتاح ونقطة النهاية من المورد الذي أنشأته لتوصيل التطبيق بواجهة برمجة تطبيقات Personalizer. ستلصق المفتاح ونقطة النهاية في التعليمات البرمجية أدناه لاحقًا في التشغيل السريع.
  • يمكنك استخدام مستوى التسعير الحر (F0) لتجربة الخدمة، والترقية لاحقًا إلى مستوى مدفوع للإنتاج.

الإعداد

تغيير تكرار تحديث النموذج.

في مدخل Microsoft Azure، انتقل إلى صفحة تكوين مورد Personalizer، وغير تكرار تحديث النموذج إلى 30 ثانية. ستدرب هذه المدة القصيرة النموذج بسرعة، ما يسمح لك بالاطلاع على كيفية تغيير الإجراء الموصى به لكل تكرار.

تغيير وقت انتظار المكافأة

في مدخل Microsoft Azure، انتقل إلى صفحة تكوين مورد Personalizer، وغير وقت انتظار المكافأة إلى 10 دقائق. يحدد هذا المدة التي سينتظرها النموذج بعد إرسال توصية، لتلقي ملاحظات المكافأة من تلك التوصية. لن يحدث التدريب حتى انقضاء وقت انتظار المكافأة.

إنشاء تطبيق C# جديد

إنشاء تطبيق جديد.NET Core في المحرر المفضل لديك أو IDE.

في نافذة وحدة تحكم، مثل(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)
...

تثبيت مكتبة العميل

ضمن دليل التطبيق، قم بتثبيت مكتبة العميل Personalizer لـ .NET مع الأمر التالي:

dotnet add package Azure.AI.Personalizer --version 2.0.0-beta.2

تلميح

إذا كنت تستخدم Visual Studio IDE، تتوفر مكتبة العميل كحزمة NuGet قابلة للتحميل.

من دليل المشروع، افتح Program.cs الملف في المحرر المفضل لديك أو IDE. أضف توجيهات الاستخدام التالية:

using Azure;
using Azure.AI.Personalizer;
using System;
using System.Collections.Generic;
using System.Linq;

نموذج الكائن

عميل Personalizer هو عنصر PersonalizerClient حيث يقوم بالمصادقة مع Azure باستخدام Azure.AzureKeyCredential والذي يحتوي على مفتاحك.

لطلب أفضل عنصر واحد لإظهار المستخدم، قم بإنشاء PersonalizerRankOptions، ثم قم بتمريره إلى أسلوب PersonalizerClient.Rank . يقوم أسلوب Rank بإرجاع PersonalizerRankResult.

لإرسال درجة مكافأة إلى Personalizer، مرر معرف الحدث ودرجة المكافأة إلى أسلوب PersonalizerClient.Reward .

تحديد نقاط المكافأة في هذه البداية السريعة أمر غير مهم. في نظام الإنتاج، يتم تحديد ما يؤثر على ⁧⁩نقاط المكافأة⁧⁩ وإلى أي مدى يمكن أن يشكّل عملية معقدة، والتي قد تقرر تغييرها مع مرور الوقت. يجب أن يكون قرار التصميم هذا أحد القرارات الأساسية في بنية Personalizer الخاصة بك.

أمثلة على التعليمات البرمجية

توضح لك هذه المقتطفات البرمجية كيفية القيام بالمهام التالية مع مكتبة عميل Personalizer لـ .NET:

• إنشاء عميل Personalizer
• واجهة برمجة تطبيقات الرتبة متعددة الفتحات
• واجهة برمجة تطبيقات المكافأة متعددة الفتحات

مصادقة العميل

في هذا القسم، سيتعين عليك تنفيذ خطوتين:

• تحديد المفتاح ونقطة النهاية
• قم بإنشاء عميل Personalizer

ابدأ بإضافة الأسطر التالية إلى فئة البرنامج. تأكد من إضافة المفتاح ونقطة النهاية من مورد Personalizer.

هام

انتقل إلى مدخل Azure. إذا تم نشر مورد Personalizer الذي أنشأته في قسم المتطلبات الأساسية بنجاح، فانقر فوق الزر Go to Resource ضمن Next Steps. يمكنك العثور على مفتاحك ونقطة النهاية في صفحة المفتاح ونقطة النهاية للمورد ضمن إدارة المورد.

تذكر إزالة المفتاح من التعليمة البرمجية عند الانتهاء، وعدم توزيعها علناً. للإنتاج، ضَع في اعتبارك استخدام طريقة آمنة لتخزين بيانات الاعتماد والوصول إليها. على سبيل المثال، 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>";

بعد ذلك، قم بإنشاء عناوين 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));
}

الحصول على خيارات المحتوى كإجراءات

تمثل الإجراءات خيارات المحتوى التي تريد من "Personalizer" تحديد أفضل عنصر محتوى منها. قم بإضافة الأساليب التالية إلى فئة البرنامج لتمثيل مجموعة الإجراءات والميزات الخاصة بها.

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;
}

الحصول على تفضيلات المستخدم لأغراض السياق

اضف الأساليب التالية إلى فئة "البرنامج" للحصول على إدخال المستخدم من سطر الأوامر للوقت من اليوم وتفضيلات ذوق المستخدم. سوف تُستخدم تلك كخصائص السياق.

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 }
    };
}

إنشاء حلقة التعلم

حلقة التعلم الشخصية هي دورة من استدعاءات الرتبةوالمكافأة. في هذا التشغيل السريع، كل استدعاء للرتبة لإضفاء طابع شخصي على المحتوى يتبعه استدعاء للمكافأة؛ لإخبار Personalizer بمدى جودة أداء الخدمة.

تُعرض التعليمات البرمجية التالية من خلال دورة طرح الأسئلة على المستخدم بشأن تفضيلاته باستخدام سطر الأوامر وإرسال تلك المعلومات إلى Personalizer لتحديد أفضل إجراء لكل فتحة، وتقديم التحديد للعميل للاختيار من بين القائمة ثم إرسال نقاط مكافأة إلى Personalizer مع وضع إشارة حول مدى أداء الخدمة في اختيارها.

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