Instructivo: Realiza una evaluación con el cliente de GenAI en el SDK de Vertex AI

En esta página, se muestra cómo evaluar tus modelos y aplicaciones de IA generativa en una variedad de casos de uso con el cliente de GenAI en el SDK de Vertex AI.

El cliente de GenAI en el SDK de Vertex AI para el servicio de evaluación de IA generativa te permite medir el rendimiento de las instrucciones, los modelos de base y los agentes de IA complejos en función de los criterios más relevantes. Puedes evaluar la cantidad de candidatos que desees a la vez para ajustar las instrucciones, seleccionar el mejor modelo o iterar en agentes complejos.

Puedes hacer lo siguiente con el cliente de IA generativa en el SDK de Vertex AI:

  • Compara varios modelos o configuraciones en paralelo en una sola ejecución con cálculos de la tasa de victorias para guiar tus decisiones.

  • Usa la compatibilidad integrada para evaluar y comparar modelos de terceros populares sin integraciones complejas.

  • Maneja conjuntos de datos grandes con mayor eficiencia y descarga tareas de evaluación a gran escala con la evaluación por lotes asíncrona.

Ejemplo de extremo a extremo

El cliente de GenAI en el SDK de Vertex AI usa un flujo de trabajo de dos pasos: generar respuestas del modelo y evaluar las respuestas. En el siguiente ejemplo de extremo a extremo, se muestra cómo funciona el cliente de IA generativa en el SDK de Vertex AI:

  1. Instala el SDK de Vertex AI para Python:

    pip install --upgrade google-cloud-aiplatform[evaluation]

  2. Prepara el conjunto de datos de evaluación:

    import pandas as pd
from vertexai import Client, types

client = Client(project="your-project-id", location="us-central1")

prompts_df = pd.DataFrame({"prompt": ["How does AI work?"]})

  3. Ejecuta la evaluación:

    # Evaluating a single model.
eval_dataset = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df,
)
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)
eval_result.show()

  4. Compara varios candidatos:

    # Comparing multiple candidates.
candidate_1 = client.evals.run_inference(
    model="gemini-2.0-flash", src=prompts_df
)
candidate_2 = client.evals.run_inference(
    model="gemini-2.5-flash", src=prompts_df
)
comparison_result = client.evals.evaluate(
    dataset=[candidate_1, candidate_2],
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)
comparison_result.show()

Define tu métrica

Define tus métricas como una métrica basada en LLM o una métrica basada en cálculos.

Métricas basadas en LLM

Las métricas basadas en LLM usan un modelo de lenguaje grande (LLM) como un "juez" para evaluar criterios matizados, como el estilo o la calidad de la escritura, que son difíciles de medir solo con algoritmos.

Usa métricas administradas basadas en rúbricas

El cliente de IA generativa en el SDK de Vertex AI proporciona una variedad de métricas basadas en modelos listas para usar, como GENERAL_QUALITY, SAFETY y INSTRUCTION_FOLLOWING. Puedes acceder a ellos a través de la clase RubricMetric. Las definiciones de métricas administradas basadas en rúbricas se cargan a pedido desde una biblioteca centralizada para crear coherencia en las versiones de las métricas basadas en rúbricas.

# Assumes 'eval_dataset' is an EvaluationDataset object created via run_inference()

eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
    ]
)

Para crear resultados coherentes en diferentes versiones del SDK, puedes fijar una métrica en una versión específica. De forma predeterminada, se usa la versión más reciente.

# Pin to a specific version of a pre-built metric
instruction_following_v1 = types.RubricMetric.INSTRUCTION_FOLLOWING(version='v1')

Personaliza las métricas de LLM

Para los casos de uso que requieren criterios especializados, puedes definir tu propia métrica basada en LLM creando una instancia de la clase LLMMetric. Esto te brinda un control total sobre la plantilla de instrucciones de evaluación, el modelo de juez y otros parámetros.

La clase de ayuda MetricPromptBuilder crea una plantilla de instrucción estructurada para el modelo de juez, ya que te permite definir instruction, criteria y rating_scores por separado.

# Define a custom metric to evaluate language simplicity
simplicity_metric = types.LLMMetric(
    name='language_simplicity',
    prompt_template=types.MetricPromptBuilder(
        instruction="Evaluate the story's simplicity for a 5-year-old.",
        criteria={
            "Vocabulary": "Uses simple words.",
            "Sentences": "Uses short sentences.",
        },
        rating_scores={
            "5": "Excellent: Very simple, ideal for a 5-year-old.",
            "4": "Good: Mostly simple, with minor complex parts.",
            "3": "Fair: Mix of simple and complex; may be challenging for a 5-year-old.",
            "2": "Poor: Largely too complex, with difficult words/sentences.",
            "1": "Very Poor: Very complex, unsuitable for a 5-year-old."
        }
    )
)
# Use the custom metric in an evaluation
eval_result = client.evals.evaluate(
    dataset=inference_results,
    metrics=[simplicity_metric]
)

Métricas basadas en cálculos y funciones personalizadas

