Fouten opsporen in een Azure AI Search-vaardighedenset in Azure Portal

Start een foutopsporingssessie op basis van een portal om fouten te identificeren en op te lossen, wijzigingen te valideren en wijzigingen naar een bestaande vaardighedenset in uw Azure AI-Search-service te pushen.

Een foutopsporingssessie is een indexeerfunctie in de cache en de uitvoering van vaardighedensets, die zijn afgestemd op één document, die u kunt gebruiken om wijzigingen in vaardighedensets interactief te bewerken en te testen. Wanneer u klaar bent met foutopsporing, kunt u uw wijzigingen opslaan in de vaardighedenset.

Zie Foutopsporingssessies in Azure AI Search voor achtergrondinformatie over hoe een foutopsporingssessie werkt. Als u een foutopsporingswerkstroom wilt oefenen met een voorbeelddocument, raadpleegt u Zelfstudie: Fouten opsporen in sessies.

Vereisten

• Een Azure AI-Search-service. U wordt aangeraden een door het systeem toegewezen beheerde identiteit en roltoewijzingen te gebruiken waarmee Azure AI Search naar Azure Storage kan schrijven en de Azure AI-resources aanroept die in de vaardighedenset worden gebruikt.

• Een Azure Storage-account dat wordt gebruikt om de sessiestatus op te slaan.

• Een bestaande verrijkingspijplijn, waaronder een gegevensbron, een vaardighedenset, een indexeerfunctie en een index.

• Voor roltoewijzingen moet de identiteit van de zoekservice het volgende hebben:

  • Cognitive Services-gebruikersmachtigingen voor het Azure AI-account voor meerdere services dat wordt gebruikt door de vaardighedenset.

  • Inzendermachtigingen voor Opslagblobgegevens in Azure Storage. Anders plant u het gebruik van een volledige toegang verbindingsreeks voor de foutopsporingssessieverbinding met Azure Storage.

• Als het Azure Storage-account zich achter een firewall bevindt, configureert u dit om toegang tot de zoekservice toe te staan.

Beperkingen

Foutopsporingssessies werken met alle algemeen beschikbare gegevensbronnen voor indexeerfuncties en de meeste voorbeeldgegevensbronnen, met de volgende uitzonderingen:

• SharePoint Online-indexeerfunctie.

• Azure Cosmos DB voor MongoDB-indexeerfunctie.

• Als voor Azure Cosmos DB for NoSQL een rij mislukt tijdens de index en er geen bijbehorende metagegevens zijn, kiest de foutopsporingssessie mogelijk niet de juiste rij.

• Als een gepartitioneerde verzameling eerder niet is gepartitioneerd, vindt de foutopsporingssessie het document niet voor de SQL-API van Azure Cosmos DB.

• Voor aangepaste vaardigheden wordt een door de gebruiker toegewezen beheerde identiteit niet ondersteund voor een foutopsporingssessieverbinding met Azure Storage. Zoals vermeld in de vereisten, kunt u een door het systeem beheerde identiteit gebruiken of een volledige toegang opgeven verbindingsreeks die een sleutel bevat. Zie Een zoekservice verbinden met andere Azure-resources met behulp van een beheerde identiteit voor meer informatie.

Een foutopsporingssessie maken

1. Meld u aan bij Azure Portal en zoek uw zoekservice.

2. Selecteer in het menu links debug-sessies voor zoekbeheer>.

3. Selecteer op de actiebalk bovenaan de foutopsporingssessie toevoegen.

   

4. Geef in de naam van de foutopsporingssessie een naam op waarmee u weet over welke vaardighedenset, indexeerfunctie en gegevensbron de foutopsporingssessie gaat.

5. Selecteer in de indexeersjabloon de indexeerfunctie die de vaardighedenset aanstuurt die u wilt opsporen. Kopieën van zowel de indexeerfunctie als de vaardighedenset worden gebruikt om de sessie te initialiseren.

6. Zoek in het opslagaccount een opslagaccount voor algemeen gebruik voor het opslaan in de cache van de foutopsporingssessie.

7. Selecteer Verifiëren met beheerde identiteit als u eerder machtigingen voor inzender voor opslagblobgegevens hebt toegewezen aan de door het zoekservicesysteem beheerde identiteit.

8. Selecteer Opslaan.

   • Azure AI Search maakt een blobcontainer in Azure Storage met de naam ms-az-cognitive-search-debugsession.
   • In die container wordt een map gemaakt met de naam die u hebt opgegeven voor de sessienaam.
   • De foutopsporingssessie wordt gestart.

9. Er wordt een foutopsporingssessie geopend op de pagina Instellingen. U kunt wijzigingen aanbrengen in de eerste configuratie en eventuele standaardinstellingen overschrijven.

10. In Storage verbindingsreeks kunt u de verbindingsreeks opgeven of het opslagaccount wijzigen.

11. Kies in Document voor foutopsporing het eerste document in de index of selecteer een specifiek document. Als u een specifiek document selecteert, afhankelijk van de gegevensbron, wordt u gevraagd om een URI of een rij-id.

    Als uw specifieke document een blob is, geeft u de blob-URI op. U vindt de URI op de pagina met blobeigenschappen in de portal.

    

12. Geef desgewenst in de indexeerfunctie-instellingen eventuele uitvoeringsinstellingen voor de indexeerfunctie op die worden gebruikt om de sessie te maken. De instellingen moeten de instellingen spiegelen die worden gebruikt door de werkelijke indexeerfunctie. Alle indexeeropties die u opgeeft in een foutopsporingssessie hebben geen invloed op de indexeerfunctie zelf.

13. Als u wijzigingen hebt aangebracht, selecteert u De sessie Opslaan, gevolgd door Uitvoeren.

De foutopsporingssessie begint met het uitvoeren van de indexeerfunctie en vaardighedenset voor het geselecteerde document. De inhoud en metagegevens van het document zijn zichtbaar en beschikbaar in de sessie.

Een foutopsporingssessie kan worden geannuleerd terwijl deze wordt uitgevoerd met de knop Annuleren . Als u op de knop Annuleren klikt, kunt u gedeeltelijke resultaten analyseren.

Het duurt naar verwachting langer om een foutopsporingssessie uit te voeren dan de indexeerfunctie, omdat deze extra verwerking doorloopt.

Beginnen met fouten en waarschuwingen

De uitvoeringsgeschiedenis van de indexeerfunctie in de portal geeft u de volledige fout- en waarschuwingslijst voor alle documenten. In een foutopsporingssessie zijn de fouten en waarschuwingen beperkt tot één document. U kunt deze lijst doorlopen, uw wijzigingen aanbrengen en vervolgens terugkeren naar de lijst om te controleren of problemen zijn opgelost.

Houd er rekening mee dat een foutopsporingssessie is gebaseerd op één document uit de hele index. Als een invoer of uitvoer er verkeerd uitziet, kan het probleem specifiek zijn voor dat document. U kunt een ander document kiezen om te controleren of fouten en waarschuwingen pervasief of specifiek zijn voor één document.

Selecteer fouten of waarschuwingen voor een lijst met problemen.

Los als best practice problemen met invoer op voordat u verdergaat met uitvoer.

Voer de volgende stappen uit om te bewijzen of een wijziging een fout oplost:

1. Selecteer Opslaan in het detailvenster van de vaardigheid om uw wijzigingen te behouden.

2. Selecteer Uitvoeren in het sessievenster om de uitvoering van vaardighedensets aan te roepen met behulp van de gewijzigde definitie.

3. Ga terug naar fouten of waarschuwingenom te zien of het aantal is verminderd.

Verrijkte of gegenereerde inhoud weergeven

AI-verrijkingspijplijnen extraheren of informatie en structuur afleiden uit brondocumenten, waardoor er een verrijkt document in het proces wordt gemaakt. Een verrijkt document wordt eerst gemaakt tijdens het kraken van het document en gevuld met een hoofdknooppunt (/document), plus knooppunten voor inhoud die rechtstreeks uit de gegevensbron wordt opgehaald, zoals metagegevens en de documentsleutel. Er worden meer knooppunten gemaakt door vaardigheden tijdens het uitvoeren van vaardigheden, waarbij elke vaardigheidsuitvoer een nieuw knooppunt toevoegt aan de verrijkingsstructuur.

