Puoi utilizzare il modulo Gen AI Evaluation dell'SDK Vertex AI per Python per valutare a livello di programmazione i modelli e le applicazioni di linguaggio generativi 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 vasta scala sono disponibili solo utilizzando l'API REST.
Prima di iniziare
Per iniziare a eseguire le valutazioni, completa i seguenti prerequisiti.
Installa l'SDK Vertex AI
Per installare il modulo Gen AI Evaluation dall'SDK Agent Platform per Python, esegui il comando seguente:
!pip install -q google-cloud-aiplatform[evaluation]
Per saperne di più, consulta Installa l'SDK Agent Platform per Python.
Autentica l'SDK Vertex AI
Dopo aver installato l'SDK Agent Platform 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 sviluppi in locale, configura le Credenziali predefinite dell'applicazione (ADC) nel tuo ambiente locale:
Installa Google Cloud CLI, quindi inizializzalo eseguendo il comando seguente:
gcloud initCrea le credenziali di autenticazione locali per il tuo Account Google:
gcloud auth application-default loginViene 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 il comando seguente in una cella Colab per eseguire 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 Gen AI evaluation service per ottenere le previsioni dall'API Gemini in Gemini Enterprise Agent Platform per le metriche di valutazione basate su modelli. Questo account di servizio viene sottoposto a provisioning automatico alla prima richiesta al Gen AI evaluation service.
| 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.iam.gserviceaccount.com |
roles/aiplatform.rapidevalServiceAgent |
Le autorizzazioni associate al service agent di valutazione rapida sono:
| Ruolo | Autorizzazioni |
|---|---|
| Agent Platform Rapid Eval Service Agent (roles/aiplatform.rapidevalServiceAgent) | aiplatform.endpoints.predict |
Esegui la valutazione
Utilizza la classe EvalTask per eseguire le valutazioni per i seguenti casi d'uso:
Esegui valutazioni su vasta scala (anteprima)
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 di valutazione.
EvalTask si integra anche con Vertex AI Experiments per aiutarti a monitorare le configurazioni e i risultati di ogni esecuzione di valutazione. Vertex AI Experiments ti 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:
Utilizza gli esempi di metriche basate su modelli
Puoi utilizzare direttamente la costante integrata Metric Prompt Template Examples all'interno dell'SDK Vertex AI. In alternativa, puoi modificarli e incorporarli nell'interfaccia di definizione delle metriche in formato libero.
Per l'elenco completo degli esempi di modelli di prompt di metriche che coprono la maggior parte dei casi d'uso chiave, consulta Modelli di prompt di metriche.
Console
Quando esegui le valutazioni in un notebook Colab Enterprise, puoi accedere ai modelli di prompt di metriche direttamente dalla Google Cloud console.
Fai clic sul link del notebook Gen AI evaluation service che preferisci.
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.
Fai clic sull'icona Gen AI Evaluation nella barra laterale. Si apre un riquadro Modelli di metriche predefiniti.
Seleziona le metriche Pointwise o Pairwise.
Fai clic sulla metrica che vuoi utilizzare, ad esempio Fluidità. Viene visualizzato l'esempio di codice per la metrica.
Fai clic su Copia per copiare l'esempio di codice. Se necessario, fai clic su Personalizza per modificare i campi preimpostati per la metrica.
Incolla l'esempio di codice nel notebook.
SDK Agent Platform
Il seguente esempio di SDK Vertex AI 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 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.
Se necessario, puoi specificare input_variables, che è un elenco di campi di input utilizzati dal modello di prompt di metriche per generare risultati di valutazione basati su modelli. Per impostazione predefinita, la colonna response del modello è inclusa per le metriche pointwise, mentre le colonne response e baseline_model_response del modello candidato sono incluse per le metriche pairwise.
Per ulteriori informazioni, consulta la sezione "Struttura di un modello di prompt di metriche" in Modelli di prompt di 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 modello di prompt di 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 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 su calcolo in modo autonomo o insieme alle metriche basate su modelli.
# 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 vasta 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 Gen AI evaluation service per eseguire valutazioni su vasta scala.
Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:
- PROJECT_NUMBER: il numero del progetto .
- DATASET_URI: il percorso di archiviazione cloud 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 su modelli) o ai parametri di input obbligatori (per le metriche basate su calcolo). Puoi specificare un solo file JSONL. Il seguente esempio è una riga per un'istanza di valutazione pointwise:{"response": "The Roman Senate was filled with exuberance due to Pompey's defeat in Asia."} - METRIC_SPEC: una o più
specifiche di metriche che utilizzi per la
valutazione. Puoi utilizzare le seguenti specifiche di metriche quando esegui valutazioni su vasta 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 di metriche scelta. Ad esempio,
"metric_prompt_template" - METRIC_SPEC_FIELD_CONTENT: il contenuto del campo per la specifica di metriche scelta. Ad esempio, puoi utilizzare il seguente contenuto del campo per una valutazione pointwise:
"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,
e 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 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 scegliere 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 Vertex AI. Per maggiori dettagli, consulta i seguenti notebook:
Esegui la valutazione basata su modelli con limiti di frequenza e quota aumentati
Una singola richiesta di valutazione per una metrica basata su modelli 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 una quantità di dati notevolmente 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 maggiore senza degradare le prestazioni o causare interruzioni.
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. Ciò è particolarmente importante per le applicazioni sensibili al tempo o per quelle 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 ti garantisce una capacità sufficiente per gestire le valutazioni che richiedono molte risorse per attività complesse o grandi quantità di testo.
Concorrenza elevata degli utenti: se prevedi un numero elevato di utenti che richiedono contemporaneamente valutazioni basate su modelli e inferenza di modelli all'interno del tuo progetto, un limite RPM del modello più elevato è fondamentale per evitare colli di bottiglia e mantenere la reattività.
Se utilizzi il modello di valutazione predefinito gemini-2.0-flash o modelli più recenti, ti consigliamo di utilizzare la Throughput riservato per gestire la quota.
Per i modelli precedenti a gemini-2.0-flash, segui queste istruzioni per aumentare la quota RPM del modello di valutazione:
Nella Google Cloud console, vai alla pagina Quote di IAM e amministrazione.
Nel campo Filtro, specifica la Dimensione (identificatore del modello) e la Metrica (identificatore della quota per i modelli Gemini):
base_model:gemini-2.0-flasheMetric:aiplatform.googleapis.com/generate_content_requests_per_minute_per_project_per_base_model.Per la quota che vuoi aumentare, fai clic sul pulsante del menu Altre azioni .
Nel menu a discesa, fai clic su Modifica quota. Si apre il riquadro Modifiche della quota.
In Modifica quota, inserisci un nuovo valore di quota.
Fai clic su Invia richiesta.
Una richiesta di aumento della quota (QIR) viene confermata via email e in genere richiede due giorni lavorativi per l'elaborazione.
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 Gen AI evaluation service e API del Gen AI evaluation service.
Passaggi successivi
Trova un modello di metriche basate su modelli.
Prova un notebook di esempio di valutazione.