Der Skill „Shaper“Shaper cognitive skill

Die Qualifikation Shaper konsolidiert mehrere Eingaben in einem komplexen Typ, auf den später in der Anreicherungspipeline verwiesen werden kann.The Shaper skill consolidates several inputs into a complex type that can be referenced later in the enrichment pipeline. Im Wesentlichen ermöglicht es Ihnen der Skill Shaper, eine Struktur zu erstellen, den Namen der Elemente dieser Struktur zu definieren und jedem Element Werte zuzuweisen.The Shaper skill allows you to essentially create a structure, define the name of the members of that structure, and assign values to each member. Beispiele für konsolidierte Felder, die in Suchszenarien nützlich sind, sind die Kombination von Vor- und Nachnamen in einer einzigen Struktur, Stadt und Land in einer einzigen Struktur oder Name und Geburtsdatum in einer einzigen Struktur, um eine eindeutige Identität zu schaffen.Examples of consolidated fields useful in search scenarios include combining a first and last name into a single structure, city and state into a single structure, or name and birthdate into a single structure to establish unique identity.

Die API-Version bestimmt die mögliche Tiefe für die Strukturierung.The API version determines the depth of shaping you can achieve.

API-VersionAPI version Strukturieren von VerhaltensweisenShaping behaviors
Version 2019-05-06-Preview der REST-API (.NET SDK wird nicht unterstützt)2019-05-06-Preview version of the REST API (.NET SDK is not supported) Komplexe Objekte, mehrere Ebenen tief in einer Definition der Qualifikation Shaper.Complex objects, multiple levels deep, in one Shaper skill definition.
2019-05-06** (allgemein verfügbar), 2017-11-11-Preview2019-05-06** (generally available), 2017-11-11-Preview Komplexe Objekte, eine Ebene tief.Complex objects, one level deep. Eine Form mit mehreren Ebenen erfordert die Verkettung von mehreren Shaper-Schritten.A multi-level shape requires chaining several shaper steps together.

Wie von api-version=2019-05-06-Preview bereitgestellt, fügt die Qualifikation Shaper, die in Szenario 3 gezeigt wird, der Eingabe eine neue optionale sourceContext-Eigenschaft hinzu.As provided by api-version=2019-05-06-Preview, the Shaper skill illustrated in scenario 3 adds a new optional sourceContext property to the input. Die Eigenschaften source und sourceContext schließen sich gegenseitig aus.The source and sourceContext properties are mutually exclusive. Wenn die Eingabe im Kontext der Qualifikation liegt, verwenden Sie einfach source.If the input is at the context of the skill, simply use source. Wenn die Eingabe einen anderen Kontext als die Qualifikation aufweist, verwenden Sie sourceContext.If the input is at a different context than the skill context, use the sourceContext. Für sourceContext müssen Sie eine geschachtelte Eingabe mit dem Element definieren, das als Quelle verwendet werden soll.The sourceContext requires you to define a nested input with the specific element being addressed as the source.

In der Antwort lautet der Ausgabename bei allen API-Versionen immer „output“.In the response, for all API versions, the output name is always "output". Intern kann die Pipeline einen anderen Namen zuordnen (z. B. „analyzedText“ wie in den folgenden Beispielen), die Qualifikation Shaper selbst gibt in der Antwort jedoch „output“ zurück.Internally, the pipeline can map a different name, such as "analyzedText" as shown in the examples below, but the Shaper skill itself returns "output" in the response. Dies kann wichtig sein, wenn Sie angereicherte Dokumente debuggen und die Namensdiskrepanz bemerken, oder wenn Sie einen benutzerdefinierten Skill erstellen und die Antwort selbst strukturieren.This might be important if you are debugging enriched documents and notice the naming discrepancy, or if you build a custom skill and are structuring the response yourself.

Hinweis

Die Qualifikation Shaper ist nicht an eine Cognitive Services-API gebunden, und Ihnen entstehen für die Nutzung keine Kosten.The Shaper skill is not bound to a Cognitive Services API and you are not charged for using it. Es wird jedoch empfohlen, dennoch eine Cognitive Services-Ressource anzufügen, um die Ressourcenoption Free außer Kraft zu setzen, durch die Sie auf eine geringe Anzahl von Anreicherungen pro Tag beschränkt werden.You should still attach a Cognitive Services resource, however, to override the Free resource option that limits you to a small number of daily enrichments per day.

