Erstellen eines Skillsets in Azure KI Search

Ein Skillset definiert Vorgänge, die Vektor- und Textinhalte und -struktur aus Dokumenten generieren, die Bilder oder Rohinhalte enthalten. Beispiele sind Chunking-Fähigkeiten, Einbettungstechniken (Vektorisierung), Bildverbalisierung und andere Prozesse wie optische Zeichenerkennung (OCR) für Bilder, Entitätserkennung für nicht differenzierte Texte und Textübersetzung. Ein Skillset wird ausgeführt, nachdem roher Inhalt aus einer externen Datenquelle extrahiert wurde, und nachdem Feldzuordnungen verarbeitet wurden.

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

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

• Muss einen eindeutigen Namen in der Skillsetsammlung haben. Ein Skillset ist eine Ressource auf oberster Ebene, die von jedem Indexer verwendet werden kann.
• Muss mindestens einen Skill aufweisen. Drei bis fünf Skills sind die Regel. Der Höchstwert beträgt 30.
• Ein Skillset kann die Skills derselben Art wiederholen. Beispielsweise kann ein Skillset mehrere Shaper-Fähigkeiten haben.
• Ein Skillset unterstützt verkettete Vorgänge, Schleifen und Verzweigungen.

Ein Skillset ist einem Indexer zugeordnet. Um das Skillset zu verwenden, verweisen Sie in einem Indexer darauf, und führen Sie dann den Indexer aus, um Daten zu importieren, die Verarbeitung von Fähigkeiten aufzurufen und die Ausgabe an einen Index zu senden. Ein Skillset ist eine hochgradige Ressource, aber sie ist nur innerhalb der Indexerverarbeitung funktionsfähig. Als übergeordnete Ressource können Sie in mehreren Indexern darauf verweisen.

Hinzufügen einer Skillsetdefinition

Durch das Erstellen eines Skillsets wird es Ihrem Suchdienst hinzugefügt. Durch das Aktualisieren eines Skillsets wird ein vorhandenes Skillset vollständig mit dem Inhalt der Anforderungsnutzlast überschrieben. Eine bewährte Methode für Updates besteht darin, die Skillset-Definition mit einem GET abzurufen, zu ändern und dann mit PUT zu aktualisieren.

Beginnen Sie mit der grundlegenden Struktur. In der REST-API "Create Skillset" wird der Text der Anforderung in JSON erstellt und weist die folgenden Abschnitte auf:

{
   "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-Multi-Service-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. Fähigkeiten sind entweder eigenständig oder durch Eingabe-Ausgabe-Verknüpfungen verkettet, wobei die Ausgabe einer Transformation als Eingabe für eine andere dient. Fähigkeiten können utilitarisch (wie das Aufteilen von Text), transformational (basierend auf KI von Azure OpenAI oder Azure AI-Diensten) oder benutzerdefinierte Fähigkeiten sein, die Sie bereitstellen. 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. Wenn Sie es sind, fügen Sie eine Multi-Service-Ressource von Azure KI Services an.

• 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 einen Azure Key Vault und vom Kunden verwaltete Schlüssel an, mit dem vertrauliche Inhalte (Beschreibungen, Verbindungszeichenfolgen, Schlüssel) in einer Skillsetdefinition verschlüsselt werden. 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 so viele Fähigkeiten wie nötig hinzufügen, vorbehaltlich der Dienstbeschränkungen.

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 einer zweiten Fähigkeit (so wie Textübersetzung) an. Der Suchdienst bestimmt die Reihenfolge der Ausführung von Fähigkeiten und der 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 zusammenhängende 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. Qualifikationsreferenzdokumentation beschreibt alle Parameter und Eigenschaften einer bestimmten Fähigkeit. Obwohl es Unterschiede gibt, teilen sich die meisten Fertigkeiten einen gemeinsamen Satz und sind ähnlich gemustert.

Einstellen des Fähigkeitenkontextes

Jede Fähigkeit verfügt über eine Kontexteigenschaft , die die Ebene bestimmt, auf der Vorgänge stattfinden. 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": []
  }
]

Die context-Eigenschaft wird in der Regel auf eines der folgenden Beispiele festgelegt:

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

Definieren von 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 name, der eine bestimmte Eingabe identifiziert, und eine source, die den Speicherort der 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	Description
  source: /document	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 Fähigkeiten, z. B. Entitätserkennung oder Schlüsselausdruckextraktion, sollte der Ursprung ein Feld sein, das ausreichenden 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. Weitere Informationen zur vollständigen Syntax finden Sie unter Qualifikationskontext und Eingabeanmerkungssprache.

Definieren von 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 eine name und eine optionale targetName.

Skill-Referenzdokumentation für jeden Skill beschreibt die Ergebnisse, die er produzieren 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. Die name-Eigenschaft identifiziert eine bestimmte Ausgabe. Bei der Entitätserkennung kann die Ausgabe beispielsweise Personen, Standorte, Organisationen u. a. sein.

• Die targetName-Eigenschaft 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"/document/orgs" separat an eine andere Fähigkeit ü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 Fähigkeit. 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 Hinzufügen einer benutzerdefinierten Fähigkeit zu einer Azure AI Search-Anreicherungspipeline.

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 contextmit 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, erstellen Sie eine Ausgabefeldzuordnung in einem Indexer.

• Um die Ausgabe an einen Wissensspeicher zu senden, erstellen Sie eine Projektion.

• 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 eine Anmerkung .

Tipps für ein erstes Skillset

• Testen Sie den Assistenten zum Importieren von Daten oder zum Importieren von Daten (neu).

  Die Assistent automatisieren 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 Lernprogramm ist ein guter Ausgangspunkt: Lernprogramm: Debuggen eines Skillsets mithilfe von Debugsitzungen.

Nächster Schritt

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.