Creare un set di competenze in Azure AI Search

Un set di competenze definisce le operazioni che generano contenuto e struttura di testo da documenti contenenti immagini o testi non strutturati. Gli esempi sono il riconoscimento ottico dei caratteri (OCR) per le immagini, il riconoscimento delle entità per il testo indifferenziato e la traduzione testo. Un set di competenze viene eseguito dopo l'estrazione di testi e immagini da un'origine dati esterna e dopo l'elaborazione dei mapping dei campi.

Questo articolo illustra come creare un set di competenze usando le API REST, tuttavia gli stessi concetti e passaggi sono applicabili ad altri linguaggi di programmazione.

Le regole per la definizione del set di competenze includono:

• Un nome univoco all'interno della raccolta del set di competenze. Un set di competenze è una risorsa di primo livello che può essere usata da qualsiasi indicizzatore.
• Almeno una competenza. Da tre a cinque competenze sono tipiche. Il valore massimo è 30.
• Un set di competenze può ripetere competenze dello stesso tipo (ad esempio, più competenze Shaper).
• Un set di competenze supporta operazioni concatenate, cicli e diramazioni.

Gli indicizzatori determinano l'esecuzione del set di competenze. È necessario disporre di un indicizzatore, un'origine dati e di un indice per poter testare il set di competenze.

Aggiungere una definizione di un set di competenze

Iniziare con la struttura di base. In Crea API REST per il set di competenze, il corpo della richiesta viene creato in JSON e include le sezioni seguenti:

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"An Azure AI services resource in the same region as Azure AI Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

Oltre al nome e alla descrizione, un set di competenze ha quattro proprietà principali:

• Matrice skills, una raccolta di competenze non ordinata. Le competenze possono essere utilitaristiche (ad esempio, suddivisione del testo), trasformative (basate sull'intelligenza artificiale dei Servizi di Azure AI) o personalizzate, ovvero fornite dall'utente. Nella sezione successiva si fornisce un esempio di matrice di competenze.

• cognitiveServices si utilizza per le competenze fatturabili che chiamano le API dei Servizi di Azure AI. Rimuovere questa sezione se non si usano competenze fatturabili o la Ricerca entità personalizzata. Rendere visibile una risorsa se si usano.

• knowledgeStore (facoltativo) specifica un account di archiviazione di Azure e le impostazioni per proiettare l'output del set di competenze in tabelle, BLOB e file in Archiviazione di Azure. Rimuovere questa sezione se non è necessaria. In caso contrario, specificare un archivio conoscenze.

• encryptionKey (facoltativo) specifica un insieme di credenziali delle chiavi di Azure e le chiavi gestite dal cliente usate per crittografare il contenuto sensibile (descrizioni, stringhe di connessione, chiavi) in una definizione del set di competenze. Rimuovere questa proprietà se non si usa la crittografia gestita dal cliente.

Aggiungere competenze

Nella definizione del set di competenze, la matrice di competenze indica quali competenze eseguire. È comune indicare da tre a cinque competenze, tuttavia è possibile aggiungere tutte le competenze desiderate, purché entro i limiti del servizio.

Il risultato finale di una pipeline di arricchimento è il contenuto testuale in un indice di ricerca o in un archivio conoscenze. Per questo motivo, la maggior parte delle competenze crea testo da immagini (testo OCR, didascalie, tag) o analizza il testo esistente per creare nuove informazioni (entità, frasi chiave, valutazione). Le competenze che operano in modo indipendente vengono elaborate in parallelo. Le competenze che dipendono l'una dall'altra specificano l'output di una competenza (ad esempio frasi chiave) come input della seconda competenza (ad esempio la traduzione testo). Il servizio di ricerca determina l'ordine di esecuzione delle competenze e l'ambiente di esecuzione.

Tutte le competenze hanno un tipo, un contesto, input e output. Una competenza potrebbe anche avere un nome e una descrizione. Nell'esempio seguente sono illustrate due competenze predefinite non correlate per permettere il confronto con la struttura di base.

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

Ogni competenza è univoca in termini di valori di input e parametri che accetta. La Documentazione di riferimento delle competenze descrive tutti i parametri e le proprietà di una data competenza. Sebbene vi siano differenze, la maggior parte delle competenze condivide un set comune e impostata in modo simile.

Impostare il contesto della competenza

Ogni competenza ha una proprietà di contesto che determina il livello in cui avvengono le operazioni. Se la proprietà "context" non è impostata in modo esplicito, il valore predefinito è "/document", dove il contesto è l'intero documento (la competenza viene chiamata una volta per ciascun documento).

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

Il contesto viene solitamente impostato su uno degli esempi seguenti:

Inoltre, il contesto determina dove vengono prodotti gli output nell'albero di arricchimento. Ad esempio, la competenza Riconoscimento entità restituisce una proprietà denominata "organizations", acquisita come orgs. Se il contesto è "/document", allora viene aggiunto un nodo "organizations" come elemento figlio di "/document". Pertanto, se si vuole fare riferimento a questo nodo nelle competenze downstream, il percorso sarà "/document/orgs".

Definire gli input

Competenze lette da e scritte in un documento arricchito. Gli input delle competenze specificano l'origine dei dati in ingresso. Spesso è il nodo radice del documento arricchito. Per i BLOB, un input di competenza tipico è la proprietà del contenuto del documento.

La Documentazione di riferimento delle competenze per ogni competenza, descrive gli input che può utilizzare. A ogni input è associato un "name" che identifica un input specifico e una "source" che specifica la posizione dei dati nel documento arricchito. L'esempio seguente proviene dalla competenza Riconoscimento entità:

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

• Le competenze possono avere diversi input. "name" è l'input specifico. Per Riconoscimento entità, gli input specifici sono "text" e "languageCode".

• La proprietà "source" specifica il campo o la riga che fornisce il contenuto da elaborare. Per le competenze basate su testo, l'origine è un campo nel documento o nella riga che fornisce testo. Per le competenze basate su immagini, il nodo che fornisce l'input è costituito da immagini normalizzate.

  Esempio di origine	Descrizione
  "source": "/document"	Per un set di dati tabulare, un documento corrisponde a una riga.
  "source": "/document/content"	Per i BLOB, l'origine è solitamente la proprietà del contenuto del BLOB.
  "source": "/document/some-named-field"	Per le competenze basate su testo, come riconoscimento entità o estrazione di frasi chiave, l'origine deve essere un campo contenente testo sufficiente da analizzare, ad esempio "description" o "summary".
  "source": "/document/normalized_images/*"	Per il contenuto di immagini, l'origine è l'immagine normalizzata durante il cracking di documenti.

Se la competenza esegue l'iterazione su una matrice, il contesto e l'origine dell'input devono includere /* nelle posizioni corrette.

Definire gli output

Ogni competenza è progettata per generare tipi di output specifici ai quali si fa riferimento per nome nel set di competenze. Un output della competenza ha un "name" e un "targetName" facoltativo.

La Documentazione di riferimento delle competenze per ogni competenza descrive gli output che può produrre. L'esempio seguente proviene dalla competenza Riconoscimento entità:

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

• Le competenze possono avere diversi output. "name" identifica un output specifico. Ad esempio, per Riconoscimento entità, l'output può essere "persons", "locations", "organizations", per citarne alcuni.

• "targetName" specifica il nome che si desidera assegnare al nodo nel documento arricchito. Ciò è utile se gli output delle competenze hanno lo stesso nome. Nel caso in cui più competenze restituiscano lo stesso output, usare "targetName" per la disambiguazione dei nomi nei percorsi dei nodi di arricchimento. Se il nome di destinazione non è specificato, la proprietà name viene utilizzata per entrambi.

Alcune situazioni richiedono che si faccia riferimento a ogni elemento della matrice separatamente. Si supponga, ad esempio, di voler passare ogni elemento di "/document/orgs" separatamente a un'altra competenza. Per farlo, aggiungere un asterisco al percorso: "/document/orgs/*".

L'output della competenza viene scritto nel documento arricchito come nuovo nodo nell'albero di arricchimento. Potrebbe trattarsi di un valore semplice, ad esempio un punteggio di valutazione o un codice della lingua. Potrebbe anche trattarsi di una raccolta, ad esempio un elenco di organizzazioni, persone o località. L'output delle competenze può anche essere una struttura complessa, come nel caso della competenza Shaper. Gli input della competenza determinano la composizione della forma, ma l'output è l'oggetto denominato, al quale si può fare riferimento in un indice di ricerca, una proiezione dell'archivio conoscenze o in un'altra competenza in base al nome.

Aggiungere una competenza personalizzata

Questa sezione include un esempio di competenza personalizzata. L'URI punta a una funzione di Azure, che a sua volta richiama il modello o la trasformazione che viene fornita. Per altre informazioni, vedere Definire un'interfaccia personalizzata.

Anche se la competenza personalizzata esegue codice esterno alla pipeline, in una matrice di competenze si tratta soltanto di un'altra competenza. Come le competenze predefinite, ha un tipo, un contesto, input e output. Inoltre, può leggere e scrivere in un albero di arricchimento, proprio come fanno le competenze predefinite. Si noti che il campo "contesto" è impostato su "/document/orgs/*" con un asterisco. Questo significa che il passaggio di arricchimento viene chiamato per ogni organizzazione presente in "/document/orgs".

L'output, ad esempio la descrizione della società in questo esempio, viene generato per ogni organizzazione identificata. Quando si fa riferimento al nodo in un passaggio downstream (ad esempio, nell'estrazione di frasi chiave), il percorso "/document/orgs/*/companyDescription" viene utilizzato a tale scopo.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=foo",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "foobar"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Inviare l'output a una destinazione

