Definire le proiezioni in un archivio conoscenze

Le proiezioni sono il componente di una definizione dell'archivio conoscenze che determina la posizione in cui il contenuto arricchito dall'intelligenza artificiale viene archiviato in Archiviazione di Azure. Le proiezioni determinano il tipo, la quantità e la composizione delle strutture di dati contenenti il contenuto.

Questo articolo illustra la sintassi per ogni tipo di proiezione:

• Proiezioni di tabelle
• Proiezioni di oggetti
• Proiezioni di file

Tenere presente che le proiezioni vengono definite nella proprietà "knowledgeStore" di un set di competenze.

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

Se sono necessarie altre informazioni prima di iniziare, vedere questo elenco di controlli per suggerimenti e flusso di lavoro.

Suggerimento

Quando si sviluppano proiezioni, abilitare la memorizzazione nella cache di arricchimento (anteprima) in modo da poter riutilizzare gli arricchimenti esistenti durante la modifica delle definizioni di proiezione. La memorizzazione nella cache degli arricchimenti è una funzionalità di anteprima, quindi assicurarsi di usare l'API REST di anteprima (api-version=2020-06-30-preview o versione successiva) nella richiesta dell'indicizzatore. Senza memorizzazione nella cache, le semplici modifiche apportate a una proiezione genereranno una rielaborazione completa del contenuto arricchito. Memorizzando nella cache gli arricchimenti, è possibile scorrere le proiezioni senza incorrere in costi di elaborazione del set di competenze.

Requisiti

Tutte le proiezioni hanno proprietà di origine e destinazione. L'origine è sempre contenuto interno da un albero di arricchimento creato durante l'esecuzione del set di competenze. La destinazione è il nome e il tipo di un oggetto esterno creato e popolato in Archiviazione di Azure.

Ad eccezione delle proiezioni di file, che accettano solo immagini binarie, l'origine deve essere:

• JSON valido
• Percorso di un nodo nell'albero di arricchimento (ad esempio, "source": "/document/objectprojection")

Anche se un nodo potrebbe risolversi in un singolo campo, una rappresentazione più comune è un riferimento a una forma complessa. Le forme complesse vengono create tramite una metodologia di modellazione, una competenza Shaper o una definizione di shaping inline, ma in genere una competenza shaper. I campi o gli elementi della forma determinano i campi in contenitori e tabelle.

Le competenze del shaper sono preferite perché restituisce JSON, dove la maggior parte delle competenze non restituisce codice JSON valido autonomamente. In molti casi, la stessa forma di dati creata da una competenza Shaper può essere usata equamente dalle proiezioni di tabelle e oggetti.

In base ai requisiti di input di origine, sapere come modellare i dati diventa un requisito pratico per la definizione di proiezione, soprattutto se si lavora con le tabelle.

Definire una proiezione di tabella

Le proiezioni di tabelle sono consigliate per scenari che richiedono l'esplorazione dei dati, ad esempio l'analisi con Power BI o carichi di lavoro che usano frame di dati. La sezione tabelle di una matrice di proiezioni è un elenco di tabelle che si desidera proiettare.

Per definire una proiezione di tabella, usare la tables matrice nella proprietà projections. Una proiezione di tabella ha tre proprietà obbligatorie:

Proprietà	Descrizione
tableName	Determina il nome di una nuova tabella creata in Tabella di Azure Archiviazione.
generatedKeyName	Nome della colonna per la chiave che identifica in modo univoco ogni riga. Il valore è generato dal sistema. Se si omette questa proprietà, verrà creata automaticamente una colonna che usa il nome della tabella e la "chiave" come convenzione di denominazione.
source	Percorso di un nodo in un albero di arricchimento. Il nodo deve essere un riferimento a una forma complessa che determina le colonne create nella tabella.

Nelle proiezioni di tabella, "source" è in genere l'output di una competenza Shaper che definisce la forma della tabella. Le tabelle hanno righe e colonne e il data shaping è il meccanismo in base al quale vengono specificate righe e colonne. È possibile usare una competenza Shaper o forme inline. La competenza Shaper produce codice JSON valido, ma l'origine potrebbe essere l'output di qualsiasi competenza, se json valido.

