البدء السريع: مكتبة عميل Personalizer
عرض محتوى مخصص في هذه البداية السريعة باستخدام خدمة Personalizer.
ابدأ مع مكتبة عميل Personalizer. اتبع هذه الخطوات لتثبيت الحزمة، وتجربة نموذج تعليمات البرمجة للمهام الأساسية.
- ترتيب واجهة برمجة التطبيقات - يحدد أفضل عنصر، من الإجراءات، استنادا إلى المعلومات في الوقت الفعلي التي تقدمها حول المحتوى والسياق.
- مكافأة API - يمكنك تحديد نقاط المكافأة على أساس احتياجات عملك، ثم إرسالها إلى Personalizer مع واجهة برمجة التطبيقات. يمكن أن تكون هذه النتيجة قيمة واحدة مثل 1 للجيد، و 0 للسيئ، أو خوارزمية تقوم بإنشائها استنادًا إلى احتياجات عملك.
الوثائق المرجعية | لحزمة كود المصدر للمكتبة | نماذج | (NuGet)
المتطلبات الأساسية
- اشتراك Azure - إنشاء اشتراك مجانًا
- الإصدار الحالي من cURL.
- بمجرد حصولك على اشتراك Azure، قم بإنشاء مورد Personalizer في مدخل Azure للحصول على المفتاح ونقطة النهاية. بعد انتشاره، انقر فوق Go to resource.
- ستحتاج إلى المفتاح ونقطة النهاية من المورد الذي تنشئه؛ لتوصيل التطبيق الخاص بك بواجهة برمجة تطبيقات Personalizer. ستلصق المفتاح ونقطة النهاية في التعليمات البرمجية أدناه لاحقًا في التشغيل السريع.
- يمكنك استخدام مستوى التسعير الحر (
F0) لتجربة الخدمة، والترقية لاحقًا إلى مستوى مدفوع للإنتاج.
إعداد
تغيير تكرار تحديث النموذج.
في بوابة Azure، في المورد الخاص بـ Personalizer في صفحةالتكوين، غيرتكرار تحديث النموذج إلى 30 ثانية. هذه المدة القصيرة سوف تدرب الخدمة بسرعة، مما يسمح لك برؤية كيفية تغيير الإجراء الأعلى لكل تكرار.
عندما يتم إنشاء حلقة خاصة بـ Personalizer لأول مرة، لا يوجد نموذج نظراً للحظة عدم وجود اتصال واجهة برمجة تطبيقات الخاصة بالمكافأة للتدرب منها. سيرجع ترتيب عملية الاتصال إلى احتمالات متساوية لكل عنصر. يجب أن يظل التطبيق الخاص بك دائماً يصنف المحتوى باستخدام إخراج RewardActionId.
تغيير وقت انتظار المكافأة
في مدخل Azure، في مورد "Personalizer" في صفحة التكوين، قم بتغيير وقت انتظار المكافأة إلى 30 ثانية. هذه المدة القصيرة تسهم في تسريع الخدمة مما يسمح لك برؤية كيفية تغيير الإجراء العلوي لكل تكرار.
إنشاء تطبيق 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 Microsoft.Azure.CognitiveServices.Personalizer --version 1.0.0
تلميح
إذا كنت تستخدم Visual Studio IDE، فستكون مكتبة العميل متوفرة كحزمة NuGet للتحميل.
من دليل المشروع، افتح Program.csالملف في المحرر المفضل لديك أو IDE. أضف توجيهات الاستخدام التالية:
using Microsoft.Azure.CognitiveServices.Personalizer;
using Microsoft.Azure.CognitiveServices.Personalizer.Models;
using System;
using System.Collections.Generic;
using System.Linq;
نموذج الكائن
عميل Personalizer هو عنصر PersonalizerClient حيث يقوم بالمصادقة مع Azure باستخدام Microsoft.Rest.ServiceClientCredentials والذي يحتوي على مفتاحك.
لطلب أفضل عنصر من المحتوى، أنشئ RankRequest، ثم مرره إلى أسلوبرتبة العميل. قوم الأسلوب Rank بإرجاع RankResponse.
لإرسال مكافأة إلى Personalizer، أنشئ RewardRequest ، ثم مرره إلى أسلوب client.Reward .
تحديد نقاط المكافأة في هذه البداية السريعة أمر غير مهم. في نظام الإنتاج، يتم تحديد ما يؤثر على نقاط المكافأة وإلى أي مدى يمكن أن يشكّل عملية معقدة، والتي قد تقرر تغييرها مع مرور الوقت. يجب أن يكون قرار التصميم هذا أحد القرارات الأساسية في بنية Personalizer الخاصة بك.
أمثلة التعليمات البرمجية
توضح لك هذه المقتطفات البرمجية كيفية القيام بالمهام التالية مع مكتبة عميل Personalizer لـ .NET:
قم بمصادقة العميل
في هذا القسم، سيتعين عليك تنفيذ خطوتين:
- تحديد المفتاح ونقطة النهاية
- قم بإنشاء عميل Personalizer
ابدأ بإضافة الأسطر التالية إلى فئة البرنامج. تأكد من إضافة المفتاح ونقطة النهاية من مورد Personalizer.
هام
انتقل إلى مدخل Azure. إذا تم نشر مورد Personalizer الذي أنشأته في قسم المتطلبات الأساسية بنجاح، فانقر فوق الزر Go to Resource ضمن Next Steps. يمكنك العثور على مفتاحك ونقطة النهاية في صفحة مفتاح المورد ونقطة النهاية ضمن إدارة الموارد.
تذكر إزالة المفتاح من التعليمات البرمجية عند الانتهاء، وعدم نشره على الملأ مطلقًا. للإنتاج، فكر في استخدام طريقة آمنة لتخزين بيانات الاعتماد الخاصة بك والوصول إليها. على سبيل المثال، Azure key vault.
private static readonly string ApiKey = "REPLACE-WITH-YOUR-PERSONALIZER-KEY";
private static readonly string ServiceEndpoint = "https://REPLACE-WITH-YOUR-PERSONALIZER-RESOURCE-NAME.cognitiveservices.azure.com";
بعد ذلك، أضف أسلوبًا إلى البرنامج لإنشاء عميل Personalizer جديد.
static PersonalizerClient InitializePersonalizerClient(string url)
{
PersonalizerClient client = new PersonalizerClient(
new ApiKeyServiceClientCredentials(ApiKey)) { Endpoint = url };
return client;
}
قم بالحصول على المواد الغذائية كأفعال مرتبة
تمثل الإجراءات خيارات المحتوى التي تريد من "Personalizer" تحديد أفضل عنصر محتوى منها. قم بإضافة الأساليب التالية إلى فئة البرنامج لتمثيل مجموعة الإجراءات والميزات الخاصة بها.
static IList<RankableAction> GetActions()
{
IList<RankableAction> actions = new List<RankableAction>
{
new RankableAction
{
Id = "pasta",
Features =
new List<object>() { new { taste = "salty", spiceLevel = "medium" }, new { nutritionLevel = 5, cuisine = "italian" } }
},
new RankableAction
{
Id = "ice cream",
Features =
new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionalLevel = 2 } }
},
new RankableAction
{
Id = "juice",
Features =
new List<object>() { new { taste = "sweet", spiceLevel = "none" }, new { nutritionLevel = 5 }, new { drink = true } }
},
new RankableAction
{
Id = "salad",
Features =
new List<object>() { new { taste = "salty", spiceLevel = "low" }, new { nutritionLevel = 8 } }
}
};
return actions;
}
قم بالحصول على تفضيلات المستخدم للسياق
قم بإضافة الأساليب التالية إلى فئة البرنامج للحصول على إدخال المستخدم من سطر الأوامر للوقت من اليوم وتفضيل الطعام الحالي. سيتم استخدام هذه كخصائص السياق.
static string GetUsersTimeOfDay()
{
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" };
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[tasteIndex - 1];
}
تستخدم كلتا الطريقتين GetKey أسلوبًا يتعلق بقراءة تحديد المستخدم من سطر الأوامر.
private static string GetKey()
{
return Console.ReadKey().Key.ToString().Last().ToString().ToUpper();
}
قم بإنشاء حلقة التعلم
حلقة تعلم Personalizer هي دورة من استدعاءات الرتبةوالمكافأة. في هذه البداية السريعة، كل مكالمة Rank، لتخصيص المحتوى، يتبعها مكالمة مكافأة لإخبار "Personalizer" بمدى جودة أداء الخدمة.
التعليمات البرمجية التالية حلقات من خلال دورة لسؤال المستخدم عن تفضيلاته من خلال سطر الأوامر، وإرسال تلك المعلومات إلى Personalizer لتحديد أفضل إجراء لكل فتحة، وتقديم التحديد للعميل للاختيار من بين القائمة، ثم إرسال نقاط مكافأة إلى Personalizer إشارة إلى مدى أداء الخدمة في اختيارها.
static void Main(string[] args)
{
int iteration = 1;
bool runLoop = true;
IList<RankableAction> actions = GetActions();
PersonalizerClient client = InitializePersonalizerClient(ServiceEndpoint);
do
{
Console.WriteLine("\nIteration: " + iteration++);
string timeOfDayFeature = GetUsersTimeOfDay();
string tasteFeature = GetUsersTastePreference();
IList<object> currentContext = new List<object>() {
new { time = timeOfDayFeature },
new { taste = tasteFeature }
};
IList<string> excludeActions = new List<string> { "juice" };
string eventId = Guid.NewGuid().ToString();
var request = new RankRequest(actions, currentContext, excludeActions, eventId);
RankResponse response = client.Rank(request);
Console.WriteLine("\nPersonalizer service thinks you would like to have: " + response.RewardActionId + ". Is this correct? (y/n)");
float reward = 0.0f;
string answer = GetKey();
if (answer == "Y")
{
reward = 1;
Console.WriteLine("\nGreat! Enjoy your food.");
}
else if (answer == "N")
{
reward = 0;
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.");
}
Console.WriteLine("\nPersonalizer service ranked the actions with the probabilities as below:");
foreach (var rankedResponse in response.Ranking)
{
Console.WriteLine(rankedResponse.Id + " " + rankedResponse.Probability);
}
client.Reward(response.EventId, new RewardRequest(reward));
Console.WriteLine("\nPress q to break, any other key to continue:");
runLoop = !(GetKey() == "Q");
} while (runLoop);
}
إضافة الطرق التالية، التي تحصل على خيارات المحتوى،قبل تشغيل ملف التعليمات البرمجية:
GetActionsGetUsersTimeOfDayGetUsersTastePreferenceGetKey
قم بطلب أفضل إجراء
لإكمال طلب الرتبة، يطلب البرنامج من تفضيلات المستخدم إنشاء currentContext خيارات المحتوى. يمكن للعملية إنشاء محتوى للاستبعاد من الإجراءات، كما هو موضح في excludeActions. يحتاج طلب الرتبة إلى الإجراءات والميزات الخاصة بهم، ميزات currentContext excludeActions، وID حدث الرتبة الفريد لتلقي استجابة الرتبة.
هذه البداية السريعة لديها ميزات سياق بسيطة من الوقت من اليوم وتفضيل الطعام المستخدم. في أنظمة الإنتاج ، يمكن أن يكون تحديد وتقييمالإجراءات والميزات مسألة غير تافهة.
string timeOfDayFeature = GetUsersTimeOfDay();
string tasteFeature = GetUsersTastePreference();
IList<object> currentContext = new List<object>() {
new { time = timeOfDayFeature },
new { taste = tasteFeature }
};
IList<string> excludeActions = new List<string> { "juice" };
string eventId = Guid.NewGuid().ToString();
var request = new RankRequest(actions, currentContext, excludeActions, eventId);
RankResponse response = client.Rank(request);
قم بإرسال مكافأة
للحصول على نقاط المكافأة لإرسالها في طلب المكافأة، يحصل البرنامج على تحديد المستخدم من سطر الأوامر، ويعين قيمة رقمية للاختيار، ثم يرسل ID الحدث الفريد ودرجة المكافأة كقيمة رقمية إلى واجهة برمجة تطبيقات المكافأة.
هذه البداية السريعة تعيّن عددًا بسيطًا كنقاط مكافأة، إما صفر أو 1. في أنظمة الإنتاج يمكن أن يكون تحديد وقت وأهمية استدعاء المكافأة أمرًا غير مهم فهو يعتمد على احتياجاتك الخاصة.
float reward = 0.0f;
string answer = GetKey();
if (answer == "Y")
{
reward = 1;
Console.WriteLine("\nGreat! Enjoy your food.");
}
else if (answer == "N")
{
reward = 0;
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.");
}
Console.WriteLine("\nPersonalizer service ranked the actions with the probabilities as below:");
foreach (var rankedResponse in response.Ranking)
{
Console.WriteLine(rankedResponse.Id + " " + rankedResponse.Probability);
}
// Send the reward for the action based on user response.
client.Reward(response.EventId, new RewardRequest(reward));
قم بتشغيل البرنامج.
قم بتشغيل التطبيق من دليل التطبيق الخاص بك باستخدام الأمر dotnet run.
dotnet run
تتوافر التعليمة البرمجية الخاصة بالمصدر لبدء التشغيل السريع هذا.
الوثائق المرجعية |كود مصدر المكتبة | حزمة (NPM) | النماذج
المتطلبات الأساسية
- اشتراك Azure - إنشاء اشتراك مجاناً
- تثبيت Node.js وNPM (التحقق مع Node.js v14.16.0 وNPM 6.14.11).
- بمجرد حصولك على اشتراك Azure، قم بإنشاء مورد Personalizer في مدخل Azure للحصول على المفتاح ونقطة النهاية. بعد انتشاره، انقر فوق Go to resource.
- ستحتاج إلى المفتاح ونقطة النهاية من المورد الذي تنشئه؛ لتوصيل التطبيق الخاص بك بواجهة برمجة تطبيقات Personalizer. ستلصق المفتاح ونقطة النهاية في التعليمات البرمجية أدناه لاحقًا في التشغيل السريع.
- يمكنك استخدام مستوى التسعير الحر (
F0) لتجربة الخدمة، والترقية لاحقًا إلى مستوى مدفوع للإنتاج.
إعداد
تغيير تكرار تحديث النموذج.
في بوابة Azure، في المورد الخاص بـ Personalizer في صفحةالتكوين، غيرتكرار تحديث النموذج إلى 30 ثانية. هذه المدة القصيرة سوف تدرب الخدمة بسرعة، مما يسمح لك برؤية كيفية تغيير الإجراء الأعلى لكل تكرار.
عندما يتم إنشاء حلقة خاصة بـ Personalizer لأول مرة، لا يوجد نموذج نظراً للحظة عدم وجود اتصال واجهة برمجة تطبيقات الخاصة بالمكافأة للتدرب منها. سيرجع ترتيب عملية الاتصال إلى احتمالات متساوية لكل عنصر. يجب أن يظل التطبيق الخاص بك دائماً يصنف المحتوى باستخدام إخراج RewardActionId.
تغيير وقت انتظار المكافأة
في مدخل Azure، في مورد "Personalizer" في صفحة التكوين، قم بتغيير وقت انتظار المكافأة إلى 30 ثانية. هذه المدة القصيرة تسهم في تسريع الخدمة مما يسمح لك برؤية كيفية تغيير الإجراء العلوي لكل تكرار.
إنشاء تطبيق Node.js جديد
في نافذة وحدة التحكم (مثل cmd أو PowerShell أو Bash)، أنشئ دليلاً جديداً لتطبيقك وانتقل إليه.
mkdir myapp && cd myapp
استخدم الأمر npm init -y لإنشاء ملف.package.json
npm init -y
إنشاء تطبيق Node.js جديد في المحرر المفضل لديك أو IDE sample.js التي قمت بتسميتها وقم بإنشاء متغيرات نقطة نهاية المورد الخاص بك ومفتاح الاشتراك.
هام
انتقل إلى مدخل Azure. إذا تم نشر مورد Personalizer الذي أنشأته في قسم المتطلبات الأساسية بنجاح، فانقر فوق الزر Go to Resource ضمن Next Steps. يمكنك العثور على مفتاحك ونقطة النهاية في صفحة مفتاح المورد ونقطة النهاية ضمن إدارة الموارد.
تذكر إزالة المفتاح من التعليمات البرمجية عند الانتهاء، وعدم نشره على الملأ مطلقًا. للإنتاج، فكر في استخدام طريقة آمنة لتخزين بيانات الاعتماد الخاصة بك والوصول إليها. على سبيل المثال، Azure key vault.
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');
// The key specific to your personalization service instance; e.g. "0123456789abcdef0123456789ABCDEF"
const serviceKey = "<REPLACE-WITH-YOUR-PERSONALIZER-KEY>";
// The endpoint specific to your personalization service instance;
// e.g. https://<your-resource-name>.cognitiveservices.azure.com
const baseUri = "https://<REPLACE-WITH-YOUR-PERSONALIZER-ENDPOINT>.cognitiveservices.azure.com";
تثبيت مكتبة Node.js لـPersonalizer
تثبيت مكتبة عميل Personalizer لـNode.js من خلال الأمر التالي:
npm install @azure/cognitiveservices-personalizer --save
تثبيت حزم NPM المتبقية لهذا التشغيل السريع:
npm install @azure/ms-rest-azure-js @azure/ms-rest-js readline-sync uuid --save
نموذج الكائن
عميل Personalizer هو عنصر PersonalizerClient حيث يقوم بالمصادقة مع Azure باستخدام Microsoft.Rest.ServiceClientCredentials والذي يحتوي على مفتاحك.
لطلب أفضل عنصر من المحتوى، أنشئ RankRequest، ثم مرره إلى أسلوبرتبة العميل. يرسل أسلوب الرتبة RankResponse.
لإرسال مكافأة إلى Personalizer، أنشئ RewardRequest ، ثم مرره إلى أسلوب المكافأة في فئة الأحداث.
تحديد نقاط المكافأة في التشغيل السريع أمر غير مهم. في نظام الإنتاج، يتم تحديد ما يؤثر على نقاط المكافأة وإلى أي مدى يمكن أن يشكّل عملية معقدة، والتي قد تقرر تغييرها مع مرور الوقت. يجب أن يكون هذا أحد قرارات التصميم الأساسية في بنية Personalizer.
أمثلة التعليمات البرمجية
توضح لك هذه الأكواد كيفية القيام بالمهام التالية مع مكتبة عميل Personalizer لـNode.js:
مصادقة العميل
عليك إنشاء مثيل PersonalizerClient مع التطبيق serviceKey الخاص بك وbaseUri الذي قمت بإنشائه في وقت سابق.
const credentials = new CognitiveServicesCredentials(serviceKey);
// Initialize Personalization client.
const personalizerClient = new Personalizer.PersonalizerClient(credentials, baseUri);
الحصول على خيارات المحتوى كإجراءات
تمثل الإجراءات اختيارات المحتوى التي تريد أن يقوم Personalizer من خلالها بتحديد أفضل عنصر محتوى. إضافة الأساليب التالية إلى فئة البرنامج لتمثيل مجموعة الإجراءات والميزات الخاصة بها.
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 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
}
]
}
];
}
إنشاء حلقة التعلم
حلقة تعلم Personalizer هي دورة من استدعاءات الرتبةوالمكافأة. في هذا التشغيل السريع، كل استدعاء للرتبة لإضفاء طابع شخصي على المحتوى يتبعه استدعاء للمكافأة؛ لإخبار Personalizer بمدى جودة أداء الخدمة.
يدور الكود التالي من خلال سؤال المستخدم عن تفضيلاته في صفحة الأوامر وإرسال تلك المعلومات إلى Personalizer لتحديد الإجراء الأفضل وتقديم الخيارات إلى العميل للاختيار من بين القائمة ثم إرسال مكافأة إلى Personalizer تشير إلى نجاح الخدمة.
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);
إلقاء نظرة فاحصة على رتبة ومكافأة الاستدعاءات في الأقسام التالية.
إضافة الأساليب التالية،للحصول على خيارات المحتوىقبل تشغيل ملف الأكواد:
- قائمة getActionsList
- getContextFeaturesList
طلب أفضل إجراء
لإكمال طلب الرتبة، يطلب البرنامج تفضيلات المستخدم لإنشاء خيارات المحتوى. يمكن للعملية إنشاء محتوى للاستبعاد من الإجراءات، كما هو موضح في excludeActions. يحتاج طلب الرتبة إلى الإجراءات والميزات الخاصة بهم، ميزات currentContext، excludeActions، ومعرف حدث الرتبة الفريد لتلقي استجابة الرتبة.
يتضمن التشغيل السريع ميزات بسيطة لتاريخ اليوم وجهاز المستخدم. في أنظمة الإنتاج ، يمكن أن يكون تحديد وتقييمالإجراءات والميزات مسألة غير تافهة.
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);
قم بإرسال مكافأة
للحصول على نقاط المكافأة لإرسالها في طلب المكافأة، يحصل البرنامج على تحديد المستخدم من سطر الأوامر، ويعين قيمة رقمية للاختيار، ثم يرسل ID الحدث الفريد ودرجة المكافأة كقيمة رقمية إلى واجهة برمجة تطبيقات المكافأة.
هذه البداية السريعة تعيّن عددًا بسيطًا كنقاط مكافأة، إما صفر أو 1. في أنظمة الإنتاج يمكن أن يكون تحديد وقت وأهمية استدعاء المكافأة أمرًا غير مهم فهو يعتمد على احتياجاتك الخاصة.
const rewardRequest = {
value: reward
}
await personalizerClient.events.reward(rankRequest.eventId, rewardRequest);
قم بتشغيل البرنامج.
تشغيل التطبيق مع Node.js من دليل التطبيق الخاص بك.
node sample.js
الوثائق المرجعية | رمز مصدر المكتبة | حزمة (PyPi) | عينات
المتطلبات الأساسية
- اشتراك Azure - إنشاء اشتراك مجانًا
- Python 3.x
- بمجرد حصولك على اشتراك Azure، قم بإنشاء مورد Personalizer في مدخل Azure للحصول على المفتاح ونقطة النهاية. بعد انتشاره، انقر فوق Go to resource.
- ستحتاج إلى المفتاح ونقطة النهاية من المورد الذي تنشئه؛ لتوصيل التطبيق الخاص بك بواجهة برمجة تطبيقات Personalizer. ستلصق المفتاح ونقطة النهاية في التعليمات البرمجية أدناه لاحقًا في التشغيل السريع.
- يمكنك استخدام مستوى التسعير الحر (
F0) لتجربة الخدمة، والترقية لاحقًا إلى مستوى مدفوع للإنتاج.
إعداد
تغيير تكرار تحديث النموذج.
في بوابة Azure، في المورد الخاص بـ Personalizer في صفحةالتكوين، غيرتكرار تحديث النموذج إلى 30 ثانية. هذه المدة القصيرة سوف تدرب الخدمة بسرعة، مما يسمح لك برؤية كيفية تغيير الإجراء الأعلى لكل تكرار.
عندما يتم إنشاء حلقة خاصة بـ Personalizer لأول مرة، لا يوجد نموذج نظراً للحظة عدم وجود اتصال واجهة برمجة تطبيقات الخاصة بالمكافأة للتدرب منها. سيرجع ترتيب عملية الاتصال إلى احتمالات متساوية لكل عنصر. يجب أن يظل التطبيق الخاص بك دائماً يصنف المحتوى باستخدام إخراج RewardActionId.
تغيير وقت انتظار المكافأة
في مدخل Azure، في مورد "Personalizer" في صفحة التكوين، قم بتغيير وقت انتظار المكافأة إلى 30 ثانية. هذه المدة القصيرة تسهم في تسريع الخدمة مما يسمح لك برؤية كيفية تغيير الإجراء العلوي لكل تكرار.
تثبيت مكتبة العميل
بعد تثبيت Python، يمكنك تثبيت مكتبة العميل عن طريق:
pip install azure-cognitiveservices-personalizer
إنشاء تطبيق Python جديد
إنشاء ملف جديد بلغة بايثون وإنشاء متغيرات نقطة النهاية ومفتاح الاشتراك الخاص بالموارد.
هام
انتقل إلى مدخل Azure. إذا تم نشر مورد Personalizer الذي أنشأته في قسم المتطلبات الأساسية بنجاح، فانقر فوق الزر Go to Resource ضمن Next Steps. يمكنك العثور على مفتاحك ونقطة النهاية في صفحة مفتاح المورد ونقطة النهاية ضمن إدارة الموارد.
تذكر إزالة المفتاح من التعليمات البرمجية عند الانتهاء، وعدم نشره على الملأ مطلقًا. للإنتاج، فكر في استخدام طريقة آمنة لتخزين بيانات الاعتماد الخاصة بك والوصول إليها. على سبيل المثال، مفتاح مخزن Azure.
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
key = "<paste-your-personalizer-key-here>"
endpoint = "<paste-your-personalizer-endpoint-here>"
نموذج الكائن
عميل Personalizer هو عنصر عميل Personalizer حيث يقوم بالمصادقة مع Azure باستخدام Microsoft.Rest.ServiceClientCredentials والذي يحتوي على مفتاحك.
لطلب أفضل عنصر من المحتوى، أنشئ طلب رتبة، ثم مرره إلى أسلوب تصنيف العميل. ترجع طريقة الترتيب استجابة رتبة.
لإرسال نقاط مكافأة إلى Personalizer، قم بتعيين معرف الحدث ودرجة المكافأة (القيمة) لإرسالها إلى أسلوب المكافأة في فئة عمليات الحدث.
تحديد المكافأة في هذه البدء السريع أمر تافه. في نظام الإنتاج، يتم تحديد ما يؤثر على نقاط المكافأة وإلى أي مدى يمكن أن يشكّل عملية معقدة، والتي قد تقرر تغييرها مع مرور الوقت. يجب أن يكون هذا أحد قرارات التصميم الأساسية في بنية Personalizer.
أمثلة التعليمات البرمجية
توضح لك مقتطفات التعليمات البرمجية تلك كيفية القيام بما يلي باستخدام مكتبة عميل Personalizer لـ Python:
مصادقة العميل
عليك إنشاء مثيل PersonalizerClient مع التطبيق key الخاص بك وendpoint الذي قمت بإنشائه في وقت سابق.
# Instantiate a Personalizer client
client = PersonalizerClient(endpoint, CognitiveServicesCredentials(key))
الحصول على خيارات المحتوى كإجراءات
تمثل الإجراءات اختيارات المحتوى التي تريد أن يقوم Personalizer من خلالها بتحديد أفضل عنصر محتوى. إضافة الأساليب التالية إلى فئة البرنامج لتمثيل مجموعة الإجراءات والميزات الخاصة بها.
def get_actions():
action1 = RankableAction(id='pasta', features=[{"taste":"salty", "spice_level":"medium"},{"nutrition_level":5,"cuisine":"italian"}])
action2 = RankableAction(id='ice cream', features=[{"taste":"sweet", "spice_level":"none"}, { "nutritional_level": 2 }])
action3 = RankableAction(id='juice', features=[{"taste":"sweet", 'spice_level':'none'}, {'nutritional_level': 5}, {'drink':True}])
action4 = RankableAction(id='salad', features=[{'taste':'salty', 'spice_level':'none'},{'nutritional_level': 2}])
return [action1, action2, action3, action4]
def get_user_timeofday():
res={}
time_features = ["morning", "afternoon", "evening", "night"]
time = input("What time of day is it (enter number)? 1. morning 2. afternoon 3. evening 4. night\n")
try:
ptime = int(time)
if(ptime<=0 or ptime>len(time_features)):
raise IndexError
res['time_of_day'] = time_features[ptime-1]
except (ValueError, IndexError):
print("Entered value is invalid. Setting feature value to", time_features[0] + ".")
res['time_of_day'] = time_features[0]
return res
def get_user_preference():
res = {}
taste_features = ['salty','sweet']
pref = input("What type of food would you prefer? Enter number 1.salty 2.sweet\n")
try:
ppref = int(pref)
if(ppref<=0 or ppref>len(taste_features)):
raise IndexError
res['taste_preference'] = taste_features[ppref-1]
except (ValueError, IndexError):
print("Entered value is invalid. Setting feature value to", taste_features[0]+ ".")
res['taste_preference'] = taste_features[0]
return res
إنشاء حلقة التعلم
حلقة التعلم الشخصية هي دورة من استدعاءات الرتبةوالمكافأة. في هذا البدء السريع، يتبع كل استدعاء رتبة، لتخصيص المحتوى، دعوة مكافأة لإخبار Personalizer بمدى جودة أداء الخدمة.
تدور التعليمات البرمجية التالية خلال دورة من سؤال المستخدم عن تفضيلاته في سطر الأوامر، وإرسال تلك المعلومات إلى Personalizer لتحديد الإجراء الأفضل، وتقديم التحديد إلى العميل للاختيار من بين القائمة، ثم إرسال مكافأة إلى Personalizer مشيرًا إلى جودة الخدمة في اختيارها.
keep_going = True
while keep_going:
eventid = str(uuid.uuid4())
context = [get_user_preference(), get_user_timeofday()]
actions = get_actions()
rank_request = RankRequest( actions=actions, context_features=context, excluded_actions=['juice'], event_id=eventid)
response = client.rank(rank_request=rank_request)
print("Personalizer service ranked the actions with the probabilities listed below:")
rankedList = response.ranking
for ranked in rankedList:
print(ranked.id, ':',ranked.probability)
print("Personalizer thinks you would like to have", response.reward_action_id+".")
answer = input("Is this correct?(y/n)\n")[0]
reward_val = "0.0"
if(answer.lower()=='y'):
reward_val = "1.0"
elif(answer.lower()=='n'):
reward_val = "0.0"
else:
print("Entered choice is invalid. Service assumes that you didn't like the recommended food choice.")
client.events.reward(event_id=eventid, value=reward_val)
br = input("Press Q to exit, any other key to continue: ")
if(br.lower()=='q'):
keep_going = False
إضافة الأساليب التالية،للحصول على خيارات المحتوى، قبل تشغيل ملف التعليمات البرمجية:
get_user_preferenceget_user_timeofdayget_actions
قم بطلب أفضل إجراء
لإكمال طلب الرتبة، يطلب البرنامج من تفضيلات المستخدم إنشاء currentContent خيارات المحتوى. يمكن للعملية إنشاء محتوى للاستبعاد من الإجراءات، كما هو موضح في excludeActions. يحتاج طلب الرتبة إلى الإجراءات والميزات الخاصة بهم، ميزات currentContext excludeActions، وID حدث الرتبة الفريد لتلقي استجابة الرتبة.
هذه البداية السريعة لديها ميزات سياق بسيطة من الوقت من اليوم وتفضيل الطعام المستخدم. في أنظمة الإنتاج ، يمكن أن يكون تحديد وتقييمالإجراءات والميزات مسألة غير تافهة.
rank_request = RankRequest( actions=actions, context_features=context, excluded_actions=['juice'], event_id=eventid)
response = client.rank(rank_request=rank_request)
قم بإرسال مكافأة
للحصول على نقاط المكافأة لإرسالها في طلب المكافأة، يحصل البرنامج على تحديد المستخدم من سطر الأوامر، ويعين قيمة رقمية للاختيار، ثم يرسل ID الحدث الفريد ودرجة المكافأة كقيمة رقمية إلى واجهة برمجة تطبيقات المكافأة.
هذه البداية السريعة تعيّن عددًا بسيطًا كنقاط مكافأة، إما صفر أو 1. في أنظمة الإنتاج يمكن أن يكون تحديد وقت وأهمية استدعاء المكافأة أمرًا غير مهم فهو يعتمد على احتياجاتك الخاصة.
reward_val = "0.0"
if(answer.lower()=='y'):
reward_val = "1.0"
elif(answer.lower()=='n'):
reward_val = "0.0"
else:
print("Entered choice is invalid. Service assumes that you didn't like the recommended food choice.")
client.events.reward(event_id=eventid, value=reward_val)
قم بتشغيل البرنامج.
قم بتشغيل التطبيق باستخدام Python من دليل التطبيق الخاص بك.
python sample.py
تنظيف الموارد
إذا كنت تريد تنظيف وإلغاء اشتراك الخدمات المعرفية، يمكنك حذف المورد أو مجموعة الموارد. يؤدي حذف مجموعة الموارد إلى حذف أية موارد أخرى مقترنة بها أيضًا.