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 traccia è generalmente disponibile per i prompt e gli agenti ospitati. Workflow e gli agenti esterni sono in versione 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.

Il punto di partenza consigliato è il tracciamento lato server. Foundry lo abilita automaticamente dopo la connessione di una risorsa di Application Insights al progetto. Non sono necessarie modifiche al codice e le tracce sono disponibili entro pochi minuti dall'abilitazione. Il tracing lato server funziona per qualsiasi agente ospitato in Foundry. Quando è necessaria visibilità sul codice dell'applicazione, ad esempio per tracciare la logica personalizzata che circonda una chiamata dell'agente, è possibile aggiungere la strumentazione lato client come secondo passaggio.

Il Microsoft Foundry Skill può aiutare a scegliere il tracciamento lato server o lato client e a risolvere i problemi dovuti alla telemetria mancante.

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.

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

  • Per connettere una risorsa esistente, selezionare la risorsa e quindi selezionare Connetti.
  • Per creare una nuova risorsa, selezionare Crea nuovo e quindi completare la procedura guidata.

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

Usa il percorso di connessione dei dettagli del progetto

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

  1. Selezionare Gestisci nella barra di spostamento in alto a destra, quindi selezionare Dettagli del progetto. Schermata della sezione Gestisci con l'opzione Dettagli progetto evidenziata.
  2. Selezionare la scheda Risorse connesse e quindi selezionare Aggiungi connessione. Schermata di Dettagli del progetto con la scheda Risorse connesse selezionata e il pulsante Aggiungi connessione evidenziato.
  3. In Scegliere una connessione selezionare Application Insights. Screenshot di Scegli una connessione con Application Insights evidenziato.

Per l'acquisizione delle tracce con autenticazione Entra, vedere Configurare l'autenticazione di Microsoft Entra per l'acquisizione delle tracce di Foundry Agent (anteprima).

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

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

Iniziare 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. Una volta abilitata la traccia nel progetto Foundry, è possibile accedere alle tracce predefinite relative agli ultimi 90 giorni.
  • Foundry supporta anche un'integrazione semplice con i framework principali dell'agente .

Tracce lato client con Microsoft Foundry SDK (Python)

Installare OpenTelemetry e il plug-in di traccia Azure SDK attenendosi alla procedura seguente:

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

Riferimento: azure-ai-projects, azure-core-tracing-opentelemetry

Importante

Per usare l'endpoint di un progetto nell'applicazione, è necessario configurare Microsoft Entra ID. Se non si configura Microsoft Entra ID, utilizzare la stringa di connessione di Application Insights.

Dopo aver avviato l'agente, è possibile 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.

Esegui il tracciamento in locale con l'estensione Microsoft Foundry Toolkit per Visual Studio Code

L'estensione Microsoft Foundry Toolkit for Visual Studio Code consente di tracciare localmente in VS Code usando un agente di raccolta compatibile con OTLP locale. Questo approccio è ideale per lo sviluppo e il debug.

Il toolkit supporta framework di intelligenza artificiale come il servizio agente Foundry, 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 scorrere ogni intervallo, identificare i problemi e osservare la risposta dell'applicazione. Questo processo consente di 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 predefinito, oltre alle tracce nella pagina Tracce.

Cerca in base all'ID della risposta o a un ID di traccia associato a questa conversazione. Selezionare quindi un ID della conversazione da esaminare:

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

Screenshot del riquadro Dettagli conversazione in Foundry che mostra un ID conversazione con una cronologia di traccia e i dettagli sui 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 visualizzare i relativi dettagli.

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

Sicurezza e privacy

Il tracciamento può acquisire informazioni sensibili, come input dell'utente, output del modello e parametri e risultati degli strumenti. Usare queste procedure per ridurre i rischi:

  • Non archiviare segreti, credenziali o token in richieste, argomenti dello strumento o attributi span.
  • 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 in base al 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. Se le tabelle sono protette, assegnare anche Privileged Monitoring Data 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 nelle tracce 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

Dopo aver configurato la traccia, esplorare queste risorse per approfondire la comprensione e estendere le funzionalità di osservabilità:

  • Last updated on