التشغيل السريع: الترتيب الدلالي

في هذا البدء السريع، تستخدم مكتبة العميل Azure AI Search ل .NET لإضافة الترتيب الدلالي إلى فهرس بحث موجود واستعلام الفهرس.

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

تلميح

هل تريد get started فورا؟ قم بتحميل source code على GitHub.

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

• حساب Azure مع اشتراك نشط. أنشئ حسابا مجانا.

• An Azure AI Search service مع semantic ranker enabled.

• فهرس يحتوي على حقول نصية وصفية تنسب إلى searchable و retrievable. هذا البدء السريع يفترض مؤشر عينات الفنادق.

• .NET 9 أو أحدث.

• قم باستنساخ مستودع العينات.

• Azure CLI للمصادقة بدون مفتاح باستخدام Microsoft Entra ID.

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات access للمحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة وaccess القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين access القائم على الأدوار الموصى به:

1. فعل access المعتمدة على الأدوار search service.

2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

   • Search Service المساهم

   • قارئ بيانات فهرس البحث

‏‫ملاحظة‬

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

الحصول على نقطة النهاية

كل Search service ذكاء اصطناعي في Azure يحتوي على endpoint، وهو رابط فريد يحدد ويوفر access الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة search service الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

البدء بفهرس

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

لاستخدام فهرس مختلف، استبدل اسم الفهرس، وأسماء الحقول في التكوين الدلالي، وأسماء الحقول في عبارات الاستعلام select في جميع أنحاء الكود النموذجي. يجب أن يحتوي فهرسك على حقول نصية وصفية تنسب ك searchable و retrievable.

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

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. حدد hotels-sample.

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

   

5. اختر مستكشف البحث، ثم اختر عرض>عرض JSON.

6. قم بلصق JSON التالي في query editor.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. حدد بحث لتشغيل الاستعلام.

   يجب أن تكون الاستجابة مشابهة للمثال التالي. هذا استعلام نصي كامل مصنف حسب BM25، لذا تتطابق النتائج مع مصطلحات الاستعلام الفردية والمتغيرات اللغوية بدلا من المعنى العام للاستعلام. على سبيل المثال، تطابق walkingwalk، و live و music تطابق بشكل مستقل بدلا من أن يكون عبارة واحدة.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   تلميح

   يظهر هذا الاستعلام كيف يبدو الرد قبل تطبيق الترتيب الدلالي. بعد أن تقوم بتكوين التكوين الدلالي، أضف "queryType": "semantic" و "semanticConfiguration": "semantic-config" لترى كيف يتم ترتيب نفس الاستعلام بشكل مختلف حسب الترتيب الدلالي.

إعداد البيئة

1. استخدم Git لاستنساخ مستودع العينات.

   git clone https://github.com/Azure-Samples/azure-search-dotnet-samples
   

2. انتقل إلى مجلد البدء السريع.

   cd azure-search-dotnet-samples/quickstart-semantic-ranking
   

3. في BuildIndex/Program.cs، استبدل قيمة البديل المؤقت ل endpoint بعنوان URL الذي حصلت عليه في Get endpoint.

4. كرر الخطوة السابقة ل QueryIndex/Program.cs.

5. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على Azure AI Search service.

   az login
   

تشغيل التعليمات البرمجية

1. شغل أول project لتحديث الفهرس بتكوين دلالي.

   dotnet run --project BuildIndex
   

2. شغل project الثاني للاستعلام عن الفهرس. اضغط Enter بين الاستعلامات لرؤية التقدم من استعلام بسيط إلى استعلام دلالي مع الترجمة والإجابات.

   dotnet run --project QueryIndex
   

الإخرَاج

يقوم project الأول بتحديث مؤشر الفنادق للعينات بتكوين دلالي. يتضمن الناتج تأكيدا للتكوين الدلالي.

Here's a list of all indexes on the search service. You should see hotels-sample:
hotels-sample

Added new semantic configuration 'semantic-config' to the index definition.
Index updated successfully.
Here is the revised index definition:
{
  "Name": "hotels-sample",
  ... // Trimmed for brevity
  "SemanticSearch": {
    "DefaultConfigurationName": "semantic-config",
    "Configurations": [
      {
        "Name": "hotels-sample-semantic-configuration",
        ... // Trimmed for brevity
      },
      {
        "Name": "semantic-config",
        "PrioritizedFields": {
          "TitleField": {
            "FieldName": "HotelName"
          },
          "ContentFields": [
            {
              "FieldName": "Description"
            }
          ],
          "KeywordsFields": [
            {
              "FieldName": "Tags"
            }
          ]
        },
        "RankingOrder": {}
      }
    ]
  }
}

project الثاني يشغل أربع استفسارات. تتضمن النتائج نتائج البحث مع درجات الصلة، والترجمات، والإجابات.

Query 1: Simple query using the search string 'walking distance to live music'.
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
----------------------------------------
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 2: Semantic query (no captions, no answers) for 'walking distance to live music'.
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
@search.rerankerScore: 2.271434783935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 3: Semantic query with captions.
Caption: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.
Extractive Answers:
  Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
----------------------------------------
... // Trimmed for brevity

فهم الكود

‏‫ملاحظة‬

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

1. التكوين والمصادقة
2. تحديث الفهرس بتكوين دلالي
3. استعلام الفهرس

التكوين والمصادقة

كلا المشروعين يشتركان في نفس نمط التكوين. تحدد الملفات Program.cs نقطة نهاية البحث واستخدامها DefaultAzureCredential للمصادقة بدون مفتاح.

var endpoint = new Uri("PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE");
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(endpoint, credential);

المسارات الرئيسية:

• يوفر DefaultAzureCredential المصادقة بدون مفتاح باستخدام Microsoft Entra ID. يربط عدة أنواع من الاعتمادات، بما في ذلك Azure CLI الاعتماد من az login.
• SearchIndexClient يدير العمليات على مستوى الفهرس، مثل تحديث مخطط الفهرس.
• SearchClient تتعامل مع العمليات على مستوى المستند، مثل الاستعلام عن الفهرس.

تحديث الفهرس بتكوين دلالي

الكود التالي يضيف BuildIndex/Program.cs تكوينا دلاليا إلى الفهرس الحالي. هذه العملية لا تحذف أي مستندات بحث، ويظل الفهرس يعمل بعد إضافة التكوين.

static void AddSemanticConfiguration(
    SearchIndex index,
    string semanticConfigName)
{
    if (index.SemanticSearch == null)
    {
        index.SemanticSearch = new SemanticSearch();
    }
    var configs = index.SemanticSearch.Configurations;
    if (!configs.Any(c => c.Name == semanticConfigName))
    {
        var prioritizedFields =
            new SemanticPrioritizedFields
        {
            TitleField = new SemanticField("HotelName"),
            ContentFields =
            {
                new SemanticField("Description")
            },
            KeywordsFields =
            {
                new SemanticField("Tags")
            }
        };

        configs.Add(
            new SemanticConfiguration(
                semanticConfigName,
                prioritizedFields
            )
        );
    }
    index.SemanticSearch.DefaultConfigurationName =
        semanticConfigName;
}

المسارات الرئيسية:

• يحدد التكوين الدلالي الحقول المستخدمة في الترتيب الدلالي.
• يمكن إضافة التكوينات الدلالية إلى الفهارس الموجودة دون إعادة بناء.
• TitleField يحدد الحقل الذي يمثل عنوان المستند.
• ContentFields تحدد الحقول التي تحتوي على المحتوى الرئيسي.
• KeywordsFields تحدد الحقول التي تحتوي على كلمات مفتاحية أو وسوم.

استعلام الفهرس

يدير QueryIndex project أربع استفسارات متتالية، تتقدم من بحث بسيط بالكلمات المفتاحية إلى ترتيب دلالي مع الترجمة والإجابات.

استعلام نموذجي

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

await RunQuery(client, searchText, new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Simple,
    IncludeTotalCount = true,
    Select = { "HotelId", "HotelName", "Description" }
});

المسارات الرئيسية:

• SearchQueryType.Simple يستخدم خوارزمية الترتيب الافتراضية BM25.
• يتم ترتيب النتائج حسب صلة الكلمات المفتاحية (@search.score) فقط.

