Esempio dettagliato di forme e proiezioni in un archivio conoscenze
Questo articolo fornisce un esempio dettagliato che integra concetti di alto livello e articoli basati sulla sintassi illustrando i passaggi di modellazione e proiezione necessari per esprimere completamente l'output di un set di competenze avanzato in un archivio conoscenze.
Se i requisiti dell'applicazione richiedono più competenze e proiezioni, questo esempio può offrire un'idea migliore del modo in cui le forme e le proiezioni si intersecano.
Configurare i dati di esempio
I documenti di esempio non sono inclusi nella raccolta Proiezioni, ma i file di dati demo di arricchimento tramite intelligenza artificiale contengono testo e immagini che funzionano con le proiezioni descritte in questo esempio.
Creare un contenitore BLOB in Archiviazione di Azure e caricare tutti e 14 gli elementi.
In Archiviazione di Azure, copiare una stringa di connessione.
È possibile usare il file projections.rest per eseguire gli esempi in questo articolo.
Set di competenze di esempio
Per comprendere la dipendenza tra forme e proiezioni, esaminare il set di competenze seguente che crea contenuto arricchito. Questo set di competenze elabora sia immagini non elaborate che testo, producendo output a cui verrà fatto riferimento nelle forme e nelle proiezioni.
Prestare particolare attenzione agli output delle competenze (targetNames). Si fa riferimento agli output scritti nell'albero dei documenti arricchiti nelle proiezioni e nelle forme (tramite le competenze di Shaper).
{
"name": "projections-demo-ss",
"description": "Skillset that enriches blob data found in "merged_content". The enrichment granularity is a document.",
"skills": [
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"name": "#1",
"description": null,
"context": "/document/merged_content",
"categories": [
"Person",
"Quantity",
"Organization",
"URL",
"Email",
"Location",
"DateTime"
],
"defaultLanguageCode": "en",
"minimumPrecision": null,
"inputs": [
{
"name": "text",
"source": "/document/merged_content"
},
{
"name": "languageCode",
"source": "/document/language"
}
],
"outputs": [
{
"name": "persons",
"targetName": "people"
},
{
"name": "organizations",
"targetName": "organizations"
},
{
"name": "locations",
"targetName": "locations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
"name": "#2",
"description": null,
"context": "/document/merged_content",
"defaultLanguageCode": "en",
"maxKeyPhraseCount": null,
"inputs": [
{
"name": "text",
"source": "/document/merged_content"
},
{
"name": "languageCode",
"source": "/document/language"
}
],
"outputs": [
{
"name": "keyPhrases",
"targetName": "keyphrases"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
"name": "#3",
"description": null,
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_content"
}
],
"outputs": [
{
"name": "languageCode",
"targetName": "language"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.MergeSkill",
"name": "#4",
"description": null,
"context": "/document",
"insertPreTag": " ",
"insertPostTag": " ",
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "itemsToInsert",
"source": "/document/normalized_images/*/text"
},
{
"name": "offsets",
"source": "/document/normalized_images/*/contentOffset"
}
],
"outputs": [
{
"name": "mergedText",
"targetName": "merged_content"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
"name": "#5",
"description": null,
"context": "/document/normalized_images/*",
"textExtractionAlgorithm": "printed",
"lineEnding": "Space",
"defaultLanguageCode": "en",
"detectOrientation": true,
"inputs": [
{
"name": "image",
"source": "/document/normalized_images/*"
}
],
"outputs": [
{
"name": "text",
"targetName": "text"
},
{
"name": "layoutText",
"targetName": "layoutText"
}
]
}
],
"cognitiveServices": {
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "An Azure AI services resource in the same region as Search.",
"key": "<Azure AI services All-in-ONE KEY>"
},
"knowledgeStore": null
}
Competenza Shaper di esempio
Una competenza Shaper è un'utilità per l'uso di contenuto arricchito esistente che si sostituisce alla creazione di nuovi contenuti arricchiti. L'aggiunta di uno Shaper a un set di competenze consente di creare una forma personalizzata che è possibile proiettare in una tabella o in un archivio BLOB. Senza una forma personalizzata, le proiezioni sono limitate a fare riferimento a un singolo nodo (una proiezione per output), che non è adatto per le tabelle. La creazione di una forma personalizzata aggrega vari elementi in un nuovo intero logico che può essere proiettato come singola tabella o sezionato e distribuito in una raccolta di tabelle.
In questo esempio la forma personalizzata combina i metadati del BLOB e le entità e le frasi chiave identificate. La forma personalizzata viene chiamata projectionShape ed è padre in /document.
Uno degli scopi dello shaping è garantire che tutti i nodi di arricchimento siano espressi in JSON ben formato, che è necessario per la proiezione nell'archivio conoscenze. Ciò vale soprattutto quando un albero di arricchimento contiene nodi che non sono JSON ben formati (ad esempio, quando un arricchimento è padre in una primitiva come una stringa).
Si notino gli ultimi due nodi KeyPhrases e Entities. Questi vengono racchiusi in un oggetto JSON valido con sourceContext. Questa operazione è necessaria perché keyphrases e entities sono arricchimenti nelle primitive e devono essere convertiti in JSON validi prima che possano essere proiettati.
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"name": "ShaperForTables",
"description": null,
"context": "/document",
"inputs": [
{
"name": "metadata_storage_content_type",
"source": "/document/metadata_storage_content_type",
"sourceContext": null,
"inputs": []
},
{
"name": "metadata_storage_name",
"source": "/document/metadata_storage_name",
"sourceContext": null,
"inputs": []
},
{
"name": "metadata_storage_path",
"source": "/document/metadata_storage_path",
"sourceContext": null,
"inputs": []
},
{
"name": "metadata_content_type",
"source": "/document/metadata_content_type",
"sourceContext": null,
"inputs": []
},
{
"name": "keyPhrases",
"source": null,
"sourceContext": "/document/merged_content/keyphrases/*",
"inputs": [
{
"name": "KeyPhrases",
"source": "/document/merged_content/keyphrases/*"
}
]
},
{
"name": "Entities",
"source": null,
"sourceContext": "/document/merged_content/entities/*",
"inputs": [
{
"name": "Entities",
"source": "/document/merged_content/entities/*/name"
}
]
}
],
"outputs": [
{
"name": "output",
"targetName": "projectionShape"
}
]
}
Aggiungere Shaper a un set di competenze
Il set di competenze di esempio introdotto all'inizio di questo articolo non includeva la competenza Shaper, ma le competenze di Shaper appartengono a un set di competenze e vengono spesso posizionate verso la fine.
All'interno di un set di competenze, una competenza Shaper potrebbe essere simile alla seguente:
{
"name": "projections-demo-ss",
"skills": [
{
<Shaper skill goes here>
}
],
"cognitiveServices": "A key goes here",
"knowledgeStore": []
}
Proiezioni in tabelle
Attingendo agli esempi precedenti, esiste una quantità nota di arricchimenti e forme di dati a cui è possibile fare riferimento nelle proiezioni di tabelle. Nella proiezione delle tabelle seguenti vengono definite tre tabelle impostando le proprietà tableName, source e generatedKeyName.
Tutte e tre le tabelle verranno correlate tramite chiavi generate e dall'elemento padre /document/projectionShape condiviso.
"knowledgeStore" : {
"storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
"projections": [
{
"tables": [
{
"tableName": "tblDocument",
"generatedKeyName": "Documentid",
"source": "/document/projectionShape"
},
{
"tableName": "tblKeyPhrases",
"generatedKeyName": "KeyPhraseid",
"source": "/document/projectionShape/keyPhrases/*"
},
{
"tableName": "tblEntities",
"generatedKeyName": "Entityid",
"source": "/document/projectionShape/Entities/*"
}
],
"objects": [],
"files": []
}
]
}
Testare il lavoro
È possibile controllare le definizioni di proiezione seguendo questa procedura:
Impostare la proprietà
storageConnectionStringdell’archivio conoscenze su una stringa di connessione valida dell’account di archiviazione per utilizzo generico V2.Aggiornare il set di competenze inviando la richiesta PUT.
Dopo aver aggiornato il set di competenze, eseguire l'indicizzatore.
È ora disponibile una proiezione funzionante con tre tabelle. L'importazione di queste tabelle in Power BI dovrebbe comportare l'individuazione delle relazioni da parte di Power BI.
Prima di passare all'esempio successivo, esaminiamo gli aspetti della proiezione di tabella per comprendere i meccanismi di sezionamento e i dati correlati.
Sezionamento di una tabella in più tabelle figlio
Il sezionamento è una tecnica che suddivide un'intera forma consolidata in parti costitutive. Il risultato è costituito da tabelle separate, ma correlate che è possibile usare singolarmente.
Nell'esempio, projectionShape è la forma consolidata (o nodo di arricchimento). Nella definizione di proiezione, projectionShape viene suddiviso in tabelle aggiuntive e consente di estrarre parti della forma, keyPhrases e Entities. In Power BI questa opzione è utile perché più entità e keyPhrase sono associate a ogni documento e si otterranno altre informazioni se è possibile visualizzare entità e keyPhrase come dati classificati.
Il sezionamento genera in modo implicito una relazione tra le tabelle padre e figlio, utilizzando generatedKeyName nella tabella padre per creare una colonna con lo stesso nome nella tabella figlio.
Assegnazione di nomi alle relazioni
Le proprietà generatedKeyName e referenceKeyName vengono usate per correlare dati tra tabelle o anche tra tipi di proiezioni. Ogni riga della tabella figlio ha una proprietà che punta di nuovo all’elemento padre. Il nome della colonna o della proprietà nell’elemento figlio è la proprietà referenceKeyName dell’elemento padre. Quando la proprietà referenceKeyName non viene fornita, per impostazione predefinita, il servizio la imposta sulla proprietà generatedKeyName dall’elemento padre.
Power BI si basa su queste chiavi generate per individuare le relazioni all’interno delle tabelle. Se è necessario assegnare un nome diverso alla colonna nella tabella figlio, impostare la proprietà referenceKeyName nella tabella padre. Un esempio è impostare la proprietà generatedKeyName come ID nella tabella tblDocument e la proprietà referenceKeyName come DocumentID. Ciò comporta l’assegnazione del nome DocumentID alla colonna nelle tabelle tblEntities e tblKeyPhrases contenenti l’ID documento.
Proiezione di documenti BLOB
Le proiezioni di oggetti sono rappresentazioni di oggetti JSON dell’albero di arricchimento che possono essere originate da qualsiasi nodo. Rispetto alle proiezioni di tabelle, le proiezioni di oggetti sono più semplici da definire e vengono usate durante la proiezione di interi documenti. Le proiezioni di oggetti sono limitate a una singola proiezione in un contenitore e non possono essere sezionate.
Per definire una proiezione di oggetti, utilizzare la matrice objects nella proprietà delle proiezioni.
L'origine è il percorso a un nodo dell'albero di arricchimento che rappresenta la radice della proiezione. Anche se non è obbligatorio, il percorso del nodo è in genere l'output di una competenza Shaper. Ciò è dovuto al fatto che la maggior parte delle competenze non restituisce oggetti JSON validi autonomamente, il che significa che è necessaria una forma di shaping. In molti casi, è possibile usare la stessa competenza Shaper che crea una proiezione di tabella per generare una proiezione di oggetti. In alternativa, l'origine può anche essere impostata su un nodo con una forma inline per fornire la struttura.
La destinazione è sempre un contenitore BLOB.
L’esempio seguente proietta singoli documenti di hotel, un documento di hotel per BLOB, in un contenitore chiamato hotels.
"knowledgeStore": {
"storageConnectionString": "an Azure storage connection string",
"projections" : [
{
"tables": [ ]
},
{
"objects": [
{
"storageContainer": "hotels",
"source": "/document/objectprojection",
}
]
},
{
"files": [ ]
}
]
}
L’origine è l’output di una competenza Shaper chiamata "objectprojection". Ogni BLOB avrà una rappresentazione di un oggetto JSON di ogni input di campo.
{
"@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"
}
]
}
Proiezione di un file di immagine
Le proiezioni di file sono sempre immagini binarie e normalizzate, in cui la normalizzazione si riferisce al ridimensionamento e alla rotazione potenziali da usare nell’esecuzione del set di competenze. Le proiezioni di file, simili alle proiezioni di oggetti, vengono create come BLOB in Archiviazione di Azure e contengono l'immagine.
Per definire una proiezione di file, usare la matrice files nella proprietà delle proiezioni.
L'origine è sempre /document/normalized_images/*. Le proiezioni di file agiscono solo sulla raccolta normalized_images. Né gli indicizzatori né un set di competenze passeranno attraverso l’immagine originale non normalizzata.
La destinazione è sempre un contenitore BLOB, con un prefisso della cartella del valore con codifica in base64 dell’ID documento. Le proiezioni di file non possono condividere lo stesso contenitore delle proiezioni di oggetti e devono essere proiettate in un contenitore diverso.
L’esempio seguente proietta tutte le immagini normalizzate estratte dal nodo del documento di un documento arricchito, in un contenitore chiamato myImages.
"knowledgeStore" : {
"storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
"projections": [
{
"tables": [ ],
"objects": [ ],
"files": [
{
"storageContainer": "myImages",
"source": "/document/normalized_images/*"
}
]
}
]
}
Proiezione in più tipi
Uno scenario più complesso potrebbe richiedere di proiettare il contenuto tra i vari tipi di proiezione. Ad esempio, proiettando frasi chiave ed entità in tabelle, salvando i risultati OCR di testo e layout come oggetti e quindi proiettando le immagini come file.
Passaggi per più tipi di proiezione:
- Creare una tabella con una riga per ogni documento.
- Creare una tabella correlata alla tabella del documento con ogni frase chiave identificata come riga in questa tabella.
- Creare una tabella correlata alla tabella del documento con ogni entità identificata come riga in questa tabella.
- Creare una proiezione di oggetti con il testo del layout per ogni immagine.
- Creare una proiezione di file proiettando ogni immagine estratta.
- Creare una tabella di riferimento incrociato contenente riferimenti alla tabella del documento, alla proiezione di oggetti con il testo del layout e alla proiezione di file.
Modellare i dati per la proiezione incrociata
Per ottenere le forme necessarie per queste proiezioni, iniziare aggiungendo una nuova competenza Shaper che crea un oggetto sottoposto a shaping denominato crossProjection.
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"name": "ShaperForCrossProjection",
"description": null,
"context": "/document",
"inputs": [
{
"name": "metadata_storage_name",
"source": "/document/metadata_storage_name",
"sourceContext": null,
"inputs": []
},
{
"name": "keyPhrases",
"source": null,
"sourceContext": "/document/merged_content/keyphrases/*",
"inputs": [
{
"name": "KeyPhrases",
"source": "/document/merged_content/keyphrases/*"
}
]
},
{
"name": "entities",
"source": null,
"sourceContext": "/document/merged_content/entities/*",
"inputs": [
{
"name": "Entities",
"source": "/document/merged_content/entities/*/name"
}
]
},
{
"name": "images",
"source": null,
"sourceContext": "/document/normalized_images/*",
"inputs": [
{
"name": "image",
"source": "/document/normalized_images/*"
},
{
"name": "layoutText",
"source": "/document/normalized_images/*/layoutText"
},
{
"name": "ocrText",
"source": "/document/normalized_images/*/text"
}
]
}
],
"outputs": [
{
"name": "output",
"targetName": "crossProjection"
}
]
}
Definire proiezioni di tabelle, oggetti e file
Dall'oggetto crossProjection consolidato, suddividere l'oggetto in più tabelle, acquisire l'output OCR come BLOB e quindi salvare l'immagine come file (anche nell'archivio BLOB).
"knowledgeStore" : {
"storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
"projections": [
{
"tables": [
{
"tableName": "crossDocument",
"generatedKeyName": "Id",
"source": "/document/crossProjection"
},
{
"tableName": "crossEntities",
"generatedKeyName": "EntityId",
"source": "/document/crossProjection/entities/*"
},
{
"tableName": "crossKeyPhrases",
"generatedKeyName": "KeyPhraseId",
"source": "/document/crossProjection/keyPhrases/*"
},
{
"tableName": "crossReference",
"generatedKeyName": "CrossId",
"source": "/document/crossProjection/images/*"
}
],
"objects": [
{
"storageContainer": "crossobject",
"generatedKeyName": "crosslayout",
"source": null,
"sourceContext": "/document/crossProjection/images/*/layoutText",
"inputs": [
{
"name": "OcrLayoutText",
"source": "/document/crossProjection/images/*/layoutText"
}
]
}
],
"files": [
{
"storageContainer": "crossimages",
"generatedKeyName": "crossimages",
"source": "/document/crossProjection/images/*/image"
}
]
}
]
}
Le proiezioni di oggetti richiedono un nome contenitore per ogni proiezione. Le proiezioni di oggetti e le proiezioni di file non possono condividere un contenitore.
Relazioni tra le proiezioni di tabelle, oggetti e file
In questo esempio viene evidenziata anche un'altra funzionalità delle proiezioni. Definendo più tipi di proiezioni all'interno dello stesso oggetto di proiezione, esiste una relazione espressa all'interno e tra i diversi tipi (tabelle, oggetti, file). In questo modo è possibile iniziare con una riga di tabella per un documento e trovare tutto il testo OCR per le immagini all'interno del documento nella proiezione dell'oggetto.
Se non si desidera che i dati siano correlati, definire le proiezioni in gruppi di proiezione diversi. Ad esempio, il frammento di codice seguente comporterà la correlazione delle tabelle, ma senza relazioni tra le tabelle e le proiezioni dell'oggetto (testo OCR).
I gruppi di proiezioni sono utili quando si desidera proiettare gli stessi dati in forme diverse per esigenze diverse. Ad esempio, un gruppo di proiezione per il dashboard di Power BI e un altro gruppo di proiezione per l'acquisizione dei dati usati per eseguire il training di un modello di Machine Learning incapsulato in una competenza personalizzata.
Quando si compilano proiezioni di tipi diversi, vengono generate prima proiezioni di file e oggetti, quindi vengono aggiunti i percorsi alle tabelle.
"knowledgeStore" : {
"storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
"projections": [
{
"tables": [
{
"tableName": "unrelatedDocument",
"generatedKeyName": "Documentid",
"source": "/document/projectionShape"
},
{
"tableName": "unrelatedKeyPhrases",
"generatedKeyName": "KeyPhraseid",
"source": "/document/projectionShape/keyPhrases"
}
],
"objects": [
],
"files": []
},
{
"tables": [],
"objects": [
{
"storageContainer": "unrelatedocrtext",
"source": null,
"sourceContext": "/document/normalized_images/*/text",
"inputs": [
{
"name": "ocrText",
"source": "/document/normalized_images/*/text"
}
]
},
{
"storageContainer": "unrelatedocrlayout",
"source": null,
"sourceContext": "/document/normalized_images/*/layoutText",
"inputs": [
{
"name": "ocrLayoutText",
"source": "/document/normalized_images/*/layoutText"
}
]
}
],
"files": []
}
]
}
Passaggi successivi
L'esempio in questo articolo illustra modelli comuni su come creare proiezioni. Ora che si ha una buona conoscenza dei concetti, è possibile creare proiezioni per uno scenario specifico.