Come creare un oggetto di competenze in una pipeline di arricchimento di intelligenza artificiale in Azure ricerca cognitivaHow to create a skillset in an AI enrichment pipeline in Azure Cognitive Search

fasi dell'indicizzatoreindexer stages

Un skillt definisce le operazioni che estraggono e arricchiscono i dati per renderle ricercabili.A skillset defines the operations that extract and enrich data to make it searchable. Un skillt viene eseguito dopo che il contenuto di testo e immagine viene estratto dai documenti di origine e dopo che tutti i campi del documento di origine sono mappati a campi di destinazione in un indice o in un archivio informazioni.A skillset executes after text and image content are extracted from source documents, and after any fields from the source document are (optionally) mapped to destination fields in an index or knowledge store.

Un skillt contiene una o più competenze cognitive che rappresentano un'operazione di arricchimento specifica, ad esempio la conversione di testo, l'estrazione di frasi chiave o l'esecuzione del riconoscimento ottico dei caratteri da un file di immagine.A skillset contains one or more cognitive skills that represent a specific enrichment operation, like translating text, extracting key phrases, or performing optical character recognition from an image file. Per creare un di competenze, è possibile usare le competenze predefinite di Microsoft o competenze personalizzate che contengono modelli o logica di elaborazione fornita (vedere esempio: creazione di un'abilità personalizzata in una pipeline di arricchimento intelligenza artificiale per ulteriori informazioni).To create a skillset, you can use built-in skills from Microsoft, or custom skills that contain models or processing logic that you provide (see Example: Creating a custom skill in an AI enrichment pipeline for more information).

Questo articolo descrive come creare una pipeline di arricchimento per le competenze che si vuole usare.In this article, you learn how to create an enrichment pipeline for the skills you want to use. Un skillt è associato a un indicizzatoredi Azure ricerca cognitiva.A skillset is attached to an Azure Cognitive Search indexer. Una parte della progettazione della pipeline, trattata in questo articolo, consiste nella costruzione del set di competenze stesso.One part of pipeline design, covered in this article, is constructing the skillset itself.

Nota

L'altra parte della progettazione della pipeline prevede la specifica di un indicizzatore e viene descritta nel prossimo passaggio.Another part of pipeline design is specifying an indexer, covered in the next step. Una definizione di indicizzatore include un riferimento al set di competenze, nonché i mapping dei campi usati per connettere gli input agli output nell'indice di destinazione.An indexer definition includes a reference to the skillset, plus field mappings used for connecting inputs to outputs in the target index.

Punti principali da tenere presente:Key points to remember:

  • È possibile avere solo un set di competenze per indicizzatore.You can only have one skillset per indexer.
  • Un set di competenze deve includere almeno una competenza.A skillset must have at least one skill.
  • È possibile creare più competenze dello stesso tipo (ad esempio, varianti di una competenza di analisi di immagini).You can create multiple skills of the same type (for example, variants of an image analysis skill).

Iniziare definendo l'obiettivo da raggiungereBegin with the end in mind

Il primo passaggio consigliato consiste nel decidere quali dati estrarre dai dati non elaborati e come usarli in una soluzione di ricerca.A recommended initial step is deciding which data to extract from your raw data and how you want to use that data in a search solution. Per identificare meglio i passaggi necessari, si può creare un'illustrazione dell'intera pipeline di arricchimento.Creating an illustration of the entire enrichment pipeline can help you identify the necessary steps.

Si supponga di essere interessati all'elaborazione di un set di commenti di analisti finanziari.Suppose you are interested in processing a set of financial analyst comments. Per ogni file si desidera estrarre i nomi delle società e la valutazione generale dei commenti.For each file, you want to extract company names and the general sentiment of the comments. Si desidera inoltre scrivere un arricchitore personalizzato che usi il servizio Ricerca entità di Bing per ottenere informazioni aggiuntive sulla società, ad esempio il tipo di business svolto della società.You might also want to write a custom enricher that uses the Bing Entity Search service to find additional information about the company, such as what kind of business the company is engaged in. Si desidera, in pratica, estrarre informazioni simili alle seguenti, indicizzate per ogni documento:Essentially, you want to extract information like the following, indexed for each document:

Testo del recordrecord-text Societàcompanies sentimentsentiment Descrizione della societàcompany descriptions
record di esempiosample-record ["Microsoft", "LinkedIn"]["Microsoft", "LinkedIn"] 0.990.99 ["Microsoft Corporation è una società di tecnologia multinazionale american...", "LinkedIn è un social network orientato al business e all'occupazione..."]["Microsoft Corporation is an American multinational technology company ..." , "LinkedIn is a business- and employment-oriented social networking..."]

Il diagramma seguente illustra una pipeline di arricchimento ipotetica:The following diagram illustrates a hypothetical enrichment pipeline:

Una pipeline di arricchimento ipoteticaA hypothetical enrichment pipeline

Quando si ha un'idea chiara del contenuto che si desidera includere nella pipeline, si può specificare il set di competenze per eseguire questi passaggi.Once you have fair idea of what you want in the pipeline, you can express the skillset that provides these steps. Dal punto di vista funzionale, il livello di competenze viene espresso quando si carica la definizione dell'indicizzatore in Azure ricerca cognitiva.Functionally, the skillset is expressed when you upload your indexer definition to Azure Cognitive Search. Per altre informazioni su come caricare l'indicizzatore, vedere la documentazione relativa all'indicizzatore.To learn more about how to upload your indexer, see the indexer-documentation.

Nel diagramma il passaggio di individuazione del documento avviene automaticamente.In the diagram, the document cracking step happens automatically. In pratica, Azure ricerca cognitiva sa come aprire file noti e crea un campo contenuto contenente il testo Estratto da ogni documento.Essentially, Azure Cognitive Search knows how to open well-known files and creates a content field containing the text extracted from each document. Le caselle bianche sono arricchitori integrati e la casella punteggiata "Ricerca entità di Bing" rappresenta un arricchitore personalizzato che si sta creando.The white boxes are built-in enrichers, and the dotted "Bing Entity Search" box represents a custom enricher that you are creating. Come illustrato, il set di competenze contiene tre competenze.As illustrated, the skillset contains three skills.

Definizione del set di competenze in RESTSkillset definition in REST

Un set di competenze è definito come una matrice di competenze.A skillset is defined as an array of skills. Ogni competenza definisce l'origine dei relativi input e il nome degli output generati.Each skill defines the source of its inputs and the name of the outputs produced. Tramite l'API REST di creazione del set di competenze è possibile definire un set di competenze corrispondente al diagramma precedente:Using the Create Skillset REST API, you can define a skillset that corresponds to the previous diagram:

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2020-06-30
api-key: [admin key]
Content-Type: application/json
{
  "description": 
  "Extract sentiment from financial records, extract company names, and then find additional information about each company mentioned.",
  "skills":
  [
    {
      "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
      "context": "/document",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "organizations"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.SentimentSkill",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "score",
          "targetName": "mySentiment"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
     "description": "Calls an Azure function, which in turn calls Bing Entity Search",
      "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeTextAnalyticsV3?code=foo",
      "httpHeaders": {
          "Ocp-Apim-Subscription-Key": "foobar"
      },
      "context": "/document/organizations/*",
      "inputs": [
        {
          "name": "query",
          "source": "/document/organizations/*"
        }
      ],
      "outputs": [
        {
          "name": "description",
          "targetName": "companyDescription"
        }
      ]
    }
  ]
}

Creare un set di competenzeCreate a skillset

Durante la creazione di un set di competenze è possibile specificare una descrizione per autodocumentare il set.While creating a skillset, you can provide a description to make the skillset self-documenting. Una descrizione è facoltativa, ma è utile per tenere traccia dello scopo di un set di competenze.A description is optional, but useful for keeping track of what a skillset does. Poiché il set di competenze è un documento JSON, che non consente di includere commenti, è necessario usare un elemento description per la descrizione.Because skillset is a JSON document, which does not allow comments, you must use a description element for this.

{
  "description": 
  "This is our first skill set, it extracts sentiment from financial records, extract company names, and then finds additional information about each company mentioned.",
  ...
}

La parte successiva nel set di competenze è una matrice di competenze.The next piece in the skillset is an array of skills. Si può pensare a ogni competenza come una primitiva di arricchimento.You can think of each skill as a primitive of enrichment. Ogni competenza esegue una breve attività all'interno di questa pipeline di arricchimento.Each skill performs a small task in this enrichment pipeline. Ognuna prende un input (o un set di input) e restituisce output.Each one takes an input (or a set of inputs), and returns some outputs. Le prossime sezioni si concentrano su come specificare le competenze predefinite e personalizzate, concatenando le competenze tramite riferimenti di input e output.The next few sections focus on how to specify built-in and custom skills, chaining skills together through input and output references. Gli input possono provenire da dati di origine o da un'altra competenza.Inputs can come from source data or from another skill. Gli output possono essere mappati a un campo in un indice di ricerca o essere usati come input per una competenza a valle.Outputs can be mapped to a field in a search index or used as an input to a downstream skill.

Aggiungi competenze predefiniteAdd built-in skills