استفسار دلالي (بدون تعليقات، بدون إجابات)

الاستفسار التالي يضيف ترتيبا دلاليا بدون تعليقات أو إجابات. يوضح الكود التالي الحد الأدنى من المتطلب لتفعيل التصنيف الدلالي.

var semanticOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config"
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(client, searchText, semanticOptions);

المسارات الرئيسية:

• SearchQueryType.Semantic تمكين الترتيب الدلالي على الاستعلام.
• SemanticConfigurationName يحدد أي تكوين دلالي يجب استخدامه.
• @search.rerankerScore يشير إلى الصلة الدلالية (الأعلى أفضل).
• يتم إعادة تقييم النتائج الأولية من مصطلح الاستعلام باستخدام نماذج التصنيف الدلالية. بالنسبة لهذه المجموعة من البيانات والاستعلام، تكون تأثيرات الترتيب الدلالي أكثر وضوحا في النتائج ذات المرتبة الأدنى.

استعلام دلالي مع تعليقات

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

var captionsOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryCaption =
            new QueryCaption(QueryCaptionType.Extractive)
        {
            HighlightEnabled = true
        }
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
captionsOptions.HighlightFields.Add("Description");
await RunQuery(
    client, searchText, captionsOptions, showCaptions: true
);

المسارات الرئيسية:

• QueryCaption تمكين الترجمة التوضيحية الاستخراجية من حقول المحتوى.
• الترجمة surface المقاطع الأكثر صلة وأضف وسوم <em> حول المصطلحات المهمة.

استعلام دلالي مع إجابات

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

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

var answersOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryAnswer =
            new QueryAnswer(QueryAnswerType.Extractive)
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(
    client, searchText2, answersOptions, showAnswers: true
);

المسارات الرئيسية:

• QueryAnswer تمكين الإجابات الاستخراجية للاستفسارات الشبيهة بالسؤال.
• الإجابات هي محتوى حرفي مستخرج من فهرسك، وليست نصا مولدا.

في هذا البدء السريع، تستخدم مكتبة العملاء Azure AI Search لجافا لإضافة semantic ranking إلى فهرس بحث موجود وتستعلام الفهرس.

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

تلميح

هل تريد get started فورا؟ قم بتحميل source code على GitHub.

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

• حساب Azure مع اشتراك نشط. أنشئ حسابا مجانا.

• An Azure AI Search service مع semantic ranker enabled.

• فهرس يحتوي على حقول نصية وصفية تنسب إلى searchable و retrievable. هذا البدء السريع يفترض مؤشر عينات الفنادق.

• Java 21 (LTS) و Maven.

• قم باستنساخ مستودع العينات.

• Azure CLI للمصادقة بدون مفتاح باستخدام Microsoft Entra ID.

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات access للمحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة وaccess القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين access القائم على الأدوار الموصى به:

1. فعل access المعتمدة على الأدوار search service.

2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

   • Search Service المساهم

   • قارئ بيانات فهرس البحث

‏‫ملاحظة‬

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

الحصول على نقطة النهاية

كل Search service ذكاء اصطناعي في Azure يحتوي على endpoint، وهو رابط فريد يحدد ويوفر access الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة search service الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

البدء بفهرس

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

لاستخدام فهرس مختلف، استبدل اسم الفهرس، وأسماء الحقول في التكوين الدلالي، وأسماء الحقول في عبارات الاستعلام select في جميع أنحاء الكود النموذجي. يجب أن يحتوي فهرسك على حقول نصية وصفية تنسب ك searchable و retrievable.

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

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. حدد hotels-sample.

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

   

5. اختر مستكشف البحث، ثم اختر عرض>عرض JSON.

6. قم بلصق JSON التالي في query editor.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. حدد بحث لتشغيل الاستعلام.

   يجب أن تكون الاستجابة مشابهة للمثال التالي. هذا استعلام نصي كامل مصنف حسب BM25، لذا تتطابق النتائج مع مصطلحات الاستعلام الفردية والمتغيرات اللغوية بدلا من المعنى العام للاستعلام. على سبيل المثال، تطابق walkingwalk، و live و music تطابق بشكل مستقل بدلا من أن يكون عبارة واحدة.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   تلميح

   يظهر هذا الاستعلام كيف يبدو الرد قبل تطبيق الترتيب الدلالي. بعد أن تقوم بتكوين التكوين الدلالي، أضف "queryType": "semantic" و "semanticConfiguration": "semantic-config" لترى كيف يتم ترتيب نفس الاستعلام بشكل مختلف حسب الترتيب الدلالي.

إعداد البيئة

1. استخدم Git لاستنساخ مستودع العينات.

   git clone https://github.com/Azure-Samples/azure-search-java-samples
   

2. انتقل إلى مجلد البدء السريع.

   cd azure-search-java-samples/quickstart-semantic-ranking
   

3. في src/main/resources/application.properties، استبدل قيمة البديل المؤقت ل azure.search.endpoint بعنوان URL الذي حصلت عليه في Get endpoint.

4. تجميع project لحل التبعيات، بما في ذلك azure-search-documents.

   mvn compile
   

   عند اكتمال البناء، تحقق من عدم ظهور أي أخطاء في المخرج.

5. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على Azure AI Search service.

   az login
   

تشغيل التعليمات البرمجية

1. احصل على إعدادات الفهرس الحالية.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.GetIndexSettings"
   

2. قم بتحديث الفهرس بتكوين دلالي.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.UpdateIndexSettings"
   

3. أجر استعلاما دلاليا.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQuery"
   

4. قم بإجراء استعلام دلالي مع التعليقات.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQueryWithCaptions"
   

5. شغل استعلاما دلاليا مع الإجابات.

   mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticAnswer"
   

الإخرَاج

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

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic search configurations: 1
Configuration name: hotels-sample-semantic-configuration

يعرض مخرجات UpdateIndexSettings.java جميع التكوينات الدلالية على الفهرس، بما في ذلك التكوينة التي أضافها الكود، تليها رسالة نجاح.

// Trimmed for brevity
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

يعيد الناتج SemanticQuery.java جميع المستندات المتطابقة المرتبة حسب درجة إعادة ترتيب الترتيب الدلالي.

Search result #1:
  Re-ranker Score: 2.61
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.27
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.99
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

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

Search result #1:
  Re-ranker Score: 2.61
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.27
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

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

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.98

Search Results:

Search result #1:
Re-ranker Score: 2.12
Hotel: Stay-Kay City Hotel
Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.

Search result #2:
Re-ranker Score: 2.07
Hotel: Double Sanctuary Resort
Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
Caption: <em>5 star Luxury Hotel </em>-<em> Biggest </em>Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
// Trimmed for brevity

فهم الكود

‏‫ملاحظة‬

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

1. التكوين والمصادقة
2. تحديث الفهرس بتكوين دلالي
3. استعلام الفهرس

التكوين والمصادقة

تقوم الفئة SearchConfig.java بتحميل الخصائص من application.properties وإنشاء a DefaultAzureCredential للمصادقة بدون مفتاح.

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;

public class SearchConfig {
    private static final Properties properties =
        new Properties();

    static {
        try (InputStream input = SearchConfig.class
            .getClassLoader()
            .getResourceAsStream(
                "application.properties")) {
            properties.load(input);
        } catch (IOException e) {
            throw new RuntimeException(
                "Failed to load application.properties",
                e);
        }
    }

    public static final String SEARCH_ENDPOINT =
        properties.getProperty(
            "azure.search.endpoint");
    public static final String INDEX_NAME =
        properties.getProperty(
            "azure.search.index.name");
    public static final String SEMANTIC_CONFIG_NAME =
        properties.getProperty(
            "semantic.configuration.name");

    public static final DefaultAzureCredential
        CREDENTIAL = new DefaultAzureCredentialBuilder()
            .build();
}

المسارات الرئيسية:

• يوفر DefaultAzureCredential المصادقة بدون مفتاح باستخدام Microsoft Entra ID. يربط عدة أنواع من الاعتمادات، بما في ذلك Azure CLI الاعتماد من az login.
• يتم تحميل الخصائص من الملف application.properties في مسار الclasspath.
• الحقول الثابتة (SEARCH_ENDPOINT، INDEX_NAME، SEMANTIC_CONFIG_NAME، CREDENTIAL) مشتركة بين جميع الفئات في project.

تحديث الفهرس بتكوين دلالي

تضيف الفئة UpdateIndexSettings.java تكوينة دلالية إلى الفهرس الحالي hotels-sample . هذه العملية لا تحذف أي مستندات بحث، ويظل الفهرس يعمل بعد إضافة التكوين.

import com.azure.search.documents.indexes
    .SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models
    .SearchIndex;
import com.azure.search.documents.indexes.models
    .SemanticConfiguration;
import com.azure.search.documents.indexes.models
    .SemanticField;
import com.azure.search.documents.indexes.models
    .SemanticPrioritizedFields;
import com.azure.search.documents.indexes.models
    .SemanticSearch;

import java.util.ArrayList;
import java.util.List;

var indexClient = new SearchIndexClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

SearchIndex existingIndex =
    indexClient.getIndex(SearchConfig.INDEX_NAME);

var prioritizedFields =
    new SemanticPrioritizedFields()
        .setTitleField(
            new SemanticField("HotelName"))
        .setKeywordsFields(
            List.of(new SemanticField("Tags")))
        .setContentFields(
            List.of(
                new SemanticField("Description")));

var newSemanticConfiguration =
    new SemanticConfiguration(
        SearchConfig.SEMANTIC_CONFIG_NAME,
        prioritizedFields);

SemanticSearch semanticSearch =
    existingIndex.getSemanticSearch();
if (semanticSearch == null) {
    semanticSearch = new SemanticSearch();
    existingIndex.setSemanticSearch(semanticSearch);
}

List<SemanticConfiguration> configurations =
    semanticSearch.getConfigurations();
if (configurations == null) {
    configurations = new ArrayList<>();
    semanticSearch.setConfigurations(configurations);
}

configurations.add(newSemanticConfiguration);

indexClient.createOrUpdateIndex(existingIndex);

المسارات الرئيسية:

• SemanticPrioritizedFields يحدد أي الحقول يقيمها المصنف الدلالي. setTitleField يحدد عنوان المستند، setContentFields ويحدد المحتوى الرئيسي، ويحدد setKeywordsFields حقول الكلمات المفتاحية أو الوسوم.
• SemanticConfiguration يربط الاسم مع الحقول ذات الأولوية، ويحدد أي تكوين دلالي يجب استخدامه في وقت الاستعلام.
• createOrUpdateIndex يدفع المخطط المحدث إلى search service دون إعادة بناء الفهرس أو حذف المستندات.

استعلام الفهرس

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

استفسار دلالي (بدون تعليقات، بدون إجابات)

الاستفسار الأول يضيف ترتيبا دلاليا بدون تعليقات أو إجابات. تظهر الفئة SemanticQuery.java الحد الأدنى من المتطلب لتفعيل التصنيف الدلالي.

import com.azure.search.documents
    .SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryType;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.SearchResult;
import com.azure.search.documents.models
    .SemanticSearchOptions;
import com.azure.search.documents.util
    .SearchPagedIterable;

var searchClient = new SearchClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .indexName(SearchConfig.INDEX_NAME)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME))
    .setSelect("HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    var document = result.getDocument(
        SearchDocument.class);
    double rerankerScore = result
        .getSemanticSearch().getRerankerScore();

    System.out.printf("Re-ranker Score: %.2f%n",
        rerankerScore);
    System.out.printf("HotelName: %s%n",
        document.get("HotelName"));
    System.out.printf("Description: %s%n%n",
        document.get("Description"));
}

المسارات الرئيسية:

• QueryType.SEMANTIC تمكين الترتيب الدلالي على الاستعلام.
• setSemanticConfigurationName يحدد أي تكوين دلالي يجب استخدامه.
• SearchPagedIterable يقدم تكرارا على النتائج المعاد ترتيبها. كل واحدة SearchResult تحتوي على getSemanticSearch() ملحق لدرجة إعادة الترتيب.

استعلام دلالي مع تعليقات

تضيف الفئة SemanticQueryWithCaptions.java تعليقات لاستخراج المقاطع الأكثر صلة من كل نتيجة، مع تطبيق تمييز الضربات على المصطلحات والعبارات المهمة.

import com.azure.search.documents.models
    .QueryCaption;
import com.azure.search.documents.models
    .QueryCaptionResult;
import com.azure.search.documents.models
    .QueryCaptionType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE)
                    .setHighlightEnabled(true)))
    .setSelect(
        "HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    List<QueryCaptionResult> captions =
        result.getSemanticSearch()
            .getQueryCaptions();
    if (captions != null && !captions.isEmpty()) {
        QueryCaptionResult caption = captions.get(0);
        if (caption.getHighlights() != null) {
            System.out.printf(
                "Caption: %s%n",
                caption.getHighlights());
        }
    }
}

المسارات الرئيسية:

• QueryCaption(QueryCaptionType.EXTRACTIVE) تمكين الترجمة التوضيحية الاستخراجية من حقول المحتوى.
• setHighlightEnabled(true) يضيف <em> علامات حول المصطلحات المهمة في الترجمة.
• كل منهما SearchResult يوفر getQueryCaptions() أداة البحث الدلالي.

استعلام دلالي مع إجابات

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

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

import com.azure.search.documents.models
    .QueryAnswer;
import com.azure.search.documents.models
    .QueryAnswerResult;
import com.azure.search.documents.models
    .QueryAnswerType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE))
            .setQueryAnswer(
                new QueryAnswer(
                    QueryAnswerType.EXTRACTIVE)))
    .setSelect(
        "HotelName", "Description", "Category");

SearchPagedIterable results = searchClient.search(
    "What's a good hotel for people who like to read",
    searchOptions, null);

List<QueryAnswerResult> semanticAnswers =
    results.getSemanticResults().getQueryAnswers();

for (QueryAnswerResult answer :
    semanticAnswers != null ? semanticAnswers
        : List.<QueryAnswerResult>of()) {
    if (answer.getHighlights() != null) {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getHighlights());
    } else {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getText());
    }
    System.out.printf(
        "Semantic Answer Score: %.2f%n",
        answer.getScore());
}

المسارات الرئيسية:

• QueryAnswer(QueryAnswerType.EXTRACTIVE) تمكين الإجابات الاستخراجية للاستفسارات الشبيهة بالسؤال.
• الإجابات هي محتوى حرفي مستخرج من فهرسك، وليست نصا مولدا.
• results.getSemanticResults().getQueryAnswers() يسترجع كائنات الإجابة بشكل منفصل عن نتائج البحث.

في هذا البدء السريع، تستخدم مكتبة العملاء Azure AI Search لجافا سكريبت لإضافة الترتيب الدلالي إلى فهرس بحث موجود واستعلام الفهرس.

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

تلميح

هل تريد get started فورا؟ قم بتحميل source code على GitHub.

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

• حساب Azure مع اشتراك نشط. أنشئ حسابا مجانا.

• An Azure AI Search service مع semantic ranker enabled.

• فهرس يحتوي على حقول نصية وصفية تنسب إلى searchable و retrievable. هذا البدء السريع يفترض مؤشر عينات الفنادق.

• Node.js 20 LTS أو أكثر.

• قم باستنساخ مستودع العينات.

• Azure CLI للمصادقة بدون مفتاح باستخدام Microsoft Entra ID.

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات access للمحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة وaccess القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين access القائم على الأدوار الموصى به:

1. فعل access المعتمدة على الأدوار search service.

2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

   • Search Service المساهم

   • قارئ بيانات فهرس البحث

‏‫ملاحظة‬

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

الحصول على نقطة النهاية

كل Search service ذكاء اصطناعي في Azure يحتوي على endpoint، وهو رابط فريد يحدد ويوفر access الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة search service الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

البدء بفهرس

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

لاستخدام فهرس مختلف، استبدل اسم الفهرس، وأسماء الحقول في التكوين الدلالي، وأسماء الحقول في عبارات الاستعلام select في جميع أنحاء الكود النموذجي. يجب أن يحتوي فهرسك على حقول نصية وصفية تنسب ك searchable و retrievable.

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

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. حدد hotels-sample.

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

   

5. اختر مستكشف البحث، ثم اختر عرض>عرض JSON.

6. قم بلصق JSON التالي في query editor.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. حدد بحث لتشغيل الاستعلام.

   يجب أن تكون الاستجابة مشابهة للمثال التالي. هذا استعلام نصي كامل مصنف حسب BM25، لذا تتطابق النتائج مع مصطلحات الاستعلام الفردية والمتغيرات اللغوية بدلا من المعنى العام للاستعلام. على سبيل المثال، تطابق walkingwalk، و live و music تطابق بشكل مستقل بدلا من أن يكون عبارة واحدة.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   تلميح

   يظهر هذا الاستعلام كيف يبدو الرد قبل تطبيق الترتيب الدلالي. بعد أن تقوم بتكوين التكوين الدلالي، أضف "queryType": "semantic" و "semanticConfiguration": "semantic-config" لترى كيف يتم ترتيب نفس الاستعلام بشكل مختلف حسب الترتيب الدلالي.

إعداد البيئة

1. استخدم Git لاستنساخ مستودع العينات.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. انتقل إلى مجلد البدء السريع.

   cd azure-search-javascript-samples/quickstart-semantic-ranking-js
   

3. في sample.env، استبدل قيمة البديل المؤقت ل AZURE_SEARCH_ENDPOINT بعنوان URL الذي حصلت عليه في Get endpoint.

4. أعد تسمية sample.env إلى .env.

   mv sample.env .env
   

5. ثبّت التبعيات.

   npm install
   

   عند اكتمال التثبيت، يجب أن ترى مجلد node_modules في مجلد project.

6. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على Azure AI Search service.

   az login
   

تشغيل التعليمات البرمجية

1. احصل على إعدادات الفهرس الحالية.

   node -r dotenv/config src/getIndexSettings.js
   

2. قم بتحديث الفهرس بتكوين دلالي.

   node -r dotenv/config src/updateIndexSettings.js
   

3. أجر استعلاما دلاليا.

   node -r dotenv/config src/semanticQuery.js
   

4. قم بإجراء استعلام دلالي مع التعليقات.

   node -r dotenv/config src/semanticQueryReturnCaptions.js
   

5. شغل استعلاما دلاليا مع الإجابات.

   node -r dotenv/config src/semanticAnswer.js
   

الإخرَاج

يعيد السكربت getIndexSettings.js اسم الفهرس، وحقوله، وأي تكوينات دلالية موجودة.

Getting semantic ranking index settings...
Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
Field: Description_fr, Type: Edm.String, Searchable: true
Field: Category, Type: Edm.String, Searchable: true
Field: Tags, Type: Collection(Edm.String), Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

يعيد السكربت updateIndexSettings.js جميع التكوينات الدلالية على الفهرس، بما في ذلك التكوين الذي أضاف الكود، يليه رسالة نجاح.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

يعيد السكربت semanticQuery.js جميع المستندات المطابقة المرتبة حسب درجة إعادة ترتيب الترتيب الدلالي.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.9861756563186646
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

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

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

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

Answers:

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
// Trimmed for brevity

فهم الكود

‏‫ملاحظة‬

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

1. التكوين والمصادقة
2. تحديث الفهرس بتكوين دلالي
3. استعلام الفهرس

التكوين والمصادقة

يقوم الملف config.js بتحميل متغيرات البيئة وينشئ متغيرات DefaultAzureCredential للمصادقة.

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

المسارات الرئيسية:

• يوفر DefaultAzureCredential المصادقة بدون مفتاح باستخدام Microsoft Entra ID. يربط عدة أنواع من الاعتمادات، بما في ذلك Azure CLI الاعتماد من az login.
• يتم تحميل متغيرات البيئة من .env الملف باستخدام dotenv.

تحديث الفهرس بتكوين دلالي

يضيف الملف updateIndexSettings.js تكوينة دلالية إلى الفهرس الحالي hotels-sample . هذه العملية لا تحذف أي مستندات بحث، ويظل الفهرس يعمل بعد إضافة التكوين.

import { SearchIndexClient }
    from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields = {
    titleField: { name: "HotelName" },
    keywordsFields: [{ name: "Tags" }],
    contentFields: [{ name: "Description" }]
};

const newSemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

المسارات الرئيسية:

• يحدد التكوين الدلالي الحقول المستخدمة في الترتيب الدلالي. titleField يحدد عنوان المستند، contentFields ويحدد المحتوى الرئيسي، ويحدد keywordsFields حقول الكلمات المفتاحية أو الوسوم.
• تقوم بإنشاء كائن تكوين وتدفعه إلى مصفوفة الفهرس semanticSearch.configurations الحالية.
• createOrUpdateIndex يدفع المخطط المحدث إلى search service دون إعادة بناء الفهرس أو حذف المستندات.

استعلام الفهرس

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

استفسار دلالي (بدون تعليقات، بدون إجابات)

يوضح الكود التالي الحد الأدنى من المتطلب لتفعيل التصنيف الدلالي.

import { SearchClient }
    from "@azure/search-documents";
import {
    credential, searchEndpoint,
    indexName, semanticConfigurationName
} from "./config.js";

const searchClient = new SearchClient(
    searchEndpoint, indexName, credential
);

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

المسارات الرئيسية:

• queryType: "semantic" تمكين الترتيب الدلالي على الاستعلام.
• semanticSearchOptions.configurationName يحدد أي تكوين دلالي يجب استخدامه.
• تشير النتائج rerankerScore إلى الصلة الدلالية (الأعلى أفضل).

استعلام دلالي مع تعليقات

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

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

المسارات الرئيسية:

• captions.captionType: "extractive" تمكين الترجمة التوضيحية الاستخراجية من حقول المحتوى.
• الترجمة surface المقاطع الأكثر صلة وأضف وسوم <em> حول المصطلحات المهمة.

استعلام دلالي مع إجابات

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

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

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

المسارات الرئيسية:

• answers.answerType: "extractive" تمكين الإجابات الاستخراجية للاستفسارات الشبيهة بالسؤال.
• الإجابات هي محتوى حرفي مستخرج من فهرسك، وليست نصا مولدا.
• results.answers يسترجع كائنات الإجابة بشكل منفصل عن نتائج البحث.

في هذا البدء السريع، تستخدم مكتبة العملاء Azure AI Search ل Python لإضافة الترتيب الدلالي إلى فهرس بحث موجود وتستعلام الفهرس.

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

تلميح

هل تريد get started فورا؟ قم بتحميل source code على GitHub.

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

• حساب Azure مع اشتراك نشط. أنشئ حسابا مجانا.

• An Azure AI Search service مع semantic ranker enabled.

• فهرس يحتوي على حقول نصية وصفية تنسب إلى searchable و retrievable. هذا البدء السريع يفترض مؤشر عينات الفنادق.

• Python 3.10 أو أحدث.

• Visual Studio Code مع <امتداد c1>Python.

• قم باستنساخ مستودع العينات.

• Azure CLI للمصادقة بدون مفتاح باستخدام Microsoft Entra ID.

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات access للمحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة وaccess القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين access القائم على الأدوار الموصى به:

1. فعل access المعتمدة على الأدوار search service.

2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

   • Search Service المساهم

   • قارئ بيانات فهرس البحث

‏‫ملاحظة‬

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

الحصول على نقطة النهاية

كل Search service ذكاء اصطناعي في Azure يحتوي على endpoint، وهو رابط فريد يحدد ويوفر access الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة search service الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

البدء بفهرس

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

لاستخدام فهرس مختلف، استبدل اسم الفهرس، وأسماء الحقول في التكوين الدلالي، وأسماء الحقول في عبارات الاستعلام select في جميع أنحاء الكود النموذجي. يجب أن يحتوي فهرسك على حقول نصية وصفية تنسب ك searchable و retrievable.

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

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. حدد hotels-sample.

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

   

5. اختر مستكشف البحث، ثم اختر عرض>عرض JSON.

