Debuggen eines Azure KI Search-Skillsets im Azure-Portal

Starten Sie eine portalbasierte Debugsitzung, um Fehler zu identifizieren und zu beheben, Änderungen zu überprüfen und dann an ein vorhandenes Skillset in Ihrem Azure KI-Suchdienst zu pushen.

Eine Debugsitzung ist eine zwischengespeicherte Indexer- und Skillsetausführung, die auf ein einzelnes Dokument festgelegt ist und mit der Sie Ihre Skillsetänderungen interaktiv bearbeiten und testen können. Wenn Sie mit dem Debuggen fertig sind, können Sie Ihre Änderungen im Skillset speichern.

Hintergrundinformationen zur Funktionsweise einer Debugsitzung finden Sie unter Debugsitzungen in der Azure KI-Suche. Informationen zur praktischen Verwendung eines Debugworkflows mit einem Beispieldokument finden Sie unter Tutorial: Debuggen eines Skillsets mithilfe von Debugsitzungen.

Voraussetzungen

• Ein Azure KI Search-Dienst. Es wird empfohlen, eine systemseitig zugewiesene verwaltete Identität und Rollenzuweisungen zu verwenden, mit denen Azure KI-Suche in Azure Storage schreiben und die im Skillset verwendeten Azure KI-Ressourcen aufrufen kann.

• Ein Azure Storage-Konto zum Speichern des Sitzungszustands

• Eine vorhandene Anreicherungspipeline, einschließlich einer Datenquelle, eines Skillsets, eines Indexers und eines Indexes.

• Für Rollenzuweisungen muss die Suchdienstidentität Folgendes aufweisen:

  • Berechtigungen für Cognitive Services-Benutzer für das Azure KI-Konto mit mehreren Diensten, das vom Skillset verwendet wird

  • Berechtigungen für Mitwirkende an Speicherblobdaten in Azure Storage Andernfalls planen Sie die Verwendung einer Verbindungszeichenfolge mit vollem Zugriff für die Debugsitzungsverbindung zu Azure Storage.

• Wenn sich das Azure Storage-Konto hinter einer Firewall befindet, konfigurieren Sie diese so, dass der Zugriff auf den Suchdienst zugelassen ist.

Begrenzungen

Debugsitzungen funktionieren mit allen allgemein verfügbaren Indexerdatenquellen und den meisten Vorschaudatenquellen, mit den folgenden Ausnahmen:

• SharePoint Online-Indexer

• Azure Cosmos DB for MongoDB-Indexer

• Azure Cosmos DB for NoSQL: Wenn während der Indizierung bei einer Zeile ein Fehler auftritt und keine entsprechenden Metadaten vorhanden sind, wird in der Debugsitzung möglicherweise nicht die richtige Zeile ausgewählt.

• SQL-API von Azure Cosmos DB: Wenn eine partitionierte Sammlung vorher nicht partitioniert war, wird das Dokument in der Debugsitzung nicht gefunden.

• Für benutzerdefinierte Skills wird eine benutzerseitig zugewiesene verwaltete Identität für eine Debugsitzungsverbindung mit Azure Storage nicht unterstützt. Wie in den Voraussetzungen angegeben, können Sie eine systemseitig verwaltete Identität verwenden oder eine Vollzugriffsverbindungszeichenfolge angeben, die einen Schlüssel enthält. Weitere Informationen finden Sie unter Verbinden eines Suchdiensts für andere Azure-Ressourcen mithilfe einer verwalteten Identität.

Erstellen einer Debugsitzung

1. Melden Sie sich beim Azure-Portal an, und suchen Sie den Suchdienst.

2. Wählen Sie im linken Menü Suchverwaltung>Debugsitzungen aus.

3. Wählen Sie in der Aktionsleiste oben die Option Debugsitzung hinzufügen aus.

   

4. Geben Sie unter Name der Debugsitzung einen Namen an, der Ihnen hilft, sich zu merken, um welches Skillset, welchen Indexer und welche Datenquelle es sich bei der Debugsitzung handelt.

5. Wählen Sie in der Indexervorlage den Indexer aus, der das Skillset steuert, das Sie debuggen möchten. Kopien von Indexer und Skillset werden zur Initialisierung der Sitzung verwendet.

6. Suchen Sie unter Speicherkonto ein universelles Speicherkonto für die Zwischenspeicherung der Debugsitzung.

7. Wählen Sie Mit verwalteter Identität authentifizieren aus, wenn Sie zuvor der systemseitig verwalteten Identität des Suchdienstes Berechtigungen für Mitwirkende an Speicherblobdaten zugewiesen haben.

