Erstellen eines Skillsets in Azure KI Search

Note

Azure KI-Suche ist über das Azure Portal, REST-APIs und Azure SDKs verfügbar. Es unterstützt auch Foundry IQ, die verwaltete Wissensschicht, die Unternehmensinhalte in wiederverwendbare, berechtigungsfähige Wissensbasen für Agenten im Microsoft Foundry-Portal transformiert.

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 jeder Indexer verwenden 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 an einen Indexer anfügen. 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 ressource auf hoher Ebene, ist aber nur innerhalb der Indizierungsverarbeitung funktionsfähig. Als übergeordnete Ressource können Sie in mehreren Indexern darauf verweisen.

Tip

Aktivieren Sie das Anreicherungszwischenspeichern , um den bereits verarbeiteten Inhalt wiederzuverwenden und die Entwicklungskosten zu senken.

Hinzufügen einer Skillsetdefinition

Wenn Sie ein Skillset erstellen, fügen Sie es Ihrem Suchdienst hinzu. Wenn Sie ein Skillset aktualisieren, überschreiben Sie ein vorhandenes Skillset vollständig mit dem Inhalt der Anforderungsnutzlast. Um ein Skillset zu aktualisieren, rufen Sie die Skillset-Definition mithilfe von GET ab, ändern Sie es, und aktualisieren Sie es dann mithilfe von PUT.

Note

Wenn Sie ein Skillset mithilfe von GET abrufen, gibt der Dienst <redacted> für alle httpHeaders-Werte in benutzerdefinierten Skills und ?code=<redacted> für alle ?code=-Abfrageparameter in demuri zurück. Wenn Sie das Skillset aktualisieren möchten, ohne diese Werte zu ändern, setzen Sie diese Felder im Textkörper der PUT-Anforderung auf <unchanged>. Ausführliche Informationen finden Sie unter "Benutzerdefinierte Web-API-Fähigkeit – Qualifikationsparameter".

Beginnen Sie mit der grundlegenden Struktur. Erstellen Sie in der REST-API „Skillset erstellen“ den Textkörper der Anfrage in JSON. Es 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":"A Microsoft Foundry resource in the same region as Azure AI Search",
      "key":"<Your-Azure-AI-Foundry-Resource-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 sein (z. B. das Aufteilen von Text), transformational (basierend auf KI von Azure OpenAI oder Foundry Tools) oder benutzerdefinierte Fähigkeiten, die Sie bereitstellen. Ein Beispiel für ein Fertigkeiten-Array finden Sie im nächsten Abschnitt.

• cognitiveServices wird für abrechnende Fähigkeiten verwendet, die Foundry Tools-APIs aufrufen. Entfernen Sie diesen Abschnitt, wenn Sie weder abrechenbaren Fertigkeiten noch einen benutzerdefinierte Entitäten Lookup verwenden. Wenn das der Fall ist, fügen Sie eine Foundry-Ressource 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. Geben Sie andernfalls 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.

Note

Sie können komplexe Skillsets mit Schleifen und Branches erstellen, indem Sie den Kognitiver Skill „Bedingt“ zur Erstellung der Ausdrücke verwenden. Die Syntax basiert auf der JSON-Zeigerpfadnotation 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 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": []
  }
]

Legen Sie die context Eigenschaft auf eines der folgenden Beispiele fest:

Kontextbeispiel	Description
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 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

Jeder Skill ist so konzipiert, dass er bestimmte Arten von Ausgaben erzeugt, die das Skillset namentlich referenziert. Eine Qualifikationsausgabe verfügt über eine name und eine optionale targetName.

Die Referenzdokumentation zu den Skills für jeden Skill beschreibt die Ausgaben, die er 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. 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 dieser Knoten im erweiterten Dokument haben soll. Diese Eigenschaft ist nützlich, wenn Qualifikationsausgaben denselben Namen haben. Wenn Sie über mehrere Fertigkeiten verfügen, die dieselbe Ausgabe zurückgeben, müssen Sie targetName zur Namensunterscheidung innerhalb der Anreicherungsknotenpfade verwenden. Wenn Sie den Zielnamen nicht angeben, wird die Name-Eigenschaft für beides 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 KI-Suche-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. Verwenden Sie beim Verweisen auf den Knoten in einem nachgelagerten Schritt (z. B. in der Tastenauszugsextraktion) den Pfad "/document/orgs/*/companyDescription" , um dies zu tun.

{
  "@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=<YOUR-FUNCTION-KEY>",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "<YOUR-APIM-KEY>"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Senden der Ausgabe an ein Ziel

Obwohl Sie Skillausgaben optional zur Wiederverwendung zwischenspeichern können, sind diese in der Regel nur vorübergehend und existieren nur, solange die Skills ausgeführt werden.

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

  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 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.

Verweisen auf Anmerkungen in einem Skillset