Configurare il tracciamento in Microsoft Foundry

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente 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 avere funzionalità limitate. Per altre informazioni, vedere Condizioni supplementari per l'utilizzo delle anteprime di Microsoft Azure.

Nota

La funzionalità di rastremazione è generalmente disponibile solo per gli agenti prompt. I flussi di lavoro, gli agenti ospitati e gli agenti personalizzati sono in fase di anteprima.

Usare la traccia per eseguire il debug degli agenti di intelligenza artificiale e monitorarne il comportamento nell'ambiente di produzione. La traccia acquisisce dati di telemetria dettagliati, tra cui latenza, eccezioni, richieste di contenuto e operazioni di recupero, in modo da poter identificare e risolvere i problemi più velocemente.

Prerequisiti

Connettere Application Insights al progetto Foundry

Foundry archivia le tracce in Application Insights usando convenzioni semantiche OpenTelemetry.

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia attivato. Questi passaggi fanno riferimento a Foundry (nuovo).These steps refer to Foundry (new).
  2. Aprire il progetto Foundry.
  3. Nella navigazione a sinistra, selezionare Agenti.
  4. Nella parte superiore selezionare Tracce.
  5. A destra selezionare Connetti per creare o connettere una risorsa di Application Insights:
    • Per connettere una risorsa esistente, selezionare la risorsa e quindi selezionare Connetti.
    • Per creare una nuova risorsa, selezionare Crea nuovo e completare la procedura guidata.

Screenshot della scheda Agenti che mostra le tracce e il pulsante Connetti.

Viene visualizzato un messaggio di conferma quando la connessione ha esito positivo.

Dopo aver connesso la risorsa, il progetto è pronto per l'uso della traccia.

Se la barra dei messaggi o il pulsante Connetti non viene visualizzato, ecco un modo alternativo per abilitare Monitoraggio di Azure Application Insights.

  1. Selezionare i Dettagli del progetto dal menu a discesa associato al nome del tuo progetto. Screenshot del menu del nome del progetto con i dettagli del progetto evidenziati.
  2. Passare alla scheda Risorse connesse e quindi selezionare Aggiungi connessione. Screenshot dei dettagli del progetto con la scheda Risorse connesse, selezionare l'evidenziazione dell'aggiunta della connessione.
  3. Selezionare Application Insights nel menu Scegliere una connessione . Screenshot di Scegliere una connessione con Application Insights evidenziato.

Importante

Assicurarsi di avere le autorizzazioni necessarie per eseguire query sui dati di telemetria.

Instrumentare gli agenti di intelligenza artificiale

Scegliere l'approccio corrispondente alla modalità di sviluppo ed esecuzione dell'agente.

Tracce lato server nel portale Foundry

Inizia con le tracce lato server. Foundry registra le tracce per scenari comuni di agente e flusso di lavoro senza modificare il codice.

  • Foundry registra automaticamente le tracce lato server per gli agenti prompt, gli agenti host e i flussi di lavoro nel portale di Foundry. Dopo aver abilitato il tracciamento nel progetto di Foundry, avrai accesso alle tracce predefinite degli ultimi 90 giorni.
  • Foundry consente anche una facile integrazione con i principali framework agente.

Tracce lato client con Microsoft Foundry SDK (Python)

Installare OpenTelemetry e il plug-in di tracciamento dell'Azure SDK utilizzando:

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry

Importante

L'uso dell'endpoint di un progetto nell'applicazione richiede la configurazione di Microsoft Entra ID. Se non si configura Microsoft Entra ID, utilizzare la stringa di connessione di Application Insights.

Dopo aver eseguito l'agente, è possibile iniziare a visualizzare e analizzare le tracce nel portale Foundry.

Per istruzioni dettagliate ed esempi di codice specifici dell'SDK, vedere Tracing with azure-ai-projects (Python SDK) e Telemetry samples for agents.

Traccia in locale con Foundry Toolkit in VS Code

Foundry Toolkit consente di tracciare localmente in VS Code usando un agente di raccolta compatibile con OTLP locale, ideale per lo sviluppo e il debug.

Il toolkit supporta framework di intelligenza artificiale come foundry agents service, OpenAI, Anthropic e LangChain tramite OpenTelemetry. È possibile visualizzare immediatamente le tracce in VS Code senza dover accedere al cloud.

Per istruzioni dettagliate sull'installazione e esempi di codice specifici dell'SDK, vedere Tracing in Foundry Toolkit.

Visualizzare e analizzare le tracce

Visualizzare le tracce nel portale Foundry

