فهرسة البيانات من Azure Cosmos DB ل NoSQL للاستعلامات في Azure الذكاء الاصطناعي Search

في هذه المقالة، تعرف على كيفية تكوين مفهرس يستورد المحتوى من Azure Cosmos DB ل NoSQL ويجعله قابلا للبحث في Azure الذكاء الاصطناعي Search.

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

نظرا لأن المصطلحات يمكن أن تكون مربكة، تجدر الإشارة إلى أن فهرسة Azure Cosmos DB وفهرسة Azure الذكاء الاصطناعي Search هي عمليات مختلفة. تؤدي الفهرسة في Azure الذكاء الاصطناعي Search إلى إنشاء فهرس بحث وتحميله على خدمة البحث.

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

• حساب Azure Cosmos DB وقاعدة البيانات والحاوية والعناصر. استخدم نفس المنطقة لكل من Azure الذكاء الاصطناعي Search وAzure Cosmos DB للحصول على زمن انتقال أقل ولتجنب رسوم النطاق الترددي.

• نهج فهرسة تلقائي على مجموعة Azure Cosmos DB، تم تعيينه إلى Consistent. هذا هو التكوين الافتراضي. لا يوصى بالفهرسة البطيئة ويمكن أن تؤدي إلى فقدان البيانات.

• قراءة الأذونات. يتضمن سلسلة الاتصال "الوصول الكامل" مفتاحا يمنح الوصول إلى المحتوى، ولكن إذا كنت تستخدم Azure RBAC (معرف Microsoft Entra)، فتأكد من تعيين الهوية المدارة لخدمة البحث لكل من دور قارئ حساب Cosmos DB ودور قارئ البيانات المضمن في Cosmos DB.

• عميل REST لإنشاء مصدر البيانات والفهرس والمفهرس.

تعريف مصدر البيانات

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

1. إنشاء مصدر بيانات أو تحديثه لتعيين تعريفه:

   POST https://[service name].search.windows.net/datasources?api-version=2023-11-01
   Content-Type: application/json
   api-key: [Search service admin key]
   {
       "name": "[my-cosmosdb-ds]",
       "type": "cosmosdb",
       "credentials": {
         "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
       },
       "container": {
         "name": "[my-cosmos-db-collection]",
         "query": null
       },
       "dataChangeDetectionPolicy": {
         "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
       "  highWaterMarkColumnName": "_ts"
       },
       "dataDeletionDetectionPolicy": null,
       "encryptionKey": null,
       "identity": null
   }
   

2. تعيين "type" إلى "cosmosdb" (مطلوب). إذا كنت تستخدم إصدارا أقدم من واجهة برمجة تطبيقات البحث 2017-11-11، فإن بناء جملة "النوع" هو "documentdb". وإلا، بالنسبة إلى 2019-05-06 والإصدارات الأحدث، استخدم "cosmosdb".

3. تعيين "بيانات الاعتماد" إلى سلسلة الاتصال. يصف القسم التالي التنسيقات المدعومة.

4. تعيين "حاوية" إلى المجموعة. خاصية "الاسم" مطلوبة وتحدد معرف مجموعة قاعدة البيانات المراد فهرستها. خاصية "الاستعلام" اختيارية. استخدمه لتبسيح مستند JSON عشوائي في مخطط مسطح يمكن ل Azure الذكاء الاصطناعي Search فهرسته.

5. قم بتعيين "dataChangeDetectionPolicy" إذا كانت البيانات متقلبة وتريد أن يلتقط المفهرس العناصر الجديدة والمحدثة فقط على عمليات التشغيل اللاحقة.

6. قم بتعيين "dataDeletionDetectionPolicy" إذا كنت تريد إزالة مستندات البحث من فهرس بحث عند حذف العنصر المصدر.

بيانات الاعتماد سلسلة الاتصال المدعومة

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

تجنب أرقام المنافذ في عنوان URL لنقطة النهاية. إذا قمت بتضمين رقم المنفذ، فسيفشل الاتصال.

