Valutazione continua con i monitoraggi online

Il monitoraggio online ti consente di valutare continuamente la qualità dei tuoi agenti in produzione. Questo approccio proattivo ti aiuta a identificare la deviazione della qualità, ovvero una diminuzione osservabile delle prestazioni dell'agente nel tempo, causata da cambiamenti nel comportamento degli utenti o nei dati esterni. Configurando i monitor online, puoi valutare in modo asincrono le tracce live utilizzando metriche predefinite e personalizzate, garantendo che l'agente rimanga affidabile e in linea con i tuoi standard di rendimento.

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 Eseguire 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 Valutare gli agenti per le istruzioni di inizializzazione dell'SDK Agent Platform.

Requisiti di telemetria

Il monitoraggio online richiede all'agente di esportare segnali OpenTelemetry specifici per fornire il contesto necessario per la valutazione:

  1. Richiama span 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 di tutti gli strumenti a disposizione dell'agente.

Se utilizzi l'Agent Development Kit, devi abilitare 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 il tuo 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. Configura le seguenti variabili di ambiente per abilitare questa funzionalità:

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 Raccogliere prompt e risposte multimodali.

Come funzionano i monitoraggi online

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

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

Creare un monitoraggio online

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

    Vai a Valutazione

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

  3. Specifica tracce filtro:

    • 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 metriche:aggiungi le metriche che vuoi monitorare continuamente, ad esempio Sicurezza.

  6. Imposta campionamento:

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

  7. Fai clic su Crea.

Gestire i 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 Attiva o Disattiva per mettere in pausa la valutazione senza eliminare la configurazione.
  • Mettere in pausa e riprendere:utilizza Altre opzioni per interrompere temporaneamente la valutazione.
  • Duplica:crea un nuovo monitor con le impostazioni precompilate di uno esistente.
  • Visualizza tracce:fai clic sul link Visualizza tracce nella colonna Tracce campionate 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 Piattaforma dell'agente > Agenti.
  2. Nel menu di navigazione a sinistra, seleziona Implementazioni.

  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.

Visualizzare i risultati per le 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 per l'interazione specifica.

Risolvere i problemi relativi ai monitoraggi online

Se il monitor online è attivo, ma non vengono visualizzati risultati nel pannello:

  1. Verifica la telemetria:assicurati che l'agente esporti correttamente gli eventi e gli span OpenTelemetry richiesti. Controlla Cloud Trace per vedere se le tracce live 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 diagnostiche 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 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"