Ricerca cognitiva di Azure libreria client per Python - versione 11.4.0

  • Articolo

Ricerca cognitiva di Azure è una soluzione cloud di ricerca distribuita come servizio che offre agli sviluppatori le API e gli strumenti necessari per aggiungere un'esperienza di ricerca arricchita su contenuti eterogenei e privati nelle applicazioni Web, aziendali e per dispositivi mobili.

Il servizio Ricerca cognitiva di Azure è adatto per gli scenari dell'applicazione seguenti:

  • Consolidare diversi tipi di contenuto in un singolo indice ricercabile. Per popolare un indice, è possibile eseguire il push di documenti JSON contenenti il contenuto oppure se i dati sono già in Azure, creare un indicizzatore per eseguire il pull automatico dei dati.
  • Collegare i set di competenze a un indicizzatore per creare contenuto ricercabile da immagini e documenti di testo di grandi dimensioni. Un set di competenze sfrutta l'intelligenza artificiale da Servizi cognitivi per L'OCR predefinito, il riconoscimento delle entità, l'estrazione di frasi chiave, il rilevamento della lingua, la traduzione del testo e l'analisi del sentiment. È anche possibile aggiungere competenze personalizzate per integrare l'elaborazione esterna del contenuto durante l'inserimento dei dati.
  • In un'applicazione client di ricerca implementare la logica di query e le esperienze utente simili ai motori di ricerca Web commerciali.

Usare la libreria client Azure.Search.Documents per:

  • Inviare query per moduli di query semplici e avanzati che includono la ricerca fuzzy, la ricerca con caratteri jolly, le espressioni regolari.
  • Implementare query filtrate per la navigazione con facet, la ricerca geospaziale o per limitare i risultati in base ai criteri di filtro.
  • Creare e gestire gli indici di ricerca.
  • Caricare e aggiornare documenti nell'indice di ricerca.
  • Creare e gestire gli indicizzatori che estraggono i dati da Azure in un indice.
  • Creare e gestire set di competenze che aggiungono l'arricchimento dell'intelligenza artificiale all'inserimento dei dati.
  • Creare e gestire analizzatori per l'analisi avanzata del testo o il contenuto multi-linguale.
  • Ottimizzare i risultati tramite profili di assegnazione dei punteggi per tenere conto della logica di business o della freschezza.

Codice | sorgentePacchetto (PyPI) | Pacchetto (Conda) | Documentazione di | riferimento sulle APIDocumentazione | del prodottoCampioni

Introduzione

Installare il pacchetto

Installare la libreria client Ricerca cognitiva di Azure per Python con pip:

pip install azure-search-documents

Prerequisiti

Per creare un nuovo servizio di ricerca, è possibile usare la portale di Azure, la Azure PowerShell o l'interfaccia della riga di comando di Azure. 

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

Per altre informazioni sulle opzioni disponibili, vedere la scelta di un piano tariffario .

Autenticare il client

Per interagire con la servizio di ricerca, è necessario creare un'istanza della classe client appropriata: SearchClient per la ricerca di documenti indicizzati, SearchIndexClient per la gestione degli indici o SearchIndexerClient per la ricerca per indicizzazione di origini dati e il caricamento di documenti di ricerca in un indice. Per creare un'istanza di un oggetto client, è necessario un endpoint e una chiave API. È possibile fare riferimento alla documentazione per altre informazioni sugli approcci di autenticazione supportati con la servizio di ricerca.

Ottenere una chiave API

È possibile ottenere l'endpoint e una chiave API dal servizio di ricerca nel portale di Azure. Per istruzioni su come ottenere una chiave API, vedere la documentazione .

In alternativa, è possibile usare il comando dell'interfaccia della riga di comando di Azure seguente per recuperare la chiave API dal servizio di ricerca:

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

Esistono due tipi di chiavi usate per accedere al servizio di ricerca: admin(read-write) e query(read-only). Limitare l'accesso e le operazioni nelle app client è essenziale per proteggere gli asset di ricerca nel servizio. Usare sempre una chiave di query anziché una chiave di amministrazione per qualsiasi query proveniente da un'app client.

Nota: il frammento di interfaccia della riga di comando di Azure di esempio recupera una chiave di amministrazione in modo che sia più semplice iniziare a esplorare le API, ma deve essere gestito attentamente.

Creare un SearchClient

Per creare un'istanza di SearchClient, è necessario l'endpoint, la chiave API e il nome dell'indice:

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

Creare un client usando l'autenticazione di Azure Active Directory

È anche possibile creare un SearchClientoggetto , SearchIndexCliento SearchIndexerClient usando l'autenticazione di Azure Active Directory (AAD). L'utente o l'entità servizio devono essere assegnati al ruolo "Search Index Data Reader". Usando DefaultAzureCredential è possibile autenticare un servizio usando l'identità gestita o un'entità servizio, autenticarsi come sviluppatore che lavora su un'applicazione e altro ancora senza modificare il codice. Per istruzioni su come connettersi a Ricerca cognitiva di Azure, vedere la documentazione relativa al controllo degli accessi in base al ruolo di Azure.

Prima di poter usare , DefaultAzureCredentialo qualsiasi tipo di credenziale da Azure.Identity, è prima necessario installare il pacchetto Azure.Identity.

Per usare DefaultAzureCredential con un ID client e un segreto, è necessario impostare le AZURE_TENANT_IDvariabili di ambiente , AZURE_CLIENT_IDe , AZURE_CLIENT_SECRET in alternativa, è possibile passare tali valori anche ClientSecretCredential in Azure.Identity.