Alle inhoud die door een vaardighedenset is gemaakt of gebruikt, wordt weergegeven in de expressie-evaluator. U kunt de muisaanwijzer op de koppelingen bewegen om elke invoer- of uitvoerwaarde in de verrijkte documentstructuur weer te geven. Volg deze stappen om de invoer of uitvoer van elke vaardigheid weer te geven:

1. Vouw in een foutopsporingssessie de blauwe pijl uit om contextgevoelige details weer te geven. De details zijn standaard de verrijkte documentgegevensstructuur. Als u echter een vaardigheid of een toewijzing selecteert, gaat het om dat object.

   

2. Selecteer een vaardigheid.

   

3. Volg de koppelingen om verder in te zoomen op het verwerken van vaardigheden. In de volgende schermopname ziet u bijvoorbeeld de uitvoer van de eerste iteratie van de vaardigheid Tekst splitsen.

   

Indextoewijzingen controleren

Als vaardigheden uitvoer produceren, maar de zoekindex leeg is, controleert u de veldtoewijzingen. Veldtoewijzingen geven aan hoe inhoud uit de pijplijn wordt verplaatst en naar een zoekindex.

Selecteer een van de toewijzingsopties en vouw de detailweergave uit om de bron- en doeldefinities te controleren.

• Projectietoewijzingen vindt u in vaardighedensets die geïntegreerde vectorisatie bieden, zoals de vaardigheden die zijn gemaakt door de wizard Gegevens importeren en vectoriseren. Deze toewijzingen bepalen bovenliggende en onderliggende veldtoewijzingen (chunk) en of er een secundaire index wordt gemaakt voor alleen de gesegmenteerde inhoud

• Uitvoerveldtoewijzingen worden gevonden in indexeerfuncties en worden gebruikt wanneer vaardighedensets ingebouwde of aangepaste vaardigheden aanroepen. Deze toewijzingen worden gebruikt om het gegevenspad van een knooppunt in de verrijkingsstructuur in te stellen op een veld in de zoekindex. Zie de syntaxis van het verrijkingsknooppuntpad voor meer informatie over paden.

• Veldtoewijzingen vindt u in indexeerfuncties en ze stellen het gegevenspad vast van onbewerkte inhoud in de gegevensbron en een veld in de index. U kunt veldtoewijzingen gebruiken om ook coderings- en decoderingsstappen toe te voegen.

In dit voorbeeld ziet u de details voor een projectietoewijzing. U kunt de JSON bewerken om toewijzingsproblemen op te lossen.

Vaardigheidsdefinities bewerken

Als de veldtoewijzingen juist zijn, controleert u de afzonderlijke vaardigheden voor configuratie en inhoud. Als een vaardigheid geen uitvoer produceert, ontbreekt er mogelijk een eigenschap of parameter, die kan worden bepaald via fout- en validatieberichten.

Andere problemen, zoals een ongeldige context of invoerexpressie, kunnen moeilijker worden opgelost, omdat de fout u vertelt wat er mis is, maar niet hoe u dit kunt oplossen. Zie Referentieverrijkingen in een Azure AI Search-vaardighedenset voor hulp bij context- en invoersyntaxis. Zie Veelvoorkomende fouten en waarschuwingen van indexeerfuncties oplossen voor hulp bij afzonderlijke berichten.

In de volgende stappen ziet u hoe u informatie over een vaardigheid krijgt.

1. Selecteer een vaardigheid op het werkoppervlak. Het detailvenster Vaardigheid wordt aan de rechterkant geopend.

2. Bewerk een vaardigheidsdefinitie met vaardigheidsinstellingen. U kunt de JSON rechtstreeks bewerken.

