Cognitive Search-Qualifikation „Benutzerdefinierte Entitätssuche“

Der Skill Benutzerdefinierte Entitätssuche wird verwendet, um von Ihnen definierte Entitäten zu erkennen oder zu bestimmen. Während der Ausführung des Skillsets sucht der Skill nach Text aus einer benutzerdefinierten Liste von Wörtern und Ausdrücken. Der Skill verwendet diese Liste, um alle übereinstimmenden Entitäten in Quelldokumenten zu kennzeichnen. Der Skill unterstützt auch einen gewissen Grad an Fuzzyübereinstimmung, der für die Suche nach ähnlichen, aber nicht genauen Übereinstimmungen verwendet werden kann.

Hinweis

Dieser Skill ist nicht an eine Azure AI Services API gebunden, sondern erfordert einen Azure AI Services Key, um mehr als 20 Transaktionen zu ermöglichen. Dieser Skill wird von Azure AI Search gemessen.

@odata.type

Microsoft.Skills.Text.CustomEntityLookupSkill

Datengrenzwerte

• Die maximal unterstützte Größe für den Eingabedatensatz beträgt 256 MB. Wenn Sie Ihre Daten teilen müssen, bevor Sie sie an die Qualifikation „Benutzerdefinierte Entitätssuche“ senden, denken Sie daran, die Qualifikation „Text teilen“ zu verwenden. Wenn Sie einen Text-Split-Skill verwenden, setzen Sie die Seitenlänge auf 5000, um die beste Leistung zu erzielen.
• Die maximale Größe der benutzerdefinierten Entitätsdefinition beträgt 10 MB, wenn sie als externe Datei bereitgestellt wird, die über den Parameter „entityDefinitionUri“ angegeben wird.
• Wenn die Entitäten inline mit dem Parameter „inlineEntitiesDefinition“ definiert werden, beträgt die maximal unterstützte Größe 10 KB.

Skillparameter

Bei den Parametern wird zwischen Groß- und Kleinschreibung unterschieden.

Parametername	Beschreibung
entitiesDefinitionUri	Pfad zu einer externen JSON- oder CSV-Datei, die den gesamten Zieltext enthält, mit dem verglichen werden soll. Diese Entitätsdefinition wird am Anfang der Ausführung eines Indexers gelesen. Alle Aktualisierungen an dieser Datei während der Ausführung werden erst in nachfolgenden Ausführungen berücksichtigt. Auf diese Datei muss über HTTPS zugegriffen werden können. Weitere Informationen zum erwarteten CSV- oder JSON-Schema finden Sie unter Cognitive Search-Qualifikation „Benutzerdefinierte Entitätssuche“ weiter unten.
inlineEntitiesDefinition	Inline-JSON-Entitätsdefinitionen. Dieser Parameter ersetzt den entitiesDefinitionUri-Parameter, falls vorhanden. Es können nicht mehr als 10 KB der Konfiguration inline bereitgestellt werden. Weitere Informationen zum erwarteten JSON-Schema finden Sie unter Benutzerdefinierte Entitätsdefinition weiter unten.
defaultLanguageCode	(Optional) Sprachcode des Eingabetexts, der verwendet wird, um den Eingabetext mit Token zu versehen und abzugrenzen. Die folgenden Sprachen werden unterstützt: da, de, en, es, fi, fr, it, pt. Die Standardsprache ist Englisch (en). Wenn Sie ein languagecode-countrycode-Format übergeben, wird nur der languagecode-Teil des Formats verwendet.
globalDefaultCaseSensitive	(Optional) Hierbei handelt es sich um einen Standardwert zur Beachtung der Groß-/Kleinschreibung für den Skill. Wenn der Wert defaultCaseSensitive einer Entität nicht angegeben ist, wird dieser Wert als defaultCaseSensitive-Wert für die Entität verwendet.
globalDefaultAccentSensitive	(Optional) Hierbei handelt es sich um einen Standardwert für die Beachtung von Diakritika für den Skill. Wenn der Wert defaultAccentSensitive einer Entität nicht angegeben ist, wird dieser Wert als defaultAccentSensitive-Wert für die Entität verwendet.
globalDefaultFuzzyEditDistance	(Optional) Hierbei handelt es sich um einen Standardwert zur Fuzzybearbeitungsdistanz für den Skill. Wenn der Wert defaultFuzzyEditDistance einer Entität nicht angegeben ist, wird dieser Wert als defaultFuzzyEditDistance-Wert für die Entität verwendet.

