> ## Documentation Index > Fetch the complete documentation index at: https://docs.mka1.com/llms.txt > Use this file to discover all available pages before exploring further. # Projetar suítes de tarefas de avaliação > Defina manifestos de avaliação com arquivos enviados, conjuntos de dados do Hugging Face, modelos de prompt, exemplos few-shot, extração de saída, métricas e parâmetros de geraçã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](/pt/docs/evals). Para contratos de pontuação em Python, consulte [Escrever avaliadores de avaliação em Python](/pt/docs/evals-python-graders). ## Estrutura do manifesto Cada versão da suíte armazena um manifesto. ```json theme={null} { "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. ```json theme={null} { "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: ```json eval.jsonl theme={null} {"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: ```csv eval.csv theme={null} 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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "num_fewshot": 2 } ``` Forma expandida: ```json theme={null} { "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. ```json theme={null} { "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: ```json theme={null} { "output_extraction": { "type": "regex", "pattern": "Answer:\\s*([A-D])", "group": 1, "flags": "i" } } ``` ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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.