3. Controleer de padsyntaxis voor verwijzingen naar knooppunten in een verrijkingsstructuur. Hieronder volgen enkele van de meest voorkomende invoerpaden:

   • /document/content voor stukken tekst. Dit knooppunt wordt ingevuld vanuit de inhoudseigenschap van de blob.
   • /document/merged_content voor segmenten van tekst in vaardigheidssets met de vaardigheid Tekst samenvoegen.
   • /document/normalized_images/* voor tekst die wordt herkend of afgeleid van afbeeldingen.

Fouten in een aangepaste vaardigheid lokaal opsporen

Aangepaste vaardigheden kunnen lastiger zijn om fouten op te sporen omdat de code extern wordt uitgevoerd, zodat de foutopsporingssessie niet kan worden gebruikt om fouten op te sporen. In deze sectie wordt beschreven hoe u lokaal fouten kunt opsporen in uw aangepaste web-API-vaardigheid, foutopsporingssessie, Visual Studio Code en ngrok of Tunnelmole. Deze techniek werkt met aangepaste vaardigheden die worden uitgevoerd in Azure Functions of een ander Web Framework dat lokaal wordt uitgevoerd (bijvoorbeeld FastAPI).

Een openbare URL ophalen

In deze sectie worden twee benaderingen beschreven voor het ophalen van een openbare URL naar een aangepaste vaardigheid.

Tunnelmole gebruiken

Tunnelmole is een opensource-tunnelingprogramma dat een openbare URL kan maken waarmee aanvragen via een tunnel naar uw lokale computer worden doorgestuurd.

1. Tunnelmole installeren:

   • 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: Installeren met behulp van npm. Als u NodeJS niet hebt geïnstalleerd, downloadt u het vooraf gecompileerde .exe-bestand voor Windows en plaatst u het ergens in uw PATH.

2. Voer deze opdracht uit om een nieuwe tunnel te maken:

   tmole 7071
   

   Als het goed is, ziet u een antwoord dat er als volgt uitziet:

   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
   

   In het vorige voorbeeld https://m5hdpb-ip-49-183-170-144.tunnelmole.net wordt doorgestuurd naar de poort 7071 op uw lokale computer. Dit is de standaardpoort waar Azure-functies worden weergegeven.

ngrok gebruiken

ngrok is een populaire, gesloten brontoepassing die een tunneling- of doorstuur-URL kan maken, zodat internetaanvragen uw lokale computer bereiken. Gebruik ngrok om aanvragen van een verrijkingspijplijn in uw zoekservice door te sturen naar uw computer om lokale foutopsporing toe te staan.

1. Installeer ngrok.

2. Open een terminal en ga naar de map met het uitvoerbare bestand ngrok.

3. Voer ngrok uit met de volgende opdracht om een nieuwe tunnel te maken:

   ngrok http 7071 
   

   Notitie

   Azure-functies worden standaard weergegeven op 7071. Voor andere hulpprogramma's en configuraties moet u mogelijk een andere poort opgeven.

4. Wanneer ngrok wordt gestart, kopieert u de openbare doorstuur-URL en slaat u deze op voor de volgende stap. De doorstuur-URL wordt willekeurig gegenereerd.

   

Configureren in Azure Portal

Zodra u een openbare URL voor uw aangepaste vaardigheid hebt, wijzigt u de URI voor aangepaste web-API-vaardigheden binnen een foutopsporingssessie om de tunnelmole- of ngrok-doorstuur-URL aan te roepen. Zorg ervoor dat u '/api/FunctionName' toevoegt wanneer u Azure Function gebruikt voor het uitvoeren van de vaardighedensetcode.

U kunt de vaardigheidsdefinitie bewerken in de sectie Vaardigheidsinstellingen van het deelvenster Details van vaardigheid .

Uw code testen

Op dit moment moeten nieuwe aanvragen van uw foutopsporingssessie nu worden verzonden naar uw lokale Azure-functie. U kunt onderbrekingspunten in Visual Studio Code gebruiken om fouten in uw code op te sporen of stap voor stap uit te voeren.

Volgende stappen

Nu u de indeling en mogelijkheden van de visuele editor voor foutopsporingssessies begrijpt, kunt u de zelfstudie voor een praktische ervaring proberen.

Zelfstudie: Foutopsporingssessies verkennen