Membuat set keterampilan di Azure AI Search

  • Artikel

indexer stages

Set keterampilan mendefinisikan operasi yang menghasilkan konten tekstual dan struktur dari dokumen yang berisi gambar atau teks yang tidak terstruktur. Contohnya adalah OCR untuk gambar, pengenalan entitas untuk teks yang tidak terpusat, dan terjemahan teks. Set keterampilan dijalankan setelah teks dan gambar diekstrak dari sumber data eksternal, dan setelah pemetaan bidang diproses .

Artikel ini menjelaskan cara membuat set keterampilan menggunakan REST API, tetapi konsep dan langkah yang sama berlaku untuk bahasa pemrograman lainnya.

Aturan untuk definisi skillset meliputi:

  • Nama unik dalam koleksi skillset. Skillset adalah sumber daya tingkat atas yang dapat digunakan oleh pengindeks apa pun.
  • Setidaknya satu keterampilan. Tiga hingga lima keterampilan khas. Maksimum adalah 30.
  • Sebuah skillset dapat mengulang keterampilan dari jenis yang sama (misalnya, beberapa keterampilan Shaper).
  • Set keterampilan mendukung operasi berantai, perulangan, dan percabangan.

Pengindeks mendorong eksekusi skillset. Anda 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. Di 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":"An Azure AI services resource in the same region as Azure AI 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:

  • skillsarray, kumpulan keterampilan yang tidak diurutkan. Keterampilan dapat berupa utilitarian (seperti memisahkan teks), transformasional (berdasarkan AI dari layanan Azure AI), atau keterampilan kustom yang Anda berikan. Contoh array keterampilan disediakan di bagian berikutnya.

  • cognitiveServices digunakan untuk keterampilan yang dapat ditagih yang memanggil API layanan Azure AI. 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 skillset 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 skillset, 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 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 menggambarkan 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 diambil 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. Seringkali 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 spesifik. 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 melalui 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 nama disambiguasi dalam 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 {i>skillset

  • Coba wizard Impor data.

    Wizard mengotomatiskan beberapa langkah yang dapat menantang pertama kalinya. Ini mendefinisikan skillset, indeks, dan pengindeks, termasuk pemetaan bidang dan pemetaan bidang output. Ini juga mendefinisikan 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 pemecahan dokumen.

    Setelah wizard berjalan, Anda dapat membuka setiap objek di portal Azure untuk melihat definisi JSON-nya.

  • Coba Sesi Debug untuk memanggil eksekusi set keterampilan melalui dokumen target dan periksa dokumen yang diperkaya yang dibuat set keterampilan. Anda dapat melihat dan memodifikasi pengaturan dan nilai input dan output. Tutorial ini adalah tempat yang baik untuk memulai: Tutorial: Men-debug set keterampilan menggunakan Sesi Debug.

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.

Mereferensikan anotasi dalam skillset