Keterampilan kognitif Pencarian Entitas Kustom

Artikel
09/01/2024

Keterampilan Pencarian Entitas Kustom digunakan untuk mendeteksi atau mengenali entitas yang Anda tentukan. Selama eksekusi skillset, keterampilan mencari teks dari daftar kata dan frasa kustom yang ditentukan pengguna. Keterampilan ini menggunakan daftar ini untuk melabeli entitas yang cocok yang ditemukan dalam dokumen sumber. Keterampilan ini juga mendukung tingkat pencocokan fuzzy yang dapat diterapkan untuk menemukan kecocokan yang serupa tetapi tidak persis.

Catatan

Keterampilan ini tidak terikat ke API layanan Azure AI tetapi memerlukan kunci layanan Azure AI untuk memungkinkan lebih dari 20 transaksi. Keterampilan ini diukur oleh Azure AI Search.

@odata.type

Microsoft.Skills.Text.CustomEntityLookupSkill

Batasan data

Ukuran catatan input maksimum yang didukung adalah 256 MB. Jika Anda perlu memecah data sebelum mengirimkannya ke keterampilan pencarian entitas kustom, pertimbangkan untuk menggunakan keterampilan Pemisahan Teks. Jika Anda menggunakan keterampilan pemisahan teks, atur panjang halaman ke 5000 untuk performa terbaik.
Ukuran maksimum definisi entitas kustom adalah 10 MB jika disediakan sebagai file eksternal, yang ditentukan melalui parameter "entitiesDefinitionUri".
Jika entitas didefinisikan sebaris menggunakan parameter "inlineEntitiesDefinition", ukuran maksimumnya adalah 10 KB.

Parameter keterampilan

Parameternya peka huruf besar/kecil.

Nama Parameter	Deskripsi
`entitiesDefinitionUri`	Jalur ke file JSON atau CSV eksternal yang berisi semua teks target yang cocok. Definisi entitas ini dibaca pada saat awal pengindeks dieksekusi; setiap pembaruan yang dilakukan terhadap file ini pada pertengahan eksekusi tidak akan direalisasikan hingga eksekusi berikutnya. File ini harus dapat diakses melalui HTTPS. Lihat Format Definisi Entitas Kustom di bawah ini untuk skema CSV atau JSON yang diharapkan.
`inlineEntitiesDefinition`	Definisi entitas JSON tidak terpisah. Parameter ini menggantikan parameter entitiesDefinitionUri jika ada. Konfigurasi yang disediakan tidak terpisah tidak boleh lebih dari 10 KB. Lihat Definisi Entitas Kustom di bawah ini untuk skema JSON yang diharapkan.
`defaultLanguageCode`	(Opsional) Kode bahasa dari teks input yang digunakan untuk membuat token dan menguraikan teks input. Bahasa berikut ini telah didukung: `da, de, en, es, fi, fr, it, pt`. Bahasa default adalah bahasa Inggris (`en`). Jika Anda meneruskan `languagecode-countrycode` format, hanya `languagecode` bagian format yang digunakan.
`globalDefaultCaseSensitive`	(Opsional) Nilai peka huruf besar/kecil default untuk keterampilan. Jika `defaultCaseSensitive` nilai entitas tidak ditentukan, nilai ini akan menjadi nilai untuk entitas tersebut `defaultCaseSensitive` .
`globalDefaultAccentSensitive`	(Optional) Nilai peka aksen default untuk keterampilan. Jika `defaultAccentSensitive` nilai entitas tidak ditentukan, nilai ini akan menjadi nilai untuk entitas tersebut `defaultAccentSensitive` .
`globalDefaultFuzzyEditDistance`	(Opsional) Nilai jarak edit fuzzy default untuk keterampilan. Jika `defaultFuzzyEditDistance` nilai entitas tidak ditentukan, nilai ini akan menjadi nilai untuk entitas tersebut `defaultFuzzyEditDistance` .

Input keterampilan

