Azure Cognitive Search Python ügyfélkódtára – 11.4.0-s verzió

  • Cikk

A Azure Cognitive Search egy szolgáltatásként nyújtott felhőalapú keresési megoldás, amely a fejlesztők API-jait és eszközeit kínálja a webes, mobil- és nagyvállalati alkalmazások privát, heterogén tartalmaihoz való gazdag keresési élmény hozzáadásához.

A Azure Cognitive Search szolgáltatás a következő alkalmazási helyzetekben használható:

  • A különböző tartalomtípusok egyetlen kereshető indexbe való összevonása. Az index feltöltéséhez leküldheti a tartalmat tartalmazó JSON-dokumentumokat, vagy ha az adatai már az Azure-ban vannak, hozzon létre egy indexelőt az adatok automatikus lekéréséhez.
  • Csatolja a képességcsoportokat egy indexelőhöz, hogy kereshető tartalmat hozzon létre képekből és nagyméretű szöveges dokumentumokból. A képességcsoport a Cognitive Services mesterséges intelligenciát használ a beépített OCR-hez, az entitásfelismeréshez, a kulcskifejezések kinyeréséhez, a nyelvfelismeréshez, a szövegfordításhoz és a hangulatelemzéshez. Egyéni képességeket is hozzáadhat a tartalom külső feldolgozásának integrálásához az adatbetöltés során.
  • A keresőügyfél-alkalmazásokban a kereskedelmi webes keresőmotorokhoz hasonló lekérdezési logikát és felhasználói élményeket valósíthat meg.

Az Azure.Search.Documents ügyfélkódtár használatával:

  • Lekérdezések küldése egyszerű és speciális lekérdezési űrlapokhoz, amelyek közé tartozik a homályos keresés, a helyettesítő karakterek keresése és a reguláris kifejezések.
  • Szűrt lekérdezéseket implementálhat a részletes navigációhoz, a térinformatikai kereséshez, vagy szűkítheti a találatokat a szűrési feltételek alapján.
  • Keresési indexek létrehozása és kezelése.
  • Dokumentumok feltöltése és frissítése a keresési indexben.
  • Olyan indexelők létrehozása és kezelése, amelyek adatokat kérnek le az Azure-ból egy indexbe.
  • Olyan képességcsoportokat hozhat létre és kezelhet, amelyek AI-bővítést adnak az adatbetöltéshez.
  • Elemzők létrehozása és kezelése speciális szövegelemzéshez vagy többnyelvű tartalomhoz.
  • Optimalizálja az eredményeket pontozási profilok segítségével az üzleti logika vagy a frissesség figyelembe vételéhez.

Forráskód | Csomag (PyPI) | Csomag (Conda) | API-referenciadokumentáció | Termékdokumentáció | Minták

Első lépések

A csomag telepítése

Telepítse a Pythonhoz készült Azure Cognitive Search ügyfélkódtárat a pip használatával:

pip install azure-search-documents

Előfeltételek

Új keresési szolgáltatás létrehozásához használhatja a Azure Portal, Azure PowerShell vagy az Azure CLI-t.

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

Az elérhető lehetőségekről további információt a tarifacsomag kiválasztása című témakörben talál.

Az ügyfél hitelesítése

A Search szolgáltatás használatához létre kell hoznia egy példányt a megfelelő ügyfélosztályból: SearchClient indexelt dokumentumok kereséséhez, SearchIndexClient indexek kezeléséhez, SearchIndexerClient adatforrások bejárásához és keresési dokumentumok indexbe való betöltéséhez. Egy ügyfélobjektum példányosításához egy végpontra és egy API-kulcsra lesz szüksége. A Search szolgáltatás támogatott hitelesítési megközelítéseivel kapcsolatos további információkért tekintse meg a dokumentációt.

API-kulcs lekérése

A végpontot és egy API-kulcsot az Azure Portal Search szolgáltatás érheti el. Az API-kulcs beszerzésére vonatkozó útmutatásért tekintse meg a dokumentációt .

Másik lehetőségként az alábbi Azure CLI-paranccsal is lekérheti az API-kulcsot a Search szolgáltatás:

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

A keresési szolgáltatás eléréséhez kétféle kulcs használható: rendszergazdai (írási-olvasási) és lekérdezési(csak olvasási) kulcsok. Az ügyfélalkalmazások hozzáférésének és műveleteinek korlátozása elengedhetetlen a szolgáltatás keresési eszközeinek védelméhez. Minden ügyfélalkalmazásból származó lekérdezéshez mindig használjon lekérdezési kulcsot rendszergazdai kulcs helyett.

