مشاركة عبر


البرنامج التعليمي: الفهرس من مصادر بيانات متعددة باستخدام NET SDK.

يدعم Azure الذكاء الاصطناعي Search استيراد البيانات وتحليلها وفهرستها من مصادر بيانات متعددة إلى فهرس بحث موحد واحد.

يستخدم هذا البرنامج التعليمي C# مكتبة عميل Azure.Search.Documents في Azure SDK ل .NET لفهرسة نموذج بيانات الفندق من مثيل Azure Cosmos DB. ثم تقوم بدمج البيانات مع تفاصيل غرفة الفندق المستمدة من مستندات Azure Blob Storage. والنتيجة هي فهرس بحث مجمع للفنادق يحتوي على مستندات فندقية، مع غرف لأنواع بيانات معقدة.

في هذا البرنامج التعليمي، سوف تتعلّم:

  • رفع بيانات العينة إلى مصادر البيانات
  • تحديد مفتاح المستند
  • تحديد وإنشاء الفهرس
  • فهرسة بيانات الفندق من Azure Cosmos DB
  • دمج بيانات غرف الفنادق من Blob Storage

نظرة عامة

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

يمكن العثور على نسخة نهائية من التعليمة البرمجية في هذا البرنامج التعليمي في المشروع التالي:

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

ملاحظة

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

تحضير الخدمات

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

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

تستخدم هذه العينة مجموعتين صغيرتين من البيانات التي تصف سبعة فنادق خيالية. تصف مجموعة واحدة الفنادق نفسها وسيتم تحميلها في قاعدة بيانات Azure Cosmos DB. تحتوي المجموعة الأخرى على تفاصيل غرفة الفندق ويتم توفيرها على أنها سبعة ملفات JSON منفصلة ليتم تحميلها إلى Azure Blob Storage.

البدء ب Azure Cosmos DB

  1. سجل الدخول إلى بوابة Azure واختر حساب Azure Cosmos DB الخاص بك.

  2. من اللوحة اليسرى، اختر مستكشف البيانات.

  3. اختر قاعدةبيانات>.

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

  4. ادخل اسم hotel-rooms-db . اقبل القيم الافتراضية للإعدادات المتبقية.

    تكوين قاعدة البيانات

  5. أنشئ حاوية تستهدف قاعدة البيانات التي أنشأتها سابقا. أدخل الفنادق لاسم الحاوية و /HotelId لمفتاح القسم.

    إضافة حاوية

  6. اخترعناصر>، ثم اختر رفع العنصر في شريط الأوامر.

  7. قم بتحميل ملف JSON من المجلد cosmosdb في multiple-data-sources/v11.

    تحميل إلى مجموعة Azure Cosmos DB

  8. استخدم زر التحديث لتحديث رؤيتك للعناصر في مجموعة الفنادق. يجب أن ترى سبعة مستندات قاعدة بيانات جديدة مدرجة.

  9. من الجزء الأيمن، حدد Settings>Keys.

  10. دون ملاحظة لسلسلة الاتصال. تحتاج إلى هذه القيمة appsettings.json في خطوة لاحقة. إذا لم تستخدم اسم قاعدة بيانات hotel-rooms-db المقترح، انسخ اسم قاعدة البيانات أيضا.

Azure Blob Storage

  1. سجل الدخول إلى مدخل Microsoft Azure وحدد حساب Azure Storage الخاص بك.

  2. من الجزء الأيمن، حددحاويات> البيانات.

  3. إنشاء حاوية كائن ثنائي كبير الحجم تسمى hotel-rooms لتخزين نموذج ملفات JSON لغرفة الفندق. يمكنك ضبط مستوى الوصول لأي قيمة صحيحة.

    إنشاء حاوية BLOB

  4. افتح الحاوية، ثم اختر رفع الإعدادات في شريط الأوامر.

  5. قم بتحميل ملفات JSON السبعة من المجلد blob في multiple-data-sources/v11.

    تحميل الملفات

  6. من الجزء الأيمن، حدد Security + networking>Access keys.

  7. سجل اسم الحساب وسلسلة الاتصال. تحتاج إلى كلتا القيمتين appsettings.json في خطوة لاحقة.

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

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

  1. سجل الدخول إلى مدخل Microsoft Azure وحدد خدمة البحث.

  2. من الجزء الأيمن، حدد نظرة عامة.

  3. قم بتدوين عنوان URL ، والذي يجب أن يبدو مثل https://my-service.search.windows.net.

  4. من الجزء الأيمن، حدد Settings>Keys.

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

