Membuat Skillset (Azure AI Search REST API)
Skillset adalah kumpulan keterampilan kognitif yang digunakan untuk pengayaan AI, dengan spesifikasi opsional untuk membuat penyimpanan pengetahuan eksternal di Azure Storage. Keterampilan memanggil pemrosesan bahasa alami dan transformasi lainnya, seperti pengenalan entitas, ekstraksi frasa kunci, memotong teks menjadi halaman logis, antara lain.
Set keterampilan dilampirkan ke pengindeks. Untuk menggunakan skillset, referensikan dalam pengindeks lalu jalankan pengindeks untuk mengimpor data, memanggil transformasi dan pengayaan, dan memetakan bidang output ke indeks. Skillset adalah sumber daya tingkat tinggi, tetapi hanya beroperasi dalam pemrosesan pengindeks. Sebagai sumber daya tingkat tinggi, Anda dapat merancang set keterampilan sekali, lalu mereferensikannya dalam beberapa pengindeks.
Anda dapat menggunakan POST atau PUT pada permintaan. Untuk salah satu dari keduanya, dokumen JSON dalam isi permintaan menyediakan definisi objek.
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
HTTPS diperlukan untuk semua permintaan layanan. Jika set keterampilan tidak ada, set keterampilan akan dibuat. Jika sudah ada, itu diperbarui ke definisi baru.
Catatan
Skillsets adalah dasar pengayaan AI. Sumber daya gratis tersedia untuk pemrosesan terbatas, tetapi untuk beban kerja yang lebih besar atau lebih sering, sumber daya Cognitive Services yang dapat ditagih diperlukan.
Parameter URI
| Parameter | Deskripsi |
|---|---|
| nama layanan | Wajib diisi. Atur ini ke nama unik yang ditentukan pengguna dari layanan pencarian Anda. |
| nama skillset | Diperlukan pada URI jika menggunakan PUT. Nama harus huruf kecil, dimulai dengan huruf atau angka, tidak memiliki garis miring atau titik, dan kurang dari 128 karakter. Nama harus dimulai dengan huruf atau angka, tetapi sisa nama dapat menyertakan huruf, angka, dan tanda hubung apa pun, selama tanda hubung tidak berturut-turut. |
| versi-api | Wajib diisi. Lihat versi API untuk daftar versi yang didukung. |
Judul Permintaan
Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.
| Bidang | Deskripsi |
|---|---|
| Jenis-Konten | Wajib diisi. Atur titik akhir ini ke application/json |
| api-key | Opsional jika Anda menggunakan peran Azure dan token pembawa disediakan berdasarkan permintaan, jika tidak, kunci diperlukan. Membuat permintaan harus menyertakan header yang api-key diatur ke kunci admin Anda (dibandingkan dengan kunci kueri). Lihat Menyambungkan ke Azure AI Search menggunakan autentikasi kunci untuk detailnya. |
Isi Permintaan
Isi permintaan berisi definisi set keterampilan. Keterampilan bersifat mandiri atau dirangkai bersama melalui asosiasi input-output, di mana output dari satu transformasi menjadi input ke transformasi lain. Suatu skillset harus mempunyai setidaknya satu keterampilan. Tidak ada batas teoritis pada jumlah maksimum keterampilan, tetapi tiga hingga lima adalah konfigurasi umum.
JSON berikut adalah representasi tingkat tinggi dari bagian utama definisi.
{
"name" : (optional on PUT; required on POST) "Name of the skillset",
"description" : (optional) "Anything you want, or nothing at all",
"skills" : (required) ["An array of skills. Each skill has an odata.type, name, input and output parameters"],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "Optional. Anything you want, or null",
"key": "<YOUR-COGNITIVE-SERVICES-ALL-IN-ONE-KEY>"
},
"knowledgeStore": (optional) { ... },
"encryptionKey": (optional) { }
}
Permintaan berisi properti berikut:
| Properti | Deskripsi |
|---|---|
| nama | Wajib diisi. Nama set keterampilan. Nama harus huruf kecil, dimulai dengan huruf atau angka, tidak memiliki garis miring atau titik, dan kurang dari 128 karakter. Nama harus dimulai dengan huruf atau angka, tetapi sisa nama dapat menyertakan huruf, angka, dan tanda hubung apa pun, selama tanda hubung tidak berturut-turut. |
| Keterampilan | Array keterampilan. Setiap keterampilan memiliki parameter odata.type, nama, konteks, dan input dan output. Array dapat mencakup keterampilan bawaan dan keterampilan kustom. Setidaknya diperlukan satu keterampilan. Jika Anda menggunakan penyimpanan pengetahuan, sertakan keterampilan Shaper kecuali Anda menentukan bentuk data dalam proyeksi. |
| cognitiveServices | Kunci all-in-one diperlukan untuk keterampilan yang dapat ditagih yang memanggil API Cognitive Services pada lebih dari 20 dokumen setiap hari, per pengindeks. Kuncinya harus untuk sumber daya di wilayah yang sama dengan layanan pencarian. Untuk informasi selengkapnya, lihat Melampirkan sumber daya Cognitive Services. Jika Anda menggunakan keterampilan Pencarian Entitas Kustom , sertakan bagian ini dan kunci untuk mengaktifkan transaksi di luar 20 transaksi setiap hari per pengindeks. Anda tidak memerlukan Kunci Cognitive Services sehingga dapat mengecualikan cognitiveServices bagian jika set keterampilan Anda hanya terdiri dari keterampilan kustom, keterampilan utilitas (Kondisional, Pembentuk, Penggabungan Teks, Pemisahan Teks), atau keterampilan Ekstraksi Dokumen. Jika Anda ingin menghapus sumber daya layanan kognitif terlampir dari set keterampilan (untuk kembali menggunakan batas "default"), tentukan @odata.type sebagai #Microsoft.Azure.Search.DefaultCognitiveServices, Lihat contoh ini untuk informasi selengkapnya. |
| knowledgeStore | Pilihan. Tujuan untuk output pengayaan ke Azure Storage. Memerlukan string koneksi ke akun dan proyeksi Azure Storage.
storageConnectionString (diperlukan) String dalam format ini: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net".
projections (diperlukan) Array objek proyeksi yang terdiri dari tables, objects, files, yang ditentukan atau null.
tables
Membuat satu atau beberapa tabel di Azure Table Storage, memproyeksikan konten dari setiap dokumen sebagai baris dalam tabel. Setiap tabel dapat memiliki tiga properti berikut:
objects
Memproyeksikan dokumen sebagai blob dalam Azure Blob Storage. Setiap objek memiliki dua properti yang diperlukan:
files
Setiap entri file menentukan penyimpanan gambar biner di Blob Storage. Proyeksi file memiliki dua properti yang diperlukan:
|
| encryptionKey | Pilihan. Digunakan untuk mengenkripsi definisi set keterampilan tidak aktif dengan kunci Anda sendiri, yang dikelola di Key Vault Azure Anda. Tersedia untuk layanan pencarian yang dapat ditagih yang dibuat pada atau setelah 2019-01-01.
Bagian encryptionKey berisi yang ditentukan keyVaultKeyName pengguna (diperlukan), yang dihasilkan keyVaultKeyVersion sistem (diperlukan), dan keyVaultUri menyediakan kunci (diperlukan, juga disebut sebagai nama DNS). Contoh URI mungkin "https://my-keyvault-name.vault.azure.net".
Secara opsional, Anda dapat menentukan accessCredentials apakah Anda tidak menggunakan identitas sistem terkelola. Properti yang accessCredentials disertakan applicationId (Microsoft Entra ID ID aplikasi yang diberikan izin akses ke Key Vault Azure yang Anda tentukan), dan applicationSecret (kunci autentikasi aplikasi terdaftar). Contoh di bagian berikutnya mengilustrasikan sintaks. |
Respons
Untuk permintaan yang berhasil, Anda akan melihat kode status "201 Dibuat".
Secara default, isi respons akan berisi JSON untuk definisi set keterampilan yang dibuat. Namun, jika Prefer header permintaan diatur ke return=minimal, isi respons kosong, dan kode status keberhasilan adalah "204 Tanpa Konten" alih-alih "201 Dibuat". Hal ini berlaku terlepas dari apakah PUT atau POST digunakan untuk membuat skillset.
Contoh
Contoh: Skillset yang mengenali entitas bisnis dan sentimen dalam ulasan pelanggan
Skillset ini menggunakan dua keterampilan secara asinkron, secara independen diproses /document/content sebagai dua transformasi yang berbeda. Keterampilannya adalah Pengenalan Entitas dan Sentimen. Di pohon pengayaan, /document/content berikan konten (atau ulasan pelanggan) dari sumber data eksternal.
{
"name": "reviews-ss",
"description":
"Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
"skills":
[
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"context": "/document/content",
"categories": [ "Organization" ],
"defaultLanguageCode": "en",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "companyName"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "languageCode",
"source": "/document/languageCode"
}
],
"outputs": [
{
"name": "sentiment",
"targetName": "reviewSentiment"
},
{
"name": "confidenceScores",
"targetName": "sentimentScore"
}
]
}
],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "mycogsvcs resource in West US 2",
"key": "<your cognitive services all-in-one key goes here>"
},
"knowledgeStore": { },
"encryptionKey": { }
}
Contoh: Penyimpanan pengetahuan
Set keterampilan dapat secara opsional mengirim output ke penyimpanan pengetahuan di Azure Storage. Ini memerlukan string koneksi ke akun Azure Storage dan proyeksi yang menentukan apakah konten yang diperkaya mendarat di penyimpanan tabel atau blob (sebagai objek atau file). Proyeksi biasanya memerlukan keterampilan Shaper upstream yang mengumpulkan simpul dari pohon pengayaan sebagai input, menghasilkan satu bentuk yang dapat diteruskan ke proyeksi. Pembentuk biasanya merupakan keterampilan terakhir yang akan diproses.
{
"name": "reviews-ss",
"description":
"Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
"skills":
[
{ ... },
{ ... },
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"context": "/document/content",
"inputs": [
{
"name": "Company",
"source": "/document/content/companyName"
},
{
"name": "Sentiment_Score",
"source": "/document/content/sentimentScore"
},
{
"name": "Sentiment_Label",
"source": "/document/content/reviewSentiment"
}
],
"outputs": [
{
"name": "output",
"targetName": "shapeCustomerReviews"
}
]
}
],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "mycogsvcs resource in West US 2",
"key": "<your cognitive services all-in-one key goes here>"
},
"knowledgeStore": {
"storageConnectionString": "<your storage account connection string>",
"projections": [
{
"tables": [
{ "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
. . .
],
"objects": [ ],
"files": [ ]
}
]
}
"encryptionKey": { }
}
Contoh: Kunci enkripsi
Kunci enkripsi adalah kunci yang dikelola pelanggan yang digunakan untuk enkripsi tambahan konten sensitif. Contoh ini menunjukkan kepada Anda cara menentukan enkripsi yang dikelola pelanggan pada set keterampilan.
{
"name": "reviews-ss",
"description": "A brief description of the skillset",
"skills": [ omitted for brevity ],
"cognitiveServices": { omitted for brevity },
"knowledgeStore": { omitted for brevity },
"encryptionKey": (optional) {
"keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
"keyVaultKeyVersion": "Version of the Azure Key Vault key",
"keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
"accessCredentials": (optional, only if not using managed system identity) {
"applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
"applicationSecret": "Authentication key of the specified Azure AD application)"}
}
}