Puedes usar el módulo de Gen AI Evaluation del SDK de Agent Platform para Python para evaluar de manera programática tus modelos y aplicaciones de lenguaje generativo con la API del Gen AI Evaluation Service. En esta página, se muestra cómo ejecutar evaluaciones con el SDK de Agent Platform. Ten en cuenta que las evaluaciones a gran escala solo están disponibles con la API de REST.
Antes de comenzar
Para comenzar a ejecutar evaluaciones, completa los siguientes requisitos previos.
Instala el SDK de Agent Platform
Para instalar el módulo de Gen AI Evaluation desde el SDK de Agent Platform para Python, ejecuta el siguiente comando:
!pip install -q google-cloud-aiplatform[evaluation]
Si quieres obtener más información, consulta Instala el SDK de Agent Platform para Python.
Autentica el SDK de Agent Platform
Después de instalar el SDK de Agent Platform para Python, debes autenticarte. En los siguientes temas, se explica cómo autenticar con el SDK de Agent Platform si trabajas de forma local y en Colaboratory:
Si desarrollas de manera local, configura las credenciales predeterminadas de la aplicación (ADC) en tu entorno local:
Instala Google Cloud CLI y, luego, inicialízala a través de la ejecución del siguiente comando:
gcloud initCrea credenciales de autenticación locales para tu Cuenta de Google:
gcloud auth application-default loginSe muestra una pantalla de acceso. Después de acceder, tus credenciales se almacenan en el archivo de credenciales local que usa ADC. Para obtener más información, consulta Configura ADC para un entorno de desarrollo local.
Si trabajas en Colaboratory, ejecuta el siguiente comando en una celda de Colab para autenticarte:
from google.colab import auth auth.authenticate_user()Este comando abre una ventana en la que puedes completar la autenticación.
Comprende las cuentas de servicio
El servicio de evaluación de IA generativa usa la cuenta de servicio para obtener predicciones de la API de Gemini en Agent Platform de Gemini Enterprise para las métricas de evaluación basadas en modelos. Esta cuenta de servicio se aprovisiona de forma automática en la primera solicitud al servicio de evaluación de IA generativa.
| Nombre | Descripción | Dirección de correo electrónico | Rol |
|---|---|---|---|
| Agente de servicio de Rapid Eval de Agent Platform | La cuenta de servicio que se usa para obtener predicciones para la evaluación basada en modelos. | service-PROJECT_NUMBER@gcp-sa-vertex-eval.iam.gserviceaccount.com |
roles/aiplatform.rapidevalServiceAgent |
Los permisos asociados con el agente de servicio de evaluación rápida son los siguientes:
| Rol | Permisos |
|---|---|
| Agente de servicio de Rapid Eval de Agent Platform (roles/aiplatform.rapidevalServiceAgent) | aiplatform.endpoints.predict |
Ejecuta tu evaluación
Usa la clase EvalTask para ejecutar evaluaciones de los siguientes casos de uso:
Ejecuta evaluaciones a gran escala (vista previa)
Clase EvalTask
La clase EvalTask te ayuda a evaluar modelos y aplicaciones en función de tareas específicas. Para realizar comparaciones justas entre modelos generativos, por lo general, debes evaluar de forma repetida varios modelos y plantillas de instrucciones en un conjunto de datos de evaluación fijo con métricas específicas. También es importante evaluar varias métricas de forma simultánea en una sola ejecución de evaluación.
EvalTask también se integra con Agent Platform Experiments para ayudarte a hacer un seguimiento de las configuraciones y los resultados de cada ejecución de evaluación. Agent Platform Experiments ayuda a administrar e interpretar los resultados de la evaluación, lo que te permite tomar decisiones fundamentadas.
En el siguiente ejemplo, se muestra cómo crear una instancia de la clase EvalTask y ejecutar una evaluación:
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,
)
Ejecuta la evaluación con métricas basadas en modelos
Para las métricas basadas en modelos, usa las clases PointwiseMetric y PairwiseMetric para definir métricas adaptadas a tus criterios específicos. Ejecuta evaluaciones con las siguientes opciones:
Usa ejemplos de métricas basadas en modelos
Puedes usar directamente la constante integrada Metric Prompt Template Examples en el SDK de Agent Platform. De forma alternativa, puedes modificarlos e incorporarlos en la interfaz de definición de métricas de formato libre.
Para obtener la lista completa de ejemplos de plantillas de instrucciones de métricas que abarcan la mayoría de los casos de uso clave, consulta Plantillas de instrucciones de métricas.
Console
Cuando ejecutas evaluaciones en un notebook de Colab Enterprise, puedes acceder a las plantillas de instrucciones de métricas directamente desde la Google Cloud consola.
Haz clic en el vínculo del notebook del servicio de evaluación de IA generativa que prefieras.
El notebook se abrirá en GitHub. Haz clic en Abrir en Colab Enterprise. Si un diálogo te solicita que habilites las APIs, haz clic en Habilitar.
Haz clic en el ícono Gen AI Evaluation en la barra lateral. Se abrirá un panel de Plantillas de métricas creadas previamente.
Selecciona métricas Pointwise o Pairwise.
Haz clic en la métrica que deseas usar, como Fluidez. Aparecerá la muestra de código de la métrica.
Haz clic en Copiar para copiar la muestra de código. De manera opcional, haz clic en Personalizar para cambiar los campos preestablecidos de la métrica.
Pega la muestra de código en tu notebook.
SDK de Agent Platform
En el siguiente ejemplo del SDK de Agent Platform, se muestra cómo usar la clase MetricPromptTemplateExamples para definir tus métricas:
# 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,
)
Usa una interfaz con plantillas de métricas basadas en modelos
Para personalizar tus métricas, propaga campos como Criteria y Rating Rubrics con las clases PointwiseMetricPromptTemplate y PairwiseMetricPromptTemplate en el SDK de Agent Platform. A ciertos campos, como Instruction, se les asigna un valor predeterminado si no proporcionas una entrada.
De manera opcional, puedes especificar input_variables, que es una lista de campos de entrada que usa la plantilla de instrucciones de métricas para generar resultados de evaluación basados en modelos. De forma predeterminada, se incluye la columna response del modelo para las métricas por puntos, y se incluyen las columnas response y baseline_model_response del modelo candidato para las métricas por pares.
Para obtener información adicional, consulta la sección “Estructura una plantilla de instrucciones de métricas” en Plantillas de instrucciones de métricas.
# 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,
)
Usa la interfaz de SDK de formato libre de métricas basadas en modelos
Para obtener más flexibilidad en la personalización de la plantilla de instrucciones de métricas, puedes definir una métrica directamente con la interfaz de formato libre, que acepta una entrada de cadena directa.
# 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,
)
Evalúa un modelo de traducción
Para evaluar tu modelo de traducción, puedes especificar BLEU, MetricX o COMET como métricas de evaluación cuando usas el SDK de 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()
Ejecuta la evaluación con métricas basadas en cálculos
Puedes usar métricas basadas en cálculos de forma independiente o junto con métricas basadas en modelos.
# 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,
)
Ejecuta evaluaciones a gran escala
Si tienes grandes conjuntos de datos de evaluación o ejecutas evaluaciones de forma periódica en un entorno de producción, puedes usar la API de EvaluateDataset en el servicio de evaluación de IA generativa para ejecutar evaluaciones a gran escala.
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- PROJECT_NUMBER: Es tu número de proyecto.
- DATASET_URI: Es la ruta de acceso de Cloud Storage a un archivo JSONL
que contiene instancias de evaluación. Cada línea del archivo debe representar una sola instancia, con
claves que corresponden a los campos de entrada definidos por el usuario en el
metric_prompt_template(para métricas basadas en modelos) o los parámetros de entrada obligatorios (para métricas basadas en cálculos). Solo puedes especificar un archivo JSONL. El siguiente ejemplo es una línea para una instancia de evaluación por puntos:{"response": "The Roman Senate was filled with exuberance due to Pompey's defeat in Asia."} - METRIC_SPEC: Son una o más
especificaciones de métricas que usas para la
evaluación. Puedes usar las siguientes especificaciones de métricas cuando ejecutas evaluaciones a gran escala:
"pointwise_metric_spec","pairwise_metric_spec","exact_match_spec","bleu_spec"y"rouge_spec". - METRIC_SPEC_FIELD_NAME: Son los campos obligatorios
para la especificación de métricas elegida. Por ejemplo,
"metric_prompt_template". - METRIC_SPEC_FIELD_CONTENT: Es el contenido del campo para la especificación de métricas elegida. Por ejemplo, puedes usar el siguiente contenido de campo para una evaluación por puntos:
"Evaluate the fluency of this sentence: {response}. Give score from 0 to 1. 0 - not fluent at all. 1 - very fluent." - OUTPUT_BUCKET: Es el nombre del bucket de Cloud Storage en el que deseas almacenar los resultados de la evaluación.
Método HTTP y URL:
POST https://us-central1-aiplatform.googleapis.com/v1beta1/projects/PROJECT_NUMBER/locations/us-central1/evaluateDataset
Cuerpo JSON de la solicitud:
{
"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"
}
}
}
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:
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
Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:
$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
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
Puedes usar el OPERATION_ID que recibes en la respuesta para solicitar el estado de la evaluación:
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"
Personalización adicional de métricas
Si necesitas personalizar aún más tus métricas, como elegir un modelo de juez diferente para las métricas basadas en modelos o definir una nueva métrica basada en procesamiento, puedes usar la clase CustomMetric en el SDK de Agent Platform. Para obtener más detalles, consulta los siguientes notebooks:
Ejecuta la evaluación basada en modelos con límites de frecuencia y cuota aumentados
Una sola solicitud de evaluación para una métrica basada en modelos da como resultado varias solicitudes subyacentes a la API de Gemini en Agent Platform y consume cuota para el modelo de juez. Debes establecer un límite de frecuencia más alto para el servicio de evaluación en los siguientes casos de uso:
Mayor volumen de datos: Si procesas muchos más datos con las métricas basadas en modelos, es posible que alcances la cuota predeterminada de solicitudes por minuto (RPM). Si aumentas la cuota, puedes controlar el volumen más grande sin degradación ni interrupciones del rendimiento.
Evaluación más rápida: Si tu aplicación requiere un tiempo de respuesta más rápido para las evaluaciones, es posible que necesites una cuota de RPM más alta. Esto es especialmente importante para las aplicaciones sensibles al tiempo o aquellas con interacciones en tiempo real en las que las demoras en la evaluación pueden afectar la experiencia del usuario.
Tareas de evaluación complejas: Una cuota de RPM más alta garantiza que tengas suficiente capacidad para controlar las evaluaciones que usan muchos recursos para tareas complejas o grandes cantidades de texto.
Alta simultaneidad de usuarios: Si prevés que una gran cantidad de usuarios solicitarán de forma simultánea evaluaciones basadas en modelos y la inferencia de modelos en tu proyecto, es fundamental tener un límite de RPM de modelo más alto para evitar cuellos de botella y mantener la capacidad de respuesta.
Si usas el modelo de juez predeterminado de gemini-2.0-flash o modelos más recientes, te recomendamos que uses la Capacidad de procesamiento aprovisionada para administrar tu cuota.
Para los modelos anteriores a gemini-2.0-flash, usa las siguientes instrucciones para aumentar la cuota de RPM del modelo de juez:
En la Google Cloud consola de, ve a la página IAM y administración Cuotas.
En el campo Filtro, especifica la Dimensión (identificador del modelo) y la Métrica (identificador de cuota para los modelos de Gemini):
base_model:gemini-2.0-flashyMetric:aiplatform.googleapis.com/generate_content_requests_per_minute_per_project_per_base_model.Para la cuota que deseas aumentar, haz clic en el menú más acciones botón.
En el menú desplegable, haz clic en Editar cuota. Se abrirá el panel Cambios de cuota.
En Editar cuota, ingresa un nuevo valor de cuota.
Haz clic en Enviar solicitud.
La solicitud de aumento de cuota (QIR) se confirma por correo electrónico y, por lo general, tarda dos días hábiles en procesarse.
Para ejecutar una evaluación con una cuota nueva, configura el parámetro evaluation_service_qps de la siguiente manera:
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,
)
Para obtener más información sobre las cuotas y los límites, consulta Cuotas del servicio de evaluación de IA generativa y API del servicio de evaluación de IA generativa.
¿Qué sigue?
Busca una plantilla de métricas basadas en modelos.
Prueba un notebook de ejemplo de evaluación.