Las métricas basadas en procesamiento comparan matemáticamente el resultado de un modelo con una verdad fundamental o una referencia. Estas métricas, calculadas con código a través de la clase base Metric, admiten algoritmos predefinidos basados en el procesamiento, como exact_match, bleu y rouge_1. Para usar una métrica basada en el procesamiento, crea una instancia de la clase Metric con el nombre de la métrica. La métrica requiere una columna reference en tu conjunto de datos para la comparación.

eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.Metric(name='exact_match'),
        types.Metric(name='bleu'),
        types.Metric(name='rouge_1'),
    ]
)

Implementa una métrica de función personalizada

También puedes implementar lógica de evaluación personalizada pasando una función de Python personalizada al parámetro custom_function para tener un control completo. El cliente de IA generativa en el SDK de Vertex AI ejecuta esta función para cada fila de tu conjunto de datos.

# Define a custom function to check for the presence of a keyword
def contains_keyword(instance: dict) -> dict:
    keyword = "magic"
    response_text = instance.get("response", "")
    score = 1.0 if keyword in response_text.lower() else 0.0
    return {"score": score}

keyword_metric = types.Metric(
    name="keyword_check",
    custom_function=contains_keyword
)


eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[keyword_metric]
)

Prepara tu conjunto de datos de evaluación

El cliente de IA generativa en el SDK de Vertex AI detecta y controla automáticamente varios formatos de datos comunes. Esto significa que, a menudo, puedes usar tus datos tal como están sin necesidad de realizar conversiones manuales, ya sea que generes respuestas nuevas con run_inference o evalúes las existentes con evaluate.

El cliente de IA generativa en el SDK de Vertex AI admite los siguientes formatos:

  • DataFrame de Pandas (formato aplanado)

    Para evaluaciones sencillas, puedes usar un pandas.DataFrame. El cliente de IA generativa en el SDK de Vertex AI busca nombres de columnas comunes, como prompt, response y reference. Este formato es totalmente retrocompatible.

    import pandas as pd

# Simple DataFrame with prompts and ground truth references
prompts_df = pd.DataFrame({
    "prompt": [
        "What is the capital of France?",
        "Who wrote 'Hamlet'?",
    ],
    "reference": [
        "Paris",
        "William Shakespeare",
    ]
})

# Generate responses using the DataFrame as a source
inference_results = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df
)
inference_results.show()

  • Formato de predicción por lotes de Gemini

    Puedes usar directamente el resultado de un trabajo de predicción por lotes de Vertex AI, que suelen ser archivos JSONL almacenados en Cloud Storage, en los que cada línea contiene un objeto request y response. El cliente de GenAI en el SDK de Vertex AI analiza esta estructura automáticamente para proporcionar integración con otros servicios de Vertex AI.

    Ejemplo de una sola línea en un archivo jsonl:

    {"request": {"contents": [{"role": "user", "parts": [{"text": "Why is the sky blue?"}]}]}, "response": {"candidates": [{"content": {"role": "model", "parts": [{"text": "The sky appears blue to the human eye as a result of a phenomenon known as Rayleigh scattering."}]}}]}}

    Luego, puedes evaluar las respuestas generadas previamente desde un trabajo por lotes directamente:

    # Cloud Storage path to your batch prediction output file
batch_job_output_uri = "gs://path/to/your/batch_output.jsonl"

# Evaluate the results directly from Cloud Storage
eval_result = client.evals.evaluate(
    dataset=batch_job_output_uri,
    metrics=[
        types.RubricMetric.COHERENCE,
        types.RubricMetric.FLUENCY,
    ]
)
eval_result.show()

  • Formato de Chat Completion de OpenAI

    Para evaluar o comparar con modelos de terceros, el cliente de GenAI en el SDK de Vertex AI admite el formato de finalización de chat de OpenAI. Puedes proporcionar un conjunto de datos en el que cada fila sea un objeto JSON estructurado como una solicitud de la API de OpenAI. El cliente de IA generativa en el SDK de Vertex AI detecta automáticamente este formato.

    A continuación, se muestra un ejemplo de una sola línea en este formato:

    {"request": {"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What's the capital of France?"}], "model": "gpt-4o"}}

    Puedes usar estos datos para generar respuestas a partir de un modelo de terceros y evaluar las respuestas:

    # Ensure your third-party API key is set
# e.g., os.environ['OPENAI_API_KEY'] = 'Your API Key'

openai_request_uri = "gs://path/to/your/openai_requests.jsonl"

# Generate responses using a LiteLLM-supported model string
openai_responses = client.evals.run_inference(
    model="gpt-4o",
    src=openai_request_uri,
)

# The resulting dataset can then be evaluated
eval_result = client.evals.evaluate(
    dataset=openai_responses,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.FLUENCY,
    ]
)

eval_result.show()

Ejecutar evaluación

El cliente de GenAI en el SDK de Vertex AI usa el siguiente proceso basado en el cliente para ejecutar evaluaciones:

  1. run_inference(): Genera respuestas a partir de tu modelo para un conjunto determinado de instrucciones.

  2. evaluate(): Calcula métricas sobre las respuestas generadas.

