Azure Cognitive Search Python ügyfélkódtára – 11.4.0-s verzió
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
- A csomag használatához Python 3.7 vagy újabb verzió szükséges.
- A csomag használatához Azure-előfizetésre és Azure Cognitive Search szolgáltatásra van szüksége.
Ú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 SearchClient
vé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étrehozhatSearchClient
SearchIndexClient
SearchIndexerClient
. 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_ID
a és AZURE_CLIENT_SECRET
a AZURE_TENANT_ID
kö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.
SearchClient
segít a következőkben:- Keresés az indexelt dokumentumokban gazdag lekérdezések és hatékony adatformázás használatával
- Részben beírt keresési kifejezések automatikus kiegészítése az index dokumentumai alapján
- A dokumentumokban a legvalószínűbben egyező szöveg felhasználói típusként való ajánlása
- Dokumentumok hozzáadása, frissítése vagy törlése indexből
SearchIndexClient
lehetővé teszi a következőket:- Keresési index létrehozása, törlése, frissítése vagy konfigurálása
- Egyéni szinonimatérképek deklarálása lekérdezések kibontásához vagy átírásához
SearchServiceClient
A legtöbb funkció még nem érhető el az aktuális előzetes verzióban
SearchIndexerClient
lehetővé teszi a következőket:
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
- Index létrehozása
- Dokumentumok hozzáadása az indexhez
- Adott dokumentum lekérése az indexből
- Async API-k
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 SearchableField
ComplexField
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étrehozhatUpload
MergeOrUpload
Merge
Delete
. 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 aAZURE_AUTHORITY_HOST
környezeti változón keresztül - Állítsa be a következőt:
audience
SearchClient
,SearchIndexClient
, vagySearchIndexerClient
# 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
- Lépjen tovább az Azure.Search.Documents és a https://github.com/Azure/azure-sdk-for-python/blob/azure-search-documents_11.4.0/sdk/search/azure-search-documents/samples
- Bemutató vagy részletes bemutató videó megtekintése
- További információ a Azure Cognitive Search szolgáltatásról
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.
Kapcsolódó projektek
Azure SDK for Python