Esegui una valutazione

Puoi utilizzare il modulo Gen AI Evaluation dell'SDK Agent Platform per Python per valutare in modo programmatico i tuoi modelli linguistici e le tue applicazioni generative con l'API Gen AI evaluation service. Questa pagina mostra come eseguire le valutazioni con l'SDK Agent Platform. Tieni presente che le valutazioni su larga scala sono disponibili solo tramite l'API REST.

Prima di iniziare

Per iniziare a eseguire le valutazioni, completa i seguenti prerequisiti.

Installa l'SDK Agent Platform

Per installare il modulo di valutazione AI generativa dall'SDK Agent Platform per Python, esegui questo comando:

!pip install -q google-cloud-aiplatform[evaluation]

Per saperne di più, consulta Installa l'SDK Agent Platform per Python.

Autentica l'SDK Agent Platform

Dopo aver installato l'SDK Agent Platform per Python, devi eseguire l'autenticazione. I seguenti argomenti spiegano come eseguire l'autenticazione con l'SDK Agent Platform se lavori in locale e se lavori in Colaboratory:

  • Se lo sviluppo avviene in locale, configura le Credenziali predefinite dell'applicazione (ADC) nel tuo ambiente locale:

    1. Installa Google Cloud CLI, quindi inizializzala eseguendo questo comando:

      gcloud init

    2. Crea credenziali di autenticazione locali per il tuo Account Google:

      gcloud auth application-default login

      Viene visualizzata una schermata di accesso. Dopo aver eseguito l'accesso, le tue credenziali vengono archiviate nel file delle credenziali locali utilizzato da ADC. Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale.

  • Se lavori in Colaboratory, esegui questo comando in una cella di Colab per l'autenticazione:

    from google.colab import auth
auth.authenticate_user()

    Questo comando apre una finestra in cui puoi completare l'autenticazione.

Informazioni sugli account di servizio

Il service account viene utilizzato dal servizio di valutazione dell'AI generativa per ottenere previsioni dall'API Gemini in Gemini Enterprise Agent Platform per le metriche di valutazione basate su modelli. Il provisioning di questo account di servizio viene eseguito automaticamente alla prima richiesta al servizio di valutazione dell'AI generativa.

Nome Descrizione Indirizzo email Ruolo
Agent Platform Rapid Eval Service Agent Il account di servizio utilizzato per ottenere le previsioni per la valutazione basata su modelli. service-PROJECT_NUMBER@gcp-sa-vertex-eval. roles/aiplatform.rapidevalServiceAgent

Le autorizzazioni associate all'agente di servizio di valutazione rapida sono:

Ruolo Autorizzazioni
Vertex AI Rapid Eval Service Agent (roles/aiplatform.rapidevalServiceAgent) aiplatform.endpoints.predict

Esegui la valutazione

Utilizza la classe EvalTask per eseguire valutazioni per i seguenti casi d'uso:

Classe EvalTask

La classe EvalTask ti aiuta a valutare modelli e applicazioni in base ad attività specifiche. Per fare confronti equi tra i modelli generativi, in genere è necessario valutare ripetutamente vari modelli e template di prompt rispetto a un set di dati di valutazione fisso utilizzando metriche specifiche. È anche importante valutare più metriche contemporaneamente all'interno di una singola esecuzione della valutazione.

EvalTask si integra anche con Experiments su Gemini Enterprise Agent Platform per aiutarti a monitorare le configurazioni e i risultati di ogni esecuzione della valutazione. Gli esperimenti su Gemini Enterprise Agent Platform aiutano a gestire e interpretare i risultati della valutazione, consentendoti di prendere decisioni informate.

L'esempio seguente mostra come creare un'istanza della classe EvalTask ed eseguire una valutazione:

from vertexai.evaluation import (
    EvalTask,
    PairwiseMetric,
    PairwiseMetricPromptTemplate,
    PointwiseMetric,
    PointwiseMetricPromptTemplate,
    MetricPromptTemplateExamples,
)

eval_task = EvalTask(
    dataset=DATASET,
    metrics=[METRIC_1, METRIC_2, METRIC_3],
    experiment=EXPERIMENT_NAME,
)

eval_result = eval_task.evaluate(
    model=MODEL,
    prompt_template=PROMPT_TEMPLATE,
    experiment_run=EXPERIMENT_RUN,
)