6. قم بلصق JSON التالي في query editor.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. حدد بحث لتشغيل الاستعلام.

   يجب أن تكون الاستجابة مشابهة للمثال التالي. هذا استعلام نصي كامل مصنف حسب BM25، لذا تتطابق النتائج مع مصطلحات الاستعلام الفردية والمتغيرات اللغوية بدلا من المعنى العام للاستعلام. على سبيل المثال، تطابق walkingwalk، و live و music تطابق بشكل مستقل بدلا من أن يكون عبارة واحدة.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   تلميح

   يظهر هذا الاستعلام كيف يبدو الرد قبل تطبيق الترتيب الدلالي. بعد أن تقوم بتكوين التكوين الدلالي، أضف "queryType": "semantic" و "semanticConfiguration": "semantic-config" لترى كيف يتم ترتيب نفس الاستعلام بشكل مختلف حسب الترتيب الدلالي.

إعداد البيئة

1. استخدم Git لاستنساخ مستودع العينات.

   git clone https://github.com/Azure-Samples/azure-search-python-samples
   

2. انتقل إلى مجلد البدء السريع وافتحه في Visual Studio Code.

   cd azure-search-python-samples/Quickstart-Semantic-Ranking
   code .
   

3. في sample.env، استبدل قيمة البديل المؤقت ل AZURE_SEARCH_ENDPOINT بعنوان URL الذي حصلت عليه في Get endpoint.

4. أعد تسمية sample.env إلى .env.

   mv sample.env .env
   

5. افتح semantic-ranking-quickstart.ipynb.

6. اضغط Ctrl+Shift+P، اختر نوت بوتبوت: اختر نواة نوت بوتبوت، واتبع التعليمات لإنشاء بيئة افتراضية. اختر requirements.txt للتبعيات.

   عند الانتهاء، يجب أن ترى مجلد .venv في مجلد project.

7. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على Azure AI Search service.

   az login
   

تشغيل التعليمات البرمجية

1. شغل الخلايا Install packages and set variables لتثبيت الحزم المطلوبة ومتغيرات بيئة التحميل.

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

الإخرَاج

مخرج Get the index definition الخلية هو اسم الفهرس، وحقوله، وأي تكوينات دلالية موجودة.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: True
Field: HotelName, Type: Edm.String, Searchable: True
Field: Description, Type: Edm.String, Searchable: True
Field: Description_fr, Type: Edm.String, Searchable: True
Field: Category, Type: Edm.String, Searchable: True
Field: Tags, Type: Collection(Edm.String), Searchable: True
// Trimmed for brevity
Semantic config: hotels-sample-semantic-configuration
Title field: HotelName

يسرد مخرج Add a semantic configuration to the index الخلية جميع التكوينات الدلالية على الفهرس، بما في ذلك التكوينة التي أضافها الكود، تليها رسالة نجاح.

Semantic configurations:
----------------------------------------
  Configuration: hotels-sample-semantic-configuration
    Title field: HotelName
    Keywords fields: Category
    Content fields: Description

  Configuration: semantic-config
    Title field: HotelName
    Keywords fields: Tags
    Content fields: Description

✅ Semantic configuration successfully added!

يعيد مخرج Run a term query الخلية جميع المستندات المتطابقة المرتبة حسب درجة BM25. هذا الاستعلام الأساسي لا يستخدم التصنيف الدلالي.

5.360838
4
Sublime Palace Hotel
Description: Sublime Cliff Hotel is located in the heart of the
historic center of Sublime in an extremely vibrant and lively area
within short walking distance to the sites and landmarks of the city
and is surrounded by the extraordinary beauty of churches, buildings,
shops and monuments. Sublime Cliff is part of a lovingly restored
19th century resort, updated for every modern convenience.
4.691083
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

يعيد مخرج Run a semantic query الخلية جميع المستندات المطابقة المرتبة حسب درجة إعادة ترتيب الدلالة.

2.613231658935547
24
Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to theaters, art galleries, restaurants and
shops. Visit Seattle Art Museum by day, and then head over to
Benaroya Hall to catch the evening's concert performance.
2.271434783935547
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

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

2.613231658935547
24
Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to theaters, art galleries, restaurants and
shops. Visit Seattle Art Museum by day, and then head over to
Benaroya Hall to catch the evening's concert performance.
Caption: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to<em> theaters, </em>art galleries,
restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and
then head over to<em> Benaroya Hall </em>to catch the evening's
concert performance.
// Trimmed for brevity

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

Semantic Answer: Nature is Home on the beach. Explore the shore by
day, and then come home to our shared living space to relax around a
stone fireplace, sip something warm, and explore the<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

فهم الكود

‏‫ملاحظة‬

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

1. التكوين والمصادقة
2. تحديث الفهرس بتكوين دلالي
3. استعلام الفهرس

التكوين والمصادقة

تقوم الخلية Install packages and set variables بتحميل متغيرات البيئة وإنشاء متغيرات DefaultAzureCredential للمصادقة.

from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.identity import get_bearer_token_provider
import os

load_dotenv(override=True)

search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = os.getenv(
    "AZURE_SEARCH_INDEX", "hotels-sample"
)

المسارات الرئيسية:

• يوفر DefaultAzureCredential المصادقة بدون مفتاح باستخدام Microsoft Entra ID. يربط عدة أنواع من الاعتمادات، بما في ذلك Azure CLI الاعتماد من az login.
• يتم تحميل متغيرات البيئة من .env الملف باستخدام python-dotenv.

تحديث الفهرس بتكوين دلالي

تضيف الخلية Add a semantic configuration to the index تكوينة دلالية إلى الفهرس الموجود hotels-sample . هذه العملية لا تحذف أي مستندات بحث، ويظل الفهرس يعمل بعد إضافة التكوين.

from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

new_semantic_config = SemanticConfiguration(
    name="semantic-config",
    prioritized_fields=SemanticPrioritizedFields(
        title_field=SemanticField(field_name="HotelName"),
        keywords_fields=[
            SemanticField(field_name="Tags")
        ],
        content_fields=[
            SemanticField(field_name="Description")
        ]
    )
)

if existing_index.semantic_search is None:
    existing_index.semantic_search = SemanticSearch(
        configurations=[new_semantic_config]
    )
else:
    existing_index.semantic_search.configurations.append(
        new_semantic_config
    )

result = index_client.create_or_update_index(existing_index)

المسارات الرئيسية:

• يحدد التكوين الدلالي الحقول المستخدمة في الترتيب الدلالي. title_field يحدد عنوان المستند، content_fields ويحدد المحتوى الرئيسي، ويحدد keywords_fields حقول الكلمات المفتاحية أو الوسوم.
• تقوم بإنشاء التكوين مع SemanticConfiguration والنموذج المرتبط SemanticPrioritizedFields به، ثم تضيفه إلى الفهرس الحالي.
• create_or_update_index يدفع المخطط المحدث إلى search service دون إعادة بناء الفهرس أو حذف المستندات.

استعلام الفهرس

تشغل خلايا الاستعلام أربع استعلامات متتالية: بحث أساسي في الكلمات المفتاحية يتبعه ثلاث تغييرات في الترتيب الدلالي مع زيادة في الوظائف.

استعلام المصطلح (خط الأساس)

تقوم الخلية Run a term query بإجراء بحث كلمات مفتاحية باستخدام تقييم BM25. هذا الاستعلام الأساسي لا يستخدم التصنيف الدلالي ويعمل كنقطة مقارنة.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='simple',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    include_total_count=True
)

المسارات الرئيسية:

• query_type='simple' يحدد بحث الكلمات المفتاحية باستخدام تقييم BM25.
• تشير النتائج @search.score إلى درجة الصلة ل BM25.

استفسار دلالي (بدون تعليقات، بدون إجابات)

تظهر الخلية Run a semantic query الحد الأدنى من المتطلب لتفعيل التصنيف الدلالي.

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    query_caption='extractive'
)

المسارات الرئيسية:

• query_type='semantic' تمكين الترتيب الدلالي على الاستعلام.
• semantic_configuration_name يحدد أي تكوين دلالي يجب استخدامه.
• تشير النتائج @search.reranker_score إلى الصلة الدلالية (الأعلى أفضل).

استعلام دلالي مع تعليقات

تضيف الخلية Return captions تعليقات لاستخراج المقاطع الأكثر صلة من كل نتيجة، مع تطبيق تمييز الضغط على المصطلحات والعبارات المهمة.

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelName,HotelId,Description',
    query_caption='extractive'
)

