Felsöka en Azure AI Search-kompetensuppsättning i Azure-portalen

  • Artikel

Starta en portalbaserad felsökningssession för att identifiera och lösa fel, validera ändringar och skicka ändringar till en publicerad kompetensuppsättning i azure AI-tjänsten Search.

En felsökningssession är en cachelagrad indexerare och kompetensuppsättningskörning, begränsad till ett enda dokument, som du kan använda för att redigera och testa dina ändringar interaktivt. När du är klar med felsökningen kan du spara ändringarna i kunskapsuppsättningen.

Bakgrund om hur en felsökningssession fungerar finns i Felsöka sessioner i Azure AI Search. Information om hur du övar ett felsökningsarbetsflöde med ett exempeldokument finns i Självstudie: Felsöka sessioner.

Förutsättningar

  • En befintlig berikningspipeline, inklusive en datakälla, en kompetensuppsättning, en indexerare och ett index.

  • En rolltilldelning för deltagare i söktjänsten.

  • Ett Azure Storage-konto som används för att spara sessionstillstånd.

  • En rolltilldelning för Lagringsblobdatadeltagare i Azure Storage om du använder en systemhanterad identitet. I annat fall planerar du att använda en fullständig åtkomst anslutningssträng för felsökningssessionsanslutningen till Azure Storage.

  • Om Azure Storage-kontot finns bakom en brandvägg konfigurerar du det för att tillåta åtkomst till söktjänsten.

Begränsningar

Felsökningssessioner fungerar med alla allmänt tillgängliga indexeringsdatakällor och de flesta förhandsgranskningsdatakällor. I följande lista visas undantagen:

  • Azure Cosmos DB for MongoDB stöds för närvarande inte.

  • Om en rad misslyckas under indexet och det inte finns några motsvarande metadata för Azure Cosmos DB för NoSQL kanske felsökningssessionen inte väljer rätt rad.

  • Om en partitionerad samling tidigare inte partitionerades för SQL-API:et för Azure Cosmos DB hittar inte felsökningssessionen dokumentet.

  • För anpassade kunskaper stöds inte en användartilldelad hanterad identitet för en felsökningssessionsanslutning till Azure Storage. Som anges i förhandskraven kan du använda en systemhanterad identitet eller ange en fullständig åtkomst anslutningssträng som innehåller en nyckel. Mer information finns i Anslut en söktjänst till andra Azure-resurser med hjälp av en hanterad identitet.

Portalen stöder inte kundhanterad nyckelkryptering (CMK), vilket innebär att portalupplevelser som felsökningssessioner inte kan ha CMK-krypterade anslutningssträng eller andra krypterade metadata. Om söktjänsten har konfigurerats för CMK-tillämpning fungerar inte felsökningssessioner.

Skapa en felsökningssession

  1. Logga in på Azure-portalen och leta reda på söktjänsten.

  2. På den vänstra navigeringssidan väljer du Felsöka sessioner.

  3. I åtgärdsfältet längst upp väljer du Lägg till felsökningssession.

    Skärmbild av kommandona för felsökningssessioner på portalsidan.

  4. I Namn på felsökningssession anger du ett namn som hjälper dig att komma ihåg vilken kompetensuppsättning, indexerare och datakälla som felsökningssessionen handlar om.

  5. I Lagringsanslutning hittar du ett allmänt lagringskonto för cachelagring av felsökningssessionen. Du uppmanas att välja och eventuellt skapa en blobcontainer i Blob Storage eller Azure Data Lake Storage Gen2. Du kan återanvända samma container för alla efterföljande felsökningssessioner som du skapar. Ett användbart containernamn kan vara "cognitive-search-debug-sessions".

  6. I Hanterad identitetsautentisering väljer du Ingen om anslutningen till Azure Storage inte använder en hanterad identitet. Annars väljer du den hanterade identitet som du har beviljat Behörigheter för Storage Blob Data-deltagare .

  7. I Indexer-mallen väljer du den indexerare som driver den kompetensuppsättning som du vill felsöka. Kopior av både indexeraren och kunskapsuppsättningen används för att initiera sessionen.

  8. I Dokument att felsöka väljer du det första dokumentet i indexet eller väljer ett specifikt dokument. Om du väljer ett visst dokument, beroende på datakällan, blir du ombedd att ange en URI eller ett rad-ID.

    Om ditt specifika dokument är en blob anger du blob-URI:n. Du hittar URI:n på blobegenskapssidan i portalen.

    Skärmbild av URI-egenskapen i Blob Storage.

  9. I Indexer-inställningar kan du också ange eventuella inställningar för indexeringskörning som används för att skapa sessionen. Inställningarna bör efterlikna de inställningar som används av den faktiska indexeraren. Alla indexerare som du anger i en felsökningssession har ingen effekt på själva indexeraren.

  10. Konfigurationen bör se ut ungefär som den här skärmbilden. Välj Spara session för att komma igång.

    Skärmbild av en felsökningssessionssida.

