Membuat skillset di Azure Cognitive Search

tahap pengindeks

Skillset menentukan operasi yang mengekstrak dan memperkaya data untuk membuatnya dapat dicari. Ini dijalankan setelah teks dan gambar diekstrak, dan setelah pemetaan bidang diproses .

Artikel ini menjelaskan cara membuat set keterampilan dengan Create Skillset (REST API), tetapi konsep dan langkah yang sama berlaku untuk bahasa pemrograman lainnya.

Aturan untuk definisi set keterampilan meliputi:

  • Set keterampilan harus memiliki nama yang unik dalam koleksi set keterampilan. Saat menentukan set keterampilan, Anda membuat sumber daya tingkat atas yang dapat digunakan oleh pengindeks apa pun.
  • Sebuah skillset harus berisi setidaknya satu keterampilan. Set keterampilan yang khas memiliki tiga hingga lima. Maksimum adalah 30.
  • Sebuah skillset dapat mengulang keterampilan dari jenis yang sama (misalnya, beberapa keterampilan Shaper).
  • Set keterampilan mendukung operasi, perulangan, dan percabangan berantai.

Pengindeks mendorong eksekusi set keterampilan. Anda akan memerlukan pengindeks, sumber data, dan indeks sebelum dapat menguji set keterampilan Anda.

Tip

Aktifkan cache pengayaan untuk menggunakan kembali konten yang telah Anda proses dan menurunkan biaya pengembangan.

Menambahkan definisi set keterampilan

Mulailah dengan struktur dasar. Dalam Create Skillset REST API, isi permintaan ditulis di JSON dan memiliki bagian berikut:

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"A Cognitive Services resource in the same region as Azure Cognitive Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

Setelah nama dan deskripsi, skillset memiliki empat properti utama:

  • skills array, kumpulan keterampilan yang tidak berurutan. Keterampilan dapat bersifat utilitarian (seperti memisahkan teks), transformasional (berdasarkan AI dari Cognitive Services), atau keterampilan kustom yang Anda berikan. Contoh array keterampilan disediakan di bagian berikutnya.

  • cognitiveServices digunakan untuk keterampilan yang dapat ditagih yang memanggil API Cognitive Services. Hapus bagian ini jika Anda tidak menggunakan keterampilan yang dapat ditagih atau Pencarian Entitas Kustom. Lampirkan sumber daya jika Anda.

  • knowledgeStore (opsional) menentukan akun dan pengaturan Azure Storage untuk memproyeksikan output set keterampilan ke dalam tabel, blob, dan file di Azure Storage. Hapus bagian ini jika Anda tidak membutuhkannya, jika tidak tentukan penyimpanan pengetahuan.

  • encryptionKey(opsional) menentukan azure Key Vault dan kunci yang dikelola pelanggan yang digunakan untuk mengenkripsi konten sensitif (deskripsi, string koneksi, kunci) dalam definisi set keterampilan. Hapus properti ini jika Anda tidak menggunakan enkripsi yang dikelola pelanggan.

Menambahkan keterampilan

Di dalam definisi set keterampilan, array keterampilan menentukan keterampilan mana yang akan dijalankan. Tiga hingga lima keterampilan umum, tetapi Anda dapat menambahkan keterampilan sebanyak yang diperlukan, tunduk pada batas layanan.

Hasil akhir dari alur pengayaan adalah konten tekstual dalam indeks pencarian atau penyimpanan pengetahuan. Untuk alasan ini, sebagian besar keterampilan membuat teks dari gambar (teks OCR, keterangan, tag), atau menganalisis teks yang ada untuk membuat informasi baru (entitas, frasa kunci, sentimen). Keterampilan yang beroperasi secara independen diproses secara paralel. Keterampilan yang bergantung satu sama lain menentukan output dari satu keterampilan (seperti frasa kunci) sebagai input keterampilan kedua (seperti terjemahan teks). Layanan pencarian menentukan urutan eksekusi keterampilan dan lingkungan eksekusi.

Semua keterampilan memiliki jenis, konteks, input, dan output. Keterampilan mungkin secara opsional memiliki nama dan deskripsi. Contoh berikut menunjukkan dua keterampilan bawaan yang tidak terkait sehingga Anda dapat membandingkan struktur dasar.

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "name": "#1",
    "description": "This skill detects organizations in the source content",
    "context": "/document",
    "categories": [ "Organization" ],
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "organizations",
        "targetName": "orgs"
      }
    ]
  },
  {
      "name": "#2",
      "description": "This skill detects corporate logos in the source files",
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [
          "brands"
      ],
      "inputs": [
          {
              "name": "image",
              "source": "/document/normalized_images/*"
          }
      ],
      "outputs": [
          {
              "name": "brands"
          }
      ]
  }
]

Setiap keterampilan unik dalam hal nilai inputnya dan parameter yang diperlukan. Dokumentasi referensi keterampilan menjelaskan semua parameter dan properti keterampilan tertentu. Meskipun ada perbedaan, sebagian besar keterampilan berbagi kumpulan umum dan memiliki pola yang sama.

Catatan

