Azure Cognitive Search biblioteca de cliente para Python - versão 11.4.0

  • Artigo

Azure Cognitive Search é uma solução cloud de pesquisa como serviço que fornece aos programadores APIs e ferramentas para adicionar uma experiência de pesquisa avançada sobre conteúdo privado e heterogéneo em aplicações Web, móveis e empresariais.

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

  • Consolidar tipos de conteúdo variados num único índice pesquisável. Para preencher um índice, pode emitir documentos JSON que contenham o seu conteúdo ou, se os seus dados já estiverem no Azure, crie um indexador para solicitar dados automaticamente.
  • Anexe conjuntos de competências a um indexador para criar conteúdos pesquisáveis a partir de imagens e documentos de texto grandes. Um conjunto de competências tira partido da IA dos Serviços Cognitivos para OCR incorporado, reconhecimento de entidades, extração de expressões-chave, deteção de idiomas, tradução de texto e análise de sentimentos. Também pode adicionar competências personalizadas para integrar o processamento externo dos seus conteúdos durante a ingestão de dados.
  • Numa aplicação cliente de pesquisa, implemente a lógica de consulta e as experiências de utilizador semelhantes aos motores de busca web comerciais.

Utilize a biblioteca de cliente Azure.Search.Documents para:

  • Submeta consultas para formulários de consulta simples e avançados que incluam pesquisa difusa, pesquisa de carateres universais, expressões regulares.
  • Implemente consultas filtradas para navegação facetada, pesquisa geoespacial ou para restringir resultados com base em critérios de filtro.
  • Criar e gerir índices de pesquisa.
  • Carregar e atualizar documentos no índice de pesquisa.
  • Crie e faça a gestão de indexadores que extraem dados do Azure para um índice.
  • Crie e faça a gestão de conjuntos de competências que adicionam o melhoramento de IA à ingestão de dados.
  • Crie e faça a gestão de analisadores para análise de texto avançada ou conteúdo multilinngue.
  • Otimize os resultados através de perfis de classificação para ter em conta a lógica de negócio ou a frescura.

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

Introdução

Instalar o pacote

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

pip install azure-search-documents

Pré-requisitos

Para criar um novo serviço de pesquisa, pode utilizar 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

Veja escolher um escalão de preço para obter mais informações sobre as opções disponíveis.

Autenticar o cliente

Para interagir com o Serviço de pesquisa, terá de criar uma instância da classe de cliente adequada: SearchClient para procurar documentos indexados, SearchIndexClient para gerir índices ou SearchIndexerClient para pesquisar origens de dados e carregar documentos de pesquisa para um índice. Para instanciar um objeto de cliente, precisará de um ponto final e de uma chave de API. Pode consultar a documentação para obter mais informações sobre abordagens de autenticação suportadas com o Serviço de pesquisa.

Obter uma Chave de API

Pode obter o ponto final e uma chave de API do Serviço de pesquisa no Portal do Azure. Consulte a documentação para obter instruções sobre como obter uma chave de API.

Em alternativa, pode utilizar o seguinte comando da CLI do Azure para obter a chave de API do Serviço de pesquisa:

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

Existem dois tipos de chaves utilizadas para aceder ao seu serviço de pesquisa: chaves de administração(leitura-escrita) e consulta(só de leitura). Restringir o acesso e as operações nas aplicações cliente é essencial para salvaguardar os recursos de pesquisa no seu serviço. Utilize sempre uma chave de consulta em vez de uma chave de administrador para qualquer consulta com origem numa aplicação cliente.

Nota: o fragmento de exemplo da CLI do Azure acima obtém uma chave de administrador para que seja mais fácil começar a explorar APIs, mas deve ser gerido cuidadosamente.

Criar um SearchClient

Para instanciar o SearchClient, precisará do ponto final, 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 com a autenticação do Azure Active Directory

Também pode criar uma SearchClientautenticação do SearchIndexClientSearchIndexerClient Azure Active Directory (AAD). Tem de ser atribuída a função "Leitor de Dados do Índice de Pesquisa" ao utilizador ou principal de serviço. Com o DefaultAzureCredential , pode autenticar um serviço com a Identidade Gerida ou um principal de serviço, autenticar-se como programador a trabalhar numa aplicação e muito mais sem alterar o código. Veja a documentação para obter instruções sobre como ligar a Azure Cognitive Search com o controlo de acesso baseado em funções do Azure (RBAC do Azure).

Antes de poder utilizar o DefaultAzureCredential, ou qualquer tipo de credencial do Azure.Identity, primeiro terá de instalar o pacote Azure.Identity.

Para utilizar DefaultAzureCredential com um ID de cliente e um segredo, terá de definir as AZURE_TENANT_IDvariáveis , AZURE_CLIENT_IDe AZURE_CLIENT_SECRET de ambiente; em alternativa, pode transmitir esses valores para o ClientSecretCredential também em Azure.Identity.

