Hızlı Başlangıç: Jupyter Notebook kullanarak Python'da Azure Bilişsel Arama dizini oluşturma

Bu alıştırmada Python'ı ve Python için Azure SDK'daki azure-search-documents kitaplığını kullanarak bir Azure Bilişsel Arama dizini oluşturan, yükleyen ve sorgulayan bir Jupyter Notebook oluşturun. Bu makalede, adım adım not defteri oluşturma adımları açıklanmaktadır. Alternatif olarak, tamamlanmış bir Jupyter Python not defterini indirip çalıştırabilirsiniz.

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

Önkoşullar

Bu hızlı başlangıçta aşağıdaki hizmetler ve araçlar kullanılmaktadır.

Anahtarı ve URL'yi kopyalama

Arama hizmetinize bağlanmak için uç noktayı ve erişim anahtarını sağlayın. Her ikisiyle de bir arama hizmeti oluşturulur, bu nedenle aboneliğinize Azure Bilişsel Arama eklediyseniz gerekli bilgileri almak için şu adımları izleyin:

  1. Azure portal oturum açın ve arama hizmeti genel bakış sayfanızda URL'yi alın. Örnek uç nokta https://mydemo.search.windows.net şeklinde görünebilir.

  2. Ayarlar>Anahtarları'nda, hizmette tam haklar için bir yönetici anahtarı alın. Bir anahtarı devretmeniz gerektiğinde iş sürekliliği için sağlanan, birbirinin yerine kullanılabilen iki yönetici anahtarı vardır. Nesneleri ekleme, değiştirme ve silme isteklerinde birincil veya ikincil anahtarı kullanabilirsiniz.

    HTTP uç noktası ve erişim anahtarı alma

Bağlantıyı kurarken sonraki bölümde bu değerleri sağlayacaksınız.

Bu görevde not defterini oluşturun, kitaplıkları yükleyin ve istemcilerinizi ayarlayın.

  1. Visual Studio Code'de yeni bir Python3 not defteri oluşturun:

    1. F1 tuşuna basın ve "Python Select Interpreter" araması yapın ve Python 3.7 veya sonraki bir sürümünü seçin.
    2. F1 tuşuna yeniden basın ve "Oluştur: Yeni Jupyter Notebook" araması yapın. Düzenleyicide ilk girdi için hazır boş, adsız .ipynb bir dosya açmanız gerekir.
  2. İlk hücrede, azure-search-documents dahil olmak üzere Python için Azure SDK'dan kitaplıkları yükleyin.

    %pip install azure-search-documents --pre
    %pip show azure-search-documents
    
    import os
    from azure.core.credentials import AzureKeyCredential
    from azure.search.documents.indexes import SearchIndexClient 
    from azure.search.documents import SearchClient
    from azure.search.documents.indexes.models import (
        ComplexField,
        CorsOptions,
        SearchIndex,
        ScoringProfile,
        SearchFieldDataType,
        SimpleField,
        SearchableField
    )
    
  3. İkinci bir hücre ekleyin ve bağlantı bilgilerine yapıştırın. Bu hücre ayrıca belirli işlemler için kullanacağınız istemcileri de ayarlar: Dizin oluşturmak için SearchIndexClient ve dizini sorgulamak için SearchClient .

    service_name = "YOUR-SEARCH-SERVICE-NAME"
    admin_key = "YOUR-SEARCH-SERVICE-ADMIN-API-KEY"
    
    index_name = "hotels-quickstart"
    
    # Create an SDK client
    endpoint = "https://{}.search.windows.net/".format(service_name)
    admin_client = SearchIndexClient(endpoint=endpoint,
                          index_name=index_name,
                          credential=AzureKeyCredential(admin_key))
    
    search_client = SearchClient(endpoint=endpoint,
                          index_name=index_name,
                          credential=AzureKeyCredential(admin_key))
    
  4. Üçüncü hücrede, hizmetinizi mevcut oteller-hızlı başlangıç dizinlerinden temizlemek için bir delete_index işlemi çalıştırın. Dizini silmek, aynı ada ait başka bir hotels-quickstart dizini oluşturmanıza olanak tanır.

    try:
        result = admin_client.delete_index(index_name)
        print ('Index', index_name, 'Deleted')
    except Exception as ex:
        print (ex)
    
  5. Her adımı çalıştırın.

