Erstellen eines Skillsets in einer AnreicherungspipelineHow to create a skillset in an enrichment pipeline

Die kognitive Suche extrahiert Daten und reichert diese an, um sie in Azure Search durchsuchbar zu machen.Cognitive search extracts and enriches data to make it searchable in Azure Search. Extrahierungs- und Anreicherungsschritte werden als kognitive Skills bezeichnet, die in einem Skillset kombiniert sind, auf das während der Indizierung verwiesen wird.We call extraction and enrichment steps cognitive skills, combined into a skillset referenced during indexing. Ein Skillset kann integrierte Qualifikationen oder benutzerdefinierte Qualifikationen verwenden. Weitere Informationen finden Sie unter Beispiel: Erstellen einer benutzerdefinierten Qualifikation mit der Bing-Entitätssuche-API.A skillset can use built-in skills or custom skills (see Example: Creating a custom skill for cognitive search for more information).

In diesem Artikel erfahren Sie, wie Sie eine Anreicherungspipeline für die Skills erstellen, die Sie verwenden möchten.In this article, you learn how to create an enrichment pipeline for the skills you want to use. Ein Skillset wird an einen Azure Search-Indexer angehängt.A skillset is attached to an Azure Search indexer. Ein Teil des Pipelineentwurfs, der in diesem Artikel behandelt wird, ist die Konstruktion des Skillsets selbst.One part of pipeline design, covered in this article, is constructing the skillset itself.

Hinweis

Ein weiterer Teil des Pipelineentwurfs ist die Festlegung eines Indexers im nächsten Schritt.Another part of pipeline design is specifying an indexer, covered in the next step. Eine Indexerdefinition enthält einen Verweis auf das Skillset sowie Feldzuordnungen, die für die Verbindung von Eingaben zu Ausgaben im Zielindex verwendet werden.An indexer definition includes a reference to the skillset, plus field mappings used for connecting inputs to outputs in the target index.

Wichtige Punkte, die Sie beachten sollten:Key points to remember:

  • Pro Indexer kann nur ein Skillset vorhanden sein.You can only have one skillset per indexer.
  • Ein Skillset muss mindestens einen Skill umfassen.A skillset must have at least one skill.
  • Sie können mehrere Qualifikationen des gleichen Typs erstellen (z. B. Varianten einer Bildanalysequalifikation).You can create multiple skills of the same type (for example, variants of an image analysis skill).

Denken Sie bereits zu Beginn an das EndeBegin with the end in mind

Ein empfohlener erster Schritt ist die Entscheidung, welche Daten Sie aus Ihren Rohdaten extrahieren und wie Sie diese Daten in einer Suchanwendung verwenden wollen.A recommended initial step is deciding which data to extract from your raw data and how you want to use that data in a search solution. Das Erstellen einer Abbildung der gesamten Anreicherungspipeline kann Ihnen helfen, die notwendigen Schritte zu identifizieren.Creating an illustration of the entire enrichment pipeline can help you identify the necessary steps.

Angenommen, Sie möchten eine Reihe von Kommentaren von Finanzexperten verarbeiten.Suppose you are interested in processing a set of financial analyst comments. Für jede Datei möchten Sie Firmennamen und die allgemeine Stimmung der Kommentare extrahieren.For each file, you want to extract company names and the general sentiment of the comments. Sie können auch eine benutzerdefinierte Anreicherungsfunktion schreiben, die den Bing-Entitätssuche-Dienst verwendet, um zusätzliche Informationen über das Unternehmen zu finden, z.B. welche Art von Geschäft das Unternehmen betreibt.You might also want to write a custom enricher that uses the Bing Entity Search service to find additional information about the company, such as what kind of business the company is engaged in. Im Wesentlichen möchten Sie Informationen wie die folgenden extrahieren, die für jedes Dokument indiziert sind:Essentially, you want to extract information like the following, indexed for each document:

Datensatztextrecord-text Unternehmencompanies Stimmungsentiment Unternehmensbeschreibungcompany descriptions
Beispiel-Datensatzsample-record [„Microsoft“, „LinkedIn“]["Microsoft", "LinkedIn"] 0,990.99 [„Microsoft Corporation ist ein amerikanisches multinationales Technologieunternehmen....“ „LinkedIn ist ein wirtschafts- und beschäftigungsorientiertes soziales Netzwerk....“]["Microsoft Corporation is an American multinational technology company ..." , "LinkedIn is a business- and employment-oriented social networking..."]

Das folgende Diagramm veranschaulicht eine hypothetische Anreicherungspipeline:The following diagram illustrates a hypothetical enrichment pipeline:

Eine hypothetische AnreicherungspipelineA hypothetical enrichment pipeline

Sobald Sie eine ungefähre Vorstellung davon haben, wie die Pipeline aussehen soll, können Sie das Skillset für die erforderlichen Schritte erstellen.Once you have fair idea of what you want in the pipeline, you can express the skillset that provides these steps. Funktionell wird das Skillset ausgedrückt, sobald Sie Ihre Indexerdefinition in Azure Search hochladen.Functionally, the skillset is expressed when you upload your indexer definition to Azure Search. Weitere Informationen darüber, wie Sie Ihren Indexer hochladen können, finden Sie in der Indexerdokumentation.To learn more about how to upload your indexer, see the indexer-documentation.

Im Diagramm erfolgt der Schritt zur Dokumententschlüsselung automatisch.In the diagram, the document cracking step happens automatically. Bekannte Dateien werden in Azure Search problemlos geöffnet, und es wird ein content-Feld erstellt, das den aus jedem Dokument extrahierten Text enthält.Essentially, Azure Search knows how to open well-known files and creates a content field containing the text extracted from each document. Die weißen Felder sind integrierte Anreicherungsfunktionen, und das gepunktete Feld „Bing Entity Search“ (Bing-Entitätssuche) stellt eine benutzerdefinierte Anreicherungsfunktion dar, die Sie erstellen.The white boxes are built-in enrichers, and the dotted "Bing Entity Search" box represents a custom enricher that you are creating. Wie dargestellt, enthält das Skillset drei Skills.As illustrated, the skillset contains three skills.

Skillsetdefinition in RESTSkillset definition in REST

Ein Skillset wird als ein Array von Skills definiert.A skillset is defined as an array of skills. Jeder Skill definiert die Quelle der Eingaben und den Namen der erzeugten Ausgaben.Each skill defines the source of its inputs and the name of the outputs produced. Mit der REST-API zum Erstellen von Skillsets können Sie einen Skillset definieren, der dem vorherigen Diagramm entspricht:Using the Create Skillset REST API, you can define a skillset that corresponds to the previous diagram:

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2019-05-06
api-key: [admin key]
Content-Type: application/json
{
  "description": 
  "Extract sentiment from financial records, extract company names, and then find additional information about each company mentioned.",
  "skills":
  [
    {
      "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
      "context": "/document",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "organizations"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.SentimentSkill",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "score",
          "targetName": "mySentiment"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
     "description": "Calls an Azure function, which in turn calls Bing Entity Search",
      "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeTextAnalyticsV3?code=foo",
      "httpHeaders": {
          "Ocp-Apim-Subscription-Key": "foobar"
      },
      "context": "/document/organizations/*",
      "inputs": [
        {
          "name": "query",
          "source": "/document/organizations/*"
        }
      ],
      "outputs": [
        {
          "name": "description",
          "targetName": "companyDescription"
        }
      ]
    }
  ]
}

Erstellen eines SkillsetsCreate a skillset

Beim Erstellen eines Skillsets können Sie eine Beschreibung angeben, um das Skillset selbstdokumentierend zu gestalten.While creating a skillset, you can provide a description to make the skillset self-documenting. Eine Beschreibung ist optional, aber zum Nachverfolgen der Wirkungsweise eines Skillsets durchaus nützlich.A description is optional, but useful for keeping track of what a skillset does. Da das Skillset ein JSON-Dokument ist, das keine Kommentare zulässt, müssen Sie dafür ein description-Element verwenden.Because skillset is a JSON document, which does not allow comments, you must use a description element for this.

{
  "description": 
  "This is our first skill set, it extracts sentiment from financial records, extract company names, and then finds additional information about each company mentioned.",
  ...
}

Das nächste Segment im Skillset ist ein Array von Skills.The next piece in the skillset is an array of skills. Man kann sich jeden Skill als einen Grundtyp für die Anreicherung vorstellen.You can think of each skill as a primitive of enrichment. In dieser Anreicherungspipeline führt jeder Skill eine kleine Aufgabe aus.Each skill performs a small task in this enrichment pipeline. Dies ist eine Eingabe (oder eine Reihe von Eingaben), durch die einige Ausgaben zurückgegeben werden.Each one takes an input (or a set of inputs), and returns some outputs. In den nächsten Abschnitten geht es darum, vordefinierte und integrierte Qualifikationen festzulegen und diese durch Eingabe- und Ausgabeverweise miteinander zu verketten.The next few sections focus on how to specify built-in and custom skills, chaining skills together through input and output references. Eingaben können aus Quelldaten oder aus einem anderen Skill stammen.Inputs can come from source data or from another skill. Ausgaben können einem Feld in einem Suchindex zugeordnet oder als Eingabe für einen nachfolgenden Skill verwendet werden.Outputs can be mapped to a field in a search index or used as an input to a downstream skill.

Hinzufügen integrierter QualifikationenAdd built-in skills

Betrachten Sie die erste Qualifikation, bei der es sich um die integrierte Qualifikation „Entitätserkennung“ handelt:Let's look at the first skill, which is the built-in entity recognition skill:

    {
      "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
      "context": "/document",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "organizations"
        }
      ]
    }
  • Jede integrierte Qualifikation verfügt über die Eigenschaften odata.type, input und output.Every built-in skill has odata.type, input, and output properties. Skillspezifische Eigenschaften bieten zusätzliche Informationen, die auf diesen Skill anwendbar sind.Skill-specific properties provide additional information applicable to that skill. Bei der Entitätserkennung ist categories eine Entität aus einem festen Satz von Entitätstypen, die das vortrainierte Modell erkennen kann.For entity recognition, categories is one entity among a fixed set of entity types that the pretrained model can recognize.

  • Jeder Skill muss über ein "context"-Element verfügen.Each skill should have a "context". Der Kontext stellt die Ebene dar, auf der Vorgänge ausgeführt werden.The context represents the level at which operations take place. In der oben gezeigten Qualifikation ist der Kontext das gesamte Dokument. Das bedeutet, dass die Qualifikation „Entitätserkennung“ einmal pro Dokument aufgerufen wird.In the skill above, the context is the whole document, meaning that the entity recognition skill is called once per document. Auf dieser Ebene werden auch Ausgaben erzeugt.Outputs are also produced at that level. Genauer gesagt werden "organizations" als Element von "/document" generiert.More specifically, "organizations" are generated as a member of "/document". In den nachfolgenden Skills wird auf diese neu erstellten Informationen mit "/document/organizations" verwiesen.In downstream skills, you can refer to this newly created information as "/document/organizations". Wenn das Feld "context" nicht explizit festgelegt ist, wird das Dokument als Standardkontext genommen.If the "context" field is not explicitly set, the default context is the document.

  • Der Skill hat eine Eingabe namens „text“, wobei die Eingabe der Quelle auf "/document/content" gesetzt ist.The skill has one input called "text", with a source input set to "/document/content". Die Qualifikation (Entitätserkennung) wird für das content-Feld jedes Dokuments ausgeführt. Hierbei handelt es sich um ein Standardfeld, das vom Azure Blob-Indexer erstellt wird.The skill (entity recognition) operates on the content field of each document, which is a standard field created by the Azure blob indexer.

  • Der Skill verfügt über eine Ausgabe mit der Bezeichnung "organizations".The skill has one output called "organizations". Ausgaben gibt es nur während der Verarbeitung.Outputs exist only during processing. Um diese Ausgabe mit der Eingabe eines nachfolgenden Skills zu verketten, verweisen Sie auf die Ausgabe mit "/document/organizations".To chain this output to a downstream skill's input, reference the output as "/document/organizations".

  • Für ein bestimmtes Dokument ist der Wert von "/document/organizations" ein Array von Organisationen, die aus dem Text extrahiert werden.For a particular document, the value of "/document/organizations" is an array of organizations extracted from the text. Beispiel:For example:

    ["Microsoft", "LinkedIn"]
    

In manchen Situationen ist es notwendig, auf jedes Element eines Arrays einzeln zu verweisen.Some situations call for referencing each element of an array separately. Angenommen, Sie möchten jedes Element von "/document/organizations" separat an einen anderen Skill übergeben (wie z.B. die benutzerdefinierte Anreicherungsfunktion der Bing-Entitätssuche).For example, suppose you want to pass each element of "/document/organizations" separately to another skill (such as the custom Bing entity search enricher). Sie können auf jedes Element des Arrays verweisen, indem Sie dem Pfad ein Sternchen hinzufügen: "/document/organizations/*"You can refer to each element of the array by adding an asterisk to the path: "/document/organizations/*"

Der zweite Skill zum Extrahieren von Stimmungen folgt dem gleichen Muster wie die erste Anreicherungsfunktion.The second skill for sentiment extraction follows the same pattern as the first enricher. Er verwendet "/document/content" als Eingabe und gibt einen Wert für die Stimmung für jede Inhaltsinstanz zurück.It takes "/document/content" as input, and returns a sentiment score for each content instance. Da Sie das Feld "context" nicht explizit festgelegt haben, ist die Ausgabe (mySentiment) nun ein untergeordnetes Element von "/document".Since you did not set the "context" field explicitly, the output (mySentiment) is now a child of "/document".

    {
      "@odata.type": "#Microsoft.Skills.Text.SentimentSkill",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "score",
          "targetName": "mySentiment"
        }
      ]
    },

Hinzufügen eines benutzerdefinierten SkillsAdd a custom skill

Erinnern Sie sich an die Struktur der benutzerdefinierten Anreicherungsfunktion für die Bing-Entitätssuche:Recall the structure of the custom Bing entity search enricher:

    {
      "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
     "description": "This skill calls an Azure function, which in turn calls Bing Entity Search",
      "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeTextAnalyticsV3?code=foo",
      "httpHeaders": {
          "Ocp-Apim-Subscription-Key": "foobar"
      },
      "context": "/document/organizations/*",
      "inputs": [
        {
          "name": "query",
          "source": "/document/organizations/*"
        }
      ],
      "outputs": [
        {
          "name": "description",
          "targetName": "companyDescription"
        }
      ]
    }

Diese Definition ist ein benutzerdefinierter Skill, der eine Web-API als Teil des Anreicherungsprozesses aufruft.This definition is a custom skill that calls a web API as part of the enrichment process. Für jede Organisation, die durch die Entitätserkennung identifiziert wird, ruft diese Qualifikation eine Web-API auf, um die Beschreibung dieser Organisation zu suchen.For each organization identified by entity recognition, this skill calls a web API to find the description of that organization. Eine interne Anreicherungs-Engine regelt die Orchestrierung, wann die Web-API aufgerufen werden soll und wie die empfangenen Informationen weitergeleitet werden sollen.The orchestration of when to call the web API and how to flow the information received is handled internally by the enrichment engine. Die für den Aufruf dieser benutzerdefinierten API erforderliche Initialisierung muss jedoch über das JSON-Dokument bereitgestellt werden (z.B. URI, HTTP-Header und die erwarteten Eingaben).However, the initialization necessary for calling this custom API must be provided in the JSON (such as uri, httpHeaders, and the inputs expected). Informationen zum Erstellen einer benutzerdefinierten Web-API für die Anreicherungspipeline finden Sie unter Definieren einer benutzerdefinierten Schnittstelle.For guidance in creating a custom web API for the enrichment pipeline, see How to define a custom interface.

Beachten Sie, dass das Feld „context“ mit einem Sternchen auf "/document/organizations/*" gesetzt ist, d.h. der Anreicherungsschritt wird für jede Organisation unter "/document/organizations" aufgerufen.Notice that the "context" field is set to "/document/organizations/*" with an asterisk, meaning the enrichment step is called for each organization under "/document/organizations".

Die Ausgabe, in diesem Fall eine Firmenbeschreibung, wird für jede identifizierte Organisation generiert.Output, in this case a company description, is generated for each organization identified. Bei Bezugnahme auf die Beschreibung in einem nachfolgenden Schritt (z.B. bei der Schlüsselbegriffserkennung) würden Sie dazu den Pfad "/document/organizations/*/description" verwenden.When referring to the description in a downstream step (for example, in key phrase extraction), you would use the path "/document/organizations/*/description" to do so.

