بداية سريعة: مكتبة عملاء QnA Maker

  • مقالة

إشعار

يستخدم Azure Open الذكاء الاصطناعي On Your Data نماذج لغة كبيرة (LLMs) لإنتاج نتائج مماثلة ل QnA Maker. إذا كنت ترغب في ترحيل مشروع QnA Maker إلى Azure Open الذكاء الاصطناعي على بياناتك، فيرجى الاطلاع على دليلنا.

ابدأ مع مكتبة عميل QnA Maker. اتبع هذه الخطوات لتثبيت الحزمة وتجربة نموذج تعليمات البرمجة للمهام الأساسية.

إشعار

ستتوقف خدمة QnA Maker في 31 مارس 2025. يتوفر الآن إصدار أحدث من إمكانية السؤال والإجابة كجزء من Azure الذكاء الاصطناعي Language. للحصول على إمكانيات الإجابة على الأسئلة داخل خدمة اللغة، راجع الإجابة على الأسئلة. اعتبارًا من 1 أكتوبر 2022، لن تتمكن من إنشاء موارد QnA Maker جديدة. للحصول على معلومات عن ترحيل قواعد معارف صانع QnA الحالية إلى الإجابة على الأسئلة، راجع دليل الترحيل .

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

إشعار

لا تنطبق تلك الوثائق على أحدث إصدار. للتعرف على استخدام واجهة برمجة تطبيقات REST بأحدث إصدار، انظرالبدء السريع للإجابة على السؤال لواجهة برمجة تطبيقات REST

  • الإصدار الحالي من cURL. يتم استخدام العديد من مفاتيح سطر الأوامر في عمليات التشغيل السريع، والتي تتم الإشارة إليها في وثائق cURL.

  • يجب أن يكون لديك مورد QnA Maker، لاستخدام اسم المفتاح والمورد. لقد أدخلت اسم المورد أثناء إنشاء المورد، ثم تم إنشاء المفتاح لك. يتم استخدام اسم المورد كفرع لنقطة النهاية. لاسترداد اسم المفتاح والمورد، حدد Quickstart لموردك في مدخل Microsoft Azure. اسم المورد هو النطاق الفرعي الأول لعنوان URL نقطة النهاية:

    https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0

تنبيه

تستخدم \ أمثلة BASH التالية حرف متابعة السطر. إذا كانت وحدة التحكم أو المحطة الطرفية الخاصة بك تستخدم حرف متابعة سطر مختلف، فاستخدم هذا الحرف.

إنشاء قاعدة معارف

لإنشاء قاعدة معارف مع واجهات برمجة التطبيقات REST و cURL، تحتاج إلى الحصول على المعلومات التالية:

‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏المعلومات تكوين cURL الغرض
اسم مورد صانع QnA عنوان URL تستخدم لبناء عنوان URL
مفتاح مورد صانع QnA -hمعلمة للعنوان Ocp-Apim-Subscription-Key المصادقة على خدمة QnA Maker
JSON تصف قاعدة المعرفة -d بارام أمثلة على JSON
حجم JSON بالبايت -hمعلمة للعنوان Content-Size

يتم تنفيذ الأمر cURL من BASH shell. قم بتحرير هذا الأمر مع اسم موردك ومفتاح المورد وقيم JSON وحجم JSON.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/create \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:107" \
-d '{ name: "QnA Maker FAQ",urls: [ "https://learn.microsoft.com/azure/ai-services/qnamaker/faqs"]}'

تتضمن operationId استجابة cURL من QnA Maker ، وهو مطلوب للحصول على حالة العملية.

{
  "operationState": "NotStarted",
  "createdTimestamp": "2020-02-27T04:11:22Z",
  "lastActionTimestamp": "2020-02-27T04:11:22Z",
  "userId": "9596077b3e0441eb93d5080d6a15c64b",
  "operationId": "95a4f700-9899-4c98-bda8-5449af9faef8"
}

الحصول على حالة العملية

عند إنشاء قاعدة معارف؛ لأن العملية غير متزامنة، تتضمن الاستجابة معلومات لتحديد الحالة.

‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏المعلومات تكوين cURL الغرض
اسم مورد صانع QnA عنوان URL تستخدم لبناء عنوان URL
معرف ‏‏العملية مسار URL /operations/REPLACE-WITH-YOUR-OPERATION-ID
مفتاح مورد صانع QnA -hمعلمة للعنوان Ocp-Apim-Subscription-Key المصادقة على خدمة QnA Maker

يتم تنفيذ الأمر cURL من BASH shell. قم بتحرير هذا الأمر مع اسم موردك ومفتاح المورد ومعرف العملية.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/operations/REPLACE-WITH-YOUR-OPERATION-ID \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

تتضمن استجابة cURL الحالة. إذا نجحت حالة العملية، فسيتضمن resourceLocation معرف قاعدة المعارف (KB).

{
   "operationState": "Succeeded",
   "createdTimestamp": "2020-02-27T04:54:07Z",
   "lastActionTimestamp": "2020-02-27T04:54:19Z",
   "resourceLocation": "/knowledgebases/fe3971b7-cfaa-41fa-8d9f-6ceb673eb865",
   "userId": "f596077b3e0441eb93d5080d6a15c64b",
   "operationId": "f293f218-d080-48f0-a766-47993e9b26a8"
}

انشر قاعدة معرفية

قبل الاستعلام عن قاعدة المعارف، تحتاج إلى:

  • انشر قاعدة معرفية
  • الحصول على مفتاح نقطة النهاية وقت التشغيل

تنشر هذه المهمة قاعدة المعارف. يعد الحصول على مفتاح نقطة نهاية وقت التشغيل مهمة منفصلة.

‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏المعلومات تكوين cURL الغرض
اسم مورد صانع QnA عنوان URL تستخدم لبناء عنوان URL
مفتاح مورد صانع QnA -hمعلمة للعنوان Ocp-Apim-Subscription-Key المصادقة على خدمة QnA Maker
معرف قاعدة المعارف مسار URL /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

يتم تنفيذ الأمر cURL من BASH shell. قم بتحرير هذا الأمر مع اسم موردك ومفتاح المورد ومعرف أساس المعرفة.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-v \
-X POST \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY" \
--data-raw ''

حالة الاستجابة هي 204 بدون نتائج. استخدم معلمة -v سطر الأوامر لمشاهدة الإخراج المطول لأمر cURL. وهذا يشمل حالة HTTP.

الحصول على مفتاح نقطة النهاية وقت التشغيل لقاعدة المعرفة المنشورة

قبل الاستعلام عن قاعدة المعارف، تحتاج إلى:

  • انشر قاعدة معرفية
  • الحصول على مفتاح نقطة النهاية وقت التشغيل

هذه المهمة تحصل على مفتاح نقطة النهاية وقت التشغيل. يعد نشر قاعدة المعارف (KB) مهمة منفصلة.

مفتاح نقطة النهاية وقت التشغيل هو نفس المفتاح لكافة قواعد المعرفة باستخدام المورد QnA Maker.

‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏المعلومات تكوين cURL الغرض
اسم مورد صانع QnA عنوان URL تستخدم لبناء عنوان URL
مفتاح مورد صانع QnA -hمعلمة للعنوان Ocp-Apim-Subscription-Key المصادقة على خدمة QnA Maker

يتم تنفيذ الأمر cURL من BASH shell. قم بتحرير هذا الأمر مع اسم موردك ومفتاح المورد .

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/endpointkeys \
-X GET \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

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

{
  "primaryEndpointKey": "93e88a14-694a-44d5-883b-184a68aa8530",
  "secondaryEndpointKey": "92c98c16-ca31-4294-8626-6c57454a5063",
  "installedVersion": "4.0.5",
  "lastStableVersion": "4.0.6"
}

الاستعلام عن الإجابة من قاعدة المعارف المنشورة

الحصول على إجابة من المعرفة يتم من وقت تشغيل منفصل عن إدارة قاعدة المعارف. لأنه وقت تشغيل منفصل، تحتاج إلى المصادقة باستخدام مفتاح وقت التشغيل.

‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏المعلومات تكوين cURL الغرض
اسم مورد صانع QnA عنوان URL تستخدم لبناء عنوان URL
QnA Maker مفتاح وقت التشغيل -hمعلمة للعنوان Authorization المفتاح هو جزء من سلسلة تتضمن الكلمة Endpointkey . المصادقة على خدمة QnA Maker
معرف قاعدة المعارف مسار URL /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID
JSON تصف الاستعلام -d بارام طلب معلمات النص الأساسي وأمثلة على JSON
حجم JSON بالبايت -hمعلمة للعنوان Content-Size

يتم تنفيذ الأمر cURL من BASH shell. قم بتحرير هذا الأمر مع اسم موردك ومفتاح المورد ومعرف أساس المعرفة.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.azurewebsites.net/qnamaker/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID/generateAnswer \
-X POST \
-H "Authorization: EndpointKey REPLACE-WITH-YOUR-RUNTIME-KEY" \
-H "Content-Type:application/json" \
-H "Content-Size:159" \
-d '{"question": "How are QnA Maker and LUIS used together?","top": 6,"isTest": true,  "scoreThreshold": 20, "strictFilters": [], "userId": "sd53lsY="}'

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

حذف قاعدة المعارف

عند الانتهاء من قاعدة المعارف، احذفه.

‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏‏المعلومات تكوين cURL الغرض
اسم مورد صانع QnA عنوان URL تستخدم لبناء عنوان URL
مفتاح مورد صانع QnA -hمعلمة للعنوان Ocp-Apim-Subscription-Key المصادقة على خدمة QnA Maker
معرف قاعدة المعارف مسار URL /knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID

يتم تنفيذ الأمر cURL من BASH shell. قم بتحرير هذا الأمر مع اسم موردك ومفتاح المورد ومعرف أساس المعرفة.

curl https://REPLACE-WITH-YOUR-RESOURCE-NAME.cognitiveservices.azure.com/qnamaker/v4.0/knowledgebases/REPLACE-WITH-YOUR-KNOWLEDGE-BASE-ID \
-X DELETE \
-v \
-H "Ocp-Apim-Subscription-Key: REPLACE-WITH-YOUR-RESOURCE-KEY"

حالة الاستجابة هي 204 بدون نتائج. استخدم معلمة -v سطر الأوامر لمشاهدة الإخراج المطول لأمر cURL. وهذا يشمل حالة HTTP.

الموارد الإضافية

