Bagikan melalui

Membuat Skillset (Rest API Pencarian Azure AI)

Penting

Referensi API ini untuk versi warisan. Lihat Operasi REST sarana data untuk dokumentasi referensi yang diperbarui. Gunakan filter di kiri atas untuk memilih versi.

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, pemotongan teks menjadi halaman logis, antara lain.

Set keterampilan dilampirkan ke pengindeks. Untuk menggunakan set keterampilan, 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 di beberapa pengindeks.

Anda dapat menggunakan POST atau PUT pada permintaan. Untuk salah satu, 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.

Nota

Skillset 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

Pengaturan Deskripsi
nama layanan Dibutuhkan. 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 Dibutuhkan. Lihat versi API untuk daftar versi yang didukung.

Minta Header

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.

Bidang Deskripsi
Jenis-Konten Dibutuhkan. Atur ini ke application/json
kunci API 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.

Badan Permintaan

Isi permintaan berisi definisi set keterampilan. Keterampilan mandiri atau ditautkan bersama melalui asosiasi input-output, di mana output dari satu transformasi menjadi input ke yang lain. Set keterampilan harus memiliki setidaknya satu keterampilan. Tidak ada batas teoritis pada jumlah keterampilan maksimum, 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:

Harta benda Deskripsi
Nama Dibutuhkan. 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.
kemampuan 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 dan sebagainya 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 Fakultatif. 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 (wajib) 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 dokumen akar yang diperkaya, dan kemudian diperluas ke /document/<shaper-output>/, atau /document/content/, atau simpul lain dalam pohon pengayaan. Contoh: /document/countries/* (semua negara), atau /document/countries/*/states/* (semua negara bagian di semua negara).

objects
Memproyeksikan dokumen sebagai blob di Azure Blob Storage. Setiap objek memiliki dua properti yang diperlukan:
  • storageContainer adalah nama kontainer untuk dibuat atau digunakan di 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 mendefinisikan penyimpanan gambar biner di Blob Storage. Proyeksi file memiliki dua properti yang diperlukan:
  • storageContainer adalah nama kontainer untuk dibuat atau digunakan di 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 Fakultatif. Digunakan untuk mengenkripsi definisi set keterampilan saat tidak aktif dengan kunci Anda sendiri, dikelola di Azure Key Vault 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 menyediakan keyVaultUri 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. accessCredentials Properti termasuk applicationId (ID aplikasi ID Microsoft Entra yang diberikan izin akses ke Azure Key Vault yang Ditentukan), dan applicationSecret (kunci autentikasi aplikasi terdaftar). Contoh di bagian berikutnya mengilustrasikan sintaks.

Tanggapan

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 Pembentuk hulu 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