Buat gudang pengetahuan menggunakan REST

Artikel
03/12/2024

Di Azure AI Search, penyimpanan pengetahuan adalah repositori konten yang dihasilkan AI 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 menjadikan kumpulan data awal tersedia, ulasan hotel terlebih dahulu diimpor ke Azure Blob Storage. Setelah pemrosesan, hasilnya disimpan sebagai gudang pengetahuan di Azure Table Storage.

Tip

Artikel ini menggunakan REST untuk penjelasan terperinci tentang setiap langkah. Unduh file REST jika Anda hanya ingin menjalankan perintah. Atau, Anda juga dapat membuat penyimpanan pengetahuan di portal Azure.

Prasyarat

Visual Studio Code dengan klien REST. Jika Anda memerlukan bantuan untuk memulai, lihat Mulai Cepat: Pencarian teks menggunakan REST.
Pencarian Azure AI. Buat layanan atau temukan yang sudah ada. Anda dapat menggunakan layanan gratis untuk latihan ini.
Azure Storage. Buat akun atau temukan akun yang sudah ada. Jenis akun harus StorageV2 (tujuan umum V2).

Set keterampilan dalam contoh ini menggunakan Azure AI Services untuk pengayaan. Karena beban kerja sangat kecil, layanan Azure AI diketuk di belakang layar untuk menyediakan pemrosesan gratis hingga 20 transaksi setiap hari. Beban kerja kecil berarti Anda dapat melewati pembuatan atau melampirkan sumber daya multi-layanan Azure AI.

Mengunggah data ke Azure Storage dan mendapatkan string koneksi

Unduh HotelReviews_Free.csv. CSV ini berisi 19 umpan balik pelanggan tentang satu hotel (berasal dari Kaggle.com).
Di portal Azure, temukan akun penyimpanan Anda dan gunakan Browser Penyimpanan untuk membuat kontainer blob bernama ulasan hotel.
Pilih Unggah di bagian atas halaman untuk memuat file HotelReviews-Free.csv yang Anda unduh dari langkah sebelumnya.
Di sebelah kiri, pilih Kunci Akses, pilih Perlihatkan Kunci, lalu salin string koneksi untuk key1 atau key2. Akses penuh string koneksi memiliki format berikut:

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

Catatan

Lihat Koneksi menggunakan identitas terkelola jika Anda tidak ingin memberikan data sensitif pada string koneksi.

Menyalin kunci dan URL

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

Masuk ke portal Azure, navigasikan ke halaman Gambaran Umum, dan salin URL. Contoh titik akhir mungkin terlihat sepertihttps://mydemo.search.windows.net.
Di bawah Pengaturan> Keys, salin kunci admin. Kunci admin digunakan untuk menambahkan, memodifikasi, dan menghapus objek. Ada dua kunci admin yang dapat dipertukarkan. Salin salah satu.

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

Buat indeks

Buat Indeks (REST) membuat indeks pencarian pada layanan pencarian. 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.

Buka file teks baru di Visual Studio Code.

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
@storageConnection = PUT-YOUR-STORAGE-CONNECTION-STRING-HERE
@blobContainer = PUT-YOUR-CONTAINER-NAME-HERE (hotel-reviews)

Simpan file dengan .rest ekstensi file.

Tempelkan dalam contoh berikut untuk membuat permintaan indeks.

### Create a new index
POST {{baseUrl}}/indexes?api-version=2023-11-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 }
        ]
    }

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

Membuat Sumber Data membuat koneksi sumber data di Azure AI Search.

Tempelkan dalam contoh berikut untuk membuat sumber data.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2023-11-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
    }

Pilih Kirim Permintaan.

Membuat skillset

Set keterampilan mendefinisikan pengayaan (keterampilan) dan penyimpanan pengetahuan Anda. Buat Skillset membuat objek di layanan pencarian Anda.

Tempelkan dalam contoh berikut untuk membuat set keterampilan.

### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2023-11-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 adalah bagian dari dokumen yang diperkaya yang ingin Anda simpan. Output adalah konsolidasi simpul 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.

Tempelkan dalam contoh berikut untuk membuat pengindeks.

### Create indexer
POST {{baseUrl}}/indexers?api-version=2023-11-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" }
    ]
}

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 bidang membuat "AzureSearch_DocumentKey" adalah pengenal 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 akan merespons dengan pesan sukses 201.

### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/hotel-reviews-kstore-idxr/status?api-version=2023-11-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-idxr/docs/search?api-version=2023-11-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 portal Azure

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

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

Screenshot of the knowledge store tables in Storage Browser

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

Table	Deskripsi
`hotelReviews1Document`	Berisi bidang yang diteruskan dari CSV, seperti reviews_date dan reviews_text.
`hotelReviews2Pages`	Berisi bidang yang diperkaya yang dibuat oleh set keterampilan, seperti skor sentimen dan teks yang diterjemahkan.
`hotelReviews3KeyPhrases`	Berisi daftar panjang dari frase kunci saja.
`hotelReviews4InlineProjectionDocument`	Sebagai alternatif untuk tabel pertama, menggunakan pembentukan sebaris, bukan keterampilan Shaper, guna membentuk data untuk proyeksi.
`hotelReviews5InlineProjectionPages`	Sebagai alternatif untuk tabel kedua, menggunakan pembentukan sebaris.
`hotelreviews6InlineProjectionKeyPhrases`	Sebagai alternatif untuk tabel ketiga, menggunakan pembentukan sebaris.

Penghapusan

Saat bekerja dengan langganan Anda sendiri, sebaiknya identifikasi apakah Anda masih membutuhkan sumber daya yang Anda buat di akhir proyek. Sumber daya yang dibiarkan berjalan dapat menghabiskan uang Anda. 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 portal, menggunakan tautan Semua sumber daya atau Grup sumber daya di panel navigasi kiri.

Langkah berikutnya

Sekarang setelah Anda memperkaya data Anda dengan menggunakan layanan Azure AI dan memproyeksikan hasilnya ke penyimpanan pengetahuan, Anda dapat menggunakan Storage Explorer atau aplikasi lain untuk menjelajahi himpunan data yang diperkaya.

Memulai dengan Storage Explorer

Bagikan melalui