Esercitazione: Eseguire il debug di un set di competenze usando le sessioni di debug

Un set di competenze coordina le azioni delle competenze che analizzano, trasformano o creano contenuto ricercabile. Spesso, l'output di una competenza diventa l'input di un altro. Quando gli input dipendono da output, gli errori nelle definizioni del set di competenze e nelle associazioni di campi possono comportare operazioni e dati mancanti.

Le sessioni di debug sono uno strumento portale di Azure che fornisce una visualizzazione olistica di un set di competenze. Usando questo strumento, è possibile eseguire il drill-down in passaggi specifici per vedere facilmente dove potrebbe cadere un'azione.

In questo articolo usare le sessioni di debug per trovare e correggere gli input e gli output mancanti. L'esercitazione è all-inclusive. Fornisce dati di esempio, un file REST che crea oggetti e istruzioni per il debug dei problemi nel set di competenze.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

Prerequisiti

• Azure AI Search. Creare un servizio o trovarne uno esistente nella sottoscrizione corrente. È possibile usare un servizio gratuito per questa esercitazione.

• Archiviazione di Azure account con Archiviazione BLOB, usata per ospitare dati di esempio e per rendere persistenti i dati memorizzati nella cache creati durante una sessione di debug.

• Visual Studio Code con un client REST.

• PDF di esempio (studi clinici).

• File debug-sessions.rest di esempio usato per creare la pipeline di arricchimento.

Nota

Questa esercitazione usa anche i servizi di intelligenza artificiale di Azure per il rilevamento della lingua, il riconoscimento delle entità e l'estrazione di frasi chiave. Poiché il carico di lavoro è così piccolo, i servizi di intelligenza artificiale di Azure vengono toccati dietro le quinte per l'elaborazione gratuita per un massimo di 20 transazioni. Ciò significa che è possibile completare questo esercizio senza dover creare una risorsa dei servizi di intelligenza artificiale di Azure fatturabile.

Configurare i dati di esempio

Questa sezione crea il set di dati di esempio in Archiviazione BLOB di Azure in modo che l'indicizzatore e il set di competenze abbiano contenuto da usare.

1. Scaricare i dati di esempio (clinical-trials-pdf-19), costituiti da 19 file.

2. Creare un account di archiviazione di Azure o trovare un account esistente.

   • Scegliere la stessa area di Ricerca di intelligenza artificiale di Azure per evitare addebiti per la larghezza di banda.

   • Scegliere il tipo di account Archiviazione V2 (utilizzo generico V2).

3. Passare alle pagine dei servizi di Archiviazione di Azure nel portale e creare un contenitore BLOB. È consigliabile specificare il livello di accesso "privato". Assegnare al contenitore il nome clinicaltrialdataset.

4. Nel contenitore selezionare Carica per caricare i file di esempio scaricati e decompressi nel primo passaggio.

5. Nel portale copiare il stringa di connessione per Archiviazione di Azure. È possibile ottenere il stringa di connessione da Impostazioni> Chiavi di accesso nel portale.

Copiare una chiave e un URL

Le chiamate REST richiedono l'endpoint del servizio di ricerca e una chiave API per ogni richiesta. È possibile ottenere questi valori dalla 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 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 l'origine dati, il set di competenze, l'indice e l'indicizzatore

In questa sezione creare un flusso di lavoro "buggy" che è possibile correggere in questa esercitazione.

1. Avviare Visual Studio Code e aprire il debug-sessions.rest file.

2. Specificare le variabili seguenti: URL del servizio di ricerca, chiave API amministratore dei servizi di ricerca, stringa di connessione di archiviazione e nome del contenitore BLOB che archivia i PDF.

3. Inviare ogni richiesta a sua volta. Il completamento della creazione dell'indicizzatore richiede alcuni minuti.

4. Chiudere il file .

Controllare i risultati nel portale

Il codice di esempio crea intenzionalmente un indice buggy come conseguenza di problemi che si sono verificati durante l'esecuzione del set di competenze. Il problema è che l'indice non contiene dati.

1. Nella pagina Panoramica del servizio di ricerca portale di Azure selezionare la scheda Indici.

2. Selezionare studi clinici.

