Tutorial: esegui la valutazione utilizzando il client GenAI nell'SDK Vertex AI

Questa pagina mostra come valutare i modelli e le applicazioni di AI generativa in una serie di casi d'uso utilizzando il client GenAI nell'SDK Vertex AI.

Il client GenAI nell'SDK Vertex AI per il servizio di valutazione dell'AI generativa ti consente di misurare le prestazioni di prompt, foundation model e agenti AI complessi in base ai criteri piรน pertinenti. Puoi valutare contemporaneamente un numero qualsiasi di candidati per perfezionare i prompt, selezionare il modello migliore o eseguire l'iterazione su agenti complessi.

Con il client GenAI nell'SDK Vertex AI puoi:

  • Confronta piรน modelli o configurazioni affiancati in una singola esecuzione, utilizzando i calcoli del tasso di vittoria per guidare le tue decisioni.

  • Utilizza il supporto integrato per valutare e confrontare i modelli di terze parti piรน diffusi senza integrazioni complesse.

  • Gestisci set di dati di grandi dimensioni in modo piรน efficiente e scarica le attivitร  di valutazione su larga scala utilizzando la valutazione batch asincrona.

Esempio end-to-end

Il client GenAI nell'SDK Vertex AI utilizza un flusso di lavoro in due passaggi: generazione delle risposte del modello e valutazione delle risposte. Il seguente esempio end-to-end mostra come funziona il client GenAI nell'SDK Vertex AI:

  1. Installa l'SDK Vertex AI Python:

    pip install --upgrade google-cloud-aiplatform[evaluation]

  2. Prepara il set di dati di valutazione:

    import pandas as pd
from vertexai import Client, types

client = Client(project="your-project-id", location="us-central1")

prompts_df = pd.DataFrame({"prompt": ["How does AI work?"]})

  3. Esegui la valutazione:

    # Evaluating a single model.
eval_dataset = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df,
)
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)
eval_result.show()

  4. Confrontare piรน candidati:

    # Comparing multiple candidates.
candidate_1 = client.evals.run_inference(
    model="gemini-2.0-flash", src=prompts_df
)
candidate_2 = client.evals.run_inference(
    model="gemini-2.5-flash", src=prompts_df
)
comparison_result = client.evals.evaluate(
    dataset=[candidate_1, candidate_2],
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)
comparison_result.show()

Definisci la metrica

Definisci le metriche come metriche basate su LLM o metriche basate su calcolo.

Metriche basate su LLM

Le metriche basate su LLM utilizzano un modello linguistico di grandi dimensioni (LLM) come "giudice" per valutare criteri sfumati come lo stile o la qualitร  della scrittura, che sono difficili da misurare solo con gli algoritmi.

Utilizzare le metriche gestite basate su rubrica

Il client GenAI nell'SDK Vertex AI fornisce una serie di metriche basate su modelli pronte all'uso, come GENERAL_QUALITY, SAFETY e INSTRUCTION_FOLLOWING. Puoi accedervi tramite il corso RubricMetric. Le definizioni delle metriche basate su rubriche gestite vengono caricate on demand da una libreria centralizzata per creare coerenza tra le versioni delle metriche basate su rubriche.

# Assumes 'eval_dataset' is an EvaluationDataset object created via run_inference()

eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
    ]
)

Per creare risultati coerenti nelle diverse versioni dell'SDK, puoi bloccare una metrica su una versione specifica. Per impostazione predefinita, viene utilizzata l'ultima versione.

# Pin to a specific version of a pre-built metric
instruction_following_v1 = types.RubricMetric.INSTRUCTION_FOLLOWING(version='v1')

Personalizzare le metriche LLM

Per i casi d'uso che richiedono criteri specializzati, puoi definire la tua metrica basata su LLM istanziando la classe LLMMetric. In questo modo avrai il pieno controllo del modello di prompt di valutazione, del modello di giudice e di altri parametri.

La classe helper MetricPromptBuilder crea un modello di prompt strutturato per il modello giudice consentendoti di definire separatamente instruction, criteria e rating_scores.

# Define a custom metric to evaluate language simplicity
simplicity_metric = types.LLMMetric(
    name='language_simplicity',
    prompt_template=types.MetricPromptBuilder(
        instruction="Evaluate the story's simplicity for a 5-year-old.",
        criteria={
            "Vocabulary": "Uses simple words.",
            "Sentences": "Uses short sentences.",
        },
        rating_scores={
            "5": "Excellent: Very simple, ideal for a 5-year-old.",
            "4": "Good: Mostly simple, with minor complex parts.",
            "3": "Fair: Mix of simple and complex; may be challenging for a 5-year-old.",
            "2": "Poor: Largely too complex, with difficult words/sentences.",
            "1": "Very Poor: Very complex, unsuitable for a 5-year-old."
        }
    )
)
# Use the custom metric in an evaluation
eval_result = client.evals.evaluate(
    dataset=inference_results,
    metrics=[simplicity_metric]
)

Metriche basate su calcolo e funzioni personalizzate

Le metriche basate sul calcolo confrontano matematicamente l'output di un modello con un dato di fatto o un riferimento. Queste metriche, calcolate con il codice utilizzando la classe base Metric, supportano algoritmi predefiniti basati su calcoli come exact_match, bleu e rouge_1. Per utilizzare una metrica basata sul calcolo, crea un'istanza della classe Metric con il nome della metrica. La metrica richiede una colonna reference nel set di dati per il confronto.

eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.Metric(name='exact_match'),
        types.Metric(name='bleu'),
        types.Metric(name='rouge_1'),
    ]
)

Implementare una metrica di funzione personalizzata

Per un controllo completo, puoi anche implementare una logica di valutazione personalizzata passando una funzione Python personalizzata al parametro custom_function. Il client GenAI nell'SDK Vertex AI esegue questa funzione per ogni riga del set di dati.

# Define a custom function to check for the presence of a keyword
def contains_keyword(instance: dict) -> dict:
    keyword = "magic"
    response_text = instance.get("response", "")
    score = 1.0 if keyword in response_text.lower() else 0.0
    return {"score": score}

keyword_metric = types.Metric(
    name="keyword_check",
    custom_function=contains_keyword
)


eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[keyword_metric]
)

Prepara il set di dati di valutazione

Il client GenAI nell'SDK Vertex AI rileva e gestisce automaticamente diversi formati di dati comuni. Ciรฒ significa che spesso puoi utilizzare i tuoi dati cosรฌ come sono senza dover eseguire conversioni manuali, sia che tu stia generando nuove risposte con run_inference sia che tu stia valutando quelle esistenti con evaluate.

Il client GenAI nell'SDK Vertex AI supporta i seguenti formati:

  • DataFrame Pandas (formato appiattito)

    Per valutazioni semplici, puoi utilizzare un pandas.DataFrame. Il client GenAI nell'SDK Vertex AI cerca nomi di colonne comuni come prompt, response e reference. Questo formato รจ completamente compatibile con le versioni precedenti.

    import pandas as pd

# Simple DataFrame with prompts and ground truth references
prompts_df = pd.DataFrame({
    "prompt": [
        "What is the capital of France?",
        "Who wrote 'Hamlet'?",
    ],
    "reference": [
        "Paris",
        "William Shakespeare",
    ]
})

# Generate responses using the DataFrame as a source
inference_results = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df
)
inference_results.show()

  • Formato di previsione batch di Gemini

    Puoi utilizzare direttamente l'output di un job di previsione batch Vertex AI, che in genere sono file JSONL archiviati in Cloud Storage, in cui ogni riga contiene un oggetto request e response. Il client GenAI nell'SDK Vertex AI analizza automaticamente questa struttura per fornire l'integrazione con altri servizi Vertex AI.

    Esempio di una singola riga in un file jsonl:

    {"request": {"contents": [{"role": "user", "parts": [{"text": "Why is the sky blue?"}]}]}, "response": {"candidates": [{"content": {"role": "model", "parts": [{"text": "The sky appears blue to the human eye as a result of a phenomenon known as Rayleigh scattering."}]}}]}}

    Puoi quindi valutare direttamente le risposte pregenerate da un job batch:

    # Cloud Storage path to your batch prediction output file
batch_job_output_uri = "gs://path/to/your/batch_output.jsonl"

# Evaluate the results directly from Cloud Storage
eval_result = client.evals.evaluate(
    dataset=batch_job_output_uri,
    metrics=[
        types.RubricMetric.COHERENCE,
        types.RubricMetric.FLUENCY,
    ]
)
eval_result.show()

  • Formato di completamento della chat di OpenAI

    Per la valutazione o il confronto con modelli di terze parti, il client GenAI nell'SDK Vertex AI supporta il formato di completamento della chat di OpenAI. Puoi fornire un set di dati in cui ogni riga รจ un oggetto JSON strutturato come una richiesta API OpenAI. Il client GenAI nell'SDK Vertex AI rileva automaticamente questo formato.

    Un esempio di una singola riga in questo formato:

    {"request": {"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What's the capital of France?"}], "model": "gpt-4o"}}

    Puoi utilizzare questi dati per generare risposte da un modello di terze parti e valutarle:

    # Ensure your third-party API key is set
# e.g., os.environ['OPENAI_API_KEY'] = 'Your API Key'

openai_request_uri = "gs://path/to/your/openai_requests.jsonl"

# Generate responses using a LiteLLM-supported model string
openai_responses = client.evals.run_inference(
    model="gpt-4o",
    src=openai_request_uri,
)

# The resulting dataset can then be evaluated
eval_result = client.evals.evaluate(
    dataset=openai_responses,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.FLUENCY,
    ]
)

eval_result.show()

Esegui valutazione

Il client GenAI nell'SDK Vertex AI utilizza il seguente processo basato sul client per l'esecuzione delle valutazioni:

  1. run_inference(): genera risposte dal modello per un determinato insieme di prompt.

  2. evaluate(): Calcola le metriche sulle risposte generate.

eval_dataset = client.evals.run_inference(
    model="gemini-2.5-flash",
src="gs://vertex-evaluation-llm-dataset-us-central1/genai_eval_sdk/test_prompts.jsonl",
)
eval_dataset.show()


eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.QUESTION_ANSWERING_QUALITY,
        types.Metric(name='bleu'),
        types.Metric(name='rouge_1'),
    ]
)
eval_result.show()

Per analizzare le prestazioni di piรน modelli o sistemi di AI in una singola valutazione, genera una risposta per ogni candidato e trasmettila in un elenco al metodo evaluate():

inference_result_1 = client.evals.run_inference(
    model="gemini-2.0-flash",
    src=prompts_df,
)
inference_result_2 = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df,
)

# Compare the responses against each other
comparison_result = client.evals.evaluate(
    dataset=[inference_result_1, inference_result_2],
    metrics=[
        types.RubricMetric.TEXT_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
    ]
)

comparison_result.show()

Valutazione asincrona e su larga scala

Per i set di dati di grandi dimensioni, il client GenAI nell'SDK Vertex AI fornisce un metodo di valutazione batch asincrono a esecuzione prolungata. Questa opzione รจ ideale per gli scenari in cui non hai bisogno di risultati immediati e vuoi eseguire l'offload del calcolo.

Il metodo batch_evaluate() restituisce un oggetto operazione di cui puoi eseguire il polling per monitorarne l'avanzamento. I parametri sono compatibili con il metodo evaluate().

GCS_DEST_BUCKET = "gs://your-gcs-bucket/batch_eval_results/"

inference_result_saved = client.evals.run_inference(
    model="gemini-2.0-flash",
    src=prompts_df,
    config={'dest': GCS_DEST_BUCKET}
)
print(f"Eval dataset uploaded to: {inference_result_saved.gcs_source}")

batch_eval_job  = client.evals.batch_evaluate(
   dataset = inference_result_saved,
   metrics = [
        types.RubricMetric.TEXT_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
        types.RubricMetric.FLUENCY,
        types.Metric(name='bleu'),
    ],
   dest=GCS_DEST_BUCKET
)

Valutazione di modelli di terze parti

Puoi utilizzare il client GenAI nell'SDK Vertex AI per valutare e confrontare i modelli di fornitori come OpenAI passando la stringa del nome del modello al metodo run_inference. Il client GenAI nell'SDK Vertex AI utilizza la libreria litellm per chiamare l'API del modello.

Assicurati di impostare la chiave API richiesta come variabile di ambiente (OPENAI_API_KEY):

import os

# Set your third-party model API key
os.environ['OPENAI_API_KEY'] = 'YOUR_OPENAI_API_KEY'

# Run inference on an OpenAI model
gpt_response = client.evals.run_inference(
    model='gpt-4o',
    src=prompt_df
)

# You can now evaluate the responses
eval_result = client.evals.evaluate(
    dataset=gpt_response,
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)

eval_result.show()

Visualizzazione

Il client GenAI nell'SDK Vertex AI ti consente di visualizzare i risultati direttamente nel tuo ambiente di sviluppo, ad esempio un notebook Colab o Jupyter. Il metodo .show(), disponibile sia sugli oggetti EvaluationDataset sia su quelli EvaluationResult, esegue il rendering di un report HTML interattivo per l'analisi.

Visualizzare i risultati dell'inferenza

Dopo aver generato risposte con run_inference(), puoi chiamare .show() sull'oggetto EvaluationDataset risultante per esaminare gli output del modello insieme ai prompt e ai riferimenti originali. Ciรฒ รจ utile per un rapido controllo della qualitร  prima di eseguire una valutazione completa.

# First, run inference to get an EvaluationDataset
gpt_response = client.evals.run_inference(
    model='gpt-4o',
    src=prompt_df
)

# Now, visualize the inference results
gpt_response.show()

Viene visualizzata una tabella con ogni prompt, il riferimento corrispondente (se fornito) e la risposta appena generata.

Visualizzare i risultati dell'inferenza

Visualizzare i report sulla valutazione

Quando chiami .show() su un oggetto EvaluationResult, viene visualizzato un report con due sezioni principali:

  • Metriche riepilogative: una visualizzazione aggregata di tutte le metriche, che mostra il punteggio medio e la deviazione standard nell'intero set di dati.

  • Risultati dettagliati: una suddivisione caso per caso, che ti consente di esaminare il prompt, il riferimento, la risposta del candidato e il punteggio e la spiegazione specifici per ogni metrica.

# First, run an evaluation on a single candidate
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.RubricMetric.TEXT_QUALITY]
)

# Visualize the detailed evaluation report
eval_result.show()

Report sulla valutazione

Il formato del report si adatta a seconda che tu stia valutando un singolo candidato o confrontando piรน candidati. Per una valutazione multicandidato, il report fornisce una visualizzazione affiancata e include i calcoli del tasso di vittoria/pareggio nella tabella riepilogativa.

Per tutti i report, puoi espandere una sezione Visualizza JSON non elaborato per esaminare i dati di qualsiasi prompt o risposta strutturati.

Confronto dettagliato

Passaggi successivi