@odata.type

Microsoft.Skills.Util.ShaperSkillMicrosoft.Skills.Util.ShaperSkill

Szenario 1: komplexe TypenScenario 1: complex types

Stellen Sie sich ein Szenario vor, in dem Sie eine Struktur namens analyzedText erstellen möchten, die zwei Elemente hat: text und sentiment.Consider a scenario where you want to create a structure called analyzedText that has two members: text and sentiment, respectively. In einem Azure Search-Index wird ein mehrteiliges, durchsuchbares Feld als komplexer Typ bezeichnet und oft erstellt, wenn die Quelldaten über eine entsprechende komplexe Struktur verfügen, die dem Typ entspricht.In an Azure Search index, a multi-part searchable field is called a complex type and it's often created when source data has a corresponding complex structure that maps to it.

Einen anderen Ansatz für das Erstellen komplexer Typen stellt die Qualifikation Shaper dar.However, another approach for creating complex types is through the Shaper skill. Durch das Einschließen dieser Qualifikation in eine Qualifikationsgruppe können die speicherinternen Vorgänge während der Verarbeitung von Qualifikationsgruppen Datenformen mit geschachtelten Strukturen ausgeben, die dann einem komplexen Typ in Ihrem Index zugeordnet werden können.By including this skill in a skillset, the in-memory operations during skillset processing can output data shapes with nested structures, which can then be mapped to a complex type in your index.

Die folgende Beispieldefinition für eine Qualifikation stellt die Elementnamen als Eingabe bereit.The following example skill definition provides the member names as the input.

{
  "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
  "context": "/document/content/phrases/*",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content/phrases/*"
    },
    {
      "name": "sentiment",
      "source": "/document/content/phrases/*/sentiment"
    }
  ],
  "outputs": [
    {
      "name": "output",
      "targetName": "analyzedText"
    }
  ]
}

BeispielindexSample index