Verrà ora esaminata la prima competenza, ovvero la capacità di riconoscimento entitàincorporata:Let's look at the first skill, which is the built-in entity recognition skill:

    {
      "@odata.type": "#Microsoft.Skills.Text.EntityRecognitionSkill",
      "context": "/document",
      "categories": [ "Organization" ],
      "defaultLanguageCode": "en",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "organizations",
          "targetName": "organizations"
        }
      ]
    }
  • Tutte le competenze predefinite hanno odata.type proprietà, input e output .Every built-in skill has odata.type, input, and output properties. Le proprietà specifiche della competenza includono informazioni aggiuntive applicabili alla competenza stessa.Skill-specific properties provide additional information applicable to that skill. Per il riconoscimento delle entità, categories è un'entità tra un set fisso di tipi di entità che il modello precedentemente preparato è in grado di riconoscere.For entity recognition, categories is one entity among a fixed set of entity types that the pretrained model can recognize.

  • Ogni competenza deve avere un "context".Each skill should have a "context". Il contesto rappresenta il livello in cui vengono eseguite le operazioni.The context represents the level at which operations take place. Nelle competenze precedenti, il contesto è l'intero documento, vale a dire che l'abilità di riconoscimento delle entità viene chiamata una volta per ogni documento.In the skill above, the context is the whole document, meaning that the entity recognition skill is called once per document. Anche gli output vengono generati in tale livello.Outputs are also produced at that level. L'elemento "organizations", più specificatamente, viene generato come membro di "/document".More specifically, "organizations" are generated as a member of "/document". Nelle competenze a valle è possibile fare riferimento a queste informazioni appena create come "/document/organizations".In downstream skills, you can refer to this newly created information as "/document/organizations". Se il campo "context" non viene impostato in modo esplicito, il contesto predefinito è il documento.If the "context" field is not explicitly set, the default context is the document.

  • La competenza include un input denominato "testo", con un input di origine impostato su "/document/content".The skill has one input called "text", with a source input set to "/document/content". L'abilità (riconoscimento entità) opera sul campo contenuto di ogni documento, che è un campo standard creato dall'indicizzatore BLOB di Azure.The skill (entity recognition) operates on the content field of each document, which is a standard field created by the Azure blob indexer.

  • La competenza genera un output denominato "organizations".The skill has one output called "organizations". Gli output esistono solo durante l'elaborazione.Outputs exist only during processing. Per concatenare questo output all'input della competenza a valle, fare riferimento all'output come "/document/organizations".To chain this output to a downstream skill's input, reference the output as "/document/organizations".

  • Per un particolare documento, il valore di "/document/organizations" è una matrice di organizzazioni estratte dal testo.For a particular document, the value of "/document/organizations" is an array of organizations extracted from the text. Ad esempio:For example:

    ["Microsoft", "LinkedIn"]
    

Alcune situazioni richiedono che si faccia riferimento a ogni elemento della matrice separatamente.Some situations call for referencing each element of an array separately. Si supponga ad esempio di voler passare ogni elemento di "/document/organizations" separatamente a un'altra competenza (ad esempio l'arricchitore di Ricerca entità di Bing personalizzato).For example, suppose you want to pass each element of "/document/organizations" separately to another skill (such as the custom Bing entity search enricher). È possibile fare riferimento a ogni elemento della matrice aggiungendo un asterisco al percorso: "/document/organizations/*"You can refer to each element of the array by adding an asterisk to the path: "/document/organizations/*"

La seconda competenza che riguarda l'estrazione delle valutazioni segue lo stesso modello del primo arricchitore.The second skill for sentiment extraction follows the same pattern as the first enricher. Prende "/document/content" come input e restituisce un punteggio di valutazione per ogni istanza del contenuto.It takes "/document/content" as input, and returns a sentiment score for each content instance. Poiché il campo "context" non è stato impostato in modo esplicito, l'output (mySentiment) è un figlio di "/document".Since you did not set the "context" field explicitly, the output (mySentiment) is now a child of "/document".

    {
      "@odata.type": "#Microsoft.Skills.Text.SentimentSkill",
      "inputs": [
        {
          "name": "text",
          "source": "/document/content"
        }
      ],
      "outputs": [
        {
          "name": "score",
          "targetName": "mySentiment"
        }
      ]
    },

Aggiungere una competenza personalizzataAdd a custom skill

Richiamare la struttura dell'arricchitore di Ricerca entità di Bing personalizzato:Recall the structure of the custom Bing entity search enricher:

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

Questa definizione è un' abilità personalizzata che chiama un'API Web come parte del processo di arricchimento.This definition is a custom skill that calls a web API as part of the enrichment process. Per ogni organizzazione identificata dal riconoscimento delle entità, questa competenza chiama un'API Web per trovare la descrizione di tale organizzazione.For each organization identified by entity recognition, this skill calls a web API to find the description of that organization. L'orchestrazione di quando chiamare l'API Web e come propagare le informazioni ricevute viene gestita internamente dal motore di arricchimento.The orchestration of when to call the web API and how to flow the information received is handled internally by the enrichment engine. L'inizializzazione necessaria per chiamare l'API personalizzata deve tuttavia essere specificata nel file JSON (ad esempio URI, intestazioni http e input previsti).However, the initialization necessary for calling this custom API must be provided in the JSON (such as uri, httpHeaders, and the inputs expected). Per informazioni sulla creazione di un'API Web personalizzata per la pipeline di arricchimento, vedere How to define a custom interface (Come definire un'interfaccia personalizzata).For guidance in creating a custom web API for the enrichment pipeline, see How to define a custom interface.

Si noti che il campo "contesto" è impostato su "/document/organizations/*" con un asterisco. Questo significa che il passaggio di arricchimento viene chiamato per ogni organizzazione presente in "/document/organizations".Notice that the "context" field is set to "/document/organizations/*" with an asterisk, meaning the enrichment step is called for each organization under "/document/organizations".

L'output, in questo caso la descrizione di una società, viene generato per ogni organizzazione identificata.Output, in this case a company description, is generated for each organization identified. Quando si fa riferimento alla descrizione in un passaggio a valle (ad esempio, nell'estrazione di frasi chiave), si usa il percorso "/document/organizations/*/description" a tale scopo.When referring to the description in a downstream step (for example, in key phrase extraction), you would use the path "/document/organizations/*/description" to do so.

Aggiungi strutturaAdd structure

Il set di competenze genera informazioni strutturate da dati non strutturati.The skillset generates structured information out of unstructured data. Si consideri l'esempio seguente:Consider the following example:

"Nel quarto trimestre Microsoft ha registrato $1,1 miliardi in ricavi da LinkedIn, la società di social networking acquistata l'anno scorso. L'acquisizione consente a Microsoft di combinare le funzionalità di LinkedIn con le relative funzionalità CRM e Office. Gli azionisti sono entusiasti del progresso fino a questo punto. ""In its fourth quarter, Microsoft logged $1.1 billion in revenue from LinkedIn, the social networking company it bought last year. The acquisition enables Microsoft to combine LinkedIn capabilities with its CRM and Office capabilities. Stockholders are excited with the progress so far."

Un probabile risultato può essere una struttura generata simile a quella nella figura riportata di seguito:A likely outcome would be a generated structure similar to the following illustration:

Esempio di struttura di outputSample output structure

Fino ad ora, questa struttura è stata solo interna, solo di memoria e usata solo negli indici ricerca cognitiva di Azure.Until now, this structure has been internal-only, memory-only, and used only in Azure Cognitive Search indexes. L'aggiunta di un archivio informazioni consente di salvare gli arricchimenti a forme da usare all'esterno della ricerca.The addition of a knowledge store gives you a way to save shaped enrichments for use outside of search.

Aggiungere un archivio informazioniAdd a knowledge store

Archivio informazioni è una funzionalità di Azure ricerca cognitiva per il salvataggio del documento arricchito.Knowledge store is a feature in Azure Cognitive Search for saving your enriched document. Un archivio informazioni creato, supportato da un account di archiviazione di Azure, è il repository in cui i dati arricchiti vengono archiviati.A knowledge store that you create, backed by an Azure storage account, is the repository where your enriched data lands.

Una definizione dell'archivio informazioni viene aggiunta a un oggetto di competenze.A knowledge store definition is added to a skillset. Per una procedura dettagliata dell'intero processo, vedere creare un archivio informazioni in Rest.For a walkthrough of the entire process, see Create a knowledge store in REST.

"knowledgeStore": {
  "storageConnectionString": "<an Azure storage connection string>",
  "projections" : [
    {
      "tables": [ ]
    },
    {
      "objects": [
        {
          "storageContainer": "containername",
          "source": "/document/EnrichedShape/",
          "key": "/document/Id"
        }
      ]
    }
  ]
}

È possibile scegliere di salvare i documenti arricchiti come tabelle con relazioni gerarchiche conservate o come documenti JSON nell'archivio BLOB.You can choose to save the enriched documents as tables with hierarchical relationships preserved or as JSON documents in blob storage. L'output di una qualsiasi delle competenze nel grado di competenze può essere originato come input per la proiezione.Output from any of the skills in the skillset can be sourced as the input for the projection. Se si sta cercando di proiettare i dati in una forma specifica, l' abilità di shaper aggiornata può ora modellare tipi complessi da usare.If you are looking to project the data into a specific shape, the updated shaper skill can now model complex types for you to use.

Passaggi successiviNext steps

Dopo avere acquisito familiarità con la pipeline di arricchimento e i set di competenze, passare a Come fare riferimento alle annotazioni in un set di competenze o How to map outputs to fields in an index (Come mappare gli output ai campi di un indice).Now that you are familiar with the enrichment pipeline and skillsets, continue with How to reference annotations in a skillset or How to map outputs to fields in an index.