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

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.

@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.

Entrées de la compétence

Sorties de la compétence

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 ».

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 :

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.

Voir aussi

• Compétences prédéfinies
• Guide pratique pour définir un ensemble de compétences
• Compétence de reconnaissance d'entités (pour rechercher des entités bien connues)