Assicurarsi di usare lo spazio dei nomi corretto per DefaultAzureCredential nella parte superiore del file di origine:

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)

Concetti chiave

Un servizio Ricerca cognitiva di Azure contiene uno o più indici che forniscono un archivio permanente di dati ricercabili sotto forma di documenti JSON. Se non si ha familiarità con la ricerca, è possibile creare un'analogia molto approssimativa tra indici e tabelle di database. La libreria client Azure.Search.Documents espone operazioni su queste risorse tramite due tipi client principali.

Ricerca cognitiva di Azure offre due potenti funzionalità: Ricerca semantica e Ricerca vettoriale.

La ricerca semantica migliora la qualità dei risultati della ricerca per le query basate su testo. Abilitando La ricerca semantica nel servizio di ricerca, è possibile migliorare la rilevanza dei risultati della ricerca in due modi:

  • Si applica la classificazione secondaria al set di risultati iniziale, promuovendo i risultati più rilevanti in modo semantico all'inizio.
  • Estrae e restituisce didascalie e risposte nella risposta, che può essere visualizzata in una pagina di ricerca per migliorare l'esperienza di ricerca dell'utente.

Per altre informazioni sulla ricerca semantica, è possibile fare riferimento alla documentazione.

Ricerca vettoriale è una tecnica di recupero delle informazioni che supera le limitazioni della ricerca tradizionale basata su parole chiave. Anziché basarsi esclusivamente sull'analisi lessicale e sulla corrispondenza dei singoli termini di query, Vector Search usa modelli di Machine Learning per acquisire il significato contestuale di parole e frasi. Rappresenta documenti e query come vettori in uno spazio ad alta dimensione denominato incorporamento. Comprendendo la finalità dietro la query, La ricerca vettoriale può offrire risultati più pertinenti che si allineano ai requisiti dell'utente, anche se i termini esatti non sono presenti nel documento. Inoltre, La ricerca vettoriale può essere applicata a vari tipi di contenuto, tra cui immagini e video, non solo testo.

Per informazioni su come indicizzare i campi vettoriali ed eseguire la ricerca vettoriale, è possibile fare riferimento all'esempio. Questo esempio fornisce indicazioni dettagliate sui campi vettoriali di indicizzazione e illustra come eseguire la ricerca vettoriale.

Inoltre, per informazioni più complete sulla ricerca vettoriale, inclusi i concetti e l'utilizzo, è possibile fare riferimento alla documentazione. La documentazione fornisce spiegazioni approfondite e indicazioni su come sfruttare la potenza di Ricerca vettoriale in Ricerca cognitiva di Azure.

La Azure.Search.Documents libreria client (v1) è una nuova offerta per gli sviluppatori Python che vogliono usare la tecnologia di ricerca nelle applicazioni. Esiste una libreria client precedente e completamente in primo piano Microsoft.Azure.Search (v10) con molte API simili, quindi prestare attenzione a evitare confusione durante l'esplorazione delle risorse online.

Esempio

Gli esempi seguenti usano tutti un semplice set di dati hotel che è possibile importare nel proprio indice dalla portale di Azure. Queste sono solo alcune delle nozioni di base: vedere i nostri esempi per molto altro.

Query

Iniziamo importando gli spazi dei nomi.

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

Verrà quindi creato un oggetto SearchClient per accedere all'indice di ricerca degli hotel.

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)

Cerchiamo un hotel "lusso".

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

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

Creazione di un indice

È possibile usare per SearchIndexClient creare un indice di ricerca. I campi possono essere definiti usando modelli , o ComplexField praticiSimpleFieldSearchableField. Gli indici possono anche definire i suggeritori, gli analizzatori lessicali e altro ancora.

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)

Aggiunta di documenti all'indice

È possibile Upload, Merge, MergeOrUploade Delete più documenti da un indice in una singola richiesta in batch. Esistono alcune regole speciali per l'unione di cui tenere conto.

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

Eseguire l'autenticazione in un cloud nazionale

Per eseguire l'autenticazione in un cloud nazionale, è necessario apportare le aggiunte seguenti alla configurazione client:

  • Impostare nelle AuthorityHost opzioni delle credenziali o tramite la AZURE_AUTHORITY_HOST variabile di ambiente
  • Impostare in 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, credential=credential, audience="https://search.azure.cn")

Recupero di un documento specifico dall'indice

Oltre a eseguire query per i documenti usando parole chiave e filtri facoltativi, è possibile recuperare un documento specifico dall'indice se si conosce già la chiave. È possibile ottenere la chiave da una query, ad esempio, e visualizzare altre informazioni su di esso o spostarsi al cliente in tale 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 asincrone

Questa libreria include un'API asincrona completa. Per usarlo, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. Per altre informazioni, vedere la documentazione di 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"]))

Risoluzione dei problemi

Generale

Il client Ricerca cognitiva di Azure genererà eccezioni definite in Azure Core.

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.

La registrazione dettagliata a livello di debug, inclusi i corpi di richiesta-risposta e le intestazioni non modificate, può essere abilitata su un client con l'argomento parola chiave 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)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:

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

Passaggi successivi

Contributo

Per informazioni dettagliate sulla compilazione, il test e il contributo a questa libreria, vedere il CONTRIBUTING.md di ricerca .

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, visitare cla.microsoft.com.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Impression

Impression