Debugging-Sitzungen in Azure KI-Suche

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.

"Debug Sessions ist ein visueller Editor, der mit einem bestehenden Skillset im Azure-Portal arbeitet und während der Dauer der Sitzung die Struktur und den Inhalt eines durch einen Indexer und ein Skillset angereicherten Dokuments offenlegt." Da Sie mit einem Livedokument arbeiten, ist die Sitzung interaktiv. Sie können Fehler identifizieren, Änderungen vornehmen, die Ausführung von Skills aufrufen und die Ergebnisse in Echtzeit überprüfen. Wenn Ihre Änderungen das Problem beheben, können Sie sie zu einem veröffentlichten Skillset hinzufügen, damit die Fehlerbehebungen global angewendet werden.

In diesem Artikel werden unterstützte Szenarien erläutert, und wie der Editor strukturiert ist. Die Registerkarten und Abschnitte des Editors stellen verschiedene Ebenen des Skillsets dar, sodass Sie die Skillsetstruktur, den Flow und den Inhalt untersuchen können, der zur Laufzeit generiert wird.

Unterstützte Szenarios

Verwenden Sie Debug-Sitzungen, um Probleme zu untersuchen und zu beheben.

• Integrierten Fähigkeiten, die für KI-Anreicherung verwendet werden, z. B. OCR, Bildanalyse, Entitätserkennung und Stichwortextraktion.

• Integrierten Fähigkeiten, die für integrierte Vektorisierung verwendet werden, mit Datenblöcken durch Textaufteilung und Vektorisierung durch eine Einbettungskompetenz.

• Benutzerdefinierte Fähigkeiten werden verwendet, um externe Verarbeitungen zu integrieren, die Sie bereitstellen.

Vergleichen Sie die folgenden Debugsitzungsbilder für die ersten beiden Szenarien. Für beide Szenarien zeigt die Fläche die Entwicklung der Fähigkeiten, die Inhalte auf dem Weg vom Quelldokument zum Suchindex erzeugen oder umwandeln. Der Fluss enthält Optionen für die Indexzuordnung, und Sie können anhand der Pfeile den Verarbeitungspfad verfolgen. Der Detailbereich rechts ist kontextsensitiv. Es zeigt eine Darstellung des durch die Pipeline erstellten angereicherten Dokuments oder die Details einer Fähigkeit oder Zuordnung.

Die erste Abbildung zeigt ein Muster für die angewendete KI-Anreicherung (keine Vektoren). Fähigkeiten können sequenziell oder parallel ausgeführt werden, wenn keine Abhängigkeiten vorhanden sind. Indexzuordnungen zeigen, wie angereicherte oder generierte Inhalte aus In-Memory-Datenstrukturen in Felder in einem Index übertragen werden. Ein angereichertes Dokument zeigt die Datenstruktur, die das Skillset erstellt.

Die zweite Abbildung zeigt ein typisches Muster für die integrierte Vektorisierung. Fähigkeiten für integrierte Vektorisierung umfassen in der Regel die Qualifikationen Textaufteilung und Einbettung. Eine Textaufteilungsqualifikation gliedert ein Dokument in Blöcke. Eine Einbettungsqualifikation ruft eine Einbettungs-API auf, um diese Blöcke zu vektorisieren. Dieses spezielle Skillset gliedert Inhalte in ein Array von „Seiten“. Bei der integrierten Vektorisierung steuern Projektionszuordnungen, wie Blöcke Feldern im Index zugeordnet werden.

Begrenzungen

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

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

• Datenquellen mit Verschlüsselung, die über vom Kunden verwaltete Schlüssel (CMK) aktiviert sind.

• Geteilte private Links werden nicht unterstützt. Wenn Ihr Suchdienst private Endpunktkonnektivität verwendet, um Datenquellen oder andere Ressourcen zu erreichen, können Debugsitzungen nicht auf diese Ressourcen zugreifen. Eine Problemumgehung finden Sie unter Debugsitzungen und privater Konnektivität.

• Derzeit ist die Möglichkeit zum Auswählen des zu debuggenden Dokuments nicht verfügbar. Diese Einschränkung ist nicht dauerhaft und sollte bald aufgehoben werden. Zu, aktuellen Zeitpunkt wird in Debugsitzungen das erste Dokument im Quelldatencontainer oder -ordner ausgewählt.

Funktionsweise einer Debugsitzung

Wenn Sie eine Sitzung starten, erstellt der Suchdienst eine Kopie des Skillsets, des Indexers und eine Datenquelle, die ein einzelnes Dokument enthält, das zum Testen des Skillsets verwendet wird. Der Azure KI-Suche Dienst speichert den gesamten Sitzungszustand in einem neuen Blobcontainer, den er in einem von Ihnen bereitgestellten Azure Storage Konto erstellt. Der generierte Containername weist ein Präfix von ms-az-cognitive-search-debugsession. Dieses Präfix reduziert die Wahrscheinlichkeit, dass Sitzungsdaten versehentlich in einen anderen Container in Ihrem Konto exportiert werden.

Wenn Sie die Speicherkontoverbindung mithilfe einer verwalteten Identität konfigurieren, weisen Sie die Storage Blob Data Contributor Rolle Ihrer Suchdienstidentität für das Speicherkonto zu. Aktivieren Sie in Ihrem Speicherkonto vertrauenswürdige Dienste, um Schreibzugriff von Azure KI-Suche zuzulassen.

Eine zwischengespeicherte Kopie des angereicherten Dokuments und Skillsets wird in den visuellen Editor geladen, sodass Sie den Inhalt und die Metadaten des angereicherten Dokuments überprüfen können. Dabei können Sie jeden Dokumentknoten überprüfen und jeden Aspekt der Skillsetdefinition bearbeiten. Alle Änderungen, die während der Sitzung vorgenommen werden, werden zwischengespeichert. Diese Änderungen wirken sich nur dann auf das veröffentlichte Skillset aus, wenn Sie sie committen. Durch das Committen von Änderungen wird das Produktionsskillset überschrieben.

Wenn die Anreicherungspipeline keine Fehler enthält, kann eine Debugsitzung verwendet werden, um ein Dokument inkrementell anzureichern sowie alle Änderungen vor dem Commit zu testen und zu validieren.

Debugsitzungen helfen dabei, die Ursache von Fehlern oder Warnungen zu identifizieren, indem Daten, Qualifikationseingaben und Ausgaben sowie Feldzuordnungen analysiert werden. Verwenden Sie den Bereich "Qualifikationsdetails", um zu prüfen, was jede Fähigkeit als Eingabe erhält und als Ausgabe erzeugt. Diese Inspektion hilft zu überprüfen, ob Qualifikationsdefinitionen, Ausdrücke und Feldzuordnungen korrekt gebildet sind. Wenn beim Indexer Konfigurationsprobleme auftreten, z. B. falsche Netzwerkeinrichtungs- oder Berechtigungszugriffsfehler, überprüfen Sie die spezifische Fehlermeldung und die verknüpfte Dokumentation. Anleitungen zur Problembehandlung finden Sie unter Allgemeine Indexerfehler und Warnungen.

Debugsitzungen und private Konnektivität

Debug-Sitzungen unterstützen keine geteilten privaten Links. Wenn Ihr Produktionssuchdienst private Endpunktkonnektivität für den Zugriff auf Datenquellen oder andere Ressourcen verwendet, können Debugsitzungen für diesen Dienst nicht ausgeführt werden.

Problemumgehung: Verwenden eines Testsuchdiensts

Um Ihr Skillset zu debuggen, erstellen Sie einen separaten Azure KI-Suche Dienst ohne private Konnektivitätseinschränkungen. Um Produktionsdaten und Schemadetails aus einer nicht privaten Umgebung herauszuhalten, erstellen Sie Ihre Testumgebung mit synthetischen Dokumenten:

• Erstellen Sie Testdokumente, die den Feldtypen und der Struktur Ihrer Produktionsdaten entsprechen, verwenden Sie jedoch generische Feldnamen (z. B. content, title, category) und Platzhalterwerte anstelle von echten Daten. Die Kompetenzlogik hängt von Inhaltstypen und Struktur ab, nicht von bestimmten Feldnamen.
• Kopieren Sie das Skillset-JSON von Ihrem Produktionsdienst. Wenn Skill-Eingaben auf Produktionsfeldnamen verweisen, aktualisieren Sie diese Verweise so, dass sie mit Ihren generischen Testfeldnamen übereinstimmen. Verwenden Sie Feldzuordnungen im Testindexer, um Feldnamen mit Skillset-Eingaben auszurichten.
• Konfigurieren Sie einen Indexer, der für die Testdatenquelle ausgeführt werden soll.

Führen Sie die Debugsitzung auf dem Testdienst aus, um Qualifikationseingaben und -ausgaben zu prüfen, Qualifikationsausdrücke und Feldzuordnungen zu überprüfen und Fehler zu identifizieren. Wenn Ihre Änderungen überprüft werden, stellen Sie die ursprünglichen Verweise auf den Namen des Produktionsfelds im JSON-Code des Skillsets wieder her, und wenden Sie sie wieder auf Ihren Produktionsdienst an.

Debugsitzungslayout

Der visuelle Editor ist in einer Oberfläche organisiert, die eine Abfolge von Operationen zeigt, beginnend mit der Dokumententschlüsselung, gefolgt von Fähigkeiten, Zuordnungen und einem Index.

Wählen Sie eine beliebige Fähigkeit oder Zuordnung aus. Daraufhin öffnet sich ein Fenster mit den relevanten Informationen auf der Seite.

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.

Skilldetailsbereich

Der Bereich Qualifikationsdetails enthält die folgenden Abschnitte:

• Iterationen: Zeigt, wie oft eine Fähigkeit ausgeführt wird. Sie können die Eingaben und Ausgaben einzeln überprüfen.
• Qualifikationseinstellungen: Anzeigen oder Bearbeiten der JSON-Qualifikationsdefinition.
• Fehler und Warnungen: Zeigt die für diese Qualifikation spezifischen Fehler oder Warnungen an.

Bereich „Angereicherte Datenstruktur“

Wenn Sie das blaue Pfeilsymbol zum Ein- und Ausblenden wählen, wird der Bereich Angereicherte Datenstruktur zur Seite geschoben. Es ist eine lesbare Darstellung dessen, was das angereicherte Dokument enthält. Vorherige Screenshots in diesem Artikel zeigen Beispiele für die anreicherte Datenstruktur.

Nächste Schritte

Nachdem Sie nun die Elemente von Debugsitzungen kennen, starten Sie Ihre erste Debugsitzung für ein vorhandenes Skillset.

Debuggen eines Azure Cognitive Search-Skillsets im Azure-Portal