Creare un archivio conoscenze con REST

Articolo
03/11/2024

In Ricerca di intelligenza artificiale di Azure un archivio conoscenze è un repository di contenuti generati dall'intelligenza artificiale usati per scenari non di ricerca. Creare l'archivio conoscenze usando un indicizzatore e un set di competenze e specificare Archiviazione di Azure per archiviare l'output. Dopo aver popolato l'archivio conoscenze, usare strumenti come Archiviazione Explorer o Power BI per esplorare il contenuto.

In questo articolo si usa l'API REST per inserire, arricchire ed esplorare un set di recensioni dei clienti dei soggiorni di hotel in un archivio conoscenze. L'archivio conoscenze contiene contenuto di testo originale estratto dall'origine, oltre a contenuto generato dall'intelligenza artificiale che include un punteggio del sentiment, l'estrazione di frasi chiave, il rilevamento della lingua e la traduzione testuale dei commenti dei clienti non in inglese.

Per rendere disponibile il set di dati iniziale, le recensioni degli hotel vengono prima importate in Archiviazione BLOB di Azure. Dopo l'elaborazione, i risultati vengono salvati come archivio conoscenze nella tabella di Azure Archiviazione.

Suggerimento

Questo articolo usa REST per spiegazioni dettagliate di ogni passaggio. Scaricare il file REST se si desidera eseguire solo i comandi. In alternativa, è anche possibile creare un archivio conoscenze in portale di Azure.

Prerequisiti

Visual Studio Code con un client REST. Per informazioni introduttive, vedere Guida introduttiva: Ricerca di testo con REST.
Azure AI Search. Creare un servizio o trovarne uno esistente. È possibile usare il servizio gratuito per questo esercizio.
Archiviazione di Azure. Creare un account o trovarne uno esistente. Il tipo di account deve essere Archiviazione V2 (utilizzo generico V2).

Il set di competenze in questo esempio usa i servizi di intelligenza artificiale di Azure per gli arricchimenti. Poiché il carico di lavoro è così piccolo, i servizi di intelligenza artificiale di Azure vengono toccati dietro le quinte per fornire un'elaborazione gratuita per un massimo di 20 transazioni al giorno. Un piccolo carico di lavoro significa che è possibile ignorare la creazione o il collegamento di una risorsa multiservizio di Azure per intelligenza artificiale.

Caricare i dati in Archiviazione di Azure e ottenere un stringa di connessione

Download HotelReviews_Free.csv. Questo csv contiene 19 commenti e suggerimenti dei clienti su un singolo hotel (ha origine da Kaggle.com).
In portale di Azure trovare l'account di archiviazione e usare Archiviazione Browser per creare un contenitore BLOB denominato hotel-reviews.
Selezionare Carica nella parte superiore della pagina per caricare il file HotelReviews-Free.csv scaricato dal passaggio precedente.
A sinistra selezionare Chiavi di accesso, selezionare Mostra chiavi e quindi copiare il stringa di connessione per key1 o key2. Un stringa di connessione di accesso completo ha il formato seguente:

"knowledgeStore": {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-ACCOUNT-NAME>;AccountKey=<YOUR-ACCOUNT-KEY>;EndpointSuffix=core.windows.net;"
}

Nota

Vedere Connessione l'uso di un'identità gestita se non si vogliono fornire dati sensibili nel stringa di connessione.

Copiare una chiave e un URL

In questo esempio, le chiamate REST richiedono l'endpoint del servizio di ricerca e usano una chiave API in ogni richiesta. È possibile ottenere questi valori dalla portale di Azure.

Accedere al portale di Azure, passare alla pagina Panoramica e copiare l'URL. Un endpoint di esempio potrebbe essere simile a https://mydemo.search.windows.net.
In Impostazioni> Chiavi copiare una chiave di amministratore. Amministrazione chiavi vengono usate per aggiungere, modificare ed eliminare oggetti. Sono disponibili due chiavi di amministrazione intercambiabili. Copiarne uno.

Una chiave API valida stabilisce un trust, per ogni richiesta, tra l'applicazione che invia la richiesta e il servizio di ricerca che la gestisce.

Creare un indice

Creare un indice (REST) crea un indice di ricerca nel servizio di ricerca. Un indice di ricerca non è correlato a un archivio conoscenze, ma l'indicizzatore ne richiede uno. L'indice di ricerca contiene lo stesso contenuto dell'archivio conoscenze, che è possibile esplorare inviando richieste di query.

Aprire un nuovo file di testo in Visual Studio Code.

