Ejecuta una canalización de evaluación basada en procesamiento

Puedes evaluar el rendimiento de los modelos de base y los modelos de IA generativa ajustados en Gemini Enterprise Agent Platform. Los modelos se evalúan mediante un conjunto de métricas en función de un conjunto de datos de evaluación que proporcionas. En esta página, se explica cómo funciona la evaluación de modelos basada en procesamiento a través del servicio de canalización de evaluación , cómo crear y formatear el conjunto de datos de evaluación y cómo realizar la evaluación mediante la Google Cloud consola de , la API de Agent Platform o el SDK de Agent Platform para Python.

Cómo funciona la evaluación de modelos basada en procesamiento

Para evaluar el rendimiento de un modelo, primero debes crear un conjunto de datos de evaluación que contenga mensajes y pares de verdad fundamental. Para cada par, la instrucción es la entrada que deseas evaluar y la verdad fundamental es la respuesta ideal para esa instrucción. Durante la evaluación, la instrucción de cada par del conjunto de datos de evaluación se pasa al modelo para producir un resultado. El resultado que generó el modelo y la verdad fundamental del conjunto de datos de evaluación se usan para calcular las métricas de evaluación.

El tipo de métricas usadas para la evaluación depende de la tarea que estés evaluando. En la siguiente tabla, se muestran las tareas admitidas y las métricas usadas para evaluar cada tarea:

Tarea Métrica
Clasificación Micro-F1, Macro-F1 y por clase F1
Resúmenes ROUGE-L
Búsqueda de respuestas Concordancia exacta
Generación de texto BLEU, ROUGE-L

Modelos compatibles

La evaluación de modelos es compatible con los siguientes modelos:

  • text-bison: Versiones de base y ajustadas

  • Gemini: Todas las tareas, excepto la clasificación

Prepara el conjunto de datos de evaluación

El conjunto de datos de evaluación que se usa para la evaluación del modelo incluye pares de instrucción y verdad fundamental que se alinean con la tarea que deseas evaluar. Tu conjunto de datos debe incluir un mínimo de un par de instrucción y verdad fundamental y al menos 10 pares para las métricas significativas. Cuantos más ejemplos proporciones, más significativos serán los resultados.

Formato del conjunto de datos

El conjunto de datos de evaluación debe estar en Líneas JSON (JSONL) donde cada línea contiene un solo mensaje y un par de verdad fundamental especificados en elinput_text youtput_text respectivamente. El campo input_text contiene la instrucción que deseas evaluar y el campo output_text contiene la respuesta ideal para la instrucción.

La longitud máxima del token para input_text es 8,192 y la longitud máxima del token para output_text es 1,024.

Sube un conjunto de datos de evaluación a Cloud Storage

Puedes crear un bucket de Cloud Storage nuevo o usar uno existente para almacenar tu archivo de conjunto de datos. El bucket debe estar en la misma región que el modelo.

Una vez que tu bucket esté listo, sube tu archivo de conjunto de datos al bucket.

Realiza la evaluación del modelo

Puedes evaluar los modelos a través de la API de REST o la Google Cloud consola de.

REST