Skilleingaben

Eingabename	Beschreibung
text	Der zu analysierende Text
languageCode	Optional. Der Standardwert ist "en".

Skillausgaben

Ausgabename

Beschreibung

entities

Ein Array mit komplexen Typen und den folgenden Feldern: "name": Die übergeordnete Entität. Sie stellt die „normalisierte“ Form dar. "id": Ein eindeutiger Bezeichner für die Entität, wie vom Benutzer im „benutzerdefinierten Entitätsdefinitionsformat“ definiert. "description": Entitätsbeschreibung, wie vom Benutzer im "Custom Entity Definition Format" definiert. "type": Entitätstyp, wie vom Benutzer im „benutzerdefinierten Entitätsdefinitionsformat“ definiert. "subtype": Entitätsuntertyp, wie vom Benutzer im „benutzerdefinierten Entitätsdefinitionsformat“ definiert. "matches": Ein Array aus komplexen Typen, das Folgendes enthält: "text" aus dem Quelldokument "offset" Fundstelle der Übereinstimmung im Text "length" des in Zeichen gemessenen Textes "matchDistance" oder die Anzahl der Zeichen, die zwischen der Übereinstimmung und der Entität "name" unterschiedlich sind.

Benutzerdefiniertes Entitätsdefinitionsformat

Es gibt drei Ansätze, die Liste der benutzerdefinierten Entitäten für den Skill „Benutzerdefinierte Entitätssuche“ bereitzustellen.

• .CSV-Datei (UTF-8-codiert)
• .JSON-Datei (UTF-8-codiert)
• Inline innerhalb der Skilldefinition

Wenn die Definitionsdatei eine .CSV- oder .JSON-Datei ist, geben Sie den vollständigen Pfad im Parameter „entitiesDefinitionUri“ an. Die Datei wird zu Beginn eines jeden Indizierungslaufs heruntergeladen. Sie muss bis zum Anhalten des Indexers zugänglich bleiben.

Wenn Sie eine Inlinedefinition verwenden, geben Sie sie unter dem Parameter „inlineEntitiesDefinition“ an.

Hinweis

Indexer unterstützen spezielle Analysemodi für JSON- und CSV-Dateien. Wenn Sie den Skill „Benutzerdefinierte Entitätssuche“ verwenden, belassen Sie „parsingMode“ auf „standard“. Der Skill erwartet die JSON- und CSV-Dateien in einem nicht analysierten Zustand.

CSV-Format

Sie können die Definition der benutzerdefinierten Entitäten, nach denen gesucht werden soll, in einer CSV-Datei (Comma-Separated Value) bereitstellen, indem Sie den Pfad zur Datei angeben und ihn im Skillparameter „entitiesDefinitionUri“ festlegen. Der Pfad sollte sich an einem https-Speicherort befinden. Die Definitionsdatei kann bis zu 10 MB groß sein.

Das CSV-Format ist einfach. Jede Zeile stellt eine einzelne Einheit dar, wie unten dargestellt:

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

In diesem Fall gibt es drei Entitäten, die zurückgegeben werden können (Bill Gates, Satya Nadella, Microsoft). Aliase folgen nach der Hauptentität. Eine Übereinstimmung auf einem Alias wird unter der primären Entität gebündelt. Wird in einem Dokument beispielsweise die Zeichenfolge „William H. Gates“ gefunden, wird eine Übereinstimmung für die Entität „Bill Gates“ zurückgegeben.

