Skapa en kompetensuppsättning i Azure AI Search

En kompetensuppsättning definierar åtgärder som genererar textinnehåll och struktur från dokument som innehåller bilder eller ostrukturerad text. Exempel är optisk teckenigenkänning (OCR) för bilder, entitetsigenkänning för oberörd text och textöversättning. En kompetensuppsättning körs när text och bilder har extraherats från en extern datakälla och efter att fältmappningar har bearbetats .

Den här artikeln beskriver hur du skapar en kompetensuppsättning med hjälp av REST-API:er, men samma begrepp och steg gäller för andra programmeringsspråk.

Regler för kompetensuppsättningsdefinition är:

• Måste ha ett unikt namn i kunskapsuppsättningssamlingen. En kompetensuppsättning är en resurs på den översta nivån som kan användas av alla indexerare.
• Måste ha minst en färdighet. Tre till fem färdigheter är typiska. Maxvärdet är 30.
• En kompetensuppsättning kan upprepa färdigheter av samma typ. En kompetensuppsättning kan till exempel ha flera Formverktygskunskaper.
• En kompetensuppsättning stöder länkade åtgärder, loopning och förgrening.

Indexerare driver kompetensuppsättningskörning. Du behöver en indexerare, datakälla och index innan du kan testa din kompetensuppsättning.

Lägga till en definition för kompetensuppsättning

Börja med den grundläggande strukturen. I REST-API:et Create Skillset (Skapa kunskapsuppsättning) skapas brödtexten för begäran i JSON och innehåller följande avsnitt:

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"An Azure AI services resource in the same region as Azure AI Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

Efter namnet och beskrivningen har en kompetensuppsättning fyra huvudegenskaper:

• skills matris, en osorterad samling med kunskaper. Färdigheter kan vara utilitaristiska (som att dela upp text), transformering (baserat på AI från Azure AI-tjänster) eller anpassade färdigheter som du tillhandahåller. Ett exempel på en kompetensmatris finns i nästa avsnitt.

• cognitiveServicesanvänds för fakturerbara färdigheter som anropar API:er för Azure AI-tjänster. Ta bort det här avsnittet om du inte använder fakturerbara kunskaper eller anpassad entitetssökning. Om du är det ansluter du en Azure AI-resurs med flera tjänster.

• knowledgeStore (valfritt) anger ett Azure Storage-konto och inställningar för att projicera kunskapsuppsättningens utdata till tabeller, blobbar och filer i Azure Storage. Ta bort det här avsnittet om du inte behöver det, annars anger du ett kunskapslager.

• encryptionKey(valfritt) anger ett Azure Key Vault och kundhanterade nycklar som används för att kryptera känsligt innehåll (beskrivningar, anslutningssträng, nycklar) i en kompetensuppsättningsdefinition. Ta bort den här egenskapen om du inte använder kundhanterad kryptering.

Lägga till kunskaper

I kompetensuppsättningsdefinitionen anger kompetensmatrisen vilka färdigheter som ska köras. Tre till fem färdigheter är vanliga, men du kan lägga till så många färdigheter som behövs, med förbehåll för tjänstbegränsningar.

Slutresultatet av en berikningspipeline är textinnehåll i antingen ett sökindex eller ett kunskapslager. Därför kan de flesta kunskaper antingen skapa text från bilder (OCR-text, undertexter, taggar) eller analysera befintlig text för att skapa ny information (entiteter, nyckelfraser, sentiment). Kunskaper som fungerar självständigt bearbetas parallellt. Färdigheter som är beroende av varandra anger utdata från en färdighet (till exempel nyckelfraser) som indata för en andra färdighet (till exempel textöversättning). Söktjänsten avgör ordningen på färdighetskörningen och körningsmiljön.

Alla kunskaper har en typ, kontext, indata och utdata. En färdighet kan ha ett namn och en beskrivning. I följande exempel visas två orelaterade inbyggda kunskaper så att du kan jämföra den grundläggande strukturen.

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

Varje färdighet är unik när det gäller dess indatavärden och de parametrar som krävs. Dokumentation om kunskapsreferens beskriver alla parametrar och egenskaper för en viss färdighet. Även om det finns skillnader delar de flesta färdigheter en gemensam uppsättning och är lika mönstrade.

Ange kompetenskontext

Varje färdighet har en kontextegenskap som avgör på vilken nivå åtgärderna ska utföras. Om egenskapen context inte uttryckligen anges är "/document"standardvärdet , där kontexten är hela dokumentet (färdigheten anropas en gång per dokument).

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

Egenskapen context är vanligtvis inställd på något av följande exempel:

Kontexten avgör också var utdata produceras i berikningsträdet. Entitetsigenkänningsfärdigheten returnerar till exempel en egenskap med namnet organizations, insamlad som orgs. Om kontexten är "/document"läggs en organizations nod till som underordnad "/document". Om du sedan vill referera till den här noden i underordnade kunskaper är "/document/orgs"sökvägen .

Definiera indata

Kunskaper som läse från och skriver till ett berikat dokument. Kunskapsindata anger ursprunget för inkommande data. Det är ofta rotnoden i det berikade dokumentet. För blobar är en typisk kunskapsinmatning dokumentets innehållsegenskap.

Kunskapsreferensdokumentation för varje färdighet beskriver de indata som den kan använda. Varje indata har en name som identifierar en specifik indata och en source som anger platsen för data i det berikade dokumentet. Följande exempel är från entitetsigenkänningsfärdigheten:

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

• Kunskaper kan ha flera indata. name är de specifika indata. För Entitetsigenkänning är de specifika indata text och languageCode.