Felsökningssessionen börjar med att köra indexeraren och kunskapsuppsättningen i det valda dokumentet. Dokumentets innehåll och metadata som skapas kommer att vara synliga och tillgängliga i sessionen.

En felsökningssession kan avbrytas medan den körs med knappen Avbryt . Om du trycker på knappen Avbryt bör du kunna analysera partiella resultat.

Det förväntas att en felsökningssession tar längre tid att köra än indexeraren eftersom den genomgår extra bearbetning.

Börja med fel och varningar

Indexerarens körningshistorik i portalen ger dig den fullständiga fel- och varningslistan för alla dokument. I en felsökningssession begränsas felen och varningarna till ett dokument. Du kommer att gå igenom den här listan, göra dina ändringar och sedan gå tillbaka till listan för att kontrollera om problem har lösts.

Om du vill visa meddelandena väljer du en färdighet i AI Enrichment > Skill Graph och väljer sedan Fel/varningar i informationsfönstret .

Vi rekommenderar att du löser problem med indata innan du går vidare till utdata.

Följ dessa steg för att bevisa om en ändring löser ett fel:

  1. Välj Spara i fönstret kunskapsinformation för att bevara dina ändringar.

  2. Välj Kör i sessionsfönstret för att anropa körning av kompetensuppsättningar med den ändrade definitionen.

  3. Gå tillbaka till Fel/varningar för att se om antalet har minskats. Listan uppdateras inte förrän du öppnar fliken.

Visa innehåll för berikningsnoder

AI-berikande pipelines extraherar eller härleder information och struktur från källdokument, vilket skapar ett berikat dokument i processen. Ett berikat dokument skapas först under dokumentets sprickbildning och fylls med en rotnod (/document), plus noder för allt innehåll som lyfts direkt från datakällan, till exempel metadata och dokumentnyckeln. Fler noder skapas av färdigheter under färdighetskörningen, där varje kunskapsutdata lägger till en ny nod i berikningsträdet.

Berikade dokument är interna, men en felsökningssession ger dig åtkomst till innehållet som skapas under färdighetskörningen. Följ dessa steg om du vill visa innehållet eller utdata för varje färdighet:

  1. Börja med standardvyerna: AI-berikande > Skill Graph, med graftypen inställd på Dependency Graph.

  2. Välj en färdighet.

  3. I informationsfönstret till höger väljer du Körningar, väljer utdata och öppnar sedan uttrycksutvärderingen (</>) för att visa uttrycket och dess resultat.

    Skärmbild av en färdighetskörning som visar utdatavärden.

  4. Du kan också öppna AI-berikad > datastruktur för att rulla nedåt i listan över noder. Listan innehåller potentiella och faktiska noder, med en kolumn för utdata och en annan kolumn som anger det överordnade objektet som används för att producera utdata.

    Skärmbild av berikat dokument som visar utdatavärden.

Redigera kunskapsdefinitioner

Om fältmappningarna är korrekta kontrollerar du enskilda kunskaper om konfiguration och innehåll. Om en färdighet inte kan generera utdata kanske den saknar en egenskap eller parameter, som kan fastställas genom fel- och valideringsmeddelanden.

Andra problem, till exempel ett ogiltigt kontext- eller indatauttryck, kan vara svårare att lösa eftersom felet talar om för dig vad som är fel, men inte hur du åtgärdar det. Hjälp med kontext- och indatasyntax finns i Referensberikningar i en Azure AI Search-kompetensuppsättning. Hjälp med enskilda meddelanden finns i Felsöka vanliga indexeringsfel och varningar.