Esegui la valutazione con metriche basate su modelli

Per le metriche basate su modelli, utilizza le classi PointwiseMetric e PairwiseMetric per definire metriche personalizzate in base ai tuoi criteri specifici. Esegui le valutazioni utilizzando le seguenti opzioni:

Utilizza esempi di metriche basate su modelli

Puoi utilizzare direttamente la costante integrata Metric Prompt Template Examples all'interno dell'SDK Agent Platform. In alternativa, modificali e incorporali nell'interfaccia di definizione delle metriche in formato libero.

Per l'elenco completo degli esempi di template di prompt delle metriche che coprono la maggior parte dei casi d'uso principali, consulta Template di prompt delle metriche.

Console

Quando esegui le valutazioni in un notebook Colab Enterprise, puoi accedere ai template di prompt delle metriche direttamente dalla console Google Cloud .

  1. Fai clic sul link del notebook di Gen AI evaluation service che preferisci.

  2. Il notebook si apre in GitHub. Fai clic su Apri in Colab Enterprise. Se una finestra di dialogo ti chiede di abilitare le API, fai clic su Abilita.

  3. Fai clic sull'icona Valutazione dell'AI generativa nella barra laterale. Viene visualizzato il riquadro Modelli di metriche predefiniti.

  4. Seleziona le metriche Puntuale o A coppie.

  5. Fai clic sulla metrica che vuoi utilizzare, ad esempio Fluency. Viene visualizzato l'esempio di codice per la metrica.

  6. Fai clic su Copia per copiare l'esempio di codice. Se vuoi, fai clic su Personalizza per modificare i campi preimpostati per la metrica.

  7. Incolla l'esempio di codice nel tuo notebook.

SDK Agent Platform

L'esempio seguente dell'SDK Agent Platform mostra come utilizzare la classe MetricPromptTemplateExamples per definire le metriche:

# View all the available examples of model-based metrics
MetricPromptTemplateExamples.list_example_metric_names()

# Display the metric prompt template of a specific example metric
print(MetricPromptTemplateExamples.get_prompt_template('fluency'))

# Use the pre-defined model-based metrics directly
eval_task = EvalTask(
    dataset=EVAL_DATASET,
    metrics=[MetricPromptTemplateExamples.Pointwise.FLUENCY],
)

eval_result = eval_task.evaluate(
    model=MODEL,
)

Utilizza un'interfaccia basata su modelli per le metriche basate su modelli

Personalizza le metriche compilando campi come Criteria e Rating Rubrics utilizzando le classi PointwiseMetricPromptTemplate e PairwiseMetricPromptTemplate nell'SDK Agent Platform. Ad alcuni campi, come Instruction, viene assegnato un valore predefinito se non fornisci un input.

Facoltativamente, puoi specificare input_variables, ovvero un elenco di campi di immissione utilizzati dal template di prompt delle metriche per generare risultati di valutazione basati sul modello. Per impostazione predefinita, la colonna response del modello è inclusa per le metriche puntuali, mentre le colonne response e baseline_model_response del modello candidato sono incluse per le metriche di confronto a coppie.

Per ulteriori informazioni, consulta la sezione "Struttura un template di prompt delle metriche" in Template di prompt delle metriche.

# Define a pointwise metric with two custom criteria
custom_text_quality = PointwiseMetric(
    metric="custom_text_quality",
    metric_prompt_template=PointwiseMetricPromptTemplate(
        criteria={
          "fluency": "Sentences flow smoothly and are easy to read, avoiding awkward phrasing or run-on sentences. Ideas and sentences connect logically, using transitions effectively where needed.",
          "entertaining": "Short, amusing text that incorporates emojis, exclamations and questions to convey quick and spontaneous communication and diversion.",
        },
        rating_rubric={
          "1": "The response performs well on both criteria.",
          "0": "The response is somewhat aligned with both criteria",
          "-1": "The response falls short on both criteria",
        },
        input_variables=["prompt"],
    ),
)

# Display the serialized metric prompt template
print(custom_text_quality.metric_prompt_template)

# Run evaluation using the custom_text_quality metric
eval_task = EvalTask(
    dataset=EVAL_DATASET,
    metrics=[custom_text_quality],
)
eval_result = eval_task.evaluate(
    model=MODEL,
)

Utilizza l'interfaccia SDK in formato libero per le metriche basate su modelli

Per una maggiore flessibilità nella personalizzazione del template di prompt delle metriche, puoi definire una metrica direttamente utilizzando l'interfaccia in formato libero, che accetta un input di stringa diretto.

# Define a pointwise multi-turn chat quality metric
pointwise_chat_quality_metric_prompt = """Evaluate the AI's contribution to a meaningful conversation, considering coherence, fluency, groundedness, and conciseness.
 Review the chat history for context. Rate the response on a 1-5 scale, with explanations for each criterion and its overall impact.

# Conversation History
{history}

# Current User Prompt
{prompt}

# AI-generated Response
{response}
"""

freeform_multi_turn_chat_quality_metric = PointwiseMetric(
    metric="multi_turn_chat_quality_metric",
    metric_prompt_template=pointwise_chat_quality_metric_prompt,
)

# Run evaluation using the freeform_multi_turn_chat_quality_metric metric
eval_task = EvalTask(
    dataset=EVAL_DATASET,
    metrics=[freeform_multi_turn_chat_quality_metric],
)
eval_result = eval_task.evaluate(
    model=MODEL,
)

Valuta un modello di traduzione

Per valutare il modello di traduzione, puoi specificare BLEU, MetricX o COMET come metriche di valutazione quando utilizzi l'SDK Agent Platform.

#Prepare the dataset for evaluation.
sources = [
    "Dem Feuer konnte Einhalt geboten werden",
    "Schulen und Kindergärten wurden eröffnet.",
]

responses = [
    "The fire could be stopped",
    "Schools and kindergartens were open",
]

references = [
    "They were able to control the fire.",
    "Schools and kindergartens opened",
]

eval_dataset = pd.DataFrame({
    "source": sources,
    "response": responses,
    "reference": references,
})

# Set the metrics.

metrics = [
    "bleu",
    pointwise_metric.Comet(),
    pointwise_metric.MetricX(),
]

eval_task = evaluation.EvalTask(
    dataset=eval_dataset,
    metrics=metrics,
)
eval_result = eval_task.evaluate()

Esegui la valutazione con metriche basate su calcolo

Puoi utilizzare le metriche basate su calcolo in modo autonomo o insieme alle metriche basate su modello.

# Combine computation-based metrics "ROUGE" and "BLEU" with model-based metrics
eval_task = EvalTask(
    dataset=EVAL_DATASET,
    metrics=["rouge_l_sum", "bleu", custom_text_quality],
)
eval_result = eval_task.evaluate(
    model=MODEL,
)

Esegui valutazioni su larga scala

Se hai set di dati di valutazione di grandi dimensioni o esegui periodicamente valutazioni in un ambiente di produzione, puoi utilizzare l'API EvaluateDataset nel servizio di valutazione dell'AI generativa per eseguire valutazioni su larga scala.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_NUMBER: il tuo numero di progetto.
  • DATASET_URI: il percorso Cloud Storage di un file JSONL contenente istanze di valutazione. Ogni riga del file deve rappresentare una singola istanza, con chiavi corrispondenti ai campi di immissione definiti dall'utente in metric_prompt_template (per le metriche basate su modello) o ai parametri di input richiesti (per le metriche basate su calcolo). Puoi specificare un solo file JSONL. L'esempio seguente è una riga per un'istanza di valutazione puntuale: 
    {"response": "The Roman Senate was filled with exuberance due to Pompey's defeat in Asia."}
  • METRIC_SPEC: una o più specifiche delle metriche che utilizzi per la valutazione. Puoi utilizzare le seguenti specifiche delle metriche quando esegui valutazioni su larga scala: "pointwise_metric_spec", "pairwise_metric_spec", "exact_match_spec", "bleu_spec" e "rouge_spec".
  • METRIC_SPEC_FIELD_NAME: i campi obbligatori per la specifica della metrica scelta. Ad esempio, "metric_prompt_template"
  • METRIC_SPEC_FIELD_CONTENT: Il contenuto del campo per la specifica della metrica scelta. Ad esempio, è possibile utilizzare il seguente contenuto del campo per una valutazione puntuale: "Evaluate the fluency of this sentence: {response}. Give score from 0 to 1. 0 - not fluent at all. 1 - very fluent."
  • OUTPUT_BUCKET: il nome del bucket Cloud Storage in cui vuoi archiviare i risultati della valutazione.

