Sessioni di debug in Azure AI Search

Sessioni di debug è un editor visivo che funziona con set di competenze esistenti nel portale di Azure, esponendo la struttura e il contenuto di un unico documento arricchito, come generato da un indicizzatore e un set di competenze, per la durata della sessione. Poiché si usa un documento live, la sessione è interattiva; è possibile identificare gli errori, modificare e richiamare l'esecuzione delle competenze e convalidare i risultati in tempo reale. Se le modifiche risolvono il problema, è possibile eseguirne il commit in un set di competenze pubblicato per applicare le correzioni a livello globale.

Questo articolo illustra gli scenari supportati e la modalità di organizzazione dell'editor. Schede e sezioni dell'editor decomprimono livelli diversi del set di competenze in modo da poter esaminare la struttura, il flusso del set di competenze e il contenuto generato in fase di esecuzione.

Scenari supportati

Usare sessioni di debug per analizzare e risolvere i problemi relativi a:

• Competenze predefinite usate per l’arricchimento tramite intelligenza artificiale, ad esempio OCR, analisi delle immagini, riconoscimento delle entità ed estrazione di parole chiave.

• Competenze predefinite usate per la vettorizzazione integrata, con suddivisione dei dati tramite suddivisione del testo e vettorizzazione tramite una competenza di incorporamento.

• Competenze personalizzate usate per integrare l'elaborazione esterna che si fornisce.

Confrontare le immagini di sessione di debug seguenti per i primi due scenari. Per entrambi gli scenari, l'area di attacco mostra la progressione delle competenze che generano o trasformano il contenuto durante l’instradamento dal documento di origine all'indice di ricerca. Il flusso include opzioni di mapping degli indici ed è possibile tracciare le frecce per seguire il percorso di elaborazione. Il riquadro dei dettagli a destra è sensibile al contesto. Mostra una rappresentazione del documento arricchito creato dalla pipeline o i dettagli di una competenza o di un mapping.

La prima immagine mostra un modello per l'arricchimento tramite intelligenza artificiale applicato (senza vettori). Le competenze possono essere eseguite in sequenza o in parallelo se non sono presenti delle dipendenze. I mapping degli indici mostrano come contenuti arricchiti o generati passano da strutture di dati in memoria ai campi in un indice. Il documento arricchito mostra la struttura di dati creata dal set di competenze.

La seconda immagine mostra un modello tipico per la vettorializzazione integrata. Le competenze per la vettorializzazione integrata includono in genere una competenza Suddivisione del testo e una competenza di incorporamento. La competenza Suddivisione del testo divide un documento in blocchi. La competenza di incorporamento chiama un'API di incorporamento per vettorizzare i blocchi. Questo particolare set di competenze suddivide il contenuto in una matrice di "pagine". Per la vettorializzazione integrata, i mapping di proiezione controllano il mapping dei blocchi ai campi nell'indice.

Limitazioni

Le sessioni di debug funzionano con tutte le origini dati indicizzatore disponibili a livello generale e la maggior parte delle origini dati di anteprima, con le eccezioni seguenti:

• Indicizzatore di SharePoint.

• Indicizzatore di Azure Cosmos DB per MongoDB.

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

• Origini dati con crittografia abilitata tramite chiavi gestite dal cliente.

• I collegamenti privati condivisi non sono supportati. Se il servizio di ricerca usa la connettività dell'endpoint privato per raggiungere origini dati o altre risorse, le sessioni di debug non possono accedere a tali risorse. Per una soluzione alternativa, vedere Eseguire il debug di sessioni e connettività privata.

• Attualmente, la possibilità di selezionare il documento di cui eseguire il debug non è prevista. Questa limitazione non è permanente e dovrebbe essere rimossa presto. Le sessioni di debug selezionano il primo documento nella cartella o nel contenitore dei dati di origine.

Funzionamento di una sessione di debug

Quando si avvia una sessione, il servizio di ricerca crea una copia del set di competenze, dell'indicizzatore e di un'origine dati contenente un singolo documento usato per testare il set di competenze. Il servizio Azure AI Search salva tutto lo stato della sessione in un nuovo contenitore BLOB creato in un account Archiviazione di Azure specificato. Il nome del contenitore generato ha un prefisso .ms-az-cognitive-search-debugsession Questo prefisso riduce la possibilità di esportare accidentalmente i dati della sessione in un altro contenitore nell'account.

Se si configura la connessione all'account di archiviazione tramite un'identità gestita, assegnare il ruolo Storage Blob Data Contributor all'identità del servizio di ricerca nell'account di archiviazione. Nel tuo account di archiviazione, attiva i servizi attendibili per consentire ad Azure AI Search l'accesso in scrittura.

