bibliothèque de client Recherche cognitive Azure pour Python - version 11.4.0

  • Article

La Recherche cognitive Azure est une solution cloud de recherche en tant que service qui offre aux développeurs des API et des outils permettant d’ajouter une expérience de recherche enrichie sur du contenu privé et hétérogène dans des applications web, mobiles et d’entreprise.

Le service Recherche cognitive Azure convient parfaitement aux scénarios d’application suivants :

  • Regroupez les types de contenu variés dans un seul index pouvant faire l’objet d’une recherche. Pour remplir un index, vous pouvez envoyer (push) des documents JSON qui contiennent votre contenu ou, si vos données sont déjà dans Azure, créer un indexeur pour extraire automatiquement les données.
  • Joignez des ensembles de compétences à un indexeur pour créer du contenu pouvant faire l’objet d’une recherche à partir d’images et de documents texte volumineux. Un ensemble de compétences tire parti de l’IA de Cognitive Services pour l’OCR intégrée, la reconnaissance d’entité, l’extraction d’expressions clés, la détection de langue, la traduction de texte et l’analyse des sentiments. Vous pouvez également ajouter des compétences personnalisées pour intégrer le traitement externe de votre contenu pendant l’ingestion des données.
  • Dans une application cliente de recherche, implémentez une logique de requête et des expériences utilisateur similaires aux moteurs de recherche web commerciaux.

Utilisez la bibliothèque cliente Azure.Search.Documents pour :

  • Envoyez des requêtes pour les formulaires de requête simples et avancés qui incluent la recherche approximative, la recherche par caractères génériques et les expressions régulières.
  • Implémentez des requêtes filtrées pour la navigation à facettes, la recherche géospatiale ou pour affiner les résultats en fonction de critères de filtre.
  • Créer et gérer des index de recherche.
  • Charger et mettre à jour des documents dans l’index de recherche.
  • Créez et gérez des indexeurs qui extrayent des données d’Azure dans un index.
  • Créez et gérez des ensembles de compétences qui ajoutent l’enrichissement par IA à l’ingestion des données.
  • Créez et gérez des analyseurs pour l’analyse de texte avancée ou le contenu multilingue.
  • Optimisez les résultats via des profils de scoring pour prendre en compte la logique métier ou l’actualisation.

| Code sourcePackage (PyPI) | Package (Conda) | Documentation de référence sur les | API | Documentation produitÉchantillons

Prise en main

Installer le package

Installez la bibliothèque cliente Recherche cognitive Azure pour Python avec pip :

pip install azure-search-documents

Prérequis

Pour créer un service de recherche, vous pouvez utiliser le Portail Azure, Azure PowerShell ou Azure CLI.

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

Pour plus d’informations sur les options disponibles, consultez Choix d’un niveau tarifaire .

Authentifier le client

Pour interagir avec le service Search, vous devez créer un instance de la classe cliente appropriée : SearchClient pour la recherche de documents indexés, SearchIndexClient la gestion des index ou SearchIndexerClient l’analyse des sources de données et le chargement de documents de recherche dans un index. Pour instancier un objet client, vous avez besoin d’un point de terminaison et d’une clé API. Pour plus d’informations sur les approches d’authentification prises en charge avec le service Search, consultez la documentation.

Obtenir une clé API

Vous pouvez obtenir le point de terminaison et une clé API à partir du service Search dans le portail Azure. Reportez-vous à la documentation pour obtenir des instructions sur l’obtention d’une clé API.

Vous pouvez également utiliser la commande Azure CLI suivante pour récupérer la clé API du service Search :

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

Deux types de clés sont utilisés pour accéder à votre service de recherche : les clés d’administration(lecture-écriture) et les clés de requête(lecture seule). Il est essentiel de restreindre l'accès et les opérations dans les applications clientes afin de protéger les ressources de recherche de votre service. Utilisez toujours une clé de requête plutôt qu'une clé d'administration pour toutes les requêtes provenant d'une application cliente.

Remarque : l’exemple d’extrait de code Azure CLI ci-dessus récupère une clé d’administration afin de faciliter l’exploration des API, mais elle doit être gérée avec soin.

Créer un SearchClient

Pour instancier le SearchClient, vous aurez besoin du point de terminaison, de la clé API et du nom d’index :

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

Créer un client à l’aide de l’authentification Azure Active Directory

Vous pouvez également créer un SearchClient, SearchIndexClientou à l’aide SearchIndexerClient de l’authentification Azure Active Directory (AAD). Le rôle « Lecteur de données d’index de recherche » doit être attribué à votre utilisateur ou principal de service. À l’aide de DefaultAzureCredential , vous pouvez authentifier un service à l’aide d’une identité managée ou d’un principal de service, vous authentifier en tant que développeur travaillant sur une application, et bien plus encore, sans modifier le code. Consultez la documentation pour obtenir des instructions sur la façon de se connecter à Recherche cognitive Azure à l’aide du contrôle d’accès en fonction du rôle Azure (RBAC Azure).

Avant de pouvoir utiliser , DefaultAzureCredentialou tout type d’informations d’identification à partir d’Azure.Identity, vous devez d’abord installer le package Azure.Identity.

Pour utiliser DefaultAzureCredential avec un ID client et un secret, vous devez définir les AZURE_TENANT_IDvariables d’environnement , AZURE_CLIENT_IDet AZURE_CLIENT_SECRET . Vous pouvez également passer ces valeurs à également ClientSecretCredential dans Azure.Identity.