إعداد بيئتك

  1. افتح الملف AzureSearchMultipleDataSources.sln من multiple-data-sources/v11 في Visual Studio.

  2. في مستكشف الحلول، انقر بزر الفأرة الأيمن على المشروع واختر إدارة حزم NuGet للحل....

  3. في تبويب التصفح ، ابحث عن الحزم التالية وثبت الآن:

    • Azure.Search.Documents (الإصدار 11.0 أو أحدث)

    • Microsoft.Extensions.Configuration

    • Microsoft.Extensions.Configuration.Json

  4. في مستكشف الحلول، عدل الملف appsettings.json بمعلومات الاتصال التي جمعتها في الخطوات السابقة.

    {
      "SearchServiceUri": "<YourSearchServiceURL>",
      "SearchServiceAdminApiKey": "<YourSearchServiceAdminApiKey>",
      "BlobStorageAccountName": "<YourBlobStorageAccountName>",
      "BlobStorageConnectionString": "<YourBlobStorageConnectionString>",
      "CosmosDBConnectionString": "<YourCosmosDBConnectionString>",
      "CosmosDBDatabaseName": "hotel-rooms-db"
    }
    

تعيين حقول المفاتيح

يتطلب دمج المحتوى أن كلاً من دفق البيانات يستهدف نفس المستندات في فهرس البحث.

في Azure الذكاء الاصطناعي Search، يعرف حقل المفتاح كل مستند بشكل فريد. يجب أن يحتوي كل فهرس بحث على حقل مفتاح واحد بالضبط من النوع Edm.String. يجب أن يكون حقل المفتاح هذا موجودًا لكل مستند في مصدر بيانات تمت إضافته إلى الفهرس. (في الواقع، هذا هو الحقل الوحيد المطلوب.)

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

غالبا ما يتطلب الأمر بعض التخطيط المسبق لتحديد مفتاح مستند ذي معنى للفهرس والتأكد من وجوده في كلا مصدري البيانات. في هذا العرض التوضيحي، HotelId يوجد مفتاح كل فندق في Azure Cosmos DB أيضا في كتل JSON في Blob Storage.

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

ملاحظة

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

استكشاف التعليمات البرمجية

عندما تكون إعدادات البيانات والتكوين جاهزة، يجب أن يكون البرنامج النموذجي جاهزا AzureSearchMultipleDataSources.sln للبناء والتشغيل.

هذا التطبيق وحدة التحكم C#/.NET بسيط ينفذ المهام التالية:

  • ينشئ فهرسا جديدا استنادا إلى بنية البيانات لفئة فندق C#، والتي تشير أيضا إلى فئتي العنوان والغرفة.
  • ينشئ مصدر بيانات جديدًا ومفهرسًا يقوم بتعيين بيانات Azure Cosmos DB لفهرسة الحقول. كلاهما كائنان في Azure الذكاء الاصطناعي Search.
  • تشغيل المفهرس لتحميل بيانات الفندق من Azure Cosmos DB.
  • ينشئ مصدر بيانات ثانيًا ومفهرسًا يقوم بتعيين بيانات JSON blob لفهرسة الحقول.
  • يشغل الفهرس الثاني لتحميل بيانات غرف الفندق من تخزين Blob.

قبل تشغيل البرنامج، خذ دقيقة لدراسة الكود، تعريف الفهرس، وتعريف المؤشر. الكود ذو الصلة موجود في ملفين:

  • Hotel.cs يحتوي على المخطط الذي يحدد الفهرس.
  • Program.cs يحتوي على وظائف تنشئ فهرس Azure الذكاء الاصطناعي للبحث، ومصادر البيانات، والفهارسات، وتحميل النتائج المجمعة في الفهرس.

إنشاء فهرس

يستخدم هذا البرنامج النموذجي CreateIndexAsync لتعريف وإنشاء فهرس Azure الذكاء الاصطناعي Search. يستفيد من فئة FieldBuilder لإنشاء بنية فهرس من فئة نموذج بيانات C#‎.

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

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

تظهر المقتطفات التالية من Hotel.cs الملف حقول فردية، تليها إشارة إلى فئة نموذج بيانات أخرى، Room[]، والتي بدورها تعرف في Room.cs الملف (غير معروضة).

