Python için Azure Bilişsel Arama istemci kitaplığı - sürüm 11.4.0

  • Makale

Azure Bilişsel Arama, geliştiricilere web, mobil ve kurumsal uygulamalarda özel, heterojen içerik üzerinde zengin bir arama deneyimi eklemeye yönelik API'ler ve araçlar sağlayan bir hizmet olarak arama bulut çözümüdür.

Azure Bilişsel Arama hizmeti aşağıdaki uygulama senaryoları için uygundur:

  • Çeşitli içerik türlerini tek bir aranabilir dizinde birleştirin. Dizini doldurmak için, içeriğinizi içeren JSON belgelerini gönderebilirsiniz veya verileriniz zaten Azure'daysa verileri otomatik olarak çekmek için bir dizin oluşturucu oluşturabilirsiniz.
  • Resimlerden ve büyük metin belgelerinden aranabilir içerik oluşturmak için beceri kümelerini dizin oluşturucuya ekleyin. Beceri kümesi yerleşik OCR, varlık tanıma, anahtar ifade ayıklama, dil algılama, metin çevirisi ve yaklaşım analizi için Bilişsel Hizmetler'den yapay zekadan yararlanıyor. Ayrıca, veri alımı sırasında içeriğinizin dış işlemesini tümleştirmek için özel beceriler de ekleyebilirsiniz.
  • Bir arama istemci uygulamasında, ticari web arama altyapılarına benzer sorgu mantığını ve kullanıcı deneyimlerini uygulayın.

Azure.Search.Documents istemci kitaplığını kullanarak:

  • Belirsiz arama, joker karakter araması ve normal ifadeler içeren basit ve gelişmiş sorgu formları için sorgu gönderin.
  • Çok yönlü gezinti, jeo-uzamsal arama veya filtre ölçütlerine göre sonuçları daraltmak için filtrelenmiş sorgular uygulayın.
  • Arama dizinleri oluşturun ve yönetin.
  • Arama dizinindeki belgeleri karşıya yükleyin ve güncelleştirin.
  • Azure'dan dizine veri çeken dizin oluşturucular oluşturun ve yönetin.
  • Veri alımına yapay zeka zenginleştirmesi ekleyen beceri kümeleri oluşturun ve yönetin.
  • Gelişmiş metin analizi veya çok dilli içerik için çözümleyiciler oluşturun ve yönetin.
  • İş mantığını veya güncelliği dikkate almak için puanlama profilleriyle sonuçları iyileştirin.

Kaynak kodu | Paket (PyPI) | Paket (Conda) | API başvuru belgeleri | Ürün belgeleri | Örnekleri

Başlarken

Paketi yükleme

Pip ile Python için Azure Bilişsel Arama istemci kitaplığını yükleyin:

pip install azure-search-documents

Önkoşullar

Yeni bir arama hizmeti oluşturmak için Azure portal, Azure PowerShell veya Azure CLI'yı kullanabilirsiniz.

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

Kullanılabilir seçenekler hakkında daha fazla bilgi için bkz. fiyatlandırma katmanı seçme .

İstemcinin kimliğini doğrulama

Arama hizmeti etkileşim kurmak için uygun istemci sınıfının bir örneğini oluşturmanız gerekir: SearchClient dizinlenmiş belgelerde arama yapmak, SearchIndexClient dizinleri yönetmek veya SearchIndexerClient veri kaynaklarında gezinmek ve arama belgelerini bir dizine yüklemek için. İstemci nesnesinin örneğini oluşturmak için bir uç nokta ve API anahtarı gerekir. Arama hizmeti desteklenen kimlik doğrulama yaklaşımları hakkında daha fazla bilgi için belgelere başvurabilirsiniz.

API Anahtarı Alma

Uç noktayı ve API anahtarınıAzure Portal'daki Arama hizmeti alabilirsiniz. API anahtarı alma yönergeleri için lütfen belgelere bakın.

Alternatif olarak, api anahtarını Arama hizmeti almak için aşağıdaki Azure CLI komutunu kullanabilirsiniz:

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

Arama hizmetinize erişmek için kullanılan iki tür anahtar vardır: admin(okuma-yazma) ve sorgu(salt okunur) anahtarlar. İstemci uygulamalarında erişimi ve işlemleri kısıtlamak, hizmetinizdeki arama varlıklarını korumak için çok önemlidir. İstemci uygulamasından kaynaklanan herhangi bir sorgu için her zaman yönetici anahtarı yerine sorgu anahtarı kullanın.

Not: Yukarıdaki örnek Azure CLI kod parçacığı, API'leri keşfetmeye başlamanın daha kolay olması için bir yönetici anahtarı alır, ancak dikkatle yönetilmelidir.

SearchClient oluşturma

SearchClientörneği oluşturmak için uç nokta, API anahtarı ve dizin adı gerekir:

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

Azure Active Directory kimlik doğrulamayı kullanarak istemci oluşturma

Azure Active Directory (AAD) kimlik doğrulamayı kullanarak da , SearchClientSearchIndexClientveya SearchIndexerClient oluşturabilirsiniz. Kullanıcı veya hizmet sorumlunuza "Arama Dizini Veri Okuyucusu" rolü atanmalıdır. DefaultAzureCredential kullanarak Yönetilen Kimlik veya hizmet sorumlusu kullanarak bir hizmetin kimliğini doğrulayabilir, uygulama üzerinde çalışan bir geliştirici olarak kimlik doğrulaması yapabilir ve daha fazlasını kod değiştirmeden yapabilirsiniz. Azure rol tabanlı erişim denetimi (Azure RBAC) kullanarak Azure Bilişsel Arama bağlanma yönergeleri için lütfen belgelere bakın.

Azure.Identity'den veya herhangi bir kimlik bilgisi türünü kullanabilmeniz DefaultAzureCredentialiçin önce Azure.Identity paketini yüklemeniz gerekir.

İstemci kimliği ve gizli dizi ile kullanmak DefaultAzureCredential için , AZURE_CLIENT_IDve AZURE_CLIENT_SECRET ortam değişkenlerini ayarlamanız AZURE_TENANT_IDgerekir; alternatif olarak, bu değerleri ClientSecretCredential Azure.Identity'de de öğesine geçirebilirsiniz.

Kaynak dosyanızın üst kısmındaki için DefaultAzureCredential doğru ad alanını kullandığınızdan emin olun:

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)

Önemli kavramlar

Azure Bilişsel Arama hizmeti, aranabilir verilerin JSON belgeleri biçiminde kalıcı olarak depolanmasını sağlayan bir veya daha fazla dizin içerir. (Aramada yeniyseniz, dizinler ve veritabanı tabloları arasında çok kaba bir benzetme yapabilirsiniz.) Azure.Search.Documents istemci kitaplığı, bu kaynaklardaki işlemleri iki ana istemci türü aracılığıyla kullanıma sunar.

Azure Bilişsel Arama iki güçlü özellik sağlar: AnlamSal Arama ve Vektör Arama.

AnlamSal Arama , metin tabanlı sorgular için arama sonuçlarının kalitesini artırır. Arama hizmetinizde AnlamSal Arama'yı etkinleştirerek, arama sonuçlarının ilgi düzeyini iki yolla geliştirebilirsiniz:

  • İlk sonuç kümesine ikincil derecelendirme uygulayarak en ilgili sonuçları en üste yükseltmeyi sağlar.
  • Yanıttaki açıklamalı alt yazıları ve yanıtları ayıklar ve döndürür. Bu yanıt, kullanıcının arama deneyimini geliştirmek için arama sayfasında görüntülenebilir.

Anlam Arama hakkında daha fazla bilgi edinmek için belgelere başvurabilirsiniz.

Vektör Arama , geleneksel anahtar sözcük tabanlı aramanın sınırlamalarının üstesinden gelen bir bilgi alma tekniğidir. Vektör Arama, yalnızca sözcük temelli analize ve tek tek sorgu terimlerine güvenmek yerine, sözcüklerin ve tümceciklerin bağlamsal anlamını yakalamak için makine öğrenmesi modellerini kullanır. Belgeleri ve sorguları ekleme adı verilen yüksek boyutlu bir alanda vektör olarak temsil eder. Vektör Arama, sorgunun amacını anlayarak, belgede tam terimler olmasa bile kullanıcının gereksinimlerine uygun daha ilgili sonuçlar sunabilir. Ayrıca, Vektör Araması yalnızca metinlere değil, resimler ve videolar da dahil olmak üzere çeşitli içerik türlerine uygulanabilir.

Vektör alanlarını dizine almayı ve vektör araması yapmayı öğrenmek için örne başvurabilirsiniz. Bu örnek, vektör alanlarını dizinleme hakkında ayrıntılı rehberlik sağlar ve vektör araması gerçekleştirmeyi gösterir.

