Preparar o conjunto de dados de avaliação

Nesta página, descrevemos como preparar seu conjunto de dados para o serviço de avaliação de IA generativa.

Visão geral

O serviço de avaliação de IA generativa detecta e processa automaticamente vários formatos de dados comuns. Isso significa que, muitas vezes, você pode usar seus dados como estão, sem precisar fazer conversões manuais.

Os campos que você precisa fornecer no conjunto de dados dependem do seu objetivo:

Objetivo Dados obrigatórios Fluxo de trabalho do SDK
Gerar novas respostas e avaliá-las prompt run_inference() → evaluate()
Avaliar respostas atuais prompt e response evaluate()
Gerar novos resultados de execução do agente e avaliá-los prompt run_inference() → evaluate()
Avaliar respostas do agente e eventos intermediários prompt, response e intermediate_events evaluate()

Ao executar client.evals.evaluate() ou client.evals.create_evaluation_run(), o serviço de avaliação de IA generativa procura automaticamente os seguintes campos comuns no conjunto de dados:

  • prompt: (obrigatório) a entrada do modelo que você quer avaliar. Para melhores resultados, forneça exemplos de comandos que representem os tipos de entradas que seus modelos processam na produção.

  • response: (obrigatório) a saída gerada pelo modelo ou aplicativo que está sendo avaliado.

  • reference: (opcional) a verdade básica ou resposta "ideal" que você pode comparar com a resposta do modelo. Esse campo geralmente é obrigatório para métricas baseadas em computação, como bleu e rouge.

  • conversation_history: (opcional) uma lista de turnos anteriores em uma conversa com vários turnos. O serviço de avaliação de IA generativa extrai esse campo automaticamente de formatos compatíveis. Para mais informações, consulte Como lidar com conversas com vários turnos.

  • session_inputs: (opcional) entrada para inicializar uma sessão para executar um agente. Isso só é opcional para o fluxo de trabalho run_inference() → evaluate().

  • intermediate_events: (opcional) rastreamentos de agente de um único turno em uma execução do agente, incluindo chamadas de função, respostas de função e respostas intermediárias do modelo. Esse campo não é obrigatório para o fluxo de trabalho run_inference() → evaluate().

Formatos de dados compatíveis

O serviço de avaliação de IA generativa oferece suporte aos seguintes formatos:

DataFrame do Pandas

Para avaliações simples, você pode usar um pandas.DataFrame. O serviço de avaliação de IA generativa procura nomes de colunas comuns, como prompt, response e reference. Esse formato é totalmente compatível com versões anteriores.

import pandas as pd

# Example 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",
    ]
})

# You can use this DataFrame directly with run_inference or evaluate
eval_dataset = client.evals.run_inference(model="gemini-2.5-flash", src=prompts_df)
eval_result = client.evals.evaluate(
    dataset=eval_dataset,
    metrics=[types.PrebuiltMetric.GENERAL_QUALITY]
)
eval_result.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 Gemini Enterprise Agent Platform, que geralmente são arquivos JSONL armazenados no Cloud Storage, em que cada linha contém um objeto de solicitação e resposta. O serviço de avaliação de IA generativa analisa essa estrutura automaticamente para fornecer integração com outros serviços da Gemini Enterprise Agent Platform.

Confira a seguir um 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, você pode avaliar 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 pre-generated responses directly
eval_result = client.evals.evaluate(
    dataset=batch_job_output_uri,
    metrics=[types.PrebuiltMetric.GENERAL_QUALITY]
)
eval_result.show()

Formato de conclusão de chat da OpenAI

Para avaliar ou comparar com modelos de terceiros, como OpenAI e Anthropic, o serviço de avaliação de IA generativa oferece suporte ao 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 de API da OpenAI. O serviço de avaliação de IA generativa detecta esse formato automaticamente.

Confira a seguir um 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 avaliar as respostas:

# 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",  # LiteLLM compatible model string
    src=openai_request_uri,
)

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

Como lidar com conversas com vários turnos

O serviço de avaliação de IA generativa analisa automaticamente dados de conversas com vários turnos de formatos compatíveis. Quando os dados de entrada incluem um histórico de trocas (como no campo request.contents no formato Gemini ou request.messages no formato OpenAI), o serviço de avaliação de IA generativa identifica os turnos anteriores e os processa como conversation_history.

Isso significa que não é necessário separar manualmente o comando atual da conversa anterior, já que as métricas de avaliação podem usar o histórico da conversa para entender o contexto da resposta do modelo.

Confira a seguir um exemplo de uma conversa com vários turnos no formato Gemini:

{
  "request": {
    "contents": [
      {"role": "user", "parts": [{"text": "I'm planning a trip to Paris."}]},
      {"role": "model", "parts": [{"text": "That sounds wonderful! What time of year are you going?"}]},
      {"role": "user", "parts": [{"text": "I'm thinking next spring. What are some must-see sights?"}]}
    ]
  },
  "response": {
    "candidates": [
      {"content": {"role": "model", "parts": [{"text": "For spring in Paris, you should definitely visit the Eiffel Tower, the Louvre Museum, and wander through Montmartre."}]}}
    ]
  }
}

A conversa com vários turnos é analisada automaticamente da seguinte maneira:

  • prompt: a última mensagem do usuário é identificada como o comando atual ({"role": "user", "parts": [{"text": "I'm thinking next spring. What are some must-see sights?"}]}).

  • conversation_history: as mensagens anteriores são extraídas automaticamente e disponibilizadas como o histórico da conversa ([{"role": "user", "parts": [{"text": "I'm planning a trip to Paris."}]}, {"role": "model", "parts": [{"text": "That sounds wonderful! What time of year are you going?"}]}]).

  • response: a resposta do modelo é extraída do campo response ({"role": "model", "parts": [{"text": "For spring in Paris..."}]}).

A seguir