Verweisen auf einen Pfad zu angereicherten Knoten mithilfe von Kontext- und Quelleigenschaften und des Azure KI-Suche-Skillset

  • Artikel

Während der Ausführung des Skillset erstellt das Modul eine In-Memory-Anreicherungsstruktur, die jede Anreicherung erfasst, z. B. erkannte Entitäten oder übersetzten Text. In diesem Artikel erfahren Sie, wie Sie auf einen Anreicherungsknoten in der Anreicherungsstruktur verweisen, damit Sie die Ausgabe an nachgelagerte Skills übergeben oder eine Ausgabefeldzuordnung für ein Suchindexfeld angeben können.

In diesem Artikel werden Beispiele verwendet, um verschiedene Szenarien zu veranschaulichen. Die vollständige Syntax finden Sie unter Skillkontext und Eingabeanmerkungssprache.

Hintergrundkonzepte

Gehen Sie vor dem Überprüfen der Syntax nun noch einmal einige wichtige Konzepte durch, um die später in diesem Artikel vorgestellten Beispiele besser zu verstehen.

Begriff Beschreibung
„Angereichertes Dokument“ Ein angereichertes Dokument ist eine In-Memory-Struktur, die die Ausgabe von Skills während der Erstellung erfasst und alle Anreicherungen zu einem Dokument enthält. Stellen Sie sich ein angereichertes Dokument als eine Struktur vor. Im Allgemeinen beginnt die Struktur auf der Ebene des Stammdokuments, und jede neue Anreicherung wird von einer vorherigen Anreicherung als deren untergeordnete Anreicherung erstellt.
„node“ In einem angereicherten Dokument wird ein Knoten (manchmal auch als „Anmerkung“ bezeichnet) erstellt und durch einen Skill aufgefüllt, wie z. B. „text“ und „layoutText“ im OCR-Skill. Ein angereichertes Dokument wird sowohl mit Anreicherungen als auch mit ursprünglichen Quellfeldwerten oder Metadaten aufgefüllt, die aus der Quelle kopiert wurden.
„Kontext“ Der Umfang der Anreicherung, d. h. entweder das gesamte Dokument, ein Teil eines Dokuments oder, wenn Sie mit Bildern arbeiten, die extrahierten Bilder aus einem Dokument. Standardmäßig befindet sich der Anreicherungskontext auf der Ebene "/document", die auf einzelne Dokumente in der Datenquelle bezogen ist. Wenn ein Skill ausgeführt wird, werden die Ergebnisse dieses Skills zu Eigenschaften des definierten Kontexts.

Pfade für verschiedene Szenarios

Pfade werden in den Eigenschaften „Kontext“ und „Quelle“ eines Skillsets und in den Ausgabefeldzuordnungen in einem Indexer angegeben.

Screenshot einer Skillsetdefinition mit hervorgehobenen Kontext- und Quellelementen

Das Beispiel im Screenshot veranschaulicht den Pfad für ein Element in einer Azure Cosmos DB-Sammlung.

  • Der Pfad context ist /document/HotelId, da die Auflistung durch das Feld /HotelId in Dokumente partitioniert wird.

  • Der Pfad source ist /document/Description, da der Skill ein Übersetzungsskill ist, und das Feld, das der Skill übersetzen soll, ist das Feld Description im jeweiligen Dokument.

Alle Pfade beginnen mit /document. Ein angereichertes Dokument wird in der Phase „Dokumententschlüsselung“ der Indexerausführung erstellt, wenn der Indexer ein Dokument öffnet oder in einer Zeile aus der Datenquelle liest. Der einzige Knoten in einem angereicherten Dokument ist zunächst der Stammknoten (/document), von dem aus alle anderen Anreicherungen erfolgen.

Die folgende Liste enthält einige gängige Beispiele:

  • /document ist der Stammknoten und gibt einen gesamten Blob in Azure Storage oder eine Zeile in einer SQL-Tabelle an.
  • /document/{key} ist die Syntax für ein Dokument oder Element in einer Azure Cosmos DB-Sammlung, wobei es sich bei {key} um den tatsächlichen Schlüssel handelt, wie z. B. /document/HotelId im vorherigen Beispiel.
  • /document/content gibt die Eigenschaft „Inhalt“ eines JSON-Blobs an.
  • /document/{field} ist die Syntax für einen Vorgang, der für ein bestimmtes Feld ausgeführt wird, z. B. das Übersetzen des Felds /document/Description, das im vorherigen Beispiel dargestellt wird.
  • /document/pages/* oder /document/sentences/* werden zum Kontext, wenn Sie ein großes Dokument für die Verarbeitung in kleinere Abschnitte aufteilen. Wenn es sich bei „Kontext“ um /document/pages/* handelt, wird der Skill einmal für jede Seite im Dokument ausgeführt. Da möglicherweise mehr als eine Seite oder ein Satz vorhanden ist, fügen Sie /* an, um alle zu erfassen.
  • /document/normalized_images/* wird während der Dokumententschlüsselung erstellt, wenn das Dokument Bilder enthält. Alle Pfade zu Bildern beginnen mit normalized_images. Da häufig mehrere Bilder in ein Dokument eingebettet sind, fügen Sie /* an.

Die Beispiele im restlichen Teil dieses Artikels basieren auf dem Feld „content“, das automatisch von Azure Blob-Indexern während der Dokumententschlüsselung generiert wird. Wenn Sie sich auf Dokumente aus einem Blobcontainer beziehen, verwenden Sie ein Format wie "/document/content", wobei das Feld „Inhalt“ Teil des „Dokuments“ ist.

Beispiel 1: Einfacher Anmerkungsverweis

Angenommen, Sie haben in Azure Blob Storage eine Vielzahl von Dateien, die Verweise auf die Namen von Personen enthalten, die Sie mithilfe der Entitätserkennung extrahieren möchten. In der folgenden Skilldefinition ist "/document/content" die Textdarstellung des gesamten Dokuments, und „people“ ist eine Extrahierung von vollständigen Namen für als Personen identifizierte Entitäten.

Da der Standardkontext "/document" ist, kann auf die Liste der Personen nun als "/document/people" verwiesen werden. In diesem speziellen Fall ist "/document/people" eine Anmerkung, die nun einem Feld in einem Index zugeordnet oder in einem anderen Skill im gleichen Skillset verwendet werden kann.

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

Beispiel 2: Verweisen auf ein Array innerhalb eines Dokuments

Dieses Beispiel baut auf dem vorherigen auf und zeigt Ihnen, wie Sie einen Anreicherungsschritt mehrfach über dasselbe Dokument aufrufen können. Angenommen, das vorherige Beispiel generiert ein Array von Zeichenfolgen mit zehn Personennamen aus einem einzigen Dokument. Ein sinnvoller nächster Schritt könnte eine zweite Anreicherung sein, die den Nachnamen aus einem vollständigen Namen extrahiert. Da es zehn Namen gibt, soll dieser Schritt in diesem Dokument zehnmal aufgerufen werden, d.h. einmal pro Person.

Um die richtige Anzahl von Iterationen aufzurufen, setzen Sie den Kontext auf "/document/people/*", wobei das Sternchen ("*") für alle Knoten im angereicherten Dokument als untergeordnete Elemente von "/document/people" steht. Obwohl dieser Skill nur einmal im Skillsarray definiert ist, wird er für jedes Element innerhalb des Dokuments aufgerufen, bis alle Elemente bearbeitet sind.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

Wenn es sich bei Anmerkungen um Arrays oder Sammlungen von Zeichenfolgen handelt, empfiehlt es sich, für bestimmte Elemente statt auf das Array als Ganzes abzuzielen. Der Code im obigen Beispiel generiert unter jedem Knoten, der durch den Kontext repräsentiert wird, eine Anmerkung namens "last". Wenn Sie auf diese Familie von Anmerkungen verweisen möchten, können Sie die Syntax "/document/people/*/last" verwenden. Wenn Sie auf eine bestimmte Anmerkung verweisen möchten, können Sie einen expliziten Index verwenden: "/document/people/1/last", um auf den Nachnamen der ersten im Dokument identifizierten Person zu verweisen. Beachten Sie, dass in dieser Syntax Arrays „0 indiziert“ sind.

Beispiel 3: Verweisen auf Elemente innerhalb eines Arrays

Manchmal müssen Sie alle Anmerkungen eines bestimmten Typs gruppieren, um sie an einen bestimmten Skill zu übergeben. Angenommen, es gibt einen hypothetischen benutzerdefinierten Skill, der den häufigsten Nachnamen aus allen in Beispiel 2 extrahierten Nachnamen identifiziert. Um dem benutzerdefinierten Skill nur die Nachnamen bereitzustellen, legen Sie den Kontext auf "/document" und die Eingabe auf "/document/people/*/lastname" fest.

Beachten Sie, dass die Kardinalität von "/document/people/*/lastname" größer als die des Dokuments ist. Es kann zehn Nachnamenknoten geben, während es nur einen Dokumentknoten für dieses Dokument gibt. In diesem Fall wird automatisch ein Array von "/document/people/*/lastname" erstellt, das alle Elemente des Dokuments enthält.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

Tipps zur Problembehandlung bei Anmerkungspfaden

Wenn Sie Probleme bei der Angabe von Skilleingaben haben, können die folgenden Tipps hilfreich sein:

Siehe auch