Definiera projektioner i ett kunskapslager

Artikel
09/01/2024

Projektioner är komponenten i en kunskapslagerdefinition som avgör var AI-berikat innehåll lagras i Azure Storage. Projektioner avgör typen, kvantiteten och sammansättningen av de datastrukturer som innehåller ditt innehåll.

I den här artikeln lär du dig syntaxen för varje typ av projektion:

Tabellprojektioner
Objektprojektioner
Filprojektioner

Kom ihåg att projektioner definieras under egenskapen "knowledgeStore" för en kompetensuppsättning.

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

Om du behöver mer bakgrund innan du kommer igång kan du läsa den här kontrolllistan för tips och arbetsflöden.

Dricks

När du utvecklar projektioner aktiverar du cachelagring av berikning (förhandsversion) så att du kan återanvända befintliga berikanden när du redigerar projektionsdefinitioner. Cachelagring av berikning är en förhandsversionsfunktion, så se till att använda rest-API:et för förhandsversionen på indexerarens begäran. Utan cachelagring resulterar enkla ändringar i en projektion i en fullständig ombearbetning av berikat innehåll. Genom att cachelagra berikningarna kan du iterera över projektioner utan att behöva debiteras för bearbetning av kompetensuppsättningar.

Krav

Alla projektioner har käll- och målegenskaper. Källan är alltid internt innehåll från ett berikande träd som skapades under körningen av kompetensuppsättningen. Målet är namnet och typen på ett externt objekt som skapas och fylls i i Azure Storage.

Förutom filprojektioner, som endast accepterar binära bilder, måste källan vara:

Giltig JSON
En sökväg till en nod i berikningsträdet (till exempel "source": "/document/objectprojection")

En nod kan matcha ett enda fält, men en vanligare representation är en referens till en komplex form. Komplexa former skapas med hjälp av en formningsmetod, antingen en Formningsfärdighet eller en infogad formningsdefinition, men vanligtvis en Formningsfärdighet. Fälten eller elementen i formen avgör fälten i containrar och tabeller.

Shaper-färdigheter gynnas eftersom det matar ut JSON, där de flesta färdigheter inte matar ut giltig JSON på egen hand. I många fall kan samma dataform som skapats av en Shaper-färdighet användas lika av både tabell- och objektprojektioner.

Med tanke på kraven för källindata blir det ett praktiskt krav för projektionsdefinition att veta hur data ska formas, särskilt om du arbetar med tabeller.

Definiera en tabellprojektion

Tabellprojektioner rekommenderas för scenarier som kräver datautforskning, till exempel analys med Power BI eller arbetsbelastningar som använder dataramar. Tabellavsnittet i en projektionsmatris är en lista över tabeller som du vill projicera.

Om du vill definiera en tabellprojektion använder du matrisen tables i egenskapen projektioner. En tabellprojektion har tre obligatoriska egenskaper:

Property	beskrivning
tableName	Avgör namnet på en ny tabell som skapats i Azure Table Storage.
generatedKeyName	Kolumnnamn för nyckeln som unikt identifierar varje rad. Värdet är systemgenererat. Om du utelämnar den här egenskapen skapas en kolumn automatiskt som använder tabellnamnet och "nyckeln" som namngivningskonvention.
source	En sökväg till en nod i ett berikande träd. Noden ska vara en referens till en komplex form som avgör vilka kolumner som skapas i tabellen.

I tabellprojektioner är "källa" vanligtvis utdata från en Shaper-färdighet som definierar tabellens form. Tabeller har rader och kolumner, och formning är den mekanism som rader och kolumner anges med. Du kan använda en Shaper-färdighet eller infogade former. Shaper-färdigheten genererar giltig JSON, men källan kan vara utdata från valfri färdighet, om den är giltig JSON.

Kommentar

Tabellprojektioner omfattas av de lagringsgränser som införts av Azure Storage. Entitetsstorleken får inte överstiga 1 MB och en enskild egenskap får inte vara större än 64 kB. Dessa begränsningar gör tabeller till en bra lösning för att lagra ett stort antal små entiteter.

