Come tracciare un'applicazione con prompt flow SDK | Studio AI della piattaforma Azure
Importante
Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente disponibili in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.
Lo strumento di traccia offre agli sviluppatori la potenza di una comprensione approfondita del processo di esecuzione delle applicazioni di intelligenza artificiale generativa, ad esempio agenti, AutoGene casi d'uso RAG (Retrieval Augmented Generation). Esso fornisce una vista dettagliata del flusso di esecuzione, inclusi gli input e gli output di ciascun nodo all'interno dell'applicazione. Queste informazioni essenziali sono di fondamentale importanza durante il debug di applicazioni complesse o l'ottimizzazione delle prestazioni.
Tuttavia, sempre più sviluppatori usano vari framework, ad esempio Langchain, Semantic Kernel, OpenAI e diversi tipi di agenti, per creare applicazioni basate su LLM. La traccia con l'SDK prompt flow assicura una visibilità avanzata e una risoluzione dei problemi semplificata per le applicazioni basate su LLM, inoltre supporta efficacemente lo sviluppo, l'iterazione e il monitoraggio della produzione. La traccia in Studio AI segue la specifica OpenTelemetry, acquisendo e visualizzando i dettagli di esecuzione interna di qualsiasi applicazione di intelligenza artificiale e migliorando, complessivamente, l'esperienza di sviluppo.
Vantaggi della traccia di Studio AI sulla piattaforma cloud di livello aziendale
In aggiunta, adesso viene offerto il test locale permanente in Studio AI, che è la piattaforma cloud di livello aziendale, con conseguente significativo miglioramento della collaborazione, della persistenza e della gestione della cronologia dei test.
Grazie alla traccia è possibile:
- Disporre di una posizione basata sul cloud per rendere permanenti i test cronologici e tenerne traccia.
- Estrarre e visualizzare facilmente i risultati dei test, confrontando gli output di diversi test case.
- Riutilizzare gli asset di test precedenti per un utilizzo successivo, ad esempio feedback umano, cura dei dati e così via.
- Facilitare un migliore utilizzo delle risorse in futuro.
- Eseguire il debug e ottimizzare l'applicazione con facilità. Per iniziare a eseguire il debug degli scenari dell’applicazione LLM, vedere Tracciamento con l'applicazione LLM
- Analizzare i processi di recupero e generazione nelle applicazioni RAG.
- Osservare le interazioni tra più agenti negli scenari con più agenti. Per iniziare a usare il tracciamento in scenari con più agenti, vedere Traccia con AutoGen.
Registrare e visualizzare le tracce delle applicazioni
Studio AI offre la funzionalità di traccia per la registrazione e la gestione di test e valutazioni delle applicazioni LLM eseguendo, allo stesso tempo, il debug e l'osservazione tramite l’esecuzione del drill-down della vista della traccia.
Attualmente, la traccia di qualsiasi funzionalità dell'applicazione viene implementata nel pacchetto open source prompt flow, per consentire all'utente di tenere traccia della chiamata o della funzionalità LLM e dei framework LLM quali LangChain e AutoGen, indipendentemente dal framework, usando la specifica OpenTelemetry.
Abilitare il tracciamento nell'applicazione
Code First: assicurarsi di avere annotato il codice per la traccia in prompt flow!
- Installazione di prompt flow: richiedere il tracciamento di prompt flow
- Strumentazione del codice dell'applicazione: usando
@traceestart_trace(). - Testare e visualizzare la traccia in locale
Per ulteriori informazioni sulla traccia in prompt flow, vedere questa documentazione prompt flow.
Registrare la traccia in Studio AI
Impostare la destinazione della traccia
Per impostazione predefinita, la traccia viene registrata e visualizzata nell'ambiente locale. Per registrarla in Studio AI nel cloud, è necessario impostare trace destination su un progetto di Studio AI specificato.
È possibile fare riferimento ai passaggi seguenti per impostare la destinazione della traccia sul progetto di Studio AI.
In primo luogo, verificare che l'interfaccia della riga di comando di Azure sia installata e connessa:
az login
Successivamente, eseguire il comando seguente per impostare la destinazione della traccia. Sostituire <your_subscription_id>, <your_resourcegroup_name>e <your_studio_project_name> con l'ID sottoscrizione, il nome del gruppo di risorse e il nome del progetto di Studio AI specifici:
pf config set trace.destination=azureml://subscriptions/<your_subscription_id>/resourcegroups/<your_resourcegroup_name>/providers/Microsoft.MachineLearningServices/workspaces/<your_studio_project_name>
Nota
L'area Stati Uniti occidentali 3 (westus3) non supporta la traccia.
Raccolte
Una raccolta è un gruppo di tracce associate. In Studio AI queste raccolte, insieme alle relative tracce interne, vengono gestite e archiviate nel modulo Traccia nella scheda Raccolte.
Passare al progetto in Studio AI.
Nel riquadro di sinistra, selezionare Traccia. È possibile visualizzare la scheda Raccolte. Nell'elenco delle raccolte è possibile visualizzare soltanto le raccolte personalizzate. In questo esempio, non sono ancora presenti raccolte.
La scheda Raccolta mostra un elenco completo di tutte le raccolte create. Vi sono indicati i metadati essenziali per ogni raccolta, tra cui il nome, il percorso di esecuzione, l'ora dell'ultimo aggiornamento e l'ora di creazione.
- Percorso di esecuzione: indica se l'applicazione viene eseguita in locale o nel cloud. La raccolta cloud è associata a una specifica cronologia di test della creazione cloud prompt flow e tracce generate. In questo caso, il nome della raccolta corrisponde al nome visualizzato nel prompt flow.
- Aggiornato il: mostra l'ora più recente di registrazione di una nuova traccia in una raccolta. Per impostazione predefinita, le raccolte vengono organizzate in ordine decrescente in base agli orari di aggiornamento.
- Creato il: ora di inizio della creazione della raccolta.
Selezionando il nome di una raccolta, è possibile accedere a un elenco di tutte le tracce all'interno di tale raccolta. Solo un subset di tracce può essere condiviso con altri utenti. Per ulteriori informazioni, consultare condividere una traccia.
Quando si registra una traccia, è possibile specificare il nome di una raccolta per raggrupparlo con altre tracce correlate. È possibile creare più raccolte per consentire una migliore organizzazione delle tracce. Se non si specifica il nome di una raccolta durante la registrazione di una traccia, esso diventa, per impostazione predefinita, il nome della cartella del progetto o la raccolta predefinita.
Personalizzare le raccolte
Per organizzare meglio le tracce, è possibile specificare un nome di raccolta personalizzato durante la registrazione di una traccia.
Quando si tiene traccia dell’applicazione, è possibile impostare il nome della raccolta nella funzione start_trace() nel codice:
from promptflow.tracing import start_trace, trace
@trace
def my_function(input: str) -> str:
output = input + "Hello World!"
return output
my_function("This is my function")
start_trace(collection="my_custom_collection")
Per altre informazioni sulla personalizzazione delle raccolte, consultare l'esercitazione sulla traccia e il comando prompt flow.
Visualizzare le tracce
In primo luogo, è necessario completare i passaggi precedenti per visualizzare le tracce nel cloud:
A questo punto, eseguire direttamente lo script Python. Quando l'esecuzione è stata completata correttamente, nell'output viene visualizzato un collegamento alla traccia cloud. che sarà simile al seguente:
Starting prompt flow service...
...
You can view the traces in cloud from AI Studio: https://ai.azure.com/projecttrace/detail/....
Selezionare l'URL per passare a una pagina dei dettagli di traccia nel portale cloud. Questa pagina è simile alla vista della traccia locale.
La vista dei dettagli della traccia fornisce una panoramica completa e strutturata delle operazioni all'interno dell'applicazione.
Informazioni sulla vista dei dettagli della traccia
Nell'angolo in alto a destra della vista della traccia, si trovano:
- Nome traccia: uguale al nome dell'intervallo radice, che rappresenta il nome della funzione di ingresso dell'applicazione.
- Stato: potrebbe essere "completato" o "non riuscito".
- Durata totale: durata totale dell'esecuzione del test. Passare il puntatore del mouse per visualizzare l'ora di inizio e di fine.
- Token totali: costo totale dei token del test. Passare il puntatore del mouse per visualizzare i token di richiesta e i token completati.
- Ora di creazione: ora della creazione della traccia.
Sul lato sinistro è possibile visualizzare una struttura ad albero gerarchica. Questa struttura mostra la sequenza delle chiamate di funzione. I metadati di ogni chiamata di funzione sono organizzati in intervalli. Questi intervalli sono collegati tra loro in una struttura di tipo ad albero e illustrano la sequenza di esecuzione.
Nell'SDK di prompt flow sono stati definiti diversi tipi di intervallo, tra cui LLM, Funzione, Incorporazione, Recupero e Flusso. Il sistema crea automaticamente intervalli con informazioni sull'esecuzione negli attributi e negli eventi designati.
Ogni intervallo consente di visualizzare:
- Nome funzione: per impostazione predefinita, si tratta del nome della funzione come definito nel codice. Tuttavia, può anche essere un nome di intervallo personalizzato definito tramite Open Telemetry.
- Durata: rappresenta la durata di esecuzione della funzione. Passare il puntatore del mouse per visualizzare l'ora di inizio e di fine.
- Token per le chiamate LLM: indica il costo del token della chiamata LLM. Passare il puntatore del mouse per visualizzare i token di richiesta e i token completati.
Selezionando un intervallo specifico, è possibile passare alla visualizzazione delle informazioni dettagliate associate sul lato destro. Queste informazioni includono input, output, JSON non elaborato, log ed eccezioni, elementi essenziali per osservare ed eseguire il debug dell'applicazione.
Per l'intervallo LLM, viene fornita una vista chiara della conversazione. Sono incluse la richiesta di sistema, la richiesta utente e la risposta assistente. Queste informazioni sono particolarmente importanti in casi con più agenti, poiché consentono di comprendere il flusso della conversazione e l'interazione all'interno della chiamata automatica intermedia LLM.
È possibile selezionare la scheda JSON non elaborata per visualizzare i dati JSON dell'intervallo. Questo formato potrebbe essere più adatto per gli sviluppatori per quanto riguarda il debug e la risoluzione dei problemi.
Condividere la traccia
Se si desidera condividere la traccia con altri utenti che dispongono dell'autorizzazione per il progetto, è possibile selezionare il pulsante Condividi nell'angolo destro della pagina dei dettagli della traccia; quindi, si disporrà del collegamento alla pagina copiato da condividere con altri utenti.
Nota
La traccia condivisa è di sola lettura e la possono visualizzare solo le persone che dispongono dell'autorizzazione del progetto, tramite il collegamento.