Tutorial: realizar uma avaliação usando o cliente da IA generativa no SDK da Vertex AI

Nesta página, mostramos como avaliar seus modelos e aplicativos de IA generativa em vários casos de uso usando o cliente GenAI no SDK da Vertex AI.

O cliente de IA generativa no SDK da Vertex AI para o serviço de avaliação de IA generativa permite medir a performance de comandos, modelos de fundação e agentes de IA complexos de acordo com os critérios mais relevantes. É possível avaliar qualquer número de candidatos de uma só vez para ajustar comandos, selecionar o melhor modelo ou iterar em agentes complexos.

Com o cliente da IA generativa no SDK da Vertex AI, é possível fazer o seguinte:

  • Compare vários modelos ou configurações lado a lado em uma única execução usando cálculos de taxa de vitória para orientar suas decisões.

  • Use o suporte integrado para avaliar e comparar com modelos de terceiros conhecidos sem integrações complexas.

  • Gerencie grandes conjuntos de dados com mais eficiência e descarregue tarefas de avaliação em grande escala usando a avaliação assíncrona em lote.

Exemplo completo

O cliente de IA generativa no SDK da Vertex AI usa um fluxo de trabalho de duas etapas: gerar respostas do modelo e avaliar as respostas. O exemplo completo a seguir mostra como o cliente de IA generativa no SDK da Vertex AI funciona:

  1. Instale o SDK da Vertex AI para Python:

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

  2. Prepare o conjunto de dados de avaliação:

    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. Execute a avaliação:

    # 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 vários 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 sua métrica

Defina suas métricas como baseadas em LLM ou baseadas em computação.

Métricas baseadas em LLM

As métricas baseadas em LLM usam um modelo de linguagem grande (LLM) como um "juiz" para avaliar critérios sutis, como estilo ou qualidade da escrita, que são difíceis de medir apenas com algoritmos.

Usar métricas gerenciadas com base em rubricas

O cliente de IA generativa no SDK da Vertex AI oferece várias métricas baseadas em modelos prontas para uso, como GENERAL_QUALITY, SAFETY e INSTRUCTION_FOLLOWING. É possível acessar esses elementos pela classe RubricMetric. As definições de métricas gerenciadas com base em rubricas são carregadas sob demanda de uma biblioteca centralizada para criar consistência entre as versões de métricas com base em rubricas.

# 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 criar resultados consistentes em diferentes versões do SDK, fixe uma métrica em uma versão específica. Por padrão, a versão mais recente é usada.

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

Personalizar métricas de LLM

Para casos de uso que exigem critérios especializados, é possível definir sua própria métrica baseada em LLM instanciando a classe LLMMetric. Isso dá a você controle total sobre o modelo de comando de avaliação, o modelo juiz e outros parâmetros.

A classe auxiliar MetricPromptBuilder cria um modelo de comando estruturado para o modelo de avaliação, permitindo que você defina instruction, criteria e rating_scores separadamente.

# 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 com base em computação e função personalizada

Métricas baseadas em computação comparam matematicamente a saída de um modelo com uma informação empírica ou referência. Essas métricas, calculadas com código usando a classe base Metric, oferecem suporte a algoritmos predefinidos baseados em computação, como exact_match, bleu e rouge_1. Para usar uma métrica baseada em computação, crie uma instância da classe Metric com o nome da métrica. A métrica exige uma coluna reference no conjunto de dados para comparação.

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

Implementar uma métrica de função personalizada

Também é possível implementar uma lógica de avaliação personalizada transmitindo uma função Python personalizada ao parâmetro custom_function para ter controle total. O cliente da GenAI no SDK da Vertex AI executa essa função para cada linha do conjunto de dados.

# 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 o conjunto de dados de avaliação

O cliente de IA generativa no SDK da Vertex AI detecta e processa automaticamente vários formatos de dados comuns. Isso significa que você pode usar seus dados como estão, sem precisar fazer conversões manuais, seja gerando novas respostas com o run_inference ou avaliando as atuais com o evaluate.

