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 gepubliceerde vaardighedenset in uw Azure AI-Search-service te pushen.

Een foutopsporingssessie is een indexeerfunctie en een vaardighedenset met een bereik van één document, dat u kunt gebruiken om uw wijzigingen 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 bestaande verrijkingspijplijn, waaronder een gegevensbron, een vaardighedenset, een indexeerfunctie en een index.

• Een roltoewijzing inzender in de zoekservice.

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

• Een roltoewijzing voor inzender voor opslagblobgegevens in Azure Storage als u een door het systeem beheerde identiteit gebruikt. 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. In de volgende lijst worden de uitzonderingen vermeld:

• Azure Cosmos DB voor MongoDB wordt momenteel niet ondersteund.

• 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 Verbinding maken een zoekservice voor andere Azure-resources met behulp van een beheerde identiteit voor meer informatie.

De portal biedt geen ondersteuning voor door de klant beheerde sleutelversleuteling (CMK), wat betekent dat portalervaringen zoals foutopsporingssessies geen CMK-versleutelde verbindingsreeks s of andere versleutelde metagegevens kunnen hebben. Als uw zoekservice is geconfigureerd voor CMK-afdwinging, werken foutopsporingssessies niet.

Een foutopsporingssessie maken

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

2. Selecteer op de linkernavigatiepagina foutopsporingssessies.

3. Selecteer in 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. Zoek in de opslagverbinding een opslagaccount voor algemeen gebruik om de foutopsporingssessie in de cache op te slaan. U wordt gevraagd om een blobcontainer te selecteren en optioneel te maken in Blob Storage of Azure Data Lake Storage Gen2. U kunt dezelfde container opnieuw gebruiken voor alle volgende foutopsporingssessies die u maakt. Een nuttige containernaam kan 'cognitive-search-debug-sessions' zijn.

6. Kies bij verificatie van beheerde identiteit geen als de verbinding met Azure Storage geen beheerde identiteit gebruikt. Kies anders de beheerde identiteit waaraan u inzendermachtigingen voor Opslagblobgegevens hebt verleend.

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

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

   

9. 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 nabootsen die worden gebruikt door de werkelijke indexeerfunctie. Alle indexeeropties die u opgeeft in een foutopsporingssessie hebben geen invloed op de indexeerfunctie zelf.

10. Uw configuratie moet er ongeveer uitzien als in deze schermopname. Selecteer Sessie opslaan om aan de slag te gaan.

    

De foutopsporingssessie begint met het uitvoeren van de indexeerfunctie en vaardighedenset voor het geselecteerde document. De inhoud en metagegevens van het document die zijn gemaakt, 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 worden de fouten en waarschuwingen beperkt tot één document. U doorloopt deze lijst, voert uw wijzigingen aan en gaat vervolgens terug naar de lijst om te controleren of problemen zijn opgelost.

Als u de berichten wilt weergeven, selecteert u een vaardigheid in AI Enrichment > Skill Graph en selecteert u vervolgens Fouten/waarschuwingen in het detailvenster.

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/waarschuwingen om te zien of het aantal is verminderd. De lijst wordt pas vernieuwd wanneer u het tabblad opent.

Inhoud van verrijkingsknooppunten 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.

Verrijkte documenten zijn intern, maar met een foutopsporingssessie hebt u toegang tot de inhoud die wordt geproduceerd tijdens het uitvoeren van vaardigheden. Volg deze stappen om de inhoud of uitvoer van elke vaardigheid weer te geven:

1. Begin met de standaardweergaven: AI-verrijkingsgrafiek>, waarbij het grafiektype is ingesteld op Dependency Graph.

2. Selecteer een vaardigheid.

3. Selecteer in het detailvenster aan de rechterkant uitvoeringen, selecteer een UITVOER en open vervolgens de expressie-evaluator (</>) om de expressie en het resultaat ervan weer te geven.

   

4. U kunt ook AI-verrijking > verrijkte gegevensstructuur openen om omlaag te schuiven in de lijst met knooppunten. De lijst bevat potentiële en werkelijke knooppunten, met een kolom voor uitvoer en een andere kolom die het upstream-object aangeeft dat wordt gebruikt om de uitvoer te produceren.

   

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 in AI-verrijkingsgrafiek>. Het deelvenster Vaardigheidsdetails wordt aan de rechterkant geopend.

2. Bewerk een vaardigheidsdefinitie met behulp van een van beide benaderingen:

   • Vaardigheid Instellingen als u de voorkeur geeft aan een visuele editor
   • JSON-editor voor vaardigheden om het JSON-document rechtstreeks te 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.

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

1. Begin met de standaardweergaven: AI-verrijkingsgrafiek>, waarbij het grafiektype is ingesteld op Dependency Graph.

2. Selecteer veldtoewijzingen bovenaan. U moet ten minste de documentsleutel vinden die elk zoekdocument uniek identificeert en koppelt in de zoekindex aan het brondocument in de gegevensbron.

   Als u onbewerkte inhoud rechtstreeks uit de gegevensbron importeert en verrijking overslaan, moet u deze velden vinden in Veldtoewijzingen.

3. Selecteer Uitvoerveldtoewijzingen onderaan de grafiek. Hier vindt u toewijzingen van vaardigheidsuitvoer naar doelvelden in de zoekindex. Tenzij u de wizard Gegevens importeren hebt gebruikt, worden uitvoerveldtoewijzingen handmatig gedefinieerd en kunnen deze onvolledig of onjuist zijn getypt.

   Controleer of de velden in uitvoerveldtoewijzingen aanwezig zijn in de zoekindex zoals opgegeven, waarbij u controleert op de syntaxis van het pad naar het spelling- en verrijkingsknooppunt.

   

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

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

Wijzig in de foutopsporingssessie de URI voor aangepaste web-API-vaardigheden om de tunnelmole- of doorstuur-URL van ngrok 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 portal.

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