Compétence cognitive Recherche d’entité personnalisée

Article
03/25/2023

La compétence Recherche d’entité personnalisée est utilisée pour détecter ou reconnaître les entités que vous définissez. Lors de l’exécution de l’ensemble de compétences, la compétence recherche du texte dans une liste de mots et d’expressions personnalisée et définie par l’utilisateur. La compétence utilise cette liste pour étiqueter toutes les entités correspondantes trouvées dans les documents sources. La compétence prend également en charge un degré de correspondance approximative qui peut être appliqué pour rechercher des correspondances similaires mais non exactes.

Remarque

Cette compétence n’est pas liée à une API Azure AI Search. Toutefois, elle nécessite une clé de services Azure AI pour autoriser plus de 20 transactions. Cette compétence est mesurée par Azure AI Search.

@odata.type

Microsoft.Skills.Text.CustomEntityLookupSkill

Limites de données

La taille maximale prise en charge pour les enregistrements d'entrée est de 256 Mo. Si vous devez subdiviser vos données avant de les envoyer à la compétence de recherche d'entité personnalisée, utilisez la compétence Fractionnement de texte. Si vous utilisez une compétence de fractionnement de texte, définissez la longueur de la page sur 5 000 pour obtenir les meilleures performances.
La taille maximale de la définition d’entité personnalisée est de 10 Mo si elle est fournie en tant que fichier externe, par le biais du paramètre « entityDefinitionUri ».
Si les entités sont définies au format inline, à l’aide du paramètre inlineEntitiesDefinition, la taille maximale est de 10 ko.

Paramètres de la compétence

Les paramètres respectent la casse.

Nom du paramètre	Description
`entitiesDefinitionUri`	Chemin d’accès à un fichier JSON ou CSV externe contenant tout le texte cible à comparer. Cette définition d'entité est lue au début de l'exécution d'un indexeur ; les mises à jour de ce fichier à mi-parcours ne seront pas réalisées avant l'exécution suivante. Ce fichier doit être accessible via HTTPS. Reportez-vous à la section Format de définition d’entité personnalisée ci-dessous pour en savoir plus sur le schéma CSV ou JSON attendu.
`inlineEntitiesDefinition`	Définitions d'entités JSON au format inline. Ce paramètre remplace le paramètre entitiesDefinitionUri s'il est présent. Un maximum de 10 Ko de configuration peut être fourni au format inline. Reportez-vous à la section Définition d'entité personnalisée ci-dessous pour en savoir plus sur le schéma JSON attendu.
`defaultLanguageCode`	(Facultatif) Code langue du texte d'entrée utilisé pour « tokeniser » et délimiter le texte. Langues prises en charge : `da, de, en, es, fi, fr, it, pt`. La langue par défaut est l'anglais (`en`). Si vous passez un format `languagecode-countrycode`, seule la partie `languagecode` du format est utilisée.
`globalDefaultCaseSensitive`	(Facultatif) Valeur de la casse par défaut pour cette compétence. Si la valeur `defaultCaseSensitive` d’une entité n’est pas spécifiée, cette valeur devient la valeur `defaultCaseSensitive` de cette entité.
`globalDefaultAccentSensitive`	(Facultatif) Valeur de l’accent par défaut pour cette compétence. Si la valeur `defaultAccentSensitive` d’une entité n’est pas spécifiée, cette valeur devient la valeur `defaultAccentSensitive` de cette entité.
`globalDefaultFuzzyEditDistance`	(Facultatif) Valeur de la distance d’édition par défaut pour cette compétence. Si la valeur `defaultFuzzyEditDistance` d’une entité n’est pas spécifiée, cette valeur devient la valeur `defaultFuzzyEditDistance` de cette entité.

Entrées de la compétence

Nom de l'entrée	Description
`text`	Texte à analyser.
`languageCode`	facultatif. La valeur par défaut est `"en"`.

Sorties de la compétence

Nom de sortie Description

Nom de sortie	Description
`entities`	Tableau de types complexes contenant les champs suivants : `"name"` : L’entité de plus haut niveau ; elle représente la forme « normalisée ». `"id"` : identificateur unique de l’entité, tel que défini dans la « Définition d’entité personnalisée ». `"description"` : description de l'entité telle que définie par l'utilisateur dans le « Format de définition d'entité personnalisée ». `"type"` : type de l’entité tel que défini par l’utilisateur dans le « Format de définition d’entité personnalisée ». `"subtype"` : sous-type de l’entité, tel que défini par l’utilisateur dans le « Format de définition d’entité personnalisée ». `"matches"` : tableau de types complexes contenant : `"text"` du document source `"offset"` : emplacement où la correspondance a été trouvée dans le texte. `"length"` du texte mesuré en caractères `"matchDistance"` ou le nombre de caractères qui diffèrent entre la correspondance et l’entité `"name"`.