Exempel på en tabell

Schemat för en tabell anges delvis av projektionen (tabellnamn och nyckel), och även av källan som tillhandahåller formen på tabellen (kolumner). Det här exemplet visar bara en tabell så att du kan fokusera på information om definitionen.

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

Kolumner härleds från "källan". Följande dataform som innehåller HotelId, HotelName, Category och Description resulterar i att kolumnerna skapas i tabellen.

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

Exempel på flera tabeller (segmentering)

Ett vanligt mönster för tabellprojektioner är att ha flera relaterade tabeller, där systemgenererade partitionKey- och rowKey-kolumner skapas för att stödja korstabellrelationer för alla tabeller under samma projektionsgrupp.

Att skapa flera tabeller kan vara användbart om du vill ha kontroll över hur relaterade data aggregeras. Om berikat innehåll har orelaterade eller oberoende komponenter, till exempel nyckelord som extraheras från ett dokument, kan vara orelaterade från de entiteter som identifieras i samma dokument, kan du dela upp dessa fält i intilliggande tabeller.

När du projicerar till flera tabeller projiceras den fullständiga formen i varje tabell, såvida inte en underordnad nod är källan till en annan tabell i samma grupp. Om du lägger till en projektion med en källsökväg som är underordnad en befintlig projektion resulterar det i att den underordnade noden delas ut från den överordnade noden och projiceras i den nya men relaterade tabellen. Med den här tekniken kan du definiera en enskild nod i en Shaper-färdighet som kan vara källan för alla dina projektioner.

Mönstret för flera tabeller består av:

En tabell som överordnad eller huvudtabell
Ytterligare tabeller som ska innehålla sektorer av det berikade innehållet

Anta till exempel att en Shaper-färdighet matar ut en "EnrichedShape" som innehåller hotellinformation, plus berikat innehåll som nyckelfraser, platser och organisationer. Huvudtabellen innehåller fält som beskriver hotellet (ID, namn, beskrivning, adress, kategori). Nyckelfraser skulle hämta nyckelfraskolumnen. Entiteter skulle hämta entitetskolumnerna.

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

Namnge relationer

Egenskaperna generatedKeyName och referenceKeyName används för att relatera data mellan tabeller eller till och med mellan projektionstyper. Varje rad i den underordnade tabellen har en egenskap som pekar tillbaka till den överordnade tabellen. Namnet på kolumnen eller egenskapen i det underordnade objektet är referenceKeyName från den överordnade. När inte referenceKeyName tillhandahålls, standardinställningen för tjänsten från generatedKeyName den överordnade tjänsten.

Power BI förlitar sig på dessa genererade nycklar för att identifiera relationer i tabellerna. Om du behöver kolumnen i den underordnade tabellen med namnet annorlunda anger du egenskapen i referenceKeyName den överordnade tabellen. Ett exempel är att ange generatedKeyName som ID i tabellen tblDocument och referenceKeyName som DocumentID. Detta skulle resultera i kolumnen i tabellerna tblEntities och tblKeyPhrases som innehåller dokument-ID:t med namnet DocumentID.

Definiera en objektprojektion

Objektprojektioner är JSON-representationer av berikningsträdet som kan hämtas från valfri nod. Jämfört med tabellprojektioner är objektprojektioner enklare att definiera och används när hela dokument projiceras. Objektprojektioner är begränsade till en enda projektion i en container och kan inte segmenteras.

Om du vill definiera en objektprojektion använder du matrisen objects i projektionsegenskapen. En objektprojektion har tre nödvändiga egenskaper:

Property	beskrivning
storageContainer	Avgör namnet på en ny container som skapats i Azure Storage.
generatedKeyName	Kolumnnamn för nyckeln som unikt identifierar varje rad. Värdet är systemgenererat. Om du utelämnar den här egenskapen skapas en kolumn automatiskt som använder tabellnamnet och "nyckeln" som namngivningskonvention.
source	En sökväg till en nod i ett berikande träd som är projektionens rot. Noden är vanligtvis en referens till en komplex dataform som avgör blobstrukturen.