O cliente de IA generativa no SDK da Vertex AI oferece suporte aos seguintes formatos:

  • DataFrame do Pandas (formato simplificado)

    Para avaliações simples, use um pandas.DataFrame. O cliente da GenAI no SDK da Vertex AI procura nomes de colunas comuns, como prompt, response e reference. Esse formato é totalmente compatível com versões anteriores.

    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 previsão em lote do Gemini

    Você pode usar diretamente a saída de um job de previsão em lote da Vertex AI, que geralmente são arquivos JSONL armazenados no Cloud Storage, em que cada linha contém um objeto request e response. O cliente de IA generativa no SDK da Vertex AI analisa essa estrutura automaticamente para fornecer integração com outros serviços da Vertex AI.

    Exemplo de uma única linha em um arquivo 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."}]}}]}}

    Em seguida, avalie as respostas pré-geradas de um job em lote diretamente:

    # 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 conclusão de chat da OpenAI

    Para avaliar ou comparar com modelos de terceiros, o cliente GenAI no SDK da Vertex AI é compatível com o formato de conclusão de chat da OpenAI. Você pode fornecer um conjunto de dados em que cada linha é um objeto JSON estruturado como uma solicitação da API OpenAI. O cliente de IA generativa no SDK da Vertex AI detecta automaticamente esse formato.

    Exemplo de uma única linha nesse formato:

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

    Você pode usar esses dados para gerar respostas de um modelo de terceiros e avaliá-las:

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

Executar avaliação

O cliente de IA generativa no SDK da Vertex AI usa o seguinte processo baseado em cliente para executar avaliações:

  1. run_inference(): gere respostas do seu modelo para um determinado conjunto de comandos.

  2. evaluate(): calcula métricas nas respostas geradas.

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 analisar o desempenho de vários modelos ou sistemas de IA em uma única avaliação, gere uma resposta para cada candidato e transmita-as em uma lista para o 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()

Avaliação assíncrona e em grande escala

Para grandes conjuntos de dados, o cliente de IA generativa no SDK da Vertex AI oferece um método de avaliação em lote assíncrono e de longa duração. Isso é ideal para cenários em que você não precisa de resultados imediatos e quer descarregar a computação.

O método batch_evaluate() retorna um objeto de operação que pode ser pesquisado para acompanhar o progresso. Os parâmetros são compatíveis com o 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
)

Como avaliar modelos de terceiros

É possível usar o cliente GenAI no SDK da Vertex AI para avaliar e comparar modelos de provedores como a OpenAI transmitindo a string do nome do modelo para o método run_inference. O cliente de IA generativa no SDK da Vertex AI usa a biblioteca litellm para chamar a API do modelo.

Defina a chave de API necessária como uma variável de ambiente (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()

Visualização

Com o cliente de IA generativa no SDK da Vertex AI, é possível visualizar os resultados diretamente no ambiente de desenvolvimento, como um notebook do Colab ou do Jupyter. O método .show(), disponível nos objetos EvaluationDataset e EvaluationResult, renderiza um relatório HTML interativo para análise.

Como visualizar os resultados da inferência

Depois de gerar respostas com run_inference(), chame .show() no objeto EvaluationDataset resultante para inspecionar as saídas do modelo junto com seus comandos e referências originais. Isso é útil para uma verificação rápida de qualidade antes de executar uma avaliação 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()

Uma tabela é exibida com cada comando, a referência correspondente (se fornecida) e a resposta recém-gerada.

Como visualizar os resultados da inferência

Visualizar relatórios de avaliação

Quando você chama .show() em um objeto EvaluationResult, um relatório é exibido com duas seções principais:

  • Métricas de resumo: uma visão agregada de todas as métricas, mostrando a pontuação média e o desvio padrão em todo o conjunto de dados.

  • Resultados detalhados: uma análise caso a caso que permite inspecionar o comando, a referência, a resposta candidata e a pontuação e explicação 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()

Relatório de avaliação

O formato do relatório se adapta dependendo de você estar avaliando um único candidato ou comparando vários. Para uma avaliação com vários candidatos, o relatório oferece uma visualização lado a lado e inclui cálculos de taxa de vitória/empate na tabela de resumo.

Em todos os relatórios, é possível abrir uma seção Ver JSON bruto para inspecionar os dados de qualquer comando ou resposta estruturada.

Comparação detalhada

A seguir