Een vaardighedenset maken in Azure Cognitive Search

Een vaardighedenset definieert de bewerkingen die gegevens extraheren en verrijken om deze doorzoekbaar te maken. Een vaardighedenset wordt uitgevoerd nadat het document is gekraakt, wanneer tekst- en afbeeldingsinhoud worden geëxtraheerd uit brondocumenten en nadat velden uit het brondocument (optioneel) zijn toe te staan aan doelvelden in een index of kennisopslag.

In dit artikel leert u de stappen voor het maken van een vaardighedenset. Ter referentie wordt in dit artikel de vaardighedenset maken (REST API) gebruikt.

Enkele gebruiksregels voor vaardighedensets zijn onder andere:

• Een vaardighedenset is een resource op het hoogste niveau, wat betekent dat er één keer naar kan worden verwezen door veel indexeren.
• Een vaardighedenset moet ten minste één vaardigheid bevatten.
• Een vaardighedenset kan vaardigheden van hetzelfde type herhalen (bijvoorbeeld meerdere Shaper-vaardigheden).

Denk eraan dat indexeerders de uitvoering van vaardighedensets aanroepen, wat betekent dat u ook een indexer,gegevensbron en zoekindex moet maken voordat u uw vaardighedenset kunt testen.

Definitie set vaardigheden

Begin met de basisstructuur. In de REST APIwordt een vaardighedenset geschreven in JSON en heeft deze de volgende secties:

{
   "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":"A Cognitive Services resource in the same region as Azure Cognitive Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

Na de naam en beschrijving heeft een vaardighedenset vier hoofdeigenschappen:

• skills array, een niet-ordenen verzameling vaardigheden,waarvoor de zoekservice de volgorde van de uitvoering bepaalt op basis van de invoer die vereist is voor elke vaardigheid. Als vaardigheden onafhankelijk zijn, worden ze parallel uitgevoerd. Vaardigheden kunnen hulpprogramma's zijn (zoals het splitsen van tekst), transformationeel (op basis van AI van Cognitive Services) of aangepaste vaardigheden die u op maat maakt. In de volgende sectie wordt een voorbeeld gegeven van een vaardigheden array.

• cognitiveServiceswordt gebruikt voor factureerbare vaardigheden die de Cognitive Services-API's. Verwijder deze sectie als u geen factureerbare vaardigheden of Custom Entity Lookup gebruikt. Voeg een resource toe als u dat wel bent.

• knowledgeStore, (optioneel) geeft een Azure Storage-account en instellingen voor het projecteren van uitvoer van vaardighedensets in tabellen, blobs en bestanden in Azure Storage. Verwijder deze sectie als u deze niet nodig hebt, anders geeft u een kennisopslag op.

• encryptionKey, (optioneel) geeft een Azure Key Vault en door de klant beheerde sleutels die worden gebruikt voor het versleutelen van gevoelige inhoud in een definitie van een vaardighedenset. Verwijder deze eigenschap als u geen door de klant beheerde versleuteling gebruikt.

Een vaardigheden array toevoegen

Binnen een definitie van een vaardighedenset geeft de vaardighedenmatrix aan welke vaardigheden moeten worden uitgevoerd. In het volgende voorbeeld maakt u kennis met de samenstelling ervan door twee niet-gerelateerde, ingebouwde vaardigheden weer te geven. U ziet dat elke vaardigheid een type, context, invoer en uitvoer heeft.

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "categories": [ "Organization" ],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "organizations",
        "targetName": "orgs"
      }
    ]
  },
  {
    "@odata.type": "#Microsoft.Skills.Text.SentimentSkill",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "score",
        "targetName": "mySentiment"
      }
    ]
  }
]

Hoe ingebouwde vaardigheden zijn gestructureerd

Elke vaardigheid is uniek wat betreft de invoerwaarden en de parameters die nodig zijn. In de documentatie voor elke vaardigheid worden alle parameters en eigenschappen van een bepaalde vaardigheid beschreven. Hoewel er verschillen zijn, delen de meeste vaardigheden een gemeenschappelijke set en hebben ze een vergelijkbaar patroon. Ter illustratie van verschillende punten biedt de vaardigheid Entiteitsherkenning een voorbeeld:

