REST kullanarak bilgi deposu oluşturma

  • Makale

Azure AI Search'te bilgi deposu, arama dışı senaryolar için kullanılan yapay zeka tarafından oluşturulan içeriğin deposudur. Bilgi depoyu dizin oluşturucu ve beceri kümesi kullanarak oluşturur ve çıkışı depolamak için Azure Depolama'yı belirtirsiniz. Bilgi deposu dolduruldıktan sonra içeriği keşfetmek için Depolama Gezgini veya Power BI gibi araçları kullanın.

Bu makalede, bir bilgi mağazasında otel konaklamalarına ilişkin bir dizi müşteri incelemesini almak, zenginleştirmek ve keşfetmek için REST API'yi kullanacaksınız. Bilgi deposu, kaynaktan çekilen özgün metin içeriğinin yanı sıra yaklaşım puanı, anahtar ifade ayıklama, dil algılama ve İngilizce olmayan müşteri yorumlarının metin çevirisini içeren yapay zeka tarafından oluşturulan içeriği içerir.

İlk veri kümesini kullanılabilir hale getirmek için, otel incelemeleri ilk olarak Azure Blob Depolama içeri aktarılır. İşlem sonrasında sonuçlar Azure Tablo Depolama'da bilgi deposu olarak kaydedilir.

İpucu

Bu makalede, her adımın ayrıntılı açıklamaları için REST kullanılır. Yalnızca komutları çalıştırmak istiyorsanız REST dosyasını indirin. Alternatif olarak, Azure portalında bir bilgi deposu da oluşturabilirsiniz.

Önkoşullar

Bu örneklerdeki beceri kümesi zenginleştirmeler için Azure Yapay Zeka Hizmetleri'ni kullanır. İş yükü çok küçük olduğundan, Azure yapay zeka hizmetleri arka planda dokunarak günde 20 işlemeye kadar ücretsiz işlem sağlar. Küçük bir iş yükü, Azure AI çoklu hizmet kaynağı oluşturmayı veya eklemeyi atlayabileceğiniz anlamına gelir.

Azure Depolama'ya veri yükleme ve bağlantı dizesi alma

  1. HotelReviews_Free.csv indirin. Bu CSV tek bir otel hakkında 19 müşteri geri bildirimi içerir (Kaggle.com kaynaklanır).

  2. Azure portalında depolama hesabınızı bulun ve Storage Browser'ı kullanarak hotel-reviews adlı bir blob kapsayıcısı oluşturun.

  3. Önceki adımda indirdiğiniz HotelReviews-Free.csv dosyasını yüklemek için sayfanın üst kısmındaki Karşıya Yükle'yi seçin.

    Karşıya yüklenen dosya ve sol gezinti bölmesi ile Depolama Tarayıcısı'nın ekran görüntüsü

  4. Sol tarafta Erişim Anahtarları'nı seçin, Anahtarları Göster'i seçin ve ardından anahtar1 veya anahtar2 için bağlantı dizesi kopyalayın. Tam erişim bağlantı dizesi aşağıdaki biçime sahiptir:

"knowledgeStore": {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-ACCOUNT-NAME>;AccountKey=<YOUR-ACCOUNT-KEY>;EndpointSuffix=core.windows.net;"
}

Not

bağlantı dizesi hassas veriler sağlamak istemiyorsanız bkz. Yönetilen kimlik kullanarak bağlanma.

Anahtar ve URL kopyalama

Bu örnekte REST çağrıları, arama hizmeti uç noktasını gerektirir ve her istekte bir API anahtarı kullanır. Bu değerleri Azure portalından alabilirsiniz.

  1. Azure portalında oturum açın, Genel Bakış sayfasına gidin ve URL'yi kopyalayın. Örnek uç nokta https://mydemo.search.windows.net şeklinde görünebilir.

  2. Ayarlar>Anahtarları'nın altında bir yönetici anahtarı kopyalayın. Yönetici anahtarları nesneleri eklemek, değiştirmek ve silmek için kullanılır. Değiştirilebilir iki yönetici anahtarı vardır. İkisini de kopyalayın.

    Azure portalındaki URL ve API anahtarlarının ekran görüntüsü.

Geçerli bir API anahtarı, isteği gönderen uygulama ile bunu işleyen arama hizmeti arasında istek temelinde güven oluşturur.

Dizin oluşturma

Dizin Oluştur (REST), arama hizmetinde bir arama dizini oluşturur. Arama dizini bir bilgi deposuyla ilişkili değildir, ancak dizin oluşturucu için bir tane gerekir. Arama dizini, sorgu istekleri göndererek keşfedebileceğiniz bilgi deposuyla aynı içeriği içerir.

  1. Visual Studio Code'da yeni bir metin dosyası açın.

  2. Değişkenleri arama uç noktasına ve daha önce topladığınız API anahtarına ayarlayın.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@apiKey = PUT-YOUR-ADMIN-API-KEY-HERE