Masukkan nama	Deskripsi
`text`	Teks yang akan dianalisis.
`languageCode`	Opsional. Defaultnya adalah `"en"`.

Output keterampilan

Nama output Deskripsi

Nama output	Deskripsi
`entities`	Array jenis kompleks yang berisi bidang berikut: `"name"`: Entitas tingkat atas; ini mewakili bentuk "dinormalisasi". `"id"`: Pengidentifikasi unik untuk entitas seperti yang didefinisikan dalam "Definisi Entitas Kustom". `"description"`: Deskripsi entitas sebagaimana didefinisikan oleh pengguna dalam "Format Definisi Entitas Kustom". `"type"`: Jenis entitas seperti yang didefinisikan oleh pengguna dalam "Format Definisi Entitas Kustom". `"subtype"`: Subjenis entitas seperti yang didefinisikan oleh pengguna dalam "Format Definisi Entitas Kustom". `"matches"`: Array jenis kompleks yang berisi: `"text"` dari dokumen sumber `"offset"` lokasi di mana kecocokan ditemukan, `"length"` teks yang diukur dalam karakter `"matchDistance"` atau jumlah karakter yang berbeda antara kecocokan dan entitas `"name"`.

entities

Array jenis kompleks yang berisi bidang berikut:

"name": Entitas tingkat atas; ini mewakili bentuk "dinormalisasi".
"id": Pengidentifikasi unik untuk entitas seperti yang didefinisikan dalam "Definisi Entitas Kustom".
"description": Deskripsi entitas sebagaimana didefinisikan oleh pengguna dalam "Format Definisi Entitas Kustom".
"type": Jenis entitas seperti yang didefinisikan oleh pengguna dalam "Format Definisi Entitas Kustom".
"subtype": Subjenis entitas seperti yang didefinisikan oleh pengguna dalam "Format Definisi Entitas Kustom".
"matches": Array jenis kompleks yang berisi:
- "text" dari dokumen sumber
- "offset" lokasi di mana kecocokan ditemukan,
- "length" teks yang diukur dalam karakter
- "matchDistance" atau jumlah karakter yang berbeda antara kecocokan dan entitas "name".

Format definisi entitas kustom

Ada tiga pendekatan untuk menyediakan daftar entitas kustom untuk keterampilan Pencarian Entitas Kustom:

. File CSV (dikodekan UTF-8)
. File JSON (dikodekan UTF-8)
Sebaris dalam definisi keterampilan

Jika file definisi berada dalam . CSV atau . File JSON, berikan jalur lengkap dalam parameter "entitiesDefinitionUri". File diunduh di awal setiap pengindeks berjalan. Ini harus tetap dapat diakses sampai pengindeks berhenti.

Jika Anda menggunakan definisi sebaris, tentukan di bawah parameter keterampilan "inlineEntitiesDefinition".

Catatan

Pengindeks mendukung mode penguraian khusus untuk file JSON dan CSV. Saat menggunakan keterampilan pencarian entitas kustom, tetap atur "parsingMode" ke "default". Keterampilan ini mengharapkan JSON dan CSV dalam keadaan yang tidak diurai.

Format CSV

Anda dapat memberikan definisi entitas kustom untuk dicari dalam file Comma-Separated Value (CSV) dengan menyediakan jalur ke file dan mengaturnya di parameter keterampilan "entitiesDefinitionUri". Jalur harus berada di lokasi https. File definisi dapat berukuran hingga 10 MB.

Format CSV sederhana. Setiap baris mewakili entitas yang unik, seperti yang ditunjukkan di bawah ini:

Bill Gates, BillG, William H. Gates
Microsoft, MSFT
Satya Nadella

Dalam hal ini, ada tiga entitas yang dapat dikembalikan (Bill Gates, Satya Nadella, Microsoft). Alias mengikuti setelah entitas utama. Kecocokan pada alias dibundel di bawah entitas utama. Misalnya, jika string "William H. Gates" ditemukan dalam dokumen, kecocokan untuk entitas "Bill Gates" akan dikembalikan.