8. Wählen Sie Speichern.

   • Azure KI-Suche erstellt einen Blobcontainer in Azure Storage mit dem Namen ms-az-cognitive-search-debugsession.
   • Innerhalb dieses Containers wird ein Ordner mit dem Namen erstellt, den Sie für den Sitzungsnamen angegeben haben.
   • Damit wird die Debugsitzung gestartet.

9. Eine Debugsitzung wird auf der Einstellungsseite geöffnet. Sie können Änderungen an der anfänglichen Konfiguration vornehmen und alle Standardwerte überschreiben.

10. In Speicherverbindungszeichenfolge können Sie die Verbindungszeichenfolge angeben oder das Speicherkonto ändern.

11. Wählen Sie unter Zu debuggendes Dokument das erste Dokument im Index oder ein bestimmtes Dokument aus. Wenn Sie ein bestimmtes Dokument auswählen, werden Sie, je nach Datenquelle, nach einer URI oder einer Zeilen-ID gefragt.

    Wenn Ihr spezifisches Dokument ein Blob ist, geben Sie die Blob-URI an. Sie finden die URI auf der Blobeigenschaftsseite im Portal.

    

12. Optional können Sie unter Indexereinstellungen alle Ausführungseinstellungen für den Indexer festlegen, die zum Erstellen der Sitzung verwendet werden. Die Einstellungen sollten die vom tatsächlichen Indexer verwendeten Einstellungen widerspiegeln. Alle Indexeroptionen, die Sie in einer Debugsitzung angeben, haben keine Auswirkungen auf den Indexer selbst.

13. Wenn Sie Änderungen vorgenommen haben, wählen Sie Sitzung speichern aus, gefolgt von Ausführen.

Die Debugsitzung beginnt mit der Ausführung des Indexers und Skillsets für das ausgewählte Dokument. Der Inhalt und die Metadaten des Dokuments werden angezeigt und sind in der Sitzung verfügbar.

Eine Debugsitzung kann während der Ausführung mithilfe der Schaltfläche Abbrechen abgebrochen werden. Wenn Sie auf die Schaltfläche Abbrechen klicken, sollten Sie in der Lage sein, Teilergebnisse zu analysieren.

Es ist zu erwarten, dass die Ausführung einer Debugsitzung länger dauert als die des Indexers, da sie eine zusätzliche Verarbeitung durchläuft.

Beginnen mit Fehlern und Warnungen

Der Indexerausführungsverlauf im Portal enthält die vollständige Fehler- und Warnungsliste für alle Dokumente. In einer Debugsitzung sind die Fehler und Warnungen auf ein Dokument beschränkt. Sie können diese Liste durcharbeiten, Änderungen vornehmen und dann zur Liste zurückkehren, um zu überprüfen, ob die Probleme behoben wurden.

Beachten Sie, dass eine Debugsitzung auf einem Dokument aus dem gesamten Index basiert. Wenn eine Eingabe oder Ausgabe falsch aussieht, könnte das Problem für dieses Dokument spezifisch sein. Sie können ein anderes Dokument auswählen, um zu überprüfen, ob die Fehler und Warnungen weit verbreitet oder für ein einzelnes Dokument spezifisch sind.

Wählen Sie Fehler oder Warnungen für eine Liste von Problemen aus.

Als bewährte Methode sollten Sie Probleme mit Eingaben beheben, bevor Sie mit den Ausgaben fortfahren.

Um nachzuweisen, ob eine Änderung einen Fehler behebt, führen Sie die folgenden Schritte aus:

1. Klicken Sie im Detailbereich für den Skill auf Speichern, um Ihre Änderungen zu speichern.

2. Klicken Sie im Sitzungsfenster auf Ausführen, um die Skillsetausführung mithilfe der geänderten Definition aufzurufen.

3. Wechseln Sie zurück zu Fehler oder Warnungen, um herauszufinden, ob die Anzahl reduziert wurde.

Anzeigen von erweiterten oder generierten Inhalten

KI-Anreicherungspipelines extrahieren Informationen und Strukturen aus Quelldokumenten oder leiten diese ab, um ein angereichertes Dokument zu erstellen. Ein angereichertes Dokument wird zuerst während der Dokumententschlüsselung erstellt und mit einem Stammknoten (/document) plus Knoten für alle Inhalte aufgefüllt, die direkt aus der Datenquelle heraufgestuft werden, etwa einem Dokumentschlüssel und Metadaten. Weitere Knoten werden während der Skillausführung durch Skills erstellt, wobei jede Skillausgabe der Anreicherungsstruktur einen neuen Knoten hinzufügt.

Alle von einem Skillset erstellten oder verwendeten Inhalte werden in der Ausdrucksauswertung angezeigt. Sie können mit der Maus auf die Links zeigen, um jeden Eingabe- oder Ausgabewert in der angereicherten Dokumentstruktur anzuzeigen. Führen Sie die folgenden Schritte aus, um die Eingabe oder Ausgabe der einzelnen Skills anzuzeigen:

1. Erweitern Sie in einer Debugsitzung den blauen Pfeil, um kontextbezogene Details anzuzeigen. Standardmäßig ist das Detail die angereicherte Dokumentdatenstruktur. Wenn Sie jedoch einen Skill oder eine Zuordnung auswählen, handelt es sich beim Detail um dieses Objekt.

   

2. Wählen Sie einen Skill aus.

   

3. Folgen Sie den Links, um mehr über die Verarbeitung von Skills zu erfahren. Der folgende Screenshot zeigt zum Beispiel die Ausgabe der ersten Iteration des Skills Textaufteilung.

   

Überprüfen Sie Indexzuordnungen

Wenn Skills eine Ausgabe erzeugen, der Suchindex jedoch leer ist, überprüfen Sie die Feldzuordnungen. Feldzuordnungen geben an, wie Inhalt aus der Pipeline in einen Suchindex bewegt wird.

Wählen Sie eine der Zuordnungsoptionen aus, und erweitern Sie die Detailansicht, um Quell- und Zieldefinitionen zu überprüfen.

• Projektionszuordnungen finden sich in Skillsets, die eine integrierte Vektorisierung bieten, z. B. die Skills, die vom Assistenten zum Importieren und Vektorisieren von Daten erstellt wurden. Diese Zuordnungen legen fest, wie übergeordnete und untergeordnete Felder (in Blöcken) zugeordnet werden und ob ein sekundärer Index nur für den segmentierten (in Blöcke aufgeteilten) Inhalt erstellt wird.

• Ausgabefeldzuordnungen finden sich in Indexern und werden verwendet, wenn Skillsets integrierte oder benutzerdefinierte Skills aufrufen. Diese Zuordnungen werden verwendet, um den Datenpfad von einem Knoten in der Anreicherungsstruktur auf ein Feld im Suchindex festzulegen. Weitere Informationen zu Pfaden finden Sie unter Pfadsyntax von Anreicherungsknoten.

• Feldzuordnungen finden sich in Indexerdefinitionen und legen den Datenpfad aus rohem Inhalt in der Datenquelle und einem Feld im Index fest. Sie können auch Feldzuordnungen verwenden, um Codierungs- und Decodierungsschritte hinzuzufügen.

Dieses Beispiel zeigt die Details für eine Projektionszuordnung. Sie können den JSON-Code bearbeiten, um alle Zuordnungsprobleme zu beheben.

Bearbeiten von Skilldefinitionen

Wenn die Feldzuordnungen richtig sind, überprüfen Sie die einzelnen Skills auf Konfiguration und Inhalt. Wenn ein Skill keine Ausgabe erzeugt, fehlt möglicherweise eine Eigenschaft oder ein Parameter, die durch Fehler- und Validierungsmeldungen ermittelt werden können.

Andere Probleme wie ein ungültiger Kontext oder ein ungültiger Eingabeausdruck können schwieriger zu beheben sein, da der Fehler Sie darüber informiert, was das Problem ist, aber nicht, wie Sie es beheben können. Hilfe zur Kontext- und Eingabesyntax finden Sie unter Verweisen auf Anmerkungen in einem Azure KI-Suche-Skillset. Informationen zu einzelnen Meldungen finden Sie unter Beheben von häufigen Fehler und Warnungen bei Suchindexern in Azure Cognitive Search.

In den folgenden Schritten wird gezeigt, wie Sie Informationen zu einem Skill abrufen.

1. Wählen Sie einen Skill auf der Arbeitsoberfläche aus. Auf der rechten Seite wird der Bereich „Skilldetails“ geöffnet.

2. Bearbeiten Sie eine Skilldefinition mithilfe von Skilleinstellungen. Sie können den JSON-Code direkt bearbeiten.

