Azure Cognitive Search clientbibliotheek voor Python - versie 11.4.0

  • Artikel

Azure Cognitive Search is een search-as-a-service-cloudoplossing die ontwikkelaars API's en hulpprogramma's biedt voor het toevoegen van een uitgebreide zoekervaring voor persoonlijke, heterogene inhoud in web-, mobiele en bedrijfstoepassingen.

De Azure Cognitive Search-service is geschikt voor de volgende toepassingsscenario's:

  • Voeg verschillende inhoudstypen samen in één doorzoekbare index. Als u een index wilt vullen, kunt u JSON-documenten met uw inhoud pushen. Als uw gegevens zich al in Azure bevinden, kunt u een indexeerfunctie maken om automatisch gegevens op te halen.
  • Koppel vaardighedensets aan een indexeerfunctie om doorzoekbare inhoud te maken van afbeeldingen en grote tekstdocumenten. Een vaardighedenset maakt gebruik van AI van Cognitive Services voor ingebouwde OCR, entiteitsherkenning, sleuteltermextractie, taaldetectie, tekstomzetting en sentimentanalyse. U kunt ook aangepaste vaardigheden toevoegen om externe verwerking van uw inhoud tijdens gegevensopname te integreren.
  • Implementeer in een zoekclienttoepassing querylogica en gebruikerservaringen die vergelijkbaar zijn met commerciële webzoekprogramma's.

Gebruik de clientbibliotheek Azure.Search.Documents om het volgende te doen:

  • Verzend query's voor eenvoudige en geavanceerde queryformulieren met fuzzy zoekopdrachten, zoeken met jokertekens en reguliere expressies.
  • Implementeer gefilterde query's voor facetnavigatie, georuimtelijke zoekopdrachten of om resultaten te beperken op basis van filtercriteria.
  • Zoekindexen maken en beheren.
  • Documenten uploaden en bijwerken in de zoekindex.
  • Indexeerfuncties maken en beheren die gegevens uit Azure in een index ophalen.
  • Vaardighedensets maken en beheren die AI-verrijking toevoegen aan gegevensopname.
  • Analyseprogramma's maken en beheren voor geavanceerde tekstanalyse of meertalige inhoud.
  • Optimaliseer resultaten via scoreprofielen om rekening te houden met bedrijfslogica of nieuwheid.

Broncode | Pakket (PyPI) | Pakket (Conda) | API-referentiedocumentatie | Productdocumentatie | Monsters

Aan de slag

Het pakket installeren

Installeer de Azure Cognitive Search-clientbibliotheek voor Python met pip:

pip install azure-search-documents

Vereisten

Als u een nieuwe zoekservice wilt maken, kunt u de Azure Portal, Azure PowerShell of de Azure CLI gebruiken.

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

Zie Een prijscategorie kiezen voor meer informatie over beschikbare opties.

De client verifiëren

Als u wilt communiceren met de Search-service, moet u een exemplaar van de juiste clientklasse maken: SearchClient voor het zoeken naar geïndexeerde documenten, SearchIndexClient voor het beheren van indexen of SearchIndexerClient voor het verkennen van gegevensbronnen en het laden van zoekdocumenten in een index. Als u een clientobject wilt instantiëren, hebt u een eindpunt en een API-sleutel nodig. Raadpleeg de documentatie voor meer informatie over ondersteunde verificatiemethoden met de Search-service.

Een API-sleutel ophalen

U kunt het eindpunt en een API-sleutel ophalen uit de Search-service in Azure Portal. Raadpleeg de documentatie voor instructies over het verkrijgen van een API-sleutel.

U kunt ook de volgende Azure CLI-opdracht gebruiken om de API-sleutel op te halen uit de Search-service:

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

Er zijn twee typen sleutels die worden gebruikt voor toegang tot uw zoekservice: beheerderssleutels(lezen-schrijven) en querysleutels(alleen-lezen). Het beperken van toegang en bewerkingen in client-apps is essentieel voor het beveiligen van de zoekassets in uw service. Gebruik altijd een querysleutel in plaats van een beheerderssleutel voor elke query die afkomstig is van een client-app.

Opmerking: met het bovenstaande voorbeeld van een Azure CLI-fragment wordt een beheersleutel opgehaald, zodat u gemakkelijker aan de slag kunt met het verkennen van API's, maar het moet zorgvuldig worden beheerd.

Een SearchClient maken

Als u de SearchClientwilt instantiëren, hebt u het eindpunt, de API-sleutel en de indexnaam nodig:

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

Een client maken met behulp van Azure Active Directory-verificatie

U kunt ook een SearchClient, SearchIndexClientof SearchIndexerClient maken met behulp van AAD-verificatie (Azure Active Directory). Aan uw gebruiker of service-principal moet de rol Lezer van zoekindexgegevens worden toegewezen. Met behulp van de DefaultAzureCredential kunt u een service verifiëren met behulp van een beheerde identiteit of een service-principal, verifiëren als ontwikkelaar die aan een toepassing werkt en meer zonder code te wijzigen. Raadpleeg de documentatie voor instructies over het maken van verbinding met Azure Cognitive Search met behulp van op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC).

Voordat u de DefaultAzureCredential, of een referentietype van Azure.Identity kunt gebruiken, moet u eerst het pakket Azure.Identity installeren.

Als u wilt gebruiken DefaultAzureCredential met een client-id en -geheim, moet u de AZURE_TENANT_IDomgevingsvariabelen , AZURE_CLIENT_IDen AZURE_CLIENT_SECRET instellen. U kunt deze waarden ook doorgeven aan de ClientSecretCredential ook in Azure.Identity.

Zorg ervoor dat u bovenaan het bronbestand de juiste naamruimte gebruikt:DefaultAzureCredential

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)

Belangrijkste concepten

Een Azure Cognitive Search-service bevat een of meer indexen die permanente opslag van doorzoekbare gegevens bieden in de vorm van JSON-documenten. (Als u nog geen ervaring hebt met zoeken, kunt u een zeer ruwe analogie maken tussen indexen en databasetabellen.) De azure.Search.Documents-clientbibliotheek maakt bewerkingen op deze resources beschikbaar via twee hoofdclienttypen.

Azure Cognitive Search biedt twee krachtige functies: Semantic Search en Vector Search.

Semantic Search verbetert de kwaliteit van zoekresultaten voor op tekst gebaseerde query's. Door Semantic Search in te schakelen in uw zoekservice, kunt u de relevantie van zoekresultaten op twee manieren verbeteren:

  • Het past secundaire classificatie toe op de eerste resultatenset, waardoor de meest semantisch relevante resultaten naar de top worden gepromoot.
  • Het extraheert en retourneert bijschriften en antwoorden in het antwoord, die kunnen worden weergegeven op een zoekpagina om de zoekervaring van de gebruiker te verbeteren.

Raadpleeg de documentatie voor meer informatie over Semantic Search.

Vector Search is een techniek voor het ophalen van informatie die de beperkingen van traditionele zoekopdrachten op basis van trefwoorden overwint. In plaats van alleen te vertrouwen op lexicale analyse en overeenkomende afzonderlijke querytermen, maakt Vector Search gebruik van machine learning-modellen om de contextuele betekenis van woorden en woordgroepen vast te leggen. Het vertegenwoordigt documenten en query's als vectoren in een hoogdimensionale ruimte die een insluiting wordt genoemd. Door de intentie achter de query te begrijpen, kan Vector Search relevantere resultaten leveren die overeenkomen met de vereisten van de gebruiker, zelfs als de exacte termen niet aanwezig zijn in het document. Bovendien kan Vector Search worden toegepast op verschillende soorten inhoud, waaronder afbeeldingen en video's, niet alleen tekst.

Raadpleeg het voorbeeld voor meer informatie over het indexeren van vectorvelden en het uitvoeren van vectorzoekopdrachten. Dit voorbeeld biedt gedetailleerde richtlijnen voor het indexeren van vectorvelden en laat zien hoe u vectorzoekopdrachten uitvoert.

Daarnaast kunt u de documentatie raadplegen voor uitgebreidere informatie over Vector Search, inclusief de concepten en het gebruik ervan. De documentatie biedt uitgebreide uitleg en richtlijnen voor het gebruik van de kracht van Vector Search in Azure Cognitive Search.

De Azure.Search.Documents clientbibliotheek (v1) is een gloednieuw aanbod voor Python-ontwikkelaars die zoektechnologie in hun toepassingen willen gebruiken. Er is een oudere, volledig functionele Microsoft.Azure.Search clientbibliotheek (v10) met veel vergelijkbare API's, dus wees voorzichtig om verwarring te voorkomen bij het verkennen van onlinebronnen.

Voorbeelden

In de volgende voorbeelden wordt een eenvoudige hotelgegevensset gebruikt die u vanuit de Azure Portal in uw eigen index kunt importeren. Dit zijn slechts enkele van de basisprincipes. Bekijk onze voorbeelden voor nog veel meer.

Uitvoeren van query's

Laten we beginnen met het importeren van onze naamruimten.

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

Vervolgens maken we een SearchClient om toegang te krijgen tot onze zoekindex voor hotels.

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)

Laten we zoeken naar een "luxe" hotel.

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

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

Een index maken

U kunt de SearchIndexClient gebruiken om een zoekindex te maken. Velden kunnen worden gedefinieerd met behulp van handige SimpleField, SearchableFieldof ComplexField -modellen. Indexen kunnen ook suggesties, lexicale analysefuncties en meer definiëren.

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)

Documenten toevoegen aan uw index

U kunt Upload, Merge, MergeOrUploaden Delete meerdere documenten uit een index in één batchaanvraag. Er zijn enkele speciale regels voor samenvoegen om rekening mee te houden.

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

Verifiëren in een nationale cloud

Als u zich wilt verifiëren in een nationale cloud, moet u de volgende toevoegingen aan uw clientconfiguratie aanbrengen:

  • Stel de AuthorityHost in de referentieopties of via de AZURE_AUTHORITY_HOST omgevingsvariabele in
  • Stel de audience in SearchClient, SearchIndexClientof in 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")

Een specifiek document ophalen uit de index

Naast het uitvoeren van query's op documenten met trefwoorden en optionele filters, kunt u een specifiek document uit uw index ophalen als u de sleutel al kent. U kunt de sleutel bijvoorbeeld ophalen uit een query en er meer informatie over weergeven of uw klant naar dat document navigeren.

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 API's

Deze bibliotheek bevat een volledige asynchrone API. Als u deze wilt gebruiken, moet u eerst een asynchroon transport installeren, zoals aiohttp. Zie azure-core-documentatie voor meer informatie.

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

Problemen oplossen

Algemeen

De Azure Cognitive Search-client genereert uitzonderingen die zijn gedefinieerd in Azure Core.

Logboekregistratie

Deze bibliotheek gebruikt de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op DEBUG-niveau met aanvraag/antwoord-body's en niet-geredigeerde headers, kan worden ingeschakeld op een client met het sleutelwoordargument 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)

Op dezelfde manier kan logging_enable logboekregistratie voor één bewerking inschakelen, zelfs wanneer dit niet is ingeschakeld voor de client:

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

Volgende stappen

Bijdragen

Zie onze CONTRIBUTING.md zoeken voor meer informatie over het bouwen, testen en bijdragen aan deze bibliotheek.

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar cla.microsoft.com voor meer informatie.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Weergaven

Weergaven