Anche se l'output delle competenze può, facoltativamente, essere memorizzato nella cache per il riutilizzo, in genere è temporaneo ed esiste solo durante l'esecuzione delle competenze.

• Per inviare l'output a un campo in un indice di ricerca, creare un mapping dei campi di output in un indicizzatore.

• Per inviare l'output a un archivio conoscenze, creare una proiezione.

• Per inviare l'output a una competenza downstream, fare riferimento all'output in base al nome del nodo, ad esempio "/document/organization", nella proprietà di origine dell'input della competenza downstream. Per altri esempi, vedere Riferimento a un'annotazione.

Suggerimenti per un primo set di competenze

• Provare a eseguire la procedura guidata Importa dati.

  La procedura guidata automatizza diversi passaggi che, la prima volta, potrebbero risultare difficili. Definisce il set di competenze, l'indice e l'indicizzatore, inclusi i mapping dei campi e i mapping dei campi di output. Definisce anche le proiezioni in un archivio conoscenze, se viene utilizzato. Per alcune competenze, ad esempio OCR o analisi delle immagini, la procedura guidata aggiunge competenze di utilità che uniscono l'immagine e il contenuto di testo separati durante il cracking di documenti.

  Quando la procedura guidata viene eseguita è possibile aprire ogni oggetto nel portale di Azure per visualizzarne la definizione JSON.

• Provare le Sessioni di debug per richiamare l'esecuzione del set di competenze su un documento di destinazione, quindi esaminare il documento arricchito creato dal set di competenze. È possibile visualizzare e modificare le impostazioni e i valori di input e output. Questa esercitazione è un buon punto di partenza: Esercitazione - Eseguire il debug di un set di competenze usando le sessioni di debug.

Passaggi successivi

I campi relativi a contesto e origine di input sono percorsi per i nodi in un albero di arricchimento. Nel passaggio successivo, vedere altre informazioni sulla sintassi dei percorso per i nodi in un albero di arricchimento.