JSON-Format

Sie können auch die Definition der benutzerdefinierten Entitäten angeben, nach denen in einer JSON-Datei gesucht werden soll. Das JSON-Format bietet Ihnen etwas mehr Flexibilität, da es Ihnen erlaubt, Übereinstimmungsregeln pro Begriff zu definieren. Sie können z. B. die Fuzzyübereinstimmungsdistanz (Damerau-Levenshtein-Distanz) für jeden Begriff festlegen oder angeben, ob bei der Übereinstimmung Groß-/Kleinschreibung beachtet werden soll oder nicht.

Genau wie bei CSV-Dateien müssen Sie den Pfad zur JSON-Datei angeben und ihn im Skillparameter „entitiesDefinitionUri“ festlegen. Der Pfad sollte sich an einem https-Speicherort befinden. Die Definitionsdatei kann bis zu 10 MB groß sein.

Die einfachste JSON-Definition einer benutzerdefinierten Entitätsliste kann eine Liste von Entitäten sein, die übereinstimmen müssen:

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

Komplexere Definitionen können Informationen wie benutzerdefinierte ID, Beschreibung, Typ, Untertyp und Aliase bereitstellen. Auch wenn ein Aliasbegriff übereinstimmt, wird die Entität zurückgegeben:

[ 
    { 
        "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 den folgenden Tabellen werden die Konfigurationsparameter beschrieben, die Sie bei der Definition benutzerdefinierter Entitäten festlegen können:

Feldname	Beschreibung
name	Entitätsdeskriptor der obersten Ebene. Übereinstimmungen in der Ausgabe der Qualifikation werden nach diesem Namen gruppiert; er sollte die „normalisierte“ Form des gefundenen Texts darstellen.
description	(Optional) Dieses Feld kann als Pass-Through-Feld für benutzerdefinierte Metadaten über die übereinstimmenden Texte verwendet werden. Der Wert dieses Felds wird mit jeder Übereinstimmung zur Entität in der Ausgabe der Qualifikation angezeigt.
type	(Optional) Dieses Feld kann als Pass-Through-Feld für benutzerdefinierte Metadaten über die übereinstimmenden Texte verwendet werden. Der Wert dieses Felds wird mit jeder Übereinstimmung zur Entität in der Ausgabe der Qualifikation angezeigt.
subtype	(Optional) Dieses Feld kann als Pass-Through-Feld für benutzerdefinierte Metadaten über die übereinstimmenden Texte verwendet werden. Der Wert dieses Felds wird mit jeder Übereinstimmung zur Entität in der Ausgabe der Qualifikation angezeigt.
id	(Optional) Dieses Feld kann als Pass-Through-Feld für benutzerdefinierte Metadaten über die übereinstimmenden Texte verwendet werden. Der Wert dieses Felds wird mit jeder Übereinstimmung zur Entität in der Ausgabe der Qualifikation angezeigt.
caseSensitive	(Optional) Der Standardwert ist „false“. Boolescher Wert, der angibt, ob bei Vergleichen mit dem Entitätsnamen die Groß-/Kleinschreibung beachtet werden soll. Beispiel für Übereinstimmungen mit „Microsoft“ ohne Berücksichtigung der Groß-/Kleinschreibung: microsoft, microSoft, MICROSOFT
accentSensitive	(Optional) Der Standardwert ist „false“. Hierbei handelt es sich um einen booleschen Wert, der angibt, ob zwischen Buchstaben mit oder ohne Diakritika (z. B. „é“ und „e“) unterschieden werden soll.
fuzzyEditDistance	(Optional) Der Standardwert ist „0“. Der Maximalwert ist „5“. Legt die zulässige Anzahl von abweichenden Zeichen fest, die noch als eine Übereinstimmung mit dem Entitätsnamen betrachtet werden. Die kleinste mögliche Fuzzyübereinstimmung für eine bestimmte Übereinstimmung wird zurückgegeben. Wenn die Bearbeitungsdistanz beispielsweise auf 3 festgelegt ist, stimmt „Windows 10“ noch überein mit „Windows“, „Windows 10“ und „Windows 7“. Ist die Groß-/Kleinschreibung auf „false“ festgelegt, werden Unterschiede in der Groß-/Kleinschreibung hinsichtlich der Fuzzyübereinstimmung nicht berücksichtigt; andernfalls schon.
defaultCaseSensitive	(Optional) Ändert den Standardwert für die Groß-/Kleinschreibung dieser Entität. Dieser Parameter kann dazu verwendet werden, den Standardwert für alle Aliase von caseSensitive-Werten zu ändern.
defaultAccentSensitive	(Optional) Dieser Parameter ändert den Standardwert für die Beachtung von Diakritika für diese Entität. Dieser Parameter kann dazu verwendet werden, den Standardwert für alle Aliase von accentSensitive-Werten zu ändern.
defaultFuzzyEditDistance	(Optional) Ändert den Standardwert für die Fuzzybearbeitungsdistanz dieser Entität. Es kann verwendet werden, um die Standardeinstellung für den fuzzyEditDistance-Wert aller Aliase zu ändern.
aliases	(Optional) Ein Array komplexer Objekte, die verwendet werden können, um alternative Schreibweisen oder Synonyme für den Stammnamen der Entität anzugeben.

Aliaseigenschaften	Beschreibung
text	Die alternative Schreibweise oder Darstellung eines bestimmten Zielentitätsnamens.
caseSensitive	(Optional) Funktioniert wie der oben beschriebene Parameter caseSensitive der Stammentität, gilt aber nur für diesen einen Alias.
accentSensitive	(Optional) Dieser Parameter weist dieselbe Funktion wie der oben genannte Stammentitätsparameter „accentSensitive“ auf, gilt jedoch nur für diesen einen Alias.
fuzzyEditDistance	(Optional) Funktioniert wie der oben beschriebene Parameter fuzzyEditDistance der Stammentität, gilt aber nur für diesen einen Alias.

Inlineformat

In einigen Fällen ist es möglicherweise einfacher, die benutzerdefinierte Entitätsdefinition einzubetten, damit diese mit der Skilldefinition inline ist. Sie können dasselbe JSON-Format wie das oben beschriebene verwenden, nur dass es in der Skilldefinition enthalten ist. Nur Konfigurationen mit einer Größe von weniger als 10 KB (serialisierte Größe) unterstützen Inlinedefinitionen.

Beispieldefinition einer Qualifikation

Eine Beispieldefinition einer Qualifikation mit einem Inlineformat wird unten gezeigt:

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

Alternativ können Sie auf eine Definitionsdatei für externe Entitäten verweisen. Eine Beispieldefinition eines Skills mit dem entitiesDefinitionUri-Format wird unten gezeigt:

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

Beispiel für Indexdefinition

Dieser Abschnitt enthält eine Beispielindexdefinition. Sowohl „entities“ als auch „matches“ sind Arrays komplexer Typen. Es kann mehrere Entitäten pro Dokument und mehrere Übereinstimmungen für jede Entität geben.

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

Beispieleingabedaten

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

Beispielausgabe

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

Warnungen

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

Diese Warnung wird ausgegeben, wenn die Anzahl der erkannten Übereinstimmungen größer als die maximal zulässige Anzahl ist. Es werden keine doppelten Übereinstimmungen zurückgegeben. Wenn Sie einen höheren Schwellenwert benötigen, können Sie ein Supportticket für Hilfe bei Ihrem individuellen Anwendungsfall einreichen.

Weitere Informationen

• Integrierte Qualifikationen
• Definieren eines Skillsets
• Qualifikation „Entitätserkennung“ (für die Suche nach bekannten Entitäten)