for result in results:
    captions = result["@search.captions"]
    if captions:
        caption = captions[0]
        if caption.highlights:
            print(f"Caption: {caption.highlights}\n")

المسارات الرئيسية:

• query_caption='extractive' تمكين الترجمة التوضيحية الاستخراجية من حقول المحتوى.
• الترجمة surface المقاطع الأكثر صلة وأضف وسوم <em> حول المصطلحات المهمة.

استعلام دلالي مع إجابات

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

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

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="what's a good hotel for people who "
                "like to read",
    select='HotelName,Description,Category',
    query_caption='extractive',
    query_answer="extractive",
)

semantic_answers = results.get_answers()
for answer in semantic_answers:
    if answer.highlights:
        print(f"Semantic Answer: {answer.highlights}")
    else:
        print(f"Semantic Answer: {answer.text}")
    print(f"Semantic Answer Score: {answer.score}\n")

المسارات الرئيسية:

• query_answer="extractive" تمكين الإجابات الاستخراجية للاستفسارات الشبيهة بالسؤال.
• الإجابات هي محتوى حرفي مستخرج من فهرسك، وليست نصا مولدا.
• results.get_answers() يسترجع كائنات الإجابة بشكل منفصل عن نتائج البحث.

في هذا البدء السريع، تستخدم مكتبة العملاء Azure AI Search ل JavaScript (المتوافقة مع TypeScript) لإضافة semantic ranking إلى فهرس بحث موجود وتستعل الفهرس.

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

تلميح

هل تريد get started فورا؟ قم بتحميل source code على GitHub.

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

• حساب Azure مع اشتراك نشط. أنشئ حسابا مجانا.

• An Azure AI Search service مع semantic ranker enabled.

• فهرس يحتوي على حقول نصية وصفية تنسب إلى searchable و retrievable. هذا البدء السريع يفترض مؤشر عينات الفنادق.

• Node.js 20 LTS أو بعد ذلك لتشغيل الكود المترجم.

• TypeScript لترجمة TypeScript إلى JavaScript.

• قم باستنساخ مستودع العينات.

• Azure CLI للمصادقة بدون مفتاح باستخدام Microsoft Entra ID.

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات access للمحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة وaccess القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين access القائم على الأدوار الموصى به:

1. فعل access المعتمدة على الأدوار search service.

2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

   • Search Service المساهم

   • قارئ بيانات فهرس البحث

‏‫ملاحظة‬

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

الحصول على نقطة النهاية

كل Search service ذكاء اصطناعي في Azure يحتوي على endpoint، وهو رابط فريد يحدد ويوفر access الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة search service الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

البدء بفهرس

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

لاستخدام فهرس مختلف، استبدل اسم الفهرس، وأسماء الحقول في التكوين الدلالي، وأسماء الحقول في عبارات الاستعلام select في جميع أنحاء الكود النموذجي. يجب أن يحتوي فهرسك على حقول نصية وصفية تنسب ك searchable و retrievable.

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

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. حدد hotels-sample.

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

   

5. اختر مستكشف البحث، ثم اختر عرض>عرض JSON.

6. قم بلصق JSON التالي في query editor.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. حدد بحث لتشغيل الاستعلام.

   يجب أن تكون الاستجابة مشابهة للمثال التالي. هذا استعلام نصي كامل مصنف حسب BM25، لذا تتطابق النتائج مع مصطلحات الاستعلام الفردية والمتغيرات اللغوية بدلا من المعنى العام للاستعلام. على سبيل المثال، تطابق walkingwalk، و live و music تطابق بشكل مستقل بدلا من أن يكون عبارة واحدة.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   تلميح

   يظهر هذا الاستعلام كيف يبدو الرد قبل تطبيق الترتيب الدلالي. بعد أن تقوم بتكوين التكوين الدلالي، أضف "queryType": "semantic" و "semanticConfiguration": "semantic-config" لترى كيف يتم ترتيب نفس الاستعلام بشكل مختلف حسب الترتيب الدلالي.

إعداد البيئة

1. استخدم Git لاستنساخ مستودع العينات.

   git clone https://github.com/Azure-Samples/azure-search-javascript-samples
   

2. انتقل إلى مجلد البدء السريع.

   cd azure-search-javascript-samples/quickstart-semantic-ranking-ts
   

3. في sample.env، استبدل قيمة البديل المؤقت ل AZURE_SEARCH_ENDPOINT بعنوان URL الذي حصلت عليه في Get endpoint.

4. أعد تسمية sample.env إلى .env.

   mv sample.env .env
   

5. ثبّت التبعيات.

   npm install
   

   عند اكتمال التثبيت، يجب أن ترى مجلد node_modules في مجلد project.

6. قم بتجميع ملفات TypeScript إلى JavaScript.

   npm run build
   

7. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على Azure AI Search service.

   az login
   

تشغيل التعليمات البرمجية

1. احصل على إعدادات الفهرس الحالية.

   node -r dotenv/config dist/getIndexSettings.js
   

2. قم بتحديث الفهرس بتكوين دلالي.

   node -r dotenv/config dist/updateIndexSettings.js
   

3. أجر استعلاما دلاليا.

   node -r dotenv/config dist/semanticQuery.js
   

4. قم بإجراء استعلام دلالي مع التعليقات.

   node -r dotenv/config dist/semanticQueryReturnCaptions.js
   

5. شغل استعلاما دلاليا مع الإجابات.

   node -r dotenv/config dist/semanticAnswer.js
   

   ‏‫ملاحظة‬

   تقوم هذه الأوامر بتشغيل الملفات المترجمة .js من المجلد dist . يجب تحويل كود TypeScript إلى JavaScript قبل Node.js تتمكن من تنفيذه، ولهذا السبب قمت بتشغيل npm run build.

الإخرَاج

يعيد السكربت getIndexSettings.js اسم الفهرس، وعدد الحقول، وتفاصيل الحقول مع النوع والحالة القابلة للبحث، وأي تكوينات دلالية موجودة.

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

updateIndexSettings.js النص يعيد جميع التكوينات الدلالية، بما في ذلك التي أضفتها.

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

يعيد السكربت semanticQuery.js النتائج المرتبة حسب درجة المعاد ترتيب.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown,
  within walking distance to theaters, art galleries, restaurants and
  shops. Visit Seattle Art Museum by day, and then head over to
  Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza...
  // Trimmed for brevity

يعيد النص semanticQueryReturnCaptions.js تعليقات استخراجية مع تمييز ضربات الضربة. التسميات التوضيحية هي المقاطع الأكثر صلة في النتيجة.

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown,
  within walking distance to theaters, art galleries, restaurants and
  shops. Visit Seattle Art Museum by day, and then head over to
  Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel
  in downtown, within walking distance to<em> theaters, </em>art
  galleries, restaurants and shops. Visit<em> Seattle Art Museum
  </em>by day, and then head over to<em> Benaroya Hall </em>to catch
  the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  // Trimmed for brevity

يعيد النص semanticAnswer.js إجابة دلالية (محتوى حرفي) مأخوذة من النتيجة تتطابق مع السؤال بشكل أفضل.

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by
day, and then come home to our shared living space to relax around
a stone fireplace, sip something warm, and explore the<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the
main commercial artery of the city in the heart of New York...
Caption: This classic hotel is<em> fully-refurbished </em>and
ideally located on the main commercial artery of the city...
// Trimmed for brevity

فهم الكود

‏‫ملاحظة‬

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

1. التكوين والمصادقة
2. تحديث الفهرس بتكوين دلالي
3. استعلام الفهرس

التكوين والمصادقة

يقوم الملف config.ts بتحميل متغيرات البيئة، وينشئ a DefaultAzureCredential للمصادقة، ويحدد واجهة HotelDocument لسلامة النوع.

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

export interface HotelDocument {
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
}

المسارات الرئيسية:

• يوفر DefaultAzureCredential المصادقة بدون مفتاح باستخدام Microsoft Entra ID. يربط عدة أنواع من الاعتمادات، بما في ذلك Azure CLI الاعتماد من az login.
• توفر واجهة HotelDocument فحص أنواع الترجمة لنتائج البحث، مما يضمن access آمنة للنوع إلى حقول التوثيق.
• يتم تحميل متغيرات البيئة من .env الملف باستخدام dotenv.

