Tutorial REST: Menggunakan set keterampilan untuk menghasilkan konten yang dapat dicari di Azure AI Search
Dalam tutorial ini, pelajari cara memanggil REST API yang membuat alur pengayaan AI untuk ekstraksi konten dan transformasi selama pengindeksan.
Skillset menambahkan pemrosesan AI ke konten mentah, membuat konten tersebut lebih seragam dan dapat dicari. Setelah Mengetahui cara kerja set keterampilan, Anda dapat mendukung berbagai transformasi: dari analisis gambar, hingga pemrosesan bahasa alami, hingga pemrosesan yang disesuaikan yang Anda berikan secara eksternal.
Tutorial ini membantu Anda mempelajari cara:
- Tentukan objek dalam alur pengayaan.
- Bangun set keterampilan. Panggil OCR, deteksi bahasa, pengenalan entitas, dan ekstraksi frasa kunci.
- Jalankan alur. Membuat dan memuat indeks pencarian.
- Periksa hasilnya menggunakan pencarian teks lengkap.
Jika Anda belum punya langganan Azure, buka akun gratis sebelum memulai.
Gambaran Umum
Tutorial ini menggunakan klien REST dan REST API Azure AI Search untuk membuat sumber data, indeks, pengindeks, dan set keterampilan.
Pengindeks mendorong setiap langkah dalam alur, dimulai dengan ekstraksi konten data sampel (teks dan gambar yang tidak terstruktur) dalam kontainer blob di Azure Storage.
Setelah konten diekstrak, set keterampilan menjalankan keterampilan bawaan dari Microsoft untuk menemukan dan mengekstrak informasi. Keterampilan ini termasuk Pengenalan Karakter Optik (OCR) pada gambar, deteksi bahasa pada teks, ekstraksi frasa kunci, dan pengenalan entitas (organisasi). Informasi baru yang dibuat oleh set keterampilan dikirim ke bidang dalam indeks. Setelah indeks diisi, Anda dapat menggunakan bidang dalam kueri, aspek, dan filter.
Prasyarat
Catatan
Anda dapat menggunakan layanan pencarian gratis untuk tutorial ini. Tingkat gratis membatasi Anda ke tiga indeks, tiga pengindeks, dan tiga sumber data. Tutorial ini membuat satu layanan dari masing-masing layanan. Sebelum memulai, pastikan Anda memiliki ruang pada layanan Anda untuk menerima sumber daya baru.
Mengunduh file
Unduh file zip dari repositori data sampel dan ekstrak kontennya. Pelajari caranya.
Mengunggah data sampel ke Azure Storage
Di Azure Storage, buat kontainer baru dan beri nama cog-search-demo.
Unggah file data sampel.
Dapatkan string koneksi penyimpanan sehingga Anda bisa merumuskan koneksi di Azure AI Search.
Di sebelah kiri, pilih Tombol akses.
Salin string koneksi untuk kunci satu atau dua kunci. string koneksi mirip dengan contoh berikut:
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
Layanan Azure AI
Pengayaan AI bawaan didukung oleh layanan Azure AI, termasuk Layanan bahasa dan Azure AI Vision untuk pemrosesan bahasa dan gambar alami. Untuk beban kerja kecil seperti tutorial ini, Anda dapat menggunakan alokasi gratis dua puluh transaksi per pengindeks. Untuk beban kerja yang lebih besar, lampirkan sumber daya multi-wilayah Azure AI Services ke set keterampilan untuk harga bayar sesuai penggunaan.
Menyalin URL layanan pencarian dan kunci API
Untuk tutorial ini, koneksi ke Azure AI Search memerlukan titik akhir dan kunci API. Anda bisa mendapatkan nilai-nilai ini dari portal Azure.
Masuk ke portal Azure, navigasikan ke halaman Gambaran Umum layanan pencarian, dan salin URL. Contoh titik akhir mungkin terlihat seperti
https://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.
Menyiapkan file REST Anda
Mulai Visual Studio Code dan buka file skillset-tutorial.rest . Lihat Mulai Cepat: Pencarian teks menggunakan REST jika Anda memerlukan bantuan dengan klien REST.
Berikan nilai untuk variabel: titik akhir layanan pencarian, kunci API admin layanan pencarian, nama indeks, string koneksi ke akun Azure Storage Anda, dan nama kontainer blob.
Membuat alur
Pengayaan AI digerakkan oleh pengindeks. Bagian dari panduan ini akan membuat empat objek: sumber data, definisi indeks, skillset, pengindeks.
Langkah 1: Membuat sumber data
Panggil Buat Sumber Data untuk mengatur string koneksi ke kontainer Blob yang berisi file data sampel.
### Create a data source
POST {{baseUrl}}/datasources?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-ds",
"description": null,
"type": "azureblob",
"subtype": null,
"credentials": {
"connectionString": "{{storageConnectionString}}"
},
"container": {
"name": "{{blobContainer}}",
"query": null
},
"dataChangeDetectionPolicy": null,
"dataDeletionDetectionPolicy": null
}
Langkah 2: Buat kumpulan keterampilan
Panggil Create Skillset untuk menentukan langkah pengayaan mana yang diterapkan ke konten Anda. Keterampilan dijalankan secara paralel kecuali ada dependensi.
### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-ss",
"description": "Apply OCR, detect language, extract entities, and extract key-phrases.",
"cognitiveServices": null,
"skills":
[
{
"@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
"context": "/document/normalized_images/*",
"defaultLanguageCode": "en",
"detectOrientation": true,
"inputs": [
{
"name": "image",
"source": "/document/normalized_images/*"
}
],
"outputs": [
{
"name": "text"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.MergeSkill",
"description": "Create merged_text, which includes all the textual representation of each image inserted at the right location in the content field. This is useful for PDF and other file formats that supported embedded images.",
"context": "/document",
"insertPreTag": " ",
"insertPostTag": " ",
"inputs": [
{
"name":"text",
"source": "/document/content"
},
{
"name": "itemsToInsert",
"source": "/document/normalized_images/*/text"
},
{
"name":"offsets",
"source": "/document/normalized_images/*/contentOffset"
}
],
"outputs": [
{
"name": "mergedText",
"targetName" : "merged_text"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.SplitSkill",
"textSplitMode": "pages",
"maximumPageLength": 4000,
"defaultLanguageCode": "en",
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "textItems",
"targetName": "pages"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
"description": "If you have multilingual content, adding a language code is useful for filtering",
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "languageName",
"targetName": "language"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
"context": "/document/pages/*",
"inputs": [
{
"name": "text",
"source": "/document/pages/*"
}
],
"outputs": [
{
"name": "keyPhrases",
"targetName": "keyPhrases"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Organization"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "organizations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Location"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "locations",
"targetName": "locations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Person"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "persons",
"targetName": "persons"
}
]
}
]
}
Poin utama:
Isi permintaan menentukan keterampilan bawaan berikut:
Keterampilan Deskripsi Pengenalan Karakter Optik Mengenali teks dan angka dalam file gambar. Penggabungan Teks Membuat "konten gabungan" yang menggabungkan ulang konten yang dipisahkan sebelumnya, berguna untuk dokumen dengan gambar yang disematkan (PDF, DOCX, dan sebagainya). Gambar dan teks dipisahkan selama fase pemecahan dokumen. Keterampilan penggabungan menggabungkannya kembali dengan menyisipkan teks, keterangan gambar, atau tag yang dikenali yang dibuat selama pengayaan ke lokasi yang sama tempat gambar diekstraksi dalam dokumen. Saat Anda bekerja dengan konten yang digabungkan dalam set keterampilan, simpul ini termasuk semua teks dalam dokumen, termasuk dokumen teks saja yang tidak pernah menjalani OCR atau analisis gambar. Deteksi Bahasa Mendeteksi bahasa dan output baik nama bahasa atau kode. Dalam himpunan data multibahasa, bidang bahasa dapat berguna untuk filter. Pengenalan Entitas Mengekstrak nama orang, organisasi, dan lokasi dari konten gabungan. Pemisahan Teks Memecah konten gabungan besar menjadi gugus yang lebih kecil sebelum memanggil keterampilan ekstraksi frasa kunci. Ekstraksi frasa kunci menerima input 50.000 karakter atau kurang. Beberapa file sampel perlu dipisahkan agar sesuai dalam batas ini. Ekstraksi Frasa Kunci Mengeluarkan frasa kunci paling atas. Setiap keterampilan dijalankan pada konten dokumen. Selama pemrosesan, Azure AI Search memecahkan setiap dokumen untuk membaca konten dari format file yang berbeda. Teks yang ditemukan berasal dari file sumber ditempatkan di dalam bidang
contentyang dihasilkan, satu file untuk setiap dokumen. Dengan demikian, masukan menjadi"/document/content".Untuk ekstraksi frasa kunci, karena kita menggunakan keterampilan pemisah teks untuk memecah file yang lebih besar ke dalam halaman, konteks untuk keterampilan ekstraksi frasa kunci adalah
"document/pages/*"(untuk setiap halaman dalam dokumen) bukan"/document/content".
Catatan
Output dapat dipetakan ke indeks, digunakan sebagai input ke keterampilan downstream, atau keduanya seperti halnya dengan kode bahasa. Dalam indeks, kode bahasa berguna untuk pemfilteran. Untuk mengetahui informasi selengkapnya tentang dasar-dasar skillset, lihat Cara menentukan skillset.
Langkah 3: Membuat indeks
Panggil Buat Indeks untuk menyediakan skema yang digunakan untuk membuat indeks terbalik dan konstruksi lain di Azure AI Search.
Komponen terbesar indeks adalah kumpulan bidang, di mana jenis data dan atribut menentukan konten dan perilaku di Azure AI Search. Pastikan Anda memiliki bidang untuk output yang baru dibuat.
### Create an index
POST {{baseUrl}}/indexes?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-idx",
"defaultScoringProfile": "",
"fields": [
{
"name": "content",
"type": "Edm.String",
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
},
{
"name": "text",
"type": "Collection(Edm.String)",
"facetable": false,
"filterable": true,
"searchable": true,
"sortable": false
},
{
"name": "language",
"type": "Edm.String",
"searchable": false,
"sortable": true,
"filterable": true,
"facetable": false
},
{
"name": "keyPhrases",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "organizations",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "persons",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "locations",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "metadata_storage_path",
"type": "Edm.String",
"key": true,
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
},
{
"name": "metadata_storage_name",
"type": "Edm.String",
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
}
]
}
Langkah 4 - Buat dan jalankan pengindeks
Panggil Buat Pengindeks untuk mendorong alur. Tiga komponen yang sudah Anda buat sejauh ini (sumber data, skillset, indeks) adalah input ke pengindeks. Membuat pengindeks di Azure AI Search adalah peristiwa yang membuat seluruh alur bergerak.
Diperlukan waktu beberapa menit untuk menyelesaikan langkah ini. Meskipun himpunan data kecil, keterampilan analitis berkomputasi intensif.
### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-idxr",
"description": "",
"dataSourceName" : "cog-search-demo-ds",
"targetIndexName" : "cog-search-demo-idx",
"skillsetName" : "cog-search-demo-ss",
"fieldMappings" : [
{
"sourceFieldName" : "metadata_storage_path",
"targetFieldName" : "metadata_storage_path",
"mappingFunction" : { "name" : "base64Encode" }
},
{
"sourceFieldName": "metadata_storage_name",
"targetFieldName": "metadata_storage_name"
}
],
"outputFieldMappings" :
[
{
"sourceFieldName": "/document/merged_text",
"targetFieldName": "content"
},
{
"sourceFieldName" : "/document/normalized_images/*/text",
"targetFieldName" : "text"
},
{
"sourceFieldName" : "/document/organizations",
"targetFieldName" : "organizations"
},
{
"sourceFieldName": "/document/language",
"targetFieldName": "language"
},
{
"sourceFieldName" : "/document/persons",
"targetFieldName" : "persons"
},
{
"sourceFieldName" : "/document/locations",
"targetFieldName" : "locations"
},
{
"sourceFieldName" : "/document/pages/*/keyPhrases/*",
"targetFieldName" : "keyPhrases"
}
],
"parameters":
{
"batchSize": 1,
"maxFailedItems":-1,
"maxFailedItemsPerBatch":-1,
"configuration":
{
"dataToExtract": "contentAndMetadata",
"imageAction": "generateNormalizedImages"
}
}
}
Poin utama:
Isi permintaan mencakup referensi ke objek sebelumnya, properti konfigurasi yang diperlukan untuk pemrosesan gambar, dan dua jenis pemetaan bidang.
"fieldMappings"diproses sebelum set keterampilan, mengirim konten dari sumber data ke bidang target dalam indeks. Anda menggunakan pemetaan bidang untuk mengirim konten yang sudah ada dan tidak dimodifikasi ke indeks. Jika nama dan jenis bidang sama di kedua ujungnya, tidak diperlukan pemetaan."outputFieldMappings"adalah untuk bidang yang dibuat oleh keterampilan, setelah eksekusi skillset. Referensi kesourceFieldNamedalamoutputFieldMappingstidak ada sampai pemecahan atau pengayaan dokumen membuatnya.targetFieldNameadalah bidang dalam indeks, didefinisikan dalam skema indeks.Parameter
"maxFailedItems"diatur ke -1, yang menginstruksikan mesin pengindeksan untuk mengabaikan kesalahan selama impor data. Ini dapat diterima karena ada sedikit dokumen dalam sumber data demo. Untuk sumber data yang lebih besar, Anda akan menetapkan nilainya menjadi lebih besar dari 0.Pernyataan ini
"dataToExtract":"contentAndMetadata"memberi tahu pengindeks untuk secara otomatis mengekstrak nilai dari properti konten blob dan metadata setiap objek.Parameter
imageActionmemberi tahu pengindeks untuk mengekstrak teks dari gambar yang ditemukan di sumber data. Konfigurasi"imageAction":"generateNormalizedImages", dikombinasikan dengan Keterampilan OCR dan Keterampilan Penggabungan Teks, memberi tahu pengindeks untuk mengekstrak teks dari gambar (misalnya, kata "berhenti" dari tanda Berhenti lalu lintas), dan menyematkannya sebagai bagian dari bidang konten. Perilaku ini berlaku untuk gambar yang disematkan (pikirkan gambar di dalam PDF) dan file gambar mandiri, misalnya file JPG.
Catatan
Membuat pengindeks memanggil alur. Jika ada masalah dalam mencapai data, pemetaan input dan output, atau urutan operasi, mereka muncul pada tahap ini. Untuk menjalankan kembali alur dengan perubahan kode atau skrip, Anda mungkin perlu menghapus objek terlebih dahulu. Untuk mengetahui informasi selengkapnya, lihat Mengatur ulang dan menjalankan ulang.
Memantau pengindeksan
Pengindeksan dan pengayaan dimulai segera setelah Anda mengirimkan permintaan Create Indexer. Tergantung pada kompleksitas dan operasi skillset, pengindeksan dapat memakan waktu cukup lama.
Untuk mengetahui apakah pengindeks masih berjalan, panggil Dapatkan Status Pengindeks untuk memeriksa status pengindeks.
### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/cog-search-demo-idxr/status?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
Poin utama:
Peringatan umum dalam beberapa skenario dan tidak selalu menunjukkan masalah. Misalnya, jika kontainer blob menyertakan file gambar, dan alur tidak menangani gambar, Anda mendapatkan peringatan yang menyatakan bahwa gambar tidak diproses.
Dalam sampel ini, ada file PNG yang tidak berisi teks. Kelima keterampilan berbasis teks (deteksi bahasa, pengenalan entitas lokasi, organisasi, orang, dan ekstraksi frasa kunci) gagal dijalankan pada file ini. Pemberitahuan yang dihasilkan muncul dalam riwayat eksekusi.
Memeriksa hasil
Sekarang setelah Anda membuat indeks yang berisi konten yang dihasilkan AI, panggil Cari Dokumen untuk menjalankan beberapa kueri untuk melihat hasilnya.
### Query the index\
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"search": "*",
"select": "metadata_storage_name,language,organizations",
"count": true
}
Filter dapat membantu Anda mempersempit hasil ke item yang menarik:
### Filter by organization
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2023-11-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"search": "*",
"filter": "organizations/any(organizations: organizations eq 'Microsoft')",
"select": "metadata_storage_name,organizations",
"count": true
}
Kueri ini mengilustrasikan beberapa cara Anda dapat bekerja dengan sintaks kueri dan filter pada bidang baru yang dibuat oleh Azure AI Search. Untuk contoh kueri lainnya, lihat Contoh di REST API Search Documents, Contoh kueri sintaks sederhana, dan contoh kueri Lucene Penuh.
Atur ulang dan jalankan ulang
Selama tahap awal pengembangan, iterasi atas desain adalah umum. Reset dan jalankan ulang membantu iterasi.
Poin-poin penting
Tutorial ini menunjukkan langkah-langkah dasar untuk menggunakan REST API untuk membuat alur pengayaan AI: sumber data, set keterampilan, indeks, dan pengindeks.
Keterampilan bawaan diperkenalkan, bersama dengan definisi set keterampilan yang menunjukkan mekanisme keterampilan rantai bersama-sama melalui input dan output. Anda juga mempelajari bahwa outputFieldMappings dalam definisi pengindeks diperlukan untuk merutekan nilai yang diperkaya dari alur ke dalam indeks yang dapat dicari pada azure AI layanan Pencarian.
Akhirnya, Anda sudah belajar cara menguji hasil dan mengatur ulang sistem untuk iterasi lebih lanjut. Anda sudah belajar bahwa mengeluarkan kueri terhadap indeks mengembalikan output yang dibuat oleh alur pengindeksan yang diperkaya.
Membersihkan sumber daya
Saat Anda bekerja di langganan Anda sendiri, di akhir proyek, sebaiknya hapus sumber daya yang tidak lagi Anda butuhkan. 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 terbiasa dengan semua objek dalam alur pengayaan AI, lihat lebih dekat definisi skillset dan keterampilan individual.