Cognitieve vaardigheid voor het opzoeken van aangepaste entiteiten

Artikel
10/20/2023

De vaardigheid Custom Entity Lookup wordt gebruikt om entiteiten te detecteren of te herkennen die u definieert. Tijdens het uitvoeren van vaardigheden zoekt de vaardigheid naar tekst uit een aangepaste, door de gebruiker gedefinieerde lijst met woorden en woordgroepen. De vaardigheid gebruikt deze lijst om overeenkomende entiteiten in brondocumenten te labelen. De vaardigheid ondersteunt ook het zoeken naar fuzzy overeenkomsten, waarmee overeenkomsten worden gevonden die vergelijkbaar zijn, maar niet exact.

Notitie

Deze vaardigheid is niet gebonden aan een API voor Azure AI-services, maar vereist een Azure AI-servicessleutel om meer dan 20 transacties toe te staan. Deze vaardigheid wordt gemeten door Azure AI Search.

@odata.type

Microsoft.Skills.Text.CustomEntityLookupSkill

Gegevenslimieten

De maximale ondersteunde invoerrecordgrootte is 256 MB. Als u uw gegevens wilt opsplitsen voordat u deze naar de opzoekvaardigheid voor aangepaste entiteiten verzendt, kunt u overwegen de vaardigheid Tekst splitsen te gebruiken. Als u een vaardigheid voor tekstsplitsing gebruikt, stelt u de paginalengte in op 5000 voor de beste prestaties.
De maximale grootte van de definitie van de aangepaste entiteit is 10 MB als deze is opgegeven als een extern bestand, opgegeven via de parameter entitiesDefinitionUri.
Als de entiteiten inline zijn gedefinieerd met behulp van de parameter inlineEntitiesDefinition, is de maximale grootte 10 kB.

Vaardigheidsparameters

Parameters zijn hoofdlettergevoelig.

Parameternaam	Beschrijving
`entitiesDefinitionUri`	Pad naar een extern JSON- of CSV-bestand met alle doeltekst die moet worden vergeleken. Deze entiteitsdefinitie wordt gelezen aan het begin van een indexeerfunctieuitvoering; eventuele updates voor dit bestand worden halverwege de uitvoering niet gerealiseerd totdat de volgende uitvoeringen worden uitgevoerd. Dit bestand moet toegankelijk zijn via HTTPS. Zie de indeling voor aangepaste entiteitsdefinitie hieronder voor het verwachte CSV- of JSON-schema.
`inlineEntitiesDefinition`	Inline JSON-entiteitsdefinities. Deze parameter vervangt de parameter entitiesDefinitionUri indien aanwezig. Er kan niet meer dan 10 kB aan configuratie inline worden opgegeven. Zie de definitie van de aangepaste entiteit hieronder voor het verwachte JSON-schema.
`defaultLanguageCode`	(Optioneel) Taalcode van de invoertekst die wordt gebruikt om invoertekst te tokeniseren en af te bakenen. De volgende talen worden ondersteund: `da, de, en, es, fi, fr, it, pt`. De standaardwaarde is Engels (`en`). Als u een `languagecode-countrycode` indeling doorgeeft, wordt alleen het `languagecode` deel van de indeling gebruikt.
`globalDefaultCaseSensitive`	(Optioneel) Standaard hoofdlettergevoelige waarde voor de vaardigheid. Als `defaultCaseSensitive` de waarde van een entiteit niet is opgegeven, wordt deze waarde de `defaultCaseSensitive` waarde voor die entiteit.
`globalDefaultAccentSensitive`	(Optioneel) Standaard accentgevoelige waarde voor de vaardigheid. Als `defaultAccentSensitive` de waarde van een entiteit niet is opgegeven, wordt deze waarde de `defaultAccentSensitive` waarde voor die entiteit.
`globalDefaultFuzzyEditDistance`	(Optioneel) Standaard fuzzy bewerking afstandswaarde voor de vaardigheid. Als `defaultFuzzyEditDistance` de waarde van een entiteit niet is opgegeven, wordt deze waarde de `defaultFuzzyEditDistance` waarde voor die entiteit.