Una copia memorizzata nella cache del documento arricchito e del set di competenze viene caricata nell'editor visivo in modo da poter esaminare il contenuto e i metadati del documento arricchito, con la possibilità di controllare ogni nodo documento e modificare qualsiasi aspetto della definizione del set di competenze. Tutte le modifiche apportate all'interno della sessione vengono memorizzate nella cache. Queste modifiche non influiscono sul set di competenze pubblicato, a meno che non sia eseguito il commit. Il commit delle modifiche comporterà la sovrascrittura del set di competenze di produzione.

Se la pipeline di arricchimento non contiene errori, è possibile usare una sessione di debug per arricchire in modo incrementale un documento, testare e convalidare ogni modifica prima di eseguire il commit delle modifiche.

Le sessioni di debug consentono di identificare la causa radice di errori o avvisi analizzando dati, input e output delle competenze e mapping dei campi. Usare il riquadro dei dettagli della competenza per controllare ciò che ogni competenza riceve come input e produce come output. Questa ispezione consente di verificare che le definizioni delle competenze, le espressioni e i mapping dei campi siano formati correttamente. Se l'indicizzatore rileva problemi di configurazione, ad esempio errori di configurazione della rete o errori di accesso correlati alle autorizzazioni, esaminare il messaggio di errore specifico e la documentazione collegata. Per indicazioni sulla risoluzione dei problemi, vedere Errori e avvisi comuni dell'indicizzatore.

Eseguire il debug di sessioni e connettività privata

Le sessioni di debug non supportano collegamenti privati condivisi. Se il servizio di ricerca di produzione usa la connettività dell'endpoint privato per accedere alle origini dati o ad altre risorse, le sessioni di debug non possono essere eseguite su tale servizio.

Soluzione alternativa: usare un servizio di ricerca di test

Per eseguire il debug del set di competenze, creare un servizio di Azure AI Search separato senza restrizioni di connettività privata. Per mantenere i dati di produzione e i dettagli dello schema all'esterno di un ambiente non privato, compilare la configurazione dei test con documenti sintetici:

• Creare documenti di test che corrispondono ai tipi di campo e alla struttura dei dati di produzione, ma usare nomi di campo generici (ad esempio, content, title, category) e valori segnaposto anziché dati reali. La logica del set di competenze dipende da tipi di contenuto e struttura, non da nomi di campo specifici.
• Copia il JSON del set di competenze dal servizio di produzione. Se gli input delle competenze fanno riferimento ai nomi dei campi di produzione, aggiornarli in modo che corrispondano ai nomi dei campi di test generici. Usa le mappature dei campi nell'indicizzatore di test per allineare i nomi dei campi di test con gli input del set di competenze.
• Configurare un indicizzatore da eseguire sull'origine dati di test.

Eseguire la sessione di debug nel servizio di test per esaminare gli input e gli output delle competenze, convalidare le espressioni di competenza e i mapping dei campi e identificare gli errori. Quando le modifiche sono state convalidate, ripristina i riferimenti originali ai nomi dei campi di produzione nel JSON dello skillset e riapplicalo al servizio di produzione.

Eseguire il debug del layout della sessione

L'editor visivo è organizzato in un'area di superficie che mostra una progressione delle operazioni, a partire dal cracking del documento, seguito da competenze, mapping e indice.

Selezionare qualsiasi competenza o mapping e viene aperto un riquadro che mostra le informazioni pertinenti.

Seguire i collegamenti per approfondire l'elaborazione delle competenze. Ad esempio, lo screenshot seguente mostra l'output della prima iterazione della competenza Divisione testo.

Riquadro dei dettagli competenza

Il riquadro Dettagli competenza include le sezioni seguenti:

• Iterazioni: mostra quante volte viene eseguita una competenza. È possibile controllare gli input e gli output di ognuno di essi.
• impostazioni della competenza: visualizzare o modificare la definizione del set di competenze JSON.
• Errori e avvisi: mostra gli errori o gli avvisi specifici di questa competenza.

Riquadro Struttura dei dati arricchita

Il riquadro struttura dei dati arricchita scorre verso il lato quando si seleziona il simbolo di freccia blu o nascosto. È una rappresentazione leggibile di ciò che contiene il documento arricchito. Gli screenshot precedenti in questo articolo mostrano esempi della struttura dei dati arricchita.

Passaggi successivi

Dopo aver compreso gli elementi delle sessioni di debug, avviare la prima sessione di debug in un set di competenze esistente.