Eseguire valutazioni offline

Anteprima: valutazione degli agenti sulla piattaforma agentica Gemini Enterprise

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi, nonché ai Termini specifici dei servizi di AI generativa. Questa funzionalità consente ai clienti di valutare gli agenti AI, pertanto si applicano i Termini specifici dei servizi "Servizi di AI agentica". I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

La valutazione offline ti consente di misurare il rendimento, la sicurezza e la qualità dei tuoi agenti analizzando i dati storici acquisiti durante lo sviluppo o la produzione. Puoi valutare le singole tracce (percorsi di esecuzione singoli) o le sessioni complete (cronologie delle conversazioni a più turni) in base a un insieme di metriche predefinite o personalizzate.

Tracce e sessioni

• Traccia: un record fattuale e immutabile del comportamento dell'agente, inclusi input, risposte e chiamate di strumenti del modello. Una traccia rappresenta un singolo percorso di esecuzione.
• Sessione: comprende l'intera interazione a più turni tra un utente e un agente. Utilizza le sessioni per valutare la conservazione del contesto e il flusso conversazionale nel tempo.

Prima di iniziare

Per assicurarti di disporre dei dati e dell'ambiente necessari per la valutazione offline, completa i seguenti passaggi:

• Assicurati di aver eseguito il deployment di un runtime dell'agente funzionante con Cloud Trace abilitato.
• Configura un bucket Cloud Storage per archiviare i risultati della valutazione. Devi fornire questo percorso una sola volta; verrà precompilato per le esecuzioni future.
• Se prevedi di utilizzare l'SDK Agent Platform per la valutazione, inizializza il client come descritto in Valutare gli agenti.

Requisiti di telemetria

La valutazione offline richiede che l'agente esporti segnali OpenTelemetry specifici per fornire il contesto necessario per la valutazione. Questi requisiti sono identici a quelli dei monitor online:

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 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'

Registrare 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 span 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 ulteriori informazioni, consulta Raccogliere prompt e risposte multimodali.

Creare una valutazione dal registro

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

   Vai a Valutazione

2. Fai clic su Nuova valutazione.

3. Seleziona la scheda Tracce o Sessioni in base all'obiettivo della valutazione.

4. Utilizza l'icona del filtro e il selettore di data e ora per filtrare i dati (ad esempio, per Versione o "Ultime 2 settimane") e seleziona gli ID specifici che vuoi valutare.

5. Fai clic su Continua.

6. (Facoltativo) Nel campo Nome valutazione, inserisci un nome per la valutazione o utilizza il valore predefinito precompilato.

7. Nel campo Percorso dei dati privati di output, inserisci l'URI del bucket Cloud Storage. Dopo il primo utilizzo, questo percorso viene precompilato per le esecuzioni future.

8. Per impostazione predefinita, vengono aggiunte tutte e quattro le metriche principali. Puoi aggiungere o rimuovere le metriche in base alle esigenze.

9. Fai clic su Valuta agente.

Valutare una singola traccia o sessione

Puoi attivare le valutazioni direttamente durante l'ispezione dei singoli percorsi di esecuzione:

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. Seleziona la scheda Tracce.
5. Fai clic su Visualizzazione sessione o Visualizzazione traccia per ispezionare il percorso di esecuzione.
6. Seleziona una riga specifica della tabella per aprire il riquadro dei dettagli.
7. Seleziona la scheda Valutazione.
8. Se la traccia o la sessione non è stata valutata, fai clic su Valuta per eseguire una valutazione ad hoc.

Visualizzare i risultati di una valutazione

Al termine della valutazione, puoi analizzare i risultati per identificare le lacune di rendimento e i problemi sistemici:

• Visualizzare i risultati di un'esecuzione: nella Google Cloud console, vai alla Agent Platform > Agenti > Valutazione pagina e seleziona la Valutazioni scheda. Fai clic sul nome di una valutazione per visualizzare il report dettagliato.

  Vai a Valutazione

• Visualizzare in dettaglio le tracce: da un report dei risultati, fai clic su una riga per passare direttamente alla traccia associata e ispezionare il ragionamento (le motivazioni) alla base dei punteggi.

Per ulteriori informazioni, consulta Analizzare i risultati della valutazione.