REST kullanarak bilgi deposu oluşturma

Not

Azure Yapay Zeka Arama Azure portalı, REST API'leri ve Azure SDK’ları aracılığıyla kullanılabilir. Ayrıca kuruluş içeriğini Microsoft Foundry portalındaki aracılar için yeniden kullanılabilir, izin kullanan bilgi bankalarına dönüştüren yönetilen bilgi katmanı Foundry IQ'yu temel alır.

Not

Knowledge mağazaları Azure Depolama'da bulunan ve Azure Yapay Zeka Arama beceri kümelerinin çıkışlarını içeren ikincil depolama. Bunlar, aracısal alma iş akışlarında kullanılan bilgi kaynaklarından ve bilgi bankalarından ayrıdır.

Azure Yapay Zeka Arama'da bilgi deposu, arama dışı senaryolar için kullanılan beceriyle üretilen içerik bir depodur. Bilgi depoyu bir dizin oluşturucu ve beceri kümesi kullanarak oluşturur ve çıkışı depolamak için Azure Depolama 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 Storage bilgi deposu olarak kaydedilir.

İpucu

Bu makalede, her adımın ayrıntılı açıklamaları için REST kullanılır. Komutları çalıştırmak istiyorsanız REST dosyasını indir.

Önkoşullar

Bu örnekteki beceri kümesi zenginleştirmeler için Döküm Araçları'nı kullanır. İş yükü çok küçük olduğundan, Döküm Araçları arka planda kullanılarak günde en fazla 20 işlem için ücretsiz işlem sağlar. Küçük bir iş yükü, Microsoft Foundry kaynağı oluşturmayı veya eklemeyi atlayabileceğiniz anlamına gelir.

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

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

  2. Azure portal'da storage 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_data.csv dosyasını yüklemek için sayfanın üst kısmındaki Karşıya Yükle'yi seçin.

    Yüklenen dosya ve sol gezinti bölmesi ile Storage Browser ekran-görüntüsü

  4. Sol tarafta Access Keys öğesini seçin, Anahtarları Göster'i seçin ve sonrasında anahtar1 veya anahtar2 için bağlantı dizesini kopyalayın. Tam erişim bağlantı dizisi aşağıdaki biçime sahiptir:

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

Not

Yönetilen bir kimlik kullanarak bağlantı kurma hakkında bilgi edinmek için Bağlan'a bakın; bu, bağlantı dizesinde hassas veriler vermenize gerek kalmaz.

Anahtar ve URL kopyalama

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

  1. Azure portalında arama hizmetinize gidin.

  2. Genel Bakış sayfasında uç nokta URL'sini kopyalayın. Örnek uç nokta https://mydemo.search.windows.net gibi görünebilir.

  3. Ayarlar>Anahtarları'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 search service arasında istek temelinde güven oluşturur.

Dizin oluşturma

Create Index (REST), arama hizmeti üzerinde 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
 @storageConnectionString = 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=2026-04-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 Yapay Zeka Arama üzerinde 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=2026-04-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, arama hizmetinde nesneyi 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=2026-04-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. Çıktı, düğümlerin tek bir yapıda bütünleştirilmesidir.

  • Projeksiyonlar bilgi deponuzun tablolarını, nesnelerini ve bloblarını belirtir. Her projeksiyon öğesi, Azure Depolama'da oluşturulacak sütun veya alanın "name" belirtir. , "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. Dizinleyici çalışması, belgeleri çözerek, 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=2026-04-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.

  • AzureSearch_DocumentKey için alan eşlemesi, blob dizin oluşturucu tarafından oluşturulan her belge için benzersiz bir tanımlayıcı oluşturur (meta veri storage 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 bir isteği gönderdikten sonra, arama servisi 201 başarı mesajı ile yanıt vermelidir.

### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/hotel-reviews-kstore-idxr/status?api-version=2026-04-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-idx/docs/search?api-version=2026-04-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 tabloları denetleme

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

Her bir tablo, sorgulardaki tabloları çapraz bağlamak için gereken ID'lerle oluşturulur. Tabloyu açtığınızda, işlem hattı tarafından eklenen içerik alanlarını görmek için bu alanları atlayarak kaydırın.

Storage Browser'daki bilgi deposu tablolarının ekran görüntüsü

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

Tablo Açıklama
hotelReviews1Document CSV'den ileriye doğru taşınan reviews_date ve reviews_text gibi alanları içerir.
hotelReviews2Pages Beceri kümesiyle oluşturulan duygu 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 İkinci tabloya satır içi şekillendirme kullanarak bir alternatif.
hotelReviews6InlineProjectionKeyPhrases Satır içi şekillendirme kullanarak üçüncü tabloya bir alternatif.

Temizleme

Kendi aboneliğinizde çalışırken, bir proje 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ı Azure portal bulabilir ve yönetebilirsiniz.

Sonraki adımlar

Artık Döküm Araçları'nı 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şlayın

  • Last updated on