biblioteca cliente de Azure Cognitive Search para Python: versión 11.3.0

Azure Cognitive Search es una solución en la nube de búsqueda como servicio que proporciona a los desarrolladores las API y las herramientas necesarias para agregar una completa experiencia de búsqueda de datos a través de contenido privado y heterogéneo en aplicaciones web, móviles y empresariales.

El servicio Azure Cognitive Search es adecuado para los siguientes escenarios de aplicación:

  • Consolide diversos tipos de contenido en un único índice en el que se pueden realizar búsquedas. Para rellenar un índice, puede insertar documentos JSON que contengan el contenido o, si los datos ya están en Azure, cree un indexador para extraer datos automáticamente.
  • Adjunte conjuntos de aptitudes a un indexador para crear contenido que se pueda buscar a partir de imágenes y documentos de texto grandes. Un conjunto de aptitudes aprovecha la inteligencia artificial de Cognitive Services para OCR integrado, reconocimiento de entidades, extracción de frases clave, detección de idioma, traducción de texto y análisis de opiniones. También puede agregar aptitudes personalizadas para integrar el procesamiento externo del contenido durante la ingesta de datos.
  • En una aplicación cliente de búsqueda, implemente la lógica de consulta y las experiencias de usuario similares a los motores de búsqueda web comerciales.

Use la biblioteca cliente Azure.Search.Documents para:

  • Envíe consultas para formularios de consulta simples y avanzados que incluyen búsqueda aproximada, búsqueda con caracteres comodín, expresiones regulares.
  • Implemente consultas filtradas para la navegación por facetas, la búsqueda geoespacial o para restringir los resultados en función de los criterios de filtro.
  • Cree y administre índices de búsqueda.
  • Cargue y actualice documentos en el índice de búsqueda.
  • Cree y administre indizadores que extraen datos de Azure en un índice.
  • Cree y administre conjuntos de aptitudes que agregan enriquecimiento con inteligencia artificial a la ingesta de datos.
  • Cree y administre analizadores para el análisis de texto avanzado o el contenido multilingüe.
  • Optimice los resultados mediante perfiles de puntuación para factorizar la lógica de negocios o la actualización.

Código | fuente Paquete (PyPI) | Documentación | de referencia de APIDocumentación | del producto Muestras

Declinación de responsabilidades

Los paquetes de Python del SDK de Azure para Python 2.7 finalizaron el 01 de enero de 2022. Para más información y preguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691.

Introducción

Instalar el paquete

Instale la biblioteca cliente de Azure Cognitive Search para Python con pip:

pip install azure-search-documents

Requisitos previos

Para crear un nuevo servicio de búsqueda, puede usar el Azure Portal, Azure PowerShell o la CLI de Azure.

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

Consulte Elección de un plan de tarifa para obtener más información sobre las opciones disponibles.

Autenticar el cliente

Todas las solicitudes que se realizan a un servicio de búsqueda necesitan una clave de API generada de forma específica para el servicio. La clave de API es el único mecanismo para autenticar el acceso al punto de conexión del servicio de búsqueda. Puede obtener la clave de API de la Azure Portal o a través de la CLI de Azure:

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

Hay dos tipos de claves que se usan para acceder al servicio de búsqueda: admin(read-write) y query(read-only). Restringir el acceso y las operaciones en las aplicaciones cliente es esencial para proteger los activos de búsqueda en el servicio. Use siempre una clave de consulta en lugar de una clave de administración para cualquier consulta originada desde una aplicación cliente.

Nota: El fragmento de código de la CLI de Azure de ejemplo anterior recupera una clave de administrador para que sea más fácil empezar a explorar las API, pero debe administrarse cuidadosamente.

Podemos usar la clave de API para crear un nuevo SearchClient.

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

index_name = "nycjobs"
# 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)

Conceptos clave

Un servicio Azure Cognitive Search contiene uno o varios índices que proporcionan almacenamiento persistente de datos que se pueden buscar en forma de documentos JSON. (Si no está familiarizado con la búsqueda, puede hacer una analogía muy aproximada entre índices y tablas de base de datos). La biblioteca cliente Azure.Search.Documents expone operaciones en estos recursos a través de dos tipos de cliente principales.

