Een vaardighedenset maken in Azure AI Search

  • Artikel

indexer stages

Een vaardighedenset definieert bewerkingen die tekstuele inhoud en structuur genereren op basis van documenten die afbeeldingen of ongestructureerde tekst bevatten. Voorbeelden zijn OCR voor afbeeldingen, entiteitsherkenning voor niet-gedifferentieerde tekst en tekstomzetting. Een vaardighedenset wordt uitgevoerd nadat tekst en afbeeldingen zijn geëxtraheerd uit een externe gegevensbron en nadat veldtoewijzingen zijn verwerkt.

In dit artikel wordt uitgelegd hoe u een vaardighedenset maakt met REST API's, maar dezelfde concepten en stappen zijn van toepassing op andere programmeertalen.

Regels voor de definitie van vaardighedenset zijn onder andere:

  • Een unieke naam binnen de verzameling vaardighedensets. Een vaardighedenset is een resource op het hoogste niveau die door elke indexeerfunctie kan worden gebruikt.
  • Ten minste één vaardigheid. Drie tot vijf vaardigheden zijn typisch. Het maximum is 30.
  • Een vaardighedenset kan vaardigheden van hetzelfde type herhalen (bijvoorbeeld meerdere Shaper-vaardigheden).
  • Een vaardighedenset biedt ondersteuning voor ketenbewerkingen, lussen en vertakkingen.

Indexeerfuncties stimuleren de uitvoering van vaardighedensets. U hebt een indexeerfunctie, gegevensbron en index nodig voordat u uw vaardighedenset kunt testen.

Tip

Schakel verrijkingscaching in om de inhoud die u al hebt verwerkt, opnieuw te gebruiken en de ontwikkelingskosten te verlagen.

Een definitie van een vaardighedenset toevoegen

Begin met de basisstructuur. In de CREATE Skillset REST API wordt de hoofdtekst van de aanvraag geschreven in JSON en bevat 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":"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":{ }
}

Na de naam en beschrijving heeft een vaardighedenset vier hoofdeigenschappen:

  • skills matrix, een niet-geordende verzameling vaardigheden. Vaardigheden kunnen utilitar zijn (zoals het splitsen van tekst), transformationeel (op basis van AI van Azure AI-services) of aangepaste vaardigheden die u biedt. In de volgende sectie vindt u een voorbeeld van een vaardighedenmatrix.

  • cognitiveServices wordt gebruikt voor factureerbare vaardigheden die API's van Azure AI-services aanroepen. 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 op voor het projecteren van vaardighedensetuitvoer in tabellen, blobs en bestanden in Azure Storage. Verwijder deze sectie als u deze niet nodig hebt, anders geeft u een kennisarchief op.

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

Vaardigheden toevoegen

In de definitie van de vaardighedenset geeft de vaardighedenmatrix aan welke vaardigheden moeten worden uitgevoerd. Drie tot vijf vaardigheden zijn gebruikelijk, maar u kunt zoveel vaardigheden toevoegen als nodig is, afhankelijk van servicelimieten.

Het eindresultaat van een verrijkingspijplijn is tekstuele inhoud in een zoekindex of een kennisarchief. Daarom maken de meeste vaardigheden tekst op basis van afbeeldingen (OCR-tekst, onderschrift s, tags) of analyseert u bestaande tekst om nieuwe informatie te maken (entiteiten, sleuteltermen, sentiment). Vaardigheden die onafhankelijk werken, worden parallel verwerkt. Vaardigheden die afhankelijk zijn van elkaar geven de uitvoer van één vaardigheid (zoals sleuteltermen) op als invoer van de tweede vaardigheid (zoals tekstomzetting). De zoekservice bepaalt de volgorde van de uitvoering van vaardigheden en de uitvoeringsomgeving.

Alle vaardigheden hebben een type, context, invoer en uitvoer. Een vaardigheid kan eventueel een naam en beschrijving hebben. In het volgende voorbeeld ziet u twee niet-gerelateerde ingebouwde vaardigheden , zodat u de basisstructuur kunt vergelijken.

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

Elke vaardigheid is uniek in termen van de invoerwaarden en de parameters die nodig zijn. Referentiedocumentatie over vaardigheden beschrijft alle parameters en eigenschappen van een bepaalde vaardigheid. Hoewel er verschillen zijn, delen de meeste vaardigheden een gemeenschappelijke set en zijn ze vergelijkbaar met patroon.

Notitie

