Competenza cognitiva ricerca entità personalizzata

Articolo
09/01/2024

La competenza Ricerca entità personalizzata viene usata per rilevare o riconoscere le entità definite dall'utente. Durante l'esecuzione del set di competenze, la competenza cerca testo da un elenco personalizzato definito dall'utente di parole e frasi. La competenza usa questo elenco per etichettare le entità corrispondenti trovate all'interno dei documenti di origine. La competenza supporta anche un grado di corrispondenza fuzzy che può essere applicato per trovare corrispondenze simili ma non esatte.

Nota

Questa competenza non è associata a un'API dei servizi di intelligenza artificiale di Azure, ma richiede una chiave dei servizi di intelligenza artificiale di Azure per consentire più di 20 transazioni. Questa competenza viene rilevata da Ricerca di intelligenza artificiale di Azure.

@odata.type

Microsoft.Skills.Text.CustomEntityLookupSkill

Limiti dei dati

La dimensione massima del record di input supportata è 256 MB. Se è necessario suddividere i dati prima di inviarli alla competenza di ricerca di entità personalizzata, è consigliabile usare la competenza Suddivisione testo. Se si usa una competenza di suddivisione del testo, impostare la lunghezza della pagina su 5000 per ottenere prestazioni ottimali.
La dimensione massima della definizione di entità personalizzata è di 10 MB se viene fornita come file esterno, specificata tramite il parametro "entitiesDefinitionUri".
Se le entità vengono definite inline usando il parametro "inlineEntitiesDefinition", la dimensione massima è di 10 KB.

Parametri della competenza

I parametri fanno distinzione tra maiuscole e minuscole.

Nome parametro	Descrizione
`entitiesDefinitionUri`	Percorso di un file JSON o CSV esterno contenente tutto il testo di destinazione rispetto a cui trovare la corrispondenza. Questa definizione di entità viene letta all'inizio di un'esecuzione dell'indicizzatore; tutti gli aggiornamenti di questo file a metà esecuzione non verranno resi disponibili fino alle esecuzioni successive. Questo file deve essere accessibile tramite HTTPS. Vedere Custom Entity Definition Format (Formato definizione entità personalizzata) di seguito per lo schema CSV o JSON previsto.
`inlineEntitiesDefinition`	Definizioni di entità JSON inline. Questo parametro sostituisce il parametro entitiesDefinitionUri, se presente. Non è possibile specificare più di 10 KB di configurazione inline. Vedere Definizione di entità personalizzata di seguito per lo schema JSON previsto.
`defaultLanguageCode`	(Facoltativo) Codice linguistico del testo di input usato per tokenizzare e delineare il testo di input. Sono supportate le lingue seguenti: `da, de, en, es, fi, fr, it, pt`. Il valore predefinito è Inglese (`en`). Se si passa un `languagecode-countrycode` formato, viene utilizzata solo la `languagecode` parte del formato.
`globalDefaultCaseSensitive`	(Facoltativo) Valore con distinzione tra maiuscole e minuscole predefinito per la competenza. Se `defaultCaseSensitive` il valore di un'entità non viene specificato, questo valore diventerà il `defaultCaseSensitive` valore per tale entità.
`globalDefaultAccentSensitive`	(Facoltativo) Valore predefinito per la distinzione tra caratteri accentati e accentati per la competenza. Se `defaultAccentSensitive` il valore di un'entità non viene specificato, questo valore diventerà il `defaultAccentSensitive` valore per tale entità.
`globalDefaultFuzzyEditDistance`	(Facoltativo) Valore predefinito della distanza di modifica fuzzy per la competenza. Se `defaultFuzzyEditDistance` il valore di un'entità non viene specificato, questo valore diventerà il `defaultFuzzyEditDistance` valore per tale entità.

Input competenze

Nome input	Descrizione
`text`	Testo da analizzare.
`languageCode`	Facoltativo. Il valore predefinito è `"en"`.

Output competenze

Nome output Descrizione

Nome output	Descrizione
`entities`	Matrice di tipi complessi che contiene i campi seguenti: `"name"`: l'entità di primo livello; rappresenta il formato "normalizzato". `"id"`: identificatore univoco per l'entità come definito in "Definizione di entità personalizzata". `"description"`: Descrizione dell'entità definita dall'utente in "Custom Entity Definition Format". `"type"`: tipo di entità definito dall'utente in "Custom Entity Definition Format". `"subtype"`: sottotipo di entità come definito dall'utente in "Custom Entity Definition Format". `"matches"`: matrice di tipi complessi che contengono: `"text"` dal documento di origine `"offset"` posizione in cui è stata trovata la corrispondenza, `"length"` del testo misurato in caratteri `"matchDistance"` o il numero di caratteri che differiscono tra la corrispondenza e l'entità `"name"`.