. . .
[SimpleField(IsFilterable = true, IsKey = true)]
public string HotelId { get; set; }

[SearchableField(IsFilterable = true, IsSortable = true)]
public string HotelName { get; set; }
. . .
public Room[] Rooms { get; set; }
. . .

في Program.cs الملف، يتم تعريف SearchIndex مع اسم ومجموعة حقول يتم توليدها بواسطة FieldBuilder.Build الطريقة، ثم يتم إنشاؤها كما يلي:

private static async Task CreateIndexAsync(string indexName, SearchIndexClient indexClient)
{
    // Create a new search index structure that matches the properties of the Hotel class.
    // The Address and Room classes are referenced from the Hotel class. The FieldBuilder
    // will enumerate these to create a complex data structure for the index.
    FieldBuilder builder = new FieldBuilder();
    var definition = new SearchIndex(indexName, builder.Build(typeof(Hotel)));

    await indexClient.CreateIndexAsync(definition);
}

أنشئ مفهرس ومصدر بيانات Azure Cosmos DB

يتضمن البرنامج الرئيسي منطقا لإنشاء مصدر بيانات Azure Cosmos DB لبيانات الفنادق.

أولا، يقوم بسلسلة اسم قاعدة بيانات Azure Cosmos DB إلى سلسلة الاتصال. ثم يعرف كائن SearchIndexerDataSourceConnection .

private static async Task CreateAndRunCosmosDbIndexerAsync(string indexName, SearchIndexerClient indexerClient)
{
    // Append the database name to the connection string
    string cosmosConnectString =
        configuration["CosmosDBConnectionString"]
        + ";Database="
        + configuration["CosmosDBDatabaseName"];

    SearchIndexerDataSourceConnection cosmosDbDataSource = new SearchIndexerDataSourceConnection(
        name: configuration["CosmosDBDatabaseName"],
        type: SearchIndexerDataSourceType.CosmosDb,
        connectionString: cosmosConnectString,
        container: new SearchIndexerDataContainer("hotels"));

    // The Azure Cosmos DB data source does not need to be deleted if it already exists,
    // but the connection string might need to be updated if it has changed.
    await indexerClient.CreateOrUpdateDataSourceConnectionAsync(cosmosDbDataSource);

بعد إنشاء مصدر البيانات، يقوم البرنامج بإعداد مؤشر بيانات Azure Cosmos باسم hotel-rooms-cosmos-indexer.

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

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

SearchIndexer cosmosDbIndexer = new SearchIndexer(
    name: "hotel-rooms-cosmos-indexer",
    dataSourceName: cosmosDbDataSource.Name,
    targetIndexName: indexName)
{
    Schedule = new IndexingSchedule(TimeSpan.FromDays(1))
};

// Indexers keep metadata about how much they have already indexed.
// If we already ran the indexer, it "remembers" and does not run again.
// To avoid this, reset the indexer if it exists.
try
{
    await indexerClient.GetIndexerAsync(cosmosDbIndexer.Name);
    // Reset the indexer if it exists.
    await indexerClient.ResetIndexerAsync(cosmosDbIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
    // If the indexer does not exist, 404 will be thrown.
}

await indexerClient.CreateOrUpdateIndexerAsync(cosmosDbIndexer);

Console.WriteLine("Running Azure Cosmos DB indexer...\n");

try
{
    // Run the indexer.
    await indexerClient.RunIndexerAsync(cosmosDbIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 429)
{
    Console.WriteLine("Failed to run indexer: {0}", ex.Message);
}

يتضمن هذا المثال كتلة try-catch بسيطة للإبلاغ عن أي أخطاء قد تحدث في أثناء التنفيذ.

بعد تشغيل مفهرس Azure Cosmos DB، يحتوي فهرس البحث على مجموعة كاملة من نماذج مستندات الفندق. ومع ذلك، فإن حقل الغرف لكل فندق عبارة عن صفيف فارغ، نظرا لأن مصدر بيانات Azure Cosmos DB يحذف تفاصيل الغرفة. بعد ذلك، يسحب البرنامج من Blob Storage لتحميل ودمج بيانات الغرفة.

إنشاء مصدر بيانات ومؤشر تخزين Blob

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

private static async Task CreateAndRunBlobIndexerAsync(string indexName, SearchIndexerClient indexerClient)
{
    SearchIndexerDataSourceConnection blobDataSource = new SearchIndexerDataSourceConnection(
        name: configuration["BlobStorageAccountName"],
        type: SearchIndexerDataSourceType.AzureBlob,
        connectionString: configuration["BlobStorageConnectionString"],
        container: new SearchIndexerDataContainer("hotel-rooms"));

    // The blob data source does not need to be deleted if it already exists,
    // but the connection string might need to be updated if it has changed.
    await indexerClient.CreateOrUpdateDataSourceConnectionAsync(blobDataSource);

بعد إنشاء مصدر البيانات، يقوم البرنامج بإعداد مؤشر كتلة يسمى hotel-rooms-blob-indexer، كما هو موضح أدناه.

تحتوي الكائنات الثنائية كبيرة الحجم JSON على حقل مفتاح يسمى Id بدلا من HotelId. تستخدم التعليمات البرمجية FieldMapping الفئة لإخبار المفهرس بتوجيه Id قيمة الحقل إلى HotelId مفتاح المستند في الفهرس.

يمكن لفهرسات تخزين الكتل استخدام IndexingParameters لتحديد وضع تحليل. يجب تعيين أوضاع تحليل مختلفة استنادا إلى ما إذا كانت الكائنات الثنائية كبيرة الحجم تمثل مستندا واحدا أو مستندات متعددة داخل نفس الكائن الثنائي كبير الحجم. في هذا المثال، يمثل كل كائن ثنائي كبير الحجم مستند JSON واحدا، لذلك تستخدم التعليمات البرمجية json وضع التحليل. لمزيد من المعلومات حول معلمات تحليل المفهرس لكائنات JSON الثنائية كبيرة الحجم، راجع فهرسة الكائنات الثنائية كبيرة الحجم ل JSON.

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

IndexingParameters parameters = new IndexingParameters();
parameters.Configuration.Add("parsingMode", "json");

SearchIndexer blobIndexer = new SearchIndexer(
    name: "hotel-rooms-blob-indexer",
    dataSourceName: blobDataSource.Name,
    targetIndexName: indexName)
{
    Parameters = parameters,
    Schedule = new IndexingSchedule(TimeSpan.FromDays(1))
};

// Map the Id field in the Room documents to the HotelId key field in the index
blobIndexer.FieldMappings.Add(new FieldMapping("Id") { TargetFieldName = "HotelId" });

// Reset the indexer if it already exists
try
{
    await indexerClient.GetIndexerAsync(blobIndexer.Name);
    await indexerClient.ResetIndexerAsync(blobIndexer.Name);
}
catch (RequestFailedException ex) when (ex.Status == 404) { }

await indexerClient.CreateOrUpdateIndexerAsync(blobIndexer);

try
{
    // Run the indexer.
    await searchService.Indexers.RunAsync(blobIndexer.Name);
}
catch (CloudException e) when (e.Response.StatusCode == (HttpStatusCode)429)
{
    Console.WriteLine("Failed to run indexer: {0}", e.Response.Content);
}

نظرا لأن الفهرس تم ملؤه بالفعل ببيانات الفندق من قاعدة بيانات Azure Cosmos DB، يقوم مفهرس الكائن الثنائي كبير الحجم بتحديث المستندات الموجودة في الفهرس ويضيف تفاصيل الغرفة.

ملاحظة

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

بعد تشغيل البرنامج، يمكنك استكشاف فهرس البحث المملوء باستخدام Search Explorer في بوابة Azure.

  1. سجل الدخول إلى مدخل Microsoft Azure وحدد خدمة البحث.

  2. من الجزء الأيمن، حددفهارس إدارة >البحث.

  3. اختر عينة غرف الفنادق من قائمة الفهارس.

  4. في تبويب مستكشف البحث ، أدخل استعلاما عن مصطلح مثل Luxury.

    يجب أن ترى على الأقل وثيقة واحدة في النتائج. يجب أن يحتوي هذا المستند على قائمة بكائنات الغرف في مصفوفته Rooms .

إعادة تعيين وإعادة تشغيل

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

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

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

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

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

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

الآن بعد أن أصبحت على دراية ب استيعاب البيانات من مصادر متعددة، ألق نظرة فاحصة على تكوين المفهرس، بدءا من Azure Cosmos DB: