Dela via

Azure Cognitive Search klientbibliotek för Python – version 11.4.0

  • Artikel

Azure Cognitive Search är en molnlösning för sökning som en tjänst som ger utvecklare API:er och verktyg för att lägga till en omfattande sökupplevelse för privat, heterogent innehåll i webb-, mobil- och företagsprogram.

Tjänsten Azure Cognitive Search passar bra för följande programscenarier:

  • Konsolidera olika innehållstyper till ett enda sökbart index. Om du vill fylla i ett index kan du skicka JSON-dokument som innehåller ditt innehåll, eller om dina data redan finns i Azure skapar du en indexerare som hämtar data automatiskt.
  • Koppla kompetensuppsättningar till en indexerare för att skapa sökbart innehåll från bilder och stora textdokument. En kompetensuppsättning utnyttjar AI från Cognitive Services för inbyggd OCR, entitetsigenkänning, extrahering av nyckelfraser, språkidentifiering, textöversättning och attitydanalys. Du kan också lägga till anpassade kunskaper för att integrera extern bearbetning av ditt innehåll under datainmatning.
  • I ett sökklientprogram implementerar du frågelogik och användarupplevelser som liknar kommersiella webbsökmotorer.

Använd klientbiblioteket Azure.Search.Documents för att:

  • Skicka frågor för enkla och avancerade frågeformulär som innehåller fuzzy-sökning, jokerteckensökning, reguljära uttryck.
  • Implementera filtrerade frågor för aspektbaserad navigering, geospatial sökning eller för att begränsa resultat baserat på filterkriterier.
  • Skapa och hantera sökindex.
  • Ladda upp och uppdatera dokument i sökindexet.
  • Skapa och hantera indexerare som hämtar data från Azure till ett index.
  • Skapa och hantera kompetensuppsättningar som lägger till AI-berikning för datainmatning.
  • Skapa och hantera analysverktyg för avancerad textanalys eller flerspråkigt innehåll.
  • Optimera resultaten genom bedömningsprofiler för att ta hänsyn till affärslogik eller aktualitet.

| KällkodPaket (PyPI) | Paket (Conda) | API-referensdokumentation | Produktdokumentation | Prover

Komma igång

Installera paketet

Installera Azure Cognitive Search-klientbiblioteket för Python med pip:

pip install azure-search-documents

Förutsättningar

Om du vill skapa en ny söktjänst kan du använda Azure Portal, Azure PowerShell eller Azure CLI.

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

Mer information om tillgängliga alternativ finns i Välja prisnivå .

Autentisera klienten

För att interagera med tjänsten Search måste du skapa en instans av lämplig klientklass: SearchClient för att söka i indexerade dokument, SearchIndexClient för att hantera index eller SearchIndexerClient för att crawla datakällor och läsa in sökdokument i ett index. För att skapa en instans av ett klientobjekt behöver du en slutpunkt och en API-nyckel. Mer information om vilka autentiseringsmetoder som stöds med tjänsten Search finns i dokumentationen.

Hämta en API-nyckel

Du kan hämta slutpunkten och en API-nyckel från tjänsten Search i Azure-portalen. Anvisningar om hur du hämtar en API-nyckel finns i dokumentationen .

Du kan också använda följande Azure CLI-kommando för att hämta API-nyckeln från tjänsten Search:

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

Det finns två typer av nycklar som används för att komma åt söktjänsten: administratörsnycklar (läs-och-skrivbehörighet) och frågor(skrivskyddade). Det är viktigt att begränsa åtkomst och åtgärder i klientappar för att skydda söktillgångarna i din tjänst. Använd alltid en frågenyckel i stället för en administratörsnyckel för frågor som kommer från en klientapp.

Obs! Azure CLI-exempelfragmentet ovan hämtar en administratörsnyckel så att det är enklare att komma igång med att utforska API:er, men det bör hanteras noggrant.

Skapa en SearchClient

För att skapa en instans av SearchClientbehöver du slutpunkten, API-nyckeln och indexnamnet:

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

Skapa en klient med Azure Active Directory-autentisering

Du kan också skapa , SearchClientSearchIndexClienteller SearchIndexerClient använda Azure Active Directory-autentisering (AAD). Användaren eller tjänstens huvudnamn måste tilldelas rollen "Dataläsare för sökindex". Med hjälp av DefaultAzureCredential kan du autentisera en tjänst med hjälp av hanterad identitet eller ett huvudnamn för tjänsten, autentisera som utvecklare som arbetar med ett program och mer allt utan att ändra kod. I dokumentationen finns anvisningar om hur du ansluter till Azure Cognitive Search med rollbaserad åtkomstkontroll i Azure (Azure RBAC).

Innan du kan använda DefaultAzureCredential, eller någon typ av autentiseringsuppgifter från Azure.Identity, måste du först installera Azure.Identity-paketet.

Om du vill använda DefaultAzureCredential med ett klient-ID och en hemlighet måste du ange AZURE_TENANT_IDmiljövariablerna , AZURE_CLIENT_IDoch AZURE_CLIENT_SECRET . Alternativt kan du skicka dessa värden till ClientSecretCredential även i Azure.Identity.

Se till att du använder rätt namnområde för DefaultAzureCredential överst i källfilen:

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)

Viktiga begrepp

En Azure Cognitive Search-tjänst innehåller ett eller flera index som ger beständig lagring av sökbara data i form av JSON-dokument. (Om du är helt ny för sökning kan du göra en mycket grov analogi mellan index och databastabeller.) Klientbiblioteket Azure.Search.Documents exponerar åtgärder på dessa resurser via två huvudsakliga klienttyper.

Azure Cognitive Search innehåller två kraftfulla funktioner: Semantisk sökning och vektorsökning.

Semantisk sökning förbättrar kvaliteten på sökresultaten för textbaserade frågor. Genom att aktivera semantisk sökning i söktjänsten kan du förbättra relevansen för sökresultaten på två sätt:

  • Den tillämpar sekundär rangordning på den första resultatuppsättningen och höjer de mest semantiskt relevanta resultaten till toppen.
  • Den extraherar och returnerar undertexter och svar i svaret, som kan visas på en söksida för att förbättra användarens sökupplevelse.

Mer information om semantisk sökning finns i dokumentationen.

Vektorsökning är en informationshämtningsteknik som övervinner begränsningarna för traditionell nyckelordsbaserad sökning. I stället för att enbart förlita sig på lexikal analys och matchande enskilda frågetermer använder Vector Search maskininlärningsmodeller för att fånga den sammanhangsbaserade innebörden av ord och fraser. Den representerar dokument och frågor som vektorer i ett högdimensionellt utrymme som kallas inbäddning. Genom att förstå avsikten bakom frågan kan Vector Search leverera mer relevanta resultat som överensstämmer med användarens krav, även om de exakta termerna inte finns i dokumentet. Dessutom kan vektorsökning tillämpas på olika typer av innehåll, inklusive bilder och videor, inte bara text.

Om du vill lära dig hur du indexar vektorfält och utför vektorsökning kan du referera till exemplet. Det här exemplet ger detaljerad vägledning om indexering av vektorfält och visar hur du utför vektorsökning.

Mer omfattande information om vektorsökning, inklusive begrepp och användning, finns i dokumentationen. Dokumentationen innehåller detaljerade förklaringar och vägledning om hur du använder kraften i vektorsökning i Azure Cognitive Search.

Klientbiblioteket Azure.Search.Documents (v1) är ett helt nytt erbjudande för Python-utvecklare som vill använda sökteknik i sina program. Det finns ett äldre, fullständigt klientbibliotek Microsoft.Azure.Search (v10) med många liknande API:er, så var noga med att undvika förvirring när du utforskar onlineresurser.

Exempel

I följande exempel används en enkel hoteldatauppsättning som du kan importera till ditt eget index från Azure Portal. Dessa är bara några av grunderna - kolla in våra exempel för mycket mer.

Fråga

Vi börjar med att importera våra namnområden.

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

Sedan skapar vi en SearchClient för att få åtkomst till vårt sökindex för hotell.

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)

Låt oss söka efter ett "lyxigt" hotell.

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

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

Skapa ett index

Du kan använda SearchIndexClient för att skapa ett sökindex. Fält kan definieras med hjälp av praktiska SimpleFieldmodeller , SearchableFieldeller ComplexField modeller. Index kan också definiera förslagstagare, lexikala analysverktyg med mera.

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)

Lägga till dokument i ditt index

Du kan Upload, Merge, MergeOrUploadoch Delete flera dokument från ett index i en enda batchförfrågan. Det finns några särskilda regler för sammanslagning att känna till.

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

Autentisera i ett nationellt moln

Om du vill autentisera i ett nationellt moln måste du göra följande tillägg till klientkonfigurationen:

  • AuthorityHost Ange i alternativen för autentiseringsuppgifter eller via AZURE_AUTHORITY_HOST miljövariabeln
  • audience Ange i SearchClient, SearchIndexClientellerSearchIndexerClient
# 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")

Hämta ett specifikt dokument från ditt index

Förutom att fråga efter dokument med hjälp av nyckelord och valfria filter kan du hämta ett specifikt dokument från ditt index om du redan känner till nyckeln. Du kan till exempel hämta nyckeln från en fråga och vill visa mer information om den eller navigera kunden till dokumentet.

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

Asynkrona API:er

Det här biblioteket innehåller ett fullständigt asynkront API. Om du vill använda den måste du först installera en asynkron transport, till exempel aiohttp. Mer information finns i azure-core-dokumentationen .

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

Felsökning

Allmänt

Den Azure Cognitive Search klienten genererar undantag som definierats i Azure Core.

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade rubriker, kan aktiveras på en klient med nyckelordsargumentet 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)

logging_enable På samma sätt kan aktivera detaljerad loggning för en enda åtgärd, även om den inte är aktiverad för klienten:

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

Nästa steg

Bidra

Mer information om hur du skapar, testar och bidrar till det här biblioteket finns i vår CONTRIBUTING.md search.

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns i cla.microsoft.com.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.

Visningar

Visningar