Execute uma avaliação.

Nesta página, mostramos como executar avaliações para seus modelos e aplicativos de linguagem generativa com o serviço de avaliação de IA generativa.

Antes de começar

Instale o SDK da Vertex AI

Para instalar o módulo de avaliação de IA generativa do SDK da Vertex AI para Python, execute o seguinte comando:

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

Para mais informações, consulte Instalar o SDK da Vertex AI para Python.

Autenticar o SDK da Vertex AI

Depois de instalar o SDK da Vertex AI para Python, é preciso fazer a autenticação. Os tópicos a seguir explicam como autenticar com o SDK da Vertex AI se você estiver trabalhando localmente e no Colaboratory:

  • Se você estiver desenvolvendo localmente, configure o Application Default Credentials (ADC) no seu ambiente local:

    1. Instale a Google Cloud CLI e inicialize-a executando o seguinte comando:

      gcloud init

    2. Crie as credenciais de autenticação para sua Conta do Google:

      gcloud auth application-default login

      Uma tela de login será exibida. Após o login, suas credenciais são armazenadas no arquivo de credenciais local usado pelo ADC. Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

  • Se você estiver trabalhando no Colaboratory, execute o seguinte comando em uma célula do Colab para autenticar:

    from google.colab import auth
auth.authenticate_user()

    Esse comando abre uma janela em que você pode concluir a autenticação.

Como entender as contas de serviço

A conta de serviço é usada pelo serviço de avaliação de IA generativa para receber previsões da API Gemini na Vertex AI sobre métricas de avaliação baseadas em modelo. Essa conta de serviço é provisionada automaticamente na primeira solicitação para o serviço de avaliação de IA generativa.

Nome Descrição Endereço de e-mail Papel
Agente de serviço de avaliação rápida do Vertex AI A conta de serviço usada para receber previsões para avaliação baseada em modelo. service-PROJECT_NUMBER@gcp-sa-vertex-eval.iam.gserviceaccount.com roles/aiplatform.rapidevalServiceAgent

As permissões associadas ao agente de serviço de avaliação rápida são:

Papel Permissões
Agente de serviço de avaliação rápida da Vertex AI (roles/aiplatform.rapidevalServiceAgent) aiplatform.endpoints.predict

Executar a avaliação

O serviço de avaliação de IA generativa 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.TEXT_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()

Revisar ou reutilizar rubricas geradas para avaliação

Para pré-gerar rubricas adaptativas e revisá-las antes da avaliação ou reutilizar rubricas geradas anteriormente, use o seguinte código:

# Step 1. Generate rubrics
# Rubrics would be saved in a group named "general_quality_rubrics".
data_with_rubrics = client.evals.generate_rubrics(
    src=prompts_df,
    rubric_group_name="general_quality_rubrics",
    predefined_spec_name=types.RubricMetric.GENERAL_QUALITY,
)

# Step 2. Run Inference
eval_dataset = client.evals.run_inference(
    model=inference_model,
    src=data_with_rubrics,
)

# Step 3. Evaluate with provided rubrics
# The group of rubric named "general_quality_rubrics" will be used for evaluation.
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.RubricMetric.GENERAL_QUALITY(
      rubric_group_name="general_quality_rubrics",
    )],
)

  • generate_rubrics(): gere rubricas com um fluxo de trabalho predefinido associado à métrica.

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

  • evaluate(): valida as respostas com base nas rubricas fornecidas.

Avaliação assíncrona e em grande escala

Para grandes conjuntos de dados, o serviço de avaliação de IA generativa 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

Você pode usar o serviço de avaliação de IA generativa para avaliar e comparar modelos de provedores como a OpenAI transmitindo a string do nome do modelo para o método run_inference. O serviço de avaliação de IA generativa usa a biblioteca litellm para chamar a API do modelo.

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

eval_result.show()

A seguir