Megjegyzés: A fenti Azure CLI-kódrészlet egy rendszergazdai kulcsot kér le, így egyszerűbb az API-k megismerésének megkezdése, de körültekintően kell kezelni.

SearchClient létrehozása

A példányosításhoz szüksége lesz a SearchClientvégpontra, az API-kulcsra és az index nevére:

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

Ügyfél létrehozása Azure Active Directory-hitelesítéssel

Azure Active Directory-hitelesítést (AAD) is létrehozhatSearchClientSearchIndexClientSearchIndexerClient. A felhasználónak vagy a szolgáltatásnévnek hozzá kell rendelnie a "Keresési index adatolvasója" szerepkört. A DefaultAzureCredential használatával felügyelt identitással vagy szolgáltatásnévvel hitelesíthet egy szolgáltatást, alkalmazáson dolgozó fejlesztőként hitelesíthet, és egyebek között kód módosítása nélkül is. Az Azure-beli szerepköralapú hozzáférés-vezérlés (Azure RBAC) használatával történő Azure Cognitive Search csatlakozással kapcsolatos útmutatásért tekintse meg a dokumentációt.

Ahhoz, hogy használni tudja a DefaultAzureCredential, vagy bármilyen hitelesítő adattípust az Azure.Identityből, először telepítenie kell az Azure.Identity csomagot.

Az ügyfélazonosítóval és titkos kóddal való használathoz DefaultAzureCredential be kell állítania a , AZURE_CLIENT_IDa és AZURE_CLIENT_SECRET a AZURE_TENANT_IDkörnyezeti változókat, vagy átadhatja ezeket az értékeket az ClientSecretCredential Azure.Identityben is.

Győződjön meg arról, hogy a megfelelő névteret DefaultAzureCredential használja a forrásfájl tetején:

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)

Fő fogalmak

A Azure Cognitive Search szolgáltatás egy vagy több olyan indexet tartalmaz, amely JSON-dokumentumok formájában biztosítja a kereshető adatok állandó tárolását. (Ha még csak most ismerkedik a kereséssel, nagyon durva analógiát készíthet az indexek és az adatbázistáblák között.) Az Azure.Search.Documents ügyfélkódtár két fő ügyféltípuson keresztül teszi elérhetővé ezen erőforrások műveleteit.

Azure Cognitive Search két hatékony funkciót kínál: Szemantikus keresés és Vektorkeresés.

A szemantikai keresés javítja a szöveges lekérdezések keresési eredményeinek minőségét. A szemantikai keresés keresési szolgáltatásban való engedélyezésével kétféleképpen javíthatja a keresési eredmények relevanciáját:

  • A másodlagos rangsorolást alkalmazza a kezdeti eredményhalmazra, és a legszembetűnőbb eredményeket jeleníti meg a legfelső helyen.
  • Feliratokat és válaszokat nyer ki és ad vissza a válaszban, amelyek megjeleníthetők a keresési oldalon a felhasználó keresési élményének javítása érdekében.

A szemantikai kereséssel kapcsolatos további információkért tekintse meg a dokumentációt.

A Vector Search egy információlekérési technika, amely leküzdi a hagyományos kulcsszóalapú keresés korlátait. Ahelyett, hogy kizárólag lexikális elemzésre és egyező lekérdezési kifejezésekre támaszkodna, a Vector Search gépi tanulási modelleket használ a szavak és kifejezések környezetfüggő jelentésének rögzítésére. A dokumentumokat és lekérdezéseket vektorként jelöli egy beágyazás nevű, nagy dimenziójú térben. A lekérdezés mögötti szándék megértésével a Vector Search relevánsabb eredményeket jeleníthet meg, amelyek megfelelnek a felhasználó követelményeinek, még akkor is, ha a pontos kifejezések nem szerepelnek a dokumentumban. A Vektorkeresés emellett különböző típusú tartalmakra is alkalmazható, beleértve a képeket és videókat, nem csak a szöveget.

Ha meg szeretné tudni, hogyan indexelheti a vektormezőket, és hogyan végezhet vektorkeresést, tekintse meg a mintát. Ez a minta részletes útmutatást nyújt a vektormezők indexeléséhez, és bemutatja, hogyan végezhet vektorkeresést.

A Vector Search szolgáltatással kapcsolatos átfogóbb információkért, beleértve a fogalmakat és a használatot is, tekintse meg a dokumentációt. A dokumentáció részletes magyarázatokat és útmutatást nyújt a Vector Search Azure Cognitive Search nyújtotta lehetőségek kihasználásához.