eval_dataset = client.evals.run_inference(
    model="gemini-2.5-flash",
src="gs://vertex-evaluation-llm-dataset-us-central1/genai_eval_sdk/test_prompts.jsonl",
)
eval_dataset.show()


eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[
        types.RubricMetric.GENERAL_QUALITY,
        types.RubricMetric.QUESTION_ANSWERING_QUALITY,
        types.Metric(name='bleu'),
        types.Metric(name='rouge_1'),
    ]
)
eval_result.show()

Para analizar el rendimiento de varios modelos o sistemas de IA en una sola evaluación, genera una respuesta para cada candidato y pásalas en una lista al método evaluate():

inference_result_1 = client.evals.run_inference(
    model="gemini-2.0-flash",
    src=prompts_df,
)
inference_result_2 = client.evals.run_inference(
    model="gemini-2.5-flash",
    src=prompts_df,
)

# Compare the responses against each other
comparison_result = client.evals.evaluate(
    dataset=[inference_result_1, inference_result_2],
    metrics=[
        types.RubricMetric.TEXT_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
    ]
)

comparison_result.show()

Evaluación asíncrona y a gran escala

Para conjuntos de datos grandes, el cliente de IA generativa en el SDK de Vertex AI proporciona un método de evaluación por lotes asíncrono de larga duración. Esto es ideal para situaciones en las que no necesitas resultados inmediatos y deseas descargar el procesamiento.

El método batch_evaluate() devuelve un objeto de operación que puedes sondear para hacer un seguimiento de su progreso. Los parámetros son compatibles con el método evaluate().

GCS_DEST_BUCKET = "gs://your-gcs-bucket/batch_eval_results/"

inference_result_saved = client.evals.run_inference(
    model="gemini-2.0-flash",
    src=prompts_df,
    config={'dest': GCS_DEST_BUCKET}
)
print(f"Eval dataset uploaded to: {inference_result_saved.gcs_source}")

batch_eval_job  = client.evals.batch_evaluate(
   dataset = inference_result_saved,
   metrics = [
        types.RubricMetric.TEXT_QUALITY,
        types.RubricMetric.INSTRUCTION_FOLLOWING,
        types.RubricMetric.FLUENCY,
        types.Metric(name='bleu'),
    ],
   dest=GCS_DEST_BUCKET
)

Cómo evaluar modelos de terceros

Puedes usar el cliente de IA generativa en el SDK de Vertex AI para evaluar y comparar modelos de proveedores como OpenAI pasando la cadena del nombre del modelo al método run_inference. El cliente de IA generativa del SDK de Vertex AI usa la biblioteca litellm para llamar a la API del modelo.

Asegúrate de establecer la clave de API requerida como una variable de entorno (OPENAI_API_KEY):

import os

# Set your third-party model API key
os.environ['OPENAI_API_KEY'] = 'YOUR_OPENAI_API_KEY'

# Run inference on an OpenAI model
gpt_response = client.evals.run_inference(
    model='gpt-4o',
    src=prompt_df
)

# You can now evaluate the responses
eval_result = client.evals.evaluate(
    dataset=gpt_response,
    metrics=[types.RubricMetric.GENERAL_QUALITY]
)

eval_result.show()

Visualización

El cliente de IA generativa del SDK de Vertex AI te permite visualizar tus resultados directamente en tu entorno de desarrollo, como un notebook de Colab o Jupyter. El método .show(), disponible en los objetos EvaluationDataset y EvaluationResult, renderiza un informe HTML interactivo para el análisis.

Visualiza los resultados de la inferencia

Después de generar respuestas con run_inference(), puedes llamar a .show() en el objeto EvaluationDataset resultante para inspeccionar los resultados del modelo junto con tus instrucciones y referencias originales. Esto es útil para realizar una verificación rápida de la calidad antes de ejecutar una evaluación completa.

# First, run inference to get an EvaluationDataset
gpt_response = client.evals.run_inference(
    model='gpt-4o',
    src=prompt_df
)

# Now, visualize the inference results
gpt_response.show()

Se muestra una tabla con cada instrucción, su referencia correspondiente (si se proporciona) y la respuesta recién generada.

Visualiza los resultados de la inferencia

Visualiza informes de evaluación

Cuando llamas a .show() en un objeto EvaluationResult, se muestra un informe con dos secciones principales:

  • Métricas de resumen: Una vista agregada de todas las métricas, que muestra la puntuación media y la desviación estándar en todo el conjunto de datos.

  • Resultados detallados: Un desglose caso por caso que te permite inspeccionar la instrucción, la referencia, la respuesta candidata, la puntuación específica y la explicación de cada métrica.

# First, run an evaluation on a single candidate
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.RubricMetric.TEXT_QUALITY]
)

# Visualize the detailed evaluation report
eval_result.show()

Informe de evaluación

El formato del informe se adapta según si evalúas a un solo candidato o comparas a varios. En el caso de una evaluación de varios candidatos, el informe proporciona una vista comparativa y, en la tabla de resumen, incluye cálculos de la tasa de victorias y empates.

En todos los informes, puedes expandir la sección Ver JSON sin procesar para inspeccionar los datos de cualquier instrucción o respuesta estructurada.

Comparación detallada

¿Qué sigue?