@storageConnection = PUT-YOUR-STORAGE-CONNECTION-STRING-HERE
@blobContainer = PUT-YOUR-CONTAINER-NAME-HERE (hotel-reviews)

  3. Dosyayı bir .rest dosya uzantısıyla kaydedin.

  4. Dizin isteğini oluşturmak için aşağıdaki örneği yapıştırın.

    ### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-idx",  
        "fields": [
            { "name": "name", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_date", "type": "Edm.DateTimeOffset", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_rating", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_text", "type": "Edm.String", "filterable": false,  "sortable": false, "facetable": false },
            { "name": "reviews_title", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_username", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "AzureSearch_DocumentKey", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false, "key": true },
            { "name": "language", "type": "Edm.String", "filterable": true, "sortable": false, "facetable": true },
            { "name": "translated_text", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false },
            { "name": "sentiment", "type": "Collection(Edm.String)", "searchable": false, "filterable": true, "retrievable": true, "sortable": false, "facetable": true },
            { "name": "keyphrases", "type": "Collection(Edm.String)", "filterable": true, "sortable": false, "facetable": true }
        ]
    }

  5. İstek gönder’i seçin. Bir HTTP/1.1 201 Created yanıtınız olmalıdır ve yanıt gövdesi dizin şemasının JSON gösterimini içermelidir.

Veri kaynağı oluşturma

Veri Kaynağı Oluştur, Azure AI Search'te bir veri kaynağı bağlantısı oluşturur.

  1. Veri kaynağını oluşturmak için aşağıdaki örneği yapıştırın.

    ### Create a data source
POST {{baseUrl}}/datasources?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-ds",
        "description": null,
        "type": "azureblob",
        "subtype": null,
        "credentials": {
            "connectionString": "{{storageConnectionString}}"
        },
        "container": {
            "name": "{{blobContainer}}",
            "query": null
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null
    }

  2. İstek gönder’i seçin.

Beceri kümesi oluşturma

Beceri kümesi zenginleştirmeleri (becerileri) ve bilgi deponuzu tanımlar. Beceri Kümesi Oluştur, nesneyi arama hizmetinizde oluşturur.

  1. Beceri kümesini oluşturmak için aşağıdaki örneği yapıştırın.

    ### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-ss",
        "description": "Skillset to detect language, translate text, extract key phrases, and score sentiment",
        "skills": [ 
            {
                "@odata.type": "#Microsoft.Skills.Text.SplitSkill", 
                "context": "/document/reviews_text", "textSplitMode": "pages", "maximumPageLength": 5000,
                "inputs": [ 
                    { "name": "text", "source": "/document/reviews_text" }
                ],
                "outputs": [
                    { "name": "textItems", "targetName": "pages" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
                "context": "/document/reviews_text/pages/*",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text/pages/*" },
                    { "name": "languageCode", "source": "/document/language" }
                ],
                "outputs": [
                    { "name": "sentiment", "targetName": "sentiment" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
                "context": "/document",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text" }
                ],
                "outputs": [
                    { "name": "languageCode", "targetName": "language" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.TranslationSkill",
                "context": "/document/reviews_text/pages/*",
                "defaultFromLanguageCode": null,
                "defaultToLanguageCode": "en",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text/pages/*" }
                ],
                "outputs": [
                    { "name": "translatedText", "targetName": "translated_text" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
                "context": "/document/reviews_text/pages/*",
                "inputs": [
                    { "name": "text",  "source": "/document/reviews_text/pages/*" },
                    { "name": "languageCode",  "source": "/document/language" }
                ],
                "outputs": [
                    { "name": "keyPhrases" , "targetName": "keyphrases" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
                "context": "/document",
                "inputs": [
                    { "name": "name",  "source": "/document/name" },
                    { "name": "reviews_date",  "source": "/document/reviews_date" },
                    { "name": "reviews_rating",  "source": "/document/reviews_rating" },
                    { "name": "reviews_text",  "source": "/document/reviews_text" },
                    { "name": "reviews_title",  "source": "/document/reviews_title" },
                    { "name": "reviews_username",  "source": "/document/reviews_username" },
                    { "name": "AzureSearch_DocumentKey",  "source": "/document/AzureSearch_DocumentKey" },
                    {
                    "name": "pages",
                    "sourceContext": "/document/reviews_text/pages/*",
                    "inputs": [
                        {
                        "name": "languageCode",
                        "source": "/document/language"
                        },
                        {
                        "name": "translatedText",
                        "source": "/document/reviews_text/pages/*/translated_text"
                        },
                        { 
                        "name": "sentiment",
                        "source": "/document/reviews_text/pages/*/sentiment"
                        },
                        {
                        "name": "keyPhrases",
                        "source": "/document/reviews_text/pages/*/keyphrases/*"
                        },
                        {
                        "name": "Page",
                        "source": "/document/reviews_text/pages/*"
                        }
                    ]
                    }
                ],
                "outputs": [
                    { "name": "output" , "targetName": "tableprojection" }
                ]
            }
        ],
        "knowledgeStore": {
            "storageConnectionString": "{{storageConnectionString}}",
            "projections": [
                {
                    "tables": [
                        { "tableName": "hotelReviews1Document", "generatedKeyName": "Documentid", "source": "/document/tableprojection" },
                        { "tableName": "hotelReviews2Pages", "generatedKeyName": "Pagesid", "source": "/document/tableprojection/pages/*" },
                        { "tableName": "hotelReviews3KeyPhrases", "generatedKeyName": "KeyPhrasesid", "source": "/document/tableprojection/pages/*/keyPhrases/*" }
                    ],
                    "objects": []
                },
                {
                    "tables": [
                        { 
                            "tableName": "hotelReviews4InlineProjectionDocument", "generatedKeyName": "Documentid", "sourceContext": "/document",
                            "inputs": [
                                { "name": "name", "source": "/document/name"},
                                { "name": "reviews_date", "source": "/document/reviews_date"},
                                { "name": "reviews_rating", "source": "/document/reviews_rating"},
                                { "name": "reviews_username", "source": "/document/reviews_username"},
                                { "name": "reviews_title", "source": "/document/reviews_title"},
                                { "name": "reviews_text", "source": "/document/reviews_text"},
                                { "name": "AzureSearch_DocumentKey", "source": "/document/AzureSearch_DocumentKey" }
                            ]
                        },
                        { 
                            "tableName": "hotelReviews5InlineProjectionPages", "generatedKeyName": "Pagesid", "sourceContext": "/document/reviews_text/pages/*",
                            "inputs": [
                                { "name": "Sentiment", "source": "/document/reviews_text/pages/*/sentiment"},
                                { "name": "LanguageCode", "source": "/document/language"},
                                { "name": "Keyphrases", "source": "/document/reviews_text/pages/*/keyphrases"},
                                { "name": "TranslatedText", "source": "/document/reviews_text/pages/*/translated_text"},
                                { "name": "Page", "source": "/document/reviews_text/pages/*" }
                            ]
                        },
                        { 
                            "tableName": "hotelReviews6InlineProjectionKeyPhrases", "generatedKeyName": "kpidv2", "sourceContext": "/document/reviews_text/pages/*/keyphrases/*",
                            "inputs": [
                                { "name": "Keyphrases", "source": "/document/reviews_text/pages/*/keyphrases/*" }
                            ]
                        }
                    ],
                    "objects": []
                }
            ]
        }
    }