La Azure.Search.Documents biblioteca cliente (v1) es una nueva oferta para desarrolladores de Python que quieren usar la tecnología de búsqueda en sus aplicaciones. Hay una biblioteca cliente antigua y completa Microsoft.Azure.Search (v10) con muchas API similares, por lo que debe tener cuidado de evitar confusiones al explorar recursos en línea.

Ejemplos

En los ejemplos siguientes se usa un conjunto de datos hotel sencillo que se puede importar en su propio índice desde el Azure Portal. Estos son solo algunos de los conceptos básicos: consulte nuestros ejemplos para mucho más.

Consultas

Empecemos importando nuestros espacios de nombres.

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

A continuación, crearemos un SearchClient para acceder al índice de búsqueda de hoteles.

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)

Busquemos un hotel de lujo.

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

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

Creación de un índice

Puede usar SearchIndexClient para crear un índice de búsqueda. Los campos se pueden definir mediante modelos cómodos SimpleField, SearchableFieldo ComplexField . Los índices también pueden definir proveedores de sugerencias, analizadores léxicos, etc.

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    ComplexField,
    CorsOptions,
    SearchIndex,
    ScoringProfile,
    SearchFieldDataType,
    SimpleField,
    SearchableField
)

endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]

# Create a service client
client = SearchIndexClient(endpoint, AzureKeyCredential(key))

# Create the index
name = "hotels"
fields = [
        SimpleField(name="hotelId", type=SearchFieldDataType.String, key=True),
        SimpleField(name="baseRate", type=SearchFieldDataType.Double),
        SearchableField(name="description", type=SearchFieldDataType.String),
        ComplexField(name="address", fields=[
            SimpleField(name="streetAddress", type=SearchFieldDataType.String),
            SimpleField(name="city", type=SearchFieldDataType.String),
        ])
    ]
cors_options = CorsOptions(allowed_origins=["*"], max_age_in_seconds=60)
scoring_profiles = []

index = SearchIndex(
    name=name,
    fields=fields,
    scoring_profiles=scoring_profiles,
    cors_options=cors_options)

result = client.create_index(index)

Adición de documentos al índice

Puede Upload, Merge, MergeOrUploady Delete varios documentos de un índice en una única solicitud por lotes. Hay algunas reglas especiales para que la combinación tenga en cuenta.

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

index_name = "hotels"
endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]

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

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

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

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

Autenticación en una nube nacional

Para autenticarse en una nube nacional, deberá realizar las siguientes adiciones a la configuración del cliente:

  • Establecer en AuthorityHost las opciones de credenciales o a través de la variable de AZURE_AUTHORITY_HOST entorno
  • Establecer en audienceSearchClient, SearchIndexCliento 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, crdential=credential, audience="https://search.azure.cn")

Recuperación de un documento específico del índice

Además de consultar documentos mediante palabras clave y filtros opcionales, puede recuperar un documento específico del índice si ya conoce la clave. Puede obtener la clave de una consulta, por ejemplo, y desea mostrar más información sobre ella o navegar por el cliente a ese documento.

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

index_name = "hotels"
endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]

client = SearchClient(endpoint, index_name, AzureKeyCredential(key))

result = client.get_document(key="1")

print("Details for hotel '1' are:")
print("        Name: {}".format(result["HotelName"]))
print("      Rating: {}".format(result["Rating"]))
print("    Category: {}".format(result["Category"]))

API asincrónicas

Esta biblioteca incluye una API asincrónica completa. Para usarlo, primero debe instalar un transporte asincrónico, como aiohttp. Consulte la documentación de azure-core para más información.

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

client = SearchClient(endpoint, index_name, AzureKeyCredential(api_key))

async with client:
  results = await client.search(search_text="hotel")
  async for result in results:
    print("{}: {})".format(result["hotelId"], result["hotelName"]))

...

Solución de problemas

General

El cliente de Azure Cognitive Search generará excepciones definidas en Azure Core.

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado del nivel de depuración, incluidos los cuerpos de solicitud y respuesta, y los encabezados no redactados, se puede habilitar en un cliente con el argumento de palabra clave 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)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

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

Pasos siguientes

Contribuir

Consulte nuestra CONTRIBUTING.md de búsqueda para obtener más información sobre la compilación, las pruebas y la contribución a esta biblioteca.

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones

Impresiones