إنشاء مخزن معارف باستخدام REST

مقالة
03/11/2024

في Azure الذكاء الاصطناعي Search، يعد مخزن المعلومات مستودعا للمحتوى الذي تم إنشاؤه الذكاء الاصطناعي ويستخدم للسيناريوهات غير المتعلقة بالبحث. يمكنك إنشاء مخزن المعرفة باستخدام مفهرس ومجموعة مهارات، وتحديد Azure Storage لتخزين الإخراج. بعد ملء مخزن المعلومات، استخدم أدوات مثل Storage Explorer أو Power BI لاستكشاف المحتوى.

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

لإتاحة مجموعة البيانات الأولية، يجري استيراد تقييمات الفندق أولاً إلى Azure Blob Storage. بعد المعالجة، تُحفظ النتائج كمخزن معارف في Azure Table Storage.

تلميح

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

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

Visual Studio Code مع عميل REST. إذا كنت بحاجة إلى مساعدة في بدء الاستخدام، فشاهد التشغيل السريع: البحث عن النص باستخدام REST.
Azure الذكاء الاصطناعي Search. إنشاء خدمة أو العثور على خدمة موجودة. يمكنك استخدام الخدمة المجانية لهذا التمرين.
Azure Storage. إنشاء حساب أو العثور على حساب موجود. يجب أن يكون نوع الحساب StorageV2 (للأغراض العامة V2).

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

تحميل البيانات إلى Azure Storage والحصول على سلسلة الاتصال

Download HotelReviews_Free.csv. يحتوي ملف CSV هذا على 19 قطعة من ملاحظات العملاء حول فندق واحد (تنشأ من Kaggle.com).
في مدخل Microsoft Azure، ابحث عن حساب التخزين الخاص بك واستخدم Storage Browser لإنشاء حاوية كائن ثنائي كبير الحجم تسمى hotel-reviews.
حدد Upload أعلى الصفحة لتحميل الملف HotelReviews-Free.csv الذي نزلته من الخطوة السابقة.
على اليسار، حدد مفاتيح الوصول، وحدد إظهار المفاتيح، ثم انسخ سلسلة الاتصال للمفتاح 1 أو المفتاح 2. يحتوي سلسلة الاتصال الوصول الكامل على التنسيق التالي:

"knowledgeStore": {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-ACCOUNT-NAME>;AccountKey=<YOUR-ACCOUNT-KEY>;EndpointSuffix=core.windows.net;"
}

إشعار

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

نسخ مفتاح وعنوان URL

في هذا المثال، تتطلب استدعاءات REST نقطة نهاية خدمة البحث وتستخدم مفتاح API على كل طلب. يمكنك الحصول على هذه القيم من مدخل Microsoft Azure.

سجل الدخول إلى مدخل Microsoft Azure، وانتقل إلى صفحة Overview ، وانسخ عنوان URL. قد يبدو مثال نقطة النهاية بالشكل https://mydemo.search.windows.net.
ضمن الإعدادات> Keys، انسخ مفتاح مسؤول. يتم استخدام مفاتيح مسؤول لإضافة الكائنات وتعديلها وحذفها. هناك مفتاحان للمسؤول قابلان للتبديل. انسخ أي منهما.

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

إنشاء فهرس

ينشئ Create Index (REST) فهرس بحث على خدمة البحث. فهرس البحث غير مرتبط بمخزن معارف، ولكن المفهرس يتطلب واحدا. يحتوي فهرس البحث على نفس محتوى مخزن المعلومات، والذي يمكنك استكشافه عن طريق إرسال طلبات الاستعلام.

افتح ملفا نصيا جديدا في Visual Studio Code.

تعيين المتغيرات إلى نقطة نهاية البحث ومفتاح API الذي جمعته سابقا.

@baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@apiKey = PUT-YOUR-ADMIN-API-KEY-HERE
@storageConnection = PUT-YOUR-STORAGE-CONNECTION-STRING-HERE
@blobContainer = PUT-YOUR-CONTAINER-NAME-HERE (hotel-reviews)

