Zelfstudie: Een vaardighedenset oplossen met behulp van foutopsporingssessies

Artikel
09/01/2024

In Azure AI Search coördineert een vaardighedenset de acties van vaardigheden die doorzoekbare inhoud analyseren, transformeren of maken. Vaak wordt de uitvoer van de ene vaardigheid de invoer van een andere. Wanneer invoer afhankelijk is van uitvoer, kunnen fouten in definities van vaardighedensets en veldkoppelingen leiden tot gemiste bewerkingen en gegevens.

Foutopsporingssessies is een Azure Portal-hulpprogramma dat een holistische visualisatie biedt van een vaardighedenset die wordt uitgevoerd in Azure AI Search. Met dit hulpprogramma kunt u inzoomen op specifieke stappen om eenvoudig te zien waar een actie kan vallen.

In dit artikel gebruikt u Foutopsporingssessies om ontbrekende invoer en uitvoer te vinden en op te lossen. De zelfstudie is all-inclusive. Het biedt voorbeeldgegevens, een REST-bestand waarmee objecten worden gemaakt en instructies voor het opsporen van fouten in de vaardighedenset.

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

Vereisten

Azure AI Search. Maak een service of zoek een bestaande service in uw huidige abonnement. U kunt een gratis service gebruiken voor deze zelfstudie. De gratis laag biedt geen ondersteuning voor beheerde identiteiten voor een Azure AI-Search-service. U moet sleutels gebruiken voor verbindingen met Azure Storage.
Azure Storage-account met Blob Storage, gebruikt voor het hosten van voorbeeldgegevens en voor het behouden van in de cache opgeslagen gegevens die zijn gemaakt tijdens een foutopsporingssessie. Als u een gratis zoekservice gebruikt, moet voor het opslagaccount gedeelde toegangssleutels zijn ingeschakeld en moet openbare netwerktoegang zijn toegestaan.
Visual Studio Code met een REST-client.
Voorbeeld-PDF's (klinische proeven).
Voorbeeld van het bestand debug-sessions.rest dat wordt gebruikt om de verrijkingspijplijn te maken.

Notitie

In deze zelfstudie worden ook Azure AI-services gebruikt voor taaldetectie, entiteitsherkenning en sleuteltermextractie. Omdat de workload zo klein is, worden Azure AI-services achter de schermen getikt voor gratis verwerking voor maximaal 20 transacties. Dit betekent dat u deze oefening kunt voltooien zonder dat u een factureerbare Azure AI-servicesresource hoeft te maken.

De voorbeeldgegevens instellen

In deze sectie maakt u de voorbeeldgegevensset in Azure Blob Storage, zodat de indexeerfunctie en vaardighedenset inhoud hebben om mee te werken.

Download voorbeeldgegevens (clinical-trials-pdf-19), bestaande uit 19 bestanden.
Maak een Azure Storage-account of zoek een bestaand account.
- Kies dezelfde regio als Azure AI Search om bandbreedtekosten te voorkomen.
- Kies het accounttype StorageV2 (algemeen gebruik V2).
Navigeer naar de pagina's van Azure Storage-services in de portal en maak een Blob-container. Best practice is om het toegangsniveau 'privé' op te geven. Geef uw container een naam clinicaltrialdataset.
Selecteer in de container Uploaden om de voorbeeldbestanden te uploaden die u in de eerste stap hebt gedownload en uitgepakt.
Kopieer in de portal de verbindingsreeks voor Azure Storage. U kunt de verbindingsreeks ophalen uit instellingentoegangssleutels> in de portal.

Een sleutel en URL kopiëren

In deze zelfstudie worden API-sleutels gebruikt voor verificatie en autorisatie. U hebt het eindpunt van de zoekservice en een API-sleutel nodig, die u kunt ophalen uit Azure Portal.

Meld u aan bij Azure Portal, navigeer naar de pagina Overzicht en kopieer de URL. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.
Kopieer onder Instellingensleutels> een beheerderssleutel. Beheerderssleutels worden gebruikt om objecten toe te voegen, te wijzigen en te verwijderen. Er zijn twee uitwisselbare beheerderssleutels. Kopieer een van beide.

Een geldige API-sleutel brengt een vertrouwensrelatie tot stand, per aanvraag, tussen de toepassing die de aanvraag verzendt en de zoekservice die deze verwerkt.

Gegevensbron, vaardighedenset, index en indexeerfunctie maken

In deze sectie maakt u een 'buggy'-werkstroom die u in deze zelfstudie kunt oplossen.

Start Visual Studio Code en open het debug-sessions.rest bestand.
Geef de volgende variabelen op: zoekservice-URL, api-sleutel voor zoekservicesbeheerder, opslag verbindingsreeks en de naam van de blobcontainer die de PDF's opslaat.
Verzend elke aanvraag op zijn beurt. Het maken van de indexeerfunctie duurt enkele minuten.
Sluit het bestand.

Resultaten controleren in de portal

De voorbeeldcode maakt opzettelijk een buggy-index als gevolg van problemen die zijn opgetreden tijdens de uitvoering van de vaardighedenset. Het probleem is dat de index gegevens mist.

Selecteer in Azure Portal op de pagina Overzicht van de zoekservice het tabblad Indexen.
Selecteer klinische proeven.
Voer deze JSON-queryreeks in de JSON-weergave van Search Explorer in. Het retourneert velden voor specifieke documenten (geïdentificeerd door het unieke metadata_storage_path veld).
```
"search": "*",
"select": "metadata_storage_path, organizations, locations",
"count": true
```
Voer de query uit. Als het goed is, ziet u lege waarden voor organizations en locations.

Deze velden moeten zijn ingevuld via de vaardigheid Entiteitsherkenning van de vaardighedenset, die wordt gebruikt om organisaties en locaties overal in de inhoud van de blob te detecteren. In de volgende oefening gaat u fouten opsporen in de vaardighedenset om te bepalen wat er mis is gegaan.

Een andere manier om fouten en waarschuwingen te onderzoeken, is via Azure Portal.

Open het tabblad Indexeerfuncties en selecteer clinical-trials-idxr.

U ziet dat er waarschuwingen zijn opgetreden terwijl de indexeerfunctie in het algemeen is geslaagd.
Selecteer Geslaagd om de waarschuwingen weer te geven (als er meestal fouten zijn, is de detailkoppeling mislukt). U ziet een lange lijst met elke waarschuwing die door de indexeerfunctie wordt verzonden.

Uw foutopsporingssessie starten

Selecteer in het linkernavigatiedeelvenster van de zoekservice onder Zoekbeheer de foutopsporingssessies.
Selecteer + Foutopsporingssessie toevoegen.
Geef de sessie een naam.
Geef in de indexeersjabloon de naam van de indexeerfunctie op. De indexeerfunctie heeft verwijzingen naar de gegevensbron, de vaardighedenset en de index.
Selecteer het opslagaccount.
Sla de sessie op.
Er wordt een foutopsporingssessie geopend op de pagina Instellingen. U kunt wijzigingen aanbrengen in de eerste configuratie en eventuele standaardinstellingen overschrijven. Een foutopsporingssessie werkt alleen met één document. De standaardinstelling is om het eerste document in de verzameling te accepteren als basis voor uw foutopsporingssessies. U kunt een specifiek document kiezen om fouten op te sporen door de URI ervan op te geven in Azure Storage.
Wanneer de foutopsporingssessie is geïnitialiseerd, ziet u een werkstroom voor vaardigheden met toewijzingen en een zoekindex. De verrijkte documentgegevensstructuur wordt weergegeven in een detailvenster aan de zijkant. Deze is uitgesloten van de volgende schermopname, zodat u meer van de werkstroom kunt zien.

Problemen met de vaardighedenset zoeken

Eventuele problemen die door de indexeerfunctie worden gerapporteerd, worden aangeduid als fouten en waarschuwingen.

U ziet dat het aantal fouten en waarschuwingen een veel kleinere lijst is dan de lijst die eerder wordt weergegeven, omdat in deze lijst alleen de fouten voor één document worden beschreven. Net zoals de lijst die door de indexeerfunctie wordt weergegeven, kunt u een waarschuwingsbericht selecteren en de details van deze waarschuwing bekijken.

Selecteer Waarschuwingen om de meldingen te bekijken. Als het goed is, ziet u vier:

'Kan vaardigheid niet uitvoeren omdat een of meer vaardigheidsinvoeren ongeldig waren. Vereiste vaardigheidsinvoer ontbreekt. Naam: 'text', Source: '/document/content'.
'Kan uitvoerveld 'locaties' niet toewijzen aan zoekindex. Controleer de eigenschap outputFieldMappings van uw indexeerfunctie. Ontbrekende waarde '/document/merged_content/locations'.
'Kan uitvoerveld 'organisaties' niet toewijzen aan zoekindex. Controleer de eigenschap outputFieldMappings van uw indexeerfunctie. Ontbrekende waarde '/document/merged_content/organizations'.
'Vaardigheid is uitgevoerd, maar kan onverwachte resultaten hebben omdat een of meer vaardigheidsinvoeren ongeldig waren. Optionele vaardigheidsinvoer ontbreekt. Naam: 'languageCode', Bron: '/document/languageCode'. Problemen met parseren van expressietaal: Ontbrekende waarde '/document/languageCode'.

Veel vaardigheden hebben een 'languageCode'-parameter. Door de bewerking te inspecteren, ziet u dat deze taalcode-invoer ontbreekt in de EntityRecognitionSkill.#1vaardigheid voor herkenning van entiteiten die problemen ondervindt met 'locaties' en 'organisaties'-uitvoer.

Omdat alle vier de meldingen over deze vaardigheid gaan, is de volgende stap het opsporen van fouten in deze vaardigheid. Indien mogelijk moet u eerst invoerproblemen oplossen voordat u verdergaat met uitvoerproblemen.

Ontbrekende invoerwaarden voor vaardigheden oplossen

Selecteer op het werkoppervlak de vaardigheid die de waarschuwingen rapporteert. In deze zelfstudie is dit de vaardigheid voor entiteitsherkenning.
Het deelvenster Vaardigheidsdetails wordt aan de rechterkant geopend met secties voor iteraties en hun respectieve invoer en uitvoer, vaardigheidsinstellingen voor de JSON-definitie van de vaardigheid en berichten voor eventuele fouten en waarschuwingen die deze vaardigheid verzendt.
Beweeg de muisaanwijzer over elke invoer (of selecteer een invoer) om de waarden in de expressie-evaluator weer te geven. U ziet dat het weergegeven resultaat voor deze invoer er niet uitziet als een tekstinvoer. Het lijkt op een reeks nieuwe regeltekens \n \n\n\n\n in plaats van tekst. Het gebrek aan tekst betekent dat er geen entiteiten kunnen worden geïdentificeerd, dus dit document voldoet niet aan de vereisten van de vaardigheid of er is een andere invoer die in plaats daarvan moet worden gebruikt.
Ga terug naar de verrijkte gegevensstructuur en bekijk de verrijkingsknooppunten voor dit document. U ziet dat voor \n \n\n\n\n 'inhoud' geen bron van oorsprong is, maar een andere waarde voor 'merged_content' OCR-uitvoer heeft. Hoewel er geen indicatie is, lijkt de inhoud van dit PDF-bestand een JPEG-bestand te zijn, zoals wordt aangetoond door de geëxtraheerde en verwerkte tekst in 'merged_content'.
Ga terug naar de vaardigheid en selecteer Skillset-instellingen om de JSON-definitie te openen.
Wijzig de expressie van /document/content in /document/merged_contenten selecteer Opslaan. U ziet dat de waarschuwing niet meer wordt weergegeven.
Selecteer Uitvoeren in het venstermenu van de sessie. Hiermee wordt een andere uitvoering van de vaardighedenset gestart met behulp van het document.
Zodra de uitvoering van de foutopsporingssessie is voltooid, ziet u dat het aantal waarschuwingen met één is verminderd. Waarschuwingen geven aan dat de fout voor tekstinvoer is verdwenen, maar de andere waarschuwingen blijven bestaan. De volgende stap is het oplossen van de waarschuwing over de ontbrekende of lege waarde /document/languageCode.
Selecteer de vaardigheid en plaats de muisaanwijzer op /document/languageCode. De waarde voor deze invoer is null, wat geen geldige invoer is.
Net als bij het vorige probleem controleert u eerst de verrijkte gegevensstructuur op bewijs van de knooppunten. U ziet dat er geen 'languageCode'-knooppunt is, maar er is er een voor 'language'. Er is dus een typefout in de vaardigheidsinstellingen.
Kopieer de expressie /document/language.
Selecteer in het deelvenster Vaardigheidsgegevens de vaardigheidsinstellingen voor de vaardigheid #1 en plak de nieuwe waarde. /document/language
Selecteer Opslaan.
Selecteer Uitvoeren.
Nadat de uitvoering van de foutopsporingssessie is voltooid, kunt u de resultaten controleren in het detailvenster Vaardigheden. Wanneer u de muisaanwijzer aanwijst /document/language, ziet en u de waarde in de expressie-evaluator.

