أمثلة على استعلامات البحث "البسيطة" في Azure الذكاء الاصطناعي Search
في Azure الذكاء الاصطناعي Search، يستدعي بناء جملة الاستعلام البسيط محلل الاستعلام الافتراضي للبحث عن النص الكامل. المحلل سريع ويعالج السيناريوهات الشائعة، بما في ذلك البحث الكامل عن النص والبحث المصفى والواجهات والبحث عن البادئة. تستخدم هذه المقالة أمثلة لتوضيح استخدام بناء الجملة البسيط في طلب مستندات البحث (REST API).
إشعار
بناء جملة استعلام بديل هو Full Lucene، وهو يدعم بنيات استعلام أكثر تعقيدا، مثل البحث الغامض وأحرف البدل. لمزيد من المعلومات والأمثلة، راجع استخدام بناء جملة Lucene الكامل.
فهرس عينة الفنادق
تستند الاستعلامات التالية إلى فهرس hotels-sample، والذي يمكنك إنشاؤه باتباع الإرشادات الواردة في هذا التشغيل السريع.
يتم توضيح أمثلة الاستعلامات باستخدام REST API وطلبات POST. يمكنك لصقها وتشغيلها في عميل REST. أو استخدم طريقة عرض JSON لمستكشف البحث في مدخل Microsoft Azure. في طريقة عرض JSON، يمكنك اللصق في أمثلة الاستعلام الموضحة هنا في هذه المقالة.
يجب أن تحتوي رؤوس الطلبات على القيم التالية:
| مفتاح | القيمة |
|---|---|
| Content-Type | تطبيق/json |
| مفتاح واجهة برمجة التطبيقات | <your-search-service-api-key>، إما الاستعلام أو مفتاح المسؤول |
يجب أن تتضمن معلمات URI نقطة نهاية خدمة البحث الخاصة بك مع اسم الفهرس ومجموعات المستندات وأمر البحث وإصدار واجهة برمجة التطبيقات، على غرار المثال التالي:
https://{{service-name}}.search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2023-11-01
يجب تشكيل نص الطلب ك JSON صالح:
{
"search": "*",
"queryType": "simple",
"select": "HotelId, HotelName, Category, Tags, Description",
"count": true
}
"البحث" الذي تم تعيينه إلى
*هو استعلام غير محدد، مكافئ للبحث الفارغ أو الفارغ. إنه ليس مفيدا بشكل خاص، ولكنه أبسط بحث يمكنك القيام به، ويعرض جميع الحقول القابلة للاسترداد في الفهرس، مع جميع القيم."queryType" الذي تم تعيينه إلى "بسيط" هو الافتراضي ويمكن حذفه، ولكن يتم تضمينه لتعزيز أن أمثلة الاستعلام في هذه المقالة يتم التعبير عنها في بناء الجملة البسيط.
يتم استخدام "تحديد" المعين إلى قائمة الحقول المحددة بفاصلة لتكوين نتائج البحث، بما في ذلك الحقول المفيدة فقط في سياق نتائج البحث.
يقوم "count" بإرجاع عدد المستندات المطابقة لمعايير البحث. في سلسلة بحث فارغة، يكون العدد هو جميع المستندات في الفهرس (50 في فهرس عينة الفنادق).
مثال 1: البحث الكامل عن النص
يمكن أن يكون البحث الكامل عن النص أي عدد من المصطلحات المستقلة أو العبارات المحاطة باقتباس، مع عوامل التشغيل المنطقية أو بدونها.
POST /indexes/hotel-samples-index/docs/search?api-version=2023-11-01
{
"search": "pool spa +airport",
"searchMode": "any",
"queryType": "simple",
"select": "HotelId, HotelName, Category, Description",
"count": true
}
تميل عملية البحث عن الكلمات الأساسية التي تتكون من مصطلحات أو عبارات مهمة إلى العمل على أفضل نحو. تخضع حقول السلسلة لتحليل النص أثناء الفهرسة والاستعلام، مع إسقاط كلمات غير أساسية مثل "the" و"and" و"it". لمعرفة كيفية رمز سلسلة استعلام في الفهرس، مرر السلسلة في استدعاء تحليل النص إلى الفهرس.
تتحكم المعلمة "searchMode" في الدقة والاستدعاء. إذا كنت تريد المزيد من الاستدعاء، فاستخدم القيمة الافتراضية "any"، والتي ترجع نتيجة إذا تمت مطابقة أي جزء من سلسلة الاستعلام. إذا كنت تفضل الدقة، حيث يجب مطابقة جميع أجزاء السلسلة، فقم بتغيير searchMode إلى "الكل". جرب الاستعلام أعلاه كلتا الطريقتين لمعرفة كيفية تغيير searchMode للنتيجة.
يجب أن تبدو الاستجابة لاستعلام "pool spa +airport" مشابهة للمثال التالي، مقتسمة للإيجاز.
"@odata.count": 6,
"value": [
{
"@search.score": 7.3617697,
"HotelId": "21",
"HotelName": "Nova Hotel & Spa",
"Description": "1 Mile from the airport. Free WiFi, Outdoor Pool, Complimentary Airport Shuttle, 6 miles from the beach & 10 miles from downtown.",
"Category": "Resort and Spa",
"Tags": [
"pool",
"continental breakfast",
"free parking"
]
},
{
"@search.score": 2.5560288,
"HotelId": "25",
"HotelName": "Scottish Inn",
"Description": "Newly Redesigned Rooms & airport shuttle. Minutes from the airport, enjoy lakeside amenities, a resort-style pool & stylish new guestrooms with Internet TVs.",
"Category": "Luxury",
"Tags": [
"24-hour front desk service",
"continental breakfast",
"free wifi"
]
},
{
"@search.score": 2.2988036,
"HotelId": "35",
"HotelName": "Suites At Bellevue Square",
"Description": "Luxury at the mall. Located across the street from the Light Rail to downtown. Free shuttle to the mall and airport.",
"Category": "Resort and Spa",
"Tags": [
"continental breakfast",
"air conditioning",
"24-hour front desk service"
]
}
]
لاحظ درجة البحث في الاستجابة. هذه هي درجة الصلة للمباراة. بشكل افتراضي، تقوم خدمة البحث بإرجاع أفضل 50 تطابقا استنادا إلى هذه النتيجة.
تحدث الدرجات المنتظمة ل "1.0" عندما لا تكون هناك رتبة، إما لأن البحث لم يكن بحثا كاملا عن النص، أو لأنه لم يتم توفير معايير. على سبيل المثال، في بحث فارغ (search=*)، تعود الصفوف بترتيب عشوائي. عند تضمين معايير فعلية، سترى أن درجات البحث تتطور إلى قيم ذات معنى.
مثال 2: البحث حسب المعرف
عند إرجاع نتائج البحث في استعلام، فإن الخطوة المنطقية التالية هي توفير صفحة تفاصيل تتضمن المزيد من الحقول من المستند. يوضح لك هذا المثال كيفية إرجاع مستند واحد باستخدام "مستند البحث" عن طريق تمرير معرف المستند.
GET /indexes/hotels-sample-index/docs/41?api-version=2023-11-01
تحتوي جميع المستندات على معرف فريد. إذا كنت تستخدم المدخل، فحدد الفهرس من علامة التبويب Indexes ثم انظر إلى تعريفات الحقول لتحديد الحقل الذي هو المفتاح. باستخدام REST، يقوم استدعاء Get Index بإرجاع تعريف الفهرس في نص الاستجابة.
تتكون الاستجابة للاستعلام أعلاه من المستند الذي يكون مفتاحه 41. يمكن إرجاع أي حقل تم وضع علامة "استرداد" عليه في تعريف الفهرس في نتائج البحث وعرضه في تطبيقك.
{
"HotelId": "41",
"HotelName": "Ocean Air Motel",
"Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Various shops and art entertainment are on the boardwalk, just steps away.",
"Description_fr": "L'hôtel front de mer surplombant la plage dispose de chambres avec balcon privé et 2 piscines intérieures et extérieures. Divers commerces et animations artistiques sont sur la promenade, à quelques pas.",
"Category": "Budget",
"Tags": [
"pool",
"air conditioning",
"bar"
],
"ParkingIncluded": true,
"LastRenovationDate": "1951-05-10T00:00:00Z",
"Rating": 3.5,
"Location": {
"type": "Point",
"coordinates": [
-157.846817,
21.295841
],
"crs": {
"type": "name",
"properties": {
"name": "EPSG:4326"
}
}
},
"Address": {
"StreetAddress": "1450 Ala Moana Blvd 2238 Ala Moana Ctr",
"City": "Honolulu",
"StateProvince": "HI",
"PostalCode": "96814",
"Country": "USA"
}
}
مثال 3: تصفية النص
بناء جملة عامل التصفية هو تعبير OData يمكنك استخدامه بمفرده أو مع search. يتم تطبيقها معا filter أولا على الفهرس بأكمله، ثم يتم إجراء البحث على نتائج عامل التصفية. لذلك يمكن أن تكون عوامل التصفية تقنية مفيدة لتحسين أداء الاستعلام لأنها تقلل من مجموعة المستندات التي يحتاج استعلام البحث إلى معالجتها.
يمكن تعريف عوامل التصفية على أي حقل تم وضع علامة عليه ك filterable في تعريف الفهرس. بالنسبة لفهرس عينات الفنادق، تتضمن الحقول القابلة للتصفية الفئة والعلامات وSubsincluded والتصنيف ومعظم حقول العنوان.
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
"search": "art tours",
"queryType": "simple",
"filter": "Category eq 'Resort and Spa'",
"searchFields": "HotelName,Description,Category",
"select": "HotelId,HotelName,Description,Category",
"count": true
}
يتم تحديد نطاق الاستجابة للاستعلام أعلاه فقط لتلك الفنادق المصنفة على أنها "تقرير وسبا"، والتي تتضمن مصطلحي "الفن" أو "الجولات". في هذه الحالة، هناك تطابق واحد فقط.
{
"@search.score": 2.8576312,
"HotelId": "31",
"HotelName": "Santa Fe Stay",
"Description": "Nestled on six beautifully landscaped acres, located 2 blocks from the Plaza. Unwind at the spa and indulge in art tours on site.",
"Category": "Resort and Spa"
}
مثال 4: دالات التصفية
يمكن أن تتضمن تعبيرات التصفية دالتي "search.ismatch" و"search.ismatchscoring"، مما يسمح لك بإنشاء استعلام بحث داخل عامل التصفية. يستخدم تعبير عامل التصفية هذا حرف بدل مجانا لتحديد وسائل الراحة بما في ذلك شبكة wifi المجانية ومواقف السيارات المجانية وما إلى ذلك.
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
"search": "",
"filter": "search.ismatch('free*', 'Tags', 'full', 'any')",
"select": "HotelId, HotelName, Category, Description",
"count": true
}
الاستجابة للاستعلام أعلاه تتطابق مع 19 فندقا توفر وسائل الراحة المجانية. لاحظ أن درجة البحث هي "1.0" موحدة في جميع النتائج. وذلك لأن تعبير البحث فارغ أو خال، مما يؤدي إلى تطابق عامل تصفية حرفي، ولكن لا يوجد بحث نصي كامل. يتم إرجاع درجات الصلة فقط في البحث عن النص الكامل. إذا كنت تستخدم عوامل تصفية بدون search، فتأكد من أن لديك حقولا كافية قابلة للفرز بحيث يمكنك التحكم في ترتيب البحث.
"@odata.count": 19,
"value": [
{
"@search.score": 1.0,
"HotelId": "31",
"HotelName": "Santa Fe Stay",
"Tags": [
"view",
"restaurant",
"free parking"
]
},
{
"@search.score": 1.0,
"HotelId": "27",
"HotelName": "Super Deluxe Inn & Suites",
"Tags": [
"bar",
"free wifi"
]
},
{
"@search.score": 1.0,
"HotelId": "39",
"HotelName": "Whitefish Lodge & Suites",
"Tags": [
"continental breakfast",
"free parking",
"free wifi"
]
},
{
"@search.score": 1.0,
"HotelId": "11",
"HotelName": "Regal Orb Resort & Spa",
"Tags": [
"free wifi",
"restaurant",
"24-hour front desk service"
]
},
مثال 5: عوامل تصفية النطاق
يتم دعم تصفية النطاق من خلال تعبيرات عوامل التصفية لأي نوع بيانات. توضح الأمثلة التالية النطاقات الرقمية والسلسلة. تعد أنواع البيانات مهمة في عوامل تصفية النطاق وتعمل على أفضل نحو عندما تكون البيانات الرقمية في حقول رقمية، وبيانات السلسلة في حقول السلسلة. البيانات الرقمية في حقول السلسلة غير مناسبة للنطاقات لأن السلاسل الرقمية غير قابلة للمقارنة.
الاستعلام التالي هو نطاق رقمي. في hotels-sample-index، الحقل الرقمي الوحيد القابل للتصفية هو Rating.
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
"search": "*",
"filter": "Rating ge 2 and Rating lt 4",
"select": "HotelId, HotelName, Rating",
"orderby": "Rating desc",
"count": true
}
يجب أن تبدو الاستجابة لهذا الاستعلام مشابهة للمثال التالي، تم اقتطاعها للإيجاز.
"@odata.count": 27,
"value": [
{
"@search.score": 1.0,
"HotelId": "22",
"HotelName": "Stone Lion Inn",
"Rating": 3.9
},
{
"@search.score": 1.0,
"HotelId": "25",
"HotelName": "Scottish Inn",
"Rating": 3.8
},
{
"@search.score": 1.0,
"HotelId": "2",
"HotelName": "Twin Dome Motel",
"Rating": 3.6
}
...
الاستعلام التالي هو عامل تصفية نطاق عبر حقل سلسلة (Address/StateProvince):
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
"search": "*",
"filter": "Address/StateProvince ge 'A*' and Address/StateProvince lt 'D*'",
"select": "HotelId, HotelName, Address/StateProvince",
"count": true
}
يجب أن تبدو الاستجابة لهذا الاستعلام مشابهة للمثال أدناه، مقتسمة للإيجاز. في هذا المثال، لا يمكن الفرز حسب StateProvince لأن الحقل لا ينسب على أنه "قابل للفرز" في تعريف الفهرس.
"@odata.count": 9,
"value": [
{
"@search.score": 1.0,
"HotelId": "9",
"HotelName": "Smile Hotel",
"Address": {
"StateProvince": "CA "
}
},
{
"@search.score": 1.0,
"HotelId": "39",
"HotelName": "Whitefish Lodge & Suites",
"Address": {
"StateProvince": "CO"
}
},
{
"@search.score": 1.0,
"HotelId": "7",
"HotelName": "Countryside Resort",
"Address": {
"StateProvince": "CA "
}
},
...
مثال 6: البحث الجيوفضائي
يتضمن فهرس عينة الفنادق حقل الموقع مع إحداثيات خطوط الطول والعرض. يستخدم هذا المثال الدالة geo.distance التي تقوم بالتصفية على المستندات ضمن محيط نقطة البداية، إلى مسافة عشوائية (بالكيلومترات) التي توفرها. يمكنك ضبط القيمة الأخيرة في الاستعلام (10) لتقليل أو تكبير مساحة سطح الاستعلام.
POST /indexes/v/docs/search?api-version=2023-11-01
{
"search": "*",
"filter": "geo.distance(Location, geography'POINT(-122.335114 47.612839)') le 10",
"select": "HotelId, HotelName, Address/City, Address/StateProvince",
"count": true
}
ترجع الاستجابة لهذا الاستعلام جميع الفنادق على مسافة 10 كيلومترات من الإحداثيات المقدمة:
{
"@odata.count": 3,
"value": [
{
"@search.score": 1.0,
"HotelId": "45",
"HotelName": "Arcadia Resort & Restaurant",
"Address": {
"City": "Seattle",
"StateProvince": "WA"
}
},
{
"@search.score": 1.0,
"HotelId": "24",
"HotelName": "Gacc Capital",
"Address": {
"City": "Seattle",
"StateProvince": "WA"
}
},
{
"@search.score": 1.0,
"HotelId": "16",
"HotelName": "Double Sanctuary Resort",
"Address": {
"City": "Seattle",
"StateProvince": "WA"
}
}
]
}
مثال 7: القيم المنطقية مع searchMode
يدعم بناء الجملة البسيط عوامل التشغيل المنطقية في شكل أحرف (+, -, |) لدعم منطق الاستعلام AND وOR وNOT. يعمل البحث المنطقي كما قد تتوقع، مع بعض الاستثناءات الجديرة بالملاحظة.
في الأمثلة السابقة، searchMode تم تقديم المعلمة كآلية للتأثير على الدقة والاستدعاء، مع "searchMode": "any" تفضيل الاستدعاء (يعتبر المستند الذي يفي بأي من المعايير مطابقة)، و"searchMode=all" يفضل الدقة (يجب مطابقة جميع المعايير في مستند).
في سياق البحث المنطقي، يمكن أن يكون الإعداد الافتراضي "searchMode": "any" مربكا إذا كنت تقوم بتكديس استعلام مع عوامل تشغيل متعددة والحصول على نتائج أوسع بدلا من نتائج أضيق. هذا صحيح بشكل خاص مع NOT، حيث تتضمن النتائج جميع المستندات "التي لا تحتوي" على مصطلح أو عبارة معينة.
يوفر المثال التالي رسما توضيحيا. تشغيل الاستعلام التالي مع searchMode (أي)، يتم إرجاع 42 مستندا: تلك التي تحتوي على مصطلح "مطعم"، بالإضافة إلى جميع المستندات التي لا تحتوي على عبارة "تكييف الهواء".
لاحظ أنه لا توجد مسافة بين عامل التشغيل المنطقي (-) وعبارة "تكييف الهواء".
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
"search": "restaurant -\"air conditioning\"",
"searchMode": "any",
"searchFields": "Tags",
"select": "HotelId, HotelName, Tags",
"count": true
}
يؤدي التغيير إلى "searchMode": "all" فرض تأثير تراكمي على المعايير وإرجاع مجموعة نتائج أصغر (7 تطابقات) تتكون من مستندات تحتوي على مصطلح "مطعم"، مطروحا منها تلك التي تحتوي على عبارة "تكييف الهواء".
ستبدو الاستجابة لهذا الاستعلام الآن مشابهة للمثال التالي، تم اقتطاعها للإيجاز.
"@odata.count": 7,
"value": [
{
"@search.score": 2.5460577,
"HotelId": "11",
"HotelName": "Regal Orb Resort & Spa",
"Tags": [
"free wifi",
"restaurant",
"24-hour front desk service"
]
},
{
"@search.score": 2.166792,
"HotelId": "10",
"HotelName": "Countryside Hotel",
"Tags": [
"24-hour front desk service",
"coffee in lobby",
"restaurant"
]
},
...
مثال 8: نتائج الترحيل
في الأمثلة السابقة، تعرفت على المعلمات التي تؤثر على تكوين نتائج البحث، بما في ذلك select التي تحدد الحقول الموجودة في نتيجة، وأوامر الفرز، وكيفية تضمين عدد جميع التطابقات. هذا المثال هو استمرار لتكوين نتيجة البحث في شكل معلمات ترحيل الصفحات التي تسمح لك بتجميع عدد النتائج التي تظهر في أي صفحة معينة.
بشكل افتراضي، ترجع خدمة البحث أفضل 50 تطابقا. للتحكم في عدد التطابقات في كل صفحة، استخدم top لتحديد حجم الدفعة، ثم استخدم skip لالتقاط الدفعات اللاحقة.
يستخدم المثال التالي ترتيب تصفية وفرز في حقل التصنيف (التصنيف قابل للتصفية والفرز على حد سواء) لأنه من الأسهل رؤية تأثيرات الترحيل على النتائج التي تم فرزها. في استعلام بحث كامل عادي، يتم ترتيب أفضل التطابقات وصفحة حسب @search.score.
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
"search": "*",
"filter": "Rating gt 4",
"select": "HotelName, Rating",
"orderby": "Rating desc",
"top": "5",
"count": true
}
يبحث الاستعلام عن 21 مستندا متطابقا، ولكن لأنك حددت top، ترجع الاستجابة أفضل خمس تطابقات فقط، مع تصنيفات تبدأ من 4.9، وتنتهي عند 4.7 ب "سيدة البحيرة B وB".
للحصول على 5 التالية، تخطي الدفعة الأولى:
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
"search": "*",
"filter": "Rating gt 4",
"select": "HotelName, Rating",
"orderby": "Rating desc",
"top": "5",
"skip": "5",
"count": true
}
تتخطى الاستجابة للدفعة الثانية أول خمس مباريات، مع إرجاع الخمسة التالية، بدءا من "Pull'r Inn Motel". لمتابعة المزيد من الدفعات، يمكنك الاحتفاظ top ب 5، ثم زيادة skip بمقدار 5 على كل طلب جديد (skip=5، skip=10، skip=15، وما إلى ذلك).
"value": [
{
"@search.score": 1.0,
"HotelName": "Pull'r Inn Motel",
"Rating": 4.7
},
{
"@search.score": 1.0,
"HotelName": "Sublime Cliff Hotel",
"Rating": 4.6
},
{
"@search.score": 1.0,
"HotelName": "Antiquity Hotel",
"Rating": 4.5
},
{
"@search.score": 1.0,
"HotelName": "Nordick's Motel",
"Rating": 4.5
},
{
"@search.score": 1.0,
"HotelName": "Winter Panorama Resort",
"Rating": 4.5
}
]
الخطوات التالية
الآن بعد أن أصبح لديك بعض الممارسات باستخدام بناء جملة الاستعلام الأساسي، حاول تحديد الاستعلامات في التعليمات البرمجية. يغطي الارتباط التالي كيفية إعداد استعلامات البحث باستخدام Azure SDKs.
يمكن العثور على مزيد من مرجع بناء الجملة وبنية الاستعلام والأمثلة في الارتباطات التالية: