Esercitazione su REST: usare set di competenze per generare contenuto ricercabile in Azure AI Search
Questa esercitazione illustra come chiamare API REST che creano una pipeline di arricchimento tramite intelligenza artificiale per l'estrazione e le trasformazioni del contenuto durante l'indicizzazione.
I set di competenze aggiungono l'elaborazione dell'intelligenza artificiale al contenuto non elaborato, rendendolo più uniforme e ricercabile. Una volta appreso il funzionamento dei set di competenze, è possibile supportare un'ampia gamma di trasformazioni: dall'analisi delle immagini all'elaborazione del linguaggio naturale, fino all'elaborazione personalizzata fornita esternamente.
In questa esercitazione si apprenderà come:
- Definire oggetti in una pipeline di arricchimento.
- Generare un set di competenze. Richiamare OCR, rilevamento lingua, riconoscimento entità ed estrazione di frasi chiave.
- Eseguire la pipeline. Creare e caricare un indice di ricerca.
- Controllare i risultati usando la ricerca full-text.
Se non si ha una sottoscrizione di Azure, aprire un account gratuito prima di iniziare.
Panoramica
In questa esercitazione vengono usati un client REST e le API REST di Azure AI Search per creare un'origine dati, un indice, un indicizzatore e un set di competenze.
L'indicizzatore guida ogni passaggio nella pipeline, a partire dall'estrazione del contenuto di dati di esempio (immagini e testo non strutturato) all’interno di un contenitore BLOB in Archiviazione di Azure.
Una volta estratto il contenuto, il set di competenze esegue competenze predefinite da Microsoft per trovare ed estrarre informazioni. Queste competenze includono il riconoscimento ottico dei caratteri (OCR) nelle immagini, il rilevamento lingua nel testo, l’estrazione di frasi chiave e il riconoscimento di entità (organizzazioni). Le nuove informazioni create dal set di competenze vengono inviate ai campi in un indice. Dopo aver popolato l'indice, è possibile usare i campi in query, facet e filtri.
Prerequisiti
Nota
Per questa esercitazione è possibile usare un servizio di ricerca gratuito. Il livello gratuito consente di usare solo tre indici, tre indicizzatori e tre origini dati. Questa esercitazione crea un elemento per ogni tipo. Prima di iniziare, assicurarsi che lo spazio nel servizio sia sufficiente per accettare le nuove risorse.
Scaricare i file
Scaricare un file ZIP del repository di dati di esempio ed estrarre i contenuti. Procedura
Caricare i dati di esempio in Archiviazione di Azure
In Archiviazione di Azure, creare un nuovo contenitore e assegnargli il nome cog-search-demo.
Ottenere una stringa di connessione di archiviazione in modo da poter formulare una connessione in Azure AI Search.
A sinistra, selezionare Chiavi di accesso.
Copiare la stringa di connessione per la chiave uno o la chiave due. La stringa di connessione è simile all'esempio seguente:
DefaultEndpointsProtocol=https;AccountName=<your account name>;AccountKey=<your account key>;EndpointSuffix=core.windows.net
Servizi di Azure AI
L'arricchimento tramite intelligenza artificiale predefinito è supportato dai Servizi di Azure AI, inclusi Servizio cognitivo di Azure per la lingua e Visione di Azure AI per l'elaborazione del linguaggio naturale e delle immagini. Per carichi di lavoro di piccole dimensioni come in questa esercitazione, è possibile usufruire dell’allocazione gratuita di venti transazioni per indicizzatore. Per carichi di lavoro di dimensioni maggiori, collegare una risorsa multiarea di Servizi di Azure AI a un set di competenze per i prezzi con pagamento in base al consumo.
Copiare l'URL del servizio di ricerca e la chiave API
Per questa esercitazione, le connessioni ad Azure AI Search richiedono un endpoint e una chiave API. È possibile ottenere questi valori dal portale di Azure.
Accedere al portale di Azure, passare alla pagina Panoramica del servizio di ricerca e quindi copiare l'URL. Un endpoint di esempio potrebbe essere simile a
https://mydemo.search.windows.net.In Impostazioni>Chiavi, copiare una chiave amministratore. Le chiavi amministratore vengono usate per aggiungere, modificare ed eliminare oggetti. Sono disponibili due chiavi amministratore intercambiabili. Copiarne una.
Configurare il file REST
Avviare Visual Studio Code e aprire il file skillset-tutorial.rest. Per informazioni sul client REST, vedere Avvio rapido: ricerca di testo tramite REST.
Fornire i valori per le variabili, ossia endpoint del servizio di ricerca, chiave API dell'amministratore del servizio di ricerca, nome dell'indice, stringa di connessione all'account di Archiviazione di Azure e nome del contenitore BLOB.
Creare la pipeline
L’arricchimento tramite intelligenza artificiale è guidato dall’indicizzatore. In questa parte della procedura dettagliata vengono creati quattro oggetti: origine dati, definizione dell'indice, set di competenze e indicizzatore.
Passaggio 1: Creare un'origine dati
Chiamare Crea origine dati per impostare la stringa di connessione al contenitore BLOB contenente i file di dati di esempio.
### Create a data source
POST {{baseUrl}}/datasources?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-ds",
"description": null,
"type": "azureblob",
"subtype": null,
"credentials": {
"connectionString": "{{storageConnectionString}}"
},
"container": {
"name": "{{blobContainer}}",
"query": null
},
"dataChangeDetectionPolicy": null,
"dataDeletionDetectionPolicy": null
}
Passaggio 2: creare un set di competenze
Chiamare Crea set di competenze per specificare le procedure di arricchimento da applicare al contenuto. Le competenze vengono eseguite in parallelo, a meno che non vi sia una dipendenza.
### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-ss",
"description": "Apply OCR, detect language, extract entities, and extract key-phrases.",
"cognitiveServices": null,
"skills":
[
{
"@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
"context": "/document/normalized_images/*",
"defaultLanguageCode": "en",
"detectOrientation": true,
"inputs": [
{
"name": "image",
"source": "/document/normalized_images/*"
}
],
"outputs": [
{
"name": "text"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.MergeSkill",
"description": "Create merged_text, which includes all the textual representation of each image inserted at the right location in the content field. This is useful for PDF and other file formats that supported embedded images.",
"context": "/document",
"insertPreTag": " ",
"insertPostTag": " ",
"inputs": [
{
"name":"text",
"source": "/document/content"
},
{
"name": "itemsToInsert",
"source": "/document/normalized_images/*/text"
},
{
"name":"offsets",
"source": "/document/normalized_images/*/contentOffset"
}
],
"outputs": [
{
"name": "mergedText",
"targetName" : "merged_text"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.SplitSkill",
"textSplitMode": "pages",
"maximumPageLength": 4000,
"defaultLanguageCode": "en",
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "textItems",
"targetName": "pages"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
"description": "If you have multilingual content, adding a language code is useful for filtering",
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "languageName",
"targetName": "language"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
"context": "/document/pages/*",
"inputs": [
{
"name": "text",
"source": "/document/pages/*"
}
],
"outputs": [
{
"name": "keyPhrases",
"targetName": "keyPhrases"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Organization"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "organizations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Location"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "locations",
"targetName": "locations"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"categories": ["Person"],
"context": "/document",
"inputs": [
{
"name": "text",
"source": "/document/merged_text"
}
],
"outputs": [
{
"name": "persons",
"targetName": "persons"
}
]
}
]
}
Punti principali:
Il corpo della richiesta specifica le competenze predefinite seguenti:
Skill Descrizione Riconoscimento ottico dei caratteri Riconosce il testo e i numeri nei file di immagine. Fusione di testi Crea un ''contenuto sottoposto a fusione'' che ricombina i contenuti precedentemente separati, utile per i documenti con immagini incorporate (PDF, DOCX e così via). Le immagini e il testo vengono separati durante la fase del cracking di documenti. La competenza di fusione li ricombina inserendo qualsiasi testo riconosciuto, sottotitoli di immagini o tag creati durante l'arricchimento nella stessa posizione in cui è stata estratta l'immagine nel documento. Quando si lavora con contenuti sottoposti a fusione in un set di competenze, questo nodo include tutto il testo del documento, tra cui i documenti di solo testo che non vengono mai sottoposti al riconoscimento ottico dei caratteri (OCR) o all'analisi dell'immagine. Rilevamento lingua Rileva la lingua e produce un nome della lingua o un codice. Nei set di dati multilingue, un campo della lingua può essere utile per i filtri. Riconoscimento delle entità Estrae i nomi di persone, organizzazioni e località dal contenuto sottoposto a fusione. Suddivisione del testo Suddivide i contenuti sottoposti a fusione di grandi dimensioni in blocchi più piccoli prima di chiamare la competenza di estrazione delle frasi chiave. L'estrazione delle frasi chiave accetta input di al massimo 50.000 caratteri. Alcuni dei file di esempio devono essere suddivisi per rispettare questo limite. Estrazione frasi chiave Estrae le frasi chiave principali. Ogni competenza viene eseguita sul contenuto del documento. Durante l'elaborazione, Azure AI Search analizza ogni documento per leggere il contenuto da formati di file diversi. Il testo trovato con origine nel file di origine viene inserito in un campo
contentgenerato, uno per ogni documento. L'input diventa quindi"/document/content".Dal momento che per l'estrazione di frasi chiave si usa la competenza di suddivisione del testo per suddividere file più grandi in pagine, il contesto per la competenza di estrazione delle frasi chiave è
"document/pages/*"(per ogni pagina del documento) invece di"/document/content".
Nota
Gli output possono essere mappati a un indice, usati come input per una competenza a valle, o entrambi, come nel caso del codice di lingua. Nell'indice, un codice di lingua è utile per le operazioni di filtro. Per altre informazioni sui concetti di base dei set di competenze, vedere How to create a skillset (Come creare un set di competenze).
Passaggio 3: creare un indice
Chiama Crea indice per fornire lo schema usato per creare indici invertiti e altri costrutti in Azure AI Search.
Il componente più grande di un indice è la raccolta campi, in cui il tipo di dati e gli attributi determinano il contenuto e i comportamenti in Azure AI Search. Assicurarsi di disporre di campi per il nuovo output generato.
### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-idx",
"defaultScoringProfile": "",
"fields": [
{
"name": "content",
"type": "Edm.String",
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
},
{
"name": "text",
"type": "Collection(Edm.String)",
"facetable": false,
"filterable": true,
"searchable": true,
"sortable": false
},
{
"name": "language",
"type": "Edm.String",
"searchable": false,
"sortable": true,
"filterable": true,
"facetable": false
},
{
"name": "keyPhrases",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "organizations",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "persons",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "locations",
"type": "Collection(Edm.String)",
"searchable": true,
"sortable": false,
"filterable": true,
"facetable": true
},
{
"name": "metadata_storage_path",
"type": "Edm.String",
"key": true,
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
},
{
"name": "metadata_storage_name",
"type": "Edm.String",
"searchable": true,
"sortable": false,
"filterable": false,
"facetable": false
}
]
}
Passaggio 4: creare ed eseguire un indicizzatore
Chiamare Crea indicizzatore per guidare la pipeline. I tre componenti creati finora (origine dati, set di competenze, indice) costituiscono i valori di input di un indicizzatore. La creazione dell'indicizzatore in Azure AI Search è l'evento che mette in moto l'intera pipeline.
Il completamento di questa operazione può richiedere alcuni minuti. Anche se il set di dati è piccolo, le competenze analitiche prevedono un utilizzo elevato delle risorse di calcolo.
### Create and run an indexer
POST {{baseUrl}}/indexers?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"name": "cog-search-demo-idxr",
"description": "",
"dataSourceName" : "cog-search-demo-ds",
"targetIndexName" : "cog-search-demo-idx",
"skillsetName" : "cog-search-demo-ss",
"fieldMappings" : [
{
"sourceFieldName" : "metadata_storage_path",
"targetFieldName" : "metadata_storage_path",
"mappingFunction" : { "name" : "base64Encode" }
},
{
"sourceFieldName": "metadata_storage_name",
"targetFieldName": "metadata_storage_name"
}
],
"outputFieldMappings" :
[
{
"sourceFieldName": "/document/merged_text",
"targetFieldName": "content"
},
{
"sourceFieldName" : "/document/normalized_images/*/text",
"targetFieldName" : "text"
},
{
"sourceFieldName" : "/document/organizations",
"targetFieldName" : "organizations"
},
{
"sourceFieldName": "/document/language",
"targetFieldName": "language"
},
{
"sourceFieldName" : "/document/persons",
"targetFieldName" : "persons"
},
{
"sourceFieldName" : "/document/locations",
"targetFieldName" : "locations"
},
{
"sourceFieldName" : "/document/pages/*/keyPhrases/*",
"targetFieldName" : "keyPhrases"
}
],
"parameters":
{
"batchSize": 1,
"maxFailedItems":-1,
"maxFailedItemsPerBatch":-1,
"configuration":
{
"dataToExtract": "contentAndMetadata",
"imageAction": "generateNormalizedImages"
}
}
}
Punti principali:
Il corpo della richiesta include i riferimenti agli oggetti precedenti, le proprietà di configurazione necessarie per l'elaborazione delle immagini e due tipi di mapping dei campi.
Gli
"fieldMappings"vengono elaborati prima del set di competenze, inviando il contenuto dall'origine dati ai campi di destinazione in un indice. Si usano i mapping dei campi per inviare all'indice i contenuti esistenti e non modificati. Se i nomi e i tipi di campo sono uguali alle due estremità, non è necessario alcun mapping.I
"outputFieldMappings"sono per i campi creati dalle competenze, dopo l'esecuzione del set di competenze. I riferimenti asourceFieldNameinoutputFieldMappingsnon esistono fino a quando non vengono creati dal cracking o dall'arricchimento di documenti. L'oggettotargetFieldNameè un campo in un indice, definito nello schema dell'indice.Il parametro
"maxFailedItems"è impostato su -1, che indica al motore di indicizzazione di ignorare gli errori durante l'importazione dei dati. Questo comportamento è accettabile perché nell'origine dati demo sono presenti pochissimi documenti. Per un'origine dati più grande sarebbe necessario impostare un valore maggiore di 0.L'istruzione
"dataToExtract":"contentAndMetadata"indica all'indicizzatore di estrarre automaticamente i valori dalla proprietà del contenuto del BLOB e dai metadati di ogni oggetto.Il parametro
imageActionindica all'indicizzatore di estrarre il testo dalle immagini presenti nell'origine dati. La configurazione"imageAction":"generateNormalizedImages", unita alla competenza OCR e alla competenza di unione del testo, indica all'indicizzatore di estrarre il testo dalle immagini (ad esempio, la parola "stop" da un segnale stradale di stop) e incorporarlo come parte del campo del contenuto. Questo comportamento si applica sia alle immagini incorporate (si pensi ad un'immagine all'interno di un PDF) che ai file di immagine autonomi, ad esempio un file JPG.
Nota
La creazione di un indicizzatore richiama la pipeline. Eventuali problemi a raggiungere i dati, per il mapping di input e output o nell'ordine delle operazioni vengono visualizzati in questa fase. Per eseguire di nuovo la pipeline con modifiche per codice o script, potrebbe essere necessario eliminare prima gli oggetti. Per altre informazioni, vedere Reimpostare ed eseguire di nuovo.
Monitorare l'indicizzazione
L'indicizzazione e l'arricchimento iniziano non appena si invia la richiesta Crea l'indicizzatore. A seconda della complessità delle competenze e delle operazioni, l'indicizzazione può richiedere un po' di tempo.
Per scoprire se l'indicizzatore è ancora in esecuzione, chiamare Ottieni stato indicizzatore per controllare lo stato dell'indicizzatore.
### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/cog-search-demo-idxr/status?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
Punti principali:
Gli avvisi sono comuni in alcuni scenari e non sempre indicano un problema. Se, ad esempio, un contenitore BLOB include file di immagine e la pipeline non gestisce le immagini, viene visualizzato un avviso che informa che le immagini non sono state elaborate.
In questo esempio, è presente un file PNG che non contiene testo. L'esecuzione di tutte e cinque le competenze basate sul testo, ovvero rilevamento della lingua, riconoscimento delle entità di luoghi, organizzazioni, persone ed estrazione di frasi chiave, non è riuscita in questo file. La notifica risultante viene visualizzata nella cronologia di esecuzione.
Controllare i risultati
Ora che si è creato un indice che include contenuti generati dall'IA, chiamare Cerca documenti per eseguire alcune query e vedere i risultati.
### Query the index\
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"search": "*",
"select": "metadata_storage_name,language,organizations",
"count": true
}
I filtri consentono di limitare i risultati agli elementi di interesse:
### Filter by organization
POST {{baseUrl}}/indexes/cog-search-demo-idx/docs/search?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
{
"search": "*",
"filter": "organizations/any(organizations: organizations eq 'Microsoft')",
"select": "metadata_storage_name,organizations",
"count": true
}
Queste query illustrano alcuni dei modi in cui è possibile usare la sintassi e i filtri di query sui nuovi campi creati da Azure AI Search. Per altri esempi di query, vedere Esempi nell'API REST di ricerca documenti, Esempi di sintassi di query semplice ed Esempi di sintassi di query Lucene completa.
Reimpostare ed eseguire di nuovo
Durante le prime fasi di sviluppo, l'iterazione del progetto è comune. Reimpostare ed eseguire di nuovo agevola l’iterazione.
Risultati
In questa esercitazione sono stati illustrati i passaggi fondamentali per l'uso delle API REST al fine di creare una pipeline di arricchimento tramite intelligenza artificiale, che comprende una fonte di dati, un set di competenze, un indice e un indicizzatore.
Sono state presentate le competenze predefinite, oltre alla definizione del set di competenze che mostra i meccanismi di concatenamento delle competenze tramite input e output. Si è anche appreso che outputFieldMappings nella definizione dell'indicizzatore è obbligatorio per il routing dei valori arricchiti dalla pipeline in un indice cercabile in un servizio Azure AI Search.
Infine, è stato descritto come testare i risultati e reimpostare il sistema per ulteriori iterazioni. Si è appreso che l'esecuzione di query sull'indice consente di restituire l'output creato dalla pipeline di indicizzazione arricchita.
Pulire le risorse
Quando si lavora nella propria sottoscrizione, alla fine di un progetto è opportuno rimuovere le risorse che non sono più necessarie. Le risorse che rimangono in esecuzione hanno un costo. È possibile eliminare risorse singole oppure gruppi di risorse per eliminare l'intero set di risorse.
Per trovare e gestire le risorse nel portale, usare il collegamento Tutte le risorse o Gruppi di risorse nel riquadro di spostamento a sinistra.
Passaggi successivi
Ora che si ha familiarità con tutti gli oggetti che compongono una pipeline di arricchimento tramite intelligenza artificiale, è possibile dare un'occhiata più da vicino alle definizioni di set di competenze e alle competenze individuali.