Sdílet prostřednictvím

Azure Cognitive Search klientské knihovny pro Python – verze 11.4.0

  • Článek

Azure Cognitive Search je cloudové řešení vyhledávání jako služby, které vývojářům poskytuje rozhraní API a nástroje pro přidání bohatého vyhledávacího prostředí prostřednictvím soukromého heterogenního obsahu ve webových, mobilních a podnikových aplikacích.

Služba Azure Cognitive Search je vhodná pro následující scénáře aplikací:

  • Sloučení různých typů obsahu do jednoho prohledávatelného indexu Pokud chcete naplnit index, můžete odeslat dokumenty JSON, které obsahují váš obsah, nebo pokud už jsou vaše data v Azure, vytvořit indexer pro automatické načítání dat.
  • Připojte sady dovedností k indexeru a vytvořte prohledávatelný obsah z obrázků a velkých textových dokumentů. Sada dovedností využívá AI ze služeb Cognitive Services k integrovanému rozpoznávání OCR, rozpoznávání entit, extrakci klíčových frází, rozpoznávání jazyka, překladu textu a analýze mínění. Můžete také přidat vlastní dovednosti pro integraci externího zpracování obsahu během příjmu dat.
  • Ve vyhledávací klientské aplikaci implementujte logiku dotazů a uživatelská prostředí podobná komerčním webovým vyhledávacím webům.

Klientská knihovna Azure.Search.Documents slouží k:

  • Odesílejte dotazy pro jednoduché a pokročilé formuláře dotazů, které zahrnují přibližné vyhledávání, vyhledávání se zástupným znakem a regulární výrazy.
  • Implementujte filtrované dotazy pro fasetovou navigaci, geoprostorové vyhledávání nebo zúžení výsledků na základě kritérií filtru.
  • Vytváření a správa indexů vyhledávání
  • Nahrajte a aktualizujte dokumenty ve vyhledávacím indexu.
  • Vytvořte a spravujte indexery, které přetahují data z Azure do indexu.
  • Vytvářejte a spravujte sady dovedností, které přidávají rozšíření AI k příjmu dat.
  • Vytváření a správa analyzátorů pro pokročilou analýzu textu nebo vícejazyčný obsah
  • Optimalizujte výsledky prostřednictvím profilů bodování, abyste mohli zohlednit obchodní logiku nebo aktuálnost.

Zdrojový kód | Balíček (PyPI) | Balíček (Conda) | Referenční dokumentace k | rozhraní APIDokumentace k | produktuVzorky

Začínáme

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Cognitive Search pro Python pomocí pipu:

pip install azure-search-documents

Požadavky

K vytvoření nové vyhledávací služby můžete použít Azure Portal, Azure PowerShell nebo Azure CLI.

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

Další informace o dostupných možnostech najdete v tématu Volba cenové úrovně .

Ověření klienta

Pokud chcete pracovat s Search, budete muset vytvořit instanci příslušné třídy klienta: SearchClient pro vyhledávání indexovaných dokumentů, SearchIndexClient pro správu indexů nebo SearchIndexerClient pro procházení zdrojů dat a načítání hledaných dokumentů do indexu. K vytvoření instance objektu klienta budete potřebovat koncový bod a klíč rozhraní API. Další informace o podporovaných přístupech ověřování pomocí Search najdete v dokumentaci.

Získání klíče rozhraní API

Koncový bod a klíč rozhraní API můžete získat z Search na webu Azure Portal. Pokyny k získání klíče rozhraní API najdete v dokumentaci .

Případně můžete použít následující příkaz Azure CLI k načtení klíče rozhraní API z Search:

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

Pro přístup k vyhledávací službě se používají dva typy klíčů: klíče admin(pro čtení i zápis) a klíče dotazů(jen pro čtení). Omezení přístupu a operací v klientských aplikacích je nezbytné pro zabezpečení prostředků vyhledávání ve vaší službě. Pro jakýkoli dotaz pocházející z klientské aplikace vždy používejte klíč dotazu místo klíče správce.

Poznámka: Výše uvedený ukázkový fragment kódu Azure CLI načte klíč správce, takže je jednodušší začít zkoumat rozhraní API, ale měl by se spravovat opatrně.

Vytvoření vyhledávacího klienta

K vytvoření SearchClientinstance nástroje budete potřebovat koncový bod, klíč rozhraní API a název indexu:

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

Vytvoření klienta pomocí ověřování Azure Active Directory

Můžete také vytvořit SearchClient, SearchIndexClientnebo SearchIndexerClient pomocí ověřování Azure Active Directory (AAD). Vašemu uživateli nebo instančnímu objektu musí být přiřazena role Čtenář dat indexu vyhledávání. Pomocí DefaultAzureCredential můžete ověřit službu pomocí spravované identity nebo instančního objektu, ověřit se jako vývojář pracující na aplikaci a to vše beze změny kódu. Pokyny k připojení k Azure Cognitive Search pomocí řízení přístupu na základě role v Azure (Azure RBAC) najdete v dokumentaci.

Než budete moct použít DefaultAzureCredential, nebo jakýkoli typ přihlašovacích údajů z Azure.Identity, musíte nejdřív nainstalovat balíček Azure.Identity.

Pokud chcete použít DefaultAzureCredential s ID klienta a tajným kódem, budete muset nastavit AZURE_TENANT_IDproměnné prostředí , AZURE_CLIENT_IDa AZURE_CLIENT_SECRET . Případně můžete tyto hodnoty ClientSecretCredential předat také v Azure.Identity.

