Analizzare i risultati della valutazione e i cluster di errori

Prima di iniziare

Per visualizzare e analizzare i risultati della valutazione, assicurati di disporre di quanto segue:

• Esegui almeno una valutazione come descritto in Valutare gli agenti o Eseguire valutazioni offline.
• Configurato un bucket Cloud Storage per l'output della valutazione se esegui valutazioni offline.
• (Facoltativo) Se utilizzi l'SDK per recuperare i risultati, assicurati che l'ambiente sia autenticato.

Dopo aver eseguito una valutazione, Agent Platform fornisce strumenti diagnostici per aiutarti a identificare le cause principali dell'errore. Puoi analizzare i risultati a tre livelli: tendenze aggregate nella dashboard, gruppi semantici nei cluster di errori e percorsi logici granulari nelle singole tracce.

La dashboard di valutazione per i monitoraggi online

Per gli agenti con monitor online attivi, puoi visualizzare le tendenze aggregate del rendimento nella dashboard:

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

3. Seleziona l'agente.

   Vai a Deployment

4. Fai clic sulla scheda Dashboard e seleziona la sottosezione Valutazione.

• Tendenze del rendimento:visualizza come cambiano i punteggi per metriche come Riuscita dell'attività o Qualità dell'utilizzo degli strumenti in diverse versioni dell'agente o intervalli di tempo.
• Stato zero:per gli agenti senza monitoraggio online attivo, questa visualizzazione identifica le lacune nella copertura e fornisce un invito all'azione per iniziare la valutazione.

Visualizzare i risultati della valutazione con l'SDK

Puoi accedere ai risultati della valutazione a livello di programmazione utilizzando l'SDK Agent Platform. L'SDK fornisce visualizzazioni interattive integrate per gli ambienti Colab e Jupyter Notebook che mostrano sia le metriche di riepilogo aggregate sia i risultati dettagliati per caso.

Dopo aver eseguito una valutazione, chiama .show() sull'oggetto risultato per visualizzare un report interattivo direttamente nel notebook:

from vertexai import evals, types

# Run an evaluation
result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.FINAL_RESPONSE_QUALITY,
        types.RubricMetric.TOOL_USE_QUALITY,
        types.RubricMetric.HALLUCINATION,
        types.RubricMetric.SAFETY,
    ],
)

# Visualize aggregate and per-case results in your notebook
result.show()

La visualizzazione include:

• Metriche di riepilogo:punteggi aggregati in tutti i casi di valutazione, inclusi il punteggio medio e il tasso di superamento per ogni metrica.
• Risultati per caso:i singoli punteggi dei casi di valutazione che puoi espandere per esaminare i risultati dettagliati.

L'esempio seguente mostra le metriche di riepilogo di result.show():

Puoi espandere i singoli casi di valutazione per visualizzare i punteggi per metrica, i verdetti della griglia di valutazione e le motivazioni:

Interpretare i risultati della valutazione

Le metriche predefinite restituiscono risultati in due formati, a seconda del tipo di metrica:

• Le metriche della rubrica adattiva generano automaticamente rubriche in base alla configurazione dell'agente e al prompt dell'utente. Ogni rubrica riceve un verdetto individuale Superato o Non superato con una motivazione in linguaggio naturale che spiega il ragionamento del modello LLM del giudice. Il punteggio complessivo rappresenta il tasso di superamento, ovvero la proporzione di rubriche che hanno ricevuto un giudizio Superato.
• Le metriche della rubrica statica utilizzano un insieme fisso di criteri di valutazione. Ad esempio, Allucinazione segmenta la risposta in affermazioni atomiche e verifica ciascuna in base alle prove di utilizzo dello strumento. Controlli di sicurezza per PII, incitamento all'odio, contenuti pericolosi e altre violazioni delle norme. Queste metriche restituiscono un singolo punteggio numerico (da 0 a 1).

Identificare e classificare per priorità gli errori

Dopo aver esaminato i risultati della valutazione, il passaggio successivo consiste nell'identificare i pattern di errore sistemici e assegnarli in ordine di priorità per migliorare l'agente. Agent Platform fornisce l'analisi automatica delle perdite, che analizza gli indicatori di superamento o mancato superamento delle metriche basate su rubriche, classifica gli errori in pattern di perdita predefiniti e li raggruppa in cluster semantici. In questo modo, non solo potrai capire che l'agente non è riuscito a completare l'operazione, ma anche perché e come.

Accedere ai cluster di errori nella console

1. Vai alla pagina Agent Platform > Agenti > Valutazione.
2. Seleziona la scheda Valutazioni.
3. Fai clic sul nome di un'esecuzione di valutazione completata per aprire il report.
4. Se la valutazione ha rilevato cluster, questi vengono visualizzati nella sezione Cluster di errori del report.

Generare cluster di errori con l'SDK

Puoi anche generare cluster di errori a livello di programmazione utilizzando il metodo generate_loss_clusters:

# Generate failure clusters from evaluation results
loss_clusters = client.evals.generate_loss_clusters(
    eval_result=result,
)

# Visualize the loss pattern analysis in your notebook
loss_clusters.show()

L'esempio seguente mostra l'analisi del pattern di perdita di loss_clusters.show():

Tassonomie dei pattern di perdita

L'analisi automatica delle perdite classifica ogni guasto in uno o più pattern di perdita predefiniti. Questi pattern sono progettati per essere concreti e attuabili, e corrispondono direttamente ad aree specifiche dell'agente che puoi migliorare.

Esistono due tassonomie predefinite, ognuna allineata a una metrica specifica:

Tassonomia del successo delle attività dell'agente

Questa tassonomia viene utilizzata con la metrica Successo dell'attività multi-turno dell'agente (multi_turn_task_success_v1). Copre i comportamenti errati di alto livello dell'agente in termini di allucinazioni, rispetto delle istruzioni, chiamata dello strumento, gestione dell'output dello strumento e qualità dello strumento:

Categoria	Pattern di perdita	Descrizione
Allucinazione	Allucinazione dell'azione	L'agente afferma di aver completato un'azione senza eseguire la chiamata allo strumento necessaria.
	Allucinazione di informazioni mancanti	L'agente inventa un dettaglio (ad esempio un valore, un fatto o una data) non presente nella query dell'utente o nell'output dello strumento.
	Allucinazione di strumento o funzionalità	L'agente afferma di avere uno strumento o una funzionalità che non possiede.
Segui le istruzioni	Violazione del vincolo	L'agente esegue l'attività, ma viola i vincoli espliciti dell'utente (ad esempio regole di formattazione o vincoli negativi).
	Azione futile (under-punting)	L'agente esegue un'azione irrilevante anziché dichiarare che l'attività è impossibile con gli strumenti disponibili.
	Esecuzione incompleta	L'agente completa parzialmente un'attività, ma si interrompe prematuramente o chiede un'autorizzazione non necessaria per i passaggi richiesti esplicitamente.
	Over-Punting	L'agente rifiuta un'attività sostenendo di non disporre di uno strumento o di una funzionalità che in realtà possiede.
Chiamata allo strumento	Selezione dello strumento errata	L'agente seleziona lo strumento sbagliato tra le opzioni disponibili.
	Parametri dello strumento semanticamente errati	La chiamata allo strumento è valida dal punto di vista sintattico, ma contiene un errore logico o semantico nei valori dei parametri.
	Chiamata allo strumento sintatticamente errata	La chiamata allo strumento presenta errori di sintassi, parametri obbligatori mancanti o valori di argomenti non validi.