Para crear un trabajo de evaluaci´n de modelo, envía una solicitud POST a través del método pipelineJobs.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: El Google Cloud proyecto que ejecuta los componentes de canalización.
  • PIPELINEJOB_DISPLAYNAME: Un nombre visible para el pipelineJob.
  • LOCATION: Es la región en la que se ejecutarán los componentes de canalización. Por el momento, solo se admite us-central1.
  • DATASET_URI: Es el URI de Cloud Storage de tu conjunto de datos de referencia. Puedes especificar uno o varios URI. Este parámetro admite comodines. Para obtener más información sobre este parámetro, consulta InputConfig.
  • OUTPUT_DIR: Es el URI de Cloud Storage para almacenar el resultado de la evaluación.
  • MODEL_NAME: Especifica un modelo de publicador o un recurso de modelo ajustado de la siguiente manera:
    • Modelo de publicador: publishers/google/models/MODEL@MODEL_VERSION

      Ejemplo: publishers/google/models/text-bison@002

    • Modelo ajustado: projects/PROJECT_NUMBER/locations/LOCATION/models/ENDPOINT_ID

      Ejemplo: projects/123456789012/locations/us-central1/models/1234567890123456789

    El trabajo de evaluación no afecta ninguna implementación existente del modelo o sus recursos.

  • EVALUATION_TASK: La tarea en la que deseas evaluar el modelo. El trabajo de evaluación calcula un conjunto de métricas relevantes para esa tarea específica. Los valores aceptables son los siguientes:
    • summarization
    • question-answering
    • text-generation
    • classification
  • INSTANCES_FORMAT: el formato de tu conjunto de datos. Por el momento, solo se admite jsonl. Para obtener más información sobre este parámetro, consulta InputConfig.
  • PREDICTIONS_FORMAT: El formato del resultado de la evaluación. Por el momento, solo se admite jsonl. Para obtener más información sobre este parámetro, consulta InputConfig.
  • MACHINE_TYPE: El tipo de máquina para ejecutar el trabajo de evaluación (opcional). El valor predeterminado es e2-highmem-16. Para obtener una lista de tipos de máquinas compatibles, consulta Tipos de máquinas.
  • SERVICE_ACCOUNT: (Opcional) La cuenta de servicio que se usará para ejecutar el trabajo de evaluación. Para obtener información sobre cómo crear una cuenta de servicio personalizada, consulta Configura una cuenta de servicio con permisos detallados. Si no se especifica, se usa el agente de servicio de código personalizado de Gemini Enterprise Agent Platform.
  • NETWORK: El nombre completamente calificado de la red de Compute Engine para intercambiar tráfico con el trabajo de evaluación (opcional). El formato del nombre de la red es projects/PROJECT_NUMBER/global/networks/NETWORK_NAME. Si especificas este campo, debes tener un intercambio de tráfico entre redes de VPC para Gemini Enterprise Agent Platform. Si no se especifica, el trabajo de evaluación no intercambia tráfico con ninguna red.
  • KEY_NAME: El nombre de la clave de encriptación administrada por el cliente (CMEK) (opcional). Si se configura, los recursos que creó el trabajo de evaluación se encriptan con la clave de encriptación proporcionada. El formato del nombre de la clave es projects/PROJECT_ID/locations/REGION/keyRings/KEY_RING/cryptoKeys/KEY. La clave debe estar en la misma región que el trabajo de evaluación.

Método HTTP y URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/pipelineJobs

Cuerpo JSON de la solicitud: 

{
  "displayName": "PIPELINEJOB_DISPLAYNAME",
  "runtimeConfig": {
    "gcsOutputDirectory": "gs://OUTPUT_DIR",
    "parameterValues": {
      "project": "PROJECT_ID",
      "location": "LOCATION",
      "batch_predict_gcs_source_uris": ["gs://DATASET_URI"],
      "batch_predict_gcs_destination_output_uri": "gs://OUTPUT_DIR",
      "model_name": "MODEL_NAME",
      "evaluation_task": "EVALUATION_TASK",
      "batch_predict_instances_format": "INSTANCES_FORMAT",
      "batch_predict_predictions_format: "PREDICTIONS_FORMAT",
      "machine_type": "MACHINE_TYPE",
      "service_account": "SERVICE_ACCOUNT",
      "network": "NETWORK",
      "encryption_spec_key_name": "KEY_NAME"
    }
  },
  "templateUri": "https://us-kfp.pkg.dev/vertex-evaluation/pipeline-templates/evaluation-llm-text-generation-pipeline/1.0.1"
}

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/pipelineJobs"

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://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/pipelineJobs" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: Ten en cuenta que pipelineSpec se truncó para ahorrar espacio.

Ejemplo del comando curl

PROJECT_ID=myproject
REGION=us-central1
MODEL_NAME=publishers/google/models/text-bison@002
TEST_DATASET_URI=gs://my-gcs-bucket-uri/dataset.jsonl
OUTPUT_DIR=gs://my-gcs-bucket-uri/output

curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}/pipelineJobs" -d \
$'{
  "displayName": "evaluation-llm-text-generation-pipeline",
  "runtimeConfig": {
    "gcsOutputDirectory": "'${OUTPUT_DIR}'",
    "parameterValues": {
      "project": "'${PROJECT_ID}'",
      "location": "'${REGION}'",
      "batch_predict_gcs_source_uris": ["'${TEST_DATASET_URI}'"],
      "batch_predict_gcs_destination_output_uri": "'${OUTPUT_DIR}'",
      "model_name": "'${MODEL_NAME}'",
    }
  },
  "templateUri": "https://us-kfp.pkg.dev/vertex-evaluation/pipeline-templates/evaluation-llm-text-generation-pipeline/1.0.1"
}'

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración de Python que encontrarás en la guía de inicio rápido de Agent Platform sobre cómo usar bibliotecas cliente.

Para autenticarte en Agent Platform, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

import os

import vertexai
from vertexai.evaluation import EvalResult, EvalTask

# TODO (Developer) Set environment variables
PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION_ID = os.getenv("LOCATION_ID", "us-central1")
MODEL_NAME = os.getenv("MODEL_NAME", "gemini-2.5-flash")


def evaluate_model() -> EvalResult:
    """Evaluate the performance of a generative AI model."""

    vertexai.init(project=PROJECT_ID, location=LOCATION_ID)

    # Dataset URI containing input prompts and ground truth labels
    dataset_uri = "gs://cloud-samples-data/ai-platform/generative_ai/llm_classification_bp_input_prompts_with_ground_truth.jsonl"

    metric_column_mapping = {"reference": "ground_truth"}

    # Define evaluation task
    eval_task = EvalTask(
        dataset=dataset_uri,
        metrics=["exact_match"],
        experiment="gemini-classification-eval",
        metric_column_mapping=metric_column_mapping,
    )

    # Define a prompt template so the generative Gemini model produces formatted labels
    prompt_template = (
        "Classify the following text into exactly one category from "
        "[nature, news, sports, health, startups]. Return only the category name:\n\n{prompt}"
    )

    # Evaluate using a modern Gemini model
    eval_result = eval_task.evaluate(
        model=MODEL_NAME,
        prompt_template=prompt_template,
    )

    print("=== SUMMARY METRICS ===")
    print(eval_result.summary_metrics)

    print("\n=== METRICS TABLE SAMPLE ===")
    print(eval_result.metrics_table.head())

    return eval_result

Console

Para crear un trabajo de evaluación de modelos con la Google Cloud consola de, sigue estos pasos:

  1. En la Google Cloud consola de, ve a la página Model Registry de Gemini Enterprise Agent Platform.

    Ir a Model Registry de Gemini Enterprise Agent Platform

  2. Haz clic en el nombre del modelo que deseas evaluar.
  3. En la pestaña Evaluar, haz clic en Crear evaluación y configúrala de la siguiente manera:
    • Objetivo: Elige la tarea que deseas evaluar.
    • Columna o campo de destino: (Solo clasificación) escribe la columna de destino para la predicción. Ejemplo: ground_truth.
    • Ruta de acceso de origen: Escribe o elige el URI del conjunto de datos de evaluación.
    • Formato de salida: Escribe el formato del resultado de la evaluación. Por el momento, solo se admite jsonl.
    • Ruta de acceso de Cloud Storage: Escribe o elige el URI para almacenar el resultado de la evaluación.
    • Nombres de clase: (Solo clasificación) escribe la lista de nombres de clase posibles.
    • Cantidad de nodos de procesamiento: Escribe la cantidad de nodos de procesamiento para ejecutar el trabajo de evaluación.
    • Tipo de máquina: Elige un tipo de máquina que se usará para ejecutar el trabajo de evaluación.
  4. Haz clic en Iniciar evaluación

Visualiza los resultados de la evaluación

Puedes encontrar los resultados de la evaluación en el directorio de salida de Cloud Storage que especificaste cuando creaste el trabajo de evaluación. El nombre del archivo es evaluation_metrics.json.

Para los modelos ajustados, también puedes ver los resultados de la evaluación en la Google Cloud consola:

  1. En la sección Agent Platform de la Google Cloud consola de, ve a la página Model Registry de Gemini Enterprise Agent Platform.

    Ir a Model Registry de Gemini Enterprise Agent Platform

  2. Haz clic en el nombre del modelo para ver sus métricas de evaluación.

  3. En la pestaña Evaluar, haz clic en el nombre de la ejecución de la evaluación que deseas ver.

¿Qué sigue?