Eseguire il debug di un set di competenze di Ricerca intelligenza artificiale di Azure in portale di Azure

Articolo
01/12/2024

Avviare una sessione di debug basata sul portale per identificare e risolvere gli errori, convalidare le modifiche ed eseguire il push delle modifiche in un set di competenze pubblicato nel servizio di ricerca di intelligenza artificiale di Azure.

Una sessione di debug è un indicizzatore memorizzato nella cache e l'esecuzione del set di competenze, con ambito in un singolo documento, che è possibile usare per modificare e testare le modifiche in modo interattivo. Al termine del debug, è possibile salvare le modifiche apportate al set di competenze.

Per informazioni sul funzionamento di una sessione di debug, vedere Eseguire il debug di sessioni in Ricerca di intelligenza artificiale di Azure. Per praticare un flusso di lavoro di debug con un documento di esempio, vedere Esercitazione: Sessioni di debug.

Prerequisiti

Una pipeline di arricchimento esistente, tra cui un'origine dati, un set di competenze, un indicizzatore e un indice.
Assegnazione di ruolo Collaboratore nel servizio di ricerca.
Un account Archiviazione di Azure utilizzato per salvare lo stato della sessione.
Assegnazione di ruolo Collaboratore dati BLOB Archiviazione in Archiviazione di Azure se si usa un'identità gestita dal sistema. In caso contrario, pianificare l'uso di un stringa di connessione di accesso completo per la connessione di sessione di debug a Archiviazione di Azure.
Se l'account Archiviazione di Azure si trova dietro un firewall, configurarlo per consentire l'accesso al servizio di ricerca.

Limiti

Le sessioni di debug funzionano con tutte le origini dati dell'indicizzatore disponibili a livello generale e la maggior parte delle origini dati di anteprima. L'elenco seguente annota le eccezioni:

Azure Cosmos DB per MongoDB non è attualmente supportato.
Per Azure Cosmos DB per NoSQL, se una riga non riesce durante l'indice e non sono presenti metadati corrispondenti, la sessione di debug potrebbe non selezionare la riga corretta.
Per l'API SQL di Azure Cosmos DB, se una raccolta partizionata in precedenza non è stata partizionata, la sessione di debug non troverà il documento.
Per le competenze personalizzate, un'identità gestita assegnata dall'utente non è supportata per una connessione di sessione di debug a Archiviazione di Azure. Come indicato nei prerequisiti, è possibile usare un'identità gestita del sistema o specificare un stringa di connessione di accesso completo che include una chiave. Per altre informazioni, vedere Connessione un servizio di ricerca ad altre risorse di Azure usando un'identità gestita.

Il portale non supporta la crittografia della chiave gestita dal cliente( CMK), il che significa che le esperienze del portale come le sessioni di debug non possono avere stringa di connessione crittografate tramite chiave gestita dal cliente o altri metadati crittografati. Se il servizio di ricerca è configurato per l'imposizione della chiave gestita dal cliente, le sessioni di debug non funzioneranno.

Creare una sessione di debug

Accedere al portale di Azure e trovare il servizio di ricerca.
Nella pagina di spostamento a sinistra selezionare Sessioni di debug.
Nella barra delle azioni in alto selezionare Aggiungi sessione di debug.
In Nome della sessione di debug specificare un nome che consenta di ricordare il set di competenze, l'indicizzatore e l'origine dati interessati dalla sessione di debug.
Nella Stringa di connessione di archiviazione trovare un account di archiviazione per utilizzo generico per la memorizzazione nella cache della sessione di debug. Verrà richiesto di selezionare e, facoltativamente, creare un contenitore BLOB in Blob Archiviazione o Azure Data Lake Archiviazione Gen2. È possibile riutilizzare lo stesso contenitore per tutte le sessioni di debug successive create. Un nome di contenitore utile potrebbe essere "cognitive-search-debug-sessions".
In Autenticazione identità gestita scegliere Nessuno se la connessione a Archiviazione di Azure non usa un'identità gestita. In caso contrario, scegliere l'identità gestita a cui sono state concesse Archiviazione autorizzazioni Collaboratore dati BLOB.
Nel modello Indicizzatore selezionare l'indicizzatore su cui si basa il set di competenze di cui si vuole eseguire il debug. Le copie dell'indicizzatore e del set di competenze vengono usate per inizializzare la sessione.
In Documento di cui eseguire il debug scegliere il primo documento nell'indice o selezionare un documento specifico. Se si seleziona un documento specifico, a seconda dell'origine dati, viene richiesto un URI o un ID riga.