Metodo HTTP e URL: 

POST https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset

Corpo JSON della richiesta: 

{
  "dataset": {
    "gcs_source": {
      "uris": "DATASET_URI"
    }
  },
  "metrics": [
    {
      METRIC_SPEC: {
        METRIC_SPEC_FIELD_NAME: METRIC_SPEC_FIELD_CONTENT
      }
    }
  ],
  "output_config": {
    "gcs_destination": {
      "output_uri_prefix": "OUTPUT_BUCKET"
    }
  }
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset" | Select-Object -Expand Content

Dovresti ricevere una risposta JSON simile alla seguente.

Puoi utilizzare il valore OPERATION_ID che ricevi nella risposta per richiedere lo stato della valutazione:

curl -X GET \
  -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
  -H "Content-Type: application/json; charset=utf-8" \
  "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/operations/OPERATION_ID"

Personalizzazione aggiuntiva delle metriche

Se devi personalizzare ulteriormente le metriche, ad esempio scegliendo un modello di valutazione diverso per le metriche basate su modelli, o definire una nuova metrica basata su calcolo, puoi utilizzare la classe CustomMetric nell'SDK Agent Platform. Per maggiori dettagli, consulta i seguenti notebook:

Esegui la valutazione basata su modelli con limiti di frequenza e quote aumentati

Una singola richiesta di valutazione per una metrica basata su modello genera più richieste sottostanti all'API Gemini in Agent Platform e consuma la quota per il modello di valutazione. Devi impostare un limite di frequenza del servizio di valutazione più elevato nei seguenti casi d'uso:

  • Aumento del volume di dati: se elabori un volume di dati significativamente maggiore utilizzando le metriche basate su modelli, potresti raggiungere la quota predefinita di richieste al minuto (RPM). L'aumento della quota ti consente di gestire il volume più elevato senza interruzioni o peggioramento delle prestazioni.

  • Valutazione più rapida: se la tua applicazione richiede tempi di risposta più rapidi per le valutazioni, potresti aver bisogno di una quota RPM più elevata. Questo è particolarmente importante per le applicazioni sensibili al fattore tempo o con interazioni in tempo reale, in cui i ritardi nella valutazione possono influire sull'esperienza utente.

  • Attività di valutazione complesse: una quota RPM più elevata garantisce una capacità sufficiente per gestire valutazioni ad alta intensità di risorse per attività complesse o grandi quantità di testo.

  • Elevata contemporaneità degli utenti: se prevedi che un numero elevato di utenti richieda contemporaneamente valutazioni basate su modelli e inferenze dei modelli all'interno del tuo progetto, un limite di RPM del modello più elevato è fondamentale per evitare colli di bottiglia e mantenere la reattività.

Se utilizzi il modello di valutazione predefinito di Gemini 2.5 Flash o modelli più recenti, ti consigliamo di utilizzare il throughput riservato per gestire la tua quota.

Per eseguire una valutazione utilizzando una nuova quota, imposta il parametro evaluation_service_qps come segue:

from vertexai.evaluation import EvalTask

# GEMINI_RPM is the requests per minute (RPM) quota for gemini-2.0-flash-001 in your region
# Evaluation Service QPS limit is equal to (gemini-2.0-flash-001 RPM / 60 sec / default number of samples)
CUSTOM_EVAL_SERVICE_QPS_LIMIT = GEMINI_RPM / 60 / 4

eval_task = EvalTask(
    dataset=DATASET,
    metrics=[METRIC_1, METRIC_2, METRIC_3],
)

eval_result = eval_task.evaluate(
    evaluation_service_qps=CUSTOM_EVAL_SERVICE_QPS_LIMIT,
    # Specify a retry_timeout limit for a more responsive evaluation run
    # the default value is 600 (in seconds, or 10 minutes)
    retry_timeout=RETRY_TIMEOUT,
)

Per saperne di più su quote e limiti, consulta Quote del servizio di valutazione dell'AI generativa e API del servizio di valutazione dell'AI generativa.

Passaggi successivi