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. Esempi sono il riconoscimento ottico dei caratteri (OCR) per le immagini, il riconoscimento delle entità per il testo non indifferenziato e la traduzione testuale. 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:

• Deve avere 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.
• Deve avere almeno una competenza. Da tre a cinque competenze sono tipiche. Il valore massimo è 30.
• Un set di competenze può ripetere le competenze dello stesso tipo. Ad esempio, un set di competenze può avere più competenze di 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. In caso affermativo, collegare una risorsa multiservizio di Intelligenza artificiale di Azure.

• 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 di una seconda competenza (ad esempio la traduzione testuale). 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 context proprietà non è impostata in modo esplicito, il valore predefinito è "/document", dove il contesto è l'intero documento (la competenza viene chiamata una volta per ogni 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": []
  }
]

La context proprietà viene in genere impostata 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", un organizations nodo viene aggiunto come elemento figlio di "/document". Se si vuole fare riferimento a questo nodo nelle competenze downstream, il percorso è "/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. Ogni input ha un name oggetto che identifica un input specifico e un source oggetto 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 testo e languageCode.

• La source proprietà 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, ad esempio il riconoscimento di entità o l'estrazione di frasi chiave, l'origine deve essere un campo contenente testo sufficiente da analizzare, ad esempio una descrizione o un riepilogo.
  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 di competenza ha un name e un oggetto facoltativo targetName.

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. La name proprietà identifica un output specifico. Ad esempio, per Riconoscimento entità, l'output può essere persone, località, organizzazioni, tra le altre.

• La targetName proprietà specifica il nome che si desidera che il nodo abbia nel documento arricchito. Ciò è utile se gli output delle competenze hanno lo stesso nome. Se si dispone di più competenze che restituiscono 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 Aggiungere una competenza personalizzata a una pipeline di arricchimento di Ricerca intelligenza artificiale di Azure.

Anche se la competenza personalizzata esegue codice esterno alla pipeline, in una matrice di competenze è solo 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 context campo è impostato su "/document/orgs/*" con un asterisco, ovvero il passaggio di arricchimento viene chiamato per ogni organizzazione 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 la procedura guidata Importa dati o Importare e vettorializzare i dati.

  Le procedure guidate automatizzano diversi passaggi che possono risultare difficili per la prima volta. 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.

Passaggio successivo

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.