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 variazione della qualità, ovvero una diminuzione osservabile del rendimento dell'agente nel tempo, causata da modifiche nel comportamento degli utenti o nei dati esterni. Configurando i monitoraggi online, puoi assegnare in modo asincrono un punteggio alle tracce live utilizzando metriche predefinite e personalizzate, assicurandoti 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 monitoraggi a livello di programmazione, consulta la pagina Valuta i tuoi agenti per le istruzioni di inizializzazione dell'SDK Agent Platform.

Requisiti di telemetria

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

  1. Intervallo di chiamata 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 su tutti gli strumenti disponibili per l'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 dei 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. 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 monitoraggi online vengono eseguiti in un loop di valutazione pianificato, in genere ogni 10 minuti. Il loop segue questi passaggi:

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

Creare un monitoraggio online

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

    Vai a Valutazione

  2. Seleziona la scheda Monitoraggi online e fai clic su Nuovo monitoraggio.

  3. Specifica le tracce di 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 che corrispondono al filtro.
    • Filtri: inserisci i criteri per indirizzare il 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 campioni per esecuzione: imposta un limite per gestire i costi di valutazione.

  7. Fai clic su Crea.

Gestire i monitoraggi

Dopo aver creato un monitoraggio, puoi gestirlo dall'elenco Monitoraggi online:

  • Attiva/disattiva stato: fai clic su Altre opzioni e seleziona Attiva o Disattiva 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 da uno esistente.
  • Visualizza tracce: fai clic sul link Visualizza tracce nella colonna Tracce campionate per un monitoraggio per passare direttamente alle tracce filtrate nella scheda Tracce dell'agente.

Visualizzare i risultati nella dashboard di osservabilità

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

  1. Nella Google Cloud console, 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, come la qualità della risposta, la sicurezza e le percentuali 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 Google Cloud console, 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 monitoraggio online è attivo, ma non vengono visualizzati risultati nella dashboard:

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

  3. Controlla i log interni: i monitoraggi online scrivono informazioni diagnostiche in Cloud Logging. Se una valutazione non va a buon fine, viene generato un log di errori. Puoi trovare questi log in Esplora log cercando l'ID del monitoraggio 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"