Nel progetto Foundry passare alla scheda Tracce negli agenti o nei flussi di lavoro. È possibile cercare, filtrare o ordinare le tracce raccolte negli ultimi 90 giorni.

Selezionare una traccia per esaminare ogni intervallo, identificare i problemi e osservare la risposta dell'applicazione. In questo modo è possibile eseguire il debug e individuare i problemi nell'applicazione.

Visualizza le tracce in Monitoraggio di Azure

Le tracce vengono inviate a Monitoraggio di Azure Application Insights, in modo da poterle visualizzare.

Per altre informazioni su come inviare tracce a Monitoraggio di Azure e creare una risorsa Monitoraggio di Azure, vedere Monitoraggio di Azure documentazione di OpenTelemetry.

Visualizzare i risultati della conversazione

Una conversazione è il contesto permanente di una cronologia di dialoghi end-to-end tra un utente e un agente. Nel portale Foundry è possibile visualizzare i risultati della conversazione per l'agente preconfigurato insieme ai tracciati nella pagina Tracce.

È possibile selezionare una ricerca di conversazione per un ID risposta o cercare in base a un ID traccia mappato a questa conversazione. Selezionare quindi ID conversazione per esaminare la conversazione:

  • Dettagli della cronologia delle conversazioni
  • Informazioni sulla risposta e token in un'operazione
  • Azioni ordinate, passaggi di esecuzione e chiamate agli strumenti
  • Input e output tra un utente e un agente

Screenshot del riquadro dei dettagli della conversazione in Foundry che mostra un ID conversazione con una cronologia delle tracce e i dettagli dei passaggi di esecuzione.

Verifica della funzionalità del tracciamento

  1. Verificare che il progetto sia connesso ad Application Insights. Se necessario, seguire la procedura descritta in Connettere Application Insights al progetto Foundry.

  2. Eseguire il tuo agente o il flusso di lavoro almeno una volta (ad esempio, utilizzando il portale o l'app).

  3. Nel progetto Foundry aprire la visualizzazione Tracce e verificare che venga visualizzata una nuova traccia.

    Quando la traccia funziona correttamente, viene visualizzato un elenco di tracce recenti con timestamp, durate e indicatori di stato. Selezionare una traccia per visualizzarne i dettagli.

Se non vengono visualizzate nuove tracce, attendere alcuni minuti e aggiornare e quindi vedere Risoluzione dei problemi.

Sicurezza e privacy

La traccia può acquisire informazioni riservate, ad esempio input utente, output del modello e argomenti e risultati degli strumenti. Usare queste procedure per ridurre i rischi:

  • Non archiviare segreti, credenziali o token in richieste, argomenti dello strumento o attributi di intervallo.
  • Redigi o riduci al minimo i dati personali e altri contenuti sensibili prima che appaiano nella telemetria.
  • Considerare i dati di traccia come dati di telemetria di produzione e applicare gli stessi controlli di accesso e criteri di conservazione usati per i log e le metriche.

Per altre indicazioni, vedere Sicurezza e privacy.

Conservazione e costi dei dati

Foundry archivia le tracce nella risorsa di Application Insights connessa al progetto. La conservazione e la fatturazione dei dati seguono la configurazione di Application Insights e Log Analytics.

Risoluzione dei problemi

Problema Causa Risoluzione
Non si vedono tracce nel portale Foundry La traccia non è connessa, non è presente traffico recente o l'inserimento viene ritardato Verificare la connessione di Application Insights, generare il nuovo traffico dell'agente e aggiornare dopo alcuni minuti.
Vengono visualizzati errori di autorizzazione durante la query o la visualizzazione dei dati di telemetria Autorizzazioni di controllo degli accessi basato sul ruolo mancanti in Application Insights o Log Analytics Verificare l'accesso in Controllo di accesso (IAM) per le risorse connesse. Per le query di log, assegnare il ruolo Log Analytics Reader.
Le tracce del lato client non vengono visualizzate La strumentazione non è installata o configurata Controllare di nuovo l'installazione del pacchetto e seguire le indicazioni dell'SDK collegate in Tracce sul lato client con Microsoft Foundry SDK (Python).
Il contenuto sensibile viene visualizzato nelle tracce I prompt, gli argomenti degli strumenti o gli output contengono dati sensibili Redigi i dati sensibili prima che entrino nella telemetria e segui le indicazioni in Sicurezza e privacy.

Contenuto correlato

Ora che la traccia è configurata, esplorare queste risorse per approfondire la comprensione e estendere le funzionalità di osservabilità:

  • Last updated on