3. Überprüfen Sie die Pfadsyntax zum Verweisen auf Knoten in einer Anreicherungsstruktur. Im Folgenden finden Sie einige der gängigsten Eingabepfade:

   • /document/content für Textblöcke. Dieser Knoten wird über die Inhaltseigenschaft des Blobs aufgefüllt.
   • /document/merged_content für Textblöcke in Skillsets, die den Skill für die Textzusammenführung enthalten
   • /document/normalized_images/* für Text, der erkannt oder von Bildern abgeleitet wird

Lokales Debuggen eines benutzerdefinierten Skills

Das Debuggen benutzerdefinierter Skills kann schwieriger sein, da der Code extern ausgeführt wird, sodass die Debugsitzung nicht verwendet werden kann, um sie zu debuggen. In diesem Abschnitt wird beschrieben, wie Sie Ihren benutzerdefinierten Web-API-Skill, Debugsitzung, Visual Studio Code und ngrok oder Tunnelmole lokal debuggen. Diese Technik kann für benutzerdefinierte Skills verwendet werden, die in Azure Functions oder einem anderen lokal ausgeführten Webframework ausgeführt werden (z. B. FastAPI).

Abrufen einer öffentlichen URL

In diesem Abschnitt werden zwei Ansätze zum Abrufen einer öffentlichen URL zu einem benutzerdefinierten Skill beschrieben.

Verwenden von Tunnelmole

Tunnelmole ist ein Open-Source-Tunnelingtool, mit dem Sie eine öffentliche URL erstellen können, die Anforderungen an Ihren lokalen Computer durch einen Tunnel weiterleitet.

1. Installieren von Tunnelmole:

   • npm: npm install -g tunnelmole
   • Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows: Installation mithilfe von npm. Oder wenn Sie NodeJS nicht installiert haben, laden Sie die vorkompilierte EXE-Datei für Windows herunter und legen Sie sie irgendwo in Ihrem PATH ab.

2. Führen Sie diesen Befehl aus, um einen neuen Tunnel zu erstellen:

   tmole 7071
   

   Die Antwort sollte in etwa wie folgt aussehen:

   http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   

   Im vorherigen Beispiel leitet https://m5hdpb-ip-49-183-170-144.tunnelmole.net an Port 7071 auf Ihrem lokalen Computer weiter. Dies ist der Standardport, an dem Azure-Funktionen verfügbar gemacht werden.

Verwenden von ngrok

ngrok ist eine beliebte, plattformübergreifende Closed-Source-Anwendung, die eine Tunneling- oder Weiterleitungs-URL erstellen kann, sodass Internetanforderungen Ihren lokalen Computer erreichen. Verwenden Sie ngrok, um Anforderungen aus einer Anreicherungspipeline in Ihrem Suchdienst an Ihren Computer weiterzuleiten, um das lokale Debuggen zu ermöglichen.

1. Installieren Sie ngrok.

2. Öffnen Sie ein Terminal, und wechseln Sie zum Ordner mit der ausführbaren ngrok-Datei.

3. Führen Sie ngrok mit dem folgenden Befehl aus, um einen neuen Tunnel zu erstellen:

   ngrok http 7071 
   

   Hinweis

   Standardmäßig wird Azure Functions an 7071 verfügbar gemacht. Andere Tools und Konfigurationen erfordern möglicherweise, dass Sie einen anderen Port bereitstellen.

4. Wenn ngrok gestartet wird, kopieren und speichern Sie die Weiterleitungs-URL für den nächsten Schritt. Die Weiterleitungs-URL wird zufällig generiert.

   

Konfigurieren im Azure-Portal

Sobald Sie eine öffentliche URL für Ihren benutzerdefinierten Skill haben, ändern Sie in einer Debugsitzung Ihren benutzerdefinierten Web-API-Skill-URI, um die Tunnelmole- oder ngrok-Weiterleitungs-URL aufzurufen. Bei Verwendung von Azure Function zum Ausführen des Skillsetcodes müssen Sie „/api/FunctionName“ anfügen.

Sie können die Skilldefinition im Abschnitt Skilleinstellungen des Bereichs Skilldetails bearbeiten.

Testen Ihres Codes

An diesem Punkt sollten neue Anforderungen aus Ihrer Debugsitzung jetzt an Ihre lokale Azure Function-Instanz gesendet werden. Sie können in Ihrem Visual Studio Code Breakpoints verwenden, um Ihren Code zu debuggen oder schrittweise auszuführen.

Nächste Schritte

Nachdem Sie sich nun mit dem Layout und den Funktionen des visuellen Editors für Debugsitzungen vertraut gemacht haben, schließen Sie das Tutorial ab, um praktische Erfahrung zu sammeln.