Verweisen auf Anmerkungen in einem Skillset der kognitiven SucheHow to reference annotations in a cognitive search skillset

In diesem Artikel erfahren Sie, wie Sie auf Anmerkungen in Skilldefinitionen verweisen und verschiedene Szenarien anhand von Beispielen veranschaulichen können.In this article, you learn how to reference annotations in skill definitions, using examples to illustrate various scenarios. Während der Inhalt eines Dokuments eine Reihe von Skills durchläuft, wird er mit Anmerkungen angereichert.As the content of a document flows through a set of skills, it gets enriched with annotations. Anmerkungen können als Eingaben für die nachfolgende Anreicherung verwendet oder einem Ausgabefeld in einem Index zugeordnet werden.Annotations can be used as inputs for further downstream enrichment, or mapped to an output field in an index.

Die Beispiele in diesem Artikel basieren auf dem content-Feld, das automatisch von Azure Blob-Indexern während der Dokumententschlüsselung generiert wird.Examples in this article are based on the content field generated automatically by Azure Blob indexers as part of the document cracking phase. Wenn Sie sich auf Dokumente aus einem Blobcontainer beziehen, verwenden Sie ein Format wie "/document/content", wobei das content-Feld Teil von document ist.When referring to documents from a Blob container, use a format such as "/document/content", where the content field is part of the document.

HintergrundkonzepteBackground concepts

Gehen Sie vor dem Überprüfen der Syntax nun noch einmal einige wichtige Konzepte durch, um die später in diesem Artikel vorgestellten Beispiele besser zu verstehen.Before reviewing the syntax, let's revisit a few important concepts to better understand the examples provided later in this article.

BegriffTerm BESCHREIBUNGDescription
Angereichertes DokumentEnriched Document Ein angereichertes Dokument ist eine interne Struktur, die von der Pipeline erstellt und verwendet wird, um alle Anmerkungen zu einem Dokument zu speichern.An enriched document is an internal structure created and used by the pipeline to hold all annotations related to a document. Stellen Sie sich ein angereichertes Dokument als einen Baum von Anmerkungen vor.Think of an enriched document as a tree of annotations. Im Allgemeinen wird eine Anmerkung, die aus einer vorherigen Anmerkung erstellt wurde, zu deren untergeordnetem Element.Generally, an annotation created from a previous annotation becomes its child.

Angereicherte Dokumente existieren nur für die Dauer der Skillsetausführung.Enriched documents only exist for the duration of skillset execution. Sobald der Inhalt dem Suchindex zugeordnet ist, wird das angereicherte Dokument nicht mehr benötigt.Once content is mapped to the search index, the enriched document is no longer needed. Obwohl Sie nicht direkt mit angereicherten Dokumenten interagieren, ist es nützlich, ein Gedankenmodell der Dokumente zu haben, wenn Sie ein Skillset erstellen.Although you don't interact with enriched documents directly, it's useful to have a mental model of the documents when creating a skillset.

AnreicherungskontextEnrichment Context Der Kontext, in dem die Anreicherung stattfindet, d.h. welches Element angereichert wird.The context in which the enrichment takes place, in terms of which element is enriched. Standardmäßig befindet sich der Anreicherungskontext auf der Ebene "/document", die auf einzelne Dokumente bezogen ist.By default, the enrichment context is at the "/document" level, scoped to individual documents. Wenn ein Skill ausgeführt wird, werden die Ergebnisse dieses Skills zu Eigenschaften des definierten Kontexts.When a skill runs, the outputs of that skill become properties of the defined context.

Beispiel 1: Einfacher AnmerkungsverweisExample 1: Simple annotation reference

Angenommen, Sie haben in Azure Blob Storage eine Vielzahl von Dateien, die Verweise auf die Namen von Personen enthalten, die Sie mithilfe der Entitätserkennung extrahieren möchten.In Azure Blob storage, suppose you have a variety of files containing references to people's names that you want to extract using entity recognition. In der folgenden Skilldefinition ist "/document/content" die Textdarstellung des gesamten Dokuments, und „people“ ist eine Extrahierung von vollständigen Namen für als Personen identifizierte Entitäten.In the skill definition below, "/document/content" is the textual representation of the entire document, and "people" is an extraction of full names for entities identified as persons.