Se il documento specifico è un BLOB, specificare l'URI del BLOB. È possibile trovare l'URI nella pagina delle proprietà del BLOB nel portale.
Facoltativamente, nelle impostazioni dell'indicizzatore specificare le impostazioni di esecuzione dell'indicizzatore usate per creare la sessione. Le impostazioni devono simulare le impostazioni usate dall'indicizzatore effettivo. Le opzioni dell'indicizzatore specificate in una sessione di debug non hanno alcun effetto sull'indicizzatore stesso.
La configurazione dovrebbe essere simile a questa schermata. Selezionare Salva sessione per iniziare.

La sessione di debug inizia eseguendo l'indicizzatore e il set di competenze nel documento selezionato. Il contenuto e i metadati del documento creati saranno visibili e disponibili nella sessione.

È possibile annullare una sessione di debug durante l'esecuzione usando il pulsante Annulla . Se si preme il pulsante Annulla , sarà possibile analizzare i risultati parziali.

È previsto che l'esecuzione di una sessione di debug sia più lunga rispetto all'indicizzatore perché passa attraverso un'elaborazione aggiuntiva.

Iniziare con errori e avvisi

La cronologia di esecuzione dell'indicizzatore nel portale fornisce l'elenco completo di errori e avvisi per tutti i documenti. In una sessione di debug, gli errori e gli avvisi saranno limitati a un documento. Si userà questo elenco, si apportano le modifiche e quindi si tornerà all'elenco per verificare se i problemi vengono risolti.

Per visualizzare i messaggi, selezionare una competenza in Ai Enrichment > Skill Graph e quindi selezionare Errori/Avvisi nel riquadro dei dettagli.

Come procedura consigliata, risolvere i problemi relativi agli input prima di passare agli output.

Per dimostrare se una modifica risolve un errore, seguire questa procedura:

Selezionare Salva nel riquadro dei dettagli della competenza per mantenere le modifiche.
Selezionare Esegui nella finestra della sessione per richiamare l'esecuzione del set di competenze usando la definizione modificata.
Tornare a Errori/Avvisi per verificare se il conteggio è ridotto. L'elenco non verrà aggiornato finché non si apre la scheda.

Visualizzare il contenuto dei nodi di arricchimento

Le pipeline di arricchimento tramite intelligenza artificiale estraggono o deducono informazioni e struttura dai documenti di origine, creando un documento arricchito nel processo. Un documento arricchito viene creato per primo durante il cracking del documento e popolato con un nodo radice (/document), più nodi per qualsiasi contenuto sollevato direttamente dall'origine dati, ad esempio metadati e chiave del documento. Altri nodi vengono creati dalle competenze durante l'esecuzione delle competenze, in cui ogni output della competenza aggiunge un nuovo nodo all'albero di arricchimento.

I documenti arricchiti sono interni, ma una sessione di debug consente di accedere al contenuto prodotto durante l'esecuzione delle competenze. Per visualizzare il contenuto o l'output di ogni competenza, seguire questa procedura:

Iniziare con le visualizzazioni predefinite: Il grafico delle competenze di arricchimento > tramite intelligenza artificiale, con il tipo di grafo impostato su Dependency Graph.
Selezionare una competenza.
Nel riquadro dei dettagli a destra selezionare Esecuzioni, selezionare un OUTPUT e quindi aprire l'analizzatore di espressioni (</>) per visualizzare l'espressione e il relativo risultato.
In alternativa, aprire l'arricchimento tramite intelligenza > artificiale Enriched Data Structure per scorrere verso il basso l'elenco dei nodi. L'elenco include nodi potenziali e effettivi, con una colonna per l'output e un'altra colonna che indica l'oggetto upstream usato per produrre l'output.

Modificare le definizioni delle competenze

Se i mapping dei campi sono corretti, controllare le singole competenze per la configurazione e il contenuto. Se una competenza non riesce a produrre output, potrebbe non essere presente una proprietà o un parametro, che può essere determinato tramite messaggi di errore e convalida.

Altri problemi, ad esempio un contesto o un'espressione di input non validi, possono essere più difficili da risolvere perché l'errore indica cosa è sbagliato, ma non come risolverlo. Per informazioni sul contesto e sulla sintassi di input, vedere Arricchimenti di riferimento in un set di competenze di Ricerca di intelligenza artificiale di Azure. Per informazioni sui singoli messaggi, vedere Risoluzione degli errori e degli avvisi comuni dell'indicizzatore.

I passaggi seguenti illustrano come ottenere informazioni su una competenza.

