Tutorial: Debuggen eines Skillsets mithilfe von Debugsitzungen

  • Artikel

Ein Skillset koordiniert die Aktionen von Fähigkeiten, die durchsuchbare Inhalte analysieren, transformieren oder erstellen. Häufig wird die Ausgabe einer Fähigkeit zur Eingabe einer anderen. Wenn Eingaben von Ausgaben abhängen, können Fehler in Skillsetdefinitionen und Feldzuordnungen zu fehlenden Vorgängen und Daten führen.

Debugsitzungen ist ein Tool im Azure-Portal, das eine ganzheitliche Visualisierung eines Skillsets ermöglicht. Mithilfe dieses Tools können Sie einen Drilldown für bestimmte Schritte ausführen, um leicht zu ermitteln, wo eine Aktion möglicherweise fehlschlägt.

In diesem Artikel verwenden Sie Debugsitzungen, um fehlende Eingaben und Ausgaben zu suchen und zu korrigieren. Das Tutorial ist umfassend. Es stellt Beispieldaten, eine Postman-Sammlung, die Objekte erstellt, und Anweisungen zum Debuggen von Problemen im Skillset zur Verfügung.

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

Voraussetzungen

Hinweis

In diesem Tutorial werden auch Azure AI Services für Spracherkennung, Entitätserkennung und Schlüsselbegriffserkennung verwendet. Aufgrund der geringen Workloadgröße wird Azure AI Services im Hintergrund für die kostenlose Verarbeitung von bis zu 20 Transaktionen genutzt. Das bedeutet, dass Sie diese Übung durchführen können, ohne eine abrechenbare Azure AI Services-Ressource erstellen zu müssen.

Die Beispieldatenbank einrichten

In diesem Abschnitt wird das Beispieldataset in Azure Blob Storage erstellt, sodass Indexer und Skillset Inhalte aufweisen, mit denen Sie arbeiten können.

  1. Laden Sie Beispieldaten (clinical-trials-pdf-19) herunter, die aus 19 Dateien bestehen.

  2. Erstellen Sie ein Azure Storage-Konto, oder suchen Sie nach einem vorhandenen Konto.

    • Wählen Sie die gleiche Region wie Azure AI Search, um Bandbreitengebühren zu vermeiden.

    • Es muss den Kontotyp „StorageV2 (allgemein, Version 2)“ besitzen.

  3. Navigieren Sie im Portal zu den Seiten mit den Azure Storage-Diensten, und erstellen Sie einen Blobcontainer. Eine bewährte Methode besteht darin, die Zugriffsebene „Privat“ anzugeben. Nennen Sie den Container clinicaltrialdataset.

  4. Klicken Sie im Container auf Hochladen, um die im ersten Schritt heruntergeladenen und entpackte Beispieldateien hochzuladen.

  5. Kopieren Sie im Portal die Verbindungszeichenfolge für Azure Storage. Sie können die Verbindungszeichenfolge im Portal unter Einstellungen>Zugriffsschlüssel abrufen.

Kopieren eines Schlüssels und einer URL

Für REST-Aufrufe sind der Suchdienstendpunkt sowie ein API-Schlüssel für jede Anforderung erforderlich. Diese Werte erhalten Sie im Azure-Portal.

  1. Melden Sie sich im Azure-Portal an, navigieren Sie zur Seite Übersicht, und kopieren Sie die URL. Ein Beispiel für einen Endpunkt ist https://mydemo.search.windows.net.

  2. Kopieren Sie unter Einstellungen>Schlüssel einen Administratorschlüssel. Mit einem Administratorschlüssel können Sie Objekte hinzufügen, ändern und löschen. Es gibt zwei austauschbare Administratorschlüssel. Kopieren Sie einen der beiden Schlüssel.

    Screenshot der URL und API-Schlüssel im Azure-Portal

Ein gültiger API-Schlüssel stellt anforderungsbasiert eine Vertrauensstellung her zwischen der Anwendung, die die Anforderung sendet, und dem Dienst, der sie verarbeitet.

Erstellen von Datenquellen, Skillset, Index und Indexer

Erstellen Sie in diesem Abschnitt einen Workflow mit dem Typ "Workflow", den Sie in diesem Lernprogramm beheben können.

  1. Starten Sie Visual Studio Code, und öffnen Sie die debug-sessions.rest Datei.

  2. Stellen Sie die folgenden Variablen bereit: Suchdienst-URL, Administrator-API-Schlüssel der Suchdienste, Speicherverbindungszeichenfolge und der Name des BLOB-Containers, der die PDF-Dateien speichert.

  3. Senden Sie jede Anforderung wiederum. Das Erstellen des Indexers dauert mehrere Minuten, bis der Vorgang abgeschlossen ist.

  4. Schließen Sie die -Datei.

