Erstellen eines Skillsets in Azure KI Search

Artikel
03/13/2024

Ein Skillset definiert Vorgänge, die Textinhalte und -strukturen aus Dokumenten generieren, die Bilder oder unstrukturierten Text enthalten. Beispiele sind die optische Zeichenerkennung (OCR) für Bilder, die Entitätserkennung für nicht formatierten Text und die Textübersetzung. Ein Skillset wird ausgeführt, nachdem Text und Bilder aus einer externen Datenquelle extrahiert wurden und nachdem Feldzuordnungen verarbeitet wurden.

In diesem Artikel wird erläutert, wie Sie ein Skillset mit REST-APIs erstellen, die gleichen Konzepte und Schritte gelten jedoch auch für andere Programmiersprachen.

Zu den Regeln für die Skillsetdefinition gehören:

Ein eindeutiger Name innerhalb der Skillset-Sammlung Ein Skillset ist eine Ressource auf oberster Ebene, die von jedem Indexer verwendet werden kann.
Mindestens ein Skill Drei bis fünf Skills sind die Regel. Der Höchstwert beträgt 30.
Ein Skillset kann Fertigkeiten desselben Typs wiederholen (z. B. mehrere Former-Fertigkeiten).
Ein Skillset unterstützt verkettete Vorgänge, Schleifen und Verzweigungen.

Indexer fördern die Ausführung von Skillset. Sie benötigen einen Indexer, eine Datenquelle und einen Index, bevor Sie Ihr Skillset testen können.

Tipp

Aktivieren Sie das Zwischenspeichern von Anreicherungen, um bereits verarbeitete Inhalte wiederzuverwenden und die Entwicklungskosten zu senken.

Hinzufügen einer Skillsetdefinition

Beginnen Sie mit der grundlegenden Struktur. In der REST-API zum Erstellen von Skillsets wird der Anforderungstext in JSON erstellt und enthält die folgenden Abschnitte:

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"An Azure AI services resource in the same region as Azure AI Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

Nach dem Namen und der Beschreibung verfügt ein Skillset über vier Haupteigenschaften:

skills-Array, eine nicht angeordnete Sammlung von Fähigkeiten. Skills können nützliche (z. B. für das Aufteilen von Text), transformative (basierend auf KI aus den Azure KI Services) oder von Ihnen zur Verfügung stellende benutzerdefinierte Skills sein. Ein Beispiel für ein Fertigkeiten-Array finden Sie im nächsten Abschnitt.
cognitiveServices wird für abrechenbare Skills verwendet, welche die Azure KI Services-APIs aufrufen. Entfernen Sie diesen Abschnitt, wenn Sie weder abrechenbaren Fertigkeiten noch einen benutzerdefinierte Entitäten Lookup verwenden. Fügen Sie eine Ressource hinzu, wenn Sie es sind.
knowledgeStore (optional) gibt ein Azure Storage-Konto und Einstellungen für die Projektierung von Skillset-Ausgaben in Tabellen, Blobs und Dateien in Azure Storage an. Entfernen Sie diesen Abschnitt, wenn Sie ihn nicht benötigen, andernfalls geben Sie einen Wissensspeicher an.
encryptionKey (optional) gibt eine Azure Key Vault-Instanz und kundenseitig verwaltete Schlüssel an, die verwendet werden, um sensible Inhalte (Beschreibungen, Verbindungszeichenfolgen, Schlüssel) in einer Skillsetdefinition zu verschlüsseln. Entfernen Sie diese Eigenschaft, wenn Sie keine vom Kunden verwaltete Verschlüsselung verwenden.

Hinzufügen von Fähigkeiten

Innerhalb einer Skillsetdefinition gibt das Fertigkeiten-Array an, welche Fertigkeiten ausgeführt werden sollen. Drei bis fünf Fähigkeiten sind üblich, aber Sie können beliebig viele Fähigkeiten hinzufügen, die Dienstbeschränkungen unterliegen.

Das Ergebnis einer Anreicherungspipeline ist Textinhalt in einem Suchindex oder einem Wissensspeicher. Aus diesem Grund erstellen die meisten Fähigkeiten entweder Text aus Bildern (OCR-Text, Untertitel, Tags) oder analysieren bestehender Text, um neue Informationen zu erstellen (Entitäten, Schlüsselausdrücke, Stimmung). Fähigkeiten, die unabhängig funktionieren, werden parallel verarbeitet. Fähigkeiten, die voneinander abhängig sind, geben die Ausgabe einer Fähigkeit (so wie Schlüsselbegriffe) als Eingabe der zweiten Fähigkeit (so wie Textübersetzung) an. Der Suchdienst bestimmt die Reihenfolge der Ausführung von Skills sowie die Ausführungsumgebung.

Alle Fertigkeiten verfügen über einen Typ, Kontext, Eingaben und Ausgaben. Eine Fähigkeit kann optional einen Namen und eine Beschreibung haben. Das folgende Beispiel zeigt zwei nicht verbundene integrierte Fähigkeiten, damit Sie die grundlegende Struktur vergleichen können.

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

Jede Fertigkeit ist hinsichtlich ihrer Eingabewerte und der benötigten Parameter eindeutig. Die Dokumentation für jede Fertigkeit beschreibt alle Parameter und Eigenschaften einer bestimmten Fertigkeit. Obwohl es Unterschiede gibt, teilen sich die meisten Fertigkeiten einen gemeinsamen Satz und sind ähnlich gemustert.

Hinweis

Sie können komplexe Skillsets mit Schleifen und Branches erstellen, indem Sie die Fertigkeit „Bedingt“ zur Erstellung der Ausdrücke verwenden. Die Syntax basiert auf der JSON-Zeiger-Pfadnotation, mit einigen Änderungen zum Identifizieren von Knoten in der Anreicherungsstruktur. Ein "/" durchläuft eine niedrigere Ebene in der Struktur und "*" fungiert als „for-each“-Operator im Kontext. Zahlreiche Beispiele in diesem Artikel veranschaulichen die Syntax.

Einstellen des Fähigkeitenkontextes

Jede Fähigkeit verfügt über eine Kontexteigenschaft, die die Ebene bestimmt, auf der Vorgänge ausgeführt werden. Wenn die Eigenschaft „context" nicht explizit festgelegt ist, lautet der Standardwert "/document", wobei der Kontext das gesamte Dokument ist (die Fähigkeit wird einmal pro Dokument aufgerufen).

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

Der Kontext wird in der Regel auf eines der folgenden Beispiele festgelegt:

Kontextbeispiel	Beschreibung
"context": "/document"	(Standard) Eingaben und Ausgaben befinden sich auf Dokumentebene.
"context": "/document/pages/*"	Einige Fertigkeiten wie die Stimmungsanalyse funktionieren besser bei kleineren Textblöcken. Wenn Sie ein großes Inhaltsfeld in Seiten oder Sätze aufteilen, sollte der Kontext über jedem Teil stehen.
"context": "/document/normalized_images/*"	Eingaben und Ausgaben entsprechen einer Instanz pro Bild im übergeordneten Dokument.

Der Kontext bestimmt auch, wo Ausgaben in der Anreicherungsstruktur erzeugt werden. Beispielsweise gibt die Entitätserkennungskompetenz eine Eigenschaft namens "organizations" zurück, erfass als orgs. Wenn der Kontext "/document" ist, wird ein Knoten „Organisationen" als untergeordnetes Element "/document" hinzugefügt. Wenn Sie dann auf diesen Knoten in nachgelagerten Fähigkeiten verweisen möchten, wäre "/document/orgs" der Pfad .

Definieren der Eingaben

Fähigkeiten lesen und schreiben in ein angereichertes Dokument. Fähigkeitseingaben geben den Ursprung der eingehenden Daten und deren Verwendung an. Es ist häufig der Stammknoten des erweiterten Dokuments. Bei Blobs ist eine typische Fähigkeitseingabe die Inhaltseigenschaft des Dokuments.

In der Referenzdokumentation für jeden Skill werden die Eingaben beschrieben, die er nutzen kann. Jede Eingabe hat einen „Namen“, der eine bestimmte Eingabe identifiziert, und eine „Quelle“, die den Speicherort für die Daten im angereicherten Dokument angibt. Das folgende Beispiel stammt aus der Entitätserkennungskompetenz:

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

Fähigkeiten können mehrere Eingaben haben. Der „Name" ist die spezifische Eingabe. Für die Entitätserkennung sind die spezifischen Eingaben „Text" und „languageCode".

Die Eigenschaft „source" gibt an, welches Feld oder welche Zeile den zu verarbeitenden Inhalt bereitstellt. Bei textbasierten Fähigkeiten handelt es sich um ein Feld im Dokument oder in der Zeile, das oder die Text enthält. Bei bildbasierten Fertigkeiten handelt es sich bei dem Knoten, der die Eingabe bereitstellt, um normalisierte Bilder.

Quellbeispiel	Beschreibung
„Quelle“:“/dokument“	Bei einem tabellarischen Datensatz entspricht ein Dokument einer Zeile.
"source": "/document/content"	Bei Blobs ist die Quelle normalerweise die Inhaltseigenschaft des Blobs.
"source": "/document/some-named-field"	Bei textbasierten Fertigkeiten wie Entitätserkennung oder Schlüsselbegriffserkennung sollte der Ursprung ein Feld sein, das ausreichend zu analysierenden Text enthält, z. B. eine „Beschreibung“ oder „Zusammenfassung“.
"source": "/document/normalized_images/*"	Bei Bildinhalten handelt es sich bei der Quelle um ein Bild, das während der Dokumententschlüsselung normalisiert wurde.

Wenn die Fertigkeit über ein Array iteriert, sollten sowohl Kontext als auch Eingabequelle entsprechend /* an den richtigen Positionen enthalten.

Definieren der Ausgaben

Jede Fertigkeit ist so konzipiert, dass bestimmte Arten von Ausgaben ausgegeben werden, auf die über den Namen im Skillset verwiesen wird. Eine Qualifikationsausgabe verfügt über einen „Namen" und einen optionalen „targetName".

In der Dokumentation für jede Fertigkeit werden die Ausgaben beschrieben, die sie erzeugen kann. Das folgende Beispiel stammt aus der Entitätserkennungskompetenz:

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

Fähigkeiten können mehrere Eingaben haben. Der „Name" identifiziert eine bestimmte Ausgabe. Beispielsweise kann die Ausgabe für die Entitätserkennung „Personen", „Standorte", „Organisationen" und andere sein.
„targetName" gibt den Namen an, den Sie in dem erweiterten Dokument haben möchten. Dies ist nützlich, wenn die Fähigkeitenausgabe denselben Namen hat. Wenn Sie über mehrere Fertigkeiten verfügen, die dieselbe Ausgabe zurückgeben, müssen Sie "targetName" zur Namensunterscheidung innerhalb der Anreicherungsknotenpfade verwenden. Wenn der Zielname nicht angegeben ist, wird die Namenseigenschaft für beide verwendet.

In manchen Situationen ist es notwendig, auf jedes Element eines Arrays einzeln zu verweisen. Angenommen, Sie möchten jedes Element von "/document/orgs" separat an eine anderen Fertigkeit übergeben. Fügen Sie dazu dem Pfad ein Sternchen hinzu: "/document/orgs/*".

Die Fähigkeitsausgabe wird als neuer Knoten im Anreicherungsbaum in das anreicherte Dokument geschrieben. Es kann ein einfacher Wert sein, so wie eine Stimmungsbewertung oder ein Sprachcode. Es könnte auch eine Auflistung sein, so wie eine Liste von Organisationen, Personen oder Standorten. Die Fähigkeitsausgabe kann auch eine komplexe Struktur sein, wie dies bei der Former-Fähigkeit der Fall ist. Die Eingaben der Fähigkeiten bestimmen die Zusammensetzung der Form, aber die Ausgabe ist das benannte Objekt, auf das in einem Suchindex, einer Wissensspeicher-Projektion oder einer anderen Fähigkeit durch seinen Namen verwiesen werden kann.

Hinzufügen eines benutzerdefinierten Skills

Dieser Abschnitt enthält ein Beispiel für eine benutzerdefinierte Fertigkeit. Der URI verweist auf eine Azure-Funktion, die wiederum das von Ihnen bereitgestellte Modell oder die von Ihnen bereitgestellte Transformation aufruft. Weitere Informationen finden Sie unter Definieren einer benutzerdefinierte Schnittstelle.

Obwohl die benutzerdefinierte Fertigkeit einen Code außerhalb der Pipeline ausführt, handelt es sich bei einem Fertigkeiten-Array nur um eine weitere Fertigkeit. Wie die integrierten Fertigkeiten, verfügt sie auch über einen Typ, einen Kontext, Eingaben und Ausgaben. Sie liest und schreibt auch in eine Anreicherungsstruktur, genau wie die integrierten Fertigkeiten. Beachten Sie, dass das Feld „context“ mit einem Sternchen auf "/document/orgs/*" gesetzt ist, d.h. der Anreicherungsschritt wird für jede Organisation unter "/document/orgs" aufgerufen.

Die Ausgabe, z. B. die Unternehmensbeschreibung in diesem Beispiel, wird für jede identifizierte Organisation generiert. Bei Bezugnahme auf den Knoten in einem nachfolgenden Schritt (z. B. bei der Schlüsselbegriffserkennung) würden Sie dazu den Pfad "/document/orgs/*/companyDescription" verwenden.

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

