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 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 da sua meta:

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

Ao executar client.evals.evaluate(), o serviço de avaliação de IA generativa procura automaticamente os seguintes campos comuns no seu 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 em produção.

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

  • reference: (opcional) a resposta de informações empíricas ou "ideal" que você pode usar para 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 de várias rodadas. O serviço de avaliação de IA generativa extrai automaticamente esse campo dos formatos compatíveis. Para mais informações, consulte Como lidar com conversas de várias rodadas.

Formatos de dados compatíveis

O serviço de avaliação de IA generativa é compatível com os seguintes formatos:

DataFrames da Pandas

Para avaliações simples, use 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

É possível 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 de solicitação e resposta. O serviço de avaliação de IA generativa analisa essa estrutura automaticamente para oferecer integração com outros serviços da Vertex AI.

Confira 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, 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 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 é 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 serviço de avaliação de IA generativa detecta automaticamente esse formato.

Confira 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 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",  # 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 multiturno

O serviço de avaliação de IA generativa analisa automaticamente os dados de conversas de várias rodadas em formatos compatíveis. Quando os dados de entrada incluem um histórico de trocas (como no campo request.contents no formato do Gemini ou request.messages no formato da OpenAI), o serviço de avaliação de IA generativa identifica as rodadas anteriores e as 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 de conversas para entender o contexto da resposta do modelo.

Confira um exemplo de conversa multiturno no formato do 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 forma:

  • 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