Impostare le variabili sull'endpoint di ricerca e sulla chiave API raccolte in precedenza.

@baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@apiKey = PUT-YOUR-ADMIN-API-KEY-HERE
@storageConnection = PUT-YOUR-STORAGE-CONNECTION-STRING-HERE
@blobContainer = PUT-YOUR-CONTAINER-NAME-HERE (hotel-reviews)

Salvare il file con un'estensione .rest di file.

Incollare l'esempio seguente per creare la richiesta di indice.

### Create a new index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-idx",  
        "fields": [
            { "name": "name", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_date", "type": "Edm.DateTimeOffset", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_rating", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_text", "type": "Edm.String", "filterable": false,  "sortable": false, "facetable": false },
            { "name": "reviews_title", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "reviews_username", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false },
            { "name": "AzureSearch_DocumentKey", "type": "Edm.String", "searchable": false, "filterable": false, "sortable": false, "facetable": false, "key": true },
            { "name": "language", "type": "Edm.String", "filterable": true, "sortable": false, "facetable": true },
            { "name": "translated_text", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false },
            { "name": "sentiment", "type": "Collection(Edm.String)", "searchable": false, "filterable": true, "retrievable": true, "sortable": false, "facetable": true },
            { "name": "keyphrases", "type": "Collection(Edm.String)", "filterable": true, "sortable": false, "facetable": true }
        ]
    }

Selezionare Invia richiesta. È necessario avere una HTTP/1.1 201 Created risposta e il corpo della risposta deve includere la rappresentazione JSON dello schema dell'indice.

Creare un'origine dati

Creare un'origine dati crea una connessione all'origine dati in Ricerca di intelligenza artificiale di Azure.

Incollare l'esempio seguente per creare l'origine dati.

### Create a data source
POST {{baseUrl}}/datasources?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-ds",
        "description": null,
        "type": "azureblob",
        "subtype": null,
        "credentials": {
            "connectionString": "{{storageConnectionString}}"
        },
        "container": {
            "name": "{{blobContainer}}",
            "query": null
        },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null
    }

Selezionare Invia richiesta.

Creare un set di competenze

Un set di competenze definisce arricchimenti (competenze) e l'archivio conoscenze. Creare il set di competenze crea l'oggetto nel servizio di ricerca.

Incollare l'esempio seguente per creare il set di competenze.

### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-ss",
        "description": "Skillset to detect language, translate text, extract key phrases, and score sentiment",
        "skills": [ 
            {
                "@odata.type": "#Microsoft.Skills.Text.SplitSkill", 
                "context": "/document/reviews_text", "textSplitMode": "pages", "maximumPageLength": 5000,
                "inputs": [ 
                    { "name": "text", "source": "/document/reviews_text" }
                ],
                "outputs": [
                    { "name": "textItems", "targetName": "pages" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
                "context": "/document/reviews_text/pages/*",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text/pages/*" },
                    { "name": "languageCode", "source": "/document/language" }
                ],
                "outputs": [
                    { "name": "sentiment", "targetName": "sentiment" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
                "context": "/document",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text" }
                ],
                "outputs": [
                    { "name": "languageCode", "targetName": "language" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.TranslationSkill",
                "context": "/document/reviews_text/pages/*",
                "defaultFromLanguageCode": null,
                "defaultToLanguageCode": "en",
                "inputs": [
                    { "name": "text", "source": "/document/reviews_text/pages/*" }
                ],
                "outputs": [
                    { "name": "translatedText", "targetName": "translated_text" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
                "context": "/document/reviews_text/pages/*",
                "inputs": [
                    { "name": "text",  "source": "/document/reviews_text/pages/*" },
                    { "name": "languageCode",  "source": "/document/language" }
                ],
                "outputs": [
                    { "name": "keyPhrases" , "targetName": "keyphrases" }
                ]
            },
            {
                "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
                "context": "/document",
                "inputs": [
                    { "name": "name",  "source": "/document/name" },
                    { "name": "reviews_date",  "source": "/document/reviews_date" },
                    { "name": "reviews_rating",  "source": "/document/reviews_rating" },
                    { "name": "reviews_text",  "source": "/document/reviews_text" },
                    { "name": "reviews_title",  "source": "/document/reviews_title" },
                    { "name": "reviews_username",  "source": "/document/reviews_username" },
                    { "name": "AzureSearch_DocumentKey",  "source": "/document/AzureSearch_DocumentKey" },
                    {
                    "name": "pages",
                    "sourceContext": "/document/reviews_text/pages/*",
                    "inputs": [
                        {
                        "name": "languageCode",
                        "source": "/document/language"
                        },
                        {
                        "name": "translatedText",
                        "source": "/document/reviews_text/pages/*/translated_text"
                        },
                        { 
                        "name": "sentiment",
                        "source": "/document/reviews_text/pages/*/sentiment"
                        },
                        {
                        "name": "keyPhrases",
                        "source": "/document/reviews_text/pages/*/keyphrases/*"
                        },
                        {
                        "name": "Page",
                        "source": "/document/reviews_text/pages/*"
                        }
                    ]
                    }
                ],
                "outputs": [
                    { "name": "output" , "targetName": "tableprojection" }
                ]
            }
        ],
        "knowledgeStore": {
            "storageConnectionString": "{{storageConnectionString}}",
            "projections": [
                {
                    "tables": [
                        { "tableName": "hotelReviews1Document", "generatedKeyName": "Documentid", "source": "/document/tableprojection" },
                        { "tableName": "hotelReviews2Pages", "generatedKeyName": "Pagesid", "source": "/document/tableprojection/pages/*" },
                        { "tableName": "hotelReviews3KeyPhrases", "generatedKeyName": "KeyPhrasesid", "source": "/document/tableprojection/pages/*/keyPhrases/*" }
                    ],
                    "objects": []
                },
                {
                    "tables": [
                        { 
                            "tableName": "hotelReviews4InlineProjectionDocument", "generatedKeyName": "Documentid", "sourceContext": "/document",
                            "inputs": [
                                { "name": "name", "source": "/document/name"},
                                { "name": "reviews_date", "source": "/document/reviews_date"},
                                { "name": "reviews_rating", "source": "/document/reviews_rating"},
                                { "name": "reviews_username", "source": "/document/reviews_username"},
                                { "name": "reviews_title", "source": "/document/reviews_title"},
                                { "name": "reviews_text", "source": "/document/reviews_text"},
                                { "name": "AzureSearch_DocumentKey", "source": "/document/AzureSearch_DocumentKey" }
                            ]
                        },
                        { 
                            "tableName": "hotelReviews5InlineProjectionPages", "generatedKeyName": "Pagesid", "sourceContext": "/document/reviews_text/pages/*",
                            "inputs": [
                                { "name": "Sentiment", "source": "/document/reviews_text/pages/*/sentiment"},
                                { "name": "LanguageCode", "source": "/document/language"},
                                { "name": "Keyphrases", "source": "/document/reviews_text/pages/*/keyphrases"},
                                { "name": "TranslatedText", "source": "/document/reviews_text/pages/*/translated_text"},
                                { "name": "Page", "source": "/document/reviews_text/pages/*" }
                            ]
                        },
                        { 
                            "tableName": "hotelReviews6InlineProjectionKeyPhrases", "generatedKeyName": "kpidv2", "sourceContext": "/document/reviews_text/pages/*/keyphrases/*",
                            "inputs": [
                                { "name": "Keyphrases", "source": "/document/reviews_text/pages/*/keyphrases/*" }
                            ]
                        }
                    ],
                    "objects": []
                }
            ]
        }
    }

Punti principali:

La competenza Shaper è importante per la definizione dell'archivio conoscenze. Specifica la modalità di flusso dei dati nelle tabelle dell'archivio conoscenze. Gli input sono le parti del documento arricchito da archiviare. L'output è un consolidamento dei nodi in una singola struttura.
Le proiezioni specificano tabelle, oggetti e BLOB dell'archivio conoscenze. Ogni elemento di proiezione specifica la colonna o il "name" campo da creare in Archiviazione di Azure. "source" Specifica quale parte dell'output del shaper viene assegnata a tale campo o colonna.

Creare un indicizzatore

Creare l'indicizzatore crea ed esegue l'indicizzatore. L'esecuzione dell'indicizzatore inizia crepando i documenti, estraendo testo e immagini e inizializzando il set di competenze. L'indicizzatore controlla gli altri oggetti creati: l'origine dati, l'indice e il set di competenze.

Incollare l'esempio seguente per creare l'indicizzatore.