Invoer van vaardigheden

Invoernaam	Beschrijving
`text`	De te analyseren tekst.
`languageCode`	Optioneel. Standaard is `"en"`.

Uitvoer van vaardigheden

Uitvoernaam Beschrijving

Uitvoernaam	Beschrijving
`entities`	Een matrix met complexe typen die de volgende velden bevatten: `"name"`: De entiteit op het hoogste niveau; het vertegenwoordigt het 'genormaliseerde' formulier. `"id"`: Een unieke id voor de entiteit zoals gedefinieerd in de definitie van de aangepaste entiteit. `"description"`: Entiteitsbeschrijving zoals gedefinieerd door de gebruiker in de 'Aangepaste entiteitsdefinitie-indeling'. `"type"`: Entiteitstype zoals gedefinieerd door de gebruiker in de "Custom Entity Definition Format". `"subtype"`: Entiteitssubtype zoals gedefinieerd door de gebruiker in de "Custom Entity Definition Format". `"matches"`: Een matrix van complexe typen die het volgende bevatten: `"text"` uit het brondocument `"offset"` locatie waar de overeenkomst is gevonden, `"length"` van de tekst gemeten in tekens `"matchDistance"` of het aantal tekens dat verschilt tussen de overeenkomst en de entiteit `"name"`.

entities

Een matrix met complexe typen die de volgende velden bevatten:

"name": De entiteit op het hoogste niveau; het vertegenwoordigt het 'genormaliseerde' formulier.
"id": Een unieke id voor de entiteit zoals gedefinieerd in de definitie van de aangepaste entiteit.
"description": Entiteitsbeschrijving zoals gedefinieerd door de gebruiker in de 'Aangepaste entiteitsdefinitie-indeling'.
"type": Entiteitstype zoals gedefinieerd door de gebruiker in de "Custom Entity Definition Format".
"subtype": Entiteitssubtype zoals gedefinieerd door de gebruiker in de "Custom Entity Definition Format".
"matches": Een matrix van complexe typen die het volgende bevatten:
- "text" uit het brondocument
- "offset" locatie waar de overeenkomst is gevonden,
- "length" van de tekst gemeten in tekens
- "matchDistance" of het aantal tekens dat verschilt tussen de overeenkomst en de entiteit "name".

Aangepaste indeling voor entiteitsdefinities

Er zijn drie benaderingen voor het verstrekken van de lijst met aangepaste entiteiten aan de vaardigheid Custom Entity Lookup:

. CSV-bestand (UTF-8 gecodeerd)
. JSON-bestand (UTF-8 gecodeerd)
Inline binnen de vaardigheidsdefinitie

Als het definitiebestand zich in een . CSV of . Geef het volledige pad op in de parameter entitiesDefinitionUri. Het bestand wordt gedownload aan het begin van elke indexeerfunctieuitvoering. Deze moet toegankelijk blijven totdat de indexeerfunctie stopt.

Als u een inlinedefinitie gebruikt, geeft u deze op onder de vaardigheidsparameter 'inlineEntitiesDefinition'.

Notitie

Indexeerfuncties ondersteunen gespecialiseerde parseringsmodi voor JSON- en CSV-bestanden. Wanneer u de opzoekvaardigheid voor aangepaste entiteiten gebruikt, houdt u 'parsingMode' ingesteld op 'standaard'. De vaardigheid verwacht JSON en CSV in een niet-geparseerde status.

CSV-indeling