Nota

Le proiezioni di tabella sono soggette ai limiti di archiviazione imposti da Archiviazione di Azure. Le dimensioni dell'entità non possono superare 1 MB e una singola proprietà non può essere superiore a 64 KB. Questi vincoli rendono le tabelle una soluzione ottimale per l'archiviazione di un numero elevato di entità di piccole dimensioni.

Esempio di tabella singola

Lo schema di una tabella viene specificato in parte dalla proiezione (nome e chiave della tabella) e anche dall'origine che fornisce la forma della tabella (colonne). In questo esempio viene illustrata una sola tabella in modo che sia possibile concentrarsi sui dettagli della definizione.

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

Le colonne sono derivate da "source". La forma di dati seguente contenente HotelId, HotelName, Category e Description comporterà la creazione di tali colonne nella tabella.

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

Esempio di più tabelle (sezionamento)

Un modello comune per le proiezioni di tabelle consiste nell'avere più tabelle correlate, in cui vengono create colonne partitionKey e rowKey generate dal sistema per supportare relazioni tra tabelle per tutte le tabelle nello stesso gruppo di proiezione.

La creazione di più tabelle può essere utile se si vuole controllare la modalità di aggregazione dei dati correlati. Se il contenuto arricchito contiene componenti non correlati o indipendenti, ad esempio le parole chiave estratte da un documento potrebbero non essere correlate dalle entità riconosciute nello stesso documento, è possibile suddividere tali campi in tabelle adiacenti.

Quando si proiettano in più tabelle, la forma completa viene proiettata in ogni tabella, a meno che un nodo figlio non sia l'origine di un'altra tabella all'interno dello stesso gruppo. L'aggiunta di una proiezione con un percorso di origine figlio di una proiezione esistente comporta il sezionamento del nodo figlio dal nodo padre e proiettato nella nuova tabella correlata. Questa tecnica consente di definire un singolo nodo in una competenza Shaper che può essere l'origine per tutte le proiezioni.

Il modello per più tabelle è costituito da:

• Una tabella come tabella padre o principale
• Tabelle aggiuntive per contenere sezioni del contenuto arricchito

Si supponga, ad esempio, che una competenza Shaper restituisca una "EnrichedShape" che contiene informazioni sugli hotel, oltre a contenuti arricchiti come frasi chiave, posizioni e organizzazioni. La tabella principale include i campi che descrivono l'hotel (ID, nome, descrizione, indirizzo, categoria). Le frasi chiave otterrebbero la colonna della frase chiave. Le entità otterrebbero le colonne di entità.

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

Denominazione delle relazioni

Le generatedKeyName proprietà e referenceKeyName vengono usate per correlare i dati tra tabelle o anche tra tipi di proiezione. 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 è quello referenceKeyName dell'elemento padre. referenceKeyName Quando non viene specificato, il servizio lo usa come generatedKeyName predefinito dal padre.

Power BI si basa su queste chiavi generate per individuare le relazioni all'interno delle tabelle. Se è necessaria la colonna nella tabella figlio denominata in modo diverso, impostare la referenceKeyName proprietà nella tabella padre. Un esempio è impostare come generatedKeyName ID nella tabella tblDocument e come referenceKeyName DocumentID. Ciò comporta la colonna nelle tabelle tblEntities e tblKeyPhrases contenenti l'ID documento denominato DocumentID.

Definire una proiezione di oggetti

Le proiezioni di oggetti sono rappresentazioni 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, usare la objects matrice nella proprietà projections. Una proiezione di oggetti ha tre proprietà obbligatorie:

Proprietà	Descrizione
storageContainer	Determina il nome di un nuovo contenitore creato in Archiviazione di Azure.
generatedKeyName	Nome della colonna per la chiave che identifica in modo univoco ogni riga. Il valore è generato dal sistema. Se si omette questa proprietà, verrà creata automaticamente una colonna che usa il nome della tabella e la "chiave" come convenzione di denominazione.
source	Percorso di un nodo in un albero di arricchimento che rappresenta la radice della proiezione. Il nodo è in genere un riferimento a una forma di dati complessa che determina la struttura del BLOB.