Hinzufügen einer StrukturAdd structure

Das Skillset generiert strukturierte Informationen aus unstrukturierten Daten.The skillset generates structured information out of unstructured data. Betrachten Sie das folgende Beispiel:Consider the following example:

„In seinem vierten Quartal verzeichnete Microsoft 1,1 Milliarden Dollar Umsatz mit LinkedIn, dem im letzten Jahr erworbenen Unternehmen für soziale Netzwerke. Die Übernahme ermöglicht es Microsoft, LinkedIn-Funktionen mit seinen CRM- und Office-Funktionen zu kombinieren. Die Aktionäre sind von den bisherigen Fortschritten begeistert.“"In its fourth quarter, Microsoft logged $1.1 billion in revenue from LinkedIn, the social networking company it bought last year. The acquisition enables Microsoft to combine LinkedIn capabilities with its CRM and Office capabilities. Stockholders are excited with the progress so far."

Ein wahrscheinliches Ergebnis wäre eine generierte Struktur ähnlich der folgenden Abbildung:A likely outcome would be a generated structure similar to the following illustration:

Beispiel für AusgabestrukturSample output structure

Bis jetzt wurde diese Struktur nur intern, ausschließlich im Arbeitsspeicher und nur in Azure Search-Indizes verwendet.Until now, this structure has been internal-only, memory-only, and used only in Azure Search indexes. Das Hinzufügen eines Wissensspeichers bietet Ihnen eine Möglichkeit zum Speichern von Anreicherungen mit Formen zur Verwendung außerhalb der Suche.The addition of a knowledge store gives you a way to save shaped enrichments for use outside of search.

Hinzufügen von WissensspeichernAdd a knowledge store

Ein Wissensspeicher ist eine Previewfunktion in Azure Search zum Speichern Ihrer angereicherten Dokumente.Knowledge store is a preview feature in Azure Search for saving your enriched document. Wenn Sie einen Wissensspeicher erstellen, der durch ein Azure Storage-Konto unterstützt wird, fungiert er als Repository für Ihre angereicherten Daten.A knowledge store that you create, backed by an Azure storage account, is the repository where your enriched data lands.

Die Definition eines Wissensspeichers wird einer Qualifikationsgruppe hinzugefügt.A knowledge store definition is added to a skillset. Eine exemplarische Vorgehensweise des gesamten Prozesses finden Sie unter Erste Schritte mit Wissensspeichern.For a walkthrough of the entire process, see How to get started with knowledge store.

"knowledgeStore": {
  "storageConnectionString": "<an Azure storage connection string>",
  "projections" : [
    {
      "tables": [ ]
    },
    {
      "objects": [
        {
          "storageContainer": "containername",
          "source": "/document/EnrichedShape/",
          "key": "/document/Id"
        }
      ]
    }
  ]
}

Sie können angereicherte Dokumente auch als Tabellen mit hierarchischen Beziehungen oder als JSON-Dokumente in Blob Storage speichern.You can choose to save the enriched documents as tables with hierarchical relationships preserved or as JSON documents in blob storage. Die Ausgabe einer der Qualifikationen in der Qualifikationsgruppe kann als Eingabe für die Projektion verwendet werden.Output from any of the skills in the skillset can be sourced as the input for the projection. Wenn Sie die Daten in eine bestimmte Form projizieren möchten, kann die aktualisierte Qualifikation „Shaper“ nun auch komplexe Typen modellieren, die Sie dann verwenden können.If you are looking to project the data into a specific shape, the updated shaper skill can now model complex types for you to use.

Nächste SchritteNext steps

Nun, da Sie mit der Anreicherungspipeline und den Skillsets vertraut sind, können Sie mit den Artikeln Verweisen auf Anmerkungen in einem Skillset oder Zuordnen von Ausgaben zu Feldern in einem Index fortfahren.Now that you are familiar with the enrichment pipeline and skillsets, continue with How to reference annotations in a skillset or How to map outputs to fields in an index.