biblioteka klienta Azure Cognitive Search dla języka Python — wersja 11.4.0

  • Artykuł

Azure Cognitive Search to rozwiązanie w chmurze typu search-as-a-service, które udostępnia deweloperom interfejsy API i narzędzia umożliwiające dodawanie rozbudowanego środowiska wyszukiwania za pośrednictwem prywatnej, heterogenicznej zawartości w aplikacjach internetowych, mobilnych i dla przedsiębiorstw.

Usługa Azure Cognitive Search jest dobrze odpowiednia dla następujących scenariuszy aplikacji:

  • Skonsoliduj różne typy zawartości w jeden indeks z możliwością wyszukiwania. Aby wypełnić indeks, możesz wypchnąć dokumenty JSON zawierające zawartość lub jeśli dane są już na platformie Azure, utwórz indeksator, aby automatycznie ściągać dane.
  • Dołącz zestawy umiejętności do indeksatora, aby utworzyć zawartość z możliwością wyszukiwania na podstawie obrazów i dużych dokumentów tekstowych. Zestaw umiejętności wykorzystuje sztuczną inteligencję z usług Cognitive Services na potrzeby wbudowanego rozpoznawania OCR, rozpoznawania jednostek, wyodrębniania kluczowych fraz, wykrywania języka, tłumaczenia tekstu i analizy tonacji. Możesz również dodać umiejętności niestandardowe, aby zintegrować zewnętrzne przetwarzanie zawartości podczas pozyskiwania danych.
  • W aplikacji klienckiej wyszukiwania zaimplementuj logikę zapytań i środowiska użytkownika podobne do komercyjnych wyszukiwarek internetowych.

Użyj biblioteki klienta Azure.Search.Documents, aby:

  • Przesyłaj zapytania dotyczące prostych i zaawansowanych formularzy zapytań, które obejmują wyszukiwanie rozmyte, wyszukiwanie wieloznaczne, wyrażenia regularne.
  • Zaimplementuj zapytania filtrowane na potrzeby nawigacji aspektowej, wyszukiwania geoprzestrzennego lub zawężaj wyniki na podstawie kryteriów filtrowania.
  • Tworzenie indeksów wyszukiwania i zarządzanie nimi.
  • Przekazywanie i aktualizowanie dokumentów w indeksie wyszukiwania.
  • Tworzenie indeksatorów, które ściągają dane z platformy Azure do indeksu i zarządzaj nimi.
  • Tworzenie zestawów umiejętności, które dodają wzbogacanie sztucznej inteligencji do pozyskiwania danych i zarządzanie nimi.
  • Tworzenie analizatorów i zarządzanie nimi na potrzeby zaawansowanej analizy tekstu lub zawartości wielojęzycznej.
  • Zoptymalizuj wyniki za pomocą profilów oceniania, aby uwzględnić logikę biznesową lub świeżość.

Kod | źródłowyPakiet (PyPI) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | APIDokumentacja | produktuPróbki

Wprowadzenie

Instalowanie pakietu

Zainstaluj bibliotekę klienta Azure Cognitive Search dla języka Python przy użyciu narzędzia pip:

pip install azure-search-documents

Wymagania wstępne

Aby utworzyć nową usługę wyszukiwania, możesz użyć Azure Portal, Azure PowerShell lub interfejsu wiersza polecenia platformy Azure.

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

Aby uzyskać więcej informacji o dostępnych opcjach, zobacz wybieranie warstwy cenowej .

Uwierzytelnianie klienta

Aby korzystać z usługa wyszukiwania, należy utworzyć wystąpienie odpowiedniej klasy klienta: SearchClient do wyszukiwania indeksowanych dokumentów, SearchIndexClient zarządzania indeksami lub SearchIndexerClient przeszukiwania źródeł danych i ładowania dokumentów wyszukiwania do indeksu. Aby utworzyć wystąpienie obiektu klienta, potrzebny będzie punkt końcowy i klucz interfejsu API. Więcej informacji na temat obsługiwanych metod uwierzytelniania za pomocą usługa wyszukiwania można znaleźć w dokumentacji.

Uzyskiwanie klucza interfejsu API

Punkt końcowy i klucz interfejsu API można uzyskać z usługa wyszukiwania w witrynie Azure Portal. Zapoznaj się z dokumentacją , aby uzyskać instrukcje dotyczące uzyskiwania klucza interfejsu API.

Alternatywnie możesz użyć następującego polecenia interfejsu wiersza polecenia platformy Azure, aby pobrać klucz interfejsu API z usługa wyszukiwania:

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

Istnieją dwa typy kluczy używanych do uzyskiwania dostępu do usługi wyszukiwania: admin(read-write) i query(tylko do odczytu) klucze. Ograniczenie dostępu i operacji w aplikacjach klienckich jest niezbędne do ochrony zasobów wyszukiwania w usłudze. Zawsze używaj klucza zapytania, a nie klucza administratora dla dowolnego zapytania pochodzącego z aplikacji klienckiej.

Uwaga: powyższy fragment kodu interfejsu wiersza polecenia platformy Azure pobiera klucz administratora, aby ułatwić rozpoczęcie eksplorowania interfejsów API, ale należy go starannie zarządzać.

Tworzenie elementu SearchClient

Aby utworzyć wystąpienie elementu , potrzebny będzie punkt końcowy, klucz interfejsuSearchClientAPI i nazwa indeksu:

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

Tworzenie klienta przy użyciu uwierzytelniania usługi Azure Active Directory

Można również utworzyć SearchClientuwierzytelnianie usługi , SearchIndexClientlub SearchIndexerClient przy użyciu usługi Azure Active Directory (AAD). Użytkownik lub jednostka usługi musi mieć przypisaną rolę "Czytnik danych indeksu wyszukiwania". Za pomocą ustawienia DefaultAzureCredential można uwierzytelnić usługę przy użyciu tożsamości zarządzanej lub jednostki usługi, uwierzytelnić się jako deweloper pracujący nad aplikacją i nie tylko bez zmiany kodu. Zapoznaj się z dokumentacją, aby uzyskać instrukcje dotyczące nawiązywania połączenia z Azure Cognitive Search przy użyciu kontroli dostępu opartej na rolach platformy Azure (Azure RBAC).

Przed użyciem DefaultAzureCredentialdowolnego typu poświadczeń z witryny Azure.Identity należy najpierw zainstalować pakiet Azure.Identity.

Aby użyć DefaultAzureCredential identyfikatora klienta i wpisu tajnego, należy ustawić AZURE_TENANT_IDzmienne środowiskowe , AZURE_CLIENT_IDi AZURE_CLIENT_SECRET . Alternatywnie możesz przekazać te wartości również w ClientSecretCredential usłudze Azure.Identity.

Upewnij się, że używasz odpowiedniej przestrzeni nazw w DefaultAzureCredential górnej części pliku źródłowego:

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)

Kluczowe pojęcia

Usługa Azure Cognitive Search zawiera co najmniej jeden indeks, który zapewnia trwały magazyn danych z możliwością wyszukiwania w postaci dokumentów JSON. (Jeśli dopiero zaczynasz wyszukiwanie, możesz utworzyć bardzo szorstką analogię między indeksami i tabelami bazy danych). Biblioteka klienta Azure.Search.Documents udostępnia operacje na tych zasobach za pośrednictwem dwóch głównych typów klientów.

Azure Cognitive Search oferuje dwie zaawansowane funkcje: wyszukiwanie semantyczne i wyszukiwanie wektorowe.

Wyszukiwanie semantyczne zwiększa jakość wyników wyszukiwania dla zapytań opartych na tekście. Włączając semantyczne wyszukiwanie w usłudze wyszukiwania, można poprawić istotność wyników wyszukiwania na dwa sposoby:

  • Stosuje drugą klasyfikację do początkowego zestawu wyników, promując najbardziej semantycznie istotne wyniki na szczycie.
  • Wyodrębnia i zwraca podpisy i odpowiedzi w odpowiedzi, które można wyświetlić na stronie wyszukiwania, aby ulepszyć środowisko wyszukiwania użytkownika.

Aby dowiedzieć się więcej na temat wyszukiwania semantycznego, zapoznaj się z dokumentacją.

Wyszukiwanie wektorowe to technika pobierania informacji, która pozwala przezwyciężyć ograniczenia tradycyjnego wyszukiwania opartego na słowach kluczowych. Zamiast polegać wyłącznie na analizie leksykalnej i dopasowywaniu poszczególnych terminów zapytania, usługa Vector Search wykorzystuje modele uczenia maszynowego do przechwytywania kontekstowego znaczenia słów i fraz. Reprezentuje dokumenty i zapytania jako wektory w przestrzeni o wysokim wymiarach nazywane osadzaniem. Dzięki zrozumieniu intencji zapytania usługa Vector Search może dostarczać bardziej istotne wyniki zgodne z wymaganiami użytkownika, nawet jeśli dokładne terminy nie są obecne w dokumencie. Ponadto wyszukiwanie wektorowe można stosować do różnych typów zawartości, w tym obrazów i filmów wideo, a nie tylko tekstu.

Aby dowiedzieć się, jak indeksować pola wektorów i wykonywać wyszukiwanie wektorów, możesz zapoznać się z przykładem. Ten przykład zawiera szczegółowe wskazówki dotyczące pól wektorów indeksowania i pokazuje, jak wykonywać wyszukiwanie wektorów.

Ponadto, aby uzyskać bardziej kompleksowe informacje na temat wyszukiwania wektorowego, w tym jej pojęć i użycia, możesz zapoznać się z dokumentacją. Dokumentacja zawiera szczegółowe wyjaśnienia i wskazówki dotyczące korzystania z możliwości wyszukiwania wektorowego w Azure Cognitive Search.

Azure.Search.Documents Biblioteka klienta (wersja 1) to zupełnie nowa oferta dla deweloperów języka Python, którzy chcą korzystać z technologii wyszukiwania w swoich aplikacjach. Istnieje starsza, w pełni funkcjonalna Microsoft.Azure.Search biblioteka klienta (wersja 10) z wieloma podobnymi interfejsami API, dlatego należy zachować ostrożność, aby uniknąć nieporozumień podczas eksplorowania zasobów online.

Przykłady

W poniższych przykładach użyto prostego zestawu danych hotelowego, który można zaimportować do własnego indeksu z Azure Portal. To tylko kilka podstaw — zapoznaj się z naszymi przykładami, aby uzyskać znacznie więcej informacji.

Wykonywanie zapytania

Zacznijmy od zaimportowania przestrzeni nazw.

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

Następnie utworzymy element umożliwiający SearchClient dostęp do naszego indeksu wyszukiwania hoteli.

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)

Wyszukajmy "luksusowy" hotel.

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

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

Tworzenie indeksu

Możesz użyć polecenia SearchIndexClient , aby utworzyć indeks wyszukiwania. Pola można zdefiniować przy użyciu wygodnych SimpleFieldmodeli , SearchableFieldlub ComplexField . Indeksy mogą również definiować sugestory, analizatory leksykalne i nie tylko.

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)

Dodawanie dokumentów do indeksu

W jednym żądaniu wsadowym można utworzyć Uploadwiele Mergedokumentów z indeksu , , MergeOrUploadi Delete wielu dokumentów. Istnieje kilka specjalnych reguł dotyczących scalania , które należy znać.

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

Uwierzytelnianie w chmurze krajowej

Aby przeprowadzić uwierzytelnianie w chmurze krajowej, należy wprowadzić następujące dodatki do konfiguracji klienta:

  • AuthorityHost Ustaw wartość w opcjach poświadczeń lub za pomocą zmiennej środowiskowej AZURE_AUTHORITY_HOST
  • Ustaw właściwość w SearchClientelemecie audience , SearchIndexClientlubSearchIndexerClient
# 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")

Pobieranie określonego dokumentu z indeksu

Oprócz wykonywania zapytań dotyczących dokumentów przy użyciu słów kluczowych i opcjonalnych filtrów można pobrać konkretny dokument z indeksu, jeśli znasz już klucz. Możesz na przykład pobrać klucz z zapytania i wyświetlić więcej informacji na jego temat lub przejść do tego dokumentu.

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

Asynchroniczne interfejsy API

Ta biblioteka zawiera kompletny asynchroniczny interfejs API. Aby go używać, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Aby uzyskać więcej informacji, zobacz dokumentację platformy 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"]))

Rozwiązywanie problemów

Ogólne

Klient Azure Cognitive Search zgłosi wyjątki zdefiniowane w usłudze Azure Core.

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem słowa kluczowego 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 Podobnie można włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

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

Następne kroki

Współtworzenie

Zobacz nasze CONTRIBUTING.md wyszukiwania , aby uzyskać szczegółowe informacje na temat kompilowania, testowania i współtworzenia tej biblioteki.

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź cla.microsoft.com.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.

Wrażenia

Wrażenia