Certifique-se de que utiliza o espaço de nomes certo para DefaultAzureCredential na parte superior do ficheiro 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)

Conceitos-chave

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 não estiver familiarizado com a pesquisa, pode criar uma analogia muito aproximada entre índices e tabelas de bases de dados.) A biblioteca de cliente Azure.Search.Documents expõe operações nestes recursos através de dois tipos de cliente principais.

Azure Cognitive Search fornece duas funcionalidades avançadas: Pesquisa Semântica e Pesquisa de Vetores.

A Pesquisa Semântica melhora a qualidade dos resultados da pesquisa para consultas baseadas em texto. Ao ativar a Pesquisa Semântica no seu serviço de pesquisa, pode melhorar a relevância dos resultados da pesquisa de duas formas:

  • Aplica a classificação secundária ao conjunto de resultados inicial, promovendo os resultados mais semanticamente relevantes para o topo.
  • Extrai e devolve legendas e respostas na resposta, que podem ser apresentadas numa página de pesquisa para melhorar a experiência de pesquisa do utilizador.

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

A Pesquisa de Vetores é uma técnica de obtenção de informações que supera as limitações da pesquisa tradicional baseada em palavras-chave. Em vez de depender apenas da análise lexical e dos termos de consulta individuais correspondentes, a Pesquisa de Vetores utiliza modelos de machine learning para capturar o significado contextual de palavras e expressões. Representa documentos e consultas como vetores num espaço altamente dimensional chamado incorporação. Ao compreender a intenção subjacente à consulta, a Pesquisa de Vetores pode fornecer resultados mais relevantes que se alinham com os requisitos do utilizador, mesmo que os termos exatos não estejam presentes no documento. Além disso, a Pesquisa de Vetores pode ser aplicada a vários tipos de conteúdo, incluindo imagens e vídeos, e não apenas texto.

Para saber como indexar campos de vetor e realizar a pesquisa de vetores, pode consultar o exemplo. Este exemplo fornece orientações detalhadas sobre a indexação de campos de vetor e demonstra como realizar a pesquisa de vetores.

Além disso, para obter informações mais abrangentes sobre a Pesquisa de Vetores, incluindo os respetivos conceitos e utilização, pode consultar a documentação. A documentação fornece explicações detalhadas e orientações sobre como tirar partido do poder da Pesquisa de Vetores no Azure Cognitive Search.

A Azure.Search.Documents biblioteca de cliente (v1) é uma nova oferta para os programadores de Python que pretendem utilizar a tecnologia de pesquisa nas suas aplicações. Existe uma biblioteca de cliente mais antiga e totalmente em Microsoft.Azure.Search destaque (v10) com muitas APIs semelhantes, por isso tenha cuidado para evitar confusões ao explorar recursos online.

Exemplos

Todos os exemplos seguintes utilizam um conjunto de dados do Hotel simples que pode importar para o seu próprio índice a partir do portal do Azure. Estas são apenas algumas das noções básicas: consulte os nossos Exemplos para obter muito mais.

A consultar

Vamos começar por importar os nossos espaços de nomes.

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

Em seguida, vamos criar um SearchClient para aceder ao í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"]))

Criar um índice

Pode utilizar o SearchIndexClient para criar um índice de pesquisa. Os campos podem ser definidos com modelos , SearchableFieldou ComplexField convenientesSimpleField. Os índices também podem definir sugestores, analisadores lexical 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)

Adicionar documentos ao índice

Pode Upload, , MergeMergeOrUploade Delete vários documentos de um índice num único pedido em lote. Existem algumas regras especiais para intercalar .

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 numa Cloud Nacional

Para se autenticar numa Cloud Nacional, terá de fazer as seguintes adições à configuração do cliente:

  • Definir o AuthorityHost nas opções de credenciais ou através da variável de AZURE_AUTHORITY_HOST ambiente
  • Defina 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")

Obter um documento específico do índice

Além de consultar documentos com palavras-chave e filtros opcionais, pode obter um documento específico do índice se já souber a chave. Pode obter a chave de uma consulta, por exemplo, e pretende mostrar mais informações sobre a mesma ou navegar o 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

Esta biblioteca inclui uma API assíncrona completa. Para utilizá-lo, primeiro tem de instalar um transporte assíncrono, como o aiohttp. Veja 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"]))

Resolução de problemas

Geral

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

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registo. As informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível da INFORMAÇÃO.

O registo ao nível de DEBUG detalhado, incluindo os corpos de pedido/resposta e os cabeçalhos não retotados, pode ser ativado num cliente com o logging_enable argumento de palavra-chave:

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 ativar o registo detalhado para uma única operação, mesmo quando não está ativado para o cliente:

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

Passos seguintes

Contribuir

Veja o nosso CONTRIBUTING.md de Pesquisa para obter detalhes sobre como criar, testar e contribuir para esta biblioteca.

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões

Impressões