Share via

Projecties definiëren in een kennisarchief

  • Artikel

Projecties zijn het onderdeel van een definitie van een kennisarchief die bepaalt waar AI verrijkte inhoud wordt opgeslagen in Azure Storage. Projecties bepalen het type, de hoeveelheid en de samenstelling van de gegevensstructuren die uw inhoud bevatten.

In dit artikel leert u de syntaxis voor elk type projectie:

Zoals u weet, worden projecties gedefinieerd onder de eigenschap 'knowledgeStore' van een vaardighedenset.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
      {
        "tables": [ ],
        "objects": [ ],
        "files": [ ]
      }
    ]
}

Als u meer achtergrond nodig hebt voordat u aan de slag gaat, bekijkt u deze lijst met tips en werkstromen.

Fooi

Bij het ontwikkelen van projecties schakelt u verrijkingscaching (preview) in, zodat u bestaande verrijkingen opnieuw kunt gebruiken tijdens het bewerken van projectiedefinities. Verrijkingscaching is een preview-functie, dus zorg ervoor dat u de PREVIEW REST API (api-version=2020-06-30-preview of hoger) gebruikt voor de indexeeraanvraag. Zonder caching leiden eenvoudige bewerkingen naar een projectie tot een volledige herverwerking van verrijkte inhoud. Door de verrijkingen in de cache te plaatsen, kunt u projecties herhalen zonder dat er kosten voor het verwerken van vaardighedensets in rekening worden gebracht.

Vereisten

Alle projecties hebben bron- en doeleigenschappen. De bron is altijd interne inhoud van een verrijkingsstructuur die is gemaakt tijdens de uitvoering van de vaardighedenset. De bestemming is de naam en het type van een extern object dat wordt gemaakt en ingevuld in Azure Storage.

Met uitzondering van bestandsprojecties, die alleen binaire afbeeldingen accepteren, moet de bron het volgende zijn:

  • Geldige JSON
  • Een pad naar een knooppunt in de verrijkingsstructuur (bijvoorbeeld "source": "/document/objectprojection")

Hoewel een knooppunt kan worden omgezet in één veld, is een meer algemene weergave een verwijzing naar een complexe vorm. Complexe vormen worden gemaakt via een vormmethode, ofwel een Shaper-vaardigheid of een definitie van inline-vormgeving, maar meestal een Shaper-vaardigheid. De velden of elementen van de shape bepalen de velden in containers en tabellen.

Shaper-vaardigheden zijn gunstig omdat het JSON uitvoert, waarbij de meeste vaardigheden geen geldige JSON zelf uitvoeren. In veel gevallen kan dezelfde gegevensshape die door een Shaper-vaardigheid is gemaakt, evengoed worden gebruikt door zowel tabel- als objectprojecties.

Gezien de vereisten voor broninvoer, is het bepalen van de vorm van gegevens een praktische vereiste voor projectiedefinitie, met name als u met tabellen werkt.

Een tabelprojectie definiëren

Tabelprojecties worden aanbevolen voor scenario's die gegevensverkenning aanroepen, zoals analyse met Power BI of workloads die gegevensframes verbruiken. De tabellensectie van een projectiematrix is een lijst met tabellen die u wilt projecteren.

Als u een tabelprojectie wilt definiëren, gebruikt u de tables matrix in de eigenschap Projecties. Een tabelprojectie heeft drie vereiste eigenschappen:

Eigenschappen Beschrijving
tableName Bepaalt de naam van een nieuwe tabel die is gemaakt in Azure Table Storage.
generatedKeyName Kolomnaam voor de sleutel die elke rij uniek identificeert. De waarde wordt door het systeem gegenereerd. Als u deze eigenschap weglaat, wordt er automatisch een kolom gemaakt waarin de tabelnaam en sleutel als naamconventie worden gebruikt.
source Een pad naar een knooppunt in een verrijkingsstructuur. Het knooppunt moet een verwijzing zijn naar een complexe shape die bepaalt welke kolommen in de tabel worden gemaakt.