1 - Dizin oluşturma

Gerekli dizin öğeleri bir ad, alan koleksiyonu ve her arama belgesini benzersiz olarak tanımlayan bir belge anahtarı içerir. Alanlar koleksiyonu, hem verileri yüklemek hem de sonuçları döndürmek için kullanılan mantıksal arama belgesinin yapısını tanımlar.

Alanlar koleksiyonunda, her alanın nasıl kullanıldığını belirleyen bir adı, türü ve öznitelikleri vardır (örneğin, tam metin aranabilir, filtrelenebilir veya arama sonuçlarında alınabilir). Dizin içinde, tür Edm.String alanlarından biri belge kimliği için anahtar olarak belirlenmelidir.

Bu dizin "hotels-quickstart" olarak adlandırılır ve aşağıda gördüğünüz alan tanımlarına sahiptir. Bu, diğer kılavuzlarda kullanılan daha büyük bir Oteller dizininin alt kümesidir. Kısa olması için bu hızlı başlangıçta kırpıldı.

  1. Sonraki hücrede, şemayı sağlamak için aşağıdaki örneği bir hücreye yapıştırın.

    # Specify the index schema
    name = index_name
    fields = [
            SimpleField(name="HotelId", type=SearchFieldDataType.String, key=True),
            SearchableField(name="HotelName", type=SearchFieldDataType.String, sortable=True),
            SearchableField(name="Description", type=SearchFieldDataType.String, analyzer_name="en.lucene"),
            SearchableField(name="Description_fr", type=SearchFieldDataType.String, analyzer_name="fr.lucene"),
            SearchableField(name="Category", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
    
            SearchableField(name="Tags", collection=True, type=SearchFieldDataType.String, facetable=True, filterable=True),
    
            SimpleField(name="ParkingIncluded", type=SearchFieldDataType.Boolean, facetable=True, filterable=True, sortable=True),
            SimpleField(name="LastRenovationDate", type=SearchFieldDataType.DateTimeOffset, facetable=True, filterable=True, sortable=True),
            SimpleField(name="Rating", type=SearchFieldDataType.Double, facetable=True, filterable=True, sortable=True),
    
            ComplexField(name="Address", fields=[
                SearchableField(name="StreetAddress", type=SearchFieldDataType.String),
                SearchableField(name="City", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
                SearchableField(name="StateProvince", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
                SearchableField(name="PostalCode", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
                SearchableField(name="Country", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
            ])
        ]
    cors_options = CorsOptions(allowed_origins=["*"], max_age_in_seconds=60)
    scoring_profiles = []
    suggester = [{'name': 'sg', 'source_fields': ['Tags', 'Address/City', 'Address/Country']}]
    
  2. Başka bir hücrede isteği formüle edin. Bu create_index isteği, arama hizmetinizin dizinler koleksiyonunu hedefler ve önceki hücrede sağladığınız dizin şemasını temel alan bir SearchIndex oluşturur.

    index = SearchIndex(
        name=name,
        fields=fields,
        scoring_profiles=scoring_profiles,
        suggesters = suggester,
        cors_options=cors_options)
    
    try:
        result = admin_client.create_index(index)
        print ('Index', result.name, 'created')
    except Exception as ex:
        print (ex)
    
  3. Her adımı çalıştırın.

2 - Belgeleri yükleme

Belgeleri yüklemek için, işlem türü (karşıya yükleme, birleştirme ve karşıya yükleme vb.) için bir dizin eylemi kullanarak bir belge koleksiyonu oluşturun. Belgelerin kaynağı GitHub'daki HotelsData'dır .

  1. Yeni bir hücrede, dizin şemasına uygun dört belge sağlayın. Her belge için bir karşıya yükleme eylemi belirtin.

    documents = [
        {
        "@search.action": "upload",
        "HotelId": "1",
        "HotelName": "Secret Point Motel",
        "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
        "Description_fr": "L'hôtel est idéalement situé sur la principale artère commerciale de la ville en plein cœur de New York. A quelques minutes se trouve la place du temps et le centre historique de la ville, ainsi que d'autres lieux d'intérêt qui font de New York l'une des villes les plus attractives et cosmopolites de l'Amérique.",
        "Category": "Boutique",
        "Tags": [ "pool", "air conditioning", "concierge" ],
        "ParkingIncluded": "false",
        "LastRenovationDate": "1970-01-18T00:00:00Z",
        "Rating": 3.60,
        "Address": {
            "StreetAddress": "677 5th Ave",
            "City": "New York",
            "StateProvince": "NY",
            "PostalCode": "10022",
            "Country": "USA"
            }
        },
        {
        "@search.action": "upload",
        "HotelId": "2",
        "HotelName": "Twin Dome Motel",
        "Description": "The hotel is situated in a  nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts.",
        "Description_fr": "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
        "Category": "Boutique",
        "Tags": [ "pool", "free wifi", "concierge" ],
        "ParkingIncluded": "false",
        "LastRenovationDate": "1979-02-18T00:00:00Z",
        "Rating": 3.60,
        "Address": {
            "StreetAddress": "140 University Town Center Dr",
            "City": "Sarasota",
            "StateProvince": "FL",
            "PostalCode": "34243",
            "Country": "USA"
            }
        },
        {
        "@search.action": "upload",
        "HotelId": "3",
        "HotelName": "Triple Landscape Hotel",
        "Description": "The Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services.",
        "Description_fr": "L'hôtel est situé dans une place du XIXe siècle, qui a été agrandie et rénovée aux plus hautes normes architecturales pour créer un hôtel moderne, fonctionnel et de première classe dans lequel l'art et les éléments historiques uniques coexistent avec le confort le plus moderne.",
        "Category": "Resort and Spa",
        "Tags": [ "air conditioning", "bar", "continental breakfast" ],
        "ParkingIncluded": "true",
        "LastRenovationDate": "2015-09-20T00:00:00Z",
        "Rating": 4.80,
        "Address": {
            "StreetAddress": "3393 Peachtree Rd",
            "City": "Atlanta",
            "StateProvince": "GA",
            "PostalCode": "30326",
            "Country": "USA"
            }
        },
        {
        "@search.action": "upload",
        "HotelId": "4",
        "HotelName": "Sublime Cliff Hotel",
        "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 1800 palace.",
        "Description_fr": "Le sublime Cliff Hotel est situé au coeur du centre historique de sublime dans un quartier extrêmement animé et vivant, à courte distance de marche des sites et monuments de la ville et est entouré par l'extraordinaire beauté des églises, des bâtiments, des commerces et Monuments. Sublime Cliff fait partie d'un Palace 1800 restauré avec amour.",
        "Category": "Boutique",
        "Tags": [ "concierge", "view", "24-hour front desk service" ],
        "ParkingIncluded": "true",
        "LastRenovationDate": "1960-02-06T00:00:00Z",
        "Rating": 4.60,
        "Address": {
            "StreetAddress": "7400 San Pedro Ave",
            "City": "San Antonio",
            "StateProvince": "TX",
            "PostalCode": "78216",
            "Country": "USA"
            }
        }
    ]
    
  2. Başka bir hücrede isteği formüle edin. Bu upload_documents isteği hotels-quickstart dizininin docs koleksiyonunu hedefler ve önceki adımda sağlanan belgeleri Bilişsel Arama dizinine yönlendirir.

    try:
        result = search_client.upload_documents(documents=documents)
        print("Upload of new document succeeded: {}".format(result[0].succeeded))
    except Exception as ex:
        print (ex.message)
    
  3. Belgeleri arama hizmetinizdeki bir dizine göndermek için her adımı çalıştırın.

3 - Dizin arama

Bu adım search.client sınıfınınarama yöntemini kullanarak dizini nasıl sorgulayabileceğinizi gösterir.

  1. Aşağıdaki adım boş bir arama ()search=* yürütür ve rastgele belgelerin unranked listesini (arama puanı = 1,0) döndürür. Ölçüt olmadığından, tüm belgeler sonuçlara eklenir. Bu sorgu, her belgedeki alanlardan yalnızca iki tane yazdırır. Ayrıca sonuçlardaki tüm belgelerin sayısını (4) almak için ekler include_total_count=True .

    results =  search_client.search(search_text="*", include_total_count=True)
    
    print ('Total Documents Matching Query:', results.get_count())
    for result in results:
        print("{}: {}".format(result["HotelId"], result["HotelName"]))
    
  2. Sonraki sorgu, arama ifadesine ("wifi") terimlerin tamamını ekler. Bu sorgu sonuçların yalnızca deyimindeki alanları içerdiğini select belirtir. Geri gelen alanların sınırlanması, kablo üzerinden geri gönderilen veri miktarını en aza indirir ve arama gecikme süresini azaltır.

    results =  search_client.search(search_text="wifi", include_total_count=True, select='HotelId,HotelName,Tags')
    
    print ('Total Documents Matching Query:', results.get_count())
    for result in results:
        print("{}: {}: {}".format(result["HotelId"], result["HotelName"], result["Tags"]))
    
  3. Ardından, yalnızca derecelendirmesi 4'ten büyük olan otelleri azalan düzende sıralayarak bir filtre ifadesi uygulayın.

    results =  search_client.search(search_text="hotels", select='HotelId,HotelName,Rating', filter='Rating gt 4', order_by='Rating desc')
    
    for result in results:
        print("{}: {} - {} rating".format(result["HotelId"], result["HotelName"], result["Rating"]))
    
  4. Tek bir alanla eşleşen kapsam sorgusuna ekleyin search_fields .

    results =  search_client.search(search_text="sublime", search_fields='HotelName', select='HotelId,HotelName')
    
    for result in results:
        print("{}: {}".format(result["HotelId"], result["HotelName"]))
    
  5. Modeller model gezinti yapısı oluşturmak için kullanılabilecek etiketlerdir. Bu sorgu Category modellerini ve sayılarını döndürür.

    results =  search_client.search(search_text="*", facets=["Category"])
    
    facets = results.get_facets()
    
    for facet in facets["Category"]:
        print("    {}".format(facet))
    
  6. Bu örnekte, belirli bir belgeyi anahtarına göre arayın. Bir kullanıcı arama sonucunda bir belge seçtiğinde genellikle belgeyi döndürmek istersiniz.

    result = search_client.get_document(key="3")
    
    print("Details for hotel '3' are:")
    print("Name: {}".format(result["HotelName"]))
    print("Rating: {}".format(result["Rating"]))
    print("Category: {}".format(result["Category"]))
    
  7. Son örnekte otomatik tamamlama işlevini kullanacağız. Otomatik Tamamlama genellikle kullanıcı arama kutusuna yazarken olası eşleşmeleri sağlamak için arama kutusunda kullanılır.

    Dizin oluşturulduğunda, isteğin bir parçası olarak adlı sg bir öneri oluşturucu da oluşturulmuştur. Öneri oluşturucu tanımı, öneri oluşturucu istekleriyle olası eşleşmeleri bulmak için hangi alanların kullanılabileceğini belirtir. Bu örnekte, bu alanlar 'Etiketler', 'Adres/Şehir', 'Adres/Ülke' alanlarıdır. Otomatik tamamlamanın benzetimini yapmak için "sa" harflerini kısmi dize olarak geçirin. SearchClient'ın otomatik tamamlama yöntemi olası terim eşleşmelerini geri gönderir.

    search_suggestion = 'sa'
    results = search_client.autocomplete(search_text=search_suggestion, suggester_name="sg", mode='twoTerms')
    
    print("Autocomplete for:", search_suggestion)
    for result in results:
        print (result['text'])
    

Temizleme

Kendi aboneliğinizde çalışırken, projenin sonunda oluşturduğunuz kaynaklara hala ihtiyacınız olup olmadığını belirlemek iyi bir fikirdir. Çalışır durumda bırakılan kaynaklar maliyetlerin artmasına neden olabilir. Kaynakları teker teker silebilir veya tüm kaynak grubunu silerek kaynak kümesinin tamamını kaldırabilirsiniz.

Sol gezinti bölmesindeki Tüm kaynaklar veya Kaynak grupları bağlantısını kullanarak kaynakları portalda bulabilir ve yönetebilirsiniz.

Ücretsiz bir hizmet kullanıyorsanız üç dizin, dizin oluşturucu ve veri kaynağıyla sınırlı olduğunuzu unutmayın. Sınırın altında kalmak için portaldaki öğeleri tek tek silebilirsiniz.

Sonraki adımlar

Bu Python hızlı başlangıcında, Python SDK'sından azure.search.documents kitaplığını kullanarak temel iş akışı üzerinde çalıştınız. Dizin oluşturan, belgelerle yükleyen ve sorgular çalıştıran görevler gerçekleştirmiştiniz. Öğrenmeye devam etmek için aşağıdaki öğreticiyi deneyin.