Eseguire il debug di un set di competenze di Azure AI Search nel portale di Azure

Articolo
07/17/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 Azure AI Search.

Una sessione di debug consiste nell’esecuzione di un indicizzatore memorizzato nella cache e di un set di competenze, con ambito limitato a 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 Azure AI Search. Per esercitarsi a usare un flusso di lavoro di debug con un documento di esempio, vedere Esercitazione: Sessioni di debug.

Prerequisiti

Una pipeline di arricchimento esistente, che include un'origine dati, un set di competenze, un indicizzatore e un indice.
Assegnazione del ruolo di Collaboratore nel servizio di ricerca.
Account di archiviazione di Azure per salvare lo stato della sessione.
Assegnazione del ruolo di Collaboratore ai dati dei BLOB di archiviazione in Archiviazione di Azure se si usa un'identità gestita dal sistema. In caso contrario, pianificare l'uso di una stringa di connessione di accesso completa per la connessione della sessione di debug ad Archiviazione di Azure.
Se l'account di archiviazione di Azure è protetto da un firewall, configurarlo per consentire l'accesso al servizio di ricerca.

Limiti

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

Azure Cosmos DB per MongoDB non è attualmente supportato.
Per Azure Cosmos DB per NoSQL: se si verifica un errore in una riga durante l'indicizzazione 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: non è possibile usare un'identità gestita assegnata dall'utente per connettere una sessione di debug ad Archiviazione di Azure. Come indicato nei prerequisiti, è possibile usare un'identità gestita dal sistema o specificare una stringa di connessione di accesso completo che include una chiave. Per altre informazioni, vedere Connettere un servizio di ricerca ad altre risorse di Azure tramite 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 stringhe 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 individuare 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 Archiviazione BLOB o Azure Data Lake Storage Gen2. È possibile riutilizzare lo stesso contenitore per tutte le sessioni di debug successive che verranno create. Un nome di contenitore utile potrebbe essere "cognitive-search-debug-sessions".
In Autenticazione identità gestita scegliere Nessuno se la connessione ad Archiviazione di Azure non usa un'identità gestita. In caso contrario, scegliere l'identità gestita a cui sono state concesse le autorizzazioni di Collaboratore ai dati dei BLOB di archiviazione.
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, viene richiesto un URI o un ID riga, a seconda dell'origine dati.

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 è in genere simile a quella mostrata nella schermata. Selezionare Salva sessione per iniziare.

La sessione di debug inizia con l'esecuzione del 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 mentre è in corso usando il pulsante Annulla. Se si preme il pulsante Annulla è in genere possibile analizzare i risultati parziali.

È previsto che l'esecuzione di una sessione di debug richieda più tempo rispetto all'indicizzatore perché include un'elaborazione aggiuntiva.

Iniziare con errori e avvisi

La cronologia di esecuzione dell'indicizzatore nel portale fornisce l'elenco completo degli errori e degli avvisi per tutti i documenti. In una sessione di debug, gli errori e gli avvisi si riferiscono a un documento. Esaminare l’elenco, apportare le modifiche e quindi tornare all’elenco per verificare se i problemi sono stati risolti.

Per visualizzare i messaggi, selezionare una competenza in Arricchimento tramite intelligenza artificiale> Grafo delle competenze e quindi selezionare Errori/Avvisi nel riquadro dei dettagli.

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

Per confermare che 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 numero è minore. 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 la struttura dai documenti di origine, creando un documento arricchito nel processo. Un documento arricchito viene creato inizialmente durante il cracking del documento e popolato con un nodo radice (/document), oltre che con i nodi di qualsiasi contenuto rimosso 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.

Benché i documenti arricchiti siano interni, 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: Arricchimento tramite intelligenza artificiale> Grafo delle competenze, con il tipo di grafo impostato su Grafo delle dipendenze.
Selezionare una competenza.
Nel riquadro dei dettagli a destra selezionare Esecuzioni, scegliere un OUTPUT e quindi aprire l'analizzatore di espressioni (</>) per visualizzare l'espressione e il relativo risultato.
In alternativa, aprire Arricchimenti tramite intelligenza artificiale> Struttura dei dati arricchiti per scorrere verso il basso l'elenco dei nodi. L'elenco include i 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 l’output, potrebbe non essere presente una proprietà o un parametro,condizione che può essere determinata tramite i 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 il problema ma non fornisce indicazioni su come risolverlo. Per informazioni sul contesto e sulla sintassi di input, vedere Arricchimenti di riferimento in un set di competenze di Azure AI Search. Per informazioni sui singoli messaggi, vedere Risoluzione degli errori e degli avvisi comuni dell'indicizzatore.

La procedura seguente mostra come ottenere informazioni su una competenza.

In Arricchimento tramite intelligenza artificiale> Grafo delle competenze selezionare una competenza. Il riquadro Dettagli competenza si apre a destra.
Modificare una definizione di competenza usando uno dei due approcci seguenti:
- Impostazioni competenza 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. Il 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 un 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 in un indice di ricerca.

Iniziare con le visualizzazioni predefinite: Arricchimento tramite intelligenza artificiale> Grafo delle competenze, con il tipo di grafo impostato su Grafo delle dipendenze.
Selezionare Mapping dei 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 e l’arricchimento è stato ignorato, è in genere possibile trovare tali campi in Mapping dei campi.
Selezionare Mapping dei campi di output nella parte inferiore del grafo. 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 Importazione dei dati, i mapping dei campi di output vengono definiti manualmente e potrebbero essere incompleti o non digitati correttamente.

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

Eseguire il debug di una competenza personalizzata in locale

Eseguire il debug delle competenze personalizzate può essere più complesso perché il codice viene eseguito esternamente, quindi non è possibile usare la sessione di debug per eseguire il debug di tali competenze. Questa sezione descrive come eseguire il debug locale della competenza dell'API Web personalizzata, eseguire il debug della sessione, tramite 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 permette di 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 .exe precompilato per Windows e inserirlo in un punto qualsiasi del PERCORSO.
Eseguire questo comando per creare un nuovo tunnel:
```
tmole 7071
```
Verrà visualizzato un risultato simile al 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 esegue l’inoltro alla porta 7071 nel computer locale, che è la porta predefinita in cui vengono esposte le funzioni di Azure.

Uso di ngrok

ngrok è un'applicazione multipiattaforma closed source popolare che permette di 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 porta 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 eseguire il 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 vengono in genere inviate alla funzione di Azure locale. È possibile usare i punti di interruzione in Visual Studio Code per eseguire il debug del codice o eseguire l’operazione un passaggio alla volta.

Passaggi successivi

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

Esercitazione: Esplorare le sessioni di debug

Condividi tramite