Azure Cognitive Search biblioteca de clientes para Python – versão 11.4.0

  • Artigo

O Azure Cognitive Search é uma solução de pesquisa como serviço na nuvem que oferece aos desenvolvedores APIs e ferramentas para adicionar uma experiência de pesquisa sofisticada a um conteúdo particular e heterogêneo em aplicativos Web, móveis e empresariais.

O serviço Azure Cognitive Search é adequado para os seguintes cenários de aplicativo:

  • Consolide tipos de conteúdo variados em um único índice pesquisável. Para preencher um índice, você pode enviar por push documentos JSON que contenham seu conteúdo ou, se os dados já estiverem no Azure, crie um indexador para efetuar pull dos dados automaticamente.
  • Anexe conjuntos de habilidades a um indexador para criar conteúdo pesquisável a partir de imagens e documentos de texto grandes. Um conjunto de habilidades aproveita a IA dos Serviços Cognitivos para OCR interno, reconhecimento de entidade, extração de frases-chave, detecção de idioma, tradução de texto e análise de sentimento. Você também pode adicionar habilidades personalizadas para integrar o processamento externo do seu conteúdo durante a ingestão de dados.
  • Em um aplicativo cliente de pesquisa, implemente a lógica de consulta e as experiências do usuário semelhantes aos mecanismos de pesquisa da Web comerciais.

Use a biblioteca de clientes do Azure.Search.Documents para:

  • Envie consultas para formulários de consulta simples e avançados que incluem pesquisa difusa, pesquisa curinga, expressões regulares.
  • Implemente consultas filtradas para navegação facetada, pesquisa geoespacial ou para restringir os resultados com base em critérios de filtro.
  • Criar e gerenciar índices de pesquisa.
  • Carregar e atualizar documentos no índice de pesquisa.
  • Crie e gerencie indexadores que efetuam pull de dados do Azure para um índice.
  • Crie e gerencie conjuntos de habilidades que adicionam enriquecimento de IA à ingestão de dados.
  • Crie e gerencie analisadores para análise de texto avançada ou conteúdo multilíngue.
  • Otimize os resultados por meio de perfis de pontuação para considerar a lógica de negócios ou a atualização.

Código-fonte | Pacote (PyPI) | Pacote (Conda) | Documentação | de referência da APIDocumentação do produto | Amostras

Introdução

Instalar o pacote

Instale a biblioteca de clientes do Azure Cognitive Search para Python com pip:

pip install azure-search-documents

Pré-requisitos

Para criar um novo serviço de pesquisa, você pode usar o portal do Azure, Azure PowerShell ou a CLI do Azure.

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

Consulte escolher um tipo de preço para obter mais informações sobre as opções disponíveis.

Autenticar o cliente

Para interagir com o serviço Pesquisa, você precisará criar uma instância da classe de cliente apropriada: SearchClient para pesquisar documentos indexados, SearchIndexClient gerenciar índices ou SearchIndexerClient rastrear fontes de dados e carregar documentos de pesquisa em um índice. Para criar uma instância de um objeto de cliente, você precisará de um ponto de extremidade e uma chave de API. Você pode consultar a documentação para obter mais informações sobre abordagens de autenticação com suporte com o serviço Pesquisa.

Obter uma chave de API

Você pode obter o ponto de extremidade e uma chave de API do serviço Pesquisa no Portal do Azure. Consulte a documentação para obter instruções sobre como obter uma chave de API.

Como alternativa, você pode usar o seguinte comando da CLI do Azure para recuperar a chave de API do serviço Pesquisa:

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

Há dois tipos de chaves usadas para acessar o serviço de pesquisa: admin(leitura-gravação) e chaves de consulta(somente leitura). Restringir o acesso e as operações em aplicativos cliente é essencial para proteger os ativos de pesquisa em seu serviço. Sempre use uma chave de consulta em vez de uma chave de administração para qualquer consulta proveniente de um aplicativo cliente.

Observação: o snippet de exemplo da CLI do Azure acima recupera uma chave de administrador para que seja mais fácil começar a explorar APIs, mas deve ser gerenciado com cuidado.

Criar um SearchClient

Para instanciar o SearchClient, você precisará do ponto de extremidade, da chave de API e do nome do í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))

Criar um cliente usando a autenticação do Azure Active Directory

Você também pode criar um SearchClient, SearchIndexClientou SearchIndexerClient usando a autenticação do AAD (Azure Active Directory). Seu usuário ou entidade de serviço deve receber a função "Leitor de Dados de Índice de Pesquisa". Usando o DefaultAzureCredential , você pode autenticar um serviço usando a Identidade Gerenciada ou uma entidade de serviço, autenticar-se como um desenvolvedor trabalhando em um aplicativo e muito mais sem alterar o código. Consulte a documentação para obter instruções sobre como se conectar a Azure Cognitive Search usando o RBAC do Azure (controle de acesso baseado em função do Azure).

Antes de usar o DefaultAzureCredentialou qualquer tipo de credencial do Azure.Identity, primeiro você precisará instalar o pacote Azure.Identity.

Para usar DefaultAzureCredential com uma ID do cliente e um segredo, você precisará definir as AZURE_TENANT_IDvariáveis de ambiente , AZURE_CLIENT_IDe AZURE_CLIENT_SECRET ; como alternativa, você pode passar esses valores para o ClientSecretCredential também em Azure.Identity.

Use o namespace certo para DefaultAzureCredential na parte superior do arquivo de origem:

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)

Principais conceitos

Um serviço Azure Cognitive Search contém um ou mais índices que fornecem armazenamento persistente de dados pesquisáveis na forma de documentos JSON. (Se você for totalmente novo para pesquisar, poderá fazer uma analogia muito aproximada entre índices e tabelas de banco de dados.) A biblioteca de clientes do Azure.Search.Documents expõe operações nesses recursos por meio de dois tipos de cliente main.

Azure Cognitive Search fornece dois recursos poderosos: Pesquisa Semântica e Pesquisa de Vetor.

A Pesquisa Semântica aprimora a qualidade dos resultados da pesquisa para consultas baseadas em texto. Ao habilitar a Pesquisa Semântica em seu serviço de pesquisa, você pode melhorar a relevância dos resultados da pesquisa de duas maneiras:

  • Ele aplica a classificação secundária ao conjunto de resultados inicial, promovendo os resultados mais semanticamente relevantes para o topo.
  • Ele extrai e retorna legendas e respostas na resposta, que podem ser exibidas em uma página de pesquisa para aprimorar a experiência de pesquisa do usuário.

Para saber mais sobre a Pesquisa Semântica, consulte a documentação.

A Pesquisa de Vetor é uma técnica de recuperação de informações que supera as limitações da pesquisa tradicional baseada em palavra-chave. Em vez de depender exclusivamente da análise lexical e da correspondência de termos de consulta individuais, a Pesquisa de Vetor utiliza modelos de machine learning para capturar o significado contextual de palavras e frases. Ele representa documentos e consultas como vetores em um espaço de alta dimensão chamado de inserção. Ao entender a intenção por trás da consulta, a Pesquisa de Vetor pode fornecer resultados mais relevantes que se alinham aos requisitos do usuário, mesmo que os termos exatos não estejam presentes no documento. Além disso, a Pesquisa de Vetor pode ser aplicada a vários tipos de conteúdo, incluindo imagens e vídeos, não apenas texto.

Para saber como indexar campos de vetor e executar a pesquisa de vetor, você pode consultar o exemplo. Este exemplo fornece diretrizes detalhadas sobre a indexação de campos de vetor e demonstra como executar a pesquisa de vetor.

Além disso, para obter informações mais abrangentes sobre a Pesquisa de Vetor, incluindo seus conceitos e uso, você pode consultar a documentação. A documentação fornece explicações detalhadas e orientações sobre como aproveitar o poder da Pesquisa de Vetores em Azure Cognitive Search.

A Azure.Search.Documents biblioteca de clientes (v1) é uma nova oferta para desenvolvedores do Python que desejam usar a tecnologia de pesquisa em seus aplicativos. Há uma biblioteca de clientes mais antiga e totalmente em Microsoft.Azure.Search destaque (v10) com muitas APIs semelhantes, portanto, tenha cuidado para evitar confusão ao explorar recursos online.

Exemplos

Todos os exemplos a seguir usam um conjunto de dados hoteleiro simples que você pode importar para seu próprio índice do portal do Azure. Estes são apenas alguns dos conceitos básicos - por favor, marcar nossos Exemplos para muito mais.

Consultas

Vamos começar importando nossos namespaces.

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

Em seguida, criaremos um SearchClient para acessar nosso índice de pesquisa de hotéis.

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 procurar um hotel de "luxo".

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

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

Criando um índice

Você pode usar o SearchIndexClient para criar um índice de pesquisa. Os campos podem ser definidos usando modelos convenientes SimpleField, SearchableFieldou ComplexField . Os índices também podem definir sugestores, analisadores léxicos e muito mais.

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)

Adicionando documentos ao índice

Você pode Upload, Merge, MergeOrUploade Delete vários documentos de um índice em uma única solicitação em lote. Há algumas regras especiais para mesclar para estar ciente.

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

Autenticar em uma nuvem nacional

Para se autenticar em uma Nuvem Nacional, você precisará fazer as seguintes adições à configuração do cliente:

  • Defina o AuthorityHost nas opções de credencial ou por meio da AZURE_AUTHORITY_HOST variável de ambiente
  • Definir o audience em SearchClient, SearchIndexClientou 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")

Recuperando um documento específico do índice

Além de consultar documentos usando palavras-chave e filtros opcionais, você pode recuperar um documento específico do índice se já souber a chave. Você pode obter a chave de uma consulta, por exemplo, e deseja mostrar mais informações sobre ela ou navegar pelo cliente para esse 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"]))

APIs assíncronas

Essa biblioteca inclui uma API assíncrona completa. Para usá-lo, primeiro você deve instalar um transporte assíncrono, como aiohttp. Confira a documentação do azure-core para obter mais informações.

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

Solução de problemas

Geral

O cliente Azure Cognitive Search gerará exceções definidas no Azure Core.

Registro em log

Essa biblioteca usa a biblioteca de log padrão para registro em log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

O log detalhado no nível de DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um cliente com o argumento de palavra-chave 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)

Da mesma forma, logging_enable pode habilitar o log detalhado para uma operação individual, mesmo quando ela não está habilitada para o cliente:

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

Próximas etapas

Participante

Consulte nosso CONTRIBUTING.md de Pesquisa para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões

Impressões