{
  "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
  "context": "/document",
  "categories": [ "Organization" ],
  "defaultLanguageCode": "en",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "organizations",
      "targetName": "orgs"
    }
  ]
}

Algemene parameters zijn 'odata.type', 'inputs' en 'outputs'. De andere parameters, namelijk 'categories' en 'defaultLanguageCode', zijn voorbeelden van parameters die specifiek zijn voor Entiteitsherkenning.

• 'odata.type' identificeert elke vaardigheid op unieke manier. U vindt het type in de referentiedocumentatie voor vaardigheden.

• 'context' is een knooppunt in een verrijkingsstructuur en vertegenwoordigt het niveau waarop bewerkingen worden uitgevoerd. Alle vaardigheden hebben deze eigenschap. Als het veld 'context' niet expliciet is ingesteld, is de standaardcontext "/document" . In het voorbeeld is de context het hele document, wat betekent dat de vaardigheid entiteitsherkenning eenmaal per document wordt aangeroepen.

  De context bepaalt ook waar uitvoer wordt geproduceerd in de verrijkingsstructuur. In dit voorbeeld retourneert de vaardigheid een eigenschap met de naam , vastgelegd "organizations" als , die wordt toegevoegd als een onderliggend orgs knooppunt van "/document" . In downstreamvaardigheden is het pad naar dit zojuist gemaakte verrijkings-knooppunt "/document/orgs" . Voor een bepaald document is de waarde van een matrix van organisaties die zijn "/document/orgs" geëxtraheerd uit de tekst (bijvoorbeeld: ["Microsoft", "LinkedIn"] ). Zie Referencing annotations in a skillset (Verwijzen naar aantekeningen in een vaardighedenset) voor meer informatie over padsyntaxis.

• Invoer geeft de oorsprong van de binnenkomende gegevens op en hoe deze worden gebruikt. In het geval van Entiteitsherkenning is een van de invoergegevens . Dit is de inhoud die moet worden "text" geanalyseerd voor entiteiten. De inhoud wordt afkomstig van het "/document/content" knooppunt in een verrijkingsstructuur. In een verrijkingsstructuur "/document" is het hoofd knooppunt. Voor documenten die zijn opgehaald met behulp van een Azure Blob-indexer, is het veld van elk document een content standaardveld dat is gemaakt door de indexer.

• 'outputs' vertegenwoordigen de uitvoer van de vaardigheid. Elke vaardigheid is ontworpen om specifieke soorten uitvoer uit te geven waarnaar wordt verwezen met de naam in de vaardighedenset. In het geval van Entiteitsherkenning "organizations" is een van de uitvoer die wordt ondersteund. De documentatie voor elke vaardigheid beschrijft de uitvoer die deze kan produceren.

Uitvoer bestaat alleen tijdens de verwerking. Als u deze uitvoer wilt vastketenen aan de invoer van een downstream-vaardigheid, verwijst u naar de uitvoer als "/document/orgs" . Als u uitvoer wilt verzenden naar een veld in een zoekindex, maakt u een toewijzing van uitvoerveld in een indexer. Als u uitvoer naar een kennisopslag wilt verzenden, maakt u een projectie.

De uitvoer van de ene vaardigheid kan conflicteren met uitvoer van een andere vaardigheid. Als u meerdere vaardigheden hebt die dezelfde uitvoer retourneren, gebruikt u de voor "targetName" naamsambiguïteit in verrijkings knooppuntpaden.

In sommige situaties is het nodig om afzonderlijk naar elk element van een matrix te verwijzen. Stel bijvoorbeeld dat u elk element van afzonderlijk wilt doorgeven aan een andere "/document/orgs" vaardigheid. Voeg een sterretje toe aan het pad om dit te doen: "/document/orgs/*"

De tweede vaardigheid voor sentimentanalyse volgt hetzelfde patroon als de eerste verrijker. Deze neemt "/document/content" als invoer en retourneert een gevoelsscore voor elk exemplaar van de inhoud. Omdat u het veld 'context' niet expliciet hebt ingesteld, is de uitvoer (mySentiment) nu een onderliggende van "/document" .