Da der Standardkontext "/document" ist, kann auf die Liste der Personen nun als "/document/people" verwiesen werden.Because the default context is "/document", the list of people can now be referenced as "/document/people". In diesem speziellen Fall ist "/document/people" eine Anmerkung, die nun einem Feld in einem Index zugeordnet oder in einem anderen Skill im gleichen Skillset verwendet werden kann.In this specific case "/document/people" is an annotation, which could now be mapped to a field in an index, or used in another skill in the same skillset.

  {
    "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

Beispiel 2: Verweis auf ein Array innerhalb eines DokumentsExample 2: Reference an array within a document

Dieses Beispiel baut auf dem vorherigen auf und zeigt Ihnen, wie Sie einen Anreicherungsschritt mehrfach über dasselbe Dokument aufrufen können.This example builds on the previous one, showing you how to invoke an enrichment step multiple times over the same document. Angenommen, das vorherige Beispiel generiert ein Array von Zeichenfolgen mit zehn Personennamen aus einem einzigen Dokument.Assume the previous example generated an array of strings with 10 people names from a single document. Ein sinnvoller nächster Schritt könnte eine zweite Anreicherung sein, die den Nachnamen aus einem vollständigen Namen extrahiert.A reasonable next step might be a second enrichment that extracts the last name from a full name. Da es zehn Namen gibt, soll dieser Schritt in diesem Dokument zehnmal aufgerufen werden, d.h. einmal pro Person.Because there are 10 names, you want this step to be called 10 times in this document, once for each person.

Um die richtige Anzahl von Iterationen aufzurufen, setzen Sie den Kontext auf "/document/people/*", wobei das Sternchen ("*") für alle Knoten im angereicherten Dokument als untergeordnete Elemente von "/document/people" steht.To invoke the right number of iterations, set the context as "/document/people/*", where the asterisk ("*") represents all the nodes in the enriched document as descendants of "/document/people". Obwohl dieser Skill nur einmal im Skillsarray definiert ist, wird er für jedes Element innerhalb des Dokuments aufgerufen, bis alle Elemente bearbeitet sind.Although this skill is only defined once in the skills array, it is called for each member within the document until all members are processed.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

Wenn es sich bei Anmerkungen um Arrays oder Sammlungen von Zeichenfolgen handelt, empfiehlt es sich, für bestimmte Elemente statt auf das Array als Ganzes abzuzielen.When annotations are arrays or collections of strings, you might want to target specific members rather than the array as a whole. Der Code im obigen Beispiel generiert unter jedem Knoten, der durch den Kontext repräsentiert wird, eine Anmerkung namens "last".The above example generates an annotation called "last" under each node represented by the context. Wenn Sie auf diese Familie von Anmerkungen verweisen möchten, können Sie die Syntax "/document/people/*/last" verwenden.If you want to refer to this family of annotations, you could use the syntax "/document/people/*/last". Wenn Sie auf eine bestimmte Anmerkung verweisen möchten, können Sie einen expliziten Index verwenden: "/document/people/1/last", um auf den Nachnamen der ersten im Dokument identifizierten Person zu verweisen.If you want to refer to a particular annotation, you could use an explicit index: "/document/people/1/last" to reference the last name of the first person identified in the document. Beachten Sie, dass in dieser Syntax Arrays „0 indiziert“ sind.Notice that in this syntax arrays are "0 indexed".

Beispiel 3: Verweis auf Elemente innerhalb eines ArraysExample 3: Reference members within an array

Manchmal müssen Sie alle Anmerkungen eines bestimmten Typs gruppieren, um sie an einen bestimmten Skill zu übergeben.Sometimes you need to group all annotations of a particular type to pass them to a particular skill. Angenommen, es gibt einen hypothetischen benutzerdefinierten Skill, der den häufigsten Nachnamen aus allen in Beispiel 2 extrahierten Nachnamen identifiziert.Consider a hypothetical custom skill that identifies the most common last name from all the last names extracted in Example 2. Um dem benutzerdefinierten Skill nur die Nachnamen bereitzustellen, legen Sie den Kontext auf "/document" und die Eingabe auf "/document/people/*/lastname" fest.To provide just the last names to the custom skill, specify the context as "/document" and the input as "/document/people/*/lastname".

Beachten Sie, dass die Kardinalität von "/document/people/*/lastname" größer als die des Dokuments ist.Notice that the cardinality of "/document/people/*/lastname" is larger than that of document. Es kann zehn Nachnamenknoten geben, während es nur einen Dokumentknoten für dieses Dokument gibt.There may be 10 lastname nodes while there is only one document node for this document. In diesem Fall wird automatisch ein Array von "/document/people/*/lastname" erstellt, das alle Elemente des Dokuments enthält.In that case, the system will automatically create an array of "/document/people/*/lastname" containing all of the elements in the document.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

Weitere InformationenSee also