Creare un archivio conoscenze con REST

  • Articolo

In Azure AI Search, un archivio conoscenze è un repository di contenuti generati dall'intelligenza artificiale usati per scenari non di ricerca. Si crea l'archivio conoscenze usando un indicizzatore e un set di competenze e si specifica Archiviazione di Azure per archiviare l'output. Dopo aver popolato l'archivio conoscenze, usare strumenti come Storage 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 in hotel in un archivio conoscenze. L'archivio conoscenze contiene contenuti testuali originali estratti dall'origine, oltre a contenuti generati dall'intelligenza artificiale che includono un punteggio del sentiment, l'estrazione di frasi chiave, il rilevamento lingua e la traduzione del testo 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 in Archiviazione tabelle di Azure.

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 nel portale di Azure.

Prerequisiti

Il set di competenze in questo esempio usa i Servizi di Azure AI per gli arricchimenti. Poiché il carico di lavoro è molto ridotto, Servizi di Azure AI lavora dietro le quinte per offrire 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 una stringa di connessione

  1. Download HotelReviews_Free.csv. Questo file CSV contiene 19 commenti dei clienti relativi a un singolo hotel, creati nel sito Kaggle.com.

  2. Nel portale di Azure trovare l'account di archiviazione e usare Browser archiviazione per creare un contenitore BLOB denominato hotel-reviews.

  3. Selezionare Carica nella parte superiore della pagina per caricare il file HotelReviews-Free.csv scaricato dal passaggio precedente.

    Screenshot del browser di archiviazione con il file caricato e il riquadro di spostamento sinistro

  4. A sinistra, selezionare Chiavi di accesso, selezionare Mostra chiavi, quindi copiare la stringa di connessione per key1 o key2. Una stringa di connessione con accesso completo ha il formato seguente:

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

Nota

Vedere Connettersi usando un'identità gestita se non si vogliono fornire dati sensibili nella 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 dal portale di Azure.

  1. 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.

  2. 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.

    Screenshot delle chiavi URL e API nel portale di Azure.

La presenza di una chiave API valida stabilisce una relazione di trust, a livello di singole richieste, 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.

  1. Aprire un nuovo file di testo in Visual Studio Code.

  2. Impostare le variabili sull'endpoint di ricerca e sulla chiave API ottenuta 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)

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

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

    ### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-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 }
        ]
    }

  5. Selezionare Invia richiesta. È necessario avere una risposta HTTP/1.1 201 Created 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 Azure AI Search.

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

    ### Create a data source
POST {{baseUrl}}/datasources?api-version=2024-07-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
    }

  2. 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.

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

    ### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2024-07-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 l'oggetto "name" della colonna o del campo da creare in Archiviazione di Azure. L'oggetto "source" specifica quale parte dell'output dello Shaper viene assegnata a tale campo o colonna.

Creare un indicizzatore

Creare l'indicizzatore crea ed esegue l'indicizzatore. L'esecuzione dell'indicizzatore inizia con il cracking dei 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.

  1. Incollare l'esempio seguente per creare l'indicizzatore.

    ### Create indexer
POST {{baseUrl}}/indexers?api-version=2024-07-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" }
    ]
}

  2. Selezionare Invia richiesta per creare ed eseguire l'indicizzatore. Il completamento del 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 separati 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=2024-07-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 abbia prodotto 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=2024-07-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 nel portale di Azure

Nel portale di Azure passare all'account di archiviazione di Azure e usare il browser di archiviazione 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 delle tabelle dell'archivio conoscenze nel browser archiviazione

In questa procedura dettagliata l'archivio conoscenze è costituito da varie tabelle che illustrano diversi modi di modellare e strutturare una tabella. Le tabelle da uno 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 lo shaping inline anziché la competenza Shaper per modellare i dati per la proiezione.
hotelReviews5InlineProjectionPages Alternativa alla seconda tabella, utilizzando lo shaping inline.
hotelreviews6InlineProjectionKeyPhrases Alternativa alla terza tabella, utilizzando lo shaping 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 con i Servizi di Azure AI e aver proiettato i risultati in un archivio conoscenze, è possibile usare Storage Explorer o altre app per esplorare il set di dati arricchito.

Introduzione a Storage Explorer