Membuat Skillset (Azure AI Search REST API)

  • Artikel

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:
  • name (diperlukan) menentukan tabel yang akan dibuat atau digunakan di Azure Table Storage.
  • generatedKeyName (opsional) adalah nama kolom yang secara unik mengidentifikasi dokumen. Nilai untuk kolom ini akan dihasilkan selama pengayaan. Jika Anda menghilangkannya, layanan pencarian akan membuat kolom kunci default berdasarkan nama tabel.
  • source (wajib) adalah jalur ke simpul pohon pengayaan yang menyediakan bentuk proyeksi. Biasanya output dari keterampilan Shaper. Jalur dimulai dengan /document/, mewakili akar dokumen yang diperkaya, dan kemudian diperluas ke /document/<shaper-output>/, atau /document/content/, atau simpul lain di dalam pohon pengayaan. Contoh: /document/countries/* (semua negara), atau /document/countries/*/states/* (semua negara bagian di semua negara).

objects
Memproyeksikan dokumen sebagai blob dalam Azure Blob Storage. Setiap objek memiliki dua properti yang diperlukan:
  • storageContaineradalah nama kontainer yang akan dibuat atau digunakan dalam Azure Blob Storage.
  • source adalah jalur ke simpul pohon pengayaan yang menyediakan bentuk proyeksi. Ini harus JSON yang valid. Simpul harus menyediakan objek JSON, baik dari keterampilan yang memancarkan JSON yang valid atau output keterampilan Shaper.

files
Setiap entri file menentukan penyimpanan gambar biner di Blob Storage. Proyeksi file memiliki dua properti yang diperlukan:
  • storageContaineradalah nama kontainer yang akan dibuat atau digunakan dalam Azure Blob Storage.
  • source adalah jalur ke simpul pohon pengayaan yang merupakan akar proyeksi. Nilai yang valid untuk properti ini adalah "/document/normalized_images/*" untuk gambar yang bersumber dari Blob Storage.
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)"}
    }
}

Lihat juga