In tabelprojecties is 'bron' meestal de uitvoer van een Shaper-vaardigheid die de vorm van de tabel definieert. Tabellen hebben rijen en kolommen en vormen is het mechanisme waarmee rijen en kolommen worden opgegeven. U kunt een Shaper-vaardigheid of inlineshapes gebruiken. De Shaper-vaardigheid produceert geldige JSON, maar de bron kan de uitvoer zijn van elke vaardigheid, indien geldige JSON.

Notitie

Tabelprojecties zijn onderhevig aan de opslaglimieten die worden opgelegd door Azure Storage. De grootte van de entiteit mag niet groter zijn dan 1 MB en één eigenschap mag niet groter zijn dan 64 kB. Deze beperkingen maken tabellen een goede oplossing voor het opslaan van een groot aantal kleine entiteiten.

Voorbeeld van één tabel

Het schema van een tabel wordt deels opgegeven door de projectie (tabelnaam en -sleutel), en ook door de bron die de vorm van de tabel (kolommen) biedt. In dit voorbeeld ziet u slechts één tabel, zodat u zich kunt richten op de details van de definitie.

"projections" : [
  {
    "tables": [
      { "tableName": "Hotels", "generatedKeyName": "HotelId", "source": "/document/tableprojection" }
    ]
  }
]

Kolommen worden afgeleid van de bron. De volgende gegevensvorm die HotelId, HotelName, Category en Description bevat, resulteert in het maken van deze kolommen in de tabel.

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "#3",
    "description": null,
    "context": "/document",
    "inputs": [
    {
        "name": "HotelId",
        "source": "/document/HotelId"
    },
    {
        "name": "HotelName",
        "source": "/document/HotelName"
    },
    {
        "name": "Category",
        "source": "/document/Category"
    },
    {
        "name": "Description",
        "source": "/document/Description"
    },
    ],
    "outputs": [
    {
        "name": "output",
        "targetName": "tableprojection"
    }
    ]
}

Voorbeeld van meerdere tabellen (segmentering)

Een veelvoorkomend patroon voor tabelprojecties is het hebben van meerdere gerelateerde tabellen, waarbij door het systeem gegenereerde partitionKey- en rowKey-kolommen worden gemaakt ter ondersteuning van relaties tussen tabellen voor alle tabellen onder dezelfde projectiegroep.

Het maken van meerdere tabellen kan handig zijn als u wilt bepalen hoe gerelateerde gegevens worden samengevoegd. Als verrijkte inhoud niet-gerelateerde of onafhankelijke onderdelen heeft, zijn de trefwoorden die uit een document zijn geëxtraheerd mogelijk niet gerelateerd aan de entiteiten die in hetzelfde document worden herkend, kunt u deze velden splitsen in aangrenzende tabellen.

Wanneer u naar meerdere tabellen projecteert, wordt de volledige shape in elke tabel geprojecteerd, tenzij een onderliggend knooppunt de bron is van een andere tabel binnen dezelfde groep. Als u een projectie toevoegt met een bronpad dat een onderliggend element van een bestaande projectie is, wordt het onderliggende knooppunt uit het bovenliggende knooppunt gesegmenteerd en naar de nieuwe maar gerelateerde tabel geprojecteerd. Met deze techniek kunt u één knooppunt definiëren in een Shaper-vaardigheid die de bron kan zijn voor al uw projecties.

Het patroon voor meerdere tabellen bestaat uit:

  • Eén tabel als de bovenliggende of hoofdtabel
  • Aanvullende tabellen die segmenten van de verrijkte inhoud bevatten

Stel dat een Shaper-vaardigheid een 'EnrichedShape' uitvoert die hotelgegevens bevat, plus verrijkte inhoud, zoals sleuteltermen, locaties en organisaties. De hoofdtabel bevat velden die het hotel beschrijven (id, naam, beschrijving, adres, categorie). Sleuteltermen krijgen de kolom met sleuteltermen. Entiteiten krijgen de entiteitskolommen.

"projections" : [
  {
    "tables": [
    { "tableName": "MainTable", "generatedKeyName": "HotelId", "source": "/document/EnrichedShape" },
    { "tableName": "KeyPhrases", "generatedKeyName": "KeyPhraseId", "source": "/document/EnrichedShape/*/KeyPhrases/*" },
    { "tableName": "Entities", "generatedKeyName": "EntityId", "source": "/document/EnrichedShape/*/Entities/*" }
    ]
  }
]