3. Immettere questa stringa di query JSON nella visualizzazione JSON di Esplora ricerche. Restituisce campi per documenti specifici (identificati dal campo univoco metadata_storage_path ).

   "select": "metadata_storage_path, organizations, locations",
   "count"=true`
   

4. Esegui la query. Verranno visualizzati valori vuoti per organizations e locations.

   Questi campi dovrebbero essere stati popolati tramite la competenza Riconoscimento entità del set di competenze, usata per rilevare organizzazioni e posizioni ovunque all'interno del contenuto del BLOB. Nell'esercizio successivo si eseguirà il debug del set di competenze per determinare l'errore.

Un altro modo per analizzare gli errori e gli avvisi consiste nel portale di Azure.

1. Aprire la scheda Indicizzatori e selezionare clinical-trials-idxr.

   Si noti che, mentre il processo dell'indicizzatore è riuscito complessivamente, sono stati visualizzati avvisi.

2. Selezionare Operazione riuscita per visualizzare gli avvisi (se si sono verificati errori per lo più, il collegamento di dettaglio sarà Non riuscito). Verrà visualizzato un lungo elenco di tutti gli avvisi generati dall'indicizzatore.

   

Avviare la sessione di debug

1. Nel riquadro di spostamento sinistro del servizio di ricerca, in Gestione ricerca selezionare Sessioni di debug.

2. Selezionare + Aggiungi sessione di debug.

3. Assegnare un nome alla sessione.

4. Connettere la sessione al proprio account di archiviazione. Creare un contenitore denominato "sessioni di debug". È possibile usare ripetutamente questo contenitore per archiviare tutti i dati della sessione di debug.

5. Se è stata configurata una connessione attendibile tra la ricerca e l'archiviazione, selezionare l'identità gestita dall'utente o l'identità di sistema per la connessione. In caso contrario, usare il valore predefinito (Nessuno).

6. Nel modello indicizzatore specificare il nome dell'indicizzatore. L'indicizzatore contiene riferimenti all'origine dati, al set di competenze e all'indice.

7. Per il documento di debug accettare l'impostazione predefinita, che corrisponde al primo documento della raccolta. Una sessione di debug funziona solo con un singolo documento. È possibile scegliere il documento di cui eseguire il debug o usare solo il primo documento.

8. Selezionare Salva per salvare la sessione. Il salvataggio della sessione avvia la pipeline di arricchimento come definito dal set di competenze per il documento selezionato.

   

9. Al termine dell'inizializzazione della sessione di debug, per impostazione predefinita la sessione viene visualizzata nella scheda Arricchimenti tramite intelligenza artificiale, evidenziando Skill Graph. Skill Graph fornisce una gerarchia visiva del set di competenze e il relativo ordine di esecuzione in sequenza e in parallelo.

   

Trovare problemi con il set di competenze

Tutti i problemi segnalati dall'indicizzatore sono disponibili nella scheda Errori/Avvisi adiacenti.

Si noti che la scheda Errori/Avvisi fornirà un elenco molto più piccolo di quello visualizzato in precedenza perché questo elenco descrive in dettaglio solo gli errori per un singolo documento. Analogamente all'elenco visualizzato dall'indicizzatore, è possibile selezionare un messaggio di avviso e visualizzare i dettagli di questo avviso.

Selezionare Errori/Avvisi per esaminare le notifiche. Dovrebbero essere visualizzati quattro elementi:

• "Impossibile eseguire la competenza perché uno o più input di competenza non sono validi. L'input della competenza richiesto non è presente. Nome: 'text', Origine: '/document/content'."

• "Impossibile eseguire il mapping del campo di output 'locations' all'indice di ricerca. Controllare la proprietà 'outputFieldMappings' dell'indicizzatore. Valore mancante '/document/merged_content/locations'."

• "Impossibile eseguire il mapping del campo di output 'organizations' all'indice di ricerca. Controllare la proprietà 'outputFieldMappings' dell'indicizzatore. Valore mancante '/document/merged_content/organizations'."

• "La competenza è stata eseguita ma potrebbe avere risultati imprevisti perché uno o più input di competenza non sono validi. Manca l'input della competenza facoltativo. Name: 'languageCode', Source: '/document/languageCode'. Problemi di analisi del linguaggio delle espressioni: valore mancante '/document/languageCode'."

Molte competenze hanno un parametro "languageCode". Esaminando l'operazione, è possibile notare che questo input del codice della lingua non è presente in EntityRecognitionSkill.#1, che è la stessa competenza riconoscimento entità che presenta problemi con l'output "locations" e "organizations".

Poiché tutte e quattro le notifiche riguardano questa competenza, il passaggio successivo consiste nel eseguire il debug di questa competenza. Se possibile, iniziare risolvendo i problemi di input prima di passare ai problemi di output.

Correzione dei valori di input delle competenze mancanti

Nella scheda Errori/Avvisi sono presenti due input mancanti per un'operazione con EntityRecognitionSkill.#1etichetta . Il dettaglio del primo errore spiega che manca un input obbligatorio per 'text'. Il secondo indica un problema con un valore di input "/document/languageCode".

1. In Ai Enrichments>Skill Graph selezionare la competenza con etichetta #1 per visualizzarne i dettagli nel riquadro destro.

2. Selezionare la scheda Esecuzioni e individuare l'input per "text".

3. Selezionare il <simbolo /> per aprire l'analizzatore di espressioni. Il risultato visualizzato per questo input non sembra un input di testo, Sembra una serie di nuovi caratteri \n \n\n\n\n di riga anziché testo. La mancanza di testo indica che non è possibile identificare alcuna entità, pertanto questo documento non soddisfa i prerequisiti della competenza oppure è necessario usare un altro input.

   

4. Passare al riquadro sinistro su Struttura dati arricchita e scorrere verso il basso l'elenco dei nodi di arricchimento per questo documento. Si noti che \n \n\n\n\n per "content" non è presente alcuna origine di origine, ma un altro valore per "merged_content" ha output OCR. Sebbene non vi sia alcuna indicazione, il contenuto di questo PDF sembra essere un file JPEG, come evidenziato dal testo estratto ed elaborato in "merged_content".

   

5. Nel riquadro destro selezionare Esecuzioni per la competenza #1 e aprire l'analizzatore< di espressioni/>per l'input "text".

6. Modificare l'espressione da /document/content a /document/merged_contente quindi selezionare Valuta. Si noti che il contenuto è ora un blocco di testo e quindi utilizzabile per il riconoscimento delle entità.

   

7. Passare all'editor JSON della competenza.

8. Alla riga 16, in "input", passare /document/content a /document/merged_content.

    {
      "name": "text",
      "source": "/document/merged_content"
    },
   

9. Selezionare Salva nel riquadro Dettagli competenza.

   

10. Selezionare Esegui nel menu della finestra della sessione. Verrà avviata un'altra esecuzione del set di competenze usando il documento.

11. Al termine dell'esecuzione della sessione di debug, controllare la scheda Errori/Avvisi e indicare che l'errore per l'input di testo non è più disponibile, ma gli altri avvisi rimangono. Il passaggio successivo consiste nell'affrontare l'avviso relativo a "languageCode".

    

12. Selezionare la scheda Esecuzioni e individuare l'input per "languageCode".

13. Selezionare il <simbolo /> per aprire l'analizzatore di espressioni. Si noti che la proprietà "languageCode" non è un input valido.

    

Esistono due modi per cercare questo errore. Il primo consiste nell'esaminare la provenienza dell'input: quale competenza nella gerarchia dovrebbe produrre questo risultato? La scheda Esecuzioni nel riquadro dei dettagli della competenza dovrebbe visualizzare l'origine dell'input. Se non è presente alcuna origine, indica un errore di mapping dei campi.

1. Nella scheda Esecuzioni controllare input e trovare "languageCode". Non esiste alcuna origine per questo input elencato.

2. Impostare il riquadro sinistro su Struttura dei dati arricchita. Scorrere verso il basso l'elenco dei nodi di arricchimento per questo documento. Si noti che non esiste un nodo "languageCode", ma ne esiste uno per "language". Quindi, c'è un errore di digitazione nelle impostazioni della competenza.

   

3. Sempre nella struttura dei dati arricchita aprire l'analizzatore <di espressioni/>per il nodo "language" e copiare l'espressione /document/language.

4. Nel riquadro destro selezionare Skill Impostazioni per la competenza #1 e aprire l'analizzatore< di espressioni/>per l'input "languageCode".

5. Incollare il nuovo valore nella /document/language casella Espressione e selezionare Valuta. Dovrebbe essere visualizzato l'input corretto "en".

6. Seleziona Salva.

7. Selezionare Esegui.

Al termine dell'esecuzione della sessione di debug, controllare la scheda Errori/Avvisi e verrà visualizzato che tutti gli avvisi di input non sono più presenti. Ora rimangono solo i due avvisi relativi ai campi di output per le organizzazioni e le posizioni.

Correggere i valori di output della competenza mancanti

I messaggi dicono di controllare la proprietà 'outputFieldMappings' dell'indicizzatore, quindi consente di iniziare da lì.

1. Passare a Skill Graph (Grafico competenze) e selezionare Output Field Mappings (Mapping campi di output). I mapping sono effettivamente corretti, ma in genere si controlla la definizione dell'indice per assicurarsi che i campi esistano per "locations" e "organizations".

   

2. Se non si verificano problemi con l'indice, il passaggio successivo consiste nel controllare gli output delle competenze. Come in precedenza, selezionare la struttura dei dati arricchita e scorrere i nodi per trovare "locations" e "organizations". Si noti che l'elemento padre è "content" anziché "merged_content". Il contesto non è corretto.

   

3. Tornare a Skill Graph e selezionare la competenza di riconoscimento delle entità.

4. In Skill Settings (Impostazioni competenza) individuare "context".

   

5. Fare doppio clic sull'impostazione relativa a "context" e modificarla in "/document/merged_content".

6. Seleziona Salva.

7. Selezionare Esegui.

Tutti gli errori sono stati risolti.

Eseguire il commit delle modifiche apportate al set di competenze

Quando è stata avviata la sessione di debug, il servizio di ricerca ha creato una copia del set di competenze. Questa operazione è stata eseguita per proteggere il set di competenze originale nel servizio di ricerca. Dopo aver completato il debug del set di competenze, è possibile eseguire il commit delle correzioni (sovrascrivere il set di competenze originale).

In alternativa, se non si è pronti a eseguire il commit delle modifiche, è possibile salvare la sessione di debug e riaprirla in un secondo momento.

1. Selezionare Commit changes (Esegui commit modifiche) nel menu principale Sessioni di debug.

2. Selezionare OK per confermare che si vuole aggiornare il set di competenze.

3. Chiudere Sessione di debug e aprire Indicizzatori dal riquadro di spostamento a sinistra.

4. Selezionare "clinical-trials-idxr".

5. Selezionare Reimposta.

6. Selezionare Esegui.

7. Selezionare Aggiorna per visualizzare lo stato dei comandi di reimpostazione ed esecuzione.

Al termine dell'esecuzione dell'indicizzatore, dovrebbe essere presente un segno di spunta verde e la parola Operazione riuscita accanto al timestamp per l'esecuzione più recente nella scheda Cronologia esecuzioni. Per assicurarsi che le modifiche siano state applicate:

1. Nel riquadro di spostamento sinistro aprire Indici.

2. Selezionare l'indice "clinical-trials" e nella scheda Esplora ricerche immettere questa stringa di query: $select=metadata_storage_path, organizations, locations&$count=true per restituire campi per documenti specifici (identificati dal campo univoco metadata_storage_path ).

3. Seleziona Cerca.

I risultati dovrebbero indicare che le organizzazioni e le posizioni sono ora popolate con i valori previsti.

Pulire le risorse

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.

Il servizio gratuito è limitato a tre indici, indicizzatori e origini dati. Per non superare il limite, è possibile eliminare i singoli elementi nel portale.

Passaggi successivi

Questa esercitazione ha toccato vari aspetti della definizione e dell'elaborazione del set di competenze. Per altre informazioni sui concetti e sui flussi di lavoro, vedere gli articoli seguenti:

• Come eseguire il mapping dei campi di output del set di competenze ai campi in un indice di ricerca

• Set di competenze in Ricerca di intelligenza artificiale di Azure

• Come configurare la memorizzazione nella cache per l'arricchimento incrementale