Debugging-Sitzungen in Azure AI Search

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

• 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 gesamte Sitzungsstatus wird in einem neuen Blob-Container gespeichert, der vom Azure AI Search-Dienst in einem von Ihnen bereitgestellten Azure Storage-Konto erstellt wird. Der Name des generierten Containers weist das Präfix ms-az-cognitive-search-debugsession auf. Das Präfix ist erforderlich, da die Wahrscheinlichkeit verringert wird, dass Sitzungsdaten versehentlich in einen anderen Container in Ihrem Konto exportiert werden.

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 die Daten, Qualifikationseingaben und -ausgaben sowie Feldzuordnungen analysiert werden. Wenn beim Indexer Konfigurationsprobleme auftreten, z. B. falsche Netzwerkeinrichtung, Berechtigungsbezogene Zugriffsfehler oder ähnliche, lesen Sie bitte die spezifische Fehlermeldung zusammen mit der bereitgestellten verknüpften Dokumentation. Informationen zur Problembehandlung finden Sie in den allgemeinen Indexerfehlern und Warnungen.

Debugsitzungen mit privater Konnektivität

Wenn Ihre KI-Anreicherungspipeline freigegebene private Links für den Zugriff auf Azure-Ressourcen verwendet, ist zusätzliche Konfiguration erforderlich, um sicherzustellen, dass Indexer- und Debugsitzungen ordnungsgemäß funktionieren. Dazu gehören Berechtigungen, vertrauenswürdiger Zugriff und Netzwerkeinrichtung.

• Wenn Sie verwaltete Identität verwenden, weisen Sie Ihrer Suchdienstidentität die erforderlichen Rollen zu, einschließlich Storage Blob Data Contributor, damit Debugsitzungen Sitzungsdaten in Ihr Speicherkonto schreiben können.
• Stellen Sie sicher, dass der Suchdienst Zugriff auf alle Ressourcen hat, auf die in der Skillset-Definition verwiesen wird, einschließlich aller in der Debugsitzung verwendeten Ressourcen.
• Aktivieren Sie in Ihrem Speicherkonto vertrauenswürdige Dienste , um den Zugriff von Azure AI Search zu ermöglichen.
• Legen Sie "executionEnvironment" = "private" die Eigenschaft in der Indexerdefinition fest, um sicherzustellen, dass der Indexer in einem privaten Kontext ausgeführt wird.
• Erstellen Sie einen freigegebenen privaten Link für jede Ressource, auf die vom Suchdienst zugegriffen wird, einschließlich: Ihrer Datenquelle, wenn sie für den Indizierungscache für die KI-Anreicherung und den Wissensspeicher konfiguriert ist, und alle anderen Ressourcen, die in Ihrem Skillset konfiguriert sind.
• Weitere Anleitungen zur Problembehandlung finden Sie in den allgemeinen Indexerfehlern und Warnungen.

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.