Esquema de conjunto de dados de avaliação no Microsoft Foundry

Cada linha em um arquivo JSONL de avaliação contém um caso de teste de avaliação. O cenário de avaliação determina sua coluna primária necessária, enquanto os avaliadores selecionados podem exigir colunas de suporte.

Os requisitos adicionais dependem dos avaliadores selecionados. Por exemplo, um avaliador de similaridade textual pode exigir ground_truth, a fundamentação pode exigir context quando query e response são cadeias de caracteres, e um avaliador de agente pode exigir tool_definitions. Para os requisitos dos avaliadores, consulte avaliadores integrados.

Avaliações baseadas em rastreamentos existentes, IDs de resposta ou consultas sintéticas geradas não exigem um conjunto de dados de entrada.

Colunas padrão

As colunas padrão dependem se a avaliação usa dados de interação de modelo ou agente ou simulação de conversa.

Colunas para avaliação de modelos e agentes

Use um formato de interação para cada caso de teste: ou a coluna messages, ou as colunas separadas query e response.

Colunas de simulação de conversa

Formato de mensagens

A messages coluna é uma matriz. Cada mensagem identifica uma função e seu conteúdo. Uma linha pode conter uma troca de mensagens ou uma conversa completa com vários turnos.

O exemplo de execução a seguir contém uma breve interação de suporte à conta:

{
  "messages": [
    {"role": "system", "content": "You are an account support assistant."},
    {"role": "user", "content": "I can't sign in to my account."},
    {"role": "assistant", "content": "What error message do you see?"},
    {"role": "user", "content": "It says my password is incorrect."},
    {"role": "assistant", "content": "Use the password-reset link on the sign-in page. If the reset email doesn't arrive, check your spam folder or contact account support."}
  ]
}

Este exemplo inclui uma resposta de agente armazenada, portanto, a mensagem final tem a função assistant. Para um modelo ou agente de destino, termine o array messages com uma mensagem user. A Foundry envia as mensagens para o destino, gera a próxima resposta do assistente e avalia essa resposta.

Para avaliação em nível de turno, as mensagens anteriores fornecem contexto para a resposta que está sendo pontuada. Neste exemplo, um avaliador pode pontuar as diretrizes finais de redefinição de senha usando as mensagens anteriores como contexto. Para avaliação em nível de conversa, um avaliador pontua a interação completa. A evaluation_level configuração na execução seleciona o nível de pontuação; a messages linha permanece a mesma.

Para obter mais informações, consulte Escolher um nível de avaliação.

Estrutura de mensagens

Cada mensagem tem um role e content. O content valor pode ser uma cadeia de caracteres ou uma matriz de itens de conteúdo tipado. As mensagens de resultado da ferramenta também usam tool_call_id para identificar a chamada de ferramenta correspondente.

As mensagens de texto seguem a estrutura de mensagens do OpenAI Responses. As mensagens de entrada podem ser usadas input_texte a saída do assistente pode usar output_text. A avaliação do Foundry também permite a abreviação text e os itens de conteúdo normalizados tool_call e tool_result mostrados neste artigo.

[
  {
    "role": "developer" | "system" | "user" | "assistant" | "tool",
    "tool_call_id": "string",              // For role "tool"
    "content": "string" | [                // String or content-item array
      {
        "type": "text" | "input_text" | "output_text" | "tool_call" | "tool_result",
        "text": "string",                  // For text content
        "tool_call_id": "string",          // When type is tool_call
        "name": "string",                  // Tool name for tool_call
        "arguments": { ... },              // Tool arguments for tool_call
        "tool_result": { ... }             // Result for tool_result
      }
    ]
  }
]

Mensagens com matrizes de conteúdo

O content valor também pode ser uma matriz de itens de conteúdo tipado em vez de uma cadeia de caracteres. Este exemplo usa os tipos input_text e output_text da Responses API:

{
  "messages": [
    {
      "role": "developer",
      "content": [
        {"type": "input_text", "text": "You are an account support assistant."}
      ]
    },
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "I can't sign in to my account."}
      ]
    },
    {
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "What error message do you see?"}
      ]
    }
  ]
}

Mensagens com chamadas de ferramenta

Essa variação do exemplo em execução inclui uma chamada de ferramenta e seu resultado:

{
  "messages": [
    {"role": "system", "content": "You are an account support assistant."},
    {"role": "user", "content": "I can't sign in to my account."},
    {"role": "assistant", "content": [{"type": "tool_call", "tool_call_id": "call_123", "name": "get_sign_in_guidance", "arguments": {"error": "incorrect password"}}]},
    {"role": "tool", "tool_call_id": "call_123", "content": [{"type": "tool_result", "tool_result": {"recommended_action": "password reset"}}]},
    {"role": "assistant", "content": [{"type": "text", "text": "Use the password-reset link on the sign-in page. If the reset email doesn't arrive, check your spam folder or contact account support."}]}
  ]
}

Colunas específicas do avaliador

A maioria das avaliações precisa apenas da coluna de interação primária. Adicione colunas de suporte quando um avaliador selecionado as exigir.

Verdade básica

ground_truth é uma cadeia de caracteres que contém a resposta esperada ou de referência. Inclua-o quando um avaliador compara a saída do modelo ou do agente com uma resposta conhecida.

{
  "messages": [
    {"role": "user", "content": "I can't sign in to my account."},
    {"role": "assistant", "content": "Use the password-reset link on the sign-in page."}
  ],
  "ground_truth": "Direct the user to reset their password from the sign-in page."
}