Anda dapat membangun set keterampilan yang kompleks dengan perulangan dan percabangan menggunakan keterampilan Bersyukur untuk membuat ekspresi. Sintaksnya didasarkan pada notasi jalur JSON Pointer, dengan beberapa modifikasi untuk mengidentifikasi simpul di pohon pengayaan. Melintasi "/" tingkat yang lebih rendah di pohon dan "*" bertindak sebagai operator untuk-setiap dalam konteks. Banyak contoh dalam artikel ini mengilustrasikan sintaks.

Mengatur konteks keterampilan

Setiap keterampilan memiliki properti konteks yang menentukan tingkat di mana operasi berlangsung. Jika properti "konteks" tidak diatur secara eksplisit, defaultnya adalah "/document", di mana konteksnya adalah seluruh dokumen (keterampilan dipanggil sekali per dokumen).

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

Konteks biasanya diatur ke salah satu contoh berikut:

Contoh konteks Deskripsi
"context": "/document" (Default) Input dan output berada di tingkat dokumen.
"context": "/document/pages/*" Beberapa keterampilan seperti analisis sentimen berkinerja lebih baik daripada potongan teks yang lebih kecil. Jika Anda membagi bidang konten besar menjadi halaman atau kalimat, konteksnya harus di atas setiap bagian komponen.
"context": "/document/normalized_images/*" Untuk konten gambar, input dan output adalah satu per gambar dalam dokumen induk.

Konteks juga menentukan di mana output diproduksi di pohon pengayaan. Misalnya, keterampilan Pengenalan Entitas mengembalikan properti yang disebut "organizations", yang ditangkap sebagai orgs. Jika konteksnya adalah "/document", maka simpul "organisasi" ditambahkan sebagai anak dari "/document". Jika Anda kemudian ingin mereferensikan simpul ini dalam keterampilan hilir, jalurnya adalah "/document/orgs".

Menentukan input

Keterampilan membaca dari dan menulis ke dokumen yang diperkaya. Input keterampilan menentukan asal data masuk. Ini sering menjadi simpul akar dari dokumen yang diperkaya. Untuk blob, input keterampilan umum adalah properti konten dokumen.

Dokumentasi referensi keterampilan untuk setiap keterampilan menjelaskan input yang dapat dikonsumsinya. Setiap input memiliki "nama" yang mengidentifikasi input tertentu, dan "sumber" yang menentukan lokasi untuk data dalam dokumen yang diperkaya. Contoh berikut berasal dari keterampilan Pengenalan Entitas:

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]
  • Keterampilan dapat memiliki beberapa input. "Nama" adalah input khusus. Untuk Pengenalan Entitas, input tertentu adalah "teks" dan "languageCode".

  • Properti "sumber" menentukan bidang atau baris mana yang menyediakan konten yang akan diproses. Untuk keterampilan berbasis teks, sumbernya adalah bidang dalam dokumen atau baris yang menyediakan teks. Untuk keterampilan berbasis gambar, simpul yang menyediakan input adalah gambar yang dinormalisasi.

    Contoh sumber Deskripsi
    "source": "/document" Untuk himpunan data tabular, dokumen sesuai dengan baris.
    "source": "/document/content" Untuk blob, sumbernya biasanya merupakan properti konten blob.
    "source": "/document/some-named-field" Untuk keterampilan berbasis teks, seperti pengenalan entitas atau ekstraksi frasa kunci, asal harus menjadi bidang yang berisi teks yang cukup untuk dianalisis, seperti "deskripsi" atau "ringkasan".
    "sumber": "/document/normalized_images/*" Untuk konten gambar, sumbernya adalah gambar yang telah dinormalisasi selama pemecahan dokumen.

Jika keterampilan berulang di atas array, konteks dan sumber input harus disertakan /* dalam posisi yang benar.

Tentukan output

Setiap keterampilan dirancang untuk memancarkan jenis output tertentu, yang direferensikan dengan nama dalam skillset. Output keterampilan memiliki "nama" dan "targetName" opsional.

Dokumentasi referensi keterampilan untuk setiap keterampilan menjelaskan output yang dapat dihasilkannya. Contoh berikut berasal dari keterampilan Pengenalan Entitas:

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]
  • Keterampilan dapat memiliki beberapa output. "Nama" mengidentifikasi output tertentu. Misalnya, untuk Pengenalan Entitas, output dapat berupa "orang", "lokasi", "organisasi", antara lain.

  • "targetName" menentukan nama yang Anda inginkan untuk dimiliki simpul ini dalam dokumen yang diperkaya. Ini berguna jika output keterampilan memiliki nama yang sama. Jika Anda memiliki beberapa keterampilan yang mengembalikan output yang sama, gunakan "targetName" untuk disambiguasi nama di jalur simpul pengayaan. Jika nama target tidak ditentukan, properti nama digunakan untuk keduanya.

Beberapa situasi memerlukan referensi setiap elemen suatu array secara terpisah. Misalnya, Anda ingin meneruskan setiap elemen dari "/document/orgs" secara terpisah ke keterampilan lain. Untuk melakukannya, tambahkan tanda bintang ke jalur: "/document/orgs/*".

Output keterampilan ditulis ke dokumen yang diperkaya sebagai simpul baru di pohon pengayaan. Ini mungkin nilai sederhana, seperti skor sentimen atau kode bahasa. Ini juga bisa menjadi koleksi, seperti daftar organisasi, orang, atau lokasi. Output keterampilan juga dapat menjadi struktur yang kompleks, seperti halnya dengan keterampilan Shaper. Input keterampilan menentukan komposisi bentuk, tetapi outputnya adalah objek bernama, yang dapat direferensikan dalam indeks pencarian, proyeksi penyimpanan pengetahuan, atau keterampilan lain dengan namanya.

Menambahkan keterampilan kustom

Bagian ini mencakup contoh keterampilan kustom. URI menunjuk ke Fungsi Azure, yang pada gilirannya memanggil model atau transformasi yang Anda berikan. Untuk informasi selengkapnya, lihat Menentukan antarmuka kustom.

Meskipun keterampilan kustom mengeksekusi kode yang berada di luar alur, dalam array keterampilan, itu hanyalah keterampilan lain. Seperti keterampilan bawaan, keterampilan kustom memiliki jenis, konteks, input, dan output. Keterampilan kustom juga membaca dan menulis ke pohon pengayaan, seperti yang dilakukan keterampilan bawaan. Perhatikan bahwa bidang "konteks" diatur ke "/document/orgs/*" dengan tanda bintang, yang berarti langkah pengayaan dipanggil untuk setiap organisasi pada "/document/orgs".

Output, seperti deskripsi perusahaan dalam contoh ini, dihasilkan untuk setiap organisasi yang diidentifikasi. Ketika merujuk ke simpul dalam langkah hilir (misalnya, dalam ekstraksi frasa kunci), Anda akan menggunakan jalur "/document/orgs/*/companyDescription" untuk melakukannya.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=foo",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "foobar"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Mengirim output ke tujuan

Meskipun output keterampilan dapat secara opsional di-cache untuk tujuan penggunaan kembali, biasanya bersifat sementara dan hanya ada saat eksekusi keterampilan sedang berlangsung.

  • Untuk mengirim output ke bidang dalam indeks pencarian, buat pemetaan bidang output di pengindeks.

  • Untuk mengirim output ke penyimpanan pengetahuan, buat proyeksi.

  • Untuk mengirim output ke keterampilan hilir, referensikan output dengan nama simpulnya, seperti "/document/organization", di properti sumber input keterampilan hilir. Lihat Mereferensikan anotasi untuk contoh.

Tips untuk skillset pertama

  • Kumpulkan sampel representatif konten Anda di Blob Storage atau sumber data lain yang didukung dan jalankan wizard Impor data.

    Wizard mengotomatiskan beberapa langkah yang dapat menantang untuk pertama kalinya. Ini mendefinisikan skillset, indeks, dan pengindeks, termasuk pemetaan bidang dan pemetaan bidang output. Ini juga akan menentukan proyeksi di penyimpanan pengetahuan jika Anda menggunakannya. Untuk beberapa keterampilan, seperti OCR atau analisis gambar, wizard menambahkan keterampilan utilitas yang menggabungkan konten gambar dan teks yang dipisahkan selama peretasan dokumen.

    Setelah wizard berjalan, Anda dapat membuka setiap objek di portal Azure untuk melihat definisi JSON-nya. Anda juga dapat menggunakan Sesi Debug untuk memanggil eksekusi set keterampilan melalui dokumen target.

  • Atau, Anda dapat mengimpor sampel koleksi Postman yang menyediakan artikulasi lengkap definisi objek yang diperlukan untuk mengevaluasi keterampilan.

  • Ketika Anda siap untuk memulai dari awal pada set keterampilan baru, memeriksa hasil awal adalah penting. Kami merekomendasikan indeks pencarian untuk validasi konten karena lebih mudah disiapkan, dibandingkan dengan penyimpanan pengetahuan.

    Untuk setiap output keterampilan, tentukan pemetaan bidang output di pengindeks, dan bidang dalam indeks pencarian.

    Diagram objek yang memperlihatkan entitas orang sebagai output keterampilan, pemetaan bidang pengindeks, dan bidang indeks.

    Setelah Anda menjalankan pengindeks, gunakan Penjelajah Pencarian untuk mengembalikan dokumen dari indeks dan memeriksa konten setiap bidang untuk menentukan apa yang terdeteksi atau dibuat set keterampilan.

    Cuplikan layar ini menunjukkan hasil keterampilan pengenalan entitas yang mendeteksi orang, lokasi, organisasi, dan entitas lainnya dalam potongan teks. Anda dapat melihat hasilnya untuk memutuskan apakah keterampilan menambahkan nilai ke solusi Anda.

    Cuplikan layar dokumen di Penjelajah Pencarian.

Langkah berikutnya

Bidang konteks dan sumber input adalah jalur ke node di pohon pengayaan. Sebagai langkah berikutnya, pelajari selengkapnya tentang sintaks jalur untuk simpul di pohon pengayaan.