Senden der Ausgabe an ein Ziel

Obwohl die Fähigkeitsausgabe optional für die Wiederverwendung zwischengespeichert werden kann, ist es in der Regel vorübergehend und ist nur vorhanden, während die Fähigkeitsausführung in Arbeit ist.

Um die Ausgabe an ein Feld in einem Suchindex zu senden, müssen Sie eine Ausgabefeldzuordnung in einem Indexer erstellen.
Um die Ausgabe an einen Wissensspeicher zu senden, müssen Sie eine Projektion erstellen.
Um die Ausgabe an eine nachgelagerte Fähigkeit zu senden, verweisen Sie auf die Ausgabe anhand des Knotennamens, so wie "/document/organization" in der Eingabequelleneigenschaft der nachgelagerten Fähigkeiten. Beispiele finden Sie unter Verweisen auf Anmerkungen in einem Azure Cognitive Search-Skillset.

Tipps für ein erstes Skillset

Testen Sie den Assistenten zum Importieren von Daten.

Der Assistent automatisiert mehrere Schritte, die beim ersten Mal eine Herausforderung darstellen können. Es definiert das Skillset, Index und Indexer, einschließlich Feldzuordnungen und Ausgabefeldzuordnungen. Es definiert auch Projektionen in einem Wissensspeicher, wenn Sie einen verwenden. Für einige Fertigkeiten, wie OCR oder Bildanalyse, fügt der Assistent Hilfsfertigkeiten hinzu, die Bild- und Textinhalte zusammenführen, die bei der Dokumententschlüsselung getrennt wurden.

Nachdem der Assistent ausgeführt wurde, können Sie jedes Objekt im Azure-Portal öffnen, um die JSON-Definition anzuzeigen.
Sie können auch Debug-Sitzungen verwenden, um die Ausführung des Skillsets über ein Zieldokument aufzurufen und das vom Skillset erstellte angereicherte Dokument zu untersuchen. Sie können die Einstellungen und Werte von Ein- und Ausgabe anzeigen und ändern. Dieses Tutorial ist ein guter Ausgangspunkt: Tutorial: Debuggen eines Skillsets mithilfe von Debugsitzungen.

Nächste Schritte

Die Kontext- und Eingabequellenfelder sind Pfade zu Knoten in einer Anreicherungsstruktur. Als nächsten Schritt sollten Sie mehr über die Pfadsyntax für Knoten in einer Anreicherungsstruktur erfahren.

Verweisen auf Anmerkungen in einem Skillset