Valutazione continua con i monitoraggi online

Il monitoraggio online ti consente di valutare continuamente la qualità degli agenti in produzione. Questo approccio proattivo ti aiuta a identificare la deviazione della qualità, ovvero un calo osservabile delle prestazioni dell'agente nel tempo, causato da modifiche al comportamento degli utenti o ai dati esterni. Configurando i monitoraggi online, puoi valutare in modo asincrono le tracce in tempo reale utilizzando metriche predefinite e metriche personalizzate, assicurandoti che l'agente rimanga affidabile e allineato ai tuoi standard di prestazioni.

Prima di iniziare

Per attivare il monitoraggio online per i tuoi agenti, assicurati che siano soddisfatti i seguenti requisiti:

  • Esegui il deployment dell'agente come descritto in Esegui il deployment di un agente.
  • Assicurati che Cloud Trace sia abilitato per il tuo progetto.
  • (Facoltativo) Se prevedi di creare monitor in modo programmatico, consulta la pagina Valuta gli agenti per le istruzioni di inizializzazione dell'SDK Agent Platform.

Requisiti di telemetria

Il monitoraggio online richiede che l'agente esporti segnali OpenTelemetry specifici per fornire il contesto necessario per la valutazione:

  1. Intervallo di richiamo dell'agente: deve includere i seguenti attributi:

    • gen_ai.agent.name: l'identificatore dell'agente.
    • gen_ai.agent.description: una breve descrizione dello scopo dell'agente.
    • gen_ai.conversation.id: un identificatore univoco per la sessione di conversazione specifica.

  2. Eventi di inferenza: l'evento gen_ai.client.inference.operation.details deve acquisire:

    • gen_ai.input.messages: i prompt inviati all'agente.
    • gen_ai.output.messages: le risposte generate dall'agente.
    • gen_ai.system_instructions: i prompt di sistema sottostanti.
    • gen_ai.tool.definitions: metadati relativi a tutti gli strumenti disponibili per l'agente.

Se utilizzi l'Agent Development Kit, devi attivare queste funzionalità di telemetria impostando le seguenti variabili di ambiente:

OTEL_SEMCONV_STABILITY_OPT_IN='gen_ai_latest_experimental'
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT='EVENT_ONLY'

Registrazione di contenuti multimediali in Cloud Storage

Se l'agente utilizza dati multimodali, come immagini o documenti di grandi dimensioni, ti consigliamo di registrare gli input e gli output in un bucket Cloud Storage anziché incorporarli direttamente negli intervalli di traccia. Per abilitare questa funzionalità, configura le seguenti variabili di ambiente:

OTEL_INSTRUMENTATION_GENAI_UPLOAD_FORMAT='jsonl'
OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK='upload'
OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH='gs://STORAGE_BUCKET_NAME/PATH'

Per saperne di più, consulta Raccogli prompt e risposte multimodali.

Come funzionano i monitoraggi online

I monitoraggi online vengono eseguiti in un ciclo di valutazione pianificato, in genere ogni 10 minuti. Il loop segue questi passaggi:

  1. Query: Campiona i dati campionati da Cloud Trace e Cloud Logging in base ai filtri.
  2. Valutazione: esegue le metriche configurate utilizzando il servizio di valutazione di Gemini Enterprise Agent Platform.
  3. Report: scrive i risultati in Cloud Logging ed esporta i punteggi numerici in Cloud Monitoring.

Crea un monitoraggio online

  1. Nella console Google Cloud , vai alla pagina Agent Platform > Agenti > Valutazione.

    Vai alla valutazione

  2. Seleziona la scheda Monitor online e fai clic su Nuovo monitor.

  3. Specifica i filtri per le tracce:

    • Motore dell'agente:seleziona l'agente che vuoi monitorare dal menu a discesa.
    • Criteri di filtro: scegli se valutare Tutte le tracce per l'agente o applicare Criteri di filtro specifici.

  4. Definisci i criteri di filtro (se utilizzi tracce filtrate):

    • Ispezione iniziale: seleziona un periodo di tempo (ad esempio, Ultimo giorno) per visualizzare l'anteprima delle tracce di produzione corrispondenti al filtro.
    • Filtri:inserisci i criteri per scegliere come target un traffico specifico. Puoi filtrare in base a proprietà come Duration (ad esempio Duration > 2) o Token usage.

  5. Configura le metriche:aggiungi le metriche che vuoi monitorare continuamente, ad esempio Sicurezza.

  6. Imposta il campionamento:

    • Percentuale di campionamento:definisci la percentuale di traffico in tempo reale da valutare.
    • Numero massimo di esempi per esecuzione: imposta un limite per gestire i costi di valutazione.

  7. Fai clic su Crea.

Gestisci monitor

Una volta creato un monitoraggio, puoi gestirlo dall'elenco Monitoraggi online:

  • Pulsante di attivazione/disattivazione dello stato: fai clic su Altre opzioni e seleziona Abilita o Disabilita per mettere in pausa la valutazione senza eliminare la configurazione.
  • Metti in pausa e riprendi:utilizza Altre opzioni per interrompere temporaneamente la valutazione.
  • Duplica: crea un nuovo monitoraggio con le impostazioni precompilate di un monitoraggio esistente.
  • Visualizza tracce:fai clic sul link Visualizza tracce nella colonna Tracce campionate di un monitor per passare direttamente alle tracce filtrate nella scheda Tracce dell'agente.

Visualizza i risultati nella dashboard di osservabilità

Per visualizzare le metriche di valutazione insieme ad altri indicatori di rendimento:

  1. Nella console Google Cloud , vai alla pagina Agent Platform > Agenti.
  2. Nel menu di navigazione a sinistra, seleziona Deployment.

  3. Seleziona l'agente.

    Vai a Deployment

  4. Nella visualizzazione Dashboard, seleziona la sottosezione Valutazione per visualizzare i grafici delle serie temporali per le metriche configurate, ad esempio qualità della risposta, sicurezza e tassi di allucinazione.

Visualizza i risultati per singole tracce

Puoi anche esaminare i risultati della valutazione per conversazioni specifiche direttamente nella visualizzazione delle tracce:

  1. Nella console Google Cloud , vai alla scheda Tracce dell'agente.
  2. Seleziona una sessione o una traccia dalla tabella per aprire il riquadro dei dettagli.
  3. Seleziona la scheda Valutazione per visualizzare i punteggi e le motivazioni di quella specifica interazione.

Risolvi i problemi relativi ai monitoraggi online

Se il monitoraggio online è attivo, ma non vengono visualizzati risultati nella dashboard:

  1. Verifica la telemetria: assicurati che l'agente esporti correttamente gli span e gli eventi OpenTelemetry richiesti. Controlla Cloud Trace per verificare se le tracce in tempo reale contengono gli attributi gen_ai..
  2. Controlla i filtri:esamina i criteri di filtro del monitor. Utilizza la funzionalità Ispezione iniziale per verificare che i filtri corrispondano al traffico di produzione.

  3. Controlla i log interni: i monitor online scrivono informazioni di diagnostica in Cloud Logging. Se una valutazione non va a buon fine, viene generato un log degli errori. Puoi trovare questi log in Esplora log cercando l'ID del monitor o tracce e agenti specifici:

    resource.labels.online_evaluator="projects/YOUR_PROJECT_ID/locations/YOUR_REGION/onlineEvaluators/YOUR_MONITOR_ID"
# Or search by trace or agent
labels.trace="YOUR_TRACE_ID"
labels.reasoning_engine_id="YOUR_AGENT_ID"