Projetar suítes de tarefas de avaliação

Uma suíte de avaliação é um manifesto reutilizável. Ela descreve o que executar, como renderizar prompts, como pré-processar linhas, como extrair saídas do modelo e qual avaliador Python deve pontuar cada amostra ou lote de tarefas. Esta página aborda a superfície do manifesto. Para o fluxo completo de execução, comece com Executar avaliações. Para contratos de pontuação em Python, consulte Escrever avaliadores de avaliação em Python.

Estrutura do manifesto

Cada versão da suíte armazena um manifesto.

{
  "schema_version": "2026-05-27",
  "tasks": [
    {
      "id": "qa_exact_match",
      "name": "QA exact match",
      "type": "qa",
      "dataset": {
        "file_id": "file_dataset123",
        "format": "jsonl"
      },
      "prompt_template": "Answer with only the final answer.\n\nQuestion: {{question}}",
      "target_template": "{{answer}}",
      "output_extraction": {
        "type": "take_first",
        "lines": 1
      },
      "metrics": [
        {
          "id": "exact_match",
          "aggregation": "mean",
          "higher_is_better": true
        }
      ],
      "grader": {
        "type": "python",
        "contract": "sample",
        "file_id": "file_grader123"
      },
      "metadata": {
        "source": "qa-regression"
      }
    }
  ],
  "metadata": {
    "project": "model-quality"
  }
}

Limites do manifesto:

Limite	Valor
Tarefas por versão da suíte	1 a 100
Caracteres do ID da tarefa	Letras, números, `_`, `.` e `-`
Exemplos few-shot por amostra	0 a 100
Modelos de execução por execução	1 a 20
Concorrência de execução	1 a 25
`max_rows` do Hugging Face	Até 1.000.000

Tipos de tarefa

type identifica a tarefa para pessoas e relatórios downstream. A pontuação não é codificada de forma fixa pelo tipo de tarefa. O avaliador Python determina o comportamento real da métrica. Rótulos de tarefa compatíveis:

Tipo	Uso comum
`classification`	Classificação de rótulos ou categorias de rubrica.
`multiple_choice`	Seleção de resposta de múltipla escolha.
`qa`	Perguntas e respostas com pontuação de correspondência exata, F1, semântica ou por avaliador.
`summarization`	Verificações de qualidade, cobertura e factualidade de resumos.
`semantic_similarity`	Pontuação de embeddings ou similaridade de sentenças via Python.
`llm_judge`	Pontuação de rubrica baseada em modelo via `ctx.responses_create`.
`numeric`	Extração numérica e pontuação por tolerância.
`math`	Avaliação de respostas matemáticas ou simbólicas.
`custom`	Qualquer tarefa que não se encaixe nos outros rótulos.

Use metadata nas tarefas e execuções para seus próprios identificadores de experimento. As chaves de metadados podem ter até 64 caracteres e os valores até 512 caracteres.

Conjuntos de dados enviados

Use arquivos enviados para conjuntos de dados controlados e reproduzíveis. Envie-os por /files com purpose=evals e, em seguida, faça referência ao ID do arquivo na tarefa.

{
  "dataset": {
    "file_id": "file_dataset123",
    "format": "jsonl"
  }
}

format pode ser jsonl ou csv. Se você omiti-lo, o gateway infere o formato a partir do nome do arquivo enviado. As linhas JSONL devem ser objetos:

eval.jsonl

{"question":"2+2?","answer":"4","difficulty":"easy"}
{"question":"Capital of France?","answer":"Paris","difficulty":"easy"}

Os arquivos CSV usam a primeira linha como cabeçalhos:

eval.csv

question,answer,difficulty
2+2?,4,easy
Capital of France?,Paris,easy

Conjuntos de dados do Hugging Face

Use o Hugging Face quando sua avaliação precisar ser executada a partir de um conjunto de dados público ou privado pré-configurado. O gateway carrega linhas do servidor de conjuntos de dados do Hugging Face.

{
  "dataset": {
    "source": "huggingface",
    "path": "facebook/belebele",
    "name": "ukr_Cyrl",
    "split": "test",
    "revision": "main",
    "max_rows": 100
  }
}

Campos:

Campo	Descrição
`source`	Defina como `huggingface`. Ele é inferido quando `path` está presente.
`path`	Caminho do conjunto de dados, como `facebook/belebele`.
`name`	Configuração do conjunto de dados. Se omitido, o MKA1 tenta descobrir uma configuração para a divisão solicitada.
`split`	Divisão a ser carregada. O padrão é `test`.
`revision`	Revisão opcional do conjunto de dados.
`max_rows`	Limite opcional para carregamento e testes rápidos.
`dataset_kwargs`	Metadados adicionais de carregamento retidos para paridade com definições de avaliação existentes.

Conjuntos de dados privados do Hugging Face exigem um token do Hugging Face configurado para o ambiente do gateway. O token não é fornecido no manifesto de avaliação. Entre em contato com a MKA1 se sua equipe precisar de acesso a conjuntos de dados privados ou restritos do Hugging Face.

Builders `json` e `csv` do Hugging Face

Para path: "json" ou path: "csv", forneça data_files. Somente URLs HTTP(S) são permitidas, e hosts de rede local/privada são rejeitados.

{
  "dataset": {
    "source": "huggingface",
    "path": "json",
    "split": "validation",
    "data_files": {
      "validation": "https://huggingface.co/datasets/acme/evals/resolve/main/validation.jsonl"
    },
    "max_rows": 500
  }
}

Você também pode colocar data_files em dataset_kwargs.data_files.

Modelos

prompt_template e target_template são renderizados com valores da linha atual do conjunto de dados.

{
  "prompt_template": "Context: {{context}}\n\nQuestion: {{question}}\n\nChoices:\n{{choice_list}}\n\nAnswer:",
  "target_template": "{{answer}}",
  "choices": ["A", "B", "C", "D"]
}

Comportamento dos modelos:

Padrão	Resultado
`{{field}}`	Lê um campo de linha de nível superior.
`{{nested.field}}`	Lê um campo de objeto aninhado.
`{{row}}`	Insere a linha completa como JSON.
`{{choices}}`	Insere o array `choices` da tarefa como JSON.
`{{choice_list}}`	Insere os `choices` da tarefa unidos por quebras de linha.

Valores ausentes são renderizados como uma string vazia. Objetos e arrays são renderizados como JSON.

Exemplos few-shot

Os exemplos few-shot são renderizados antes do prompt avaliado. Use num_fewshot para manifestos no estilo lm-eval ou o objeto fewshot expandido quando precisar de mais controle.

{
  "num_fewshot": 2
}

Forma expandida:

{
  "fewshot": {
    "count": 2,
    "dataset": {
      "source": "huggingface",
      "path": "facebook/belebele",
      "name": "ukr_Cyrl",
      "split": "train"
    },
    "prompt_template": "Question: {{question}}",
    "target_template": "{{correct_answer_num}}",
    "example_template": "{{prompt}}\nAnswer: {{target}}",
    "separator": "\n\n---\n\n",
    "strategy": "first",
    "seed": 0
  }
}

Campos de few-shot:

Campo	Descrição
`count`	Número de exemplos a adicionar antes.
`dataset`	Conjunto de dados separado opcional. Se omitido, os exemplos vêm do conjunto de dados da tarefa. Conjuntos de dados few-shot do Hugging Face usam `train` por padrão quando `split` é omitido.
`prompt_template`	Modelo opcional para prompts few-shot. O padrão é o `prompt_template` da tarefa.
`target_template`	Modelo opcional para alvos few-shot. O padrão é o `target_template` da tarefa.
`example_template`	Modelo que combina `{{prompt}}` e `{{target}}` renderizados. O padrão é `{{prompt}}\n{{target}}`.
`separator`	Separador entre os exemplos e o prompt avaliado.
`strategy`	`first` ou `random`.
`seed`	Seed usada pela seleção `random`.

A linha atual é excluída quando exemplos few-shot são extraídos da mesma lista de linhas em memória.

Pré-processadores Python

Use pré-processadores para normalizar linhas do conjunto de dados antes da renderização do prompt. Eles são executados no sandbox Python com as mesmas regras de escopo de arquivo dos avaliadores.

{
  "preprocess": {
    "type": "python",
    "contract": "row",
    "source": "def transform(row):\n    row['question'] = row['question'].strip()\n    return row\n",
    "timeout_seconds": 120
  }
}

Contratos:

Contrato	Nomes de função	Uso
`row`	`transform_row(row)`, `transform(row)` ou `process_doc(row)`	Transforma uma linha por vez.
`batch`	`transform_batch(rows)` ou `process_docs(rows)`	Transforma, filtra, duplica ou une linhas como um lote.

Os pré-processadores podem retornar:

Valor de retorno	Significado
`dict`	Uma linha transformada.
`list[dict]`	Zero, uma ou muitas linhas transformadas.
`None`	Nenhuma linha para essa entrada.

Se o pré-processamento falhar, a execução falhará antes da execução de amostras para essa tarefa.

Extração de saída

A extração de saída transforma o texto bruto do modelo em extracted_output. O avaliador recebe tanto sample["output_text"] quanto sample["extracted_output"].

Tipo	Campos	Comportamento
`none`	Nenhum	Remove ruído comum do modelo e espaços em branco.
`take_first`	`lines`	Obtém a primeira linha ou linhas não vazias.
`regex`	`pattern`, `group`, `flags`	Retorna o primeiro grupo de correspondência regex.
`regex_last`	`pattern`, `group`, `flags`	Retorna o último grupo de correspondência regex.
`label_set`	`labels`, `case_sensitive`	Retorna o primeiro rótulo correspondente.
`number`	Nenhum	Extrai um valor numérico.

Exemplos:

{
  "output_extraction": {
    "type": "regex",
    "pattern": "Answer:\\s*([A-D])",
    "group": 1,
    "flags": "i"
  }
}

{
  "output_extraction": {
    "type": "label_set",
    "labels": ["positive", "neutral", "negative"],
    "case_sensitive": false
  }
}

Os padrões regex são verificados quanto à segurança. Entradas regex muito grandes e contagens excessivas de correspondências são limitadas.

Métricas

As métricas declaram quais chaves de pontuação devem ser agregadas. Os avaliadores Python produzem os valores de pontuação.

{
  "metrics": [
    {
      "id": "exact_match",
      "aggregation": "mean",
      "higher_is_better": true,
      "description": "1 when the extracted output exactly matches the target."
    }
  ]
}

Campos:

Campo	Descrição
`id`	Chave de pontuação. São permitidos letras, números, `_`, `.` e `-`.
`aggregation`	`mean` ou `none`. O padrão é `mean`.
`higher_is_better`	O padrão é `true`.
`description`	Descrição opcional para dashboards e pessoas.

Se um avaliador por amostra retornar um único float, o MKA1 o armazena no metric_id do avaliador, cujo padrão é score. Se uma tarefa por amostra omitir metrics, o MKA1 adiciona uma métrica padrão para esse metric_id. Avaliadores agregados em lote podem fornecer métricas finais da tarefa por meio de grade_batch.

Configurações de geração

A generation em nível de execução controla chamadas ao modelo candidato. Ela inclui campos normalizados de Responses, aliases do lm-eval, campos de passagem direta do provedor e controles de execução de avaliação.

{
  "generation": {
    "instructions": "Answer concisely.",
    "temperature": 0,
    "top_p": 1,
    "max_gen_toks": 128,
    "until": ["<|endoftext|>"],
    "max_retries": 2,
    "max_empty_retries": 1,
    "timeout_seconds": 120
  }
}

Campos normalizados:

Campo	Observações
`instructions`	Texto de instrução de sistema/desenvolvedor para modelos Responses compatíveis.
`temperature`, `top_p`	Controles de amostragem.
`max_output_tokens`	Limite de tokens do MKA1 Responses.
`max_gen_toks`	Alias do lm-eval para `max_output_tokens`.
`stop`	String ou lista de sequências de parada.
`until`	Alias do lm-eval para sequências de parada.
`tools`, `tool_choice`, `parallel_tool_calls`, `max_tool_calls`	Configurações de ferramentas de Responses.
`reasoning`, `text`, `truncation`, `service_tier`	Transmitidos a modelos Responses compatíveis.
`presence_penalty`, `frequency_penalty`	Configurações de penalidade.

Campos de passagem direta do provedor:

Campo	Observações
`top_k`	Para upstreams não OpenAI compatíveis.
`min_p`	Para upstreams não OpenAI compatíveis.
`repetition_penalty`	Para upstreams não OpenAI compatíveis.
`do_sample`	Para upstreams não OpenAI compatíveis.
`extra_body`	Campos extras do corpo do provedor após a remoção de chaves inseguras.
`chat_template_kwargs`	Opções de modelo de chat, como `enable_thinking`.
`prefill_think`	Controle de thinking/prefill para provedores compatíveis.
`use_cache`	Controle de cache do provedor quando compatível.

