клиентская библиотека Когнитивный поиск Azure для Python версии 11.4.0

  • Статья

Когнитивный поиск Azure — это облачное решение "поиск как услуга", которое предоставляет разработчикам API и средства для реализации расширенных возможностей поиска при работе с конфиденциальным и разнородным содержимым веб-приложений, а также мобильных и корпоративных приложений.

Служба Когнитивный поиск Azure хорошо подходит для следующих сценариев приложений:

  • Объединение различных типов контента в единый индекс, доступный для поиска. Чтобы заполнить индекс, можно отправить документы JSON, содержащие содержимое, или, если данные уже находятся в Azure, создать индексатор для автоматического извлечения данных.
  • Присоединяйте наборы навыков к индексатору, чтобы создавать содержимое с возможностью поиска из изображений и документов с большим текстом. Набор навыков использует ИИ из Cognitive Services для встроенного распознавания текста, распознавания сущностей, извлечения ключевых фраз, определения языка, перевода текста и анализа тональности. Вы также можете добавить пользовательские навыки для интеграции внешней обработки содержимого во время приема данных.
  • В клиентском приложении для поиска реализуйте логику запросов и взаимодействие с пользователем аналогично коммерческим поисковым системам в Интернете.

Используйте клиентную библиотеку Azure.Search.Documents, чтобы:

  • Отправка запросов для простых и расширенных форм запросов, которые включают нечеткий поиск, поиск с подстановочными знаками, регулярные выражения.
  • Реализуйте отфильтрованные запросы для фасетной навигации, геопространственного поиска или для сужения результатов на основе критериев фильтра.
  • Создание индексов поиска и управление ими.
  • Отправка и обновление документов в индексе поиска.
  • Создание индексаторов и управление ими, извлекающими данные из Azure в индекс.
  • Создавайте наборы навыков и управляйте ими, добавляя обогащение СИ для приема данных.
  • Создание анализаторов для расширенного анализа текста или многоязычного содержимого и управление ими.
  • Оптимизируйте результаты с помощью профилей оценки, чтобы учитывать бизнес-логику или свежесть.

Исходный код | Пакет (PyPI) | Пакет (Conda) | Справочная документация по | APIДокументация по продукту | Образцы

Начало работы

Установка пакета

Установите клиентную библиотеку Когнитивный поиск Azure для Python с помощью pip:

pip install azure-search-documents

Предварительные требования

Чтобы создать новую службу поиска, можно использовать портал Azure, Azure PowerShell или Azure CLI.

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

Дополнительные сведения о доступных вариантах см. в разделе Выбор ценовой категории .

Аутентификация клиента

Для взаимодействия с служба необходимо создать экземпляр соответствующего клиентского класса: SearchClient для поиска индексированных документов, SearchIndexClient управления индексами или SearchIndexerClient для обхода источников данных и загрузки документов поиска в индекс. Чтобы создать экземпляр клиентского объекта, вам потребуется конечная точка и ключ API. Дополнительные сведения о поддерживаемых подходах к проверке подлинности с помощью служба см. в документации.

Получение ключа API

Конечную точку и ключ API можно получить из служба на портале Azure. Инструкции по получении ключа API см. в документации .

Кроме того, можно использовать следующую команду Azure CLI, чтобы получить ключ API из служба :

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

Существует два типа ключей, используемых для доступа к службе поиска: ключи администратора(для чтения и записи) и ключи запросов(только для чтения). Ограничение доступа и операций в клиентских приложениях необходимо для защиты ресурсов поиска в вашем службе. Всегда используйте ключ запроса, а не ключ администратора для любого запроса, исходящего из клиентского приложения.

Примечание. Приведенный выше пример фрагмента Azure CLI извлекает ключ администратора, чтобы было проще приступить к изучению API, но им следует тщательно управлять.

Создание 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 с помощью управления доступом на основе ролей Azure (Azure RBAC) см. в документации.

Прежде чем использовать , или любой DefaultAzureCredentialтип учетных данных из Azure.Identity, сначала необходимо установить пакет Azure.Identity.

Чтобы использовать DefaultAzureCredential с идентификатором и секретом клиента, необходимо задать AZURE_TENANT_IDпеременные среды , AZURE_CLIENT_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 содержит один или несколько индексов, которые обеспечивают постоянное хранение доступных для поиска данных в виде документов JSON. (Если вы еще не знакомы с поиском, можно провести очень приблизительные аналогии между индексами и таблицами базы данных.) Клиентская библиотека Azure.Search.Documents предоставляет операции с этими ресурсами с помощью двух типов клиентов main.

Когнитивный поиск Azure предоставляет две мощные функции: семантический поиск и векторный поиск.

Семантический поиск повышает качество результатов поиска для текстовых запросов. Включив семантический поиск в службе поиска, вы можете повысить релевантность результатов поиска двумя способами:

  • Он применяет вторичное ранжирование к начальному набору результатов, повышая наиболее семантически релевантные результаты к началу.
  • Он извлекает и возвращает субтитры и ответы в ответе, которые могут отображаться на странице поиска, чтобы улучшить работу пользователя.

Дополнительные сведения о семантиковом поиске см. в документации.

Векторный поиск — это метод получения информации, который преодолевает ограничения традиционного поиска на основе ключевое слово. Вместо того, чтобы полагаться исключительно на лексический анализ и сопоставление отдельных терминов запроса, векторный поиск использует модели машинного обучения для захвата контекстного значения слов и фраз. Он представляет документы и запросы в виде векторов в многомерном пространстве, называемом внедрением. Понимая цель запроса, векторный поиск может предоставлять более релевантные результаты, соответствующие требованиям пользователя, даже если точные термины отсутствуют в документе. Кроме того, поиск векторов можно применять к различным типам содержимого, включая изображения и видео, а не только текст.

Чтобы узнать, как индексировать поля векторов и выполнять векторный поиск, ознакомьтесь с примером. Этот пример содержит подробные инструкции по индексации векторных полей и демонстрирует, как выполнять поиск векторов.

Кроме того, более подробные сведения о поиске векторов, включая его основные понятия и использование, см. в документации. В документации содержатся подробные объяснения и рекомендации по использованию возможностей векторного поиска в Когнитивный поиск Azure.

Клиентская Azure.Search.Documents библиотека (версия 1) — это новое предложение для разработчиков Python, которые хотят использовать технологию поиска в своих приложениях. Существует более старая полнофункциончная Microsoft.Azure.Search клиентская библиотека (версия 10) с множеством похожих ИНТЕРФЕЙСов API, поэтому будьте осторожны, чтобы избежать путаницы при изучении интернет-ресурсов.

Примеры

В следующих примерах используется простой набор данных Hotel, который можно импортировать в собственный индекс из портал 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 . Поля можно определить с помощью удобных SimpleFieldмоделей , SearchableFieldили ComplexField . Индексы также могут определять средства подбора, лексические анализаторы и многое другое.

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, Merge, MergeOrUploadи 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"]))

Асинхронные API

Эта библиотека включает полный асинхронный API. Чтобы использовать его, необходимо сначала установить асинхронный транспорт, например 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 вызовет исключения, определенные в Azure Core.

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.

С помощью аргумента-ключевого слова logging_enable можно включить в клиенте ведение журнала на уровне отладки (DEBUG), на котором фиксируются сведения о телах запросов и ответов, а также заголовки без изменений:

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.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

Просмотры

Просмотры