U ziet dat de invoerwaarschuwingen zijn verdwenen. Er blijven nu slechts de twee waarschuwingen over uitvoervelden voor organisaties en locaties.

Ontbrekende uitvoerwaarden voor vaardigheid herstellen

De berichten zeggen dat u de eigenschap 'outputFieldMappings' van uw indexeerfunctie wilt controleren, zodat u daar kunt beginnen.

Selecteer Uitvoerveldtoewijzingen op het werkoppervlak. U ziet dat de toewijzingen van het uitvoerveld ontbreken.
Controleer als eerste stap of de zoekindex de verwachte velden bevat. In dit geval bevat de index velden voor 'locaties' en 'organisaties'.
Als er geen probleem is met de index, is de volgende stap het controleren van de uitvoer van vaardigheden. Net als voorheen selecteert u de verrijkte gegevensstructuur en schuift u door de knooppunten om 'locaties' en 'organisaties' te vinden. U ziet dat het bovenliggende item 'inhoud' is in plaats van 'merged_content'. De context is onjuist.
Ga terug naar het detailvenster Vaardigheden voor de vaardigheid voor entiteitsherkenning.
Ga in Vaardigheidsinstellingen naar context document/merged_content. Op dit moment moet u drie wijzigingen in de vaardigheidsdefinitie hebben.
Selecteer Opslaan.
Selecteer Uitvoeren.

Alle fouten zijn opgelost.

Wijzigingen doorvoeren in de vaardighedenset

Toen de foutopsporingssessie werd gestart, heeft de zoekservice een kopie van de vaardighedenset gemaakt. Dit is gedaan om de oorspronkelijke vaardighedenset voor uw zoekservice te beschermen. Nu u klaar bent met het opsporen van fouten in uw vaardighedenset, kunnen de oplossingen worden doorgevoerd (de oorspronkelijke vaardighedenset overschrijven).

Als u nog niet klaar bent om wijzigingen door te voeren, kunt u de foutopsporingssessie opslaan en deze later opnieuw openen.

Selecteer Wijzigingen doorvoeren in het hoofdmenu Foutopsporingssessies.
Selecteer OK om te bevestigen dat u uw vaardighedenset wilt bijwerken.
Sluit de foutopsporingssessie en open Indexeerfuncties vanuit het linkernavigatiedeelvenster.
Selecteer 'clinical-trials-idxr'.
Selecteer Opnieuw instellen.
Selecteer Uitvoeren.
Selecteer Vernieuwen om de status van het opnieuw instellen en uitvoeren van opdrachten weer te geven.

Wanneer de indexeerfunctie is uitgevoerd, moet er een groen vinkje staan en het woord Geslaagd naast het tijdstempel voor de meest recente uitvoering op het tabblad Uitvoeringsgeschiedenis . Om ervoor te zorgen dat de wijzigingen zijn toegepast:

Open Indexen in het linkernavigatiedeelvenster.
Selecteer de index 'clinical-trials' en voer op het tabblad Search Explorer deze queryreeks in: $select=metadata_storage_path, organizations, locations&$count=true als u velden wilt retourneren voor specifieke documenten (geïdentificeerd door het unieke metadata_storage_path veld).
Selecteer Zoeken.

De resultaten moeten laten zien dat organisaties en locaties nu worden gevuld met de verwachte waarden.

Resources opschonen

Wanneer u in uw eigen abonnement werkt, is het een goed idee om aan het einde van een project te bepalen of u de gemaakte resources nog nodig hebt. Resources die actief blijven, kunnen u geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

U kunt resources vinden en beheren in de portal via de koppeling Alle resources of Resourcegroepen in het navigatiedeelvenster aan de linkerkant.

De gratis service is beperkt tot drie indexen, indexeerfuncties en gegevensbronnen. U kunt afzonderlijke items in de portal verwijderen om onder de limiet te blijven.

Volgende stappen

Deze zelfstudie heeft betrekking op verschillende aspecten van de definitie en verwerking van vaardighedensets. Raadpleeg de volgende artikelen voor meer informatie over concepten en werkstromen:

Delen via