Buat gudang pengetahuan menggunakan REST
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 Menyambungkan 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 seperti
https://mydemo.search.windows.net
.Di bawah Kunci Pengaturan>, 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=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 } ] }
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=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 }
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=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": [] } ] } }
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=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" } ] }
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=2024-07-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=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
}
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.
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.