U kunt complexe vaardighedensets bouwen met lussen en vertakkingen met behulp van de voorwaardelijke vaardigheid om de expressies te maken. De syntaxis is gebaseerd op de JSON Pointer-pad notatie, met enkele wijzigingen om knooppunten in de verrijkingsstructuur te identificeren. Een "/" doorkruist een niveau lager in de structuur en "*" fungeert als een operator voor elke operator in de context. Veel voorbeelden in dit artikel illustreren de syntaxis.

Vaardigheidscontext instellen

Elke vaardigheid heeft een contexteigenschap die bepaalt op welk niveau bewerkingen plaatsvinden. Als de eigenschap 'context' niet expliciet is ingesteld, is "/document"de standaardwaarde, waarbij de context het hele document is (de vaardigheid wordt eenmaal per document aangeroepen).

"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": []
  }
]

Context is meestal ingesteld op een van de volgende voorbeelden:

Contextvoorbeeld Beschrijving
"context": "/document" (Standaard) Invoer en uitvoer bevinden zich op documentniveau.
"context": "/document/pages/*" Sommige vaardigheden, zoals sentimentanalyse, presteren beter dan kleinere stukken tekst. Als u een groot inhoudsveld splitst in pagina's of zinnen, moet de context over elk onderdeel worden verdeeld.
"context": "/document/normalized_images/*" Voor afbeeldingsinhoud zijn invoer en uitvoer één per afbeelding in het bovenliggende document.

Context bepaalt ook waar uitvoer wordt geproduceerd in de verrijkingsstructuur. De vaardigheid Entiteitsherkenning retourneert bijvoorbeeld een eigenschap met de naam "organizations", vastgelegd als orgs. Als de context is "/document", wordt een knooppunt 'organisaties' toegevoegd als een onderliggend element van "/document". Als u vervolgens naar dit knooppunt wilt verwijzen in downstreamvaardigheden, zou het pad zijn "/document/orgs".

Invoer definiëren

Vaardigheden lezen van en schrijven naar een verrijkt document. Invoer van vaardigheden geeft de oorsprong van de binnenkomende gegevens op. Dit is vaak het hoofdknooppunt van het verrijkte document. Voor blobs is een typische vaardigheidsinvoer de inhoudseigenschap van het document.

Referentiedocumentatie voor vaardigheden voor elke vaardigheid beschrijft de invoer die deze kan gebruiken. Elke invoer heeft een 'naam' die een specifieke invoer identificeert en een 'bron' die de locatie aangeeft van de gegevens in het verrijkte document. Het volgende voorbeeld is afkomstig van de vaardigheid Entiteitsherkenning:

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

  • Vaardigheden kunnen meerdere invoer hebben. De 'naam' is de specifieke invoer. Voor Entiteitsherkenning zijn de specifieke invoer 'tekst' en 'languageCode'.

  • De eigenschap Bron geeft aan welk veld of welke rij de inhoud bevat die moet worden verwerkt. Voor op tekst gebaseerde vaardigheden is de bron een veld in het document of de rij die tekst biedt. Voor vaardigheden op basis van afbeeldingen is het knooppunt dat de invoer levert genormaliseerde afbeeldingen.

    Bronvoorbeeld Beschrijving
    "source": "/document" Voor een gegevensset in tabelvorm komt een document overeen met een rij.
    "source": "/document/content" Voor blobs is de bron meestal de inhoudseigenschap van de blob.
    "source": "/document/some-named-field" Voor op tekst gebaseerde vaardigheden, zoals entiteitsherkenning of sleuteltermextractie, moet de oorsprong een veld zijn dat voldoende tekst bevat die moet worden geanalyseerd, zoals een 'beschrijving' of 'samenvatting'.
    "source": "/document/normalized_images/*" Voor afbeeldingsinhoud is de bron een afbeelding die is genormaliseerd tijdens het kraken van documenten.

Als de vaardigheid over een matrix wordt herhaald, moeten zowel de context als de invoerbron de juiste posities bevatten /* .

Uitvoer definiëren

Elke vaardigheid is ontworpen om specifieke soorten uitvoer te verzenden, waarnaar wordt verwezen op naam in de vaardighedenset. Een vaardigheidsuitvoer heeft een 'name' en een optionele targetName.

Referentiedocumentatie voor vaardigheden voor elke vaardigheid beschrijft de uitvoer die deze kan produceren. Het volgende voorbeeld is afkomstig van de vaardigheid Entiteitsherkenning:

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

  • Vaardigheden kunnen meerdere uitvoer hebben. De naam identificeert een specifieke uitvoer. Voor entiteitsherkenning kan de uitvoer bijvoorbeeld 'personen', 'locaties', 'organisaties' zijn.

  • 'targetName' geeft de naam op die dit knooppunt moet hebben in het verrijkte document. Dit is handig als uitvoer van vaardigheden dezelfde naam heeft. Als u meerdere vaardigheden hebt die dezelfde uitvoer retourneren, gebruikt u de "targetName" naamontdubbeling in verrijkingsknooppuntpaden. Als de doelnaam niet is opgegeven, wordt de naameigenschap gebruikt voor beide.

Sommige situaties vragen om afzonderlijk naar elk element van een matrix te verwijzen. Stel dat u elk element afzonderlijk "/document/orgs" aan een andere vaardigheid wilt doorgeven. Voeg hiervoor een sterretje toe aan het pad: "/document/orgs/*".

Uitvoer van vaardigheden wordt naar het verrijkte document geschreven als een nieuw knooppunt in de verrijkingsstructuur. Het kan een eenvoudige waarde zijn, zoals een gevoelsscore of taalcode. Het kan ook een verzameling zijn, zoals een lijst met organisaties, personen of locaties. Uitvoer van vaardigheden kan ook een complexe structuur zijn, zoals het geval is met de Shaper-vaardigheid. De invoer van de vaardigheid bepaalt de samenstelling van de shape, maar de uitvoer is het benoemde object, waarnaar kan worden verwezen in een zoekindex, een kennisarchiefprojectie of een andere vaardigheid op naam.

Een aangepaste vaardigheid toevoegen

Deze sectie bevat een voorbeeld van een aangepaste vaardigheid. De URI verwijst naar een Azure-functie, die op zijn beurt het model of de transformatie aanroept die u opgeeft. Zie Een aangepaste interface definiëren voor meer informatie.

Hoewel de aangepaste vaardigheid code uitvoert die zich buiten de pijplijn bevindt, is het in een vaardighedenmatrix 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 veld 'context' is ingesteld "/document/orgs/*" op een sterretje, wat betekent dat de verrijkingsstap wordt aangeroepen voor elke organisatie onder "/document/orgs".

Uitvoer, zoals de beschrijving van het bedrijf in dit voorbeeld, wordt gegenereerd voor elke organisatie die wordt geïdentificeerd. Wanneer u naar het knooppunt in een downstreamstap verwijst (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 bestemming

Hoewel uitvoer van vaardigheden optioneel kan worden opgeslagen voor hergebruik, is het meestal tijdelijk en bestaat deze alleen terwijl de uitvoering van vaardigheden wordt uitgevoerd.

  • Als u uitvoer naar een veld in een zoekindex wilt verzenden, maakt u een toewijzing van uitvoervelden in een indexeerfunctie.

  • Als u uitvoer naar een kennisarchief wilt verzenden, maakt u een projectie.

  • Als u uitvoer naar een downstream-vaardigheid wilt verzenden, verwijst u naar de uitvoer op basis van de naam van het knooppunt, zoals "/document/organization", in de invoerbroneigenschap van de downstream-vaardigheid. Zie Verwijzing naar een aantekening voor voorbeelden.

Tips voor een eerste vaardighedenset

  • Probeer de wizard Gegevens importeren.

    De wizard automatiseert verschillende stappen die de eerste keer lastig kunnen zijn. Hiermee definieert u de vaardighedenset, index en indexeerfunctie, inclusief veldtoewijzingen en uitvoerveldtoewijzingen. Het definieert ook projecties in een kennisarchief als u er een gebruikt. Voor sommige vaardigheden, zoals OCR of afbeeldingsanalyse, voegt de wizard hulpprogrammavaardigheden toe waarmee de afbeelding en tekstinhoud die tijdens het kraken van documenten zijn gescheiden, worden samengevoegd.

    Nadat de wizard is uitgevoerd, kunt u elk object openen in Azure Portal om de JSON-definitie ervan weer te geven.

  • Probeer foutopsporingssessies uit om de uitvoering van vaardighedensets aan te roepen via een doeldocument en inspecteer het verrijkte document dat door de vaardighedenset wordt gemaakt. U kunt de invoer- en uitvoerinstellingen en -waarden weergeven en wijzigen. Deze zelfstudie is een goede plek om te beginnen: Zelfstudie: Fouten opsporen in een vaardighedenset met behulp van foutopsporingssessies.

Volgende stappen

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

Verwijzingen naar aantekeningen in een vaardighedenset