تحديث الفهرس بتكوين دلالي

يضيف الملف updateIndexSettings.ts تكوينة دلالية إلى الفهرس الحالي hotels-sample . هذه العملية لا تحذف أي مستندات بحث، ويظل الفهرس يعمل بعد إضافة التكوين. تضمن تعليقات نوع TypeScript تطابق التكوين مع المخطط المتوقع.

import {
    SearchIndexClient,
    SemanticConfiguration,
    SemanticPrioritizedFields,
    SemanticField
} from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields: SemanticPrioritizedFields = {
    titleField: { name: "HotelName" },
    keywordsFields: [
        { name: "Tags" }
    ] as SemanticField[],
    contentFields: [
        { name: "Description" }
    ] as SemanticField[]
};

const newSemanticConfiguration:
    SemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

المسارات الرئيسية:

• أنواع TypeScript مثل SemanticPrioritizedFields، SemanticConfiguration، وتوفر SemanticField التحقق من صحة وقت الترجمة لبنية التكوين.
• titleField يحدد عنوان المستند، contentFields ويحدد المحتوى الرئيسي، ويحدد keywordsFields حقول الكلمات المفتاحية أو الوسوم.
• createOrUpdateIndex يدفع المخطط المحدث إلى search service دون إعادة بناء الفهرس أو حذف المستندات.

استعلام الفهرس

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

استفسار دلالي (بدون تعليقات، بدون إجابات)

يظهر السكربت semanticQuery.ts الحد الأدنى من المتطلب لتفعيل التصنيف الدلالي مع نتائج آمنة للنوع.

import { SearchClient }
    from "@azure/search-documents";
import {
    HotelDocument, credential,
    searchEndpoint, indexName,
    semanticConfigurationName
} from "./config.js";

const searchClient =
    new SearchClient<HotelDocument>(
        searchEndpoint, indexName, credential
    );

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

المسارات الرئيسية:

• يوفر SearchClient<HotelDocument> access آمنة للنوع لتوثيق الحقول في النتائج، مع إكمال تلقائي لأسماء الحقول في select و result.document.
• queryType: "semantic" تمكين الترتيب الدلالي على الاستعلام.
• semanticSearchOptions.configurationName يحدد أي تكوين دلالي يجب استخدامه.

استعلام دلالي مع تعليقات

يضيف النص semanticQueryReturnCaptions.ts تعليقات لاستخراج المقاطع الأكثر صلة من كل نتيجة، مع تطبيق تمييز الضغطات على المصطلحات والعبارات المهمة.

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

المسارات الرئيسية:

• captions.captionType: "extractive" تمكين الترجمة التوضيحية الاستخراجية من حقول المحتوى.
• الترجمة surface المقاطع الأكثر صلة وأضف وسوم <em> حول المصطلحات المهمة.

استعلام دلالي مع إجابات

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

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

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

المسارات الرئيسية:

• answers.answerType: "extractive" تمكين الإجابات الاستخراجية للاستفسارات الشبيهة بالسؤال.
• الإجابات هي محتوى حرفي مستخرج من فهرسك، وليست نصا مولدا.
• results.answers يسترجع كائنات الإجابة بشكل منفصل عن نتائج البحث.

في هذه البداية السريعة، تستخدم واجهات برمجة التطبيقات Azure AI Search REST لإضافة الترتيب الدلالي إلى فهرس بحث موجود وتستعلام الفهرس.

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

تلميح

هل تريد get started فورا؟ قم بتحميل source code على GitHub.

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

• حساب Azure مع اشتراك نشط. أنشئ حسابا مجانا.

• An Azure AI Search service مع semantic ranker enabled.

• فهرس يحتوي على حقول نصية وصفية تنسب إلى searchable و retrievable. هذا البدء السريع يفترض مؤشر عينات الفنادق.

• Visual Studio Code مع REST Client Extension.

• قم باستنساخ مستودع العينات.

• Azure CLI للمصادقة بدون مفتاح باستخدام Microsoft Entra ID.

تكوين الوصول

قبل أن تبدأ، تأكد من أن لديك صلاحيات access للمحتوى والعمليات في Azure AI Search. يستخدم هذا البدء السريع معرف Microsoft Entra ID للمصادقة وaccess القائم على الأدوار للتفويض. يجب أن تكون Owner أو User Access Administrator لتعيين الأدوار. إذا لم تكن الأدوار ممكنة، فاستخدم المصادقة المستندة إلى المفتاح بدلا من ذلك.

لتكوين access القائم على الأدوار الموصى به:

1. فعل access المعتمدة على الأدوار search service.

2. قم بتعيين الأدوار التالية لحساب المستخدم الخاص بك.

   • Search Service المساهم

   • قارئ بيانات فهرس البحث

‏‫ملاحظة‬

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

الحصول على نقطة النهاية

كل Search service ذكاء اصطناعي في Azure يحتوي على endpoint، وهو رابط فريد يحدد ويوفر access الشبكة للخدمة. في قسم لاحق، تحدد هذه النقطة النهائية للاتصال بخدمة search service الخاصة بك بشكل برمجي.

للحصول على نقطة النهاية:

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. دون نقطة النهاية، والتي يجب أن تبدو https://my-service.search.windows.net.

البدء بفهرس

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

لاستخدام فهرس مختلف، استبدل اسم الفهرس، وأسماء الحقول في التكوين الدلالي، وأسماء الحقول في عبارات الاستعلام select في جميع أنحاء الكود النموذجي. يجب أن يحتوي فهرسك على حقول نصية وصفية تنسب ك searchable و retrievable.

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

1. انتقل إلى خدمة البحث في مدخل Microsoft Azure.

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

3. حدد hotels-sample.

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

   

5. اختر مستكشف البحث، ثم اختر عرض>عرض JSON.

6. قم بلصق JSON التالي في query editor.

   {
     "search": "walking distance to live music",
     "select": "HotelId, HotelName, Description",
     "count": true
   }
   

7. حدد بحث لتشغيل الاستعلام.

   يجب أن تكون الاستجابة مشابهة للمثال التالي. هذا استعلام نصي كامل مصنف حسب BM25، لذا تتطابق النتائج مع مصطلحات الاستعلام الفردية والمتغيرات اللغوية بدلا من المعنى العام للاستعلام. على سبيل المثال، تطابق walkingwalk، و live و music تطابق بشكل مستقل بدلا من أن يكون عبارة واحدة.

   "@odata.count": 30,
   "value": [
     {
       "@search.score": 5.004435,
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
     },
     {
       "@search.score": 4.555706,
       "HotelId": "24",
       "HotelName": "Uptown Chic Hotel",
       "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
     },
     {
       "@search.score": 3.5625167,
       "HotelId": "4",
       "HotelName": "Sublime Palace Hotel",
       "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
     },
     ... // Trimmed for brevity
   ]
   

   تلميح

   يظهر هذا الاستعلام كيف يبدو الرد قبل تطبيق الترتيب الدلالي. بعد أن تقوم بتكوين التكوين الدلالي، أضف "queryType": "semantic" و "semanticConfiguration": "semantic-config" لترى كيف يتم ترتيب نفس الاستعلام بشكل مختلف حسب الترتيب الدلالي.

إعداد البيئة

1. استخدم Git لاستنساخ مستودع العينات.

   git clone https://github.com/Azure-Samples/azure-search-rest-samples
   

2. انتقل إلى مجلد البدء السريع وافتحه في Visual Studio Code.

   cd azure-search-rest-samples/Quickstart-semantic-ranking
   code .
   

3. في semantic-index-update.rest، استبدل قيمة البديل المؤقت ل @searchUrl بعنوان URL الذي حصلت عليه في Get endpoint.

4. كرر الخطوة السابقة ل semantic-query.rest.

5. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، سجل الدخول إلى حسابك في Azure. إذا كان لديك عدة اشتراكات، اختر الاشتراك الذي يحتوي على Azure AI Search service.

   az login
   

6. للمصادقة بدون مفتاح باستخدام Microsoft Entra ID، قم بإنشاء رمز access.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

7. في كلا .rest الملفين، استبدل قيمة البديل ل @personalAccessToken بالرمز من الخطوة السابقة.

