Bagikan melalui

Membuat atau Memperbarui Skillset (Pratinjau REST API)

Berlaku untuk: 2023-07-01-Preview. Versi ini tidak lagi didukung. Tingkatkan segera ke versi yang lebih baru.

Penting

2023-07-01-Preview (tidak ada perubahan).

Pratinjau 04-04-2021 menambahkan dukungan identitas terkelola untuk koneksi terkait skillset:

  • "storageConnectionString" di bawah knowledge store menerima ID sumber daya Azure untuk autentikasi Azure AD.
  • "identitas" menerima identitas terkelola yang ditetapkan pengguna. Properti ini berada di bawah penyimpanan pengetahuan . Ini juga di bawah "encryptionKey" untuk mengambil kunci yang dikelola pelanggan di Azure Key Vault.

API pratinjau ini juga mendukung koneksi identitas terkelola dari keterampilan kustom. Lihat referensi API Web Kustom untuk detailnya.

Skillset adalah kumpulan keterampilan kognitif digunakan untuk pengayaan AI, dengan opsi juga membuat penyimpanan pengetahuan eksternal di Azure Storage. Keterampilan memanggil pemrosesan bahasa alami dan proses pembelajaran mesin lainnya, seperti pengenalan entitas, ekstraksi frasa kunci, pemotongan teks ke halaman logis, antara lain.

Set keterampilan dilampirkan ke pengindeks . Untuk menggunakan set keterampilan, referensikan dalam pengindeks lalu jalankan pengindeks untuk mengimpor data, memanggil pengayaan, dan mengirim output ke indeks. Skillset adalah sumber daya tingkat tinggi, tetapi hanya beroperasi dalam pemrosesan pengindeks. Sebagai sumber daya tingkat tinggi, Anda dapat mereferensikannya di beberapa pengindeks.

Anda dapat menggunakan POST atau PUT pada permintaan buat. Untuk salah satu, isi permintaan menyediakan definisi objek.

POST https://[service name].search.windows.net/skillsets?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]

Untuk permintaan pembaruan, gunakan PUT dan tentukan nama skillset pada URI.

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.

Membuat set keterampilan menambahkannya ke layanan pencarian Anda.

Memperbarui set keterampilan sepenuhnya menimpa set keterampilan yang ada dengan konten payload permintaan. Praktik terbaik untuk pembaruan adalah mengambil definisi set keterampilan dengan GET, memodifikasinya, lalu memperbaruinya dengan PUT.

Nota

Skillsets adalah dasar daripengayaan AI . Sumber daya gratis tersedia untuk pemrosesan terbatas, tetapi untuk beban kerja yang lebih besar atau lebih sering, melampirkan sumber daya Cognitive Services yang dapat ditagih.

Parameter URI

Parameter Deskripsi
nama layanan Diperlukan. Atur properti 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. Setelah Anda memulai nama dengan huruf atau angka, sisa nama dapat menyertakan huruf, angka, dan tanda hubung apa pun, selama tanda hubung tidak berturut-turut.
versi api Diperlukan. Lihat versi API untuk versi lainnya.
disableCacheReprocessingChangeDetection Opsional (false secara default). Berlaku untuk memperbarui skenario dan menggunakan pengayaan yang di-cache selama eksekusi skillset. Atur ke true untuk mencegah pembaruan pada dokumen yang ada berdasarkan tindakan saat ini, misalnya jika Anda ingin memperbarui set keterampilan tanpa menjalankan set keterampilan. Untuk informasi selengkapnya, lihat Bypassevaluasi skillset .

Header Permintaan

Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.

Bidang Deskripsi
Tipe Isi Diperlukan. Atur properti ini ke application/json
api-key Opsional jika Anda menggunakan peran Azure dan token pembawa disediakan berdasarkan permintaan, jika tidak, kunci diperlukan. Kunci api adalah string unik yang dihasilkan sistem yang mengautentikasi permintaan ke layanan pencarian Anda. Membuat permintaan harus menyertakan header api-key yang diatur ke kunci admin Anda (dibandingkan dengan kunci kueri). Lihat Sambungkan ke Azure AI Search menggunakan autentikasi utama untuk detailnya.

Isi 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 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:

Harta benda Deskripsi
Nama Diperlukan. Nama set keterampilan. Nama harus huruf kecil, dimulai dengan huruf atau angka, tidak memiliki garis miring atau titik, dan kurang dari 128 karakter. Setelah Anda memulai nama dengan huruf atau angka, 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. Referensi keterampilan dapat ditemukan dalam dokumentasi konseptual. 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.

