إضافة اقتراحات الإكمال التلقائي والبحث في تطبيقات العميل

البحث عند الكتابة هو أسلوب شائع لتحسين إنتاجية الاستعلام. في Azure الذكاء الاصطناعي Search، يتم دعم هذه التجربة من خلال الإكمال التلقائي، والذي ينتهي من مصطلح أو عبارة استنادا إلى إدخال جزئي (إكمال "micro" باستخدام "microchip" و"microscope" و"microsoft" وأي تطابقات مصغرة أخرى). تجربة مستخدم ثانية هي الاقتراحات، أو قائمة قصيرة من المستندات المطابقة (إرجاع عناوين الكتب بمعرف بحيث يمكنك الارتباط بصفحة تفاصيل حول هذا الكتاب). يتم تقييم كل من الإكمال التلقائي والاقتراحات على تطابق في الفهرس. لن تقدم الخدمة استعلامات أو اقتراحات مكتملة تلقائيا لا ترجع أي نتائج.

لتنفيذ هذه التجارب في Azure الذكاء الاصطناعي Search:

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

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

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

إعداد طلب

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

POST /indexes/myxboxgames/docs/autocomplete?search&api-version=2020-06-30
{
  "search": "minecraf",
  "suggesterName": "sg"
}

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

توفر المعلمة "search" الاستعلام الجزئي، حيث يتم تغذية الأحرف بطلب الاستعلام من خلال عنصر تحكم jQuery Autocomplete. في المثال أعلاه، "minecraf" هو رسم توضيحي ثابت لما قد يمر به عنصر التحكم.

لا تفرض واجهات برمجة التطبيقات متطلبات الحد الأدنى للطول على الاستعلام الجزئي؛ يمكن أن يكون أقل من حرف واحد. ومع ذلك، يوفر jQuery Autocomplete الحد الأدنى من الطول. من المعتاد وجود حرفين أو ثلاثة أحرف كحد أدنى.

توجد التطابقات في بداية مصطلح في أي مكان في سلسلة الإدخال. بالنظر إلى "الثعلب البني السريع"، يتطابق كل من الإكمال التلقائي والاقتراحات على الإصدارات الجزئية من "the" أو "quick" أو "brown" أو "fox" ولكن ليس على مصطلحات غير مسبوقة جزئية مثل "rown" أو "ox". علاوة على ذلك، تحدد كل مطابقة نطاق توسعات انتقال البيانات من الخادم. سيتطابق استعلام جزئي عن "br السريع" على "البني السريع" أو "الخبز السريع"، ولكن لا "البني" أو "الخبز" في حد ذاته سيكون مطابقا ما لم يسبقها "سريع".

واجهات برمجة التطبيقات للبحث أثناء الكتابة

اتبع هذه الارتباطات للصفحات المرجعية REST و.NET SDK:

• واجهة برمجة تطبيقات REST للاقتراحات
• واجهة برمجة تطبيقات REST للإكمال التلقائي
• أسلوب SuggestAsync
• أسلوب AutocompleteAsync

هيكلة الاستجابة

الاستجابات للإكمال التلقائي والاقتراحات هي ما قد تتوقعه للنمط: يرجع الإكمال التلقائي قائمة بالمصطلحات، وترجع الاقتراحات المصطلحات بالإضافة إلى معرف المستند بحيث يمكنك إحضار المستند (استخدم واجهة برمجة تطبيقات مستند البحث لإحضار مستند معين لصفحة تفاصيل).

يتم تشكيل الاستجابات بواسطة المعلمات على الطلب:

• بالنسبة إلى الإكمال التلقائي، قم بتعيين autocompleteMode لتحديد ما إذا كان يتم إكمال النص على مصطلح واحد أو اثنين.

• بالنسبة إلى الاقتراحات، قم بتعيين $select لإرجاع الحقول التي تحتوي على قيم فريدة أو مميزة، مثل الأسماء والوصف. تجنب الحقول التي تحتوي على قيم مكررة (مثل فئة أو مدينة).

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

المعلمة‬	الاستخدام
حقول البحث	تقييد الاستعلام إلى حقول معينة.
‎$filter	تطبيق معايير المطابقة على مجموعة النتائج ($filter=Category eq 'ActionAdventure').
$top	قصر النتائج على رقم معين ($top=5).

إضافة رمز تفاعل المستخدم

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

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

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

• يظهر المكون الإضافي XDSoft Autocomplete في مقتطف التعليمات البرمجية للإكمال التلقائي.

• تظهر الاقتراحات في البرنامج التعليمي JavaScript ونموذج التعليمات البرمجية.

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

الاقتراحات

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

إنشاء مربع بحث

بافتراض مكتبة الإكمال التلقائي لواجهة المستخدم jQuery ومشروع MVC في C#، يمكنك تعريف مربع البحث باستخدام JavaScript في ملف Index.cshtml. تضيف المكتبة تفاعل البحث عند الكتابة إلى مربع البحث عن طريق إجراء استدعاءات غير متزامنة إلى وحدة تحكم MVC لاسترداد الاقتراحات.

في Index.cshtml ضمن المجلد \Views\Home، قد يكون سطر لإنشاء مربع بحث كما يلي:

<input class="searchBox" type="text" id="searchbox1" placeholder="search">

