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
10/16/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.
“nodo”	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.
“contesto”	Ambito di arricchimento, ovvero l'intero documento, una parte di un documento o, se si utilizzano delle immagini, le immagini estratte da un documento. Per impostazione predefinita, il contesto di arricchimento è al livello `"/document"`, con ambito per i 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.

Il percorso context è /document/HotelId perché la raccolta viene partizionata in documenti dal campo /HotelId.
Il percorso source è /document/Description perché la competenza è una competenza di traduzione, e il campo che si vuole tradurre è il campo Description in ogni documento.

Tutti i percorsi iniziano con /document. Un documento arricchito viene creato nella fase "cracking di documenti" 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 campo /document/Description, 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 di documenti se il documento contiene delle 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 da indicizzatori BLOB di Azure come parte della fase di cracking dei documenti. Quando si fa riferimento ai documenti da un contenitore BLOB, utilizzare un formato, ad esempio "/document/content", dove il campo “contenuto” fa parte del “documento”.

Esempio 1: riferimento di annotazione semplice

Nel servizio di archiviazione BLOB di Azure, si supponga di disporre di una serie di file contenenti i riferimenti ai nomi delle persone che si desidera estrarre tramite riconoscimento delle entità. Nella definizione di competenza riportata di seguito, "/document/content" è la rappresentazione testuale dell'intero documento e "persone" è l'estrazione di nomi e cognome 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". Sebbene questa competenza venga definita solo una volta nella matrice 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 rispetto a quello del documento. Potrebbero essere presenti 10 nodi dei cognomi mentre esserci un solo nodo del documento per questo documento. In tal caso, verranno automaticamente creati 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 relativi al percorso di annotazione

Se si verificano dei 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.

Condividi tramite