### Create indexer
POST {{baseUrl}}/indexers?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "name": "hotel-reviews-kstore-idxr",
        "dataSourceName": "hotel-reviews-kstore-ds",
        "skillsetName": "hotel-reviews-kstore-ss",
        "targetIndexName": "hotel-reviews-kstore-idx",
        "parameters": {
            "configuration": {
                "dataToExtract": "contentAndMetadata",
                "parsingMode": "delimitedText",
                "firstLineContainsHeaders": true,
                "delimitedTextDelimiter": ","
    }
},
"fieldMappings": [
    {
        "sourceFieldName": "AzureSearch_DocumentKey",
        "targetFieldName": "AzureSearch_DocumentKey",
        "mappingFunction": { "name": "base64Encode" }
    }
],
"outputFieldMappings": [
    { "sourceFieldName": "/document/reviews_text/pages/*/Keyphrases/*", "targetFieldName": "Keyphrases" },
    { "sourceFieldName": "/document/Language", "targetFieldName": "Language" },
    { "sourceFieldName": "/document/reviews_text/pages/*/Sentiment", "targetFieldName": "Sentiment" }
    ]
}

Selezionare Invia richiesta per creare ed eseguire l'indicizzatore. Il completamento di questo passaggio richiede alcuni minuti.

Punti principali:

L'oggetto parameters/configuration controlla il modo in cui l'indicizzatore inserisce i dati. In questo caso, i dati di input si trovano in un singolo file CSV con una riga di intestazione e valori delimitati da virgole.
I mapping dei campi creano "AzureSearch_DocumentKey" è un identificatore univoco per ogni documento generato dall'indicizzatore BLOB (in base al percorso di archiviazione dei metadati).
I mapping dei campi di output specificano il mapping dei campi arricchiti ai campi in un indice di ricerca. I mapping dei campi di output non vengono usati negli archivi conoscenze (gli archivi conoscenze usano forme e proiezioni per esprimere le strutture dei dati fisici).

Verificare lo stato

Dopo l'invio di ogni richiesta, il servizio di ricerca deve rispondere con un messaggio di esito positivo 201.

### Get Indexer Status (wait several minutes for the indexer to complete)
GET {{baseUrl}}/indexers/hotel-reviews-kstore-idxr/status?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

Dopo alcuni minuti, è possibile eseguire una query sull'indice per esaminare il contenuto. Anche se non si usa l'indice, questo passaggio è un modo pratico per verificare che il set di competenze produsse l'output previsto.

### Query the index (indexer status must be "success" before querying the index)
POST {{baseUrl}}/indexes/hotel-reviews-kstore-idxr/docs/search?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}
  
  {
    "search": "*",
    "select": "reviews_title, reviews_username, language, translated_text, sentiment",
    "count": true
  }

Controllare le tabelle in portale di Azure

Nella portale di Azure passare all'account Archiviazione di Azure e usare Archiviazione Browser per visualizzare le nuove tabelle. Verranno visualizzate sei tabelle, una per ogni proiezione definita nel set di competenze.

Ogni tabella viene generata con gli ID necessari per il collegamento incrociato delle tabelle nelle query. Quando si apre una tabella, scorrere oltre questi campi per visualizzare i campi di contenuto aggiunti dalla pipeline.

Screenshot of the knowledge store tables in Storage Browser

In questa procedura dettagliata l'archivio conoscenze è costituito da varie tabelle che illustrano diversi modi di modellare e strutturare una tabella. Le tabelle da 1 a tre usano l'output di una competenza Shaper per determinare le colonne e le righe. Le tabelle da quattro a sei vengono create da istruzioni di shaping inline, incorporate all'interno della proiezione stessa. È possibile usare entrambi gli approcci per ottenere lo stesso risultato.

Tabella	Descrizione
`hotelReviews1Document`	Contiene campi portati avanti dal file CSV, ad esempio reviews_date e reviews_text.
`hotelReviews2Pages`	Contiene campi arricchiti creati dal set di competenze, ad esempio il punteggio del sentiment e il testo tradotto.
`hotelReviews3KeyPhrases`	Contiene un lungo elenco di frasi chiave.
`hotelReviews4InlineProjectionDocument`	In alternativa alla prima tabella, utilizzando la forma inline anziché la competenza Shaper per modellare i dati per la proiezione.
`hotelReviews5InlineProjectionPages`	Alternativa alla seconda tabella, utilizzando la forma inline.
`hotelreviews6InlineProjectionKeyPhrases`	Alternativa alla terza tabella, utilizzando la forma inline.

Eseguire la pulizia

Quando si lavora nella propria sottoscrizione, al termine di un progetto è buona norma determinare se le risorse create sono ancora 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

Dopo aver arricchito i dati usando i servizi di intelligenza artificiale di Azure e proiettato i risultati in un archivio conoscenze, è possibile usare Archiviazione Explorer o altre app per esplorare il set di dati arricchito.

Introduzione a Storage Explorer