Tutorial: Realizar una evaluación con el cliente de IA generativa en el SDK de Vertex AI

Para ver un ejemplo de cómo empezar, realiza una evaluación con el SDK de Vertex AI a través de GenAI Client. Ejecuta el cuaderno "Primeros pasos: realiza una evaluación con el SDK de Vertex AI a través de GenAI Client" en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Vertex AI Workbench | Ver en GitHub

En esta página se explica cómo evaluar tus modelos y aplicaciones de IA generativa en una serie de casos prácticos mediante el cliente de IA generativa del SDK de Vertex AI.

El cliente de IA generativa del SDK de Vertex AI para el servicio de evaluación de IA generativa te permite medir el rendimiento de las peticiones, los modelos fundacionales y los agentes de IA complejos en función de los criterios más relevantes. Puedes evaluar a tantos candidatos como quieras a la vez para ajustar las peticiones, 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 y usa los cálculos de porcentaje de victorias para tomar decisiones.

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

• Gestiona grandes conjuntos de datos con más eficiencia y delega tareas de evaluación a gran escala mediante la evaluación por lotes asíncrona.

Ejemplo completo

El cliente de GenAI del SDK de Vertex AI usa un flujo de trabajo de dos pasos: generar respuestas del modelo y evaluar las respuestas. En el siguiente ejemplo integral 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. Realiza 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. Comparar 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()
   

Definir la métrica

Define las métricas como métricas basadas en LLMs o métricas basadas en cálculos.

Métricas basadas en LLMs

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

Usar métricas gestionadas basadas en rúbricas

El cliente de IA generativa del SDK de Vertex AI proporciona una gran variedad de métricas basadas en modelos listas para usar, como GENERAL_QUALITY, SAFETY y INSTRUCTION_FOLLOWING. Puedes acceder a ellas a través de la clase RubricMetric. Las definiciones de métricas basadas en rúbricas gestionadas se cargan bajo demanda desde una biblioteca centralizada para que las versiones de las métricas basadas en rúbricas sean coherentes.

# 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 obtener 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')

Personalizar métricas de LLM

En los casos prácticos que requieran criterios especializados, puede definir su propia métrica basada en LLMs creando una instancia de la clase LLMMetric. De esta forma, tendrá pleno control sobre la plantilla de petición de evaluación, el modelo de juez y otros parámetros.

La clase auxiliar MetricPromptBuilder crea una plantilla de petició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 cálculos comparan matemáticamente el resultado de un modelo con una verdad fundamental o una referencia. Estas métricas, calculadas con código mediante la clase base Metric, admiten algoritmos predefinidos basados en cálculos, como exact_match, bleu y rouge_1. Para usar una métrica basada en cálculos, crea una instancia de la clase Metric con el nombre de la métrica. La métrica requiere una columna reference en su conjunto de datos para hacer 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'),
    ]
)

Implementar una métrica de función personalizada

También puedes implementar una lógica de evaluación personalizada transfiriendo una función de Python personalizada al parámetro custom_function para tener un control total. El cliente de IA generativa del SDK de Vertex AI ejecuta esta función en 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]
)

Preparar el conjunto de datos de evaluación

El cliente de IA generativa del SDK de Vertex AI detecta y gestiona automáticamente varios formatos de datos habituales. Esto significa que, a menudo, puedes usar tus datos tal cual sin tener que hacer conversiones manuales, tanto si generas nuevas respuestas con run_inference como si evalúas las que ya tienes con evaluate.

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

• Pandas DataFrame (formato aplanado)

  Para las evaluaciones sencillas, puedes usar un pandas.DataFrame. El cliente de GenAI del 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 la salida de un trabajo de predicción por lotes de Vertex AI, que suelen ser archivos JSONL almacenados en Cloud Storage, donde cada línea contiene un objeto request y response. El cliente de IA generativa del 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."}]}}]}}
  

  Después, puede evaluar las respuestas pregeneradas de una tarea 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 finalización de chat de OpenAI

  Para evaluar o comparar modelos de terceros, el cliente de IA generativa del 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 del SDK de Vertex AI detecta automáticamente este formato.

  Ejemplo de una sola línea con este formato:

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

  Puede 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()
  

Hacer una evaluación

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

1. run_inference(): genera respuestas de tu modelo para un conjunto de peticiones determinado.

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

En el caso de los conjuntos de datos grandes, el cliente de IA generativa del SDK de Vertex AI proporciona un método de evaluación por lotes asíncrono de larga duración. Es ideal para situaciones en las que no necesitas resultados inmediatos y quieres delegar el cálculo.

El método batch_evaluate() devuelve un objeto de operación que puedes sondear para monitorizar 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
)

Evaluar modelos de terceros

Puedes usar el cliente de IA generativa del SDK de Vertex AI para evaluar y comparar modelos de proveedores como OpenAI. Para ello, debes pasar 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 definir la clave de API obligatoria como 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 GenAI del SDK de Vertex AI te permite visualizar los resultados directamente en tu entorno de desarrollo, como un cuaderno de Colab o Jupyter. El método .show(), disponible en los objetos EvaluationDataset y EvaluationResult, genera un informe HTML interactivo para el análisis.

Visualizar 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 peticiones y referencias originales. Esto resulta útil para hacer una comprobación de calidad rápida antes de realizar 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 petición, su referencia correspondiente (si se ha proporcionado) y la respuesta recién generada.

Visualizar 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 de todo el conjunto de datos.

• Resultados detallados: un desglose caso por caso que te permite inspeccionar la petición, la referencia, la respuesta candidata y la puntuación y la explicación específicas 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()

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

En todos los informes, puedes desplegar la sección Ver JSON sin formato para inspeccionar los datos de cualquier petición o respuesta estructurada.

Siguientes pasos

• Prueba la guía de inicio rápido de la evaluación.

• Define tus métricas de evaluación.