سلسلة الاتصال الوصول الكامل
{ "connectionString" : "AccountEndpoint=https://<Cosmos DB account name>.documents.azure.com;AccountKey=<Cosmos DB auth key>;Database=<Cosmos DB database id>" }'
يمكنك الحصول على سلسلة الاتصال من صفحة حساب Azure Cosmos DB في مدخل Microsoft Azure عن طريق تحديد Keys في جزء التنقل الأيمن. تأكد من تحديد سلسلة الاتصال كامل وليس مجرد مفتاح.

سلسلة الاتصال الهوية المدارة
{ "connectionString" : "ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.DocumentDB/databaseAccounts/<your cosmos db account name>/;(ApiKind=[api-kind];)/(IdentityAuthType=[identity-auth-type])" }
لا يتطلب هذا سلسلة الاتصال مفتاح حساب، ولكن يجب أن يكون لديك خدمة بحث يمكنها الاتصال باستخدام هوية مدارة. بالنسبة للاتصالات التي تستهدف واجهة برمجة تطبيقات SQL، يمكنك حذف ApiKind من سلسلة الاتصال. لمزيد من المعلومات حول ApiKind، IdentityAuthType راجع إعداد اتصال مفهرس بقاعدة بيانات Azure Cosmos DB باستخدام هوية مدارة.

استخدام الاستعلامات لتشكيل البيانات المفهرسة

في الخاصية "query" ضمن "container"، يمكنك تحديد استعلام SQL لتسوية الخصائص أو الصفائف المتداخلة، ومشروع خصائص JSON، وتصفية البيانات التي سيتم فهرستها.

مثال لمستند:

    {
        "userId": 10001,
        "contact": {
            "firstName": "andy",
            "lastName": "hoh"
        },
        "company": "microsoft",
        "tags": ["azure", "cosmosdb", "search"]
    }

استعلام التصفية:

SELECT * FROM c WHERE c.company = "microsoft" and c._ts >= @HighWaterMark ORDER BY c._ts

استعلام التسوية:

SELECT c.id, c.userId, c.contact.firstName, c.contact.lastName, c.company, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

استعلام الإسقاط:

SELECT VALUE { "id":c.id, "Name":c.contact.firstName, "Company":c.company, "_ts":c._ts } FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

استعلام تسوية الصفيف:

SELECT c.id, c.userId, tag, c._ts FROM c JOIN tag IN c.tags WHERE c._ts >= @HighWaterMark ORDER BY c._ts

الاستعلامات غير المدعومة (DISTINCT وGROUP BY)

الاستعلامات التي تستخدم الكلمة الأساسية DISTINCT أو عبارة GROUP BY غير مدعومة. يعتمد Azure الذكاء الاصطناعي Search على ترقيم صفحات استعلام SQL لتعداد نتائج الاستعلام بشكل كامل. لا تتوافق الكلمة الأساسية DISTINCT أو عبارات GROUP BY مع الرموز المميزة للمتابعة المستخدمة في ترقيم النتائج.

أمثلة على الاستعلامات غير المدعومة:

SELECT DISTINCT c.id, c.userId, c._ts FROM c WHERE c._ts >= @HighWaterMark ORDER BY c._ts

SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

SELECT TOP 4 COUNT(1) AS foodGroupCount, f.foodGroup FROM Food f GROUP BY f.foodGroup

على الرغم من أن Azure Cosmos DB يحتوي على حل بديل لدعم ترقيم صفحات استعلام SQL باستخدام الكلمة الأساسية DISTINCT باستخدام عبارة ORDER BY، فإنه غير متوافق مع Azure الذكاء الاصطناعي Search. يقوم الاستعلام بإرجاع قيمة JSON واحدة، بينما يتوقع Azure الذكاء الاصطناعي Search كائن JSON.

-- The following query returns a single JSON value and isn't supported by Azure AI Search
SELECT DISTINCT VALUE c.name FROM c ORDER BY c.name

إضافة حقول بحث إلى فهرس

في فهرس البحث، أضف حقولا لقبول مستندات JSON المصدر أو إخراج إسقاط الاستعلام المخصص. تأكد من أن مخطط فهرس البحث متوافق مع بيانات المصدر. بالنسبة للمحتوى في Azure Cosmos DB، يجب أن يتوافق مخطط فهرس البحث مع عناصر Azure Cosmos DB في مصدر البيانات.