Gestione dell'output dello strumento	Elaborazione dell'output dello strumento errata	L'agente riceve un output dello strumento valido, ma estrae, elabora o interpreta le informazioni in modo impreciso.
Qualità dello strumento	Output dello strumento insufficiente	Lo strumento viene eseguito correttamente, ma restituisce dati insufficienti o mancanti necessari per procedere con l'agente.
	Guasto dello strumento	Lo strumento non funziona a causa di problemi di infrastruttura come errori di autenticazione, timeout o errori interni.

Tassonomia della qualità dell'utilizzo dello strumento

Questa tassonomia viene utilizzata con la metrica Qualità dell'utilizzo dello strumento multi-turno dell'agente (multi_turn_tool_use_quality_v1). Si concentra in particolare sulla correttezza delle chiamate di strumenti e sulla gestione delle risposte degli strumenti:

Categoria	Pattern di perdita	Descrizione
Allucinazione	Allucinazione del valore del parametro	L'agente inventa un valore specifico per un parametro che non è stato fornito dall'utente o non può essere derivato dal contesto.
	Allucinazione dello strumento	L'agente tenta di chiamare una funzione che non esiste nel set di strumenti definito.
Chiamata allo strumento	Impossibile impostare il parametro	L'agente omette un parametro necessario per soddisfare i vincoli dell'utente, impostando un valore predefinito non previsto.
	Tipo di dati del parametro non corretto	L'agente fornisce un valore del tipo di dati errato per un parametro (ad esempio una stringa quando è richiesto un numero intero).
	Mappatura dei parametri non corretta	L'agente assegna un valore al parametro errato (ad esempio, scambia le date di inizio e fine).
	Valore del parametro errato	L'agente fornisce un valore parametro logicamente o fattualmente errato oppure non applica le trasformazioni dei dati necessarie.
	Selezione dello strumento errata	L'agente seleziona la funzione sbagliata dal set di strumenti disponibile.
	Sintassi della chiamata allo strumento non valida	L'agente genera una chiamata di funzione con un errore di sintassi che impedisce l'analisi o l'esecuzione.
	Parametro inesistente	L'agente include un argomento di parametro non definito nella firma dello strumento.
	Omissione della chiamata allo strumento obbligatoria	L'agente non riesce a eseguire una funzione necessaria, rispondendo direttamente, saltando una parte di una richiesta composta o un passaggio preliminare.
	Under-Punting	L'agente forza una chiamata allo strumento quando dovrebbe rispondere con un linguaggio naturale (ad esempio, chiedendo chiarimenti o rifiutando una richiesta fuori ambito).
Risposta dello strumento	Risposta dello strumento non pertinente	Lo strumento viene eseguito correttamente, ma restituisce dati non pertinenti alla query specifica dell'utente.
	Errore dello strumento	Lo strumento restituisce un errore esplicito o uno stato di errore a causa di un problema esterno (ad esempio un'interruzione dell'API o autorizzazioni non valide).

Flusso di lavoro di triage consigliato

Utilizza il seguente flusso di lavoro per eseguire il triage sistematico degli errori di valutazione:

1. Inizia con le metriche di riepilogo per identificare le metriche con il punteggio più basso nel set di dati di valutazione.
2. Esamina in dettaglio i risultati per caso per trovare i casi di valutazione specifici non riusciti.
3. Genera cluster di errori per identificare i pattern di perdita sistemici tra gli errori.
4. Esamina in dettaglio le tracce per trovare la svolta o la chiamata allo strumento esatta in cui si è verificato l'errore. Nella console, vai a Agent Platform > Agenti > Deployment, seleziona l'agente e apri la scheda Tracce. Seleziona una traccia per visualizzare la cronologia completa della conversazione e la sequenza esatta di input del modello, chiamate di strumenti e risposte.
5. Identifica la causa principale: utilizza la categoria del pattern di perdita per determinare se il problema riguarda il prompt, la configurazione dello strumento o i dati.
6. Applica una correzione mirata alle istruzioni di sistema, alle definizioni degli strumenti o agli esempi few-shot dell'agente.
7. Esegui di nuovo la valutazione e confronta i punteggi per verificare il miglioramento.