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

  • Artículo

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 los tipos de contenido variados 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 sentimiento. 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.
  • Crear y administrar índices de búsqueda.
  • Cargue y actualice documentos en el índice de búsqueda.
  • Cree y administre indexadores que extraen datos de Azure en un índice.
  • Cree y administre conjuntos de aptitudes que agregan enriquecimiento con IA a la ingesta de datos.
  • Cree y administre analizadores para el análisis avanzado de texto 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 | fuentePaquete (PyPI) | Paquete (Conda) | Documentación | de referencia de API | Documentación del productoMuestras

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

Para interactuar con el servicio Search, deberá crear una instancia de la clase de cliente adecuada: SearchClient para buscar documentos indexados, SearchIndexClient administrar índices o SearchIndexerClient rastrear orígenes de datos y cargar documentos de búsqueda en un índice. Para crear una instancia de un objeto de cliente, necesitará un punto de conexión y una clave de API. Puede consultar la documentación para obtener más información sobre los enfoques de autenticación admitidos con el servicio Search.

Obtención de una clave de API

Puede obtener el punto de conexión y una clave de API de la servicio Search en Azure Portal. Consulte la documentación para obtener instrucciones sobre cómo obtener una clave de API.

Como alternativa, puede usar el siguiente comando de la CLI de Azure para recuperar la clave de API de la servicio Search:

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: claves 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.

Creación de un elemento SearchClient

Para crear una instancia de SearchClient, necesitará el punto de conexión, la clave de API y el nombre del índice:

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))

Creación de un cliente mediante la autenticación de Azure Active Directory

También puede crear un SearchClient, SearchIndexCliento SearchIndexerClient mediante la autenticación de Azure Active Directory (AAD). El usuario o la entidad de servicio deben tener asignado el rol "Lector de datos de índice de búsqueda". Con DefaultAzureCredential , puede autenticar un servicio mediante identidad administrada o una entidad de servicio, autenticarse como desarrollador que trabaja en una aplicación y mucho más sin cambiar el código. Consulte la documentación para obtener instrucciones sobre cómo conectarse a Azure Cognitive Search mediante el control de acceso basado en rol de Azure (RBAC de Azure).

Para poder usar , DefaultAzureCredentialo cualquier tipo de credencial de Azure.Identity, primero deberá instalar el paquete Azure.Identity.

Para usar DefaultAzureCredential con un identificador de cliente y un secreto, deberá establecer las AZURE_TENANT_IDvariables de entorno , AZURE_CLIENT_IDy AZURE_CLIENT_SECRET ; como alternativa, puede pasar esos valores a ClientSecretCredential también en Azure.Identity.

Asegúrese de usar el espacio de nombres adecuado para DefaultAzureCredential en la parte superior del archivo de origen:

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)

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.

Azure Cognitive Search proporciona dos características eficaces: búsqueda semántica y búsqueda vectorial.

La búsqueda semántica mejora la calidad de los resultados de búsqueda para las consultas basadas en texto. Al habilitar la búsqueda semántica en el servicio de búsqueda, puede mejorar la relevancia de los resultados de búsqueda de dos maneras:

  • Aplica la clasificación secundaria al conjunto de resultados inicial, lo que promueve los resultados más semánticamente relevantes en la parte superior.
  • Extrae y devuelve subtítulos y respuestas en la respuesta, que se pueden mostrar en una página de búsqueda para mejorar la experiencia de búsqueda del usuario.

Para más información sobre la búsqueda semántica, puede consultar la documentación.

La búsqueda de vectores es una técnica de recuperación de información que supera las limitaciones de la búsqueda tradicional basada en palabras clave. En lugar de basarse únicamente en el análisis léxico y la coincidencia de términos de consulta individuales, la búsqueda de vectores utiliza modelos de aprendizaje automático para capturar el significado contextual de palabras y frases. Representa documentos y consultas como vectores en un espacio de alta dimensión denominado incrustación. Al comprender la intención detrás de la consulta, la búsqueda de vectores puede proporcionar resultados más relevantes que se alineen con los requisitos del usuario, incluso si los términos exactos no están presentes en el documento. Además, la búsqueda de vectores se puede aplicar a varios tipos de contenido, incluidas imágenes y vídeos, no solo texto.

Para obtener información sobre cómo indexar los campos vectoriales y realizar la búsqueda de vectores, puede hacer referencia al ejemplo. En este ejemplo se proporcionan instrucciones detalladas sobre los campos vectoriales de indexación y se muestra cómo realizar la búsqueda vectorial.

Además, para obtener información más completa sobre la búsqueda de vectores, incluidos sus conceptos y uso, puede consultar la documentación. La documentación proporciona explicaciones detalladas e instrucciones sobre cómo aprovechar la eficacia de la búsqueda de vectores en Azure Cognitive Search.

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 simple que 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

Comencemos 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 a nuestro í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)

Vamos a buscar 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.

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)

Adición de documentos al índice

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

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))

Autenticación en una nube nacional

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

  • Establecimiento de AuthorityHost en las opciones de credenciales o a través de la variable de AZURE_AUTHORITY_HOST entorno
  • audience Establezca en SearchClient, 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, credential=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.

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 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

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"]))

Solución de problemas

General

El cliente 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

Contribuciones

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