احفظ الملف بملحق .rest ملف.

الصق في المثال التالي لإنشاء طلب الفهرس.

### Create a new index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-idx",  
        "fields": [
            { "name": "name", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_date", "type": "Edm.DateTimeOffset", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_rating", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_text", "type": "Edm.String", "filterable": false,  "sortable": false, "facetable": false },
            { "name": "reviews_title", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_username", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "AzureSearch_DocumentKey", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false, "key": true },
            { "name": "language", "type": "Edm.String", "filterable": true, "sortable": false, "facetable": true },
            { "name": "translated_text", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false },
            { "name": "sentiment", "type": "Collection(Edm.String)", "searchable": false, "filterable": true, "retrievable": true, "sortable": false, "facetable": true },
            { "name": "keyphrases", "type": "Collection(Edm.String)", "filterable": true, "sortable": false, "facetable": true }
        ]
    }

حدد إرسال طلب. يجب أن يكون لديك استجابة HTTP/1.1 201 Created ويجب أن يتضمن نص الاستجابة تمثيل JSON لمخطط الفهرس.

قم بإنشاء مصدر بيانات

إنشاء مصدر بيانات ينشئ اتصال مصدر بيانات على Azure الذكاء الاصطناعي Search.

الصق في المثال التالي لإنشاء مصدر البيانات.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-ds",
        "description": null,
        "type": "azureblob",
        "subtype": null,
        "credentials": {
            "connectionString": "{{storageConnectionString}}"
        },
        "container": {
            "name": "{{blobContainer}}",
            "query": null
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null
    }

حدد إرسال طلب.

إنشاء مجموعة مهارات

تحدد مجموعة المهارات الإثراء (المهارات) ومخزن المعرفة الخاص بك. إنشاء Skillset ينشئ الكائن على خدمة البحث الخاصة بك.

الصق في المثال التالي لإنشاء مجموعة المهارات.

### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-ss",
        "description": "Skillset to detect language, translate text, extract key phrases, and score sentiment",
        "skills": [ 
            {
                "@odata.type": "#Microsoft.Skills.Text.SplitSkill", 
                "context": "/document/reviews_text", "textSplitMode": "pages", "maximumPageLength": 5000,
                "inputs": [ 
                    { "name": "text", "source": "/document/reviews_text" }
                ],
                "outputs": [
                    { "name": "textItems", "targetName": "pages" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
                "context": "/document/reviews_text/pages/*",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text/pages/*" },
                    { "name": "languageCode", "source": "/document/language" }
                ],
                "outputs": [
                    { "name": "sentiment", "targetName": "sentiment" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
                "context": "/document",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text" }
                ],
                "outputs": [
                    { "name": "languageCode", "targetName": "language" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.TranslationSkill",
                "context": "/document/reviews_text/pages/*",
                "defaultFromLanguageCode": null,
                "defaultToLanguageCode": "en",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text/pages/*" }
                ],
                "outputs": [
                    { "name": "translatedText", "targetName": "translated_text" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
                "context": "/document/reviews_text/pages/*",
                "inputs": [
                    { "name": "text",  "source": "/document/reviews_text/pages/*" },
                    { "name": "languageCode",  "source": "/document/language" }
                ],
                "outputs": [
                    { "name": "keyPhrases" , "targetName": "keyphrases" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
                "context": "/document",
                "inputs": [
                    { "name": "name",  "source": "/document/name" },
                    { "name": "reviews_date",  "source": "/document/reviews_date" },
                    { "name": "reviews_rating",  "source": "/document/reviews_rating" },
                    { "name": "reviews_text",  "source": "/document/reviews_text" },
                    { "name": "reviews_title",  "source": "/document/reviews_title" },
                    { "name": "reviews_username",  "source": "/document/reviews_username" },
                    { "name": "AzureSearch_DocumentKey",  "source": "/document/AzureSearch_DocumentKey" },
                    {
                    "name": "pages",
                    "sourceContext": "/document/reviews_text/pages/*",
                    "inputs": [
                        {
                        "name": "languageCode",
                        "source": "/document/language"
                        },
                        {
                        "name": "translatedText",
                        "source": "/document/reviews_text/pages/*/translated_text"
                        },
                        { 
                        "name": "sentiment",
                        "source": "/document/reviews_text/pages/*/sentiment"
                        },
                        {
                        "name": "keyPhrases",
                        "source": "/document/reviews_text/pages/*/keyphrases/*"
                        },
                        {
                        "name": "Page",
                        "source": "/document/reviews_text/pages/*"
                        }
                    ]
                    }
                ],
                "outputs": [
                    { "name": "output" , "targetName": "tableprojection" }
                ]
            }
        ],
        "knowledgeStore": {
            "storageConnectionString": "{{storageConnectionString}}",
            "projections": [
                {
                    "tables": [
                        { "tableName": "hotelReviews1Document", "generatedKeyName": "Documentid", "source": "/document/tableprojection" },
                        { "tableName": "hotelReviews2Pages", "generatedKeyName": "Pagesid", "source": "/document/tableprojection/pages/*" },
                        { "tableName": "hotelReviews3KeyPhrases", "generatedKeyName": "KeyPhrasesid", "source": "/document/tableprojection/pages/*/keyPhrases/*" }
                    ],
                    "objects": []
                },
                {
                    "tables": [
                        { 
                            "tableName": "hotelReviews4InlineProjectionDocument", "generatedKeyName": "Documentid", "sourceContext": "/document",
                            "inputs": [
                                { "name": "name", "source": "/document/name"},
                                { "name": "reviews_date", "source": "/document/reviews_date"},
                                { "name": "reviews_rating", "source": "/document/reviews_rating"},
                                { "name": "reviews_username", "source": "/document/reviews_username"},
                                { "name": "reviews_title", "source": "/document/reviews_title"},
                                { "name": "reviews_text", "source": "/document/reviews_text"},
                                { "name": "AzureSearch_DocumentKey", "source": "/document/AzureSearch_DocumentKey" }
                            ]
                        },
                        { 
                            "tableName": "hotelReviews5InlineProjectionPages", "generatedKeyName": "Pagesid", "sourceContext": "/document/reviews_text/pages/*",
                            "inputs": [
                                { "name": "Sentiment", "source": "/document/reviews_text/pages/*/sentiment"},
                                { "name": "LanguageCode", "source": "/document/language"},
                                { "name": "Keyphrases", "source": "/document/reviews_text/pages/*/keyphrases"},
                                { "name": "TranslatedText", "source": "/document/reviews_text/pages/*/translated_text"},
                                { "name": "Page", "source": "/document/reviews_text/pages/*" }
                            ]
                        },
                        { 
                            "tableName": "hotelReviews6InlineProjectionKeyPhrases", "generatedKeyName": "kpidv2", "sourceContext": "/document/reviews_text/pages/*/keyphrases/*",
                            "inputs": [
                                { "name": "Keyphrases", "source": "/document/reviews_text/pages/*/keyphrases/*" }
                            ]
                        }
                    ],
                    "objects": []
                }
            ]
        }
    }