{
  "@odata.type": "#Microsoft.Skills.Text.SentimentSkill",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "score",
      "targetName": "mySentiment"
    }
  ]
}

Een aangepaste vaardigheid toevoegen

Hieronder vindt u een voorbeeld van een aangepaste vaardigheid. De URI wijst naar een Azure-functie, die op zijn beurt het model of de transformatie aanroept die u op biedt. Zie Een aangepaste interface definiëren voor meer informatie.

Hoewel met de aangepaste vaardigheid code wordt uitgevoerd die extern is aan de pijplijn, is het in een vaardigheden array gewoon een andere vaardigheid. Net als de ingebouwde vaardigheden heeft het een type, context, invoer en uitvoer. Het leest en schrijft ook naar een verrijkingsstructuur, net zoals de ingebouwde vaardigheden doen. U ziet dat het contextveld is ingesteld op met een sterretje, wat betekent dat de verrijkingsstap wordt aangeroepen "/document/orgs/*" voor elke organisatie onder "/document/orgs" .

Uitvoer, in dit geval een bedrijfsbeschrijving, wordt gegenereerd voor elke geïdentificeerde organisatie. Wanneer u verwijst naar de beschrijving in een downstream-stap (bijvoorbeeld bij sleuteltermextractie), gebruikt u het pad "/document/orgs/*/companyDescription" om dit te doen.

{
  "@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"
    }
  ]
}

Uitvoer verzenden naar een index

Terwijl elke vaardigheid wordt uitgevoerd, wordt de uitvoer ervan toegevoegd als knooppunten in de verrijkingsstructuur van een document. Verrijkte documenten bestaan in de pijplijn als tijdelijke gegevensstructuren. Als u een permanente gegevensstructuur wilt maken en volledig inzicht wilt krijgen in wat een vaardigheid daadwerkelijk produceert, moet u de uitvoer verzenden naar een zoekindex of een kennisopslag.

In de eerste fasen van de evaluatie van vaardighedensets wilt u de voorlopige resultaten met minimale inspanning controleren. We raden de zoekindex aan omdat deze eenvoudiger is in te stellen. Definieer voor elke vaardigheidsuitvoer een toewijzing van uitvoerveld in de indexer en een veld in de index.

Nadat u de indexeringsfunctie hebt uitgevoerd, kunt u Search Explorer gebruiken om documenten uit de index te retourneren en de inhoud van elk veld te controleren om te bepalen wat de vaardighedenset heeft gedetecteerd of gemaakt.

In het volgende voorbeeld ziet u de resultaten van een vaardigheid voor entiteitsherkenning die personen, locaties, organisaties en andere entiteiten in een tekstvak heeft gedetecteerd. Als u de resultaten in Search Explorer bekijkt, kunt u bepalen of een vaardigheid waarde toevoegt aan uw oplossing.

Tips voor een eerste vaardighedenset

• Stel een representatief voorbeeld van uw inhoud samen in Blob Storage of een andere ondersteunde indexeergegevensbron en voer de wizard Gegevens importeren uit om het vaardighedenset-, index-, indexeer- en gegevensbronobject te maken.

  De wizard automatiseert verschillende stappen die de eerste keer lastig kunnen zijn, waaronder het definiëren van de velden in een index, het definiëren van toewijzingen van opgeslagen uitvoer in een indexer en projecties in een kennisopslag als u er een gebruikt. Voor bepaalde vaardigheden, zoals OCR of afbeeldingsanalyse, voegt de wizard hulpprogrammavaardigheden toe die afbeeldings- en tekstinhoud samenvoegen die zijn gescheiden tijdens het kraken van het document.

• U kunt ook Postman-verzamelingen voor vaardigheden importeren die volledige voorbeelden bieden van alle objectdefinities die nodig zijn om een vaardigheid te evalueren, van vaardighedenset naar een index die u kunt opvragen om de resultaten van een transformatie weer te geven.

Volgende stappen

Context- en invoerbronvelden zijn paden naar knooppunten in een verrijkingsstructuur. Als volgende stap leert u meer over de syntaxis voor het instellen van paden naar knooppunten in een verrijkingsstructuur.