Format JSON

Anda juga dapat memberikan definisi entitas kustom untuk dicari di dalam file JSON. Format JSON memberikan sedikit lebih banyak fleksibilitas karena memungkinkan Anda untuk menentukan aturan yang cocok per istilah. Misalnya, Anda dapat menentukan jarak pencocokan fuzzy (jarak Damerau-Levenshtein) untuk setiap istilah atau apakah pencocokan harus peka huruf besar/kecil atau tidak.

Sama seperti file CSV, Anda perlu menyediakan jalur ke file JSON dan mengaturnya dalam parameter keterampilan "entitiesDefinitionUri". Jalur harus berada di lokasi https. File definisi dapat berukuran hingga 10 MB.

Definisi daftar entitas kustom JSON yang paling mendasar dapat menjadi daftar entitas yang cocok:

[ 
    { 
        "name" : "Bill Gates"
    }, 
    { 
        "name" : "Microsoft"
    }, 
    { 
        "name" : "Satya Nadella"
    }
]

Definisi yang lebih kompleks dapat memberikan ID, deskripsi, jenis, subjenis, dan alias yang ditentukan pengguna. Jika istilah alias cocok, entitas akan ditampilkan juga:

[ 
    { 
        "name" : "Bill Gates",
        "description" : "Microsoft founder." ,
        "aliases" : [ 
            { "text" : "William H. Gates", "caseSensitive" : false },
            { "text" : "BillG", "caseSensitive" : true }
        ]
    }, 
    { 
        "name" : "Xbox One", 
        "type": "Hardware",
        "subtype" : "Gaming Device",
        "id" : "4e36bf9d-5550-4396-8647-8e43d7564a76",
        "description" : "The Xbox One product"
    }, 
    { 
        "name" : "LinkedIn" , 
        "description" : "The LinkedIn company", 
        "id" : "differentIdentifyingScheme123", 
        "fuzzyEditDistance" : 0 
    }, 
    { 
        "name" : "Microsoft" , 
        "description" : "Microsoft Corporation", 
        "id" : "differentIdentifyingScheme987", 
        "defaultCaseSensitive" : false, 
        "defaultFuzzyEditDistance" : 1, 
        "aliases" : [ 
            { "text" : "MSFT", "caseSensitive" : true }
        ]
    } 
]

Tabel di bawah ini menjelaskan parameter konfigurasi yang dapat Anda tetapkan saat menentukan entitas kustom:

Nama bidang	Deskripsi
`name`	Deskriptor entitas tingkat atas. Kecocokan dalam output keterampilan akan dikelompokkan berdasarkan nama ini, dan harus mewakili bentuk "dinormalisasi" dari teks yang ditemukan.
`description`	(Opsional) Bidang ini dapat digunakan sebagai passthrough untuk metadata kustom tentang teks yang cocok. Nilai bidang ini akan muncul bersama setiap kecocokan entitasnya dalam output keterampilan.
`type`	(Opsional) Bidang ini dapat digunakan sebagai passthrough untuk metadata kustom tentang teks yang cocok. Nilai bidang ini akan muncul bersama setiap kecocokan entitasnya dalam output keterampilan.
`subtype`	(Opsional) Bidang ini dapat digunakan sebagai passthrough untuk metadata kustom tentang teks yang cocok. Nilai bidang ini akan muncul bersama setiap kecocokan entitasnya dalam output keterampilan.
`id`	(Opsional) Bidang ini dapat digunakan sebagai passthrough untuk metadata kustom tentang teks yang cocok. Nilai bidang ini akan muncul bersama setiap kecocokan entitasnya dalam output keterampilan.
`caseSensitive`	(Opsional) Default ke false. Nilai Boolean yang menunjukkan apakah perbandingan dengan nama entitas harus sensitif terhadap huruf besar/kecil atau tidak. Contoh kecocokan peka huruf besar/kecil dari entitas "Microsoft" bisa menjadi: microsoft, microSoft, MICROSOFT
`accentSensitive`	(Opsional) Default ke false. Nilai Boolean yang menunjukkan apakah huruf beraksen dan tidak beraksen seperti 'é' dan 'e' harus identik.
`fuzzyEditDistance`	(Opsional) Default ke 0. Nilai maksimum 5. Menunjukkan jumlah karakter berbeda yang dapat diterima yang masih dapat menghasilkan kecocokan dengan nama entitas. Fuzzy terkecil untuk setiap kecocokan ditampilkan. Misalnya, jika jarak edit diatur ke 3, "Windows 10" masih akan cocok dengan "Windows", "Windows10" dan "windows 7". Saat peka huruf besar/kecil diatur ke false, perbedaan huruf besar/kecil TIDAK akan dihitung oleh toleransi fuzzy, tetapi sebaliknya.
`defaultCaseSensitive`	(Opsional) Mengubah nilai default dari peka huruf besar/kecil untuk entitas ini. Tindakan ini dapat digunakan untuk mengubah nilai default dari semua nilai aliases caseSensitive alias.
`defaultAccentSensitive`	(Opsional) Mengubah nilai default dari peka aksen untuk entitas ini. Tindakan ini dapat digunakan untuk mengubah nilai default dari semua nilai accentSensitive alias.
`defaultFuzzyEditDistance`	(Opsional) Mengubah nilai jarak edit fuzzy default untuk entitas ini. Tindakan ini dapat digunakan untuk mengubah nilai default dari semua nilai fuzzyEditDistance alias.
`aliases`	(Opsional) Array objek kompleks yang dapat digunakan untuk menentukan ejaan atau sinonim alternatif ke nama entitas akar.

Properti alias	Deskripsi
`text`	Ejaan atau representasi alternatif dari beberapa nama entitas target.
`caseSensitive`	(Opsional) Bertindak sama dengan parameter "caseSensitive" entitas akar di atas, tetapi hanya berlaku untuk alias yang satu ini.
`accentSensitive`	(Opsional) Bertindak sama dengan parameter "accentSensitive" entitas akar di atas, tetapi hanya berlaku untuk alias yang satu ini.
`fuzzyEditDistance`	(Opsional) Bertindak sama dengan parameter "fuzzyEditDistance" entitas akar di atas, tetapi hanya berlaku untuk alias yang satu ini.

Format tidak terpisah

Dalam beberapa kasus, mungkin lebih nyaman untuk menyematkan definisi entitas kustom sehingga sebaris dengan definisi keterampilan. Anda dapat menggunakan format JSON yang sama dengan yang dijelaskan di atas, kecuali bahwa format tersebut disertakan dalam definisi keterampilan. Hanya konfigurasi yang berukuran kurang dari 10 KB (ukuran serial) yang dapat didefinisikan tidak terpisah.

Sampel definisi keterampilan

Definisi keterampilan sampel menggunakan format tidak terpisah ditampilkan di bawah ini:

  {
    "@odata.type": "#Microsoft.Skills.Text.CustomEntityLookupSkill",
    "context": "/document",
    "inlineEntitiesDefinition": 
    [
      { 
        "name" : "Bill Gates",
        "description" : "Microsoft founder." ,
        "aliases" : [ 
            { "text" : "William H. Gates", "caseSensitive" : false },
            { "text" : "BillG", "caseSensitive" : true }
        ]
      }, 
      { 
        "name" : "Xbox One", 
        "type": "Hardware",
        "subtype" : "Gaming Device",
        "id" : "4e36bf9d-5550-4396-8647-8e43d7564a76",
        "description" : "The Xbox One product"
      }
    ],    
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "entities",
        "targetName": "matchedEntities"
      }
    ]
  }

Atau, Anda dapat menunjuk ke file definisi entitas eksternal. Contoh definisi keterampilan menggunakan format ditunjukkan entitiesDefinitionUri di bawah ini:

  {
    "@odata.type": "#Microsoft.Skills.Text.CustomEntityLookupSkill",
    "context": "/document",
    "entitiesDefinitionUri": "https://myblobhost.net/keyWordsConfig.csv",    
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "entities",
        "targetName": "matchedEntities"
      }
    ]
  }