استخدم مكتبة عميل QnA Maker لـ .NET من أجل:

  • إنشاء قاعدة معارف
  • تحديث قاعدة معارف
  • نشر قاعدة معارف
  • الحصول على مفتاح نقطة نهاية وقت تشغيل التنبؤ
  • انتظر المهمة طويلة الأمد
  • تنزيل قاعدة معارف
  • الحصول على إجابة من قاعدة معارف
  • حذف قاعدة معارف

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

إشعار

الموارد الجديدة التي تم إنشاؤها بعد 1 يوليو 2019 ستستخدم أسماء النطاقات الفرعية المخصصة. لمزيد من المعلومات وقائمة كاملة بنقاط النهاية الإقليمية، راجع أسماء النطاقات الفرعية المخصصة لخدمات Azure الذكاء الاصطناعي.

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

إشعار

لا تنطبق تلك الوثائق على أحدث إصدار. للتعرف على استخدام واجهة برمجة تطبيقات C# بأحدث إصدار، انظرالبدء السريع للإجابة على السؤال لواجهة برمجة تطبيقات C#‎.

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

الإعداد

CLI

في نافذة وحدة تحكم (مثل cmd أو PowerShell أو Bash)، استخدم الأمر ⁧dotnet new⁩ لإنشاء تطبيق وحدة تحكم جديد بالاسم ⁧qna-maker-quickstart⁩. ينشئ هذا الأمر مشروع مرحبًا بالعالم «Hello World» بلغة C#‎ بسيطًا مع ملف مصدر واحد: program.cs.

dotnet new console -n qna-maker-quickstart

غيّر دليلك إلى مجلد التطبيق المنشأ حديثاً. يمكنك إنشاء التطبيق باستخدام:

dotnet build

يجب ألا يحتوي إخراج البناء على تحذيرات أو أخطاء.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

ثبت مكتبة عميل Maker QnA لـ .NET داخل دليل التطبيق باستخدام الأمر التالي:

dotnet add package Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker --version 2.0.1

تلميح

هل تريد عرض ملف التعليمات البرمجية للبدء السريع بالكامل في الحال؟ يُمكن العثور على GitHub، والذي يحتوي على أمثلة التعليمات البرمجية في التشغيل السريع.

استخدام التوجيهات

من دليل المشروع، افتح الملف program.cs ثم أضف التوجيهات using التالية:

using Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker;
using Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker.Models;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

مفتاح الاشتراك ونقاط نهاية المورد

في أسلوب التطبيق Main، قم بإضافة المتغيرات والتعليمات البرمجية، الموضحة في القسم التالي، لاستخدام المهام الشائعة في هذه البداية السريعة.

  • نحن نستخدم مفتاح الاشتراك ومفتاح التأليف بالتبادل. لمزيد من التفاصيل حول مفتاح التأليف، اتبع المفاتيح في QnA Maker.

  • قيمة QNA_MAKER_ENDPOINT تكون بتنسيق https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. انتقل إلى مدخل Azure وابحث عن مورد QnA Maker الذي أنشأته في المتطلبات الأساسية. انقر على صفحة Keys and Endpoint، ضمن resource management لتحديد موقع مفتاح التأليف (الاشتراك) ونقطة نهاية QnA Maker.

نقطة نهاية تأليف QnA Maker

  • قيمة QNA_MAKER_RUNTIME_ENDPOINT تكون بتنسيق https://YOUR-RESOURCE-NAME.azurewebsites.net. انتقل إلى مدخل Azure وابحث عن مورد QnA Maker الذي أنشأته في المتطلبات الأساسية. انقر على صفحة Export Template، من Automation لتحديد موقع نقطة نهاية وقت التشغيل.

نقطة نهاية وقت تشغيل QnA Maker

هام

تذكر إزالة المفتاح من التعليمة البرمجية عند الانتهاء، وعدم توزيعها علناً. للإنتاج، استخدم طريقة آمنة لتخزين بيانات الاعتماد والوصول إليها مثل Azure Key Vault. راجع مقالة أمان خدمات Azure الذكاء الاصطناعي للحصول على مزيد من المعلومات.

var authoringKey = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
var authoringURL = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
var queryingURL = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

نماذج الكائن

يستخدم QnA Maker نموذجين مختلفين للكائنات:

  • QnAMakerClient هو الكائن المستخدم لإنشاء قاعدة المعارف، وإدارتها، ونشرها، وتنزيلها.
  • QnAMakerRuntime هو الكائن المستخدم للاستعلام عن قاعدة المعارف باستخدام GenerateAnswer API وإرسال أسئلة جديدة مقترحة باستخدام Train API (كجزء من التعلم النشط).

استخدام هذا المثال لقاعدة المعارف.

قاعدة المعارف في هذا التشغيل السريع تبدأ مع 2 من أزواج محادثة QnA، ويتم ذلك عن قصد لتبسيط المثال والحصول على معرفات هوية يمكن التنبؤ بها للغاية لاستخدامها في أسلوب التحديث، وربط مطالبات المتابعة مع أسئلة الأزواج جديدة. وقد تم التخطيط لذلك وتنفيذه بترتيب محدد من أجل هذا التشغيل السريع.

إذا كنت تخطط لتطوير قاعدة المعارف الخاصة بك مع مرور الوقت مع مطالبات المتابعة التي تعتمد على أزواج QnA الموجودة، يمكنك اختيار:

  • بالنسبة إلى قواعد المعرفة الأكبر، قم بإدارة قاعدة المعارف في محرر نصوص أو أداة TSV التي تدعم التشغيل التلقائي، ثم استبدل قاعدة المعارف بالكامل مرة واحدة التحديث.
  • للحصول على قاعدة معارف أصغر، قم بإدارة مطالبات المتابعة بالكامل في بوابة QnA Maker.

تفاصيل حول أزواج QnA المستخدمة في هذه البداية السريعة:

  • أنواع زوج QnA - هناك نوعان من أزواج QnA في قاعدة المعرفة هذه ، بعد التحديث: chitchat ومعلومات خاصة بالنطاق هذا الأمر نمطي إذا تم ربط قاعدة المعرفة الخاصة بك إلى تطبيق محادثة مثل chatbot.
  • في حين يمكن تصفية إجابات قاعدة المعرفة من قبل بيانات التعريف أو استخدام مطالبات المتابعة، هذه البداية السريعة لا تُظهر ذلك. ابحث عن أمثلة إنشاء إجابات حيادية اللغة هنا.
  • نص الإجابة هو تخفيض السعر ويمكن أن يحتوي علىمجموعة متنوعة من التخفيضات مثل الصور (الصور المتاحة للجمهور على الإنترنت) ، والروابط (لعناوين URL المتاحة للجمهور) ، والنقاط ، ولا تستخدم هذه البداية السريعة هذا التنوع.

نموذج كائن QnAMakerClient

عميل تأليف QnA Maker هو كائن QnAMakerClient الذي يصادق Azure باستخدام Microsoft.Rest.ServiceClientCredentials الذي يحتوي على مفتاحك.

بمجرد إنشاء حساب العميل، استخدم خاصية قاعدة المعارف لإنشاء قاعدة المعارف وإدارتها ونشرها.

إدارة قاعدة المعارف الخاصة بك عن طريق إرسال كائن JSON. بالنسبة إلى العمليات الفورية، عادةً ما تُرجع الطريقة كائن JSON الذي يشير إلى الحالة. بالنسبة إلى العمليات طويلة الأمد، تكون الإجابة هي معرف العملية. استدعي الطريقة client.Operations.GetDetailsAsync بمعرف العملية لتحديد حالة الطلب.

نموذج كائن QnAMakerRuntimeClient

عميل توقع QnA Maker هو كائن QnAMakerRuntimeClient الذي يصادق Azure باستخدام Microsoft.Rest.ServiceClientCredentials، الذي يحتوي على مفتاح وقت التشغيل التوقع الذي أُعيد بطلب من عميل التأليفclient.EndpointKeys.GetKeys بعد نشر قاعدة المعرفة.

استخدم طريقة إنشاء الإجابة للحصول على إجابة من وقت تشغيل الاستعلام.

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

توضح لك هذه المقتطفات البرمجية كيفية تنفيذ ما يلي باستخدام QnA Maker client library for .NET:

المصادقة على العميل لتأليف قاعدة المعرفة

إنشاء كائن للعميل بمفتاحك، واستخدامه مع موردك لإنشاء نقطة نهاية لإصدار QnAMakerClient مع نقطة النهاية والمفتاح الخاصين بك. إنشاء كائن ServiceClientCredentials.

var client = new QnAMakerClient(new ApiKeyServiceClientCredentials(authoringKey))
{ Endpoint = authoringURL };

إنشاء قاعدة معارف

تخزن قاعدة المعارف أزواج الأسئلة والأجوبة للكائن CreateKbDTO من ثلاثة مصادر:

  • لـالمحتوى التحريري، استخدم الكائن QnADTO.
    • لاستخدام بيانات التعريف ومتابعة المطالبات، استخدم السياق التحريري، لأنه تتم إضافة هذه البيانات على مستوى زوج QnA الفردية.
  • بالنسبة إلى الملفات، استخدم الكائن FileDTO. يتضمن FileDTO اسم الملف وعنوان URL العام للوصول إلى الملف.
  • بالنسبة إلى عناوين URL، استخدم قائمة سلاسل لتمثيل عناوين URL المتاحة للجمهور.

تتضمن خطوة الإنشاء أيضًا خصائص قاعدة المعارف:

  • defaultAnswerUsedForExtraction - ما يتم إرجاعه في حالة عدم العثور على إجابة
  • enableHierarchicalExtraction - إنشاء علاقات موجهة تلقائيًا بين أزواج QnA المستخرجة
  • language - عند إنشاء قاعدة المعرفة الأولى لمورد، قم بتعيين اللغة لاستخدامها في فهرس بحث Azure.

اطلب طريقة CreateAsync ثم مرّر مُعرف العملية الذي تم إرجاعه إلى طريقة Operations.getDetails للاستقصاء عن الحالة.

يقوم السطر الأخير من الكود التالي بإرجاع مُعرف قاعدة المعارف من استجابة MonitorOperation.