تشغيل التعليمات البرمجية

1. افتح semantic-index-update.rest.

2. اختر إرسال الطلب في أول طلب GET للتحقق من اتصالك.

   يجب أن تظهر استجابة في جزء مجاور. إذا كان لديك فهارس موجودة، فهي مدرجة بالاسم. إذا كان رمز HTTP هو 200 OK، فأنت جاهز للمتابعة.

3. أرسل الطلب ### Update the hotels-sample index to include a semantic configuration لإضافة تكوين دلالي إلى الفهرس.

   إذا حصلت على 400 Bad Request خطأ، فإن مخطط الفهرس يختلف عن العينة. أرسل الطلب ### Get the schema of the index ، انسخ JSON الرد، أضف القسم semantic من كود المصدر إلى JSON، واستبدل جسم طلب PUT بمخطط مدمج.

4. انتقل إلى semantic-query.rest وأرسل الطلبات بالتسلسل: استعلام بسيط للمقارنة الأساسية، ثم استعلامات دلالية مع الترتيب، الترجمة، والإجابات.

الإخرَاج

يعيد الطلب Send a search query to the hotels-sample index النتائج المرتبة حسب الصلة BM25، والتي يشار إليها في @search.score الحقل.

{
  "@odata.count": 30,
  "value": [
    {
      "@search.score": 5.004435,
      "HotelId": "2",
      "HotelName": "Old Century Hotel",
      "Description": "The hotel is situated in a nineteenth century plaza..."
    },
    // Trimmed for brevity
  ]
}

يضيف Send a search query to the hotels-sample index with semantic rankingالطلب @search.rerankerScore . لاحظ أن الترتيب يتغير عن الاستعلام البسيط.

{
  "@odata.count": 30,
  "@search.answers": [],
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown..."
    },
    // Trimmed for brevity
  ]
}

Return captions in the query الطلب يضيف @search.captions مع نص مستخرج وتمييزات.

{
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops...",
          "highlights": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops..."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel"
    },
    // Trimmed for brevity
  ]
}

يرجع الطلب Return semantic answers in the query إجابة استخراجية في @search.answers عندما يصاغ الاستعلام كسؤال.

{
  "@odata.count": 46,
  "@search.answers": [
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night...",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night...",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.060124,
      "@search.rerankerScore": 2.124817371368408,
      "@search.captions": [
        {
          "text": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city...",
          "highlights": "This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city..."
        }
      ],
      "HotelId": "1",
      "HotelName": "Stay-Kay City Hotel"
    },
    // Trimmed for brevity
  ]
}

فهم الكود

‏‫ملاحظة‬

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

الآن بعد أن قمت بتشغيل التعليمات البرمجية ، دعنا نقسم الخطوات الرئيسية:

1. التكوين والمصادقة
2. تحديث الفهرس بتكوين دلالي
3. استعلام الفهرس

التكوين والمصادقة

كلا .rest الملفين يعرفان متغيرات في الأعلى لإعادة الاستخدام عبر جميع الطلبات.

@searchUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@personalAccessToken = PUT-YOUR-PERSONAL-ACCESS-TOKEN-HERE
@api-version = 2025-09-01

المسارات الرئيسية:

• @searchUrl هو نهاية search service لديك.
• @personalAccessToken هو رمز Microsoft Entra ID يتم الحصول عليه من Azure CLI. هذا يستبدل مفاتيح واجهة برمجة التطبيقات بالمصادقة بدون مفتاح.
• Authorization: Bearer {{personalAccessToken}} يتم تضمينها في كل رأس طلب للمصادقة.

تحديث الفهرس بتكوين دلالي

### Update the hotels-sample index to include a semantic configuration الطلب في semantic-index-update.rest يرسل مخطط الفهرس الكامل مع قسم جديدsemantic. تتطلب واجهة برمجة تطبيقات REST المخطط الكامل لأي عملية تحديث، لذلك لا يمكنك إرسال التكوين الدلالي فقط.

الإضافة الرئيسية هي القسم semantic :

"semantic": {
    "configurations": [
        {
            "name": "semantic-config",
            "rankingOrder":
                "BoostedRerankerScore",
            "prioritizedFields": {
                "titleField": {
                    "fieldName": "HotelName"
                },
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ],
                "prioritizedKeywordsFields": [
                    {
                        "fieldName": "Tags"
                    }
                ]
            }
        }
    ]
}

المسارات الرئيسية:

• titleField يحدد أي حقل يحتوي على عنوان المستند للتقييم الدلالي.
• prioritizedContentFields يحدد الحقول الرئيسية للمحتوى. يقوم المصنف الدلالي بتقييم هذه الأمور أولا عند تقييم الأهمية.
• prioritizedKeywordsFields يحدد حقول الكلمات المفتاحية أو الوسوم لمزيد من السياق.
• rankingOrder: BoostedRerankerScore يجمع بين درجة BM25 ودرجة إعادة ترتيب الدلالة.
• تتطلب واجهة برمجة تطبيقات REST المخطط الكامل لعمليات PUT. القسم فقط semantic جديد؛ جميع الحقول الأخرى لم تتغير.

استعلام الفهرس

الطلبات جارية semantic-query.rest من بحث بسيط بالكلمات المفتاحية إلى ترتيب دلالي مع الترجمة والإجابات. جميع الاستعلامات هي طلبات POST إلى المستندات - البحث في Post (واجهة برمجة تطبيقات REST).

استعلام نموذجي

الطلب ### Send a search query to the hotels-sample index هو بحث بسيط عن الكلمات المفتاحية لا يستخدم الترتيب الدلالي. يعمل كأساس لمقارنة النتائج مع وبدون إعادة ترتيب دلالية.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "simple"
}

المسارات الرئيسية:

• queryType: "simple" يستخدم خوارزمية الترتيب الافتراضية BM25.
• يتم ترتيب النتائج حسب صلة الكلمات المفتاحية (@search.score) فقط.

استفسار دلالي (بدون تعليقات، بدون إجابات)

### Send a search query to the hotels-sample index with semantic ranking الطلب يضيف ترتيبا دلاليا. يظهر JSON التالي الحد الأدنى من المتطلب لتفعيل التصنيف الدلالي.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config"
}

المسارات الرئيسية:

• queryType: "semantic" تمكين الترتيب الدلالي على الاستعلام.
• semanticConfiguration يحدد أي تكوين دلالي يجب استخدامه.

استعلام دلالي مع تعليقات

يضيف الطلب ### Return captions in the query تعليقات لاستخراج المقاطع الأكثر صلة من كل نتيجة، مع تطبيق تمييز الضغط على المصطلحات والعبارات المهمة.

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true"
}

المسارات الرئيسية:

• captions: "extractive|highlight-true" يتيح الترجمة الاستخراجية مع <em> وسوم حول المصطلحات المهمة.
• تظهر الترجمة في المصفوفة @search.captions لكل نتيجة.

استعلام دلالي مع إجابات

### Return semantic answers in the query الطلب يضيف إجابات دلالية. يستخدم السؤال كنص بحث لأن الإجابات الدلالية تعمل بشكل أفضل عندما يصاغ الاستعلام كسؤال. الإجابة هي مقطع حرفي مستخرج من فهرسك، وليس إجابة مكتوبة من نموذج إكمال المحادثة.

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

{
    "search":
        "what's a good hotel for people who like to read",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive"
}

المسارات الرئيسية:

• answers: "extractive" تمكين الإجابات الاستخراجية للاستفسارات الشبيهة بالسؤال.
• تظهر الإجابات في المصفوفة العليا @search.answers منفصلة عن النتائج الفردية.
• الإجابات هي محتوى حرفي مستخرج من فهرسك، وليست نصا مولدا.

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

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

في Azure portal، اختر All resources أو Resource groups من اللوحة اليسرى للعثور على الموارد وإدارتها. يمكنك حذف الموارد بشكل فردي أو حذف مجموعة الموارد لإزالة كل الموارد دفعة واحدة.

المحتوى ذو الصلة

• الترتيب الدلالي في Azure AI Search
• تكوين مصنف دلالي
• إضافة إعادة كتابة الاستعلام إلى التصنيف الدلالي
• استخدم ملفات التسجيل مع الترتيب الدلالي