Följande steg visar hur du hämtar information om en färdighet.

  1. I Kunskapsdiagram för AI-berikande > väljer du en färdighet. Fönstret Kunskapsinformation öppnas till höger.

  2. Redigera en färdighetsdefinition med någon av dessa metoder:

    • Kunskap Inställningar om du föredrar en visuell redigerare
    • Skill JSON-redigeraren för att redigera JSON-dokumentet direkt

  3. Kontrollera sökvägssyntaxen för att referera till noder i ett berikande träd. Följande är några av de vanligaste indatasökvägarna:

    • /document/content för textsegment. Den här noden fylls i från blobens innehållsegenskap.
    • /document/merged_content för textsegment i kunskapsuppsättningar som innehåller kunskaper om sammanslagning av text.
    • /document/normalized_images/* för text som identifieras eller härleds från bilder.

Kontrollera fältmappningar

Om kunskaper genererar utdata men sökindexet är tomt kontrollerar du fältmappningarna. Fältmappningar anger hur innehållet flyttas från pipelinen och till ett sökindex.

  1. Börja med standardvyerna: AI-berikande > Skill Graph, med graftypen inställd på Dependency Graph.

  2. Välj Fältmappningar längst upp. Du bör hitta åtminstone den dokumentnyckel som unikt identifierar och associerar varje sökdokument i sökindexet med dess källdokument i datakällan.

    Om du importerar råinnehåll direkt från datakällan och kringgår berikning bör du hitta dessa fält i Fältmappningar.

  3. Välj Mappningar för utdatafält längst ned i diagrammet. Här hittar du mappningar från kunskapsutdata till målfält i sökindexet. Om du inte använde guiden Importera data definieras mappningar för utdatafält manuellt och kan vara ofullständiga eller feltypade.

    Kontrollera att fälten i Mappningar av utdatafält finns i sökindexet efter angivet, och kontrollera om det finns syntax för stavnings- och berikningsnodsökväg.

    Skärmbild av noden Mappningar av utdatafält och information.

Felsöka en anpassad färdighet lokalt

Anpassade kunskaper kan vara svårare att felsöka eftersom koden körs externt, så felsökningssessionen kan inte användas för att felsöka dem. I det här avsnittet beskrivs hur du lokalt felsöker din anpassade webb-API-färdighet, felsökningssession, Visual Studio Code och ngrok eller Tunnelmole. Den här tekniken fungerar med anpassade kunskaper som körs i Azure Functions eller något annat webbramverk som körs lokalt (till exempel FastAPI).

Hämta en offentlig URL

Använda Tunnelmole

Tunnelmole är ett öppen källkod tunnelverktyg som kan skapa en offentlig URL som vidarebefordrar begäranden till din lokala dator via en tunnel.

  1. Installera Tunnelmole:

    • 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: Installera med npm. Eller om du inte har NodeJS installerat laddar du ned den förkompilerade .exe-filen för Windows och placerar den någonstans i din PATH.

  2. Kör det här kommandot för att skapa en ny tunnel:

    tmole 7071

    Du bör se ett svar som ser ut så här:

    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

    I föregående exempel https://m5hdpb-ip-49-183-170-144.tunnelmole.net vidarebefordras till porten 7071 på den lokala datorn, vilket är standardporten där Azure-funktioner exponeras.

Använda ngrok

ngrok är en populär, sluten källa, plattformsoberoende program som kan skapa en url för tunneltrafik eller vidarebefordran så att internetbegäranden når din lokala dator. Använd ngrok för att vidarebefordra begäranden från en berikningspipeline i söktjänsten till datorn för att tillåta lokal felsökning.

  1. Installera ngrok.

  2. Öppna en terminal och gå till mappen med den körbara ngrok-filen.

  3. Kör ngrok med följande kommando för att skapa en ny tunnel:

    ngrok http 7071

    Kommentar

    Som standard exponeras Azure-funktioner på 7071. Andra verktyg och konfigurationer kan kräva att du anger en annan port.

  4. När ngrok startar kopierar och sparar du url:en för offentlig vidarebefordran för nästa steg. Vidarebefordrings-URL:en genereras slumpmässigt.

    Skärmbild av ngrok-terminalen.

Konfigurera i Azure Portal

I felsökningssessionen ändrar du din anpassade webb-API Skill URI så att den anropar URL:en för vidarebefordran av Tunnelmole eller ngrok. Se till att du lägger till "/api/FunctionName" när du använder Azure Function för att köra koden för kompetensuppsättningen.

Du kan redigera kunskapsdefinitionen i portalen.

Testa koden

Nu ska nya begäranden från felsökningssessionen skickas till din lokala Azure-funktion. Du kan använda brytpunkter i Visual Studio Code för att felsöka koden eller köra den steg för steg.

Nästa steg

Nu när du förstår layouten och funktionerna i det visuella redigeringsprogrammet för felsökningssessioner kan du prova självstudien för en praktisk upplevelse.

Självstudie: Utforska felsökningssessioner