Freigeben über

Azure Cognitive Search Clientbibliothek für Python– Version 11.4.0

  • Artikel

Azure Cognitive Search ist eine Search-as-a-Service-Cloudlösung, die Entwicklern APIs und Tools zum Hinzufügen von umfangreichen Suchfunktionen für private, heterogene Inhalte in Web- und Unternehmensanwendungen sowie in mobilen Anwendungen bietet.

Der Azure Cognitive Search-Dienst eignet sich gut für die folgenden Anwendungsszenarien:

  • Konsolidieren Sie verschiedene Inhaltstypen in einem einzelnen durchsuchbaren Index. Um einen Index aufzufüllen, können Sie JSON-Dokumente, die Ihre Inhalte enthalten, per Push übertragen oder wenn sich Ihre Daten bereits in Azure befinden, einen Indexer erstellen, um Daten automatisch zu pullen.
  • Fügen Sie Skillsets an einen Indexer an, um durchsuchbare Inhalte aus Bildern und großen Textdokumenten zu erstellen. Ein Skillset nutzt KI von Cognitive Services für integrierte OCR, Entitätserkennung, Schlüsselbegriffserkennung, Spracherkennung, Textübersetzung und Stimmungsanalyse. Sie können auch benutzerdefinierte Skills hinzufügen, um die externe Verarbeitung Ihrer Inhalte während der Datenerfassung zu integrieren.
  • Implementieren Sie in einer Suchclientanwendung Abfragelogik und Benutzeroberflächen ähnlich wie bei kommerziellen Websuchmaschinen.

Verwenden Sie die Azure.Search.Documents-Clientbibliothek für Folgendes:

  • Übermitteln Sie Abfragen für einfache und erweiterte Abfrageformulare, die Fuzzysuche, Wildcardsuche und reguläre Ausdrücke umfassen.
  • Implementieren Sie gefilterte Abfragen für die Facettennavigation, die Geosuche oder die Eingrenzung von Ergebnissen basierend auf Filterkriterien.
  • Erstellen und Verwalten von Suchindizes
  • Laden Sie Dokumente im Suchindex hoch, und aktualisieren Sie sie.
  • Erstellen und verwalten Sie Indexer, die Daten aus Azure in einen Index pullen.
  • Erstellen und verwalten Sie Skillsets, die der Datenerfassung KI-Anreicherung hinzufügen.
  • Erstellen und verwalten Sie Analysetools für erweiterte Textanalyse oder mehrsprachige Inhalte.
  • Optimieren Sie Ergebnisse durch Bewertungsprofile, um Geschäftslogik oder Aktualität zu berücksichtigen.

Quellcode | Paket (PyPI) | Paket (Conda) | API-Referenzdokumentation | Produktdokumentation | Proben

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Cognitive Search-Clientbibliothek für Python mit pip:

pip install azure-search-documents

Voraussetzungen

Zum Erstellen eines neuen Suchdiensts können Sie die Azure-Portal, Azure PowerShell oder die Azure CLI verwenden.

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

Weitere Informationen zu verfügbaren Optionen finden Sie unter Auswählen eines Tarifs .

Authentifizieren des Clients

Für die Interaktion mit dem Suchdienst müssen Sie eine instance der entsprechenden Clientklasse erstellen: SearchClient zum Durchsuchen indizierte Dokumente, SearchIndexClient zum Verwalten von Indizes oder SearchIndexerClient zum Durchforsten von Datenquellen und Laden von Suchdokumenten in einen Index. Zum Instanziieren eines Clientobjekts benötigen Sie einen Endpunkt und einen API-Schlüssel. Weitere Informationen zu unterstützten Authentifizierungsansätzen mit dem Suchdienst finden Sie in der Dokumentation.

Abrufen eines API-Schlüssels

Sie können den Endpunkt und einen API-Schlüssel aus der Suchdienst im Azure-Portal abrufen. Anweisungen zum Abrufen eines API-Schlüssels finden Sie in der Dokumentation .

Alternativ können Sie den folgenden Azure CLI-Befehl verwenden, um den API-Schlüssel aus dem Suchdienst abzurufen:

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

Es gibt zwei Arten von Schlüsseln, die für den Zugriff auf Ihren Suchdienst verwendet werden: Administratorschlüssel(Lese-/Schreibzugriff) und Abfrageschlüssel(schreibgeschützt). Das Einschränken des Zugriffs und der Vorgänge in Client-Apps ist besonders wichtig, um die Suchobjekte in Ihrem Dienst zu schützen. Verwenden Sie für Abfragen aus einer Client-App immer einen Abfrageschlüssel anstelle eines Administratorschlüssels.

Hinweis: Der obige Azure CLI-Beispielausschnitt ruft einen Administratorschlüssel ab, sodass sie einfacher mit der Erkundung von APIs beginnen können, aber er sollte sorgfältig verwaltet werden.

Erstellen eines SearchClient

Zum Instanziieren von SearchClientbenötigen Sie den Endpunkt, den API-Schlüssel und den Indexnamen:

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

Erstellen eines Clients mithilfe der Azure Active Directory-Authentifizierung

Sie können auch eine , SearchIndexClientoder SearchIndexerClient mithilfe der SearchClientAAD-Authentifizierung (Azure Active Directory) erstellen. Ihrem Benutzer oder Dienstprinzipal muss die Rolle "Indexdatenleser durchsuchen" zugewiesen sein. Mit DefaultAzureCredential können Sie einen Dienst mithilfe einer verwalteten Identität oder eines Dienstprinzipals authentifizieren, sich als Entwickler authentifizieren, der an einer Anwendung arbeitet, und vieles mehr, ohne code zu ändern. Anweisungen zum Herstellen einer Verbindung mit Azure Cognitive Search mithilfe der rollenbasierten Zugriffssteuerung in Azure (Azure RBAC) finden Sie in der Dokumentation.

Bevor Sie oder DefaultAzureCredentialeinen beliebigen Anmeldeinformationstyp aus Azure.Identity verwenden können, müssen Sie zunächst das Azure.Identity-Paket installieren.

Um mit einer Client-ID und einem Geheimschlüssel zu verwenden DefaultAzureCredential , müssen Sie die AZURE_TENANT_IDUmgebungsvariablen , AZURE_CLIENT_IDund AZURE_CLIENT_SECRET festlegen. Alternativ können Sie diese Werte auch in Azure.Identity an die ClientSecretCredential übergeben.

Stellen Sie sicher, dass Sie den richtigen Namespace für DefaultAzureCredential am Anfang ihrer Quelldatei verwenden:

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)

Wichtige Begriffe

Ein Azure Cognitive Search-Dienst enthält einen oder mehrere Indizes, die eine dauerhafte Speicherung durchsuchbarer Daten in Form von JSON-Dokumenten ermöglichen. (Wenn Sie ganz neu in der Suche sind, können Sie eine sehr grobe Analogie zwischen Indizes und Datenbanktabellen herstellen.) Die Azure.Search.Documents-Clientbibliothek macht Vorgänge für diese Ressourcen über zwei Standard Clienttypen verfügbar.

Azure Cognitive Search bietet zwei leistungsstarke Features: Semantische Suche und Vektorsuche.

Die semantische Suche verbessert die Qualität der Suchergebnisse für textbasierte Abfragen. Durch Aktivieren der semantischen Suche in Ihrem Suchdienst können Sie die Relevanz von Suchergebnissen auf zwei Arten verbessern:

  • Es wendet die sekundäre Rangfolge auf das anfängliche Resultset an, wodurch die semantisch relevantesten Ergebnisse nach oben heraufgesetzt werden.
  • Es extrahiert und gibt Beschriftungen und Antworten in der Antwort zurück, die auf einer Suchseite angezeigt werden können, um die Sucherfahrung des Benutzers zu verbessern.

Weitere Informationen zur semantischen Suche finden Sie in der Dokumentation.

Die Vektorsuche ist eine Technik zum Abrufen von Informationen, die die Einschränkungen der herkömmlichen Schlüsselwort (keyword)-basierten Suche überwindet. Anstatt sich ausschließlich auf lexikalische Analysen und den Abgleich einzelner Abfragebegriffe zu verlassen, verwendet die Vektorsuche Machine Learning-Modelle, um die kontextbezogene Bedeutung von Wörtern und Ausdrücken zu erfassen. Es stellt Dokumente und Abfragen als Vektoren in einem hochdimensionalen Raum dar, der als Einbettung bezeichnet wird. Wenn Sie die Absicht hinter der Abfrage verstehen, kann die Vektorsuche relevantere Ergebnisse liefern, die den Anforderungen des Benutzers entsprechen, auch wenn die genauen Begriffe nicht im Dokument vorhanden sind. Darüber hinaus kann die Vektorsuche auf verschiedene Arten von Inhalten angewendet werden, einschließlich Bildern und Videos, nicht nur auf Text.

Informationen zum Indizieren von Vektorfeldern und zum Ausführen einer Vektorsuche finden Sie im Beispiel. Dieses Beispiel enthält detaillierte Anleitungen zur Indizierung von Vektorfeldern und veranschaulicht die Durchführung der Vektorsuche.

Darüber hinaus finden Sie ausführlichere Informationen zur Vektorsuche, einschließlich der Konzepte und der Verwendung, in der Dokumentation. Die Dokumentation enthält ausführliche Erläuterungen und Anleitungen zur Nutzung der Leistungsfähigkeit der Vektorsuche in Azure Cognitive Search.

Die Azure.Search.Documents Clientbibliothek (v1) ist ein brandneues Angebot für Python-Entwickler, die Suchtechnologien in ihren Anwendungen verwenden möchten. Es gibt eine ältere, voll ausgestattete Microsoft.Azure.Search Clientbibliothek (v10) mit vielen ähnlich aussehenden APIs. Achten Sie daher darauf, Verwirrung zu vermeiden, wenn Sie Onlineressourcen erkunden.

Beispiele

In den folgenden Beispielen wird ein einfaches Hotel-Dataset verwendet, das Sie aus dem Azure-Portal in Ihren eigenen Index importieren können. Dies sind nur einige der Grundlagen . Weitere Informationen finden Sie in unseren Beispielen.

Abfragen

Zunächst importieren wir unsere Namespaces.

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

Wir erstellen dann einen SearchClient , um auf unseren Suchindex für Hotels zuzugreifen.

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)

Suchen wir nach einem "Luxus"-Hotel.

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

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

Erstellen eines Index

Sie können verwenden SearchIndexClient , um einen Suchindex zu erstellen. Felder können mit praktischen SimpleField, SearchableFieldoder ComplexField Modellen definiert werden. Indizes können auch Vorschlagser, lexikalische Analysetools und vieles mehr definieren.

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)

Hinzufügen von Dokumenten zu Ihrem Index

Sie können Upload, Merge, MergeOrUploadund Delete mehrere Dokumente aus einem Index in einer einzelnen Batchanforderung ausführen. Es gibt einige besondere Regeln für die Zusammenführung , die sie beachten sollten.

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

Authentifizieren in einer nationalen Cloud

Um sich in einer nationalen Cloud zu authentifizieren, müssen Sie die folgenden Ergänzungen an Ihrer Clientkonfiguration vornehmen:

  • Legen Sie in AuthorityHost den Anmeldeinformationsoptionen oder über die Umgebungsvariable AZURE_AUTHORITY_HOST fest.
  • Legen Sie in audienceSearchClient, SearchIndexClientoder fest. 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")

Abrufen eines bestimmten Dokuments aus Ihrem Index

Zusätzlich zum Abfragen von Dokumenten mithilfe von Schlüsselwörtern und optionalen Filtern können Sie ein bestimmtes Dokument aus Ihrem Index abrufen, wenn Sie den Schlüssel bereits kennen. Sie können den Schlüssel z. B. aus einer Abfrage abrufen und weitere Informationen dazu anzeigen oder Ihren Kunden zu diesem Dokument navigieren.

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

Asynchrone APIs

Diese Bibliothek enthält eine vollständige asynchrone API. Um es verwenden zu können, müssen Sie zuerst einen asynchronen Transport installieren, z. B. aiohttp. Weitere Informationen finden Sie in der Dokumentation zu 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"]))

Problembehandlung

Allgemein

Der Azure Cognitive Search Client löst ausnahmen aus, die in Azure Core definiert sind.

Protokollierung

Diese Bibliothek verwendet die Standardprotokollbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine ausführliche Protokollierung auf der Ebene DEBUG, einschließlich Anforderungs-/Antworttexten und vollständiger Header, kann auf einem Client mit dem Schlüsselwortargument logging_enable aktiviert werden:

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)

Ebenso kann über logging_enable die ausführliche Protokollierung für einen einzelnen Vorgang aktiviert werden, auch wenn diese Funktion für den Client nicht aktiviert ist:

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

Nächste Schritte

Mitwirken

Ausführliche Informationen zum Erstellen, Testen und Mitwirken zu dieser Bibliothek finden Sie in unserem CONTRIBUTING.md Suchen .

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe

Aufrufe