Ujistěte se, že v horní části zdrojového souboru používáte správný obor názvů 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)

Klíčové koncepty

Služba Azure Cognitive Search obsahuje jeden nebo více indexů, které poskytují trvalé úložiště prohledávatelných dat ve formě dokumentů JSON. (Pokud s vyhledáváním začínáte, můžete vytvořit velmi přibližnou analogii mezi indexy a databázovými tabulkami.) Klientská knihovna Azure.Search.Documents zveřejňuje operace s těmito prostředky prostřednictvím dvou hlavních typů klientů.

Azure Cognitive Search nabízí dvě výkonné funkce: sémantické vyhledávání a vektorové vyhledávání.

Sémantické vyhledávání zvyšuje kvalitu výsledků hledání pro textové dotazy. Povolením sémantického vyhledávání ve vyhledávací službě můžete zvýšit relevanci výsledků hledání dvěma způsoby:

  • Použije sekundární pořadí pro počáteční sadu výsledků a povýšení nejvíce sémanticky relevantních výsledků na vrchol.
  • Extrahuje a vrací titulky a odpovědi v odpovědi, které se dají zobrazit na stránce hledání, aby se zlepšilo uživatelské prostředí vyhledávání.

Další informace o sémantickém vyhledávání najdete v dokumentaci.

Vektorové vyhledávání je technika načítání informací, která překonává omezení tradičního vyhledávání založeného na klíčových slovech. Místo toho, aby se spoléhalo výhradně na lexikální analýzu a porovnávání jednotlivých termínů dotazů, využívá funkce Vector Search modely strojového učení k zachycení kontextového významu slov a frází. Představuje dokumenty a dotazy jako vektory ve vysokodimenzionálním prostoru, kterému se říká vkládání. Díky pochopení záměru dotazu může vektorové vyhledávání poskytovat relevantnější výsledky, které odpovídají požadavkům uživatele, i když v dokumentu nejsou uvedené přesné termíny. Vektorové vyhledávání je navíc možné použít u různých typů obsahu, včetně obrázků a videí, nejen u textu.

Pokud se chcete dozvědět, jak indexovat vektorová pole a provádět vektorové vyhledávání, můžete se podívat na ukázku. Tato ukázka poskytuje podrobné pokyny k indexování vektorových polí a ukazuje, jak provádět vektorové vyhledávání.

Podrobnější informace o vektorovém vyhledávání, včetně jeho konceptů a použití, najdete v dokumentaci. Dokumentace poskytuje podrobná vysvětlení a pokyny k využití výkonu funkce Vector Search v Azure Cognitive Search.

Klientská Azure.Search.Documents knihovna (v1) je zcela nová nabídka pro vývojáře Pythonu, kteří chtějí ve svých aplikacích používat vyhledávací technologie. Existuje starší plně funkční Microsoft.Azure.Search klientská knihovna (v10) s mnoha podobnými rozhraními API, takže při zkoumání online prostředků dávejte pozor, abyste se vyhnuli nejasnostem.

Příklady

Všechny následující příklady používají jednoduchou datovou sadu Hotel, kterou můžete importovat do vlastního indexu z Azure Portal. Toto je jen pár základních informací– podívejte se prosím na naše ukázky, kde najdete mnohem víc.

Dotazování

Začněme importem našich oborů názvů.

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

Pak vytvoříme pro přístup k indexu SearchClient vyhledávání hotelů.

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)

Pojďme hledat "luxusní" hotel.

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

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

Vytvoření indexu

Můžete použít k SearchIndexClient vytvoření indexu vyhledávání. Pole je možné definovat pomocí pohodlných SimpleFieldmodelů , SearchableFieldnebo ComplexField . Indexy mohou také definovat návrhy, lexikální analyzátory a další.

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)

Přidání dokumentů do indexu

V jednom dávkovém požadavku můžete UploadMergeMergeOrUploadz indexu použít více dokumentů , , a Delete více dokumentů. Existuje několik zvláštních pravidel pro slučování , o které je potřeba vědět.

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

Ověřování v národním cloudu

Pokud chcete provádět ověřování v národním cloudu, budete muset do konfigurace klienta přidat následující položky:

  • Nastavte parametr AuthorityHost v možnostech přihlašovacích údajů nebo prostřednictvím AZURE_AUTHORITY_HOST proměnné prostředí.
  • Nastavte v audienceSearchClient, SearchIndexClientnebo 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")

Načtení určitého dokumentu z indexu

Kromě dotazování na dokumenty pomocí klíčových slov a volitelných filtrů můžete z indexu načíst konkrétní dokument, pokud už znáte klíč. Klíč můžete získat například z dotazu a chcete o něm zobrazit další informace nebo nasměrovat zákazníka na daný dokument.

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

Asynchronní rozhraní API

Tato knihovna obsahuje kompletní asynchronní rozhraní API. Abyste ho mohli používat, musíte nejdřív nainstalovat asynchronní přenos, například aiohttp. Další informace najdete v dokumentaci k 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"]))

Poradce při potížích

Obecné

Klient Azure Cognitive Search vyvolá výjimky definované v Azure Core.

protokolování

Tato knihovna používá k protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně DEBUG, včetně těl požadavků/odpovědí a nezopravovaných hlaviček, je možné povolit v klientovi s argumentem klíčového logging_enable slova:

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)

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

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

Další kroky

Přispívání

Podrobnosti o vytváření, testování a přispívání do této knihovny najdete v CONTRIBUTING.md hledání .

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete v cla.microsoft.com.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.

Imprese

Imprese