private static async Task<string> CreateSampleKb(IQnAMakerClient client)
{
    var qna1 = new QnADTO
    {
        Answer = "Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        Questions = new List<string> { "How do I manage my knowledgebase?" },
        Metadata = new List<MetadataDTO> {
            new MetadataDTO { Name = "Category", Value = "api" },
            new MetadataDTO { Name = "Language", Value = "REST" }
        },

    };

    var qna2 = new QnADTO
    {
        Answer = "Yes, You can use our [.NET SDK](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Knowledge.QnAMaker) with the [.NET Reference Docs](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.knowledge.qnamaker?view=azure-dotnet) to manage your knowledge base.",
        Questions = new List<string> { "Can I program with C#?" },
        Metadata = new List<MetadataDTO> {
            new MetadataDTO { Name = "Category", Value = "api" },
            new MetadataDTO { Name = "Language", Value = ".NET" }
        }
    };

    var file1 = new FileDTO
    {
        FileName = "myfile.tsv",
        FileUri = "https://mydomain/myfile.tsv"

    };

    var createKbDto = new CreateKbDTO
    {
        Name = "QnA Maker .NET SDK Quickstart",
        QnaList = new List<QnADTO> { qna1, qna2 },
        //Files = new List<FileDTO> { file1 }

    };

    var createOp = await client.Knowledgebase.CreateAsync(createKbDto);
    createOp = await MonitorOperation(client, createOp);

    return createOp.ResourceLocation.Replace("/knowledgebases/", string.Empty);
}

تأكد من تضمين الدالة MonitorOperation، المشار إليها في التعليمات البرمجية أعلاه، من أجل إنشاء قاعدة معارف بنجاح.

تحديث قاعدة المعرفة

يمكنك تحديث قاعدة معارف عن طريق تمرير معرف قاعدة المعارف وUpdateKbOperationDTO الذي يحتوي على إضافةوتحديثوحذف كائنات DTO إلى طريقة UpdateAsync. استخدم طريقة Operation.getDetail لتحديد ما إذا كان التحديث ناجحًا.

private static async Task UpdateKB(IQnAMakerClient client, string kbId)
{

    var urls = new List<string> {
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    };

    var updateOp = await client.Knowledgebase.UpdateAsync(kbId, new UpdateKbOperationDTO
    {
        // Create JSON of changes
        Add = new UpdateKbOperationDTOAdd
        {
            QnaList = new List<QnADTO> {
                new QnADTO {
                    Questions = new List<string> {
                        "bye",
                        "end",
                        "stop",
                        "quit",
                        "done"
                    },
                    Answer = "goodbye",
                    Metadata = new List<MetadataDTO> {
                        new MetadataDTO { Name = "Category", Value="Chitchat" },
                        new MetadataDTO { Name = "Chitchat", Value = "end" },
                    }
                },
                new QnADTO {
                    Questions = new List<string> {
                        "hello",
                        "hi",
                        "start"
                    },
                    Answer = "Hello, please select from the list of questions or enter a new question to continue.",
                    Metadata = new List<MetadataDTO> {
                        new MetadataDTO { Name = "Category", Value="Chitchat" },
                        new MetadataDTO { Name = "Chitchat", Value = "begin" }
                    },
                    Context = new QnADTOContext
                    {
                        IsContextOnly = false,
                        Prompts = new List<PromptDTO>
                        {
                            new PromptDTO
                            {
                                DisplayOrder =1,
                                DisplayText= "Use REST",
                                QnaId=1

                            },
                            new PromptDTO
                            {
                                DisplayOrder =2,
                                DisplayText= "Use .NET NuGet package",
                                QnaId=2

                            },
                        }
                    }
                },
            },
            Urls = urls
        },
        Update = null,
        Delete = null
    }); ;

    // Loop while operation is success
    updateOp = await MonitorOperation(client, updateOp);
}

تأكد من تضمين الوظيفةMonitorOperation، المشار إليها في التعليمة البرمجية أعلاها، من أجل تحديث قاعدة المعرفة بنجاح.

قم بتنزيل قاعدة المعرفة

استخدم طريقة DownloadAsync لتحميل قاعدة البيانات كقائمة QnADocumentsDTO. هذا لا يعادل تصدير مدخل QnA Maker من صفحة الإعدادات؛ لأن نتيجة هذه الطريقة ليست ملف.

private static async Task DownloadKb(IQnAMakerClient client, string kbId)
{
    var kbData = await client.Knowledgebase.DownloadAsync(kbId, EnvironmentType.Prod);
    Console.WriteLine("KB Downloaded. It has {0} QnAs.", kbData.QnaDocuments.Count);

    // Do something meaningful with data
}

نشر قاعدة معارف

نشر قاعدة المعارف باستخدام طريقة PublishAsync. وهذا يأخذ النموذج المحفوظ والمدرب الحالي، المُشار إليه بمُعرف قاعدة المعارف، ثم ينشر ذلك عند نقطة النهاية الخاصة بك. هذه خطوة ضرورية للاستعلام عن قاعدة المعارف الخاصة بك.

private static async Task PublishKb(IQnAMakerClient client, string kbId)
{
    await client.Knowledgebase.PublishAsync(kbId);
}

الحصول على مفتاح وقت تشغيل الاستعلام

بمجرد نشر knowledgebase، تحتاج مفتاح وقت تشغيل الاستعلام للاستعلام عن وقت التشغيل. وهذا ليس نفس المفتاح المستخدم لإنشاء كائن العميل الأصلي.

استخدم طريقة EndpointKeys للحصول على فئة EndpointKeysDTO.

استخدم أي من خصائص المفتاح التي تم إرجاعها في الكائن للاستعلام عن قاعدة المعارف.

private static async Task<String> GetQueryEndpointKey(IQnAMakerClient client)
{
    var endpointKeysObject = await client.EndpointKeys.GetKeysAsync();

    return endpointKeysObject.PrimaryEndpointKey;
}

مفتاح وقت التشغيل ضروري للاستعلام عن قاعدة المعارف الخاصة بك.

مصادقة وقت التشغيل لإنشاء إجابة

إنشاء QnAMakerRuntimeClient للاستعلام في قاعدة المعارف لإنشاء إجابة أو التدريب من خلال التعلم النشط.

var runtimeClient = new QnAMakerRuntimeClient(new EndpointKeyServiceClientCredentials(primaryQueryEndpointKey))
{ RuntimeEndpoint = queryingURL };

استخدم QnAMakerRuntimeClient لـ:

  • الحصول على إجابة من قاعدة المعرفة
  • إرسال أسئلة مقترحة جديدة إلى قاعدة المعرفة للتعلم النشط.

إنشاء إجابة من قاعدة المعرفة

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

private static async Task GenerateAnswer(IQnAMakerRuntimeClient runtimeClient, string kbId)
{
    var response = await runtimeClient.Runtime.GenerateAnswerAsync(kbId, new QueryDTO { Question = "How do I manage my knowledgebase?" });
    Console.WriteLine("Endpoint Response: {0}.", response.Answers[0].Answer);

    // Do something meaningful with answer
}

هذا مثال بسيط للاستعلام في قاعدة المعارف. لفهم سيناريوهات الاستعلام المتقدمة، راجع أمثلة أخرى عن الاستعلام.

تحديث قاعدة معارف

حذف قاعدة المعارف باستخدام طريقة DeleteAsync مع مُعلم مُعرف قاعدة المعارف.

private static async Task DeleteKB(IQnAMakerClient client, string kbId)
{
    await client.Knowledgebase.DeleteAsync(kbId);
}

الحصول على حالة عملية

بعض الطرق، مثل الإنشاء والتحديث، يمكن أن تستغرق وقتًا كافيًا بدلًا من انتظار انتهاء العملية، لتُستكمل العملية. استخدم معرف العملية من العملية للاستطلاع (بمنطق إعادة المحاولة) لتحديد حالة الطريقة الأصلية.

يتم استخدام الحلقة وTask.Delay في كتلة التعليمة البرمجية التالية لمحاكاة منطق إعادة المحاولة. يجب استبدالها مع منطق إعادة المحاولة الخاص بك.

private static async Task<Operation> MonitorOperation(IQnAMakerClient client, Operation operation)
{
    // Loop while operation is success
    for (int i = 0;
        i < 20 && (operation.OperationState == OperationStateType.NotStarted || operation.OperationState == OperationStateType.Running);
        i++)
    {
        Console.WriteLine("Waiting for operation: {0} to complete.", operation.OperationId);
        await Task.Delay(5000);
        operation = await client.Operations.GetDetailsAsync(operation.OperationId);
    }

    if (operation.OperationState != OperationStateType.Succeeded)
    {
        throw new Exception($"Operation {operation.OperationId} failed to completed.");
    }
    return operation;
}

شغّل التطبيق

شغل التطبيق من دليل تطبيقك باستخدام الأمر dotnet run.

dotnet run

يمكن العثور على التعليمات البرمجية المصدر لهذه النماذج على GitHub.

استخدم QnA Maker client library for Node.js من أجل:

  • إنشاء قاعدة معارف
  • تحديث قاعدة معارف
  • نشر قاعدة معارف
  • الحصول على مفتاح نقطة نهاية وقت تشغيل التنبؤ
  • انتظر المهمة طويلة الأمد
  • تنزيل قاعدة معارف
  • الحصول على إجابة من قاعدة معارف
  • حذف قاعدة المعارف

حزمة الوثائق | المرجعية (npm) | Node.js عينات

إشعار

الموارد الجديدة التي تم إنشاؤها بعد 1 يوليو 2019 ستستخدم أسماء النطاقات الفرعية المخصصة. لمزيد من المعلومات وقائمة كاملة بنقاط النهاية الإقليمية، راجع أسماء النطاقات الفرعية المخصصة لخدمات Azure الذكاء الاصطناعي.

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

  • اشتراك Azure - إنشاء اشتراك مجانًا
  • الإصدار الحالي من Node.js.
  • بمجرد اشتراكك في Azure، أنشئ مورد QnA Maker في مدخل Azure للحصول على مفتاح التأليف والمورد. بعد انتشاره، حدد "Go to resource".
    • ستحتاج إلى اسم المفتاح واسم المورد من المورد الذي تنشئه لتوصيل تطبيقك بـ QnA Maker API. لصق اسم المفتاح والمورد في التعليمات البرمجية أدناه لاحقًا في التشغيل السريع.
    • يمكنك استخدام مستوى التسعير الحر (F0) لتجربة الخدمة، والترقية لاحقًا إلى مستوى مدفوع للإنتاج.

الإعداد

إنشاء تطبيق Node.js جديد

في إطار نافذة وحدة التحكم (مثل cmd أو PowerShell أو Bash)، يمكنك إنشاء دليل جديد لتطبيقك وانتقل إليه.

mkdir qnamaker_quickstart && cd qnamaker_quickstart

شغّل الأمر npm init -y لإنشاء تطبيق node باستخدام ملف package.json.

npm init -y

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

تثبيت حزم NPM التالية:

npm install @azure/cognitiveservices-qnamaker
npm install @azure/cognitiveservices-qnamaker-runtime
npm install @azure/ms-rest-js

يتم تحديث ملف تطبيقك package.json باستخدام التبعيات.

أنشئ ملفًا يسمى index.js ثم استرد المكتبات التالية:

const msRest = require("@azure/ms-rest-js");
const qnamaker = require("@azure/cognitiveservices-qnamaker");
const qnamaker_runtime = require("@azure/cognitiveservices-qnamaker-runtime");

أنشئ متغيرًا لمفتاح المورد الخاص بك Azure واسم المورد.

  • نحن نستخدم مفتاح الاشتراك ومفتاح التأليف بالتبادل. لمزيد من التفاصيل حول مفتاح التأليف، اتبع المفاتيح في QnA Maker.

  • قيمة QNA_MAKER_ENDPOINT تكون بتنسيق https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. انتقل إلى مدخل Azure وابحث عن مورد QnA Maker الذي أنشأته في المتطلبات الأساسية. انقر على صفحة Keys and Endpoint، ضمن resource management لتحديد موقع مفتاح التأليف (الاشتراك) ونقطة نهاية QnA Maker.

نقطة نهاية تأليف QnA Maker

  • قيمة QNA_MAKER_RUNTIME_ENDPOINT تكون بتنسيق https://YOUR-RESOURCE-NAME.azurewebsites.net. انتقل إلى مدخل Azure وابحث عن مورد QnA Maker الذي أنشأته في المتطلبات الأساسية. انقر على صفحة Export Template، من Automation لتحديد موقع نقطة نهاية وقت التشغيل.

نقطة نهاية وقت تشغيل QnA Maker

هام

تذكر إزالة المفتاح من التعليمة البرمجية عند الانتهاء، وعدم توزيعها علناً. للإنتاج، استخدم طريقة آمنة لتخزين بيانات الاعتماد والوصول إليها مثل Azure Key Vault. راجع مقالة أمان خدمات Azure الذكاء الاصطناعي للحصول على مزيد من المعلومات.

const subscription_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
const endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
const runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

نماذج الكائن

يستخدم QnA Maker نموذجين مختلفين للكائنات:

  • QnAMakerClient هو الكائن المستخدم لإنشاء قاعدة المعارف، وإدارتها، ونشرها، وتنزيلها.
  • QnAMakerRuntime هو الكائن المستخدم للاستعلام عن قاعدة المعارف باستخدام GenerateAnswer API وإرسال أسئلة جديدة مقترحة باستخدام Train API (كجزء من التعلم النشط).

نموذج كائن QnAMakerClient

عميل تأليف QnA Maker هو كائن QnAMakerClient الذي يصادق Azure باستخدام بيانات اعتمادك، التي تحتوي على مفتاحك.

بمجرد إنشاء العميل، استخدم خاصية قاعدة المعارف لإنشاء قاعدة المعارف، وإدارتها، ونشرها.

إدارة قاعدة المعارف الخاصة بك عن طريق إرسال كائن JSON. بالنسبة إلى العمليات الفورية، عادةً ما تُرجع الطريقة كائن JSON الذي يشير إلى الحالة. بالنسبة إلى العمليات طويلة الأمد، تكون الإجابة هي معرف العملية. استدعي الطريقة client.operations.getDetails بمعرف العملية لتحدد حالة الطلب.

نموذج كائن QnAMakerRuntimeClient

عميل QnA Maker المتوقع هو كائن QnAMakerRuntimeClient الذي يصادق Azure باستخدام Microsoft.Rest.ServiceClientCredentials، الذي يحتوي على مفتاح وقت التشغيل التوقع، الذي تم استعادته بطلب من عميل التأليف، client.EndpointKeys.getKeys بعد نشر قاعدة المعارف.

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

توضح لك هذه المقتطفات البرمجية كيفية تنفيذ ما يلي باستخدام QnA Maker client library for .NET:

المصادقة على العميل لتأليف قاعدة المعرفة

إنشاء مثيل لعميل باستخدام نقطة النهاية والمفتاح. أنشئ كائن ServiceClientCredentials باستخدام مفتاحك، واستخدمه مع نقطة النهاية لإنشاء كائن QnAMakerClient.

const creds = new msRest.ApiKeyCredentials({ inHeader: { 'Ocp-Apim-Subscription-Key': subscription_key } });
const qnaMakerClient = new qnamaker.QnAMakerClient(creds, endpoint);
const knowledgeBaseClient = new qnamaker.Knowledgebase(qnaMakerClient);

إنشاء قاعدة معارف

تخزن قاعدة المعارف أزواج الأسئلة والأجوبة للكائن CreateKbDTO من ثلاثة مصادر:

  • لـالمحتوى التحريري، استخدم الكائن QnADTO.
    • لاستخدام بيانات التعريف ومتابعة المطالبات، استخدم السياق التحريري، لأنه تتم إضافة هذه البيانات على مستوى زوج QnA الفردية.
  • بالنسبة إلى الملفات، استخدم الكائن FileDTO. يتضمن FileDTO اسم الملف وعنوان URL العام للوصول إلى الملف.
  • بالنسبة إلى عناوين URL، استخدم قائمة سلاسل لتمثيل عناوين URL المتاحة للجمهور.

تتضمن خطوة الإنشاء أيضًا خصائص قاعدة المعارف:

  • defaultAnswerUsedForExtraction - ما يتم إرجاعه في حالة عدم العثور على إجابة
  • enableHierarchicalExtraction - إنشاء علاقات موجهة تلقائيًا بين أزواج QnA المستخرجة
  • language - عند إنشاء قاعدة المعرفة الأولى لمورد، قم بتعيين اللغة لاستخدامها في فهرس بحث Azure.

استدعي طريقة الإنشاء مع معلومات قاعدة المعارف. معلومات قاعدة المعارف هي أساسا كائن JSON في الأساس.

عند إرجاع طريقة الإنشاء، مرر معرف العملية الذي تم إرجاعه إلى طريقة wait_for_operation لاستطلاع الحالة. ترجع طريقة wait_for_operation عند اكتمال العملية. تحليل resourceLocation قيمة عنوان العملية التي تم إرجاعها للحصول على معرف قاعدة المعارف الجديدة.

const createKnowledgeBase = async (qnaClient, kbclient) => {

    console.log(`Creating knowledge base...`)

    const qna1 = {
        answer: "Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        questions: ["How do I manage my knowledgebase?"],
        metadata: [
            { name: "Category", value: "api" },
            { name: "Language", value: "REST" }
        ]
    };

    const qna2 = {
        answer: "Yes, You can use our JS SDK on NPM for [authoring](https://www.npmjs.com/package/@azure/cognitiveservices-qnamaker), [query runtime](https://www.npmjs.com/package/@azure/cognitiveservices-qnamaker-runtime), and [the reference docs](https://docs.microsoft.com/en-us/javascript/api/@azure/cognitiveservices-qnamaker/?view=azure-node-latest) to manage your knowledge base.",
        questions: ["How do I manage my knowledgebase?"],
        metadata: [
            { name: "Category", value: "api" },
            { name: "Language", value: "JavaScript" }
        ]
    };

    const create_kb_payload = {
        name: 'QnA Maker JavaScript SDK Quickstart',
        qnaList: [
            qna1,
            qna2
        ],
        urls: [],
        files: [
            /*{
                fileName: "myfile.md",
                fileUri: "https://mydomain/myfile.md"
            }*/
        ],
        defaultAnswerUsedForExtraction: "No answer found.",
        enableHierarchicalExtraction: true,
        language: "English"
    };

    const results = await kbclient.create(create_kb_payload)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Create request failed - HTTP status ${results._response.status}`)
        return
    }

    const operationResult = await wait_for_operation(qnaClient, results.operationId)

    if (!operationResult || !operationResult.operationState || !(operationResult.operationState = "Succeeded") || !operationResult.resourceLocation) {
        console.log(`Create operation state failed - HTTP status ${operationResult._response.status}`)
        return
    }

    // parse resourceLocation for KB ID
    const kbID = operationResult.resourceLocation.replace("/knowledgebases/", "");

    return kbID;
}

تأكد من تضمين الدالة wait_for_operation، المشار إليها في التعليمات البرمجية أعلاه، من أجل إنشاء قاعدة معارف بنجاح.

تحديث قاعدة المعرفة

يمكنك تحديث قاعدة معارف عن طريق تمرير معرف قاعدة المعارف وUpdateKbOperationDTO الذي يحتوي على إضافة، وتحديث، وحذف كائنات DTO إلى طريقة التحديث. DTOs هي أيضًا كائنات JSON في الأساس. استخدم طريقة wait_for_operation لتحديد ما إذا كان التحديث ناجحًا.

const updateKnowledgeBase = async (qnaClient, kbclient, kb_id) => {

    console.log(`Updating knowledge base...`)

    const urls = [
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    ]

    const qna3 = {
        answer: "goodbye",
        questions: [
            "bye",
            "end",
            "stop",
            "quit",
            "done"
        ],
        metadata: [
            { name: "Category", value: "Chitchat" },
            { name: "Chitchat", value: "end" }
        ]
    };

    const qna4 = {
        answer: "Hello, please select from the list of questions or enter a new question to continue.",
        questions: [
            "hello",
            "hi",
            "start"
        ],
        metadata: [
            { name: "Category", value: "Chitchat" },
            { name: "Chitchat", value: "begin" }
        ],
        context: {
            isContextOnly: false,
            prompts: [
                {
                    displayOrder: 1,
                    displayText: "Use REST",
                    qna: null,
                    qnaId: 1
                },
                {
                    displayOrder: 2,
                    displayText: "Use JS NPM package",
                    qna: null,
                    qnaId: 2
                },
            ]
        }
    };

    console.log(JSON.stringify(qna4))

    // Add new Q&A lists, URLs, and files to the KB.
    const kb_add_payload = {
        qnaList: [
            qna3,
            qna4
        ],
        urls: urls,
        files: []
    };

    // Bundle the add, update, and delete requests.
    const update_kb_payload = {
        add: kb_add_payload,
        update: null,
        delete: null,
        defaultAnswerUsedForExtraction: "No answer found. Please rephrase your question."
    };

    console.log(JSON.stringify(update_kb_payload))

    const results = await kbclient.update(kb_id, update_kb_payload)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Update request failed - HTTP status ${results._response.status}`)
        return false
    }

    const operationResult = await wait_for_operation(qnaClient, results.operationId)

    if (operationResult.operationState != "Succeeded") {
        console.log(`Update operation state failed - HTTP status ${operationResult._response.status}`)
        return false
    }

    console.log(`Update operation state ${operationResult._response.status} - HTTP status ${operationResult._response.status}`)
    return true
}

