مكتبة عميل Azure Cognitive Search ل Python - الإصدار 11.4.0

  • مقالة

Azure Cognitive Search هو حل سحابي للبحث كخدمة يمنح المطورين واجهات برمجة التطبيقات والأدوات لإضافة تجربة بحث غنية عبر المحتوى الخاص وغير المتجانس في تطبيقات الويب والجوال والمؤسسات.

يعد Azure Cognitive خدمة البحث مناسبا تماما لسيناريوهات التطبيق التالية:

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

استخدم مكتبة عميل Azure.Search.Documents من أجل:

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

التعليمات البرمجية | المصدرالحزمة (PyPI) | حزمة (Conda) | الوثائق | المرجعية لواجهة برمجة التطبيقاتوثائق | المنتجعينات

الشروع في العمل

تثبيت الحِزَمة

قم بتثبيت مكتبة عميل Azure Cognitive Search ل Python باستخدام pip:

pip install azure-search-documents

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

لإنشاء خدمة بحث جديدة، يمكنك استخدام مدخل Microsoft Azure أو Azure PowerShell أو Azure CLI.

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

راجع اختيار مستوى تسعير لمزيد من المعلومات حول الخيارات المتاحة.

مصادقة العميل

للتفاعل مع خدمة البحث، ستحتاج إلى إنشاء مثيل لفئة العميل المناسبة: SearchClient للبحث في المستندات المفهرسة أو SearchIndexClient لإدارة الفهارس أو SearchIndexerClient لتتبع ارتباطات مصادر البيانات وتحميل مستندات البحث في فهرس. لإنشاء مثيل لكائن عميل، ستحتاج إلى نقطة نهايةومفتاح API. يمكنك الرجوع إلى الوثائق لمزيد من المعلومات حول نهج المصادقة المدعومة مع خدمة البحث.

الحصول على مفتاح واجهة برمجة التطبيقات

يمكنك الحصول على نقطة النهايةومفتاح API من خدمة البحث في مدخل Microsoft Azure. يرجى الرجوع إلى الوثائق للحصول على إرشادات حول كيفية الحصول على مفتاح API.

بدلا من ذلك، يمكنك استخدام أمر Azure CLI التالي لاسترداد مفتاح API من خدمة البحث:

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

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

ملاحظة: يسترد مثال قصاصة Azure CLI أعلاه مفتاح مسؤول بحيث يكون من الأسهل البدء في استكشاف واجهات برمجة التطبيقات، ولكن يجب إدارتها بعناية.

إنشاء SearchClient

لإنشاء مثيل SearchClient، ستحتاج إلى نقطة النهايةومفتاح APIواسم الفهرس:

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

service_endpoint = os.environ["AZURE_SEARCH_SERVICE_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
key = os.environ["AZURE_SEARCH_API_KEY"]

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

إنشاء عميل باستخدام مصادقة Azure Active Directory

يمكنك أيضا إنشاء SearchClientأو SearchIndexClientأو SearchIndexerClient استخدام مصادقة Azure Active Directory (AAD). يجب تعيين دور "قارئ بيانات فهرس البحث" للمستخدم أو كيان الخدمة. باستخدام DefaultAzureCredential ، يمكنك مصادقة خدمة باستخدام الهوية المدارة أو كيان الخدمة، والمصادقة كمطور يعمل على تطبيق، والمزيد دون تغيير التعليمات البرمجية. يرجى الرجوع إلى الوثائق للحصول على إرشادات حول كيفية الاتصال ب Azure Cognitive Search باستخدام التحكم في الوصول المستند إلى دور Azure (Azure RBAC).

قبل أن تتمكن من DefaultAzureCredentialاستخدام ، أو أي نوع بيانات اعتماد من Azure.Identity، ستحتاج أولا إلى تثبيت حزمة Azure.Identity.

للاستخدام DefaultAzureCredential مع معرف العميل والبيانات السرية، ستحتاج إلى تعيين AZURE_CLIENT_IDAZURE_TENANT_IDمتغيرات البيئة و وAZURE_CLIENT_SECRET؛ بدلا من ذلك، يمكنك تمرير هذه القيم إلى ClientSecretCredential أيضا في Azure.Identity.

تأكد من استخدام مساحة DefaultAzureCredential الاسم المناسبة ل في أعلى الملف المصدر:

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = os.getenv("AZURE_SEARCH_SERVICE_ENDPOINT")
index_name = os.getenv("AZURE_SEARCH_INDEX_NAME")
credential = DefaultAzureCredential()

search_client = SearchClient(service_endpoint, index_name, credential)

المفاهيم الرئيسية

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

يوفر Azure Cognitive Search ميزتين قويتين: البحث الدلالي والبحث المتجه.

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

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

لمعرفة المزيد حول البحث الدلالي، يمكنك الرجوع إلى الوثائق.

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

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

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

Azure.Search.Documents مكتبة العميل (v1) هي عرض جديد تماما لمطوري Python الذين يرغبون في استخدام تقنية البحث في تطبيقاتهم. هناك مكتبة عميل قديمة ومميزة Microsoft.Azure.Search بالكامل (v10) مع العديد من واجهات برمجة التطبيقات المتشابهة المظهر، لذا يرجى توخي الحذر لتجنب الارتباك عند استكشاف الموارد عبر الإنترنت.

أمثلة

تستخدم جميع الأمثلة التالية مجموعة بيانات فندق بسيطة يمكنك استيرادها إلى الفهرس الخاص بك من مدخل Microsoft Azure. هذه ليست سوى عدد قليل من الأساسيات - يرجى الاطلاع على عيناتنا لأكثر من ذلك بكثير.

الاستعلام

لنبدأ باستيراد مساحات الأسماء الخاصة بنا.

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

سنقوم بعد ذلك بإنشاء SearchClient للوصول إلى فهرس البحث في الفنادق.

index_name = "hotels"
# Get the service endpoint and API key from the environment
endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]