Önemli noktalar:

  • Shaper becerisi, bilgi deposu tanımı için önemlidir. Verilerin bilgi deposunun tablolarına nasıl aktığını belirtir. Girişler, zenginleştirilmiş belgenin depolamak istediğiniz bölümleridir. Çıkış, düğümlerin tek bir yapıda birleştirilmesidir.

  • Projeksiyonlar bilgi deponuzun tablolarını, nesnelerini ve bloblarını belirtir. Her projeksiyon öğesi, Azure Depolama'da oluşturulacak sütun veya alanın sayısını belirtir "name" . , "source" şekillendirici çıkışının hangi bölümünün bu alana veya sütuna atandığını belirtir.

Dizin oluşturucu oluşturma

Dizin Oluşturucu Oluştur, dizin oluşturucuyu oluşturur ve çalıştırır. Dizin oluşturucu yürütmesi, belgeleri kırarak, metin ve görüntüleri ayıklayarak ve beceri kümesini başlatarak başlar. Dizin oluşturucu, oluşturduğunuz diğer nesneleri denetler: veri kaynağı, dizin ve beceri kümesi.

  1. Dizin oluşturucuyu oluşturmak için aşağıdaki örneği yapıştırın.

    ### Create indexer
POST {{baseUrl}}/indexers?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-idxr",
        "dataSourceName": "hotel-reviews-kstore-ds",
        "skillsetName": "hotel-reviews-kstore-ss",
        "targetIndexName": "hotel-reviews-kstore-idx",
        "parameters": {
            "configuration": {
                "dataToExtract": "contentAndMetadata",
                "parsingMode": "delimitedText",
                "firstLineContainsHeaders": true,
                "delimitedTextDelimiter": ","
    }
},
"fieldMappings": [
    {
        "sourceFieldName": "AzureSearch_DocumentKey",
        "targetFieldName": "AzureSearch_DocumentKey",
        "mappingFunction": { "name": "base64Encode" }
    }
],
"outputFieldMappings": [
    { "sourceFieldName": "/document/reviews_text/pages/*/Keyphrases/*", "targetFieldName": "Keyphrases" },
    { "sourceFieldName": "/document/Language", "targetFieldName": "Language" },
    { "sourceFieldName": "/document/reviews_text/pages/*/Sentiment", "targetFieldName": "Sentiment" }
    ]
}

  2. Dizin oluşturucuyu oluşturmak ve çalıştırmak için İstek gönder'i seçin. Bu adımın tamamlanması birkaç dakika sürer.