Anda dapat menghilangkan kunci dan bagian ini jika set keterampilan Anda hanya terdiri dari keterampilan kustom, keterampilan utilitas (Kondisi, Pembentuk, Penggabungan Teks, Pemisahan Teks), atau keterampilan Ekstraksi Dokumen . Jika Anda menggunakan keterampilan Pencarian Entitas Kustom , sertakan bagian ini dan kunci untuk mengaktifkan transaksi di luar 20 transaksi setiap hari per pengindeks.
knowledgeStore Fakultatif. Tujuan untuk output pengayaan ke Azure Storage. Memerlukan string koneksi ke akun Azure Storage dan proyeksi .
encryptionKey Fakultatif. Digunakan untuk mengenkripsi data sensitif dalam definisi set keterampilan dengan kunci Anda sendiri, dikelola di Azure Key Vault Anda. Untuk mempelajari selengkapnya, lihat enkripsi Azure AI Search menggunakan kunci yang dikelola pelanggan di Azure Key Vault.

Jawaban

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 header Permintaan pilihan diatur ke return=minimal, isi respons akan kosong, dan kode status keberhasilan akan menjadi "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 memproses /document/content sebagai dua transformasi yang berbeda. Keterampilannya adalah Pengenalan Entitas dan sentimen . Di pohon pengayaan, /document/content menyediakan 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 dengan string koneksi akses penuh dan input berbentuk

Penyimpanan pengetahuan 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, terutama proyeksi tabel, memerlukan keterampilan pembentuk hulu yang mengumpulkan simpul dari pohon pengayaan sebagai input, menghasilkan bentuk tunggal yang dapat diteruskan ke proyeksi. Pembentuk biasanya merupakan keterampilan terakhir yang akan diproses. Dalam proyeksi tabel, simpul dalam keterampilan pembentuk menentukan bidang dalam tabel.

{
  "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": "DefaultEndpointsProtocol=https;AccountName=<storage-account-name>;AccountKey=<storage-account-key>;EndpointSuffix=core.windows.net;", 
      "projections": [ 
          { 
            "tables": [ 
                { "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
                . . .
            ], 
            "objects": [ ], 
            "files": [ ]  
          }
      ]     
  } 
  "encryptionKey": { }
}

Contoh : Koneksi yang menggunakan identitas terkelola

Identitas terkelola dapat digunakan pada koneksi ke penyimpanan pengetahuan dan ke kode eksternal dari keterampilan kustom. Contoh ini menunjukkan kedua skenario. Untuk penyimpanan pengetahuan, properti "identitas" tambahan menentukan identitas terkelola yang ditetapkan pengguna layanan pencarian yang digunakan Azure AD untuk mengautentikasi permintaan. Jika Anda menghilangkan "identitas", identitas terkelola yang ditetapkan sistem layanan pencarian akan digunakan. Agar Azure AD dapat mengautentikasi pemanggil, layanan pencarian harus dikonfigurasi untuk identitas terkelola. Identitas pencarian harus memiliki izin "Kontributor Data Blob Penyimpanan" untuk menulis ke Azure Storage.

Keterampilan kustom dapat menggunakan identitas terkelola untuk autentikasi ke fungsi Azure atau aplikasi yang menghosting kode kustom Anda. Ini termasuk properti "authResourceId" untuk menunjukkan koneksi diautentikasi menggunakan identitas terkelola. Nilai "authResourceId" adalah ID aplikasi yang dibuat oleh penyedia Identitas Microsoft. Nilai ini akan digunakan untuk memvalidasi token autentikasi yang diambil oleh pengindeks, dan akan dikirim bersama dengan permintaan API keterampilan Web kustom.

