Buat gudang pengetahuan menggunakan REST

Catatan

Knowledge store adalah storage sekunder yang ada di Azure Storage dan berisi output dari skillset Pencarian Azure AI. Mereka terpisah dari sumber pengetahuan dan pangkalan pengetahuan, yang digunakan dalam alur kerja pengambilan agenik .

Di Pencarian Azure AI, penyimpanan pengetahuan adalah repositori konten yang dihasilkan oleh kecerdasan yang digunakan untuk skenario non-pencarian. Anda membuat penyimpanan pengetahuan menggunakan pengindeks dan set keterampilan, dan menentukan Azure Storage untuk menyimpan output. Setelah penyimpanan pengetahuan diisi, gunakan alat seperti Storage Explorer atau Power BI untuk menjelajahi konten.

Dalam artikel ini, Anda menggunakan REST API untuk menyerap, memperkaya, dan menjelajahi serangkaian ulasan pelanggan tentang menginap di hotel di toko pengetahuan. Penyimpanan pengetahuan berisi konten teks asli yang ditarik dari sumbernya, ditambah konten yang dihasilkan AI yang mencakup skor sentimen, ekstraksi frasa kunci, deteksi bahasa, dan terjemahan teks komentar pelanggan non-Bahasa Inggris.

Untuk membuat himpunan data awal tersedia, ulasan hotel pertama kali diimpor ke Azure Blob Storage. Pasca-pemrosesan, hasilnya disimpan sebagai penyimpanan pengetahuan di Storage Tabel Azure.

Petunjuk / Saran

Artikel ini menggunakan REST untuk penjelasan terperinci tentang setiap langkah. Unduh file REST jika Anda hanya ingin menjalankan perintah.

Prasyarat

Skillset dalam contoh ini menggunakan Foundry Tools untuk pengayaan. Karena beban kerja sangat kecil, Foundry Tools digunakan di belakang layar untuk menyediakan pemrosesan gratis hingga 20 transaksi per hari. Beban kerja kecil berarti Anda dapat melewati pembuatan atau melampirkan sumber daya Microsoft Foundry.

Mengunggah data ke Azure Storage dan mendapatkan string koneksi

  1. Unduh HotelReviews_data.csv. CSV ini berisi 19 umpan balik pelanggan tentang satu hotel (berasal dari Kaggle.com).

  2. Di Azure portal, temukan akun storage Anda dan gunakan browser Storage untuk membuat kontainer blob bernama hotel-reviews.

  3. Pilih Unggah di bagian atas halaman untuk memuat file HotelReviews_data.csv yang Anda unduh dari langkah sebelumnya.

    Screenshot browser Storage dengan file yang diunggah dan panel navigasi kiri

  4. Di sebelah kiri, pilih Kunci Akses, pilih Tampilkan Kunci, lalu salin string koneksi dari key1 atau key2. String koneksi dengan akses penuh memiliki format berikut:

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

Catatan

Lihat Hubungkan menggunakan identitas terkelola jika Anda tidak ingin menyediakan data sensitif di string koneksi.

Menyalin kunci dan URL

Dalam contoh ini, panggilan REST memerlukan titik akhir search service dan menggunakan kunci API pada setiap permintaan. Anda bisa mendapatkan nilai-nilai ini dari Azure portal.

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Pada halaman Gambaran Umum , salin URL titik akhir. Contoh titik akhir mungkin terlihat seperti https://mydemo.search.windows.net.

  3. PadaKunci>, salin kunci admin. Kunci admin digunakan untuk menambahkan, memodifikasi, dan menghapus objek. Ada dua kunci admin yang dapat dipertukarkan. Salin salah satu.

    Screenshot url dan kunci API di Azure portal.

Kunci API yang valid menetapkan kepercayaan, berdasarkan per permintaan, antara aplikasi yang mengirim permintaan dan search service menanganinya.

Buat indeks

Buat Indeks (REST) membuat indeks pencarian di search service. Indeks pencarian tidak terkait dengan penyimpanan pengetahuan, tetapi pengindeks memerlukannya. Indeks pencarian berisi konten yang sama dengan penyimpanan pengetahuan, yang dapat Anda jelajahi dengan mengirim permintaan kueri.

  1. Buka file teks baru di kode Visual Studio.

  2. Atur variabel ke titik akhir pencarian dan kunci API yang Anda kumpulkan sebelumnya.

    @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. Simpan file dengan .rest ekstensi file.

  4. Tempelkan dalam contoh berikut untuk membuat permintaan indeks.

    ### 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. Pilih Kirim Permintaan. Anda harus memiliki HTTP/1.1 201 Created respons dan isi respons harus menyertakan representasi JSON dari skema indeks.

Membuat sumber data

Buat Sumber Data membuat koneksi sumber data pada Pencarian Azure AI.

  1. Tempelkan dalam contoh berikut untuk membuat sumber data.

    ### 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. Pilih Kirim Permintaan.

Mengembangkan keterampilan

Set keterampilan mendefinisikan kemampuan (keterampilan) dan gudang pengetahuan Anda. Buat Skillset membuat objek pada layanan pencarian Anda.

  1. Tempelkan contoh berikut untuk membuat keterampilan.

    ### 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": []
                }
            ]
        }
    }

