Fare riferimento a un percorso ai nodi arricchiti usando il contesto e le proprietà di origine di un set di competenze di Ricerca di intelligenza artificiale di Azure

Articolo
01/19/2024

Durante l'esecuzione del set di competenze, il motore compila un albero di arricchimento in memoria che acquisisce ogni arricchimento, ad esempio entità riconosciute o testo tradotto. Questo articolo illustra come fare riferimento a un nodo di arricchimento nell'albero di arricchimento in modo da poter passare l'output alle competenze downstream o specificare un mapping dei campi di output per un campo dell'indice di ricerca.

Questo articolo usa esempi per illustrare vari scenari. Per la sintassi completa, vedere Contesto delle competenze e linguaggio di annotazione di input.

Concetti di base

Prima di esaminare la sintassi, è opportuno rivedere alcuni concetti importanti per comprendere meglio gli esempi forniti più avanti in questo articolo.

Termine	Descrizione
"documento arricchito"	Un documento arricchito è una struttura in memoria che raccoglie l'output delle competenze durante la creazione e contiene tutti gli arricchimenti correlati a un documento. Si pensi a un documento arricchito come un albero. In genere, l'albero inizia a livello di documento radice e ogni nuovo arricchimento viene creato da un elemento precedente come figlio.
"node"	All'interno di un documento arricchito, un nodo (talvolta definito "annotazione") viene creato e popolato da una competenza, ad esempio "text" e "layoutText" nella competenza OCR. Un documento arricchito viene popolato con arricchimenti e valori di campo di origine originali o metadati copiati dall'origine.
"context"	Ambito di arricchimento, ovvero l'intero documento, una parte di un documento o se si utilizzano immagini, le immagini estratte da un documento. Per impostazione predefinita, il contesto di arricchimento è a `"/document"` livello, con ambito per singoli documenti contenuti nell'origine dati. Quando viene eseguita una competenza, gli output di tale competenza diventano proprietà del contesto definito.

Percorsi per diversi scenari

I percorsi vengono specificati nelle proprietà "context" e "source" di un set di competenze e nei mapping dei campi di output in un indicizzatore.

L'esempio nello screenshot illustra il percorso di un elemento in una raccolta di Azure Cosmos DB.

context path è /document/HotelId dovuto al fatto che la raccolta è partizionata in documenti in base al /HotelId campo .
source path è /document/Description dovuto al fatto che la competenza è una competenza di traduzione e il campo che si vuole tradurre è il Description campo in ogni documento.

Tutti i percorsi iniziano con /document. Un documento arricchito viene creato nella fase "document cracking" dell'esecuzione dell'indicizzatore, quando l'indicizzatore apre un documento o legge in una riga dall'origine dati. Inizialmente, l'unico nodo in un documento arricchito è il nodo radice (/document) ed è il nodo da cui si verificano tutti gli altri arricchimenti.

L'elenco seguente include diversi esempi comuni:

/documentè il nodo radice e indica un intero BLOB in Archiviazione di Azure o una riga in una tabella SQL.
/document/{key} è la sintassi per un documento o un elemento in una raccolta di Azure Cosmos DB, dove {key} è la chiave effettiva, ad esempio /document/HotelId nell'esempio precedente.
/document/content specifica la proprietà "content" di un BLOB JSON.
/document/{field} è la sintassi per un'operazione eseguita su un campo specifico, ad esempio la conversione del /document/Description campo, come illustrato nell'esempio precedente.
/document/pages/* o /document/sentences/* diventano il contesto se si suddivide un documento di grandi dimensioni in blocchi più piccoli per l'elaborazione. Se "context" è /document/pages/*, la competenza viene eseguita una volta su ogni pagina del documento. Poiché potrebbero essere presenti più pagine o frasi, si aggiungerà /* per intercettarli tutti.
/document/normalized_images/* viene creato durante il cracking del documento se il documento contiene immagini. Tutti i percorsi delle immagini iniziano con normalized_images. Poiché in un documento sono spesso presenti più immagini incorporate, aggiungere /*.

Gli esempi nella parte restante di questo articolo si basano sul campo "contenuto" generato automaticamente dagli indicizzatori BLOB di Azure come parte della fase di cracking del documento. Quando si fa riferimento a documenti da un contenitore BLOB, usare un formato come "/document/content", dove il campo "contenuto" fa parte del "documento".

Esempio 1: riferimento di annotazione semplice

In Archiviazione BLOB di Azure si supponga di avere un'ampia gamma di file contenenti riferimenti ai nomi degli utenti da estrarre usando il riconoscimento delle entità. Nella definizione di competenza seguente, "/document/content" è la rappresentazione testuale dell'intero documento e "persone" è un'estrazione di nomi completi per le entità identificate come persone.

Poiché il contesto predefinito è "/document", è ora possibile fare riferimento all'elenco delle persone come "/document/people". In questo caso specifico "/document/people" è un'annotazione, che potrebbe ora essere mappata a un campo in un indice o utilizzata in un'altra competenza nello stesso insieme di competenze.

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

Esempio 2: riferimento a una matrice all'interno di un documento

Questo esempio si basa su quello precedente e mostra come richiamare più volte un'operazione di arricchimento tramite lo stesso documento. Supponiamo che nell'esempio precedente viene generata una matrice di stringhe con i nomi di 10 persone da un singolo documento. Un passaggio successivo congruo potrebbe essere un secondo arricchimento che estrae il cognome da nome e cognome. Poiché sono presenti 10 nomi, questo passaggio deve essere chiamato 10 volte in questo documento, una volta per ogni persona.

Per richiamare il corretto numero di iterazioni, impostare il contesto come "/document/people/*", in cui l'asterisco ("*") rappresenta tutti i nodi nel documento arricchito come discendenti di "/document/people". Anche se questa competenza viene definita una sola volta nella matrice di competenze, viene chiamata per ogni membro all'interno del documento fino a quando non vengono elaborati tutti i membri.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

Quando le annotazioni sono matrici o raccolte di stringhe, è possibile fare riferimento a membri specifici anziché alla matrice nel suo complesso. L'esempio precedente genera un'annotazione denominata "last" in ogni nodo rappresentato dal contesto. Se si desidera fare riferimento a questa famiglia di annotazioni, è possibile utilizzare la sintassi "/document/people/*/last". Se si desidera fare riferimento a un'annotazione particolare, è possibile utilizzare un indice esplicito: "/document/people/1/last"per fare riferimento al cognome del primo utente identificato nel documento. Si noti che in questa sintassi le matrici sono "indicizzate a 0".

Esempio 3: riferimento a membri all'interno di una matrice

In alcuni casi è necessario raggruppare tutte le annotazioni di un determinato tipo per trasmetterle a una determinata competenza. Prendere in considerazione un’ipotetica competenza personalizzata che identifica il cognome più comune da tutti i cognomi estratti nell'esempio 2. Per fornire alla competenza personalizzata solo i cognomi, specificare il contesto come "/document" e l'input come "/document/people/*/lastname".

Si noti che la cardinalità di "/document/people/*/lastname" è maggiore di quella del documento. Potrebbero essere presenti 10 nodi lastname, mentre per questo documento è presente un solo nodo documento. In tal caso, il sistema creerà automaticamente una matrice di "/document/people/*/lastname" contenente tutti gli elementi nel documento.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

Suggerimenti per la risoluzione dei problemi del percorso di annotazione

Se si verificano problemi con la specifica degli input delle competenze, questi suggerimenti potrebbero aiutare a procedere:

Eseguire la procedura guidata Importa dati sui dati per esaminare le definizioni del set di competenze e i mapping dei campi generati dalla procedura guidata.
Avviare una sessione di debug in un set di competenze per visualizzare la struttura di un documento arricchito. È possibile modificare i percorsi e altre parti della definizione della competenza e quindi eseguire la competenza per convalidare le modifiche.