Contoh definisi indeks

Bagian ini menyediakan contoh definisi indeks. "Entitas" dan "kecocokan" adalah array dari jenis kompleks. Anda dapat memiliki beberapa entitas per dokumen, dan beberapa kecocokan untuk setiap entitas.

{
  "name": "entities",
  "type": "Collection(Edm.ComplexType)",
  "fields": [
    {
      "name": "name",
      "type": "Edm.String",
      "facetable": false,
      "filterable": false,
      "retrievable": true,
      "searchable": true,
      "sortable": false,
    },
    {
      "name": "id",
      "type": "Edm.String",
      "facetable": false,
      "filterable": false,
      "retrievable": true,
      "searchable": false,
      "sortable": false,
    },
    {
      "name": "description",
      "type": "Edm.String",
      "facetable": false,
      "filterable": false,
      "retrievable": true,
      "searchable": true,
      "sortable": false,
    },
    {
      "name": "type",
      "type": "Edm.String",
      "facetable": true,
      "filterable": true,
      "retrievable": true,
      "searchable": false,
      "sortable": false,
    },
    {
      "name": "subtype",
      "type": "Edm.String",
      "facetable": true,
      "filterable": true,
      "retrievable": true,
      "searchable": false,
      "sortable": false,
    },
    {
      "name": "matches",
      "type": "Collection(Edm.ComplexType)",
      "fields": [
        {
          "name": "text",
          "type": "Edm.String",
          "facetable": false,
          "filterable": false,
          "retrievable": true,
          "searchable": true,
          "sortable": false,
        },
        {
          "name": "offset",
          "type": "Edm.Int32",
          "facetable": true,
          "filterable": true,
          "retrievable": true,
          "sortable": false,
        },
        {
          "name": "length",
          "type": "Edm.Int32",
          "facetable": true,
          "filterable": true,
          "retrievable": true,
          "sortable": false,
        },
        {
          "name": "matchDistance",
          "type": "Edm.Double",
          "facetable": true,
          "filterable": true,
          "retrievable": true,
          "sortable": false,
        }
      ]
    }
  ]
}

Contoh data input

{
    "values": [
      {
        "recordId": "1",
        "data":
           {
             "text": "The company, Microsoft, was founded by Bill Gates. Microsoft's gaming console is called Xbox",
             "languageCode": "en"
           }
      }
    ]
}

Sampel output

  { 
    "values" : 
    [ 
      { 
        "recordId": "1", 
        "data" : { 
          "entities": [
            { 
              "name" : "Microsoft", 
              "description" : "This document refers to Microsoft the company", 
              "id" : "differentIdentifyingScheme987", 
              "matches" : [ 
                { 
                  "text" : "microsoft", 
                  "offset" : 13, 
                  "length" : 9, 
                  "matchDistance" : 0 
                }, 
                { 
                  "text" : "Microsoft",
                  "offset" : 49, 
                  "length" : 9, 
                  "matchDistance" : 0
                }
              ] 
            },
            { 
              "name" : "Bill Gates",
              "description" : "William Henry Gates III, founder of Microsoft.", 
              "matches" : [
                { 
                  "text" : "Bill Gates",
                  "offset" : 37, 
                  "length" : 10,
                  "matchDistance" : 0 
                }
              ]
            }
          ] 
        } 
      } 
    ] 
  }

Peringatan

"Reached maximum capacity for matches, skipping all further duplicate matches."

Peringatan ini akan ditampilkan jika jumlah kecocokan yang terdeteksi lebih besar dari maksimum yang diperbolehkan. Tidak ada lagi kecocokan duplikat yang akan dikembalikan. Jika Anda memerlukan ambang batas yang lebih tinggi, Anda dapat mengajukan tiket dukungan untuk bantuan terkait kasus penggunaan individual Anda.

Bagikan melalui