Naamgevingsrelaties

De generatedKeyName eigenschappen en referenceKeyName eigenschappen worden gebruikt om gegevens in tabellen of zelfs over projectietypen te relateren. Elke rij in de onderliggende tabel heeft een eigenschap die naar het bovenliggende item wijst. De naam van de kolom of eigenschap in het onderliggende item is de referenceKeyName naam van het bovenliggende item. Wanneer de referenceKeyName service niet is opgegeven, wordt deze standaard ingesteld op de generatedKeyName bovenliggende service.

Power BI is afhankelijk van deze gegenereerde sleutels om relaties in de tabellen te detecteren. Als u de kolom in de onderliggende tabel anders wilt noemen, stelt u de referenceKeyName eigenschap in op de bovenliggende tabel. Een voorbeeld hiervan is het instellen van de generatedKeyName as-id in de tblDocument-tabel en de referenceKeyName als DocumentID. Dit zou resulteren in de kolom in de tabellen tblEntities en tblKeyPhrases met de document-id met de naam DocumentID.

Een objectprojectie definiëren

Objectprojecties zijn JSON-representaties van de verrijkingsstructuur die kan worden opgehaald uit elk knooppunt. In vergelijking met tabelprojecties zijn objectprojecties eenvoudiger te definiëren en worden ze gebruikt bij het projecteren van hele documenten. Objectprojecties zijn beperkt tot één projectie in een container en kunnen niet worden gesegmenteerd.

Als u een objectprojectie wilt definiëren, gebruikt u de objects matrix in de eigenschap projecties. Een objectprojectie heeft drie vereiste eigenschappen:

Eigenschappen Beschrijving
storageContainer Bepaalt de naam van een nieuwe container die is gemaakt in Azure Storage.
generatedKeyName Kolomnaam voor de sleutel die elke rij uniek identificeert. De waarde wordt door het systeem gegenereerd. Als u deze eigenschap weglaat, wordt er automatisch een kolom gemaakt waarin de tabelnaam en sleutel als naamconventie worden gebruikt.
source Een pad naar een knooppunt in een verrijkingsstructuur die de hoofdmap van de projectie is. Het knooppunt is meestal een verwijzing naar een complexe gegevensshape die de blobstructuur bepaalt.

Het volgende voorbeeld projecteert afzonderlijke hoteldocumenten, één hoteldocument per blob, in een container met de naam hotels.

"knowledgeStore": {
  "storageConnectionString": "an Azure storage connection string",
  "projections" : [
    {
      "tables": [ ]
    },
    {
      "objects": [
        {
        "storageContainer": "hotels",
        "source": "/document/objectprojection",
        }
      ]
    },
    {
        "files": [ ]
    }
  ]
}

De bron is de uitvoer van een Shaper-vaardigheid, genaamd "objectprojection". Elke blob heeft een JSON-weergave van elke veldinvoer.

    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "name": "#3",
      "description": null,
      "context": "/document",
      "inputs": [
        {
          "name": "HotelId",
          "source": "/document/HotelId"
        },
        {
          "name": "HotelName",
          "source": "/document/HotelName"
        },
        {
          "name": "Category",
          "source": "/document/Category"
        },
        {
          "name": "keyPhrases",
          "source": "/document/HotelId/keyphrases/*"
        },
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "objectprojection"
        }
      ]
    }

Een bestandsprojectie definiëren

Bestandsprojecties zijn altijd binaire, genormaliseerde afbeeldingen, waarbij normalisatie verwijst naar mogelijke groottes en rotatie voor gebruik bij het uitvoeren van vaardighedensets. Bestandsprojecties, vergelijkbaar met objectprojecties, worden gemaakt als blobs in Azure Storage en bevatten binaire gegevens (in tegenstelling tot JSON).

Als u een bestandsprojectie wilt definiëren, gebruikt u de files matrix in de eigenschap projecties. Een bestandsprojectie heeft drie vereiste eigenschappen:

Eigenschappen Beschrijving
storageContainer Bepaalt de naam van een nieuwe container die is gemaakt in Azure Storage.
generatedKeyName Kolomnaam voor de sleutel die elke rij uniek identificeert. De waarde wordt door het systeem gegenereerd. Als u deze eigenschap weglaat, wordt er automatisch een kolom gemaakt waarin de tabelnaam en sleutel als naamconventie worden gebruikt.
source Een pad naar een knooppunt in een verrijkingsstructuur die de hoofdmap van de projectie is. Voor afbeeldingenbestanden is de bron altijd /document/normalized_images/*. Bestandsprojecties reageren alleen op de normalized_images verzameling. Indexeerfuncties of een vaardighedenset passeren de oorspronkelijke niet-genormaliseerde afbeelding niet.

Het doel is altijd een blobcontainer, met een mapvoorvoegsel van de base64-gecodeerde waarde van de document-id. Als er meerdere afbeeldingen zijn, worden ze samen in dezelfde map geplaatst. Bestandsprojecties kunnen niet dezelfde container delen als objectprojecties en moeten in een andere container worden geprojecteerd.

In het volgende voorbeeld worden alle genormaliseerde afbeeldingen geprojecteerd die zijn geëxtraheerd uit het documentknooppunt van een verrijkt document, in een container met de naam myImages.

"projections": [
    {
        "tables": [ ],
        "objects": [ ],
        "files": [
            {
                "storageContainer": "myImages",
                "source": "/document/normalized_images/*"
            }
        ]
    }
]

Testprojecties

U kunt projecties verwerken door de volgende stappen uit te voeren:

  1. Stel de eigenschap van storageConnectionString het kennisarchief in op een geldig V2-opslagaccount voor algemeen gebruik verbindingsreeks.

  2. Werk de vaardighedenset bij door een PUT-aanvraag uit te geven met uw projectiedefinitie in de hoofdtekst van de vaardighedenset.

  3. Voer de indexeerfunctie uit om de vaardighedenset in uitvoering te brengen.

  4. Bewaak de uitvoering van de indexeerfunctie om de voortgang te controleren en eventuele fouten te ondervangen.

  5. Azure Portal gebruiken om het maken van objecten in Azure Storage te verifiëren.

  6. Als u tabellen projecteert, importeert u deze in Power BI voor tabelbewerking en -visualisatie. In de meeste gevallen detecteert Power BI automatisch de relaties tussen tabellen.

Algemene problemen

Als u een van de volgende stappen weglaat, kan dit leiden tot onverwachte resultaten. Controleer op de volgende voorwaarden als uw uitvoer er niet goed uitziet.

  • Tekenreeksverrijkingen worden niet vormgegeven in geldige JSON. Wanneer tekenreeksen zijn verrijkt, bijvoorbeeld merged_content verrijkt met sleuteltermen, wordt de verrijkte eigenschap weergegeven als een onderliggend element in merged_content de verrijkingsstructuur. De standaardweergave is geen goed opgemaakte JSON. Zorg er tijdens projectietijd voor dat u de verrijking transformeert in een geldig JSON-object met een naam en een waarde. Het gebruik van een Shaper-vaardigheid of het definiëren van inlineshapes helpt dit probleem op te lossen.

  • /* Weglating aan het einde van een bronpad. Als de bron van een projectie is /document/projectionShape/keyPhrases, wordt de matrix met sleuteltermen geprojecteerd als één object/rij. Stel in plaats daarvan het bronpad in op /document/projectionShape/keyPhrases/* één rij of object voor elk van de sleuteltermen.

  • Padsyntaxisfouten. Padkiezers zijn hoofdlettergevoelig en kunnen leiden tot ontbrekende invoerwaarschuwingen als u niet de exacte case voor de kiezer gebruikt.

Volgende stappen

De volgende stap begeleidt u bij het vormgeven en projecteren van uitvoer uit een uitgebreide vaardighedenset. Als uw vaardighedenset complex is, bevat het volgende artikel voorbeelden van shapes en projecties.

Gedetailleerd voorbeeld van vormen en projecties