Veillez à utiliser l’espace de noms approprié pour DefaultAzureCredential en haut de votre fichier source :

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)

Concepts clés

Un service Recherche cognitive Azure contient un ou plusieurs index qui fournissent un stockage persistant des données pouvant faire l’objet d’une recherche sous forme de documents JSON. (Si vous débutez dans la recherche, vous pouvez faire une analogie très approximative entre les index et les tables de base de données.) La bibliothèque de client Azure.Search.Documents expose les opérations sur ces ressources via deux types de clients main.

Recherche cognitive Azure fournit deux fonctionnalités puissantes : la recherche sémantique et la recherche vectorielle.

La recherche sémantique améliore la qualité des résultats de recherche pour les requêtes textuelles. En activant la recherche sémantique sur votre service de recherche, vous pouvez améliorer la pertinence des résultats de recherche de deux manières :

  • Il applique le classement secondaire au jeu de résultats initial, en faisant la promotion des résultats sémantiquement pertinents en haut.
  • Il extrait et retourne des légendes et des réponses dans la réponse, qui peuvent être affichées sur une page de recherche pour améliorer l’expérience de recherche de l’utilisateur.

Pour en savoir plus sur la recherche sémantique, consultez la documentation.

La recherche vectorielle est une technique de récupération d’informations qui surmonte les limitations de la recherche basée sur les mot clé traditionnelles. Au lieu de s’appuyer uniquement sur l’analyse lexicale et de mettre en correspondance des termes de requête individuels, recherche vectorielle utilise des modèles machine learning pour capturer la signification contextuelle des mots et des expressions. Il représente les documents et les requêtes en tant que vecteurs dans un espace de haute dimension appelé incorporation. En comprenant l’intention derrière la requête, la recherche vectorielle peut fournir des résultats plus pertinents qui s’alignent sur les exigences de l’utilisateur, même si les termes exacts ne sont pas présents dans le document. En outre, la recherche vectorielle peut être appliquée à différents types de contenu, y compris des images et des vidéos, et pas seulement du texte.

Pour savoir comment indexer des champs vectoriels et effectuer une recherche vectorielle, vous pouvez vous reporter à l’exemple. Cet exemple fournit des instructions détaillées sur l’indexation des champs vectoriels et montre comment effectuer une recherche vectorielle.

En outre, pour obtenir des informations plus complètes sur la recherche vectorielle, y compris ses concepts et son utilisation, vous pouvez consulter la documentation. La documentation fournit des explications détaillées et des conseils sur l’exploitation de la puissance de la recherche vectorielle dans Recherche cognitive Azure.

La Azure.Search.Documents bibliothèque cliente (v1) est une toute nouvelle offre pour les développeurs Python qui souhaitent utiliser la technologie de recherche dans leurs applications. Il existe une bibliothèque cliente Microsoft.Azure.Search plus ancienne et complète (v10) avec de nombreuses API similaires. Veillez donc à éviter toute confusion lors de l’exploration des ressources en ligne.

Exemples

Les exemples suivants utilisent tous un jeu de données Hotel simple que vous pouvez importer dans votre propre index à partir du Portail Azure. Ce ne sont que quelques-unes des bases - s’il vous plaît case activée nos exemples pour bien plus.

Interrogation

Commençons par importer nos espaces de noms.

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

Nous allons ensuite créer un SearchClient pour accéder à notre index de recherche d’hôtels.

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)

Nous allons chercher un hôtel de luxe.

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

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

Création d'un index

Vous pouvez utiliser pour SearchIndexClient créer un index de recherche. Les champs peuvent être définis à l’aide de SimpleFieldmodèles pratiques , SearchableFieldou ComplexField . Les index peuvent également définir des suggesteurs, des analyseurs lexicales, 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)

Ajout de documents à votre index

Vous pouvez Upload, Merge, MergeOrUploadet Delete plusieurs documents à partir d’un index dans une seule requête par lot. Il existe quelques règles spéciales pour la fusion dont il faut être conscient.

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

S’authentifier dans un cloud national

Pour vous authentifier dans un cloud national, vous devez effectuer les ajouts suivants à votre configuration cliente :

  • Définissez dans AuthorityHost les options d’informations d’identification ou via la variable d’environnement AZURE_AUTHORITY_HOST
  • Définissez dans audienceSearchClient, 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")

Récupération d’un document spécifique à partir de votre index

En plus d’interroger des documents à l’aide de mots clés et de filtres facultatifs, vous pouvez récupérer un document spécifique à partir de votre index si vous connaissez déjà la clé. Vous pouvez obtenir la clé à partir d’une requête, par exemple, et vouloir afficher plus d’informations à ce sujet ou parcourir votre client jusqu’à ce document.

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 asynchrones

Cette bibliothèque comprend une API asynchrone complète. Pour l’utiliser, vous devez d’abord installer un transport asynchrone, tel que aiohttp. Pour plus d’informations, consultez la documentation 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"]))

Dépannage

Général

Le client Recherche cognitive Azure déclenche des exceptions définies dans Azure Core.

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée de niveau DEBUG, comprenant le corps de la demande et/ou de la réponse et les en-têtes non rédigés, peut être activée sur un client à l’aide de l’argument de mot clé 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)

De la même façon, logging_enable peut activer la journalisation détaillée pour une seule opération, même quand elle n’est pas activée pour le client :

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

Étapes suivantes

Contribution

Consultez notre CONTRIBUTING.md de recherche pour plus d’informations sur la création, le test et la contribution à cette bibliothèque.

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, consultez cla.microsoft.com.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions

Impressions