entities

Matrice di tipi complessi che contiene i campi seguenti:

"name": l'entità di primo livello; rappresenta il formato "normalizzato".
"id": identificatore univoco per l'entità come definito in "Definizione di entità personalizzata".
"description": Descrizione dell'entità definita dall'utente in "Custom Entity Definition Format".
"type": tipo di entità definito dall'utente in "Custom Entity Definition Format".
"subtype": sottotipo di entità come definito dall'utente in "Custom Entity Definition Format".
"matches": matrice di tipi complessi che contengono:
- "text" dal documento di origine
- "offset" posizione in cui è stata trovata la corrispondenza,
- "length" del testo misurato in caratteri
- "matchDistance" o il numero di caratteri che differiscono tra la corrispondenza e l'entità "name".

Formato di definizione dell'entità personalizzato

Esistono tre approcci per fornire l'elenco di entità personalizzate alla competenza Ricerca entità personalizzata:

. File CSV (con codifica UTF-8)
. File JSON (con codifica UTF-8)
Inline all'interno della definizione della competenza

Se il file di definizione si trova in un oggetto . CSV o . File JSON, specificare il percorso completo nel parametro "entitiesDefinitionUri". Il file viene scaricato all'inizio di ogni esecuzione dell'indicizzatore. Deve rimanere accessibile fino all'arresto dell'indicizzatore.

Se si usa una definizione inline, specificarla nel parametro della competenza "inlineEntitiesDefinition".

Nota

Gli indicizzatori supportano modalità di analisi specializzate per i file JSON e CSV. Quando si usa la competenza di ricerca dell'entità personalizzata, mantenere "parsingMode" impostato su "default". La competenza prevede json e CSV in uno stato non analizzato.

Formato CSV

È possibile specificare la definizione delle entità personalizzate da cercare in un file con valori delimitati da virgole (CSV) specificando il percorso del file e impostandolo nel parametro della competenza "entitiesDefinitionUri". Il percorso deve trovarsi in una posizione https. Il file di definizione può avere dimensioni fino a 10 MB.

Il formato CSV è semplice. Ogni riga rappresenta un'entità univoca, come illustrato di seguito:

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

In questo caso, sono disponibili tre entità che possono essere restituite (Bill Gates, Satya Nadella, Microsoft). Gli alias seguono dopo l'entità principale. Una corrispondenza in un alias viene raggruppata nell'entità primaria. Ad esempio, se la stringa "William H. Gates" viene trovata in un documento, verrà restituita una corrispondenza per l'entità "Bill Gates".

Formato JSON

È possibile specificare anche la definizione delle entità personalizzate da cercare in un file JSON. Il formato JSON offre una maggiore flessibilità perché consente di definire regole di corrispondenza per periodo. Ad esempio, è possibile specificare la distanza corrispondente fuzzy (distanza Damerau-Levenshtein) per ogni termine o se la corrispondenza deve essere fatta distinzione tra maiuscole e minuscole o meno.

Analogamente ai file CSV, è necessario specificare il percorso del file JSON e impostarlo nel parametro di competenza "entitiesDefinitionUri". Il percorso deve trovarsi in una posizione https. Il file di definizione può avere dimensioni fino a 10 MB.

La definizione dell'elenco di entità personalizzata JSON più semplice può essere un elenco di entità da associare:

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

Le definizioni più complesse possono fornire un ID, una descrizione, un tipo, un sottotipo e alias definiti dall'utente. Se viene trovata una corrispondenza con un termine alias, verrà restituita anche l'entità:

[ 
    { 
        "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 }
        ]
    } 
]

Le tabelle seguenti descrivono i parametri di configurazione che è possibile impostare quando si definiscono entità personalizzate:

Nome del campo	Descrizione
`name`	Descrittore di entità di primo livello. Le corrispondenze nell'output della competenza verranno raggruppate in base a questo nome e dovrebbero rappresentare la forma "normalizzata" del testo trovato.
`description`	(Facoltativo) Questo campo può essere usato come pass-through per i metadati personalizzati relativi ai testi corrispondenti. Il valore di questo campo verrà visualizzato con ogni corrispondenza dell'entità nell'output della competenza.
`type`	(Facoltativo) Questo campo può essere usato come pass-through per i metadati personalizzati relativi ai testi corrispondenti. Il valore di questo campo verrà visualizzato con ogni corrispondenza dell'entità nell'output della competenza.
`subtype`	(Facoltativo) Questo campo può essere usato come pass-through per i metadati personalizzati relativi ai testi corrispondenti. Il valore di questo campo verrà visualizzato con ogni corrispondenza dell'entità nell'output della competenza.
`id`	(Facoltativo) Questo campo può essere usato come pass-through per i metadati personalizzati relativi ai testi corrispondenti. Il valore di questo campo verrà visualizzato con ogni corrispondenza dell'entità nell'output della competenza.
`caseSensitive`	(Facoltativo) Il valore predefinito è false. Valore booleano che indica se i confronti con il nome dell'entità devono essere sensibili alla combinazione di maiuscole e minuscole. Le corrispondenze senza distinzione tra maiuscole e minuscole di esempio di "Microsoft" potrebbero essere: microsoft, microSoft, MICROSOFT
`accentSensitive`	(Facoltativo) Il valore predefinito è false. Valore booleano che indica se le lettere accentate e non accentate, ad esempio 'é' e 'e' devono essere identiche.
`fuzzyEditDistance`	(Facoltativo) Il valore predefinito è 0. Valore massimo di 5. Indica il numero accettabile di caratteri divergenti che costituiscono comunque una corrispondenza con il nome dell'entità. Viene restituita la minima confusione possibile per ogni corrispondenza specificata. Ad esempio, se la distanza di modifica è impostata su 3, "Windows 10" corrisponderebbe comunque a "Windows", "Windows10" e "windows 7". Quando la distinzione tra maiuscole e minuscole è impostata su false, le differenze tra maiuscole e minuscole non vengono conteggiate per la tolleranza di fuzzità, ma in caso contrario.
`defaultCaseSensitive`	(Facoltativo) Modifica il valore di distinzione tra maiuscole e minuscole predefinito per questa entità. Può essere usato per modificare il valore predefinito di tutti gli alias senza distinzione tra maiuscole e minuscole.
`defaultAccentSensitive`	(Facoltativo) Modifica il valore di riservatezza principale predefinito per questa entità. Può essere usato per modificare il valore predefinito di tutti i valori accentati accentati degli alias.
`defaultFuzzyEditDistance`	(Facoltativo) Modifica il valore predefinito della distanza di modifica fuzzy per questa entità. Può essere usato per modificare il valore predefinito di tutti gli alias fuzzyEditDistance valori.
`aliases`	(Facoltativo) Matrice di oggetti complessi che possono essere usati per specificare ortografia o sinonimi alternativi per il nome dell'entità radice.

Proprietà degli alias	Descrizione
`text`	Ortografia alternativa o rappresentazione di un nome di entità di destinazione.
`caseSensitive`	(Facoltativo) Funge da parametro "caseSensitive" dell'entità radice precedente, ma si applica solo a questo alias.
`accentSensitive`	(Facoltativo) Agisce come il parametro "accentSensitive" dell'entità radice precedente, ma si applica solo a questo alias.
`fuzzyEditDistance`	(Facoltativo) Funge da parametro "fuzzyEditDistance" dell'entità radice precedente, ma si applica solo a questo alias.

Formato inline

In alcuni casi, può essere più pratico incorporare la definizione di entità personalizzata in modo che la relativa inline con la definizione della competenza. È possibile usare lo stesso formato JSON descritto in precedenza, ad eccezione del fatto che è incluso nella definizione della competenza. Solo le configurazioni con dimensioni inferiori a 10 KB (dimensioni serializzate) possono essere definite inline.

Definizione di competenza di esempio

Di seguito è illustrata una definizione di competenza di esempio che usa un formato inline:

  {
    "@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"
      }
    ]
  }

In alternativa, è possibile puntare a un file di definizione di entità esterne. Di seguito è illustrata una definizione di competenza di esempio che usa il entitiesDefinitionUri formato:

  {
    "@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"
      }
    ]
  }

Definizione di indice di esempio

Questa sezione fornisce una definizione di indice di esempio. Le "entità" e le "corrispondenze" sono matrici di tipi complessi. È possibile avere più entità per documento e più corrispondenze per ogni entità.

{
  "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,
        }
      ]
    }
  ]
}

Dati di input di esempio

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

Output di esempio

  { 
    "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 
                }
              ]
            }
          ] 
        } 
      } 
    ] 
  }

Avvisi

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

Questo avviso verrà generato se il numero di corrispondenze rilevate è maggiore del massimo consentito. Non verranno restituite altre corrispondenze duplicate. Se è necessaria una soglia superiore, è possibile inviare un ticket di supporto per assistenza per il singolo caso d'uso.

Condividi tramite