A passagem direta do provedor é enviada somente para upstreams não OpenAI compatíveis com OpenAI. Upstreams OpenAI reais recebem apenas campos compatíveis. Controles de execução:

Campo	Descrição
`timeout_seconds`	Timeout por chamada de modelo. O intervalo é de 1 a 3600.
`max_retries`	Tentativas para erros recuperáveis de provedor/rede. O intervalo é de 0 a 10.
`max_empty_retries`	Tentativas quando a saída candidata está vazia. O intervalo é de 0 a 10.

Exemplo: tarefa de múltipla escolha do Hugging Face

{
  "schema_version": "2026-05-27",
  "tasks": [
    {
      "id": "belebele_ukrainian",
      "type": "multiple_choice",
      "dataset": {
        "source": "huggingface",
        "path": "facebook/belebele",
        "name": "ukr_Cyrl",
        "split": "test",
        "max_rows": 100
      },
      "choices": ["1", "2", "3", "4"],
      "prompt_template": "Read the passage and answer with the option number only.\n\n{{flores_passage}}\n\nQuestion: {{question}}\n1. {{mc_answer1}}\n2. {{mc_answer2}}\n3. {{mc_answer3}}\n4. {{mc_answer4}}",
      "target_template": "{{correct_answer_num}}",
      "output_extraction": {
        "type": "label_set",
        "labels": ["1", "2", "3", "4"]
      },
      "metrics": [
        { "id": "accuracy" }
      ],
      "grader": {
        "type": "python",
        "contract": "sample",
        "source": "def grade(sample, item):\n    return {'scores': {'accuracy': 1.0 if sample.get('extracted_output') == item.get('target') else 0.0}}\n"
      }
    }
  ]
}

Exemplo: tarefa few-shot com uma divisão de treinamento separada

{
  "id": "fewshot_qa",
  "type": "qa",
  "dataset": {
    "source": "huggingface",
    "path": "acme/support-qa",
    "split": "test"
  },
  "fewshot": {
    "count": 3,
    "dataset": {
      "source": "huggingface",
      "path": "acme/support-qa",
      "split": "train"
    },
    "example_template": "Question: {{prompt}}\nAnswer: {{target}}",
    "separator": "\n\n"
  },
  "prompt_template": "{{question}}",
  "target_template": "{{answer}}",
  "grader": {
    "type": "python",
    "contract": "sample",
    "file_id": "file_grader123"
  }
}

Orientações de versionamento

Crie uma nova versão da suíte quando alterar qualquer comportamento que afete os resultados:

Arquivo do conjunto de dados ou caminho/configuração/divisão do Hugging Face.
Prompt, alvo, few-shot, pré-processamento ou extração de saída.
IDs de métricas ou comportamento de agregação.
Código-fonte ou ID do arquivo do avaliador Python.

Armazene escolhas específicas da execução na execução:

Modelos candidatos.
Modelo avaliador.
Modelo de embedding.
Configurações de geração.
Concorrência e limites de amostras.

Isso mantém a suíte reutilizável, ao mesmo tempo que preserva exatamente o que cada execução realizou.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Projetar suítes de tarefas de avaliação

Estrutura do manifesto

Tipos de tarefa

Conjuntos de dados enviados

Conjuntos de dados do Hugging Face

Builders `json` e `csv` do Hugging Face

Modelos

Exemplos few-shot

Pré-processadores Python

Extração de saída

Métricas

Configurações de geração

Exemplo: tarefa de múltipla escolha do Hugging Face

Exemplo: tarefa few-shot com uma divisão de treinamento separada

Orientações de versionamento

​Estrutura do manifesto

​Tipos de tarefa

​Conjuntos de dados enviados

​Conjuntos de dados do Hugging Face

​Builders json e csv do Hugging Face

​Modelos

​Exemplos few-shot

​Pré-processadores Python

​Extração de saída

​Métricas

​Configurações de geração

​Exemplo: tarefa de múltipla escolha do Hugging Face

​Exemplo: tarefa few-shot com uma divisão de treinamento separada

​Orientações de versionamento

Estrutura do manifesto

Tipos de tarefa

Conjuntos de dados enviados

Conjuntos de dados do Hugging Face

Builders `json` e `csv` do Hugging Face

Modelos

Exemplos few-shot

Pré-processadores Python

Extração de saída

Métricas

Configurações de geração

Exemplo: tarefa de múltipla escolha do Hugging Face

Exemplo: tarefa few-shot com uma divisão de treinamento separada

Orientações de versionamento