Creare un set di competenze in Azure AI Search

  • Articolo

indexer stages

Un set di competenze definisce operazioni che generano contenuto testuale e struttura da documenti che contengono immagini o testo non strutturato. Gli esempi sono 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 testo 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, ma gli stessi concetti e passaggi si applicano ad altri linguaggi di programmazione.

Le regole per la definizione del set di competenze includono:

  • 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. Le abilità da tre a cinque sono tipiche. Il valore massimo è 30.
  • Un set di competenze può ripetere le competenze dello stesso tipo (ad esempio, più competenze di Shaper).
  • Un set di competenze supporta operazioni concatenati, cicli e diramazione.

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

Suggerimento

Abilitare la memorizzazione nella cache degli arricchimenti per riutilizzare il contenuto già elaborato e ridurre il costo dello sviluppo.

Aggiungere una definizione del set di competenze

Iniziare con la struttura di base. Nell'API REST Create Skillset 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":{ }
}

Dopo il nome e la descrizione, un set di competenze ha quattro proprietà principali:

  • skills matrice, una raccolta non ordinata di competenze. Le competenze possono essere utilitaristiche (ad esempio la suddivisione del testo), la trasformazione (basata sull'intelligenza artificiale dai servizi di intelligenza artificiale di Azure) o le competenze personalizzate fornite dall'utente. Nella sezione successiva viene fornito un esempio di matrice di competenze.

  • cognitiveServices viene usato per competenze fatturabili che chiamano le API dei servizi di intelligenza artificiale di Azure. Rimuovere questa sezione se non si usano competenze fatturabili o Ricerca entità personalizzata. Allegare una risorsa , se si è.

  • knowledgeStore(facoltativo) specifica un account e impostazioni Archiviazione di Azure 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 chiavi gestite dal cliente usati per crittografare contenuto sensibile (descrizioni, stringa di connessione, chiavi) in una definizione del set di competenze. Rimuovere questa proprietà se non si usa la crittografia gestita dal cliente.

Aggiungere competenze

All'interno della definizione del set di competenze, la matrice di competenze specifica le competenze da eseguire. Le competenze da tre a cinque sono comuni, ma è possibile aggiungere tutte le competenze necessarie, soggette ai limiti del servizio.

Il risultato finale di una pipeline di arricchimento è 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, didascalia, tag) o analizza il testo esistente per creare nuove informazioni (entità, frasi chiave, sentiment). 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 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. Facoltativamente, una competenza potrebbe avere un nome e una descrizione. L'esempio seguente mostra due competenze predefinite non correlate in modo da poter confrontare 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 sulle competenze descrive tutti i parametri e le proprietà di una determinata competenza. Anche se esistono differenze, la maggior parte delle competenze condivide un set comune e viene impostata in modo analogo.

Nota

È possibile creare set di competenze complessi con cicli e diramazioni usando la competenza Condizionale per creare le espressioni. La sintassi si basa sulla notazione del percorso del puntatore JSON, con alcune modifiche per identificare i nodi nell'albero di arricchimento. Un "/" attraversa un livello inferiore nell'albero e "*" funge da operatore for-each nel contesto. Numerosi esempi in questo articolo illustrano la sintassi.

Impostare il contesto della competenza

Ogni competenza ha una proprietà di contesto che determina il livello in cui vengono eseguite 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 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": []
  }
]

Il contesto viene in genere impostato su uno degli esempi seguenti:

Esempio di contesto Descrizione
"context": "/document" (Impostazione predefinita) Gli input e gli output sono a livello di documento.
"context": "/document/pages/*" Alcune competenze come l'analisi del sentiment offrono prestazioni migliori rispetto a blocchi di testo più piccoli. Se si divide un campo di contenuto di grandi dimensioni in pagine o frasi, il contesto deve essere posizionato su ogni parte del componente.
"context": "/document/normalized_images/*" Per il contenuto dell'immagine, gli input e gli output sono uno per ogni immagine nel documento padre.

Il contesto determina anche 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", viene aggiunto un nodo "organizzazioni" come figlio di "/document". Se si vuole quindi fare riferimento a questo nodo nelle competenze downstream, il percorso sarà "/document/orgs".

Definire gli input

Competenze lette 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 sulle competenze per ogni competenza descrive gli input che può usare. Ogni input ha un "nome" che identifica un input specifico e una "origine" 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 più 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 è 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 è in genere 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 "riepilogo".
    "source": "/document/normalized_images/*" Per il contenuto dell'immagine, l'origine è l'immagine normalizzata durante la creazione di documenti.

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

Definire gli output

Ogni competenza è progettata per generare tipi specifici di output, a cui viene fatto riferimento in base al nome nel set di competenze. Un output della competenza ha un "nome" e un "targetName" facoltativo.

La documentazione di riferimento sulle 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 più output. Il "nome" identifica un output specifico. Ad esempio, per Riconoscimento entità, l'output può essere "persone", "posizioni", "organizzazioni", tra gli altri.

  • "targetName" 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 hanno più competenze che restituiscono lo stesso output, usare per la "targetName" 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. A tale scopo, 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 linguistico. Può 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, a cui è possibile fare riferimento in un indice di ricerca, una proiezione dell'archivio conoscenze o 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 fornita. Per altre informazioni, vedere Definire un'interfaccia personalizzata.

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. Legge e scrive anche 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), si userà il percorso "/document/orgs/*/companyDescription" per farlo.

{
  "@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 della competenza può essere memorizzato nella cache facoltativamente a scopo di riutilizzo, in genere è temporaneo ed esiste solo mentre l'esecuzione delle competenze è in corso.

  • 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 di input della competenza downstream. Per esempi, vedere Fare riferimento a un'annotazione .

Suggerimenti per un primo set di competenze

  • Provare la procedura guidata Importa dati.

    La procedura guidata automatizza diversi passaggi che possono risultare difficili per la prima volta. Definisce il set di competenze, l'indice e l'indicizzatore, inclusi mapping dei campi e mapping dei campi di output. Definisce anche le proiezioni in un archivio conoscenze se ne usa uno. 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 l'individuazione dei documenti.

    Dopo l'esecuzione della procedura guidata, è possibile aprire ogni oggetto nel portale di Azure per visualizzarne la definizione JSON.

  • Provare Sessioni di debug per richiamare l'esecuzione del set di competenze su un documento di destinazione ed 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 sessioni di debug.

Passaggi successivi

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

Riferimento alle annotazioni in un set di competenze