Überprüfen der Ergebnisse im Portal

Der Beispielcode erstellt als Folge der Probleme, die bei der Skillsetausführung aufgetreten sind, absichtlich einen fehlerhaften Index. Das Problem im Index sind fehlende Daten.

  1. Wählen Sie im Azure-Portal auf der Seite Übersicht des Suchdiensts die Registerkarte Indizes aus.

  2. Wählen Sie clinical-trials aus.

  3. Geben Sie diese JSON-Abfragezeichenfolge in die JSON-Ansicht des Such-Explorers ein. Es werden Felder für bestimmte Dokumente (durch das eindeutige metadata_storage_path Feld identifiziert) zurückgegeben.

    "select": "metadata_storage_path, organizations, locations",
"count"=true`

  4. Abfrage ausführen. Leere Werte für organizations und locations.

    Diese Felder sollten durch den Skill „Entitätserkennung“ des Skillsets aufgefüllt worden sein, der zum Erkennen von Organisationen und Standorten überall im Blobinhalt verwendet wurde. In der nächsten Übung debuggen Sie das Skillset, um zu ermitteln, welche Fehler aufgetreten sind.

Fehler und Warnungen können auch im Azure-Portal untersucht werden.

  1. Öffnen Sie die Registerkarte Indexer, und wählen Sie clinical-trials-idxr aus.

    Beachten Sie, dass der Indexerauftrag insgesamt zwar erfolgreich ausgeführt wurde, aber Warnungen ausgegeben wurden.

  2. Wählen Sie Erfolg aus, um die Warnungen anzuzeigen (liegen überwiegend Fehler vor, würde der Detaillink Fehler lauten). Sie sehen eine lange Liste aller vom Indexer ausgegebenen Warnungen.

    Screenshot: Anzeigen von Warnungen

Starten Sie Ihre Debugsitzung.

  1. Wählen Sie im linken Navigationsbereich des Suchdiensts unter Suchverwaltung die Option Debugsitzungen aus.

  2. Wählen Sie + Debugsitzung hinzufügen aus.

  3. Geben Sie der Sitzung einen Namen.

  4. Verbinden Sie die Sitzung mit Ihrem Speicherkonto. Erstellen Sie einen Container mit dem Namen „Debugsitzungen“. Sie können diesen Container wiederholt verwenden, um alle Ihre Debugsitzungsdaten zu speichern.

  5. Wenn Sie eine vertrauenswürdige Verbindung zwischen Suche und Speicher konfiguriert haben, wählen Sie die benutzerseitig verwaltete Identität oder die Systemidentität für die Verbindung aus. Andernfalls verwenden Sie den Standardwert (Keine).

  6. Geben Sie in der Indexervorlage den Indexernamen an. Der Indexer verweist auf die Datenquelle, das Skillset und den Index.

  7. Akzeptieren Sie die Standarddokumentauswahl für das erste Dokument in der Sammlung. Eine Debugsitzung funktioniert nur mit einem einzelnen Dokument. Sie können auswählen, für welches Dokument das Debugging durchgeführt werden soll, oder nur das erste verwenden.

  8. Speichern Sie die Sitzung. Durch das Speichern der Sitzung wird die Anreicherungspipeline gestartet, wie durch das Skillset des ausgewählten Dokuments definiert.

    Screenshot: Konfigurieren einer neuen Debugsitzung

  9. Wenn die Initialisierung der Debugsitzung beendet ist, wird die Sitzung standardmäßig auf die Registerkarte KI-Anreicherungen gesetzt, wobei der Skillgraph hervorgehoben wird. Der Skillgraph bietet eine visuelle Hierarchie des Skillsets und seiner Ausführungsreihenfolge nacheinander und parallel.

    Screenshot: Visueller Editor für Debugsitzungen

Ermitteln von Problemen mit dem Skillset

Alle vom Indexer gemeldeten Probleme finden Sie auf der danebenliegenden Registerkarte Fehler/Warnungen.

Screenshot: Registerkarte „Fehler und Warnungen“

Beachten Sie, dass die Registerkarte Fehler/Warnungen eine viel kleinere Liste als die zuvor angezeigte enthält, da diese Liste nur die Details zu den Fehlern für ein einzelnes Dokument aufführt. Wie bei der Liste, die der Indexer anzeigt, können Sie auf eine Warnmeldung klicken und die Details zu dieser Warnung sehen.

Wählen Sie Fehler/Warnungen aus, um die Benachrichtigungen zu überprüfen. Es sollten vier zu sehen sein:

  • „Could not execute skill because one or more skill inputs were invalid. Required skill input is missing. Name: 'text', Source: '/document/content'.“ (Skill konnte nicht ausgeführt werden, da mindestens eine Skilleingabe ungültig war. Eine erforderliche Skilleingabe fehlt. Name: 'text', Quelle: '/document/content'.)

  • „Could not map output field 'locations' to search index. Check the 'outputFieldMappings' property of your indexer. Missing value '/document/merged_content/locations'.“ (Das Ausgabefeld 'locations' konnte dem Suchindex nicht zugeordnet werden. Überprüfen Sie die Eigenschaft 'outputFieldMappings' des Indexers. Fehlender Wert für '/document/merged_content/locations'.)

  • „Could not map output field 'organizations' to search index. Check the 'outputFieldMappings' property of your indexer. Fehlender Wert für '/document/merged_content/organizations'.“ (Das Ausgabefeld 'organizations' konnte dem Suchindex nicht zugeordnet werden. Überprüfen Sie die Eigenschaft 'outputFieldMappings' des Indexers. Fehlender Wert für '/document/merged_content/organizations'.)

  • „Skill executed but may have unexpected results because one or more skill inputs were invalid. Optional skill input is missing. Name: 'languageCode', Source: '/document/languageCode'. Expression language parsing issues: Missing value '/document/languageCode'.“ (Der Skill wurde ausgeführt, hat jedoch unter Umständen unerwartete Ergebnisse, da mindestens eine Skilleingabe ungültig war. Eine optionale Skilleingabe fehlt. Name: 'languageCode', Quelle: '/document/languageCode'. Probleme bei der Analyse der Ausdruckssprache. Fehlender Wert für '/document/languageCode'.)

Viele Skills verfügen über den Parameter „languageCode“. Wenn Sie den Vorgang überprüfen, sehen Sie, dass diese Sprachcodeeingabe in EntityRecognitionSkill.#1 fehlt. Dabei handelt es sich um denselben Skill für die Entitätserkennung, bei der Probleme mit der Ausgabe von „locations“ und „organizations“ auftreten.

Da alle vier Benachrichtigungen zu diesem Skill gehören, besteht der nächste Schritt im Debuggen dieses Skills. Beginnen Sie nach Möglichkeit mit der Behebung von Eingabeproblemen, und fahren Sie dann mit Ausgabeproblemen fort.

Korrigieren fehlender Skilleingabewerte

Auf der Registerkarte Fehler/Warnungen fehlen zwei Eingaben für einen Vorgang mit der Bezeichnung EntityRecognitionSkill.#1. Im Detail des ersten Fehlers wird erläutert, dass eine erforderliche Eingabe für „text“ fehlt. Im zweiten wird ein Problem mit dem Eingabewert „/document/languageCode“ angegeben.

  1. Wählen Sie unter KI-Anreicherungen>Skillgraph den Skill mit der Bezeichnung #1 aus, um seine Details im rechten Bereich anzuzeigen.

  2. Wählen Sie die Registerkarte Ausführungen aus, und suchen Sie die Eingabe für „text“.

  3. Wählen Sie das Symbol </> aus, um die Ausdrucksauswertung zu öffnen. Das angezeigte Ergebnis für diese Eingabe sieht nicht wie eine Texteingabe aus. Es sieht wie eine Reihe Zeilenvorschubzeichen \n \n\n\n\n anstelle von Text aus. Das Fehlen von Text bedeutet, dass keine Entitäten identifiziert werden können, sodass dieses Dokument entweder die Voraussetzungen des Skills nicht erfüllt, oder stattdessen eine andere Eingabe verwendet werden sollte.

    Screenshot: Ausdrucksauswertung für die Texteingabe

  4. Wechseln Sie im linken Bereich zu Angereicherte Datenstruktur, und scrollen Sie in der Liste der Anreicherungsknoten für dieses Dokument nach unten. Beachten Sie, dass \n \n\n\n\n für „content“ keine Ursprungsquelle, aber ein anderer Wert für „merged_content“ eine OCR-Ausgabe hat. Obwohl es keinen Hinweis gibt, scheint der Inhalt dieser PDF-Datei eine JPEG-Datei zu sein, wie der extrahierte und verarbeitete Text in „merged_content“ zeigt.

    Screenshot der Registerkarte „Angereicherte Datenstruktur“

  5. Wählen Sie im rechten Bereich Ausführungen für den Skill „#1“ aus, und öffnen Sie die Ausdrucksauswertung </> für die Eingabe „text“.

  6. Ändern Sie den Ausdruck von /document/content in /document/merged_content, und wählen Sie dann Auswerten aus. Beachten Sie, dass der Inhalt jetzt ein Textblock und daher für die Entitätserkennung umsetzbar ist.

    Screenshot: Ausdrucksauswertung für feste merged_content-Eingabe

  7. Wechseln Sie zu Skill-JSON-Editor.

  8. Ändern Sie in Zeile 16 unter „Eingaben“ /document/content in /document/merged_content.

     {
   "name": "text",
   "source": "/document/merged_content"
 },

  9. Wählen Sie im rechten Skilldetailsbereich Speichern aus.

    Screenshot: Befehl „Speichern“ für Skillset-Details

  10. Wählen Sie im Sitzungsfenstermenü Ausführen aus. Dadurch wird eine weitere Ausführung des Skillsets unter Verwendung des Dokuments gestartet.

  11. Nachdem die Ausführung der Debugsitzung abgeschlossen ist, sehen Sie auf der Registerkarte „Fehler/Warnungen“, dass der Fehler für die Texteingabe nicht mehr angezeigt wird, die anderen Warnungen jedoch erhalten bleiben. Im nächsten Schritt wird die Warnung zu „languageCode“ behandelt.

    Screenshot: Aktualisierte Fehler und Warnungen

  12. Wählen Sie die Registerkarte Ausführungen aus, und suchen Sie die Eingabe für „languageCode“.

  13. Wählen Sie das Symbol </> aus, um die Ausdrucksauswertung zu öffnen. Beachten Sie die Bestätigung, dass die Eigenschaft „languageCode“ keine gültige Eingabe ist.

    Screenshot: Ausdrucksauswertung für die Spracheingabe

Es gibt zwei Möglichkeiten, diesen Fehler zu untersuchen. Die erste besteht darin, zu untersuchen, woher die Eingabe stammt. Welche Qualifikation in der Hierarchie sollte dieses Ergebnis erzeugen? Auf der Registerkarte „Ausführungen“ sollte die Quelle der Eingabe im Detailbereich der Qualifikation angezeigt werden. Wenn es keine Quelle gibt, weist dies auf einen Fehler bei der Feldzuordnung hin.

  1. Überprüfen Sie die EINGABEN auf der Registerkarte Ausführungen, und suchen Sie nach „languageCode“. Es ist keine Quelle für diese Eingabe angegeben.

  2. Wechseln Sie in den linken Fensterbereich zu Angereicherte Datenstruktur. Scrollen Sie in der Liste der Anreicherungsknoten für dieses Dokument nach unten. Beachten Sie, dass es keinen Knoten „languageCode“ gibt, aber einen für „Sprache“. Es liegt also einen Tippfehler in den Skilleinstellungen vor.

    Screenshot: Angereicherte Datenstruktur mit hervorgehobener Sprache

  3. Öffnen Sie noch in der Angereicherten Datenstruktur die Ausdrucksauswertung </> für den Knoten „language“, und kopieren Sie den Ausdruck /document/language.

  4. Wählen Sie im rechten Bereich Skilleinstellungen für den Skill Nr. 1 aus, und öffnen Sie die Ausdrucksauswertung </> für die Eingabe „languageCode“.

  5. Fügen Sie den neuen Wert /document/language in das Feld Ausdruck ein, und klicken Sie auf Auswerten. Es sollte die korrekte Eingabe „en“ angezeigt werden.

  6. Wählen Sie Speichern aus.

  7. Klicken Sie auf Run (Ausführen).

Nachdem die Ausführung der Debugsitzung abgeschlossen ist, sehen Sie auf der Registerkarte „Fehler/Warnungen“, dass keine Eingabewarnungen mehr angezeigt werden. Es verbleiben jetzt nur noch die beiden Warnungen zu Ausgabefeldern für Organisationen und Standorte.

Korrigieren fehlender Qualifikationsausgabewerte

Die Meldungen fordern zur Überprüfung der Eigenschaft „outputFieldMappings“ Ihres Indexers auf, also beginnen wir dort.

  1. Wechseln Sie zu Skillgraph, und wählen Sie „Ausgabefeldzuordnungen“ aus. Die Zuordnungen sind richtig, aber normalerweise überprüfen Sie die Indexdefinition, um sicherzustellen, dass Felder für „locations“ und „organizations“ vorhanden sind.

    Screenshot: Ausgabefeldzuordnungen

  2. Wenn kein Problem mit dem Index vorliegt, ist der nächste Schritt das Überprüfen der Skillausgabe. Wählen Sie wie zuvor die Angereicherte Datenstruktur aus, und scrollen Sie durch die Knoten, um „locations“ und „organizations“ zu finden. Beachten Sie, dass das übergeordnete Element „content“ anstelle von „merged_content“ ist. Der Kontext ist falsch.

    Screenshot: Angereicherte Datenstruktur mit falschem Kontext

  3. Wechseln Sie zurück zu Skillgraph, und wählen Sie den Skill für die Entitätserkennung aus.

  4. Navigieren Sie zu den Skilleinstellungen, um nach „Kontext“ zu suchen.

    Screenshot: Kontextkorrektur in Skilleinstellung

  5. Doppelklicken Sie auf die Einstellung für „Kontext“, und bearbeiten Sie sie so, dass „/document/merged_content“ gelesen wird.

  6. Wählen Sie Speichern aus.

  7. Klicken Sie auf Run (Ausführen).

Alle Fehler wurden behoben.

Änderungen am Skillset committen

Beim Initiieren der Debugsitzung wurde vom Suchdienst eine Kopie des Skillsets erstellt. Dieser Schritt wurde ausgeführt, um das ursprüngliche Skillset für Ihren Suchdienst zu schützen. Nachdem Sie das Debugging Ihres Skillsets nun abgeschlossen haben, können Sie die Korrekturen committen (und das ursprüngliche Skillset überschreiben).

Wenn Sie die Änderungen noch nicht committen möchten, können Sie alternativ die Debugsitzung speichern und später erneut öffnen.

  1. Wählen Sie im Hauptmenü der Debugsitzungen Änderungen committen aus.

  2. Wählen Sie OK aus, um zu bestätigen, dass Sie Ihr Skillset aktualisieren möchten.

  3. Schließen Sie die Debugsitzung, und öffnen Sie Indexer im linken Navigationsbereich.

  4. Wählen Sie „clinical-trials-idxr“ aus.

  5. Klicken Sie auf Zurücksetzen.

  6. Klicken Sie auf Run (Ausführen).

  7. Wählen Sie Aktualisieren aus, um den Status der Befehle zum Zurücksetzen und Ausführen anzuzeigen.

Wenn die Ausführung des Indexers beendet ist, sollte auf der Registerkarte Ausführungshistorie ein grünes Häkchen und das Wort „Erfolg“ neben dem Zeitstempel der letzten Ausführung angezeigt werden. So stellen Sie sicher, dass die Änderungen übernommen wurden:

  1. Öffnen Sie im linken Navigationsbereich Indizes.

  2. Wählen Sie den Index „clinical-trials“ aus, und geben Sie auf der Registerkarte „Suchexplorer“ die Abfragezeichenfolge $select=metadata_storage_path, organizations, locations&$count=true ein, um Felder für bestimmte Dokumente (identifiziert durch das eindeutige Feld metadata_storage_path) zurückzugeben.

  3. Klicken Sie auf Suchen.

In den Ergebnissen sollten Sie nun erkennen, dass Organisationen und Standorte mit den erwarteten Werten aufgefüllt wurden.

Bereinigen von Ressourcen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, sollten Sie sich am Ende eines Projekts überlegen, ob Sie die erstellten Ressourcen noch benötigen. Ressourcen, die weiterhin ausgeführt werden, können Sie Geld kosten. Sie können entweder einzelne Ressourcen oder aber die Ressourcengruppe löschen, um den gesamten Ressourcensatz zu entfernen.

Ressourcen können im Portal über den Link Alle Ressourcen oder Ressourcengruppen im linken Navigationsbereich gesucht und verwaltet werden.

Ein kostenloser Dienst ist auf drei Indizes, Indexer und Datenquellen beschränkt. Sie können einzelne Elemente über das Portal löschen, um unter dem Limit zu bleiben.

Nächste Schritte

In diesem Tutorial wurden verschiedene Aspekte der Definition und Verarbeitung von Skillsets angesprochen. Weitere Informationen zu Konzepten und Workflows finden Sie in den folgenden Artikeln: