Prima di iniziare
Per visualizzare e analizzare i risultati della valutazione, assicurati di avere:
- Eseguito 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 di diagnostica 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 monitor online
Per gli agenti con monitor online attivi, puoi visualizzare le tendenze aggregate del rendimento nella dashboard:
- Nella Google Cloud console, vai alla pagina Agent Platform > Agenti.
- Nel menu di navigazione a sinistra, seleziona Deployment.
Seleziona l'agente.
Fai clic sulla scheda Dashboard e seleziona la sottosezione Valutazione.
- Tendenze del rendimento:visualizza come cambiano i punteggi per metriche come Successo dell'attività o Qualità dell'utilizzo dello strumento in diverse versioni dell'agente o periodi di tempo.
- Stato zero:per gli agenti senza monitor online attivi, questa visualizzazione identifica le lacune di 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 la percentuale di superamento per ogni metrica.
- Risultati per caso:punteggi dei singoli 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 i risultati in due formati a seconda del tipo di metrica:
- Le metriche della griglia di valutazione adattiva generano automaticamente le griglie di valutazione in base alla configurazione dell'agente e al prompt dell'utente. Ogni griglia di valutazione riceve un verdetto Superato o Non superato con una motivazione in linguaggio naturale che spiega il ragionamento del modello linguistico di grandi dimensioni del giudice. Il punteggio complessivo rappresenta la percentuale di superamento, ovvero la proporzione di griglie di valutazione che hanno ricevuto un verdetto Superato.
- Le metriche della griglia di valutazione 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 assegnare la priorità agli errori
Dopo aver esaminato i risultati della valutazione, il passaggio successivo consiste nell'identificare i pattern di errore sistemici e assegnare loro la priorità per migliorare l'agente. Agent Platform fornisce l'analisi automatica delle perdite, che analizza i segnali di superamento o non superamento delle metriche basate su griglie di valutazione, classifica gli errori in pattern di perdita predefiniti e li raggruppa in cluster semantici. In questo modo puoi capire non solo che l'agente non è riuscito, ma anche perché e come non è riuscito.
Accedere ai cluster di errori nella console
- Vai alla pagina Agent Platform > Agenti > Valutazione.
- Seleziona la scheda Valutazioni.
- Fai clic sul nome di un'esecuzione di valutazione completata per aprire il report.
- 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 dei pattern di perdita di loss_clusters.show():
Tassonomie dei pattern di perdita
L'analisi automatica delle perdite classifica ogni errore in uno o più pattern di perdita predefiniti. Questi pattern sono progettati per essere concreti e attuabili, mappando direttamente aree specifiche dell'agente che puoi migliorare.
Esistono due tassonomie predefinite, ognuna allineata a una metrica specifica:
Tassonomia del successo dell'attività dell'agente
Questa tassonomia viene utilizzata con la metrica Successo dell'attività multi-turno dell'agente (multi_turn_task_success_v1). Copre gli errori comportamentali di alto livello dell'agente in termini di allucinazione, rispetto delle istruzioni, chiamata allo 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 dello strumento o della funzionalità | L'agente afferma di avere uno strumento o una funzionalità che non possiede. | |
| Secondo 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 inutile (sottopunting) | L'agente intraprende 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 in modo esplicito. | |
| Over-Punting | L'agente rifiuta un'attività, sostenendo di non avere uno strumento o 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 è sintatticamente valida, 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 dati necessari per consentire all'agente di procedere. |
| Errore dello strumento | Lo strumento non funziona a causa di problemi di infrastruttura come errori di autenticazione errori, 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 della chiamata allo strumento e sulla gestione della risposta dello strumento:
| 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 suo set di strumenti definito. | |
| Chiamata allo strumento | Impossibile impostare il parametro | L'agente omette un parametro necessario per soddisfare i vincoli dell'utente, utilizzando un valore predefinito non previsto. |
| Tipo di dati del parametro errato | 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 errata | L'agente assegna un valore al parametro sbagliato (ad esempio scambiando 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 parametro non definito nella firma dello strumento. | |
| Omissione della chiamata allo strumento obbligatoria | L'agente non esegue una funzione necessaria, rispondendo direttamente, saltando una parte di una richiesta composta o saltando un passaggio preliminare. | |
| Sottopunting | L'agente forza una chiamata allo strumento quando dovrebbe rispondere in 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). |
Workflow di assegnazione della priorità consigliato
Utilizza il seguente workflow per assegnare sistematicamente la priorità agli errori di valutazione:
- Inizia con le metriche di riepilogo per identificare le metriche con il punteggio più basso nel set di dati di valutazione.
- Esamina in dettaglio i risultati per caso per trovare i casi di valutazione specifici che non sono riusciti.
- Genera cluster di errori per identificare i pattern di perdita sistemici tra gli errori.
- Esamina le tracce per trovare il turno 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 allo strumento e risposte.
- Identifica la causa principale: utilizza la categoria del pattern di perdita per determinare se il problema è un problema di prompt, un problema di configurazione dello strumento o un problema di dati.
- Applica una correzione mirata alle istruzioni di sistema, alle definizioni degli strumenti o agli esempi few-shot dell'agente.
- Esegui di nuovo la valutazione e confronta i punteggi per verificare il miglioramento.