Membuat kumpulan keterampilan di Pencarian Azure AI

Set keterampilan mendefinisikan operasi yang menghasilkan konten dan struktur vektor dan tekstual dari dokumen yang berisi gambar atau konten mentah. Contohnya adalah keterampilan pemecahan, keterampilan penyematan (vektorisasi), verbalisasi gambar, dan proses lainnya, seperti pengenalan karakter optik (OCR) untuk citra, pengenalan entitas untuk teks yang tidak terstruktur, dan terjemahan teks. Rangkaian keterampilan dijalankan setelah ekstraksi konten mentah dari sumber data eksternal, dan setelah pemrosesan pemetaan bidang selesai.

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:

• Harus memiliki nama unik dalam kumpulan keterampilan. Skillset adalah sumber daya tingkat atas yang dapat digunakan oleh pengindeks apa pun.
• Harus memiliki setidaknya satu keterampilan. Tiga hingga lima keterampilan khas. Maksimum adalah 30.
• Kumpulan keterampilan dapat mengulangi keterampilan yang sejenis. Misalnya, sebuah skillset dapat memiliki beberapa keterampilan Shaper.
• Set keterampilan mendukung operasi berantai, perulangan, dan percabangan.

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

Menambahkan definisi set keterampilan

Saat membuat set keterampilan, Anda menambahkannya ke layanan pencarian Anda. Saat Anda memperbarui kumpulan keterampilan, Anda menimpa sepenuhnya kumpulan keterampilan yang ada dengan isi payload permintaan. Untuk memperbarui set keterampilan, ambil definisi set keterampilan dengan menggunakan GET, ubah, lalu perbarui dengan menggunakan PUT.

Mulailah dengan struktur dasar. Di Create Skillset REST API, tulis isi permintaan di JSON. Ini 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 Microsoft Foundry resource in the same region as Azure AI Search",
      "key":"<Your-Microsoft-Foundry-Resource-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. Keahlian dapat berdiri sendiri atau diintegrasikan melalui asosiasi input-output, di mana output dari satu perubahan menjadi input ke yang lainnya. Keterampilan dapat berupa utilitarian (seperti memisahkan teks), transformasional (berdasarkan AI dari Azure OpenAI atau Foundry Tools), atau keterampilan kustom yang Anda berikan. Contoh array keterampilan disediakan di bagian berikutnya.

• cognitiveServices digunakan untuk keterampilan yang dapat ditagih yang memanggil FOUNDRY Tools API. Hapus bagian ini jika Anda tidak menggunakan keterampilan yang dikenai biaya atau Pencarian Entitas Khusus. Jika ya, lampirkan sumber daya Foundry.

• 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 oleh pelanggan yang digunakan untuk mengenkripsi konten sensitif (deskripsi, string koneksi, kunci) dalam definisi kemampuan. 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.

Mengatur konteks keterampilan

Setiap keterampilan memiliki properti konteks yang menentukan tingkat di mana operasi berlangsung. context Jika properti 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": []
  }
]

Atur context properti ke salah satu contoh berikut:

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 organizations ditambahkan sebagai anak dari "/document". Jika Anda kemudian ingin mereferensikan simpul ini dalam keterampilan hilir, jalurnya adalah "/document/orgs".

Tentukan input

Kemampuan untuk membaca dan menulis pada dokumen yang telah diperkaya. Input keahlian menentukan sumber asal data yang masuk. Seringkali simpul akar dari dokumen yang diperkaya. Untuk blob, input keterampilan yang umum digunakan adalah properti konten dokumen.

Dokumentasi referensi keterampilan untuk setiap keterampilan menjelaskan input yang dapat dikonsumsinya. Setiap input memiliki name yang mengidentifikasi input tertentu, dan source yang menentukan lokasi 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. name adalah input khusus. Untuk Pengenalan Entitas, input tertentu adalah teks dan languageCode.

• Properti source 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	Description
  source: /document	Untuk himpunan data tabular, dokumen sesuai dengan baris.
  source: /document/content	Untuk blob, sumbernya biasanya berasal dari 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.
  source: /document/normalized_images/*	Untuk konten gambar, sumbernya adalah gambar yang telah dinormalisasi selama pemecahan dokumen.

Jika keterampilan mengiterasi melalui array, baik konteks maupun sumber input harus menyertakan /* dalam posisi yang benar. Untuk informasi selengkapnya tentang sintaks lengkapnya, lihat Konteks keterampilan dan bahasa anotasi input.

Menentukan keluaran

Setiap skill dirancang untuk menghasilkan jenis keluaran tertentu, yang dirujuk oleh skillset berdasarkan namanya. Output keterampilan memiliki name dan targetName yang bersifat 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. Properti name mengidentifikasi output tertentu. Misalnya, untuk Pengenalan Entitas, output dapat berupa orang, lokasi, organisasi, antara lain.

• Properti targetName menentukan nama yang ingin Anda berikan pada simpul ini dalam dokumen yang diperkaya. Properti ini berguna jika output keterampilan memiliki nama yang sama. Jika Anda memiliki beberapa keterampilan yang mengembalikan output yang sama, gunakan targetName untuk pemilahan nama dalam simpul jalur pengayaan. Jika Anda tidak menentukan nama target, 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/*".

Hasil keterampilan ditambahkan 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 Menambahkan kemampuan kustom ke pipeline pengayaan Pencarian Azure AI.

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

Output, seperti deskripsi perusahaan pada contoh ini, dihasilkan untuk setiap organisasi yang telah diidentifikasi. Ketika merujuk ke simpul dalam langkah hilir (misalnya, dalam ekstraksi frasa kunci), gunakan 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=<YOUR-FUNCTION-KEY>",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "<YOUR-APIM-KEY>"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Mengirim output ke tujuan

Meskipun Anda dapat secara opsional menyimpan output keterampilan untuk digunakan 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 set keterampilan pertama

• Coba panduan Impor data.

  Wizard mengotomatiskan beberapa langkah yang dapat menantang pertama kalinya. Ini mendefinisikan sekumpulan keterampilan, indeks, dan pengindeks, termasuk pemetaan bidang dan pemetaan keluaran bidang. Ini juga mendefinisikan proyeksi pada 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 Debug Sessions untuk memanggil pelaksanaan skillset pada dokumen target dan memeriksa dokumen yang diperkaya yang dibuat oleh skillset. Anda dapat melihat dan memodifikasi pengaturan dan nilai input dan output. Tutorial ini adalah tempat yang baik untuk memulai: Tutorial: Debug kumpulan keterampilan menggunakan Debug Sessions.

Langkah selanjutnya

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