Definire le proiezioni in un archivio conoscenze

Le proiezioni sono il componente di una definizione dell’archivio conoscenze che determina la posizione in cui i contenuti arricchiti dall’intelligenza artificiale sono archiviati in Archiviazione di Azure. Le proiezioni determinano il tipo, la quantità e la composizione delle strutture di dati che contengono i contenuti.

Questo articolo illustra la sintassi per ogni tipo di proiezione:

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

Tenere presente che le proiezioni sono 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, esaminare questo elenco di controllo per suggerimenti e il flusso di lavoro.

Requisiti

Tutte le proiezioni hanno proprietà di origine e di destinazione. L’origine è sempre un 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
• Un percorso a 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 forma inline, ma in genere una competenza Shaper. I campi o gli elementi della forma determinano i campi in contenitori e tabelle.

Le competenze Shaper sono preferite perché restituiscono oggetti JSON, dove la maggior parte delle competenze non restituisce oggetti JSON validi 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 dare forma ai dati diventa un requisito pratico per la definizione di proiezioni, soprattutto se si lavora con 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 matrice tables nella proprietà delle proiezioni. Una proiezione di tabella ha tre proprietà obbligatorie:

Nelle proiezioni di tabella, “origine” è in genere l’output di una competenza Shaper che definisce la forma della tabella. Le tabelle hanno righe e colonne e il dare forma è il meccanismo in base al quale vengono specificate righe e colonne. È possibile usare una competenza Shaper o forme inline. La competenza Shaper produce un oggetto JSON valido, ma l’origine potrebbe essere l’output di una qualsiasi competenza, se l’oggetto JSON è valido.

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 “origine”. 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 i contenuti arricchiti contengono 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 esegue una proiezione 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 la sua proiezione 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 dei contenuti arricchiti

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

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.

Definire una proiezione di oggetti

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. Una proiezione di oggetti ha tre proprietà obbligatorie:

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

Definire una proiezione di file

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 dati binari (anziché oggetti JSON).

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

La destinazione è sempre un contenitore BLOB, con un prefisso della cartella del valore con codifica in base64 dell’ID documento. Se sono presenti più immagini, verranno inserite tutte insieme 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 chiamato myImages.

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

Testare proiezioni

È possibile elaborare proiezioni seguendo questa procedura:

1. Impostare la proprietà storageConnectionString dell’archivio conoscenze su una stringa di connessione valida dell’account di archiviazione per utilizzo generico V2.

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 eseguire il set di competenze.

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

5. Usare il 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. 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 oggetti JSON validi. Quando le stringhe vengono arricchite, ad esempio merged_content viene arricchito con frasi chiave, la proprietà arricchita viene rappresentata come figlio di merged_content all’interno dell’albero di arricchimento. La rappresentazione predefinita non è un oggetto JSON ben formato. 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 od 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 sia di forme sia di proiezioni.