Självstudie: Felsöka en kompetensuppsättning med hjälp av felsökningssessioner

En kompetensuppsättning samordnar åtgärderna för färdigheter som analyserar, transformerar eller skapar sökbart innehåll. Ofta blir utdata från en färdighet indata för en annan. När indata är beroende av utdata kan misstag i definitioner för kompetensuppsättningar och fältassociationer resultera i missade åtgärder och data.

Felsökningssessioner är ett Azure-portalverktyg som ger en holistisk visualisering av en kompetensuppsättning. Med det här verktyget kan du öka detaljnivån för specifika steg för att enkelt se var en åtgärd kan falla ned.

I den här artikeln använder du Felsökningssessioner för att hitta och åtgärda saknade indata och utdata. Självstudien är allomfattande. Den innehåller exempeldata, en REST-fil som skapar objekt och instruktioner för felsökning av problem i kompetensuppsättningen.

Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.

Förutsättningar

• Azure AI Search. Skapa en tjänst eller hitta en befintlig tjänst under din aktuella prenumeration. Du kan använda en kostnadsfri tjänst för den här självstudien.

• Azure Storage-konto med Blob Storage, används som värd för exempeldata och för att spara cachelagrade data som skapats under en felsökningssession.

• Visual Studio Code med en REST-klient.

• Exempel på PDF-filer (kliniska prövningar).

• Exempel på filen debug-sessions.rest som används för att skapa berikningspipelinen.

Kommentar

I den här självstudien används även Azure AI-tjänster för språkidentifiering, entitetsigenkänning och extrahering av nyckelfraser. Eftersom arbetsbelastningen är så liten används Azure AI-tjänster i bakgrunden för kostnadsfri bearbetning för upp till 20 transaktioner. Det innebär att du kan slutföra den här övningen utan att behöva skapa en fakturerbar Azure AI-tjänstresurs.

Konfigurera exempeldata

Det här avsnittet skapar exempeldatauppsättningen i Azure Blob Storage så att indexeraren och kompetensuppsättningen har innehåll att arbeta med.

1. Ladda ned exempeldata (clinical-trials-pdf-19), bestående av 19 filer.

2. Skapa ett Azure Storage-konto eller hitta ett befintligt konto.

   • Välj samma region som Azure AI Search för att undvika bandbreddsavgifter.

   • Välj kontotypen StorageV2 (generell användning V2).

3. Gå till sidorna för Azure Storage-tjänster i portalen och skapa en blobcontainer. Bästa praxis är att ange åtkomstnivån "privat". Ge containern clinicaltrialdatasetnamnet .

4. I containern väljer du Ladda upp för att ladda upp exempelfilerna som du laddade ned och uppackade i det första steget.

5. I portalen kopierar du anslutningssträng för Azure Storage. Du kan hämta anslutningssträng från Inställningar> Åtkomstnycklar i portalen.

Kopiera en nyckel och EN URL

REST-anrop kräver slutpunkten för söktjänsten och en API-nyckel för varje begäran. Du kan hämta dessa värden från Azure-portalen.

1. Logga in på Azure-portalen, gå till sidan Översikt och kopiera URL:en. Här följer ett exempel på hur en slutpunkt kan se ut: https://mydemo.search.windows.net.

2. Under Inställningar> Nycklar kopierar du en administratörsnyckel. Administratörsnycklar används för att lägga till, ändra och ta bort objekt. Det finns två utbytbara administratörsnycklar. Kopiera någon av dem.

   

En giltig API-nyckel upprättar förtroende per begäran mellan programmet som skickar begäran och söktjänsten som hanterar den.

Skapa datakälla, kompetensuppsättning, index och indexerare

I det här avsnittet skapar du ett "buggy"-arbetsflöde som du kan åtgärda i den här självstudien.

1. Starta Visual Studio Code och öppna debug-sessions.rest filen.

2. Ange följande variabler: URL:en för söktjänsten, api-nyckeln för söktjänsters administratör, lagring anslutningssträng och namnet på blobcontainern som lagrar PDF-filerna.

