Haz una evaluación

Puedes usar el módulo de evaluación de IA generativa del SDK de Vertex AI para Python para evaluar de forma programática tus modelos y aplicaciones de lenguaje generativo con la API del servicio de evaluación de IA generativa. En esta página se explica cómo ejecutar evaluaciones con el SDK de Vertex AI. Ten en cuenta que las evaluaciones a gran escala solo están disponibles mediante la API REST.

Antes de empezar

Instalar el SDK de Vertex AI

Para instalar el módulo Gen AI Evaluation desde el SDK de Vertex AI para Python, ejecuta el siguiente comando:

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

Para obtener más información, consulta Instalar el SDK de Vertex AI para Python.

Autenticar el SDK de Vertex AI

Después de instalar el SDK de Vertex AI para Python, debes autenticarte. En los siguientes temas se explica cómo autenticarte con el SDK de Vertex AI si trabajas de forma local o en Colaboratory:

  • Si estás desarrollando de forma local, configura las credenciales predeterminadas de la aplicación (ADC) en tu entorno local:

    1. Instala la CLI de Google Cloud y, a continuación, inicialízala ejecutando el siguiente comando:

      gcloud init

    2. Crea credenciales de autenticación local para tu cuenta de Google:

      gcloud auth application-default login

      Se muestra una pantalla de inicio de sesión. Después de iniciar sesión, tus credenciales se almacenan en el archivo de credenciales local que usa ADC. Para obtener más información, consulta el artículo Configurar ADC en 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.

Comprender las cuentas de servicio

El servicio de evaluación de IA generativa usa la cuenta de servicio para obtener predicciones de la API Gemini en Vertex AI para las métricas de evaluación basadas en modelos. Esta cuenta de servicio se aprovisiona automáticamente en la primera solicitud al servicio de evaluación de IA generativa.

Nombre Descripción Dirección de correo electrónico Rol
Agente del servicio de evaluación rápida de Vertex AI 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 al agente de servicio de evaluación rápida son los siguientes:

Rol Permisos
Agente de servicio de evaluación rápida de Vertex AI (roles/aiplatform.rapidevalServiceAgent) aiplatform.endpoints.predict

Hacer una evaluación

Usa la clase EvalTask para ejecutar evaluaciones en los siguientes casos prácticos:

Clase EvalTask

La clase EvalTask te ayuda a evaluar modelos y aplicaciones en función de tareas específicas. Para hacer comparaciones justas entre modelos generativos, normalmente tienes que evaluar repetidamente varios modelos y plantillas de peticiones con un conjunto de datos de evaluación fijo usando métricas específicas. También es importante evaluar varias métricas simultáneamente en una sola ejecución de evaluación.

EvalTask también se integra con Vertex AI Experiments para ayudarte a hacer un seguimiento de las configuraciones y los resultados de cada ejecución de evaluación. Vertex AI Experiments te ayuda a gestionar e interpretar los resultados de las evaluaciones, 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,
)

Ejecutar una evaluación con métricas basadas en modelos

En el caso de las métricas basadas en modelos, use las clases PointwiseMetric y PairwiseMetric para definir métricas adaptadas a sus criterios específicos. Ejecuta evaluaciones con las siguientes opciones:

Usar ejemplos de métricas basadas en modelos

Puedes usar directamente la constante Metric Prompt Template Examples integrada en el SDK de Vertex AI. También puede modificarlas e incorporarlas en la interfaz de definición de métricas de formato libre.

Para ver la lista completa de ejemplos de plantillas de peticiones de métricas que abarcan la mayoría de los casos prácticos clave, consulta Plantillas de peticiones de métricas.

Consola

Cuando ejecutas evaluaciones en un cuaderno de Colab Enterprise, puedes acceder a las plantillas de peticiones de métricas directamente desde la Google Cloud consola.

  1. Haz clic en el enlace del cuaderno del servicio de evaluación de la IA generativa que prefieras.

  2. El cuaderno se abre en GitHub. Haz clic en Abrir en Colab Enterprise. Si aparece un cuadro de diálogo que te pide que habilites las APIs, haz clic en Habilitar.

  3. En la barra lateral, haz clic en el icono Evaluación de la IA generativa. Se abrirá el panel Plantillas de métricas predefinidas.

  4. Seleccione las métricas Puntual o Por pares.

  5. Haz clic en la métrica que quieras usar, como Fluidez. Aparecerá el código de ejemplo de la métrica.

  6. Haga clic en Copiar para copiar el código de ejemplo. También puedes hacer clic en Personalizar para cambiar los campos predefinidos de la métrica.

  7. Pega el código de ejemplo en tu cuaderno.

SDK de Vertex AI

En el siguiente ejemplo del SDK de Vertex AI se muestra cómo usar la clase MetricPromptTemplateExamples para definir las 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,
)

Usar una interfaz basada en modelos con plantillas de métricas

Personaliza tus métricas rellenando campos como Criteria y Rating Rubrics con las clases PointwiseMetricPromptTemplate y PairwiseMetricPromptTemplate del SDK de Vertex AI. A algunos campos, como Instruction, se les asigna un valor predeterminado si no se proporciona ningún dato.

También puede especificar input_variables, que es una lista de campos de entrada que usa la plantilla de petición de métrica para generar resultados de evaluación basados en modelos. De forma predeterminada, se incluye la columna response del modelo en las métricas puntuales, y se incluyen las columnas response y baseline_model_response del modelo candidato en las métricas por pares.

Para obtener más información, consulta la sección "Estructurar una plantilla de petición de métrica" del artículo Plantillas de peticiones 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,
)

Usar la interfaz del SDK de métricas de formato libre basada en modelos

Para tener más flexibilidad a la hora de personalizar la plantilla de petición de métrica, puede definir una métrica directamente mediante 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,
)

Evaluar un modelo de traducción

Para evaluar tu modelo de traducción, puedes especificar BLEU, MetricX o COMET como métricas de evaluación al usar el SDK de 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()

Ejecutar una evaluación con métricas basadas en cálculos

Puede usar las métricas basadas en cálculos de forma independiente o junto con las 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,
)

Realizar evaluaciones a gran escala

Si tienes conjuntos de datos de evaluación grandes o realizas evaluaciones periódicamente en un entorno de producción, puedes usar la EvaluateDataset API del servicio de evaluación de IA generativa para llevar a cabo evaluaciones a gran escala.

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • PROJECT_NUMBER: tu número de proyecto.
  • DATASET_URI: ruta 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 correspondan a los campos de entrada definidos por el usuario en metric_prompt_template (para métricas basadas en modelos) o a 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 de una instancia de evaluación pointwise: 
    {"response": "The Roman Senate was filled with exuberance due to Pompey's defeat in Asia."}
  • METRIC_SPEC: una o varias especificaciones de métricas que estés usando para la evaluación. Puede usar las siguientes especificaciones de métricas al realizar evaluaciones a gran escala: "pointwise_metric_spec", "pairwise_metric_spec", "exact_match_spec", "bleu_spec" y "rouge_spec".
  • METRIC_SPEC_FIELD_NAME: los campos obligatorios de la especificación de métrica que hayas elegido. Por ejemplo, "metric_prompt_template"
  • METRIC_SPEC_FIELD_CONTENT: el contenido del campo de la especificación de métrica que elijas. Por ejemplo, puedes usar el siguiente contenido de campo para una evaluación punto a punto: "Evaluate the fluency of this sentence: {response}. Give score from 0 to 1. 0 - not fluent at all. 1 - very fluent."
  • OUTPUT_BUCKET: el nombre del segmento de Cloud Storage en el que quieres 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 siguiente.

Puedes usar el OPERATION_ID que recibas 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 cálculos, puedes usar la clase CustomMetric en el SDK de Vertex AI. Para obtener más información, consulta los siguientes cuadernos:

Ejecutar evaluaciones basadas en modelos con límites de frecuencia y cuotas más altos

Una sola solicitud de evaluación de una métrica basada en modelos da lugar a varias solicitudes subyacentes a la API de Gemini en Vertex AI y consume cuota del modelo de juez. Deberías definir un límite de frecuencia de servicio de evaluación más alto en los siguientes casos prácticos:

  • Aumento del volumen de datos: si procesas una cantidad de datos significativamente mayor con las métricas basadas en modelos, es posible que alcances la cuota predeterminada de solicitudes por minuto (RPM). Si aumentas la cuota, podrás gestionar un volumen mayor sin que se produzcan interrupciones ni se vea afectado el rendimiento.

  • Evaluación más rápida: si tu aplicación requiere un plazo de respuesta más rápido para las evaluaciones, es posible que necesites una cuota de RPM más alta. Esto es especialmente importante en las aplicaciones urgentes o en las que se producen interacciones en tiempo real, ya que los retrasos en la evaluación pueden afectar a la experiencia de usuario.

  • Tareas de evaluación complejas: una cuota de RPM más alta te asegura que tienes capacidad suficiente para gestionar evaluaciones que consumen muchos recursos en tareas complejas o grandes cantidades de texto.

  • Concurrencia de usuarios alta: si prevé que un gran número de usuarios solicitarán simultáneamente evaluaciones basadas en modelos e inferencias de modelos en su proyecto, es fundamental que el límite de RPM de modelos sea 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 Provisioned Throughput para gestionar tu cuota.

En el caso de los modelos anteriores a gemini-2.0-flash, sigue estas instrucciones para aumentar la cuota de RPM del modelo de juez:

  1. En la Google Cloud consola, ve a la página Cuotas de IAM y administración.

    Ver cuotas en la consola

  2. En el campo Filtro, especifique la Dimensión (identificador del modelo) y la Métrica (identificador de cuota de los modelos de Gemini): base_model:gemini-2.0-flash y Metric:aiplatform.googleapis.com/generate_content_requests_per_minute_per_project_per_base_model.

  3. En la cuota que quieras aumentar, haz clic en el botón del menú más acciones .

  4. En el menú desplegable, haz clic en Editar cuota. Se abrirá el panel Cambios en la cuota.

  5. En Editar cuota, introduce un nuevo valor de cuota.

  6. Haz clic en Enviar solicitud.

  7. Las solicitudes de aumento de cuota se confirman por correo electrónico y suelen tardar dos días hábiles en procesarse.

Para llevar a cabo una evaluación con una nueva cuota, define 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 las cuotas del servicio de evaluación de la IA generativa y la API del servicio de evaluación de la IA generativa.

Siguientes pasos