1. إنشاء فهرس أو تحديثه لتعريف حقول البحث التي تخزن البيانات:

   POST https://[service name].search.windows.net/indexes?api-version=2023-11-01
   Content-Type: application/json
   api-key: [Search service admin key]
   {
       "name": "mysearchindex",
       "fields": [{
           "name": "rid",
           "type": "Edm.String",
           "key": true,
           "searchable": false
       }, 
       {
           "name": "description",
           "type": "Edm.String",
           "filterable": false,
           "searchable": true,
           "sortable": false,
           "facetable": false,
           "suggestions": true
       }
     ]
   }
   

2. إنشاء حقل مفتاح مستند ("المفتاح": صحيح). بالنسبة للمجموعات المقسمة، يكون مفتاح المستند الافتراضي هو خاصية Azure Cosmos DB _rid ، والتي يقوم Azure الذكاء الاصطناعي Search بإعادة تسميتها rid تلقائيا لأن أسماء الحقول لا يمكن أن تبدأ بحرف تسطير أسفل السطر. أيضا، تحتوي قيم Azure Cosmos DB _rid على أحرف غير صالحة في مفاتيح البحث الذكاء الاصطناعي Azure. لهذا السبب، _rid يتم ترميز القيم Base64.

3. إنشاء المزيد من الحقول لمزيد من المحتوى القابل للبحث. راجع إنشاء فهرس للحصول على التفاصيل.

تعيين أنواع البيانات

أنواع بيانات JSON	أنواع حقول Azure الذكاء الاصطناعي Search
مجموعة	Edm.Boolean, Edm.String
الأرقام التي تبدو كأعداد صحيحة	Edm.Int32، Edm.Int64، Edm.String
الأرقام التي تبدو كنقاط عائمة	Edm.Double، Edm.String
السلسلة‬	Edm.String
صفائف من الأنواع البدائية مثل ["a", "b", "c"]	Collection(Edm.String)
السلاسل التي تبدو مثل التواريخ	Edm.DateTimeOffset, Edm.String
كائنات GeoJSON مثل { "type": "Point", "coordinates": [long, lat] }	Edm.GeographyPoint
كائنات JSON الأخرى	‏‫غير متوفر‬

تكوين وتشغيل Azure Cosmos DB لمفهرس NoSQL

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

1. إنشاء مفهرس أو تحديثه عن طريق تسميته والإشارة إلى مصدر البيانات والفهرس الهدف:

   POST https://[service name].search.windows.net/indexers?api-version=2023-11-01
   Content-Type: application/json
   api-key: [search service admin key]
   {
       "name" : "[my-cosmosdb-indexer]",
       "dataSourceName" : "[my-cosmosdb-ds]",
       "targetIndexName" : "[my-search-index]",
       "disabled": null,
       "schedule": null,
       "parameters": {
           "batchSize": null,
           "maxFailedItems": 0,
           "maxFailedItemsPerBatch": 0,
           "base64EncodeKeys": false,
           "configuration": {}
           },
       "fieldMappings": [],
       "encryptionKey": null
   }
   

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

3. راجع إنشاء مفهرس للحصول على مزيد من المعلومات حول الخصائص الأخرى.

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

التحقق من حالة المفهرس

لمراقبة حالة المفهرس ومحفوظات التنفيذ، أرسل طلب الحصول على حالة المفهرس:

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2023-11-01
  Content-Type: application/json  
  api-key: [admin key]

تتضمن الاستجابة الحالة وعدد العناصر التي تمت معالجتها. يجب أن يبدو مشابها للمثال التالي:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

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

فهرسة المستندات الجديدة والمتغيرة

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

لتمكين الفهرسة التزايدية، قم بتعيين الخاصية "dataChangeDetectionPolicy" في تعريف مصدر البيانات. تخبر هذه الخاصية المفهرس بآلية تعقب التغييرات المستخدمة على بياناتك.

بالنسبة لمفهرسات Azure Cosmos DB، فإن النهج الوحيد المدعوم هو HighWaterMarkChangeDetectionPolicy استخدام _ts خاصية (الطابع الزمني) التي يوفرها Azure Cosmos DB.