3. Skicka varje begäran i tur och ordning. Det tar flera minuter att skapa indexeraren.

4. Stäng filen.

Kontrollera resultaten i portalen

Exempelkoden skapar avsiktligt ett buggy-index som en följd av problem som uppstod vid körning av kompetensuppsättningar. Problemet är att indexet saknar data.

1. I Azure-portalen går du till sidan Översikt för söktjänsten och väljer fliken Index.

2. Välj kliniska prövningar.

3. Ange den här JSON-frågesträngen i Sökutforskarens JSON-vy. Den returnerar fält för specifika dokument (identifieras av det unika metadata_storage_path fältet).

   "select": "metadata_storage_path, organizations, locations",
   "count"=true`
   

4. Köra frågan. Du bör se tomma värden för organizations och locations.

   Dessa fält bör ha fyllts i via kompetensuppsättningens entitetsigenkänningsfärdighet, som används för att identifiera organisationer och platser var som helst i blobens innehåll. I nästa övning felsöker du kompetensuppsättningen för att avgöra vad som gick fel.

Ett annat sätt att undersöka fel och varningar är via Azure-portalen.

1. Öppna fliken Indexerare och välj clinical-trials-idxr.

   Observera att även om indexerarjobbet lyckades totalt sett fanns det varningar.

2. Välj Lyckades om du vill visa varningarna (om det främst fanns fel skulle informationslänken misslyckas). Du ser en lång lista över varje varning som genereras av indexeraren.

   

Starta felsökningssessionen

1. I det vänstra navigeringsfönstret för söktjänsten går du till Sökhantering och väljer Felsöka sessioner.

2. Välj + Lägg till felsökningssession.

3. Ge sessionen ett namn.

4. Anslut sessionen till ditt lagringskonto. Skapa en container med namnet "felsökningssessioner". Du kan använda den här containern upprepade gånger för att lagra alla dina felsökningssessionsdata.

5. Om du har konfigurerat en betrodd anslutning mellan sökning och lagring väljer du den användarhanterade identiteten eller systemidentiteten för anslutningen. Annars använder du standardvärdet (Ingen).

6. Ange indexerarens namn i Indexer-mallen. Indexeraren har referenser till datakällan, kompetensuppsättningen och indexet.

7. Acceptera standarddokumentvalet för det första dokumentet i samlingen. En felsökningssession fungerar bara med ett enda dokument. Du kan välja vilket dokument som ska felsökas eller bara använda det första dokumentet.

8. Spara sessionen. Om du sparar sessionen startas berikandepipelinen enligt definitionen i kompetensuppsättningen för det valda dokumentet.

   

9. När felsökningssessionen har initierats är sessionen standard på fliken AI-berikanden , vilket markerar Skill Graph. Skill Graph tillhandahåller en visuell hierarki av kompetensuppsättningen och dess körningsordning sekventiellt och parallellt.

   

Hitta problem med kompetensuppsättningen

Eventuella problem som rapporteras av indexeraren finns på den intilliggande fliken Fel/varningar .

Observera att fliken Fel/varningar ger en mycket mindre lista än den som visades tidigare eftersom den här listan endast beskriver felen för ett enda dokument. Precis som listan som visas av indexeraren kan du välja ett varningsmeddelande och se information om den här varningen.

Välj Fel/varningar för att granska meddelandena. Du bör se fyra:

• "Det gick inte att köra färdigheten eftersom en eller flera kunskapsindata var ogiltiga. Nödvändiga kunskapsindata saknas. Namn: "text", Källa: '/dokument/innehåll'."

• "Det gick inte att mappa utdatafältets platser för att söka i indexet. Kontrollera egenskapen outputFieldMappings för indexeraren. Värdet "/document/merged_content/locations" saknas."

• "Det gick inte att mappa utdatafältets organisationer för att söka efter index. Kontrollera egenskapen outputFieldMappings för indexeraren. Värdet "/document/merged_content/organizations" saknas."

• "Färdigheten utfördes men kan ha oväntade resultat eftersom en eller flera kunskapsindata var ogiltiga. Valfria kunskaper saknas. Namn: 'languageCode', Källa: '/document/languageCode'. Problem med parsning av uttrycksspråk: Värdet /document/languageCode saknas."

Många kunskaper har parametern "languageCode". Genom att granska åtgärden kan du se att den här språkkodinmatningen EntityRecognitionSkill.#1saknas i , som är samma entitetsigenkänningsfärdighet som har problem med utdata från "platser" och "organisationer".

Eftersom alla fyra meddelandena handlar om den här färdigheten är nästa steg att felsöka den här färdigheten. Börja om möjligt med att lösa indataproblem först innan du går vidare till utdataproblem.

Åtgärda saknade värden för kunskapsindata

På fliken Fel/varningar finns det två indata som saknas för en åtgärd med etiketten EntityRecognitionSkill.#1. Detaljerna i det första felet förklarar att en nödvändig inmatning för "text" saknas. Den andra anger ett problem med indatavärdet "/document/languageCode".

1. I AI Enrichments>Skill Graph väljer du färdigheten märkt #1 för att visa dess information i den högra rutan.

2. Välj fliken Körningar och leta upp indata för "text".

3. Välj symbolen </> för att öppna uttrycksutvärderingen. Det visade resultatet för den här inmatningen ser inte ut som en textinmatning. Det ser ut som en serie nya radtecken \n \n\n\n\n i stället för text. Bristen på text innebär att inga entiteter kan identifieras, så antingen misslyckas det här dokumentet med att uppfylla kraven för kunskapen, eller så finns det andra indata som ska användas i stället.

   

4. Växla det vänstra fönstret till Berikad datastruktur och rulla nedåt i listan över berikningsnoder för det här dokumentet. Observera att \n \n\n\n\n för "innehåll" inte har någon ursprungskälla, men ett annat värde för "merged_content" har OCR-utdata. Även om det inte finns någon indikation verkar innehållet i den här PDF-filen vara en JPEG-fil, vilket framgår av den extraherade och bearbetade texten i "merged_content".

   

5. I den högra rutan väljer du Körningar för kunskapen #1 och öppnar uttrycksutvärderingen</>för inmatningen "text".

6. Ändra uttrycket från /document/content till och välj sedan Utvärdera/document/merged_content. Observera att innehållet nu är ett textsegment och därmed kan användas för entitetsigenkänning.

   

7. Växla till Skill JSON-redigeraren.

8. På rad 16, under "indata", ändrar du /document/content till /document/merged_content.

    {
      "name": "text",
      "source": "/document/merged_content"
    },
   

9. Välj Spara i fönstret Kunskapsinformation.

   

10. Välj Kör i sessionens fönstermeny. Detta startar en ny körning av kunskapsuppsättningen med hjälp av dokumentet.

11. När körningen av felsökningssessionen är klar kontrollerar du fliken Fel/varningar och visar att felet för textindata är borta, men de andra varningarna kvarstår. Nästa steg är att åtgärda varningen om "languageCode".

    

12. Välj fliken Körningar och leta upp indata för "languageCode".

13. Välj symbolen </> för att öppna uttrycksutvärderingen. Observera bekräftelsen att egenskapen "languageCode" inte är en giltig indata.

    

Det finns två sätt att undersöka det här felet. Den första är att titta på var indata kommer från – vilken kompetens i hierarkin ska ge det här resultatet? Fliken Körningar i fönstret kunskapsinformation bör visa källan för indata. Om det inte finns någon källa indikerar detta ett fältmappningsfel.

1. På fliken Körningar kontrollerar du INDATA och hittar "languageCode". Det finns ingen källa för dessa indata i listan.

2. Växla den vänstra rutan till Berikad datastruktur. Rulla nedåt i listan över berikningsnoder för det här dokumentet. Observera att det inte finns någon "languageCode"-nod, men det finns en för "language". Det finns alltså ett skrivfel i kunskapsinställningarna.

   

3. I den berikade datastrukturen öppnar du uttrycksutvärderaren </> för noden "språk" och kopierar uttrycket /document/language.

4. I den högra rutan väljer du Kompetens Inställningar för kunskap nr 1 och öppnar uttrycksutvärderingen</>för indatan "languageCode".

5. Klistra in det nya värdet /document/language i rutan Uttryck och välj Utvärdera. Den bör visa rätt indata "en".

6. Välj Spara.

7. Markera Kör.

När körningen av felsökningssessionen är klar kontrollerar du fliken Fel/varningar och visar att alla indatavarningar är borta. Nu återstår bara de två varningarna om utdatafält för organisationer och platser.

Åtgärda saknade kunskapsutdatavärden

Meddelandena säger att kontrollera egenskapen "outputFieldMappings" för indexeraren, så låt oss börja där.

1. Gå till Skill Graph och välj Mappningar för utdatafält. Mappningarna är faktiskt korrekta, men normalt kontrollerar du indexdefinitionen för att säkerställa att fälten finns för "platser" och "organisationer".

   

2. Om det inte finns några problem med indexet är nästa steg att kontrollera kunskapsutdata. Precis som tidigare väljer du Den berikade datastrukturen och rullar noderna för att hitta "platser" och "organisationer". Observera att det överordnade objektet är "innehåll" i stället för "merged_content". Kontexten är fel.

   

3. Växla tillbaka till Skill Graph och välj entitetsigenkänningsfärdigheten.

4. Navigera i Inställningar för att hitta "kontext".

   

5. Dubbelklicka på inställningen för "kontext" och redigera den för att läsa '/document/merged_content'.

6. Välj Spara.

7. Markera Kör.

Alla fel har lösts.

Checka in ändringar i kompetensuppsättningen

När felsökningssessionen initierades skapade söktjänsten en kopia av kompetensuppsättningen. Detta gjordes för att skydda den ursprungliga kompetensuppsättningen i söktjänsten. Nu när du har felsökt din kompetensuppsättning kan korrigeringarna utföras (skriva över den ursprungliga kompetensuppsättningen).

Om du inte är redo att genomföra ändringar kan du också spara felsökningssessionen och öppna den igen senare.

1. Välj Checka in ändringar i huvudmenyn för felsökningssessioner.

2. Välj OK för att bekräfta att du vill uppdatera din kompetensuppsättning.

3. Stäng Felsökningssessionen och öppna Indexerare i det vänstra navigeringsfönstret.

4. Välj "clinical-trials-idxr".

5. Välj Återställ.

6. Markera Kör.

7. Välj Uppdatera för att visa status för kommandona för återställning och körning.

När indexeraren har körts bör det finnas en grön bockmarkering och ordet Lyckades bredvid tidsstämpeln för den senaste körningen på fliken Körningshistorik . Så här ser du till att ändringarna har tillämpats:

1. Öppna Index i det vänstra navigeringsfönstret.

2. Välj index för kliniska prövningar och ange följande frågesträng på fliken Sökutforskaren: $select=metadata_storage_path, organizations, locations&$count=true för att returnera fält för specifika dokument (identifieras av det unika metadata_storage_path fältet).

3. Välj Sök.

Resultaten bör visa att organisationer och platser nu är ifyllda med de förväntade värdena.

Rensa resurser

När du arbetar i din egen prenumeration kan det dock vara klokt att i slutet av ett projekt kontrollera om du fortfarande behöver de resurser som du skapade. Resurser som fortsätter att köras kostar pengar. Du kan ta bort enstaka resurser eller hela resursgruppen om du vill ta bort alla resurser.

Du kan hitta och hantera resurser i portalen med hjälp av länken Alla resurser eller Resursgrupper i det vänstra navigeringsfönstret.

Den kostnadsfria tjänsten är begränsad till tre index, indexerare och datakällor. Du kan ta bort enskilda objekt i portalen för att hålla dig under gränsen.

Nästa steg

Den här självstudien berörde olika aspekter av definition och bearbetning av kompetensuppsättningar. Mer information om begrepp och arbetsflöden finns i följande artiklar:

• Mappa utdatafält för kunskapsuppsättning till fält i ett sökindex

• Kunskapsuppsättningar i Azure AI Search

• Så här konfigurerar du cachelagring för inkrementell berikning