In Skill Graph per l'arricchimento > tramite intelligenza artificiale selezionare una competenza. Il riquadro Dettagli competenza si apre a destra.
Modificare una definizione di competenza usando uno dei due approcci seguenti:
- Competenza Impostazioni se si preferisce un editor visivo
- Editor JSON competenza per modificare direttamente il documento JSON
Controllare la sintassi del percorso per fare riferimento ai nodi in un albero di arricchimento. Di seguito sono riportati alcuni dei percorsi di input più comuni:
- /document/content per blocchi di testo. Questo nodo viene popolato dalla proprietà del contenuto del BLOB.
- /document/merged_content per blocchi di testo nei set di competenze che includono la competenza Unione testo.
- /document/normalized_images/* per il testo riconosciuto o dedotto dalle immagini.

Controllare i mapping dei campi

Se le competenze producono output ma l'indice di ricerca è vuoto, controllare i mapping dei campi. I mapping dei campi specificano il modo in cui il contenuto viene spostato dalla pipeline e in un indice di ricerca.

Iniziare con le visualizzazioni predefinite: Il grafico delle competenze di arricchimento > tramite intelligenza artificiale, con il tipo di grafo impostato su Dependency Graph.
Selezionare Mapping campi nella parte superiore. È necessario trovare almeno la chiave del documento che identifica e associa in modo univoco ogni documento di ricerca nell'indice di ricerca al documento di origine nell'origine dati.

Se si importa contenuto non elaborato direttamente dall'origine dati, ignorando l'arricchimento, è necessario trovare tali campi in Mapping campi.
Selezionare Mapping dei campi di output nella parte inferiore del grafico. Qui sono disponibili mapping dagli output delle competenze ai campi di destinazione nell'indice di ricerca. A meno che non sia stata usata la procedura guidata Importa dati, i mapping dei campi di output vengono definiti manualmente e potrebbero essere incompleti o non digitati correttamente.

Verificare che i campi in Mapping campi di output siano presenti nell'indice di ricerca come specificato, verificando la sintassi del percorso del nodo di ortografia e arricchimento.

Eseguire il debug di una competenza personalizzata in locale

Le competenze personalizzate possono risultare più complesse per il debug perché il codice viene eseguito esternamente, quindi non è possibile usare la sessione di debug per eseguirne il debug. Questa sezione descrive come eseguire il debug locale della competenza dell'API Web personalizzata, eseguire il debug di sessione, Visual Studio Code e ngrok o Tunnelmole. Questa tecnica funziona con competenze personalizzate eseguite in Funzioni di Azure o in qualsiasi altro framework Web eseguito in locale, ad esempio FastAPI.

Ottenere un URL pubblico

Uso di Tunnelmole

Tunnelmole è uno strumento di tunneling open source che può creare un URL pubblico che inoltra le richieste al computer locale tramite un tunnel.

Installare Tunnelmole:
- Npm: npm install -g tunnelmole
- Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
- Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
- Windows: eseguire l'installazione con npm. In alternativa, se NodeJS non è installato, scaricare il file di .exe precompilato per Windows e inserirlo in un punto qualsiasi del percorso.
Eseguire questo comando per creare un nuovo tunnel:
```
tmole 7071
```
Verrà visualizzata una risposta simile alla seguente:
```
http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
```
Nell'esempio precedente, https://m5hdpb-ip-49-183-170-144.tunnelmole.net inoltra alla porta 7071 nel computer locale, ovvero la porta predefinita in cui vengono esposte le funzioni di Azure.

Uso di ngrok

ngrok è un'applicazione multipiattaforma e di origine chiusa diffusa che può creare un URL di tunneling o inoltro, in modo che le richieste Internet raggiungano il computer locale. Usare ngrok per inoltrare le richieste da una pipeline di arricchimento nel servizio di ricerca al computer per consentire il debug locale.

Installare ngrok.
Aprire un terminale e passare alla cartella con l'eseguibile ngrok.
Eseguire ngrok con il comando seguente per creare un nuovo tunnel:
```
ngrok http 7071 
```
Nota

Per impostazione predefinita, le funzioni di Azure vengono esposte nella versione 7071. Altri strumenti e configurazioni potrebbero richiedere la specifica di una porta diversa.
All'avvio di ngrok copiare e salvare l'URL di inoltro pubblico per il passaggio successivo. L'URL di inoltro viene generato in modo casuale.

Configurare nel portale di Azure

Nella sessione di debug modificare l'URI della competenza dell'API Web personalizzata per chiamare l'URL di inoltro tunnelmole o ngrok. Assicurarsi di aggiungere "/api/FunctionName" quando si usa la funzione di Azure per l'esecuzione del codice del set di competenze.

È possibile modificare la definizione della competenza nel portale.

Eseguire test del codice

A questo punto, le nuove richieste dalla sessione di debug dovrebbero ora essere inviate alla funzione di Azure locale. È possibile usare i punti di interruzione in Visual Studio Code per eseguire il debug del codice o eseguire istruzioni dettagliate.

Passaggi successivi

Dopo aver compreso il layout e le funzionalità dell'editor visivo Sessioni di debug, provare l'esercitazione per un'esperienza pratica.

Esercitazione: Esplorare le sessioni di debug

Condividi tramite