L'esempio seguente proietta singoli documenti di hotel, un documento di hotel per BLOB, in un contenitore denominato 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 denominata "objectprojection". Ogni BLOB avrà una rappresentazione 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"
        }
      ]
    }

Definire una proiezione di file

Le proiezioni di file sono sempre immagini binarie, 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 dati binari (anziché JSON).

Per definire una proiezione di file, usare la files matrice nella proprietà projections. Una proiezione di file ha tre proprietà obbligatorie:

Proprietà	Descrizione
storageContainer	Determina il nome di un nuovo contenitore creato in Archiviazione di Azure.
generatedKeyName	Nome della colonna per la chiave che identifica in modo univoco ogni riga. Il valore è generato dal sistema. Se si omette questa proprietà, verrà creata automaticamente una colonna che usa il nome della tabella e la "chiave" come convenzione di denominazione.
source	Percorso di un nodo in un albero di arricchimento che rappresenta la radice della proiezione. Per i file di immagini, l'origine è sempre /document/normalized_images/*. Le proiezioni di file agiscono solo sulla normalized_images raccolta. Né gli indicizzatori né un set di competenze passeranno attraverso l'immagine originale non normalizzata.

La destinazione è sempre un contenitore BLOB, con un prefisso di cartella del valore con codifica Base64 dell'ID documento. Se sono presenti più immagini, verranno inserite nella stessa cartella. 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 denominato myImages.

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

Testare le proiezioni

È possibile elaborare le proiezioni seguendo questa procedura:

1. Impostare la proprietà dell'archivio storageConnectionString conoscenze su un account di archiviazione per utilizzo generico V2 valido stringa di connessione.

2. Aggiornare il set di competenze inviando una richiesta PUT con la definizione di proiezione nel corpo del set di competenze.

3. Eseguire l'indicizzatore per inserire il set di competenze in esecuzione.

4. Monitorare l'esecuzione dell'indicizzatore per controllare lo stato di avanzamento e rilevare eventuali errori.

5. Usare portale di Azure per verificare la creazione di oggetti in Archiviazione di Azure.

6. Se si proiettano tabelle, importarle in Power BI per la modifica e la visualizzazione delle tabelle. Nella maggior parte dei casi, Power BI individua automaticamente le relazioni tra le tabelle.

Problemi comuni

L'omissione di uno dei passaggi seguenti può comportare risultati imprevisti. Verificare le condizioni seguenti se l'output non è corretto.

• Gli arricchimenti di stringhe non vengono modellati in JSON valido. Quando le stringhe vengono arricchite, ad esempio merged_content arricchite con frasi chiave, la proprietà arricchita viene rappresentata come figlio dell'albero di merged_content arricchimento. La rappresentazione predefinita non è JSON ben formata. In fase di proiezione assicurarsi di trasformare l'arricchimento in un oggetto JSON valido con un nome e un valore. L'uso di una competenza Shaper o la definizione di forme inline consentirà di risolvere questo problema.

• Omissione di /* alla fine di un percorso di origine. Se l'origine di una proiezione è /document/projectionShape/keyPhrases, la matrice di frasi chiave viene proiettata come un singolo oggetto/riga. Impostare invece il percorso di origine su /document/projectionShape/keyPhrases/* per restituire una singola riga o oggetto per ognuna delle frasi chiave.

• Errori di sintassi del percorso. I selettori di percorso fanno distinzione tra maiuscole e minuscole e possono causare avvisi di input mancanti se non si usa il caso esatto per il selettore.

Passaggi successivi

Il passaggio successivo illustra la modellazione e la proiezione dell'output da un set di competenze avanzato. Se il set di competenze è complesso, l'articolo seguente fornisce esempi di forme e proiezioni.

Esempio dettagliato di forme e proiezioni