يوضح المثال التالي تعريف مصدر بيانات مع نهج الكشف عن التغيير:

"dataChangeDetectionPolicy": {
    "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
"  highWaterMarkColumnName": "_ts"
},

الفهرسة المتزايدة والاستعلامات المخصصة

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

في بعض الحالات، حتى إذا كان الاستعلام يحتوي على عبارة ORDER BY [collection alias]._ts ، فقد لا يستنتج Azure الذكاء الاصطناعي Search أن الاستعلام مرتب بواسطة _ts. يمكنك إخبار Azure الذكاء الاصطناعي Search أن النتائج مرتبة عن طريق تعيين assumeOrderByHighWaterMarkColumn خاصية التكوين.

لتحديد هذا التلميح، قم بإنشاء تعريف المفهرس أو تحديثه كما يلي:

{
    ... other indexer definition properties
    "parameters" : {
        "configuration" : { "assumeOrderByHighWaterMarkColumn" : true } }
} 

فهرسة المستندات المحذوفة

عند حذف الصفوف من المجموعة، عادة ما تريد حذف هذه الصفوف من فهرس البحث أيضا. الغرض من نهج الكشف عن حذف البيانات هو تحديد عناصر البيانات المحذوفة بكفاءة. حاليا، النهج الوحيد المدعوم هو Soft Delete النهج (يتم وضع علامة على الحذف بعلامة من نوع ما)، والذي يتم تحديده في تعريف مصدر البيانات كما يلي:

"dataDeletionDetectionPolicy"": {
    "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
    "softDeleteColumnName" : "the property that specifies whether a document was deleted",
    "softDeleteMarkerValue" : "the value that identifies a document as deleted"
}

إذا كنت تستخدم استعلاما مخصصا، فتأكد من عرض الخاصية المشار إليها بواسطة softDeleteColumnName الاستعلام.

softDeleteColumnName يجب أن يكون حقل المستوى الأعلى في الفهرس. استخدام الحقول المتداخلة ضمن أنواع البيانات المعقدة softDeleteColumnName لأن غير معتمد.

ينشئ المثال التالي مصدر بيانات بنهج حذف مبدئي:

POST https://[service name].search.windows.net/datasources?api-version=2023-11-01
Content-Type: application/json
api-key: [Search service admin key]

{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "AccountEndpoint=https://[cosmos-account-name].documents.azure.com;AccountKey=[cosmos-account-key];Database=[cosmos-database-name]"
    },
    "container": { "name": "[my-cosmos-collection]" },
    "dataChangeDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
        "highWaterMarkColumnName": "_ts"
    },
    "dataDeletionDetectionPolicy": {
        "@odata.type": "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
        "softDeleteColumnName": "isDeleted",
        "softDeleteMarkerValue": "true"
    }
}

استخدام .NET

بالنسبة إلى البيانات التي يتم الوصول إليها من خلال بروتوكول SQL API، يمكنك استخدام .NET SDK للأتمتة مع المفهرسات. نوصي بمراجعة أقسام واجهة برمجة تطبيقات REST السابقة لمعرفة المفاهيم وسير العمل والمتطلبات. يمكنك بعد ذلك الرجوع إلى الوثائق المرجعية ل .NET API التالية لتنفيذ مفهرس JSON في التعليمات البرمجية المدارة:

• azure.search.documents.indexes.models.searchindexerdatasourceconnection
• azure.search.documents.indexes.models.searchindexerdatasourcetype
• azure.search.documents.indexes.models.searchindex
• azure.search.documents.indexes.models.searchindexer

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

يمكنك الآن التحكم في كيفية تشغيل المفهرس أو مراقبة الحالة أو جدولة تنفيذ المفهرس. تنطبق المقالات التالية على المفهرسات التي تسحب المحتوى من Azure Cosmos DB:

• إعداد اتصال مفهرس بقاعدة بيانات Azure Cosmos DB باستخدام هوية مدارة
• فهرسة مجموعات البيانات الكبيرة
• وصول المفهرس إلى المحتوى المحمي بواسطة ميزات أمان شبكة Azure