Definições de ferramenta

tool_definitions descreve as ferramentas disponíveis para o agente. A matriz messages mostra o que o agente chamou. tool_definitions fornece os nomes, descrições e esquemas de parâmetro de todas as ferramentas que o agente poderia usar.

Inclua esta coluna quando um avaliador precisar comparar o comportamento da ferramenta com as ferramentas disponíveis.

{
  "messages": [
    {"role": "user", "content": "I can't sign in to my account."},
    {"role": "assistant", "content": [{"type": "tool_call", "tool_call_id": "call_123", "name": "get_sign_in_guidance", "arguments": {"error": "incorrect password"}}]},
    {"role": "tool", "tool_call_id": "call_123", "content": [{"type": "tool_result", "tool_result": {"recommended_action": "password reset"}}]},
    {"role": "assistant", "content": "Use the password-reset link on the sign-in page."}
  ],
  "tool_definitions": [
    {
      "name": "get_sign_in_guidance",
      "description": "Get troubleshooting guidance for a sign-in error.",
      "parameters": {
        "type": "object",
        "properties": {
          "error": {"type": "string"}
        },
        "required": ["error"]
      }
    }
  ]
}

Para obter o esquema completo, consulte o formato de definições de ferramenta.

Contexto

context contém informações de suporte usadas para avaliar uma resposta. Essa coluna é útil principalmente com valores de string query e response quando a informação necessária ainda não está presente no histórico de mensagens. Para obter detalhes sobre essa representação, consulte Formato de consulta e resposta separados.

Por exemplo, um avaliador de fundamentação pode usar context como o material-fonte que deve embasar a resposta:

{
  "query": "How can I reset my password?",
  "response": "Use the password-reset link on the sign-in page.",
  "context": "Users can reset their password from the sign-in page."
}

Simulação de conversa

Uma semente de simulação, também chamada de cenário de caso de teste, descreve uma situação que o simulador deve representar como o usuário. test_case_description é a única coluna necessária. desired_num_turns é uma orientação opcional de simulação.

O texto inicial a seguir dá continuidade ao exemplo de login na conta:

{
  "test_case_description": "Act as a user who can't sign in and initially provides little detail. After the agent asks a clarifying question, explain that your password is being rejected. Continue until the agent gives clear password-reset guidance.",
  "desired_num_turns": 4
}

A Foundry usa um simulador para desempenhar a função do usuário e interagir com o agente de destino. Os avaliadores de nível de conversa pontuam a conversa simulada, não a linha da semente.

Para o procedimento de simulação, consulte Simular conversas. Para gerar linhas de semente em vez de criá-las manualmente, consulte Gerar um conjunto de dados de semente de simulação.

Formato de consulta e resposta separados

Alguns avaliadores e fluxos de trabalho usam colunas separadas response e query. Esse formato permanece com suporte. Ambas as colunas podem conter cadeias de caracteres ou matrizes de mensagens que usam a mesma estrutura que messages.

Use valores de cadeia de caracteres para um caso de teste simples de turno único que não precisa de histórico de conversa ou detalhes de chamada de ferramenta:

{"query":"I can't sign in to my account.","response":"Use the password-reset link on the sign-in page."}

Se query for uma matriz de mensagens, ela pode incluir instruções do sistema, turnos anteriores, chamadas de ferramenta e resultados da ferramenta. Os avaliadores usam esse histórico como contexto ao pontuar response.

{
  "query": [
    {"role": "system", "content": "You are an account support assistant."},
    {"role": "user", "content": "I can't sign in."},
    {"role": "assistant", "content": "What error do you see?"},
    {"role": "user", "content": "It says my password is incorrect."}
  ],
  "response": [
    {"role": "assistant", "content": "Use the password-reset link on the sign-in page."}
  ]
}

Quando os valores das cadeias de caracteres query e response precisarem de informações de suporte separadas, adicione uma coluna context.

Se uma execução de avaliação invocar um modelo ou agente de destino, o Foundry gerará uma nova resposta para cada entrada. Qualquer response já armazenado na linha é ignorado.

O CSV também é compatível com linhas response e query baseadas em cadeias de caracteres simples. Consulte Avaliar um conjunto de dados CSV.

Quando você precisa de um mapeamento de dados

Você pode omitir data_mapping quando um avaliador compatível usa as colunas padrão em seu conjunto de dados. Adicione um mapeamento nos seguintes casos:

• Seu conjunto de dados usa um nome diferente, como question em vez de query.
• Um modelo ou destino de agente gera texto em tempo de execução e o avaliador requer uma resposta de texto. Por exemplo, Coerência exige que a resposta mapeie de {{sample.output_text}}.
• Um alvo de agente gera saída estruturada e o avaliador exige chamadas de ferramentas ou outros itens estruturados. Por exemplo, Aderência à Tarefa exige que a resposta mapeie de {{sample.output_items}}.
• Um arquivo CSV usa cabeçalhos de coluna não padrão.

Para a sintaxe de mapeamento de {{item.*}} e {{sample.*}} com exemplos executáveis, consulte Configurar avaliadores e mapeamentos de dados. Para escolher um fluxo de trabalho geral, consulte Executar avaliações do SDK.

Próximas etapas

Configure uma execução de avaliação que usa seu conjunto de dados:

Conteúdo relacionado

• Conjuntos de dados de avaliação no Microsoft Foundry
• Avaliadores internos
• Avaliadores de agentes
• Gerar um conjunto de dados de avaliação sintética
• Converta rastros de agentes em conjuntos de dados para avaliação