Hinzufügen eines benutzerdefinierten Skills zu einer Pipeline der kognitiven SucheHow to add a custom skill to a cognitive search pipeline

Eine Pipeline für die Indizierung der kognitive Suche in Azure Search kann aus vordefinierten Skills und benutzerdefinierten Skills zusammengestellt werden, die Sie persönlich erstellen und der Pipeline hinzufügen.A cognitive search indexing pipeline in Azure Search can be assembled from predefined skills as well as custom skills that you personally create and add to the pipeline. In diesem Artikel erfahren Sie, wie Sie einen benutzerdefinierten Skill erstellen, der eine Schnittstelle verfügbar macht, sodass er in eine Pipeline für die kognitive Suche eingefügt werden kann.In this article, learn how to create a custom skill that exposes an interface allowing it to be included in a cognitive search pipeline.

Das Erstellen eines benutzerdefinierten Skills gibt Ihnen die Möglichkeit, Transformationen einzufügen, die für Ihren Inhalt eindeutig sind.Building a custom skill gives you a way to insert transformations unique to your content. Ein benutzerdefinierter Skill wird unabhängig ausgeführt, wobei jeder gewünschte Anreicherungsschritt angewendet wird.A custom skill executes independently, applying whatever enrichment step you require. Sie können beispielsweise feldspezifische benutzerdefinierte Entitäten definieren, benutzerdefinierte Klassifizierungsmodelle erstellen, um Geschäfts- und Finanzverträge und -dokumente zu unterscheiden, oder einen Spracherkennungsskill hinzufügen, um selbst in Audiodateien relevante Inhalte zu erreichen.For example, you could define field-specific custom entities, build custom classification models to differentiate business and financial contracts and documents, or add a speech recognition skill to reach deeper into audio files for relevant content. Ein Beispiel mit einer schrittweisen Anleitung finden Sie unter Beispiel: Erstellen eines benutzerdefinierten Skills für die kognitive Suche.For a step-by-step example, see Example: Creating a custom skill for cognitive search.

Welchen benutzerdefinierten Skill Sie auch benötigen, es gibt eine einfache und klare Schnittstelle, um einen benutzerdefinierten Skill mit dem Rest der Anreicherungspipeline zu verbinden.Whatever custom capability you require, there is a simple and clear interface for connecting a custom skill to the rest of the enrichment pipeline. Damit die Aufnahme in ein Skillset möglich ist, müssen Eingaben akzeptiert und Ausgaben emittiert werden können, sodass diese innerhalb des Skillsets umfassend verwendet werden können.The only requirement for inclusion in a skillset is the ability to accept inputs and emit outputs in ways that are consumable within the skillset as a whole. Der Fokus dieses Artikels liegt auf den Ein- und Ausgabeformaten, die die Anreicherungspipeline benötigt.The focus of this article is on the input and output formats that the enrichment pipeline requires.

Web-API-Schnittstelle für benutzerdefinierte SkillsWeb API custom skill interface

Benutzerdefinierte WebAPI-Skill-Endpunkte nach Standardtimeout, wenn sie innerhalb eines 30-Sekunden-Fensters keine Antwort zurückgeben.Custom WebAPI skill endpoints by default timeout if they don't return a response within a 30 second window. Die Indizierungspipeline ist synchron, und die Indizierung erzeugt ein Timeoutfehler, wenn in diesem Zeitraum keine Antwort empfangen wird.The indexing pipeline is synchronous and indexing will produce a timeout error if a response is not received in that window. Durch Festlegen des Timeoutparameters ist es möglich, den Timeout auf bis zu 230 Sekunden zu konfigurieren:It is possible to configure the timeout to be up to 230 seconds, by setting the timeout parameter:

        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "description": "This skill has a 230 second timeout",
        "uri": "https://[your custom skill uri goes here]",
        "timeout": "PT230S",

Derzeit ist die einzige Methode für die Interaktion mit einem benutzerdefinierten Skill über eine Web-API-Schnittstelle.Currently, the only mechanism for interacting with a custom skill is through a Web API interface. Die Web-API-Anforderungen müssen die in diesem Abschnitt beschriebenen Voraussetzungen erfüllen.The Web API needs must meet the requirements described in this section.

1. Web-API-Eingabeformat1. Web API Input Format

Die Web-API muss ein Array von zu verarbeitenden Datensätzen akzeptieren.The Web API must accept an array of records to be processed. Jeder Datensatz muss einen „Eigenschaftenbehälter“, d.h. die Eingabewerte für Ihre Web-API, umfassen.Each record must contain a "property bag" that is the input provided to your Web API.

Angenommen, Sie möchten eine einfache Anreicherungsfunktion erstellen, die das erste im Vertragstext genannte Datum identifiziert.Suppose you want to create a simple enricher that identifies the first date mentioned in the text of a contract. In diesem Beispiel akzeptiert der Skill eine einzige Eingabe contractText als Vertragstext.In this example, the skill accepts a single input contractText as the contract text. Der Skill hat auch eine einzige Ausgabe: das Datum des Vertrags.The skill also has a single output, which is the date of the contract. Um die Anreicherungsfunktion interessanter zu machen, geben Sie contractDate in Form eines mehrteiligen komplexen Typs zurück.To make the enricher more interesting, return this contractDate in the shape of a multi-part complex type.

Ihre Web-API muss bereit sein, um einen Stapel von Eingabedatensätzen zu empfangen.Your Web API should be ready to receive a batch of input records. Jedes Element des Arrays values stellt die Eingabe für einen bestimmten Datensatz dar.Each member of the values array represents the input for a particular record. Jeder Datensatz muss die folgenden Elemente enthalten:Each record is required to have the following elements:

  • Ein recordId-Element, das der eindeutige Bezeichner für einen bestimmten Datensatz ist.A recordId member that is the unique identifier for a particular record. Wenn Ihre Anreicherungsfunktion die Ergebnisse zurückgibt, muss diese recordId-Element zur Verfügung gestellt werden, damit der Aufrufer die Datensätze mit den Eingaben abgleichen kann.When your enricher returns the results, it must provide this recordId in order to allow the caller to match the record results to their input.

  • Ein data-Element, das im Wesentlichen ein Behälter mit Eingabefeldern für jeden Datensatz ist.A data member, which is essentially a bag of input fields for each record.

Das bedeutet für das oben gezeigte Beispiel, dass die Web-API Anforderungen zu erwarten hat, die wie folgt aussehen:To be more concrete, per the example above, your Web API should expect requests that look like this:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2017 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

In der Praxis können kann Ihr Dienst mit Hunderten oder Tausenden von Datensätzen, anstatt nur mit den hier gezeigten drei, aufgerufen werden.In reality, your service may get called with hundreds or thousands of records instead of only the three shown here.

2. Web-API-Ausgabeformat2. Web API Output Format

Das Format der Ausgabe ist eine Gruppe von Datensätzen, die ein recordId-Element umfassen, und ein Eigenschaftenbehälter.The format of the output is a set of records containing a recordId, and a property bag

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2017 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Dieses spezielle Beispiel hat nur eine Ausgabe, Sie können jedoch auch mehr als eine Eigenschaft ausgeben.This particular example has only one output, but you could output more than one property.

Fehler und WarnungenErrors and Warning

Wie im vorherigen Beispiel gezeigt, können Sie für jeden Datensatz Fehler- und Warnmeldungen zurückgeben.As shown in the previous example, you may return error and warning messages for each record.

Verwenden von benutzerdefinierten Skills aus dem SkillsetConsuming custom skills from skillset

Wenn Sie eine Web-API-Anreicherungsfunktion erstellen, können Sie HTTP-Header und Parameter als Teil der Anforderung beschreiben.When you create a Web API enricher, you can describe HTTP headers and parameters as part of the request. Der folgende Codeausschnitt zeigt, wie Anforderungsparameter und HTTP-Header als Teil der Skillsetdefinition beschrieben werden können.The snippet below shows how request parameters and HTTP headers may be described as part of the skillset definition.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Nächste SchritteNext steps