I följande exempel projiceras enskilda hotelldokument, ett hotelldokument per blob, till en container med namnet hotels.

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

Källan är utdata från en Shaper-färdighet med namnet "objectprojection". Varje blob har en JSON-representation av varje fältindata.

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

Definiera en filprojektion

Filprojektioner är alltid binära, normaliserade bilder, där normalisering refererar till potentiell storleksändring och rotation för användning vid körning av kompetensuppsättningar. Filprojektioner, som liknar objektprojektioner, skapas som blobar i Azure Storage och innehåller binära data (till skillnad från JSON).

Om du vill definiera en filprojektion använder du matrisen files i projektionsegenskapen. En filprojektion har tre nödvändiga egenskaper:

Property	beskrivning
storageContainer	Avgör namnet på en ny container som skapats i Azure Storage.
generatedKeyName	Kolumnnamn för nyckeln som unikt identifierar varje rad. Värdet är systemgenererat. Om du utelämnar den här egenskapen skapas en kolumn automatiskt som använder tabellnamnet och "nyckeln" som namngivningskonvention.
source	En sökväg till en nod i ett berikande träd som är projektionens rot. För avbildningsfiler är källan alltid `/document/normalized_images/*`. Filprojektioner fungerar bara på `normalized_images` samlingen. Varken indexerare eller en kompetensuppsättning passerar den ursprungliga icke-normaliserade avbildningen.

Målet är alltid en blobcontainer med ett mappprefix för det base64-kodade värdet för dokument-ID:t. Om det finns flera bilder placeras de tillsammans i samma mapp. Filprojektioner kan inte dela samma container som objektprojektioner och behöver projiceras i en annan container.

I följande exempel projiceras alla normaliserade bilder som extraherats från dokumentnoden i ett berikat dokument till en container med namnet myImages.

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

Testprojektioner

Du kan bearbeta projektioner genom att följa dessa steg:

Ange egenskapen för kunskapsarkivet till ett giltigt V2-lagringskonto storageConnectionString för generell användning anslutningssträng.
Uppdatera kompetensuppsättningen genom att utfärda en PUT-begäran med din projektionsdefinition i kunskapsuppsättningens brödtext.
Kör indexeraren för att köra kunskapsuppsättningen.
Övervaka indexerarens körning för att kontrollera förloppet och fånga eventuella fel.
Använd Azure Portal för att verifiera att objekt skapas i Azure Storage.
Om du projicerar tabeller importerar du dem till Power BI för tabellmanipulering och visualisering. I de flesta fall identifierar Power BI relationerna mellan tabeller automatiskt.

Vanliga problem

Om du utelämnar något av följande steg kan det leda till oväntade resultat. Kontrollera följande villkor om dina utdata inte ser rätt ut.

Strängberikningar formas inte till giltig JSON. När strängar berikas, till exempel merged_content berikade med nyckelfraser, representeras den berikade egenskapen som underordnad merged_content i berikningsträdet. Standardrepresentationen är inte välformulerad JSON. Vid projektionstid bör du omvandla berikningen till ett giltigt JSON-objekt med ett namn och ett värde. Om du använder en Formningsfärdighet eller definierar infogade former kan du lösa det här problemet.
Utelämnande av /* i slutet av en källsökväg. Om källan till en projektion är /document/projectionShape/keyPhrasesprojiceras matrisen med nyckelfraser som ett enskilt objekt/en rad. Ange i stället källsökvägen till /document/projectionShape/keyPhrases/* för att ge en enskild rad eller ett objekt för var och en av nyckelfraserna.
Sökvägssyntaxfel. Sökvägsväljare är skiftlägeskänsliga och kan leda till saknade indatavarningar om du inte använder det exakta fallet för väljaren.

Nästa steg

Nästa steg vägleder dig genom formning och projektion av utdata från en omfattande kompetensuppsättning. Om din kompetensuppsättning är komplex innehåller följande artikel exempel på både former och projektioner.

Detaljerat exempel på former och projektioner

Dela via