{
  "name": "reviews-ss",
  "description": "A short description",
  "skills":
  [
    { ... },
    { ... },
    {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "sampleCustomSkill",
        "description": "A custom skill that requests an access token for the application ID specified in authResourceID",
        "context": "/document",
        "uri": "https://[your-app-name].azurewebsites.net/api/EntitySearch",
        "authResourceId": "api://xyz*****-****-****-****-********9876",
        "batchSize": 4,
        "degreeOfParallelism": null,
        "inputs": [
          {
            "name": "text",
            "source": "/document/content"
          },
          {
            "name": "language",
            "source": "/document/languageCode"
          },
          {
            "name": "phraseList",
            "source": "/document/keyphrases"
          }
        ],
        "outputs": [
          {
            "name": "<customSkillOutput>"
          }
        ]
      }
    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "context": "/document/content",
      "inputs": [ ... ],
      "outputs": [ ...]
    }
  ],
  "cognitiveServices": { ... },
  "knowledgeStore": { 
      "storageConnectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;",
      "identity": {
          "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
          "userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]",
      "projections": [ 
          { 
            "tables": [ ], 
            "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)"}
    }
}

Definisi

Tautan Deskripsi
knowledgeStore Mengonfigurasi koneksi ke Azure Storage dan proyek yang diperkaya konten dalam bentuk objek, file, dan tabel untuk menggunakan skenario penambangan pengetahuan dan pemrosesan data.
encryptionKey Mengonfigurasi koneksi ke Azure Key Vault untuk enkripsi yang dikelola pelanggan.

knowledgeStore

Penyimpanan pengetahuan adalah repositori data yang diperkaya yang menciptakan skillset dan alur pengayaan AI. Ini berada di Azure Storage dan terdiri dari proyeksi data dalam bentuk objek, file, dan tabel. Ini digunakan untuk skenario non-pencarian seperti penambangan pengetahuan, eksplorasi data di Power BI, atau sebagai sink data untuk pemrosesan yang lebih hilir oleh aplikasi lain.

Koneksi ke Azure Storage adalah string koneksi akses penuh yang menyertakan kunci, atau ID sumber daya penyimpanan asalkan layanan pencarian berjalan di bawah identitas terkelola dan memiliki penetapan peran Azure yang memberikan akses tulis ke titik akhir penyimpanan pengetahuan.

Atribut Deskripsi
storageConnectionString Diperlukan. String dalam salah satu format berikut:

"DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net"

"ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
identitas Fakultatif. Ini berisi jenis dan menentukan identitas terkelola yang ditetapkan pengguna dari layanan pencarian. Properti ini bergantung pada storageConnectionString memiliki string koneksi yang menentukan ID Sumber Daya akun penyimpanan Anda.

Jika properti identity null, koneksi ke ID sumber daya dibuat menggunakan properti yang dikelola sistem.

Jika properti ini ditetapkan ke jenis #Microsoft.Azure.Search.DataNoneIdentity, identitas eksplisit apa pun yang sebelumnya ditentukan akan dihapus.
proyeksi Diperlukan. Array proyeksi yang terdiri dari tables, objects, files, yang ditentukan atau null.

Proyeksi

Proyeksi adalah definisi struktur data dalam penyimpanan pengetahuan. Semua nama ditentukan pengguna. Anda dapat mengadopsi konvensi penamaan yang membantu Anda mengidentifikasi konten terkait di Azure Storage.

Atribut Deskripsi
Tabel Memproyeksikan bentuk data menjadi satu atau beberapa tabel di Azure Table Storage, di mana elemen dari setiap dokumen diproyeksikan ke dalam baris dalam tabel. Setiap tabel dapat memiliki tiga properti berikut.

Pertama, name (diperlukan) menentukan tabel yang akan dibuat atau digunakan di Azure Table Storage.

Kedua, 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.

Ketiga, 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).
Objek Memproyeksikan dokumen sebagai blob di Azure Blob Storage. Setiap objek memiliki dua properti yang diperlukan.

Pertama, storageContainer adalah nama kontainer yang akan dibuat atau digunakan di Azure Blob Storage.

Kedua, 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.
File Setiap entri file mendefinisikan penyimpanan gambar biner di Blob Storage.

Proyeksi file memiliki dua properti yang diperlukan. Pertama, storageContainer adalah nama kontainer yang akan dibuat atau digunakan di Azure Blob Storage.

Kedua, source adalah jalur ke simpul pohon pengayaan yang merupakan akar proyeksi. Nilai yang valid untuk properti ini "/document/normalized_images/*" untuk gambar yang bersumber dari Blob Storage.

encryptionKey

Mengonfigurasi koneksi ke Azure Key Vault untuk tambahan kunci enkripsi yang dikelola pelanggan (CMK). Enkripsi dengan kunci yang dikelola pelanggan tidak tersedia untuk layanan gratis. Untuk layanan yang dapat ditagih, layanan ini hanya tersedia untuk layanan pencarian yang dibuat pada atau setelah 2019-01-01.

Koneksi ke brankas kunci harus diautentikasi. Anda dapat menggunakan "accessCredentials" atau identitas terkelola untuk tujuan ini.

Identitas terkelola dapat berupa sistem atau ditetapkan pengguna (pratinjau). Jika layanan pencarian memiliki identitas terkelola yang ditetapkan sistem dan penetapan peran yang memberikan akses baca ke brankas kunci, Anda dapat menghilangkan "identitas" dan "accessCredentials", dan permintaan akan mengautentikasi menggunakan identitas terkelola. Jika layanan pencarian memiliki identitas dan penetapan peran yang ditetapkan pengguna, atur properti "identitas" ke ID sumber daya identitas tersebut.

Atribut Deskripsi
keyVaultKeyName Diperlukan. Nama kunci Azure Key Vault yang digunakan untuk enkripsi.
keyVaultKeyVersion Diperlukan. Versi kunci Azure Key Vault.
keyVaultUri Diperlukan. URI Azure Key Vault (juga disebut sebagai nama DNS) yang menyediakan kuncinya. Contoh URI mungkin https://my-keyvault-name.vault.azure.net.
accessCredentials Hilangkan jika Anda menggunakan identitas terkelola. Jika tidak, properti accessCredentials menyertakan applicationId (ID Aplikasi Azure Active Directory yang memiliki izin akses ke Azure Key Vault yang ditentukan), dan applicationSecret (kunci autentikasi aplikasi Azure AD yang ditentukan).
identitas Opsional kecuali Anda menggunakan identitas terkelola yang ditetapkan pengguna untuk koneksi layanan pencarian ke Azure Key Vault. Formatnya "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Lihat juga