Buna ek olarak, vektör arama kavramları ve kullanımı dahil olmak üzere daha kapsamlı bilgi için belgelere başvurabilirsiniz. Belgeler, Azure Bilişsel Arama'da Vektör Arama'nın gücünden yararlanmaya yönelik ayrıntılı açıklamalar ve rehberlik sağlar.

İstemci Azure.Search.Documents kitaplığı (v1), uygulamalarında arama teknolojisini kullanmak isteyen Python geliştiricileri için yepyeni bir tekliftir. Benzer görünümlü birçok API'ye sahip eski, tam özellikli Microsoft.Azure.Search bir istemci kitaplığı (v10) vardır, bu nedenle çevrimiçi kaynakları keşfederken karışıklığı önlemek için lütfen dikkatli olun.

Örnekler

Aşağıdaki örneklerin tümü, Azure portal kendi dizininize aktarabileceğiniz basit bir Otel veri kümesi kullanır. Bunlar temel bilgilerden yalnızca birkaçıdır. Daha fazlası için lütfen Örneklerimize göz atın.

Sorgulama

Ad alanımızı içeri aktararak başlayalım.

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

Ardından otel arama dizinimize erişmek için bir SearchClient oluşturacağız.

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üks" bir otel arayalım.

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

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

Dizin oluşturma

Arama dizini oluşturmak için kullanabilirsiniz SearchIndexClient . Alanlar uygun SimpleField, SearchableFieldveya ComplexField modelleri kullanılarak tanımlanabilir. Dizinler öneri oluşturucular, sözcük temelli çözümleyiciler ve daha fazlasını da tanımlayabilir.

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)

Dizininize belge ekleme

Tek bir toplu istekteki bir dizinden , Merge, MergeOrUploadve Delete birden çok belge oluşturabilirsinizUpload. Birleştirilmesi için dikkat etmeniz gereken birkaç özel kural vardır.

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

Ulusal Bulutta kimlik doğrulaması

Ulusal Bulutta kimlik doğrulaması yapmak için istemci yapılandırmanıza aşağıdaki eklemeleri yapmanız gerekir:

  • AuthorityHost kimlik bilgisi seçeneklerinde veya ortam değişkeni aracılığıyla AZURE_AUTHORITY_HOST değerini ayarlayın
  • , SearchIndexClientveya içinde SearchClientdeğerini audience ayarlayınSearchIndexerClient
# 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")

Dizininizden belirli bir belgeyi alma

Anahtar sözcükleri ve isteğe bağlı filtreleri kullanarak belgeleri sorgulamaya ek olarak, anahtarı zaten biliyorsanız dizininizden belirli bir belgeyi alabilirsiniz. Örneğin, bir sorgudan anahtarı alabilir ve bu sorgu hakkında daha fazla bilgi göstermek veya müşterinizi bu belgeye gitmek isteyebilirsiniz.

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

Zaman Uyumsuz API'ler

Bu kitaplık tam bir zaman uyumsuz API içerir. Bunu kullanmak için önce aiohttp gibi bir zaman uyumsuz aktarım yüklemeniz gerekir. Daha fazla bilgi için bkz. azure-core belgeleri .

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

Sorun giderme

Genel

Azure Bilişsel Arama istemcisi, Azure Core'da tanımlanan özel durumları tetikler.

Günlüğe Kaydetme

Bu kitaplık, günlüğe kaydetme için standart günlük kitaplığını kullanır. HTTP oturumlarıyla ilgili temel bilgiler (URL'ler, üst bilgiler vb.) BİlGİ düzeyinde günlüğe kaydedilir.

İstek/yanıt gövdeleri ve kaydedilmemiş üst bilgiler de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğü, anahtar sözcük bağımsız değişkeniyle logging_enable bir istemcide etkinleştirilebilir:

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)

Benzer şekilde, logging_enable istemci için etkinleştirilmemiş olsa bile tek bir işlem için ayrıntılı günlüğe kaydetmeyi etkinleştirebilir:

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

Sonraki adımlar

Katkıda bulunma

Bu kitaplığı oluşturma, test etme ve bu kitaplığa katkıda bulunma hakkında ayrıntılı bilgi için Arama CONTRIBUTING.md'mize bakın.

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için cla.microsoft.com adresini ziyaret edin.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorular veya yorumlarla iletişime geçin opencode@microsoft.com .

İzlenimler

İzlenimler