هذا المثال هو مربع نص إدخال بسيط مع فئة التصميم، ومعرف للإشارة إليه بواسطة JavaScript، ونص العنصر النائب.

ضمن نفس الملف، قم بتضمين JavaScript الذي يشير إلى مربع البحث. تستدعي الدالة التالية واجهة برمجة التطبيقات المقترحة، التي تطلب المستندات المطابقة المقترحة استنادا إلى إدخالات المصطلحات الجزئية:

$(function () {
    $("#searchbox1").autocomplete({
        source: "/home/suggest?highlights=false&fuzzy=false&",
        minLength: 3,
        position: {
            my: "left top",
            at: "left-23 bottom+10"
        }
    });
});

يخبر source دالة الإكمال التلقائي لواجهة المستخدم jQuery بمكان الحصول على قائمة العناصر المراد إظهارها ضمن مربع البحث. نظرا لأن هذا المشروع هو مشروع MVC، فإنه يستدعي الدالة Suggest في HomeController.cs التي تحتوي على منطق إرجاع اقتراحات الاستعلام. تمرر هذه الدالة أيضا بعض المعلمات للتحكم في التمييزات والمطابقة الغامضة والمصطلح. تضيف واجهة برمجة تطبيقات JavaScript للإكمال التلقائي معلمة المصطلح .

minLength: 3 يضمن إظهار التوصيات فقط عندما يكون هناك ثلاثة أحرف على الأقل في مربع البحث.

تمكين المطابقة الغامضة

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

source: "/home/suggest?highlights=false&fuzzy=true&",

تمكين التمييز

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

source: "/home/suggest?highlights=true&fuzzy=true&",

اقتراح دالة

إذا كنت تستخدم C# وتطبيق MVC، HomeController.cs الملف ضمن دليل Controllers حيث يمكنك إنشاء فئة للنتائج المقترحة. في .NET، تستند الدالة Suggest إلى أسلوب SuggestAsync. لمزيد من المعلومات حول .NET SDK، راجع كيفية استخدام Azure الذكاء الاصطناعي Search من تطبيق .NET.

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

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

public async Task<ActionResult> SuggestAsync(bool highlights, bool fuzzy, string term)
{
    InitSearch();

    var options = new SuggestOptions()
    {
        UseFuzzyMatching = fuzzy,
        Size = 8,
    };

    if (highlights)
    {
        options.HighlightPreTag = "<b>";
        options.HighlightPostTag = "</b>";
    }

    // Only one suggester can be specified per index.
    // The suggester for the Hotels index enables autocomplete/suggestions on the HotelName field only.
    // During indexing, HotelNames are indexed in patterns that support autocomplete and suggested results.
    var suggestResult = await _searchClient.SuggestAsync<Hotel>(term, "sg", options).ConfigureAwait(false);

    // Convert the suggest query results to a list that can be displayed in the client.
    List<string> suggestions = suggestResult.Value.Results.Select(x => x.Text).ToList();

    // Return the list of suggestions.
    return new JsonResult(suggestions);
}

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

الاكمال التلقائي

حتى الآن، تم توسيط رمز البحث UX على الاقتراحات. تعرض كتلة التعليمات البرمجية التالية الإكمال التلقائي، باستخدام دالة الإكمال التلقائي لواجهة مستخدم XDSoft jQuery، وتمرير طلب الإكمال التلقائي ل Azure الذكاء الاصطناعي Search. كما هو الحال مع الاقتراحات، في تطبيق C# ، تنتقل التعليمات البرمجية التي تدعم تفاعل المستخدم في index.cshtml.

$(function () {
    // using modified jQuery Autocomplete plugin v1.2.8 https://xdsoft.net/jqplugins/autocomplete/
    // $.autocomplete -> $.autocompleteInline
    $("#searchbox1").autocompleteInline({
        appendMethod: "replace",
        source: [
            function (text, add) {
                if (!text) {
                    return;
                }

                $.getJSON("/home/autocomplete?term=" + text, function (data) {
                    if (data && data.length > 0) {
                        currentSuggestion2 = data[0];
                        add(data);
                    }
                });
            }
        ]
    });

    // complete on TAB and clear on ESC
    $("#searchbox1").keydown(function (evt) {
        if (evt.keyCode === 9 /* TAB */ && currentSuggestion2) {
            $("#searchbox1").val(currentSuggestion2);
            return false;
        } else if (evt.keyCode === 27 /* ESC */) {
            currentSuggestion2 = "";
            $("#searchbox1").val("");
        }
    });
});

دالة الإكمال التلقائي

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

public async Task<ActionResult> AutoCompleteAsync(string term)
{
    InitSearch();

    // Setup the autocomplete parameters.
    var ap = new AutocompleteOptions()
    {
        Mode = AutocompleteMode.OneTermWithContext,
        Size = 6
    };
    var autocompleteResult = await _searchClient.AutocompleteAsync(term, "sg", ap).ConfigureAwait(false);

    // Convert the autocompleteResult results to a list that can be displayed in the client.
    List<string> autocomplete = autocompleteResult.Value.Results.Select(x => x.Text).ToList();

    return new JsonResult(autocomplete);
}

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

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

يوضح البرنامج التعليمي التالي تجربة البحث أثناء الكتابة.

إضافة بحث إلى موقع ويب (JavaScript)