Eine Qualifikationsgruppe wird von einem Indexer aufgerufen, der wiederum einen Index erfordert.A skillset is invoked by an indexer, and an indexer requires an index. Die Darstellung eines komplexen Felds in Ihrem Index kann wie im folgenden Beispiel aussehen.A complex field representation in your index might look like the following example.


    "name": "my-index",
    "fields": [
        {   "name": "myId", "type": "Edm.String", "key": true, "filterable": true   },
        {   "name": "analyzedText", "type": "Edm.ComplexType",
            "fields": [{
                    "name": "text",
                    "type": "Edm.String",
                    "filterable": false,
                    "sortable": false,
                    "facetable": false,
                    "searchable": true  },
          {
                    "name": "sentiment",
                    "type": "Edm.Double",
                    "searchable": true,
                    "filterable": true,
                    "sortable": true,
                    "facetable": true
                },

QualifikationseingabenSkill input

So könnte ein eingehendes JSON-Dokument aussehen, das hilfreiche Eingabewerte für diese Qualifikation Shaper enthält:An incoming JSON document providing usable input for this Shaper skill could be:

{
    "values": [
        {
            "recordId": "1",
            "data": {
                "text": "this movie is awesome",
                "sentiment": 0.9
            }
        }
    ]
}

QualifikationsausgabenSkill output

Der Skill Shaper generiert ein neues Element namens analyzedText mit den kombinierten Elementen von text und sentiment.The Shaper skill generates a new element called analyzedText with the combined elements of text and sentiment. Diese Ausgabe entspricht dem Indexschema.This output conforms to the index schema. Sie wird importiert und in einem Azure Search-Index indiziert.It will be imported and indexed in an Azure Search index.

{
    "values": [
      {
        "recordId": "1",
        "data":
           {
            "analyzedText": 
              {
                "text": "this movie is awesome" ,
                "sentiment": 0.9
              }
           }
      }
    ]
}

Szenario 2: EingabekonsolidierungScenario 2: input consolidation

In einem anderen Beispiel stellen Sie sich vor, dass Sie in verschiedenen Phasen der Pipelineverarbeitung den Titel eines Buchs und die Kapitelüberschriften auf verschiedenen Seiten des Buchs extrahiert haben.In another example, imagine that at different stages of pipeline processing, you have extracted the title of a book, and chapter titles on different pages of the book. Sie können nun eine einzige Struktur aus diesen verschiedenen Eingaben erstellen.You could now create a single structure composed of these various inputs.

Die Definition der Qualifikation Shaper für dieses Szenario könnte wie im folgenden Beispiel aussehen:The Shaper skill definition for this scenario might look like the following example:

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "context": "/document",
    "inputs": [
        {
            "name": "title",
            "source": "/document/content/title"
        },
        {
            "name": "chapterTitles",
            "source": "/document/content/pages/*/chapterTitles/*/title"
        }
    ],
    "outputs": [
        {
            "name": "output",
            "targetName": "titlesAndChapters"
        }
    ]
}

QualifikationsausgabenSkill output

In diesem Fall vereinfacht Shaper alle Kapiteltitel, um ein einzelnes Array zu erstellen.In this case, the Shaper flattens all chapter titles to create a single array.

{
    "values": [
        {
            "recordId": "1",
            "data": {
                "titlesAndChapters": {
                    "title": "How to be happy",
                    "chapterTitles": [
                        "Start young",
                        "Laugh often",
                        "Eat, sleep and exercise"
                    ]
                }
            }
        }
    ]
}

Szenario 3: Eingabekonsolidierung aus geschachtelten KontextenScenario 3: input consolidation from nested contexts

Hinweis

Geschachtelte Strukturen, die in der REST-API-Version 2019-05-06-Preview unterstützt werden, können in einem Wissensspeicher oder einem Azure Search-Index verwendet werden.Nested structures supported in the REST API version 2019-05-06-Preview can be used in a knowledge store or in an Azure Search index.

Angenommen, Sie verfügen über Titel, Kapitel und Inhalt eines Buchs, haben die Erkennung von Entitäten und Schlüsselausdrücken für den Inhalt ausgeführt und möchten jetzt die Ergebnisse der einzelnen Qualifikationen in einer einzelnen Form mit den Kapitelnamen, Entitäten und Schlüsselbegriffen aggregieren.Imagine you have the title, chapters, and contents of a book and have run entity recognition and key phrases on the contents and now need to aggregate results from the different skills into a single shape with the chapter name, entities, and key phrases.

Die Definition der Qualifikation Shaper für dieses Szenario könnte wie im folgenden Beispiel aussehen:The Shaper skill definition for this scenario might look like the following example:

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "context": "/document",
    "inputs": [
        {
            "name": "title",
            "source": "/document/content/title"
        },
        {
            "name": "chapterTitles",
            "sourceContext": "/document/content/pages/*/chapterTitles/*",
            "inputs": [
              {
                  "name": "title",
                  "source": "/document/content/pages/*/chapterTitles/*/title"
              },
              {
                  "name": "number",
                  "source": "/document/content/pages/*/chapterTitles/*/number"
              }
            ]
        }

    ],
    "outputs": [
        {
            "name": "output",
            "targetName": "titlesAndChapters"
        }
    ]
}

QualifikationsausgabenSkill output

In diesem Fall erstellt Shaper einen komplexen Typ.In this case, the Shaper creates a complex type. Diese Struktur ist im Arbeitsspeicher enthalten.This structure exists in-memory. Wenn Sie sie in einem Wissensspeicher speichern möchten, sollten Sie eine Projektion in Ihrer Qualifikationsgruppe erstellen, die Speichereigenschaften definiert.If you want to save it to a knowledge store, you should create a projection in your skillset that defines storage characteristics.

{
    "values": [
        {
            "recordId": "1",
            "data": {
                "titlesAndChapters": {
                    "title": "How to be happy",
                    "chapterTitles": [
                      { "title": "Start young", "number": 1},
                      { "title": "Laugh often", "number": 2},
                      { "title": "Eat, sleep and exercise", "number: 3}
                    ]
                }
            }
        }
    ]
}

Weitere InformationenSee also