Önemli noktalar:

  • parameters/configuration nesnesi, dizin oluşturucunun verileri nasıl aldırıyor olduğunu denetler. Bu durumda, giriş verileri üst bilgi satırı ve virgülle ayrılmış değerler içeren tek bir CSV dosyasında yer alır.

  • Alan eşlemeleri "AzureSearch_DocumentKey" oluşturur, blob dizin oluşturucu tarafından oluşturulan her belge için benzersiz bir tanımlayıcıdır (meta veri depolama yoluna göre).

  • Çıktı alanı eşlemeleri, zenginleştirilmiş alanların arama dizinindeki alanlarla nasıl eşleneceğini belirtir. Çıktı alanı eşlemeleri bilgi depolarında kullanılmaz (bilgi depoları fiziksel veri yapılarını ifade etmek için şekiller ve projeksiyonlar kullanır).

Durumu kontrol et

Her isteği gönderdikten sonra arama hizmeti 201 başarılı iletisiyle yanıt vermelidir.

### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/hotel-reviews-kstore-idxr/status?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

Birkaç dakika sonra, içeriği incelemek için dizini sorgulayabilirsiniz. Dizini kullanmasanız bile, bu adım beceri kümesinin beklenen çıkışı ürettiğini doğrulamanın kullanışlı bir yoludur.

### Query the index (indexer status must be "success" before querying the index)
POST {{baseUrl}}/indexes/hotel-reviews-kstore-idxr/docs/search?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "*",
    "select": "reviews_title, reviews_username, language, translated_text, sentiment",
    "count": true
  }

Azure portalında tabloları denetleme

Azure portalında Azure Depolama hesabınıza geçin ve yeni tabloları görüntülemek için Depolama Tarayıcısı'nı kullanın. Beceri kümesinde tanımlanan her projeksiyon için bir tane olan altı tablo görmeniz gerekir.

Her tablo, sorgulardaki tabloları çapraz bağlamak için gereken kimliklerle oluşturulur. Tabloyu açtığınızda, işlem hattı tarafından eklenen içerik alanlarını görüntülemek için bu alanları kaydırın.

Depolama Tarayıcısı'ndaki bilgi deposu tablolarının ekran görüntüsü

Bu kılavuzda, bilgi deposu bir tabloyu şekillendirmenin ve yapılandırmanın farklı yollarını gösteren çeşitli tablolardan oluşur. Tablo 1-3 arası tablolarda, sütunları ve satırları belirlemek için bir Shaper becerisinin çıkışı kullanılır. Dörtten altıya kadar olan tablolar, yansıtmanın içine eklenmiş satır içi şekillendirme yönergelerinden oluşturulur. Aynı sonucu elde etmek için iki yaklaşımdan birini kullanabilirsiniz.

Table Açıklama
hotelReviews1Document CSV'den ileriye doğru taşınan reviews_date ve reviews_text gibi alanları içerir.
hotelReviews2Pages Beceri kümesi tarafından oluşturulan yaklaşım puanı ve çevrilmiş metin gibi zenginleştirilmiş alanlar içerir.
hotelReviews3KeyPhrases Yalnızca anahtar ifadelerin uzun bir listesini içerir.
hotelReviews4InlineProjectionDocument İlk tabloya alternatif olarak, projeksiyon verilerini şekillendirmek için Şekillendirici becerisi yerine satır içi şekillendirme kullanılır.
hotelReviews5InlineProjectionPages Satır içi şekillendirme kullanarak ikinci tabloya alternatif olarak.
hotelreviews6InlineProjectionKeyPhrases Satır içi şekillendirme kullanarak üçüncü tabloya alternatif olarak.

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.

Sonraki adımlar

Azure yapay zeka hizmetlerini kullanarak verilerinizi zenginleştirdiğinize ve sonuçları bir bilgi deposuna yansıttığınız için, zenginleştirilmiş veri kümenizi keşfetmek için Depolama Gezgini veya diğer uygulamaları kullanabilirsiniz.

Depolama Gezgini ile çalışmaya başlama