U kunt de definitie van de aangepaste entiteiten opgeven waarnaar moet worden gezocht in een CSV-bestand (door komma's gescheiden waarden) door het pad naar het bestand op te geven en dit in te stellen in de vaardigheidsparameter entitiesDefinitionUri. Het pad moet zich op een https-locatie bevinden. Het definitiebestand kan maximaal 10 MB groot zijn.

De CSV-indeling is eenvoudig. Elke regel vertegenwoordigt een unieke entiteit, zoals hieronder wordt weergegeven:

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

In dit geval zijn er drie entiteiten die kunnen worden geretourneerd (Bill Gates, Satya Nadella, Microsoft). Aliassen volgen na de hoofdentiteit. Een overeenkomst op een alias wordt gebundeld onder de primaire entiteit. Als de tekenreeks William H. Gates bijvoorbeeld wordt gevonden in een document, wordt een overeenkomst voor de entiteit Bill Gates geretourneerd.

JSON-indeling

U kunt ook de definitie opgeven van de aangepaste entiteiten die u in een JSON-bestand wilt zoeken. De JSON-indeling biedt u wat meer flexibiliteit, omdat u hiermee overeenkomende regels per term kunt definiëren. U kunt bijvoorbeeld de fuzzy overeenkomende afstand (Damerau-Levenshtein-afstand) voor elke term opgeven of de overeenkomst hoofdlettergevoelig moet zijn of niet.

Net als bij CSV-bestanden moet u het pad naar het JSON-bestand opgeven en instellen in de vaardigheidsparameter 'entitiesDefinitionUri'. Het pad moet zich op een https-locatie bevinden. Het definitiebestand kan maximaal 10 MB groot zijn.

De meest eenvoudige definitie van een aangepaste JSON-entiteitslijst kan een lijst met entiteiten zijn die overeenkomen met:

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

Complexere definities kunnen een door de gebruiker gedefinieerde id, beschrijving, type, subtype en aliassen bieden. Als een aliasterm overeenkomt, wordt de entiteit ook geretourneerd:

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

In de onderstaande tabellen worden de configuratieparameters beschreven die u kunt instellen bij het definiëren van aangepaste entiteiten:

Veldnaam	Beschrijving
`name`	De entiteitsdescriptor op het hoogste niveau. Overeenkomsten in de uitvoer van de vaardigheid worden gegroepeerd op deze naam en moeten de 'genormaliseerde' vorm van de gevonden tekst vertegenwoordigen.
`description`	(Optioneel) Dit veld kan worden gebruikt als een passthrough voor aangepaste metagegevens over de overeenkomende tekst(en). De waarde van dit veld wordt weergegeven met elke overeenkomst van de entiteit in de uitvoer van de vaardigheid.
`type`	(Optioneel) Dit veld kan worden gebruikt als een passthrough voor aangepaste metagegevens over de overeenkomende tekst(en). De waarde van dit veld wordt weergegeven met elke overeenkomst van de entiteit in de uitvoer van de vaardigheid.
`subtype`	(Optioneel) Dit veld kan worden gebruikt als een passthrough voor aangepaste metagegevens over de overeenkomende tekst(en). De waarde van dit veld wordt weergegeven met elke overeenkomst van de entiteit in de uitvoer van de vaardigheid.
`id`	(Optioneel) Dit veld kan worden gebruikt als een passthrough voor aangepaste metagegevens over de overeenkomende tekst(en). De waarde van dit veld wordt weergegeven met elke overeenkomst van de entiteit in de uitvoer van de vaardigheid.
`caseSensitive`	(Optioneel) De standaardwaarde is onwaar. Booleaanse waarde die aangeeft of vergelijkingen met de entiteitsnaam gevoelig moeten zijn voor hoofdletters. Voorbeeld van niet-hoofdlettergevoelige overeenkomsten van 'Microsoft' kan zijn: microsoft, microSoft, MICROSOFT
`accentSensitive`	(Optioneel) De standaardwaarde is onwaar. Booleaanse waarde die aangeeft of accenten en niet-begeleide letters, zoals 'é' en 'e', identiek moeten zijn.
`fuzzyEditDistance`	(Optioneel) De standaardwaarde is 0. Maximumwaarde van 5. Geeft het acceptabele aantal afwijkende tekens aan dat nog steeds overeenkomt met de entiteitsnaam. De kleinste mogelijke fzzerigheid voor een bepaalde overeenkomst wordt geretourneerd. Als de bewerkingsafstand bijvoorbeeld is ingesteld op 3, komt 'Windows 10' nog steeds overeen met 'Windows', 'Windows10' en 'windows 7'. Wanneer de gevoeligheid van hoofdletters is ingesteld op onwaar, worden verschillen in hoofdletters en kleine letters niet meegeteld bij de tolerantie, maar anders wel.
`defaultCaseSensitive`	(Optioneel) Hiermee wijzigt u de standaardwaarde voor hoofdlettergevoeligheid voor deze entiteit. Deze kan worden gebruikt om de standaardwaarde van alle aliassen hoofdlettergevoelige waarden te wijzigen.
`defaultAccentSensitive`	(Optioneel) Hiermee wijzigt u de standaardwaarde voor accentgevoeligheid voor deze entiteit. Deze kan worden gebruikt om de standaardwaarde van alle aliassen accentSensitive waarden te wijzigen.
`defaultFuzzyEditDistance`	(Optioneel) Hiermee wijzigt u de standaardwaarde voor fuzzy bewerkingsafstand voor deze entiteit. Het kan worden gebruikt om de standaardwaarde van alle aliassen fuzzyEditDistance-waarden te wijzigen.
`aliases`	(Optioneel) Een matrix met complexe objecten die kunnen worden gebruikt om alternatieve spelling of synoniemen op te geven voor de naam van de hoofdentiteit.

Aliaseigenschappen	Beschrijving
`text`	De alternatieve spelling of weergave van een naam van een doelentiteit.
`caseSensitive`	(Optioneel) Fungeert hetzelfde als de bovenstaande hoofdentiteit 'caseSensitive', maar is alleen van toepassing op deze ene alias.
`accentSensitive`	(Optioneel) Fungeert hetzelfde als de bovenstaande hoofdentiteit accentSensitive, maar is alleen van toepassing op deze ene alias.
`fuzzyEditDistance`	(Optioneel) Fungeert hetzelfde als de bovenstaande hoofdentiteit 'fuzzyEditDistance', maar is alleen van toepassing op deze ene alias.

Inline-indeling

In sommige gevallen kan het handiger zijn om de definitie van de aangepaste entiteit in te sluiten, zodat deze inline is met de vaardigheidsdefinitie. U kunt dezelfde JSON-indeling gebruiken als de indeling die hierboven wordt beschreven, behalve dat deze is opgenomen in de definitie van de vaardigheid. Alleen configuraties met een grootte van minder dan 10 kB (geserialiseerde grootte) kunnen inline worden gedefinieerd.

Voorbeelddefinitie van vaardigheid

Hieronder ziet u een voorbeeld van een vaardigheidsdefinitie met behulp van een inline-indeling:

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

U kunt ook verwijzen naar een definitiebestand voor externe entiteiten. Hieronder ziet u een voorbeeld van een vaardigheidsdefinitie met behulp van de entitiesDefinitionUri indeling:

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

Voorbeeldindexdefinitie

Deze sectie bevat een voorbeeld van een indexdefinitie. Zowel 'entiteiten' als 'overeenkomsten' zijn matrices van complexe typen. U kunt meerdere entiteiten per document en meerdere overeenkomsten voor elke entiteit hebben.

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

Voorbeeldinvoergegevens

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

Voorbeelduitvoer

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

Waarschuwingen

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

Deze waarschuwing wordt verzonden als het aantal gedetecteerde overeenkomsten groter is dan het toegestane maximum. Er worden geen dubbele overeenkomsten meer geretourneerd. Als u een hogere drempelwaarde nodig hebt, kunt u een ondersteuningsticket indienen voor hulp bij uw individuele use case.

Delen via