Eseguire una valutazione

Puoi utilizzare il modulo Gen AI Evaluation dell'SDK Vertex AI per Python per valutare a livello di programmazione i tuoi modelli e applicazioni di linguaggio generativo con l'API Gen AI evaluation service. Questa pagina mostra come eseguire le valutazioni con l'SDK Vertex AI. Tieni presente che le valutazioni su larga scala sono disponibili solo tramite l'API REST.

Prima di iniziare

Installa l'SDK Vertex AI

Per installare il modulo Gen AI Evaluation dall'SDK Vertex AI per Python, esegui questo comando:

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

Per saperne di più, consulta Installare l'SDK Vertex AI per Python.

Autentica l'SDK Vertex AI

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

• Se esegui lo sviluppo 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 locale per il tuo Account Google:

     gcloud auth application-default login
     

     Viene visualizzata una schermata di accesso. Dopo l'accesso, le tue credenziali vengono archiviate nel file delle credenziali locali utilizzato da ADC. Per maggiori informazioni, vedi Configurare ADC per un ambiente di sviluppo locale.

• Se lavori in Colaboratory, esegui questo comando in una cella 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

L'account di servizio viene utilizzato da Gen AI evaluation service per ottenere le previsioni dall'API Gemini in Vertex AI per le metriche di valutazione basate sul modello. Questo account di servizio viene sottoposto a provisioning automatico alla prima richiesta al servizio Gen AI evaluation service.

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

Esegui la valutazione

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

• Metriche basate su modelli

  • Utilizzare esempi esistenti

  • Utilizzare un'interfaccia basata su modelli

  • Definire le metriche da zero

  • Valutare un modello di traduzione (anteprima)

• Metriche basate sul calcolo

• Esegui valutazioni su larga scala (anteprima)

• Personalizzazione aggiuntiva delle metriche

• Aumentare i limiti di frequenza e la quota

Classe EvalTask

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

EvalTask si integra anche con Vertex AI Experiments per aiutarti a monitorare le configurazioni e i risultati di ogni esecuzione della valutazione. Vertex AI Experiments aiuta a gestire e interpretare i risultati della valutazione, consentendoti di prendere decisioni informate.

Il seguente esempio 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:

• Utilizzare esempi esistenti

• Utilizzare un'interfaccia basata su modelli

• Definire le metriche da zero

Utilizzare esempi di metriche basate su modelli

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

Per l'elenco completo degli esempi di modelli di prompt delle metriche che coprono la maggior parte dei casi d'uso chiave, consulta Modelli di prompt delle 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,
)

Utilizzare un'interfaccia basata su modelli di metriche

Personalizza le metriche compilando campi come Criteria e Rating Rubrics utilizzando le classi PointwiseMetricPromptTemplate e PairwiseMetricPromptTemplate all'interno dell'SDK Vertex AI. A determinati campi, come Instruction, viene assegnato un valore predefinito se non fornisci input.

(Facoltativo) Puoi specificare input_variables, che è un elenco di campi di input utilizzati dal modello di prompt della metrica 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 pairwise.

Per ulteriori informazioni, consulta la sezione "Strutturare un modello di prompt della metrica" in Modelli di prompt della metrica.

# 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,
)

Utilizzare l'interfaccia SDK di forma libera della metrica basata su modello

Per una maggiore flessibilità nella personalizzazione del modello di prompt della metrica, 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,
)

Valutare un modello di traduzione

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

#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 sul calcolo in modo autonomo o insieme alle metriche basate sul 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,
)

Eseguire valutazioni su larga scala

Se disponi di 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 Gen AI per eseguire valutazioni su larga scala.

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

• PROJECT_NUMBER: il tuo numero di progetto.
• DATASET_URI: il percorso Cloud Storage di un file JSONL contenente le istanze di valutazione. Ogni riga del file deve rappresentare una singola istanza, con chiavi corrispondenti ai campi di input definiti dall'utente in metric_prompt_template (per le metriche basate sul modello) o ai parametri di input richiesti (per le metriche basate sul 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, puoi 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.

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

{
  "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"
    }
  }
}

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"

$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

{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.EvaluateDatasetOperationMetadata",
    "genericMetadata": {
      "createTime": CREATE_TIME,
      "updateTime": UPDATE_TIME
    }
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.aiplatform.v1beta1.EvaluateDatasetResponse",
    "outputInfo": {
      "gcsOutputDirectory": "gs://OUTPUT_BUCKET/evaluation_GENERATION_TIME"
    }
  }
}

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"

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,
)