تأكد من تضمين الدالة wait_for_operation، المشار إليها في التعليمات البرمجية أعلاه، من أجل تحديث قاعدة معارف بنجاح.

قم بتنزيل قاعدة المعرفة

استخدم طريقة التحميل لتحميل قاعدة البيانات كقائمة QnADocumentsDTO. هذا لا يعادل تصدير مدخل QnA Maker من صفحة "Settings" لأن نتيجة هذه الطريقة ليست ملف TSV.

const downloadKnowledgeBase = async (KBclient, kb_id) => {

    console.log(`Downloading knowledge base...`)

    var kbData = await KBclient.download(kb_id, "Prod");
    console.log(`Knowledge base downloaded. It has ${kbData.qnaDocuments.length} QnAs.`);

    // Do something meaningful with data
}

نشر قاعدة معارف

نشر قاعدة المعارف باستخدام طريقة النشر. وهذا يأخذ النموذج الحالي المحفوظة والمدرب، المشار إليه بواسطة معرف قاعدة المعارف، ثم ينشر ذلك في نقطة نهاية. تحقق من التعليمات البرمجية للاستجابة HTTP للتحقق من نجاح النشر.

const publishKnowledgeBase = async (kbclient, kb_id) => {

    console.log(`Publishing knowledge base...`)

    const results = await kbclient.publish(kb_id)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Publish request failed - HTTP status ${results._response.status}`)
        return false
    }

    console.log(`Publish request succeeded - HTTP status ${results._response.status}`)

    return true
}

الاستعلام عن قاعدة معارف

الحصول على مفتاح وقت تشغيل الاستعلام

بمجرد نشر knowledgebase، تحتاج مفتاح وقت تشغيل الاستعلام للاستعلام عن وقت التشغيل. وهذا ليس نفس المفتاح المستخدم لإنشاء كائن العميل الأصلي.

استخدم طريقة EndpointKeys.getKeys للحصول على فئة EndpointKeysDTO.

استخدم أي من خصائص المفتاح التي تم إرجاعها في الكائن للاستعلام عن قاعدة المعارف.

const getEndpointKeys = async (qnaClient) => {

    console.log(`Getting runtime endpoint keys...`)

    const runtimeKeysClient = await qnaClient.endpointKeys;
    const results = await runtimeKeysClient.getKeys()

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`GetEndpointKeys request failed - HTTP status ${results._response.status}`)
        return null
    }

    console.log(`GetEndpointKeys request succeeded - HTTP status ${results._response.status} - primary key ${results.primaryEndpointKey}`)

    return results.primaryEndpointKey
}

مصادقة وقت التشغيل لإنشاء إجابة

إنشاء QnAMakerRuntimeClient للاستعلام عن قاعدة المعارف لإنشاء إجابة أو تدريب من التعلم النشط.

const queryRuntimeCredentials = new msRest.ApiKeyCredentials({ inHeader: { 'Authorization': 'EndpointKey ' + primaryQueryRuntimeKey } });
const runtimeClient = new qnamaker_runtime.QnAMakerRuntimeClient(queryRuntimeCredentials, runtime_endpoint);

استخدم QnAMakerRuntimeClient للحصول على إجابة من قاعدة المعارف أو لإرسال أسئلة مقترحة جديدة إلى قاعدة المعارف للتعلم النشط.

إنشاء إجابة من قاعدة المعرفة

إنشاء إجابة من قاعدة معارف منشورة باستخدام أسلوب RuntimeClient.runtime.generateAnswer. تقبل هذه الطريقة مُعرف قاعدة المعارف وQueryDTO. الوصول إلى خصائص إضافية من QueryDTO، مثل أعلىوسياق لاستخدامها في بوت الدردشة الخاص بك.

const generateAnswer = async (runtimeClient, runtimeKey, kb_id) => {

    console.log(`Querying knowledge base...`)

    const requestQuery = await runtimeClient.runtime.generateAnswer(
        kb_id,
        {
            question: "How do I manage my knowledgebase?",
            top: 1,
            strictFilters: [
                { name: "Category", value: "api" }
            ]
        }
    );
    console.log(JSON.stringify(requestQuery));

}

هذا مثال بسيط عن الاستعلام عن قاعدة المعارف. لفهم سيناريوهات الاستعلام المتقدمة، راجع أمثلة أخرى عن الاستعلام.

تحديث قاعدة معارف

أحذف قاعدة المعارف باستخدام طريقة الحذف مع معيار معرف قاعدة المعارف.

const deleteKnowledgeBase = async (KBclient, kb_id) => {

    console.log(`Deleting knowledge base...`)

    const results = await KBclient.deleteMethod(kb_id)

    if ( ! results._response.status.toString().startsWith("2")) {
        console.log(`Delete operation state failed - HTTP status ${results._response.status}`)
        return false
    }

    console.log(`Delete operation state succeeded - HTTP status ${results._response.status}`)
    return true
}

الحصول على حالة عملية

بعض الطرق، مثل الإنشاء والتحديث، يمكن أن تستغرق وقتًا كافيًا بدلًا من انتظار انتهاء العملية، لتُستكمل العملية. استخدم معرف العملية من العملية للاستطلاع (بمنطق إعادة المحاولة) لتحديد حالة الطريقة الأصلية.

يُستخدم استدعاء delayTimer في كتلة التعليمات البرمجية التالية لمحاكاة منطقة إعادة المحاولة. استبدل هذا بمنطق إعادة المحاولة الخاص بك.

const wait_for_operation = async (qnaClient, operation_id) => {

    let state = "NotStarted"
    let operationResult = undefined

    while ("Running" === state || "NotStarted" === state) {

        operationResult = await qnaClient.operations.getDetails(operation_id)
        state = operationResult.operationState;

        console.log(`Operation state - ${state}`)

        await delayTimer(1000);
    }

    return operationResult;
}
const delayTimer = async (timeInMs) => {
    return await new Promise((resolve) => {
        setTimeout(resolve, timeInMs);
    });
}

شغّل التطبيق

شغل التطبيق باستخدام node index.js الأمر من دليل تطبيقك.

node index.js

يمكن العثور على التعليمات البرمجية المصدر لهذه النماذج على GitHub.

استخدم مكتبة العميل QnA Maker المتعلقة بـ python إلى:

  • إنشاء قاعدة معارف
  • تحديث قاعدة معارف
  • نشر قاعدة معارف
  • الحصول على مفتاح نقطة نهاية وقت تشغيل التنبؤ
  • انتظر المهمة طويلة الأمد
  • تنزيل قاعدة معارف
  • الحصول على إجابة من قاعدة معارف
  • حذف قاعدة المعارف

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

إشعار

الموارد الجديدة التي تم إنشاؤها بعد 1 يوليو 2019 ستستخدم أسماء النطاقات الفرعية المخصصة. لمزيد من المعلومات وقائمة كاملة بنقاط النهاية الإقليمية، راجع أسماء النطاقات الفرعية المخصصة لخدمات Azure الذكاء الاصطناعي.

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

إشعار

لا تنطبق تلك الوثائق على أحدث إصدار. للتعرف على استخدام واجهة برمجة تطبيقات Python بأحدث إصدار، انظرالبدء السريع للإجابة على السؤال لواجهة برمجة تطبيقات Python.

  • اشتراك Azure - إنشاء اشتراك مجانًا
  • Python 3.x
  • بمجرد اشتراكك في Azure، أنشئ مورد QnA Maker في مدخل Azure للحصول على مفتاح التأليف ونقطة النهاية. بعد انتشاره، حدد "Go to resource".
    • ستحتاج إلى المفتاح ونقطة النهاية من المورد الذي تنشئه لتوصيل تطبيقك بـQnA Maker API. ستلصق المفتاح ونقطة النهاية في التعليمات البرمجية أدناه لاحقًا في التشغيل السريع.
    • يمكنك استخدام مستوى التسعير الحر (F0) لتجربة الخدمة، والترقية لاحقًا إلى مستوى مدفوع للإنتاج.

الإعداد

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

بعد تثبيت Python، يمكنك تثبيت مكتبة العميل عن طريق:

pip install azure-cognitiveservices-knowledge-qnamaker==0.2.0

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

إنشاء ملف Python جديد يسمى quickstart-file.py واستيراد المكتبات التالية.

import os
import time

from azure.cognitiveservices.knowledge.qnamaker.authoring import QnAMakerClient
from azure.cognitiveservices.knowledge.qnamaker.runtime import QnAMakerRuntimeClient
from azure.cognitiveservices.knowledge.qnamaker.authoring.models import QnADTO, MetadataDTO, CreateKbDTO, OperationStateType, UpdateKbOperationDTO, UpdateKbOperationDTOAdd, EndpointKeysDTO, QnADTOContext, PromptDTO
from azure.cognitiveservices.knowledge.qnamaker.runtime.models import QueryDTO
from msrest.authentication import CognitiveServicesCredentials

أنشئ متغيرات لنقطة النهاية، ومفتاح موردك Azure.

  • نحن نستخدم مفتاح الاشتراك ومفتاح التأليف بالتبادل. لمزيد من التفاصيل حول مفتاح التأليف، اتبع المفاتيح في QnA Maker.

  • قيمة QNA_MAKER_ENDPOINT تكون بتنسيق https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. انتقل إلى مدخل Azure وابحث عن مورد QnA Maker الذي أنشأته في المتطلبات الأساسية. انقر على صفحة Keys and Endpoint، ضمن resource management لتحديد موقع مفتاح التأليف (الاشتراك) ونقطة نهاية QnA Maker.

نقطة نهاية تأليف QnA Maker

  • قيمة QNA_MAKER_RUNTIME_ENDPOINT تكون بتنسيق https://YOUR-RESOURCE-NAME.azurewebsites.net. انتقل إلى مدخل Azure وابحث عن مورد QnA Maker الذي أنشأته في المتطلبات الأساسية. انقر على صفحة Export Template، من Automation لتحديد موقع نقطة نهاية وقت التشغيل.

نقطة نهاية وقت تشغيل QnA Maker

هام

تذكر إزالة المفتاح من التعليمة البرمجية عند الانتهاء، وعدم توزيعها علناً. للإنتاج، استخدم طريقة آمنة لتخزين بيانات الاعتماد والوصول إليها مثل Azure Key Vault. راجع مقالة أمان خدمات Azure الذكاء الاصطناعي للحصول على مزيد من المعلومات.

subscription_key = 'PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE'

authoring_endpoint = 'PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE'

runtime_endpoint = 'PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE'

نماذج الكائن

يستخدم QnA Maker نموذجين مختلفين للكائنات:

  • QnAMakerClient هو الكائن المستخدم لإنشاء قاعدة المعارف، وإدارتها، ونشرها، وتنزيلها.
  • QnAMakerRuntime هو الكائن المستخدم للاستعلام عن قاعدة المعارف باستخدام GenerateAnswer API وإرسال أسئلة جديدة مقترحة باستخدام Train API (كجزء من التعلم النشط).

استخدام هذا المثال لقاعدة المعارف.

قاعدة المعارف في هذا التشغيل السريع تبدأ مع 2 من أزواج محادثة QnA، ويتم ذلك عن قصد لتبسيط المثال والحصول على معرفات هوية يمكن التنبؤ بها للغاية لاستخدامها في أسلوب التحديث، وربط مطالبات المتابعة مع أسئلة الأزواج جديدة. وقد تم التخطيط لذلك وتنفيذه بترتيب محدد من أجل هذا التشغيل السريع.

إذا كنت تخطط لتطوير قاعدة المعارف الخاصة بك مع مرور الوقت مع مطالبات المتابعة التي تعتمد على أزواج QnA الموجودة، يمكنك اختيار:

  • بالنسبة إلى قواعد المعرفة الأكبر، قم بإدارة قاعدة المعارف في محرر نصوص أو أداة TSV التي تدعم التشغيل التلقائي، ثم استبدل قاعدة المعارف بالكامل مرة واحدة التحديث.
  • للحصول على قاعدة معارف أصغر، قم بإدارة مطالبات المتابعة بالكامل في بوابة QnA Maker.

تفاصيل حول أزواج QnA المستخدمة في هذه البداية السريعة:

  • أنواع زوج QnA - هناك نوعان من أزواج QnA في قاعدة المعرفة هذه ، بعد التحديث: chitchat ومعلومات خاصة بالنطاق هذا الأمر نمطي إذا تم ربط قاعدة المعرفة الخاصة بك إلى تطبيق محادثة مثل chatbot.
  • في حين يمكن تصفية إجابات قاعدة المعرفة من قبل بيانات التعريف أو استخدام مطالبات المتابعة، هذه البداية السريعة لا تُظهر ذلك. ابحث عن أمثلة إنشاء إجابات حيادية اللغة هنا.
  • نص الإجابة هو تخفيض السعر ويمكن أن يحتوي علىمجموعة متنوعة من التخفيضات مثل الصور (الصور المتاحة للجمهور على الإنترنت) ، والروابط (لعناوين URL المتاحة للجمهور) ، والنقاط ، ولا تستخدم هذه البداية السريعة هذا التنوع.

نموذج كائن QnAMakerClient

عميل تأليف QnA Maker هو كائن QnAMakerClient الذي يصادق Azure باستخدام Microsoft.Rest.ServiceClientCredentials الذي يحتوي على مفتاحك.

بمجرد إنشاء حساب العميل، استخدم خاصية قاعدة المعارف لإنشاء قاعدة المعارف وإدارتها ونشرها.

إدارة قاعدة المعارف الخاصة بك عن طريق إرسال كائن JSON. بالنسبة إلى العمليات الفورية، عادةً ما تُرجع الطريقة كائن JSON الذي يشير إلى الحالة. بالنسبة إلى العمليات طويلة الأمد، تكون الإجابة هي معرف العملية. استدعاء الطريقة operations.get_details مع معرف العملية لتحديد حالة الطلب.

نموذج كائن QnAMakerRuntimeClient

يعد عميل Maker QnA المتوقع QnAMakerRuntimeClient الكائن الذي يصادق Azure باستخدام Microsoft.Rest.ServiceClientCredentials، الذي يحتوي على مفتاح وقت التشغيل المتوقع الذي أعيد بطلب من عميل التأليف،client.EndpointKeysOperations.get_keys، وذلك بعد نشر قاعدة المعرفة.

استخدم generate_answer الأسلوب للحصول على إجابة فيما يتعلق بالاستعلام عن وقت تشغيل.

المصادقة على العميل لتأليف قاعدة المعرفة

إنشاء مثيل لعميل باستخدام نقطة النهاية والمفتاح. قم بإنشاء عنصر CognitiveServicesCredentials باستخدام مفتاحك، واستخدمه مع نقطة النهاية لإنشاء عنصرQnAMakerClient.

client = QnAMakerClient(endpoint=authoring_endpoint, credentials=CognitiveServicesCredentials(subscription_key))

إنشاء قاعدة معارف

استخدام كائن العميل للحصول على كائن عمليات قاعدة معارف.

تخزن قاعدة المعارف أزواج الأسئلة والأجوبة للكائن CreateKbDTO من ثلاثة مصادر:

  • لـالمحتوى التحريري، استخدم الكائن QnADTO.
    • لاستخدام بيانات التعريف ومتابعة المطالبات، استخدم السياق التحريري، لأنه تتم إضافة هذه البيانات على مستوى زوج QnA الفردية.
  • بالنسبة إلى الملفات، استخدم الكائن FileDTO. يتضمن FileDTO اسم الملف وعنوان URL العام للوصول إلى الملف.
  • بالنسبة إلى عناوين URL، استخدم قائمة سلاسل لتمثيل عناوين URL المتاحة للجمهور.

اطلب طريقة الإنشاء ثم مرّر خاصية العملية التي تم إرجاعها إلى طريقة Operations.getDetails للاستقصاء عن الحالة.

يقوم السطر الأخير من الكود التالي بإرجاع مُعرف قاعدة المعارف من استجابة MonitorOperation.

def create_kb(client):
    print ("Creating knowledge base...")

    qna1 = QnADTO(
        answer="Yes, You can use our [REST APIs](https://docs.microsoft.com/rest/api/cognitiveservices/qnamaker/knowledgebase) to manage your knowledge base.",
        questions=["How do I manage my knowledgebase?"],
        metadata=[
            MetadataDTO(name="Category", value="api"),
            MetadataDTO(name="Language", value="REST"),
        ]
    )

    qna2 = QnADTO(
        answer="Yes, You can use our [Python SDK](https://pypi.org/project/azure-cognitiveservices-knowledge-qnamaker/) with the [Python Reference Docs](https://docs.microsoft.com/python/api/azure-cognitiveservices-knowledge-qnamaker/azure.cognitiveservices.knowledge.qnamaker?view=azure-python) to manage your knowledge base.",
        questions=["Can I program with Python?"],
        metadata=[
            MetadataDTO(name="Category", value="api"),
            MetadataDTO(name="Language", value="Python"),
        ]
    )

    urls = []
    files = [
        FileDTO(
            file_name = "structured.docx",
            file_uri = "https://github.com/Azure-Samples/cognitive-services-sample-data-files/raw/master/qna-maker/data-source-formats/structured.docx"
        )]

    create_kb_dto = CreateKbDTO(
        name="QnA Maker Python SDK Quickstart",
        qna_list=[
            qna1,
            qna2
        ],
        urls=urls,
        files=[],
        enable_hierarchical_extraction=True,
        default_answer_used_for_extraction="No answer found.",
        language="English"
    )
    create_op = client.knowledgebase.create(create_kb_payload=create_kb_dto)

    create_op_monitor = _monitor_operation(client=client, operation=create_op)

    # Get knowledge base ID from resourceLocation HTTP header
    knowledge_base_ID = create_op_monitor.resource_location.replace("/knowledgebases/", "")
    print("Created KB with ID: {}".format(knowledge_base_ID))

    return knowledge_base_ID

تأكد من تضمين _monitor_operation الدالة، المشار إليها في الكود أعلاه، من أجل إنشاء قاعدة معارف بنجاح.

تحديث قاعدة المعرفة

يمكنك تحديث قاعدة معارف عن طريق تمرير معرف قاعدة المعارف وUpdateKbOperationDTO الذي يحتوي على إضافة، وتحديث، وحذف كائنات DTO إلى طريقة التحديث. استخدم الأسلوب Operation.getDetail لتحديد ما إذا كان التحديث ناجحاً.

def update_kb(client, kb_id):
    print ("Updating knowledge base...")

    qna3 = QnADTO(
        answer="goodbye",
        questions=[
            "bye",
            "end",
            "stop",
            "quit",
            "done"
            ],
        metadata=[
            MetadataDTO(name="Category", value="Chitchat"),
            MetadataDTO(name="Chitchat", value="end"),
        ]
    )

    qna4 = QnADTO(
        answer="Hello, please select from the list of questions or enter a new question to continue.",
        questions=[
            "hello",
            "hi",
            "start"
        ],
        metadata=[
            MetadataDTO(name="Category", value="Chitchat"),
            MetadataDTO(name="Chitchat", value="begin"),
        ],
        context = QnADTOContext(

            is_context_only = False,
            prompts = [

                PromptDTO(
                    display_order =1,
                    display_text= "Use REST",
                    qna_id=1

                ),
                PromptDTO(
                    display_order =2,
                    display_text= "Use .NET NuGet package",
                    qna_id=2
                ),
            ]
        )

    )

    urls = [
        "https://docs.microsoft.com/azure/cognitive-services/QnAMaker/troubleshooting"
    ]



    update_kb_operation_dto = UpdateKbOperationDTO(
        add=UpdateKbOperationDTOAdd(
            qna_list=[
                qna3,
                qna4
            ],
            urls = urls,
            files=[]
        ),
        delete=None,
        update=None
    )
    update_op = client.knowledgebase.update(kb_id=kb_id, update_kb=update_kb_operation_dto)
    _monitor_operation(client=client, operation=update_op)
    print("Updated knowledge base.")

تأكد من تضمين الدالة _monitor_operation، المشار إليها في التعليمات البرمجية أعلاه، من أجل تحديث قاعدة معارف بنجاح.

قم بتنزيل قاعدة المعرفة

استخدم طريقة التحميل لتحميل قاعدة البيانات كقائمة QnADocumentsDTO. هذا لا يعادل تصدير مدخل QnA Maker من صفحة "Settings" لأن نتيجة هذه الطريقة ليست ملف TSV.

def download_kb(client, kb_id):
    print("Downloading knowledge base...")
    kb_data = client.knowledgebase.download(kb_id=kb_id, environment="Prod")
    print("Downloaded knowledge base. It has {} QnAs.".format(len(kb_data.qna_documents)))

نشر قاعدة معارف

نشر قاعدة المعارف باستخدام طريقة النشر. وهذا يأخذ النموذج الحالي المحفوظة والمدرب، المشار إليه بواسطة معرف قاعدة المعارف، ثم ينشر ذلك في نقطة نهاية.

def publish_kb(client, kb_id):
    print("Publishing knowledge base...")
    client.knowledgebase.publish(kb_id=kb_id)
    print("Published knowledge base.")

الاستعلام عن قاعدة معارف

الحصول على مفتاح وقت تشغيل الاستعلام

بمجرد نشر knowledgebase، تحتاج مفتاح وقت تشغيل الاستعلام للاستعلام عن وقت التشغيل. وهذا ليس نفس المفتاح المستخدم لإنشاء كائن العميل الأصلي.

استخدم أسلوب EndpointKeysOperations.get_keys للحصول على فئة EndpointKeysDTO.

استخدم أي من خصائص المفتاح التي تم إرجاعها في الكائن للاستعلام عن قاعدة المعارف.

def getEndpointKeys_kb(client):
    print("Getting runtime endpoint keys...")
    keys = client.endpoint_keys.get_keys()
    print("Primary runtime endpoint key: {}.".format(keys.primary_endpoint_key))

    return keys.primary_endpoint_key

مصادقة وقت التشغيل لإنشاء إجابة

إنشاء QnAMakerRuntimeClient للاستعلام في قاعدة المعارف لإنشاء إجابة أو التدريب من خلال التعلم النشط.

runtimeClient = QnAMakerRuntimeClient(runtime_endpoint=runtime_endpoint, credentials=CognitiveServicesCredentials(queryRuntimeKey))

استخدم QnAMakerRuntimeClient للحصول على إجابة من قاعدة المعارف أو لإرسال أسئلة مقترحة جديدة إلى قاعدة المعارف للتعلم النشط.

إنشاء إجابة من قاعدة المعرفة

الحصول على إجابة من قاعدة معارف منشورة باستخدام أسلوب QnAMakerRuntimeClient.runtime.generate_answer. تقبل هذه الطريقة مُعرف قاعدة المعارف وQueryDTO. الوصول إلى خصائص إضافية من QueryDTO، مثل أعلىوسياق لاستخدامها في بوت الدردشة الخاص بك.

def generate_answer(client, kb_id, runtimeKey):
    print ("Querying knowledge base...")

    authHeaderValue = "EndpointKey " + runtimeKey

    listSearchResults = client.runtime.generate_answer(kb_id, QueryDTO(question = "How do I manage my knowledgebase?"), dict(Authorization=authHeaderValue))

    for i in listSearchResults.answers:
        print(f"Answer ID: {i.id}.")
        print(f"Answer: {i.answer}.")
        print(f"Answer score: {i.score}.")

وهذا مثال بسيط للاستعلام عن قاعدة المعارف. لفهم سيناريوهات الاستعلام المتقدمة، راجع أمثلة أخرى عن الاستعلام.

تحديث قاعدة معارف

أحذف قاعدة المعارف باستخدام طريقة الحذف مع معيار معرف قاعدة المعارف.

def delete_kb(client, kb_id):
    print("Deleting knowledge base...")
    client.knowledgebase.delete(kb_id=kb_id)
    print("Deleted knowledge base.")

الحصول على حالة عملية

بعض الطرق، مثل الإنشاء والتحديث، يمكن أن تستغرق وقتًا كافيًا بدلًا من انتظار انتهاء العملية، لتُستكمل العملية. استخدم معرف العملية من العملية للاستطلاع (بمنطق إعادة المحاولة) لتحديد حالة الطريقة الأصلية.

يُستخدم استدعاء setTimeout في كتلة التعليمات البرمجية التالية لمحاكاة التعليمات البرمجية غير المتزامنة. استبدل هذا بمنطق إعادة المحاولة.

def _monitor_operation(client, operation):

    for i in range(20):
        if operation.operation_state in [OperationStateType.not_started, OperationStateType.running]:
            print("Waiting for operation: {} to complete.".format(operation.operation_id))
            time.sleep(5)
            operation = client.operations.get_details(operation_id=operation.operation_id)
        else:
            break
    if operation.operation_state != OperationStateType.succeeded:
        raise Exception("Operation {} failed to complete.".format(operation.operation_id))

    return operation

شغّل التطبيق

قم بتشغيل التطبيق باستخدام أمر python الموجود في ملف التشغيل السريع.

python quickstart-file.py

يمكن العثور على التعليمات البرمجية المصدر لهذه النماذج على GitHub.

استخدم مكتبة عميل QnA Maker لـ Java من أجل:

  • إنشاء قاعدة معارف
  • تحديث قاعدة معارف
  • نشر قاعدة معارف
  • الحصول على مفتاح نقطة نهاية وقت تشغيل التنبؤ
  • انتظر المهمة طويلة الأمد
  • تنزيل قاعدة معارف
  • الحصول على إجابة من قاعدة معارف
  • حذف قاعدة المعارف

رمز مصدر المكتبة | الحزمة | عينات

إشعار

الموارد الجديدة التي تم إنشاؤها بعد 1 يوليو 2019 ستستخدم أسماء النطاقات الفرعية المخصصة. لمزيد من المعلومات وقائمة كاملة بنقاط النهاية الإقليمية، راجع أسماء النطاقات الفرعية المخصصة لخدمات Azure الذكاء الاصطناعي.

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

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

الإعداد

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

بعد تثبيت Java، يمكنك تثبيت مكتبات العملاء باستخدام Maven من MVN Repository.

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

أنشئ ملفًا جديدًا باسم quickstart.java واستورد المكتبات التالية.

/* Download the following files.
 * - https://repo1.maven.org/maven2/com/microsoft/azure/cognitiveservices/azure-cognitiveservices-qnamaker/1.0.0-beta.1/azure-cognitiveservices-qnamaker-1.0.0-beta.1.jar
 * - https://repo1.maven.org/maven2/com/microsoft/azure/cognitiveservices/azure-cognitiveservices-qnamaker/1.0.0-beta.1/azure-cognitiveservices-qnamaker-1.0.0-beta.1.pom
 * Move the downloaded .jar file to a folder named "lib" directly under the current folder.
 * Rename the downloaded file to pom.xml.
 * At the command line, run
 * mvn dependency:copy-dependencies
 * This will download the .jar files depended on by azure-cognitiveservices-qnamaker-1.0.0-beta.1.jar to the folder "target/dependency" under the current folder. Move these .jar files to the "lib" folder as well.
 */
import com.microsoft.azure.cognitiveservices.knowledge.qnamaker.*;
import com.microsoft.azure.cognitiveservices.knowledge.qnamaker.models.*;

import java.io.*;
import java.lang.Object.*;
import java.time.format.DateTimeFormatter;  
import java.time.LocalDateTime; 
import java.util.*;
import java.net.*;

أنشئ متغيرات لنقطة النهاية، ومفتاح موردك Azure.

  • نحن نستخدم مفتاح الاشتراك ومفتاح التأليف بالتبادل. لمزيد من التفاصيل حول مفتاح التأليف، اتبع المفاتيح في QnA Maker.

  • قيمة QNA_MAKER_ENDPOINT تكون بتنسيق https://YOUR-RESOURCE-NAME.cognitiveservices.azure.com. انتقل إلى مدخل Azure وابحث عن مورد QnA Maker الذي أنشأته في المتطلبات الأساسية. انقر على صفحة Keys and Endpoint، ضمن resource management لتحديد موقع مفتاح التأليف (الاشتراك) ونقطة نهاية QnA Maker.

نقطة نهاية تأليف QnA Maker

  • قيمة QNA_MAKER_RUNTIME_ENDPOINT تكون بتنسيق https://YOUR-RESOURCE-NAME.azurewebsites.net. انتقل إلى مدخل Azure وابحث عن مورد QnA Maker الذي أنشأته في المتطلبات الأساسية. انقر على صفحة Export Template، من Automation لتحديد موقع نقطة نهاية وقت التشغيل.

نقطة نهاية وقت تشغيل QnA Maker

هام

تذكر إزالة المفتاح من التعليمة البرمجية عند الانتهاء، وعدم توزيعها علناً. للإنتاج، استخدم طريقة آمنة لتخزين بيانات الاعتماد والوصول إليها مثل Azure Key Vault. راجع مقالة أمان خدمات Azure الذكاء الاصطناعي للحصول على مزيد من المعلومات.

private static String authoring_key = "PASTE_YOUR_QNA_MAKER_AUTHORING_SUBSCRIPTION_KEY_HERE";
private static String authoring_endpoint = "PASTE_YOUR_QNA_MAKER_AUTHORING_ENDPOINT_HERE";
private static String runtime_endpoint = "PASTE_YOUR_QNA_MAKER_RUNTIME_ENDPOINT_HERE";

نماذج الكائن

يستخدم QnA Maker نموذجين مختلفين للكائنات:

  • QnAMakerClient هو الكائن المستخدم لإنشاء قاعدة المعارف، وإدارتها، ونشرها، وتنزيلها.
  • QnAMakerRuntime هو الكائن المستخدم للاستعلام عن قاعدة المعارف باستخدام GenerateAnswer API وإرسال أسئلة جديدة مقترحة باستخدام Train API (كجزء من التعلم النشط).

استخدام هذا المثال لقاعدة المعارف.

قاعدة المعارف في هذا التشغيل السريع تبدأ مع 2 من أزواج محادثة QnA، ويتم ذلك عن قصد لتبسيط المثال والحصول على معرفات هوية يمكن التنبؤ بها للغاية لاستخدامها في أسلوب التحديث، وربط مطالبات المتابعة مع أسئلة الأزواج جديدة. وقد تم التخطيط لذلك وتنفيذه بترتيب محدد من أجل هذا التشغيل السريع.

إذا كنت تخطط لتطوير قاعدة المعارف الخاصة بك مع مرور الوقت مع مطالبات المتابعة التي تعتمد على أزواج QnA الموجودة، يمكنك اختيار:

  • بالنسبة إلى قواعد المعرفة الأكبر، قم بإدارة قاعدة المعارف في محرر نصوص أو أداة TSV التي تدعم التشغيل التلقائي، ثم استبدل قاعدة المعارف بالكامل مرة واحدة التحديث.
  • للحصول على قاعدة معارف أصغر، قم بإدارة مطالبات المتابعة بالكامل في بوابة QnA Maker.

تفاصيل حول أزواج QnA المستخدمة في هذه البداية السريعة:

  • أنواع زوج QnA - هناك نوعان من أزواج QnA في قاعدة المعرفة هذه ، بعد التحديث: chitchat ومعلومات خاصة بالنطاق هذا الأمر نمطي إذا تم ربط قاعدة المعرفة الخاصة بك إلى تطبيق محادثة مثل chatbot.
  • في حين يمكن تصفية إجابات قاعدة المعرفة من قبل بيانات التعريف أو استخدام مطالبات المتابعة، هذه البداية السريعة لا تُظهر ذلك. ابحث عن أمثلة إنشاء إجابات حيادية اللغة هنا.
  • نص الإجابة هو تخفيض السعر ويمكن أن يحتوي علىمجموعة متنوعة من التخفيضات مثل الصور (الصور المتاحة للجمهور على الإنترنت) ، والروابط (لعناوين URL المتاحة للجمهور) ، والنقاط ، ولا تستخدم هذه البداية السريعة هذا التنوع.

نموذج كائن QnAMakerClient

عميل تأليف QnA Maker هو كائن QnAMakerClient الذي يصادق Azure باستخدام MsRest::ServiceClientCredentials الذي يحتوي على مفتاحك.

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

بالنسبة إلى العمليات الفورية، عادةً ما تُرجع الطريقة النتيجة، إن وجدت. بالنسبة للعمليات طويلة الأمد، الاستجابة هي كائن العملية. استدعاء الأسلوب getDetailsoperation.operationId مع القيمة لتحديد حالة الطلب.

نموذج كائن QnAMakerRuntimeClient

عميل QnA Maker وقت التشغيل هو كائن QnAMakerRuntimeClient.

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

إنشاء عميل وقت التشغيل عن طريق استدعاء QnAMakerRuntimeManager.authenticate وتمرير مفتاح نقطة نهاية وقت التشغيل. للحصول على مفتاح نقطة النهاية وقت التشغيل، استخدم عميل التأليف لاستدعاء getKeys.

المصادقة على العميل لتأليف قاعدة المعرفة

إنشاء مثيل للعميل بنقطة نهاية التأليف ومفتاح الاشتراك.

/* Note QnAMakerManager.authenticate() does not set the baseUrl paramater value
 * as the value for QnAMakerClient.endpoint, so we still need to call withEndpoint().
 */
QnAMakerClient authoring_client = QnAMakerManager.authenticate(authoring_key).withEndpoint(authoring_endpoint);
Knowledgebases kb_client = authoring_client.knowledgebases();
Operations ops_client = authoring_client.operations();
EndpointKeys keys_client = authoring_client.endpointKeys();

إنشاء قاعدة معارف

تخزن قاعدة المعارف أزواج الأسئلة والأجوبة للكائن CreateKbDTO من ثلاثة مصادر:

  • لـالمحتوى التحريري، استخدم الكائن QnADTO.
    • لاستخدام بيانات التعريف ومتابعة المطالبات، استخدم السياق التحريري، لأنه تتم إضافة هذه البيانات على مستوى زوج QnA الفردية.
  • بالنسبة إلى الملفات، استخدم الكائن FileDTO. يتضمن FileDTO اسم الملف وعنوان URL العام للوصول إلى الملف.
  • بالنسبة إلى عناوين URL، استخدم قائمة سلاسل لتمثيل عناوين URL المتاحة للجمهور.

اطلب طريقة الإنشاء ثم مرّرoperationId خاصية العملية التي تم إرجاعها إلى طريقة getDetails للاستقصاء عن الحالة.

يُرجع السطر الأخير من الكود التالي معرف قاعدة المعارف.

public String create_kb () throws Exception {
    System.out.println("Creating KB...");

    String name = "QnA Maker FAQ from quickstart";

    var metadata = new MetadataDTO()
        .withName ("Category")
        .withValue ("api");

    List<MetadataDTO> metadata_list = Arrays.asList(new MetadataDTO[]{ metadata });

    var qna = new QnADTO()
        .withAnswer ("You can use our REST APIs to manage your knowledge base.")
        .withQuestions ( Arrays.asList(new String[]{ "How do I manage my knowledgebase?" }))
        .withMetadata (metadata_list);

    List<QnADTO> qna_list = Arrays.asList(new QnADTO[]{ qna });

    var urls = Arrays.asList(new String[]{ "https://docs.microsoft.com/en-in/azure/cognitive-services/qnamaker/faqs" });

    var payload = new CreateKbDTO().withName(name).withQnaList(qna_list).withUrls(urls);

    var result = kb_client.create(payload);
    var kb_id = wait_for_operation(result);

    System.out.println("Created KB with ID: " + kb_id + ".\n");
    return kb_id;
}

تحديث قاعدة المعرفة

يمكنك تحديث قاعدة المعارف عن طريق طلب التحديث وتمرير معرف قاعدة المعارف وكائن UpdateKbOperationDTO. يمكن أن يحتوي هذا الكائن بدوره على:

قم بتمرير operationIdخاصية العملية التي تم إرجاعها إلى طريقة getDetails للاستقصاء عن الحالة.

public void update_kb (String kb_id) throws Exception {
    System.out.println("Updating KB...");

    var update = new UpdateKbOperationDTOUpdate().withName ("New KB name");

    var payload = new UpdateKbOperationDTO().withUpdate((UpdateKbOperationDTOUpdate)update);

    var result = kb_client.update(kb_id, payload);
    wait_for_operation(result);

    System.out.println("Updated KB.");
}

قم بتنزيل قاعدة المعرفة

استخدم طريقة التحميل لتحميل قاعدة البيانات كقائمة QnADocumentsDTO. هذا لا يعادل تصدير مدخل QnA Maker من صفحة "Settings" لأن نتيجة هذه الطريقة ليست ملف TSV.

public void download_kb(String kb_id) {
    System.out.println("Downloading KB...");

    var kb_data = kb_client.download(kb_id, EnvironmentType.PROD);
    System.out.println("KB Downloaded. It has " + kb_data.qnaDocuments().size() + " question/answer sets.");

    System.out.println("Downloaded KB.\n");
}

نشر قاعدة معارف

نشر قاعدة المعارف باستخدام طريقة النشر. وهذا يأخذ النموذج الحالي المحفوظة والمدرب، المشار إليه بواسطة معرف قاعدة المعارف، ثم ينشر ذلك في نقطة نهاية.

public void publish_kb(String kb_id) {
    System.out.println("Publishing KB...");
    kb_client.publish(kb_id);
    System.out.println("KB published.\n");
}

إنشاء إجابة من قاعدة المعرفة

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

استخدم أسلوب getKeys للحصول على كائن EndpointKeysDTO.

إنشاء عميل وقت تشغيل عن طريق استدعاء QnAMakerRuntimeManager.authenticate وتمرير مفتاح نقطة نهاية وقت التشغيل من كائن EndpointKeysDTO.

الحصول على إجابة من قاعدة معارف منشورة باستخدام أسلوب generateAnswer. يقبل هذا الأسلوب معرف قاعدة المعارف كائن QueryDTO.

public void query_kb(String kb_id) {
    System.out.println("Sending query to KB...");
    
    var runtime_key = keys_client.getKeys().primaryEndpointKey();
    QnAMakerRuntimeClient runtime_client = QnAMakerRuntimeManager.authenticate(runtime_key).withRuntimeEndpoint(runtime_endpoint);
    var query = (new QueryDTO()).withQuestion("How do I manage my knowledgebase?");
    var result = runtime_client.runtimes().generateAnswer(kb_id, query);
    System.out.println("Answers:");
    for (var answer : result.answers()) {
        System.out.println(answer.answer().toString());
    };
    System.out.println();
}

هذا مثال بسيط للاستعلام عن قاعدة المعرفة. لفهم سيناريوهات الاستعلام المتقدمة، راجع أمثلة أخرى عن الاستعلام.

تحديث قاعدة معارف

أحذف قاعدة المعارف باستخدام طريقة الحذف مع معيار معرف قاعدة المعارف.

public void delete_kb(String kb_id) {
    System.out.println("Deleting KB...");
    kb_client.delete(kb_id);
    System.out.println("KB deleted.\n");
}

الحصول على حالة عملية

بعض الطرق، مثل الإنشاء والتحديث، يمكن أن تستغرق وقتًا كافيًا بدلًا من انتظار انتهاء العملية، لتُستكمل العملية. استخدم معرف العملية من العملية للاستطلاع (بمنطق إعادة المحاولة) لتحديد حالة الطريقة الأصلية.

public String wait_for_operation(Operation op) throws Exception {
    System.out.println ("Waiting for operation to finish...");
    Boolean waiting = true;
    String result = "";
    while (true == waiting) {
        var op_ = ops_client.getDetails(op.operationId());
        var state = op_.operationState();
        if (OperationStateType.FAILED == state) {
            throw new Exception("Operation failed.");
        }
        if (OperationStateType.SUCCEEDED == state) {
            waiting = false;
            // Remove "/knowledgebases/" from the resource location.
            result = op_.resourceLocation().replace("/knowledgebases/", "");
        }
        if (true == waiting) {
            System.out.println("Waiting 10 seconds for operation to complete...");
            Thread.sleep(10000);
        }
    }
    return result;
}

شغّل التطبيق

هذه هي الطريقة الرئيسية للتطبيق.

    public static void main(String[] args) {
        try {
            Quickstart quickstart = new Quickstart();
            String kb_id = quickstart.create_kb();
//			quickstart.list_kbs();
            quickstart.update_kb(kb_id);
            quickstart.publish_kb(kb_id);
            quickstart.download_kb(kb_id);
            quickstart.query_kb(kb_id);
            quickstart.delete_kb(kb_id);
        } catch (Exception e) {
            System.out.println(e.getMessage());
            e.printStackTrace();
        }
    }

تشغيل التطبيق كما يلي. يفترض هذا اسم الفئة Quickstart الخاص بك ثم التبعيات الخاصة بك في مجلد فرعي يسمى lib أسفل المجلد الحالي.

javac Quickstart.java -cp .;lib\*
java -cp .;lib\* Quickstart

يمكن العثور على التعليمات البرمجية المصدر لهذه النماذج على GitHub.

تنظيف الموارد

إذا كنت ترغب في تنظيف اشتراك خدمات Azure الذكاء الاصطناعي وإزالته، يمكنك حذف المورد أو مجموعة الموارد. يؤدي حذف مجموعة الموارد إلى حذف أية موارد أخرى مقترنة بها أيضًا.

الخطوات التالية

البرنامج التعليمي: اختبار قاعدة المعارف (KB) مع ملف دفعة