Az Azure.Search.Documents ügyfélkódtár (v1) egy teljesen új ajánlat a Python-fejlesztők számára, akik keresési technológiát szeretnének használni az alkalmazásaikban. Van egy régebbi, teljes körűen kiemelt Microsoft.Azure.Search ügyfélkódtár (v10), amely számos hasonló megjelenésű API-val rendelkezik, ezért kérjük, ügyeljen arra, hogy elkerülje a félreértéseket az online erőforrások felfedezése során.

Példák

Az alábbi példák egy egyszerű Hotel adatkészletet használnak, amelyet importálhat a saját indexébe a Azure Portal. Ezek csak néhány alapismeretek – további információért tekintse meg a mintákat.

Lekérdezés

Kezdjük a névterek importálásával.

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

Ezután létrehozunk egy értéket SearchClient a szálloda keresési indexének eléréséhez.

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)

Keressünk egy "luxus" szállodát.

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

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

Index létrehozása

A használatával SearchIndexClient keresési indexet hozhat létre. A mezők kényelmes SimpleField, vagy SearchableFieldComplexField modellek használatával határozhatók meg. Az indexek javaslattevőket, lexikális elemzőket és egyebeket is definiálhatnak.

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)

Dokumentumok hozzáadása az indexhez

Egyetlen kötegelt kérelemben egy indexből több dokumentumot is létrehozhatUploadMergeOrUploadMergeDelete. Az egyesítésnek van néhány speciális szabálya , amelyeket figyelembe kell venni.

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

Hitelesítés nemzeti felhőben

A nemzeti felhőben való hitelesítéshez a következő kiegészítéseket kell elvégeznie az ügyfélkonfigurációhoz:

  • Adja meg a AuthorityHost értéket a hitelesítőadat-beállításokban vagy a AZURE_AUTHORITY_HOST környezeti változón keresztül
  • Állítsa be a következőt: audienceSearchClient, SearchIndexClient, vagy 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")

Adott dokumentum lekérése az indexből

A kulcsszavakat és választható szűrőket használó dokumentumok lekérdezése mellett egy adott dokumentumot is lekérhet az indexből, ha már ismeri a kulcsot. Lekérheti például a kulcsot egy lekérdezésből, és további információkat szeretne megjeleníteni róla, vagy az ügyfelet a dokumentumba navigálhatja.

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

Aszinkron API-k

Ez a kódtár egy teljes aszinkron API-t tartalmaz. A használatához először telepítenie kell egy aszinkron átvitelt, például az aiohttp-t. További információért tekintse meg az azure-core dokumentációját .

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

Hibaelhárítás

Általános kérdések

Az Azure Cognitive Search-ügyfél kivételeket hoz létre az Azure Core-ban.

Naplózás

Ez a kódtár a szabványos naplózási kódtárat használja a naplózáshoz. A HTTP-munkamenetekkel (URL-címekkel, fejlécekkel stb.) kapcsolatos alapvető információkat az INFO szinten naplózza a rendszer.

A hibakeresési szint részletes naplózása, beleértve a kérés-/választörzseket és a nem felügyelt fejléceket, engedélyezhető a logging_enable kulcsszóargumentummal rendelkező ügyfélen:

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)

Hasonlóképpen logging_enable engedélyezheti a részletes naplózást egyetlen művelethez, még akkor is, ha nincs engedélyezve az ügyfél számára:

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

Következő lépések

Közreműködés

A kódtár létrehozásával, teszteléssel és közreműködéssel kapcsolatos részletekért tekintse meg a Keresési CONTRIBUTING.md .

A projektben szívesen fogadjuk a hozzájárulásokat és a javaslatokat. A legtöbb hozzájáruláshoz el kell fogadnia egy Közreműködői licencszerződést (CLA-t), amelyben kijelenti, hogy jogosult arra, hogy ránk ruházza hozzájárulása felhasználási jogát, és ezt ténylegesen meg is teszi. Részletekért látogasson el cla.microsoft.com.

A projekt a Microsoft nyílt forráskódú projekteket szabályozó etikai kódexe, a Microsoft Open Source Code of Conduct hatálya alá esik. További információkért lásd a viselkedési szabályzattal kapcsolatos gyakori kérdéseket , vagy vegye fel a kapcsolatot opencode@microsoft.com az esetleges további kérdésekkel vagy megjegyzésekkel.

Megjelenések

Megjelenések