• Egenskapen source anger vilket fält eller vilken rad som innehåller det innehåll som ska bearbetas. För textbaserade kunskaper är källan ett fält i dokumentet eller raden som innehåller text. För bildbaserade kunskaper normaliseras den nod som tillhandahåller indata.

  Källexempel	beskrivning
  source: /document	För en tabelldatauppsättning motsvarar ett dokument en rad.
  source: /document/content	För blobar är källan vanligtvis blobens innehållsegenskap.
  source: /document/some-named-field	För textbaserade kunskaper, till exempel entitetsigenkänning eller extrahering av nyckelfraser, bör ursprunget vara ett fält som innehåller tillräckligt med text som ska analyseras, till exempel en beskrivning eller sammanfattning.
  source: /document/normalized_images/*	För bildinnehåll är källan en bild som har normaliserats under dokumentsprickor.

Om kunskapen itererar över en matris bör både kontexten och indatakällan inkluderas /* i rätt positioner.

Definiera utmatningar

Varje färdighet är utformad för att generera specifika typer av utdata, som refereras till med namn i kompetensuppsättningen. En färdighetsutdata har en name och en valfri targetName.

Kunskapsreferensdokumentation för varje färdighet beskriver de utdata som den kan generera. Följande exempel är från entitetsigenkänningsfärdigheten:

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

• Kunskaper kan ha flera utdata. Egenskapen name identifierar ett specifikt utdata. För Entitetsigenkänning kan utdata till exempel vara personer, platser, organisationer.

• Egenskapen targetName anger det namn som du vill att noden ska ha i det berikade dokumentet. Detta är användbart om kunskapsutdata har samma namn. Om du har flera kunskaper som returnerar samma utdata använder targetName du för namndisambition i anrikningsnodsökvägar. Om målnamnet är ospecificerat används namnegenskapen för båda.

Vissa situationer anropar för att referera till varje element i en matris separat. Anta till exempel att du vill skicka varje element "/document/orgs" separat till en annan färdighet. Det gör du genom att lägga till en asterisk i sökvägen: "/document/orgs/*".

Kunskapsutdata skrivs till det berikade dokumentet som en ny nod i berikningsträdet. Det kan vara ett enkelt värde, till exempel en attitydpoäng eller språkkod. Det kan också vara en samling, till exempel en lista över organisationer, personer eller platser. Kunskapsutdata kan också vara en komplex struktur, vilket är fallet med Shaper-färdigheten. Indata för färdigheten avgör formens sammansättning, men utdata är det namngivna objektet, som kan refereras till i ett sökindex, en kunskapslagerprojektion eller en annan färdighet med dess namn.

Lägga till en anpassad färdighet

Det här avsnittet innehåller ett exempel på en anpassad färdighet. URI:n pekar på en Azure-funktion som i sin tur anropar den modell eller transformering som du anger. Mer information finns i Lägga till en anpassad färdighet i en Azure AI Search-pipeline för berikning.

Även om den anpassade färdigheten kör kod som är extern för pipelinen, är det bara en annan färdighet i en kompetensmatris. Precis som de inbyggda färdigheterna har den en typ, kontext, indata och utdata. Den läser och skriver också till ett berikande träd, precis som de inbyggda färdigheterna gör. Observera att fältet context är inställt på med en asterisk, vilket innebär att "/document/orgs/*" berikningssteget anropas för varje organisation under "/document/orgs".

Utdata, till exempel företagsbeskrivningen i det här exemplet, genereras för varje organisation som identifieras. När du refererar till noden i ett nedströmssteg (till exempel i extrahering av nyckelfraser) använder du sökvägen "/document/orgs/*/companyDescription" för att göra det.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=foo",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "foobar"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Skicka utdata till ett mål

Även om kunskapsutdata kan cachelagras i återanvändningssyfte är det vanligtvis tillfälligt och finns bara medan färdighetskörning pågår.

• Om du vill skicka utdata till ett fält i ett sökindex skapar du en mappning av utdatafält i en indexerare.

• Skapa en projektion för att skicka utdata till ett kunskapslager.

• Om du vill skicka utdata till en underordnad kunskap refererar du till utdata med dess nodnamn, till exempel "/document/organization", i den underordnade färdighetens indatakällegenskap. Exempel finns i Referera till en anteckning .

Tips för en första kompetensuppsättning

• Prova guiden Importera data eller guiden Importera och vektorisera data.

  Guiderna automatiserar flera steg som kan vara svåra första gången. Den definierar kompetensuppsättningen, indexet och indexeraren, inklusive fältmappningar och mappningar av utdatafält. Den definierar också projektioner i ett kunskapslager om du använder ett. För vissa kunskaper, till exempel OCR eller bildanalys, lägger guiden till verktygskunskaper som sammanfogar det bild- och textinnehåll som avgränsades under dokumentsprickor.

  När guiden har körts kan du öppna varje objekt i Azure Portal för att visa dess JSON-definition.

• Prova att felsöka sessioner för att anropa körning av kompetensuppsättningar över ett måldokument och inspektera det berikade dokument som kunskapsuppsättningen skapar. Du kan visa och ändra inställningar och värden för indata och utdata. Den här självstudien är ett bra ställe att börja på: Självstudie: Felsöka en kompetensuppsättning med hjälp av felsökningssessioner.

Gå vidare

Kontext- och indatakällafält är sökvägar till noder i ett berikande träd. Som ett nästa steg kan du lära dig mer om sökvägssyntaxen för noder i ett berikande träd.