entities

Tableau de types complexes contenant les champs suivants :

"name" : L’entité de plus haut niveau ; elle représente la forme « normalisée ».
"id" : identificateur unique de l’entité, tel que défini dans la « Définition d’entité personnalisée ».
"description" : description de l'entité telle que définie par l'utilisateur dans le « Format de définition d'entité personnalisée ».
"type" : type de l’entité tel que défini par l’utilisateur dans le « Format de définition d’entité personnalisée ».
"subtype" : sous-type de l’entité, tel que défini par l’utilisateur dans le « Format de définition d’entité personnalisée ».
"matches" : tableau de types complexes contenant :
- "text" du document source
- "offset" : emplacement où la correspondance a été trouvée dans le texte.
- "length" du texte mesuré en caractères
- "matchDistance" ou le nombre de caractères qui diffèrent entre la correspondance et l’entité "name".

Format de définition d’entité personnalisée

Il existe trois approches pour fournir la liste des entités personnalisées à la compétence de recherche d’entités personnalisées :

Fichier .CSV (encodé en UTF-8)
Fichier .JSON (encodé en UTF-8)
Inline dans la définition de compétence

Si le fichier de définition se trouve dans un fichier .CSV ou .JSON, fournissez le chemin d’accès complet dans le paramètre « entitiesDefinitionUri ». Le fichier est téléchargé au début de chaque exécution de l’indexeur. Il doit rester accessible jusqu’à ce que l’indexeur s’arrête.

Si vous utilisez une définition inline, spécifiez-la sous le paramètre de compétence « inlineEntitiesDefinition ».

Remarque

Les indexeurs prennent en charge les modes d’analyse spécialisés pour les fichiers JSON et CSV. Lorsque vous utilisez la compétence de recherche d’entité personnalisée, laissez « parsingMode » sur « default ». La compétence attend les formats JSON et CSV dans un état non analysé.

Format CSV

Vous pouvez fournir la définition des entités personnalisées à rechercher dans un fichier CSV (Comma-Separated Value) en indiquant le chemin d’accès à celui-ci et en le définissant dans le paramètre de compétence « entitiesDefinitionUri ». Le chemin d'accès doit correspondre à un emplacement https. La taille du fichier de définition ne doit pas dépasser 10 Mo.

Le format CSV est simple. Chaque ligne représente une entité unique, comme illustré ci-dessous :

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

Dans ce cas, il y a trois entités qui peuvent être renvoyées (Bill Gates, Satya Nadella, Microsoft). Les alias suivent après l’entité principale. Une correspondance sur un alias est groupée sous l’entité primaire. Par exemple, si la chaîne « William H. Gates » est trouvée dans un document, une correspondance de l’entité « Bill Gates » sera renvoyée.

Format JSON

Vous pouvez également fournir la définition des entités personnalisées à rechercher dans un fichier JSON. Le format JSON vous offre un peu plus de flexibilité, car il vous permet de définir des règles de correspondance « par terme ». Par exemple, vous pouvez spécifier la distance de correspondance approximative (distance de Damerau-Levenshtein) pour chaque terme, ou indiquer si la correspondance doit respecter la casse ou non.

Comme avec les fichiers CSV, vous devez fournir le chemin d’accès au fichier JSON et le définir dans le paramètre de compétence « entitiesDefinitionUri ». Le chemin d'accès doit correspondre à un emplacement https. La taille du fichier de définition ne doit pas dépasser 10 Mo.

La définition de liste d'entités personnalisées JSON la plus élémentaire peut être une liste d'entités à comparer :

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

Des définitions plus complexes peuvent fournir un ID, une description, un type, un sous-type et des alias définis par l’utilisateur. Si une correspondance est trouvée avec un terme d'alias, l'entité est également renvoyée :

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

Les tableaux ci-dessous décrivent les paramètres de configuration que vous pouvez définir lors de la définition d’entités personnalisées :

Nom du champ	Description
`name`	descripteur d'entité de niveau supérieur. Dans la sortie de la compétence, les correspondances seront regroupées en fonction de ce nom. Il s'agit de la forme « normalisée » du texte trouvé.
`description`	(Facultatif) Ce champ peut être utilisé pour transmettre des métadonnées personnalisées au sujet du(des) texte(s) comparés. La valeur de ce champ apparaîtra avec chaque correspondance de son entité dans la sortie de la compétence.
`type`	(Facultatif) Ce champ peut être utilisé pour transmettre des métadonnées personnalisées au sujet du(des) texte(s) comparés. La valeur de ce champ apparaîtra avec chaque correspondance de son entité dans la sortie de la compétence.
`subtype`	(Facultatif) Ce champ peut être utilisé pour transmettre des métadonnées personnalisées au sujet du(des) texte(s) comparés. La valeur de ce champ apparaîtra avec chaque correspondance de son entité dans la sortie de la compétence.
`id`	(Facultatif) Ce champ peut être utilisé pour transmettre des métadonnées personnalisées au sujet du(des) texte(s) comparés. La valeur de ce champ apparaîtra avec chaque correspondance de son entité dans la sortie de la compétence.
`caseSensitive`	(Facultatif) La valeur par défaut est « False ». Valeur booléenne indiquant si les comparaisons avec le nom de l'entité doivent respecter la casse des caractères. Exemples de correspondances qui ne respectent pas la casse de « Microsoft » : microsoft, microSoft, MICROSOFT
`accentSensitive`	(Facultatif) La valeur par défaut est « False ». Valeur booléenne indiquant si les lettres accentuées et non accentuées comme « é » et « e » doivent être identiques.
`fuzzyEditDistance`	(Facultatif) La valeur par défaut est 0. La valeur maximale est 5. Indique le nombre acceptable de caractères divergents qui constitueraient encore une correspondance avec le nom de l'entité. La plus petite approximation possible d'une correspondance donnée est renvoyée. Par exemple, si la distance de modification est définie sur 3, « Windows 10 » correspondra encore à « Windows », « Windows10 » et « windows 7 ». Lorsque le respect de la casse est défini sur « False », les différences de casse ne comptent PAS dans le cadre de la tolérance aux approximations, mais sinon elles comptent.
`defaultCaseSensitive`	(Facultatif) Modifie la valeur de respect de la casse par défaut pour cette entité. Elle peut être utilisée pour modifier les valeurs caseSensitive par défaut de tous les alias.
`defaultAccentSensitive`	(Facultatif) Modifie la valeur de respect de l’accent par défaut pour cette entité. Elle peut être utilisée pour modifier les valeurs accentSensitive par défaut de tous les alias.
`defaultFuzzyEditDistance`	(Facultatif) Modifie la valeur par défaut de la distance de modification approximative pour cette entité. Elle peut être utilisée pour modifier les valeurs fuzzyEditDistance par défaut de tous les alias.
`aliases`	(Facultatif) Groupe d'objets complexes qui peut être utilisé pour spécifier d'autres orthographes ou des synonymes au nom de l'entité racine.

Propriétés des alias	Description
`text`	Autre orthographe ou représentation d'un nom d'entité cible.
`caseSensitive`	(Facultatif) Agit de la même manière que le paramètre « caseSensitive » de l'entité racine ci-dessus, mais ne s'applique qu'à cet alias.
`accentSensitive`	(Facultatif) Agit de la même manière que le paramètre « accentSensitive » de l’entité racine ci-dessus, mais ne s’applique qu’à cet alias.
`fuzzyEditDistance`	(Facultatif) Agit de la même manière que le paramètre « fuzzyEditDistance » de l'entité racine ci-dessus, mais ne s'applique qu'à cet alias.

Format inline

Dans certains cas, il peut être plus pratique d’incorporer la définition d’entité personnalisée afin qu’elle soit inline avec la définition de compétence. Vous pouvez utiliser le même format JSON que celui décrit ci-dessus, sauf qu’il est inclus dans la définition de la compétence. Seules les configurations dont la taille est inférieure à 10 Ko (taille sérialisée) peuvent être définies au format inline.

Exemple de définition de qualification

Voici un exemple de définition de compétence utilisant un format 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"
      }
    ]
  }

Vous pouvez également pointer vers un fichier de définition d’entités externe. Voici un exemple de définition de compétence utilisant le format entitiesDefinitionUri :

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

Définition de l’index d’exemples

Cette section fournit un exemple de définition d’index. Les « entités » et les « correspondances » sont des tableaux de types complexes. Vous pouvez avoir plusieurs entités par document et plusieurs correspondances pour chaque 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,
        }
      ]
    }
  ]
}

Exemples de données d’entrée

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

Exemple de sortie

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

Avertissements

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

Cet avertissement s’affiche si le nombre de correspondances détectées est supérieur au nombre maximal autorisé. Aucune autre correspondance en double ne sera retournée. Si vous avez besoin d’un seuil plus élevé, vous pouvez envoyer un ticket de support pour obtenir de l’aide sur votre cas d’usage individuel.