Poin utama:

  • Keterampilan Shaper penting untuk definisi penyimpanan pengetahuan. Ini menentukan bagaimana data mengalir ke tabel penyimpanan pengetahuan. Input-input tersebut adalah bagian dari dokumen yang diperkaya yang ingin Anda simpan. Output adalah konsolidasi node ke dalam satu struktur.

  • Proyeksi menentukan tabel, objek, dan blob penyimpanan pengetahuan Anda. Setiap item proyeksi menentukan "name" kolom atau bidang yang akan dibuat di Azure Storage. "source" menentukan bagian mana dari output pembentuk yang ditetapkan ke bidang atau kolom tersebut.

Membuat pengindeks

Membuat Pengindeks membuat dan menjalankan pengindeks. Eksekusi pengindeks dimulai dengan memecahkan dokumen, mengekstrak teks dan gambar, dan menginisialisasi set keterampilan. Pengindeks memeriksa objek lain yang Anda buat: sumber data, indeks, dan set keterampilan.

  1. Tempelkan dalam contoh berikut untuk membuat pengindeks.

    ### 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. Pilih Kirim permintaan untuk membuat dan menjalankan pengindeks. Langkah ini membutuhkan waktu beberapa menit untuk diselesaikan.

Poin utama:

  • Objek parameters/configuration mengontrol cara pemberi indeks menelan data. Dalam hal ini, data input berada dalam satu file CSV yang memiliki baris header dan nilai yang dipisahkan tanda koma.

  • Pemetaan kolom untuk AzureSearch_DocumentKey membuat pengidentifikasi unik untuk setiap dokumen yang dihasilkan oleh pengindeks blob (berdasarkan jalur penyimpanan metadata).

  • Pemetaan bidang keluaran menentukan bagaimana bidang yang diperkaya dipetakan ke bidang dalam indeks pencarian. Pemetaan bidang output tidak digunakan di penyimpanan pengetahuan (penyimpanan pengetahuan menggunakan bentuk dan proyeksi untuk mengekspresikan struktur data fisik).

Memeriksa status

Setelah Anda mengirim setiap permintaan, layanan pencarian harus merespons dengan pesan keberhasilan 201.

### 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}}

Setelah beberapa menit, Anda bisa mengkueri indeks untuk memeriksa konten. Bahkan jika Anda tidak menggunakan indeks, langkah ini adalah cara mudah untuk mengonfirmasi bahwa set keterampilan menghasilkan output yang diharapkan.

### 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
  }

Periksa tabel di Azure portal

Di Azure portal, beralihlah ke akun Azure Storage Anda dan gunakan browser Storage untuk melihat tabel baru. Anda akan melihat enam tabel, satu untuk setiap proyeksi yang didefinisikan dalam kumpulan keterampilan.

Setiap tabel dihasilkan dengan ID yang diperlukan untuk penghubungan silang tabel dalam kueri. Saat Anda membuka tabel, gulir melewati bidang ini untuk melihat bidang konten yang ditambahkan oleh alur.

Screenshot tabel penyimpanan pengetahuan di Browser Storage

Dalam panduan ini, penyimpanan pengetahuan terdiri dari berbagai tabel yang menunjukkan berbagai cara untuk membentuk dan menyusun data. Tabel satu hingga tiga menggunakan output dari keterampilan Shaper untuk menentukan kolom dan baris. Tabel empat hingga enam dibuat dari instruksi pembentukan sebaris yang disematkan dalam proyeksi itu sendiri. Anda dapat menggunakan salah satu pendekatan untuk mencapai hasil yang sama.

Tabel Deskripsi
hotelReviews1Document Berisi bidang yang diambil dari CSV, seperti reviews_date dan reviews_text.
hotelReviews2Pages Berisi bidang yang diperkaya yang dibuat oleh kumpulan skill, seperti skor sentimen dan teks yang diterjemahkan.
hotelReviews3KeyPhrases Berisi daftar panjang dari frase kunci saja.
hotelReviews4InlineProjectionDocument Sebagai alternatif untuk tabel pertama, menggunakan pembentukan data sebaris sebagai pengganti fitur Shaper untuk membentuk data dalam proyeksi.
hotelReviews5InlineProjectionPages Sebagai alternatif untuk tabel kedua, menggunakan pembentukan sebaris.
hotelReviews6InlineProjectionKeyPhrases Sebagai alternatif untuk tabel ketiga, menggunakan pembentukan sebaris.

Pembersihan

Saat Anda bekerja dalam langganan Anda sendiri, ada baiknya di akhir project untuk mengidentifikasi apakah Anda masih memerlukan sumber daya yang Anda buat. Sumber daya yang dibiarkan berjalan dapat merugikan Anda secara finansial. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus seluruh rangkaian sumber daya.

Anda dapat menemukan dan mengelola sumber daya di Azure portal, menggunakan Semua sumber daya atau grup Resource di panel navigasi kiri.

Langkah berikutnya

Setelah memperkaya data dengan menggunakan Foundry Tools dan memproyeksikan hasilnya ke penyimpanan pengetahuan, Anda dapat menggunakan Storage Explorer atau aplikasi lain untuk menjelajahi himpunan data yang diperkaya.

Mulai dengan Storage Explorer

  • Last updated on