# Create a client
credential = AzureKeyCredential(key)
client = SearchClient(endpoint=endpoint,
                      index_name=index_name,
                      credential=credential)

دعونا نبحث عن فندق "فاخر".

results = client.search(search_text="luxury")

for result in results:
    print("{}: {})".format(result["hotelId"], result["hotelName"]))

إنشاء فهرس

يمكنك استخدام SearchIndexClient لإنشاء فهرس بحث. يمكن تعريف الحقول باستخدام نماذج أو أو أو ComplexField ملائمة.SimpleFieldSearchableField يمكن للفهرس أيضا تحديد المقترحات والمحللات المعجمية والمزيد.

client = SearchIndexClient(service_endpoint, AzureKeyCredential(key))
name = "hotels"
fields = [
    SimpleField(name="hotelId", type=SearchFieldDataType.String, key=True),
    SimpleField(name="baseRate", type=SearchFieldDataType.Double),
    SearchableField(name="description", type=SearchFieldDataType.String, collection=True),
    ComplexField(
        name="address",
        fields=[
            SimpleField(name="streetAddress", type=SearchFieldDataType.String),
            SimpleField(name="city", type=SearchFieldDataType.String),
        ],
        collection=True,
    ),
]
cors_options = CorsOptions(allowed_origins=["*"], max_age_in_seconds=60)
scoring_profiles: List[ScoringProfile] = []
index = SearchIndex(name=name, fields=fields, scoring_profiles=scoring_profiles, cors_options=cors_options)

result = client.create_index(index)

إضافة مستندات إلى الفهرس

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

DOCUMENT = {
    "category": "Hotel",
    "hotelId": "1000",
    "rating": 4.0,
    "rooms": [],
    "hotelName": "Azure Inn",
}

result = search_client.upload_documents(documents=[DOCUMENT])

print("Upload of new document succeeded: {}".format(result[0].succeeded))

المصادقة في سحابة وطنية

للمصادقة في سحابة وطنية، ستحتاج إلى إجراء الإضافات التالية إلى تكوين العميل الخاص بك:

  • AuthorityHost تعيين في خيارات بيانات الاعتماد أو عبر AZURE_AUTHORITY_HOST متغير البيئة
  • تعيين في audienceSearchClientأو SearchIndexClientأو SearchIndexerClient
# Create a SearchClient that will authenticate through AAD in the China national cloud.
import os
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts
from azure.search.documents import SearchClient

index_name = "hotels"
endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA)

search_client = SearchClient(endpoint, index_name, credential=credential, audience="https://search.azure.cn")

استرداد مستند معين من الفهرس

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

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

result = search_client.get_document(key="23")

print("Details for hotel '23' are:")
print("        Name: {}".format(result["hotelName"]))
print("      Rating: {}".format(result["rating"]))
print("    Category: {}".format(result["category"]))

APIs غير المتزامنة

تتضمن هذه المكتبة واجهة برمجة تطبيقات غير متزامنة كاملة. لاستخدامه، يجب أولا تثبيت نقل غير متزامن، مثل aiohttp. راجع وثائق azure-core لمزيد من المعلومات.

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.aio import SearchClient

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

async with search_client:
    results = await search_client.search(search_text="spa")

    print("Hotels containing 'spa' in the name (or other fields):")
    async for result in results:
        print("    Name: {} (rating {})".format(result["hotelName"], result["rating"]))

استكشاف الأخطاء وإصلاحها

عام

سيقوم عميل Azure Cognitive Search برفع الاستثناءات المحددة في Azure Core.

تسجيل الدخول

تستخدم هذه المكتبة مكتبة التسجيل القياسية للتسجيل. يتم تسجيل المعلومات الأساسية حول جلسات HTTP (عناوين URL والعناوين وما إلى ذلك) على مستوى INFO.

يمكن تمكين تسجيل مستوى DEBUG مفصلة بما في ذلك الهيئات طلب /استجابة ورؤوس غير منقحة على عميل مع logging_enable وسيطة الكلمة الأساسية:

import sys
import logging
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = SearchClient("<service endpoint>", "<index_name>", AzureKeyCredential("<api key>"), logging_enable=True)

وبالمثل، logging_enable يمكن تمكين تسجيل مفصل لعملية واحدة، حتى عندما لا يتم تمكين للعميل:

result =  client.search(search_text="spa", logging_enable=True)

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

المساهمة

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

هذا المشروع يرحب بالمساهمات والاقتراحات. معظم المساهمات تتطلب منك الموافقة على اتفاقية ترخيص المساهم (CLA) التي تعلن أن لديك الحق في منحنا حق استخدام مساهمتك. للحصول على التفاصيل، تفضل بزيارة cla.microsoft.com.

اعتمد هذا المشروع مدونة السلوك من المصادر المفتوحة من Microsoft. لمزيد من المعلومات، راجع الأسئلة المتداولة حول قواعد السلوك أو الاتصال opencode@microsoft.com بأي أسئلة أو تعليقات إضافية.

الانطباعات

مرات الظهور