النقاط الرئيسية:

مهارة Shaper مهمة لتعريف مخزن المعرفة. يحدد كيفية تدفق البيانات إلى جداول مخزن المعرفة. الإدخالات هي أجزاء المستند الذي تم إثرائه الذي تريد تخزينه. الإخراج هو دمج العقد في بنية واحدة.
تحدد الإسقاطات الجداول والكائنات والكائنات الثنائية كبيرة الحجم لمخزن المعارف الخاص بك. يحدد "name" كل عنصر إسقاط العمود أو الحقل المراد إنشاؤه في Azure Storage. "source" يحدد أي جزء من إخراج شكل معين لهذا الحقل أو العمود.

إنشاء مفهرس

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

الصق في المثال التالي لإنشاء المفهرس.

### Create indexer
POST {{baseUrl}}/indexers?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-idxr",
        "dataSourceName": "hotel-reviews-kstore-ds",
        "skillsetName": "hotel-reviews-kstore-ss",
        "targetIndexName": "hotel-reviews-kstore-idx",
        "parameters": {
            "configuration": {
                "dataToExtract": "contentAndMetadata",
                "parsingMode": "delimitedText",
                "firstLineContainsHeaders": true,
                "delimitedTextDelimiter": ","
    }
},
"fieldMappings": [
    {
        "sourceFieldName": "AzureSearch_DocumentKey",
        "targetFieldName": "AzureSearch_DocumentKey",
        "mappingFunction": { "name": "base64Encode" }
    }
],
"outputFieldMappings": [
    { "sourceFieldName": "/document/reviews_text/pages/*/Keyphrases/*", "targetFieldName": "Keyphrases" },
    { "sourceFieldName": "/document/Language", "targetFieldName": "Language" },
    { "sourceFieldName": "/document/reviews_text/pages/*/Sentiment", "targetFieldName": "Sentiment" }
    ]
}

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

النقاط الرئيسية:

يتحكم الكائن parameters/configuration في كيفية استيعاب المفهرس للبيانات. في هذه الحالة، بيانات الإدخال في ملف CSV واحد يحتوي على سطر عنوان وقيم مفصولة بفاصلة.
تنشئ تعيينات الحقول "AzureSearch_DocumentKey" معرّفًا فريدًا لكل مستند يجري إنشاؤه بواسطة مفهرس blob (استنادًا إلى مسار تخزين بيانات التعريف).
تحدد تعيينات حقل الإخراج كيفية تعيين الحقول التي جرى إثراؤها إلى الحقول الموجودة في فهرس البحث. لا يتم استخدام تعيينات حقول الإخراج في مخازن المعرفة (تستخدم مخازن المعرفة الأشكال والإسقاطات للتعبير عن بنيات البيانات المادية).

تحقق من الحالة

بعد إرسال كل طلب، يجب أن تستجيب خدمة البحث برسالة نجاح 201.

### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/hotel-reviews-kstore-idxr/status?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

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

### Query the index (indexer status must be "success" before querying the index)
POST {{baseUrl}}/indexes/hotel-reviews-kstore-idxr/docs/search?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "*",
    "select": "reviews_title, reviews_username, language, translated_text, sentiment",
    "count": true
  }

التحقق من الجداول في مدخل Microsoft Azure

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

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

Screenshot of the knowledge store tables in Storage Browser

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

جدول	‏‏الوصف
`hotelReviews1Document`	يحتوي على الحقول التي تم ترحيلها من ملف CSV، مثل reviews_date and reviews_text.
`hotelReviews2Pages`	يحتوي على حقول ثرية أنشأتها مجموعة المهارات، مثل درجة المشاعر والنص المترجم.
`hotelReviews3KeyPhrases`	يحتوي على قائمة طويلة من العبارات الرئيسية فقط.
`hotelReviews4InlineProjectionDocument`	بديل للجدول الأول، باستخدام التشكيل المُضمَّن بدلاً من مهارة Shaper لتشكيل البيانات الخاصة بالإسقاط.
`hotelReviews5InlineProjectionPages`	بديل للجدول الثاني، باستخدام التشكيل المُضمَّن.
`hotelreviews6InlineProjectionKeyPhrases`	بديل للجدول الثالث، باستخدام التشكيل المُضمَّن.

تنظيف

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

يمكن العثور على الموارد وإدارتها في المدخل الإلكتروني، باستخدامAll resources أو رابط Resource groups الموجود في جزء التنقل الأيسر.

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

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

البدء باستخدام "Storage Explorer"