Mereferensikan jalur ke simpul yang diperkaya menggunakan properti konteks dan sumber kumpulan keterampilan Azure AI Search

Artikel
01/19/2024

Selama eksekusi skillset, mesin membangun pohon pengayaan dalam memori yang menangkap setiap pengayaan, seperti entitas yang dikenali atau teks yang diterjemahkan. Dalam artikel ini, pelajari cara mereferensikan simpul pengayaan di pohon pengayaan sehingga Anda dapat meneruskan output ke keterampilan hilir atau menentukan pemetaan bidang output untuk bidang indeks pencarian.

Artikel ini menggunakan contoh untuk mengilustrasikan berbagai skenario. Untuk sintaks lengkapnya, lihat Konteks keterampilan dan bahasa bahasa anotasi input.

Konsep latar belakang

Sebelum meninjau sintaks, mari kita buka kembali beberapa konsep penting untuk lebih memahami contoh yang disediakan nanti dalam artikel ini.

Persyaratan	Deskripsi
"dokumen yang diperkaya"	Dokumen yang diperkaya adalah struktur dalam memori yang mengumpulkan output keterampilan saat dibuat dan menyimpan semua pengayaan yang terkait dengan dokumen. Anggap dokumen yang diperkaya sebagai pohon. Umumnya, pohon dimulai pada tingkat dokumen akar, dan setiap pengayaan baru dibuat dari sebelumnya sebagai anaknya.
"node"	Dalam dokumen yang diperkaya, simpul (terkadang disebut sebagai "anotasi") dibuat dan diisi oleh keterampilan, seperti "teks" dan "layoutText" dalam keterampilan OCR. Dokumen yang diperkaya diisi dengan pengayaan dan nilai bidang sumber asli atau metadata yang disalin dari sumber.
"konteks"	Cakupan pengayaan, yang merupakan seluruh dokumen, sebagian dokumen, atau jika Anda bekerja dengan gambar, gambar yang diekstrak dari dokumen. Secara default, konteks pengayaan berada di tingkat , `"/document"` dilingkupkan ke dokumen individual yang terkandung dalam sumber data. Saat keterampilan dijalankan, output keterampilan tersebut menjadi properti konteks yang ditentukan.

Jalur untuk skenario yang berbeda

Jalur ditentukan dalam properti "konteks" dan "sumber" dari set keterampilan, dan dalam pemetaan bidang output dalam pengindeks.

Contoh dalam cuplikan layar mengilustrasikan jalur untuk item dalam koleksi Azure Cosmos DB.

context jalur adalah /document/HotelId karena koleksi dipartisi ke dalam dokumen menurut /HotelId bidang .
source jalur adalah /document/Description karena keterampilan adalah keterampilan terjemahan, dan bidang yang Anda inginkan untuk diterjemahkan keterampilan adalah Description bidang di setiap dokumen.

Semua jalur dimulai dengan /document. Dokumen yang diperkaya dibuat dalam tahap "pemecahan dokumen" eksekusi pengindeks, ketika pengindeks membuka dokumen atau membaca secara berurutan dari sumber data. Awalnya, satu-satunya simpul dalam dokumen yang diperkaya adalah simpul akar (/document), dan itu adalah simpul tempat semua pengayaan lainnya terjadi.

Daftar berikut ini mencakup beberapa contoh umum:

/document adalah simpul akar dan menunjukkan seluruh blob di Azure Storage, atau baris dalam tabel SQL.
/document/{key} adalah sintaks untuk dokumen atau item dalam koleksi Azure Cosmos DB, di mana {key} adalah kunci aktual, seperti /document/HotelId dalam contoh sebelumnya.
/document/content menentukan properti "konten" dari blob JSON.
/document/{field} adalah sintaks untuk operasi yang dilakukan pada bidang tertentu, seperti menerjemahkan /document/Description bidang, yang terlihat dalam contoh sebelumnya.
/document/pages/* atau /document/sentences/* menjadi konteks jika Anda memecah dokumen besar menjadi potongan yang lebih kecil untuk diproses. Jika "konteks" adalah /document/pages/*, keterampilan dijalankan sekali di setiap halaman dalam dokumen. Karena mungkin ada lebih dari satu halaman atau kalimat, Anda akan menambahkan /* untuk menangkap semuanya.
/document/normalized_images/* dibuat selama pemecahan dokumen jika dokumen berisi gambar. Semua jalur ke gambar dimulai dengan normalized_images. Karena sering ada beberapa gambar yang disematkan dalam dokumen, tambahkan /*.

Contoh di sisa artikel ini didasarkan pada bidang "konten" yang dihasilkan secara otomatis oleh pengindeks blob Azure sebagai bagian dari fase pemecahan dokumen. Saat merujuk ke dokumen dari kontainer Blob, gunakan format seperti "/document/content", di mana bidang "konten" adalah bagian dari "dokumen".

Contoh 1: Referensi anotasi sederhana

Di Azure Blob Storage, misalkan Anda memiliki berbagai file yang berisi referensi ke nama orang yang ingin diekstrak menggunakan pengenalan entitas. Dalam definisi keterampilan berikut, "/document/content" adalah representasi tekstual dari seluruh dokumen, dan "orang" adalah ekstraksi nama lengkap untuk entitas yang diidentifikasi sebagai orang.

Karena konteks defaultnya adalah "/document", daftar orang kini dapat direferensikan sebagai "/document/people". Dalam kasus tertentu, "/document/people" adalah anotasi, yang kini dapat dipetakan ke bidang dalam indeks, atau digunakan dalam keterampilan lain dalam set keterampilan yang sama.

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

Contoh 2: Mereferensikan larik dalam dokumen

Contoh ini disusun pada contoh sebelumnya, yang memperlihatkan Anda cara menggunakan langkah pengayaan beberapa kali atas dokumen yang sama. Asumsikan contoh sebelumnya menghasilkan larik string dengan 10 nama orang dari satu dokumen. Langkah berikutnya yang masuk akal mungkin merupakan pengayaan kedua yang mengekstrak nama belakang dari nama lengkap. Karena ada 10 nama, Anda menginginkan langkah ini digunakan 10 kali dalam dokumen ini, sekali untuk setiap orang.

Untuk menggunakan jumlah perulangan yang tepat, tetapkan konteks sebagai "/document/people/*", dengan keterangan tanda bintang ("*") mewakili semua simpul dalam dokumen yang diperkaya sebagai turunan "/document/people". Meskipun keterampilan ini hanya didefinisikan sekali dalam array keterampilan, keterampilan ini dipanggil untuk setiap anggota dalam dokumen sampai semua anggota diproses.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

Jika anotasi berupa larik atau koleksi untai, sebaiknya targetkan anggota tertentu, bukan larik sebagai keseluruhan. Contoh di atas menghasilkan anotasi yang disebut "last" di bawah setiap simpul yang diwakili oleh konteks. Jika ingin merujuk ke keluarga anotasi ini, Anda dapat menggunakan sintaks "/document/people/*/last". Jika Anda ingin merujuk ke anotasi tertentu, Anda dapat menggunakan indeks eksplisit: "/document/people/1/last" untuk mereferensikan nama belakang orang pertama yang diidentifikasi dalam dokumen. Perhatikan bahwa dalam larik sintaks ini adalah "0 terindeks".

Contoh 3: Mereferensikan anggota dalam larik

Terkadang Anda perlu mengelompokkan semua anotasi jenis tertentu untuk meneruskannya ke keterampilan tertentu. Pertimbangkan keterampilan kustom hipotetis yang mengidentifikasi nama belakang yang paling umum dari semua nama belakang yang diekstrak dalam Contoh 2. Untuk memberikan nama belakang saja ke keterampilan kustom, tentukan konteks sebagai "/document" dan input sebagai "/document/people/*/lastname".

Perhatikan bahwa kardinalitas "/document/people/*/lastname" lebih besar daripada kardinalitas dokumen. Mungkin ada 10 simpul nama belakang sementara hanya ada satu simpul dokumen untuk dokumen ini. Dalam hal ini, sistem akan secara otomatis membuat array "/document/people/*/lastname" yang berisi semua elemen dalam dokumen.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

Tips untuk pemecahan masalah jalur anotasi

Jika Anda mengalami masalah dalam menentukan input keterampilan, tips ini mungkin membantu Anda maju:

Jalankan wizard Impor data di atas data Anda untuk meninjau definisi set keterampilan dan pemetaan bidang yang dihasilkan wizard.
Mulai sesi debug pada set keterampilan untuk melihat struktur dokumen yang diperkaya. Anda dapat mengedit jalur dan bagian lain dari definisi keterampilan, lalu menjalankan keterampilan untuk memvalidasi perubahan Anda.