Executar avaliações

Use avaliações quando precisar medir o comportamento do modelo em relação às suas próprias tarefas, conjuntos de dados, código de pontuação e configurações operacionais. Uma avaliação possui duas camadas:

Camada	O que armazena
Suíte	Um manifesto versionado com tarefas, conjuntos de dados, modelos de prompt, pré-processadores, avaliadores e definições de métricas.
Execução	Uma execução durável de uma versão da suíte em um ou mais modelos, com configurações de geração, modelo juiz, modelo de embeddings, concorrência e artefatos de resultado.

As execuções de avaliação usam o roteamento normal do MKA1. As gerações candidatas passam por POST /api/v1/llm/responses. Os avaliadores Python baseados em modelo chamam Responses e Embeddings por meio de uma ponte pertencente ao gateway, para que o código do avaliador nunca receba sua chave de API.

Antes de começar

Você precisa de:

Requisito	Observações
Escopos da chave de API	Use uma chave com `write:evals` para criar suítes e execuções, `read:evals` para ler resultados e acesso de upload de arquivos para `/files`.
Acesso ao modelo candidato	O criador da execução escolhe os IDs dos modelos candidatos em `models`.
Acesso opcional ao modelo juiz	Necessário quando avaliadores Python chamam `ctx.responses_create(model="meetkai:functionary-pt", ...)`.
Acesso opcional ao modelo de embeddings	Necessário quando avaliadores Python chamam `ctx.embeddings_create(model="meetkai:functionary-pt", ...)`.
Conjunto de dados	Faça upload de JSONL/CSV com `purpose=evals` ou faça referência a um conjunto de dados compatível do Hugging Face.
Avaliador Python	Forneça Python embutido no manifesto ou faça upload de um arquivo `.py` com `purpose=evals`.

Use X-On-Behalf-Of quando a avaliação pertencer a um contexto específico de usuário final. Suítes, execuções, arquivos de avaliação enviados e artefatos de resultado são delimitados ao contexto da equipe autenticada.

Fluxo de trabalho

O fluxo normal é:

Faça upload do conjunto de dados e dos arquivos Python opcionais por meio de /files.
Crie uma suíte de avaliação com um manifesto.
Inicie uma execução de avaliação para um ou mais modelos.
Consulte a execução até que ela alcance um status terminal.
Inspecione as linhas das amostras e baixe os arquivos de artefato gerados.
Crie uma nova versão da suíte ao editar o manifesto.

Os status da execução de avaliação passam por:

queued -> in_progress -> finalizing -> completed
       \                         \-> failed
        \-> cancelling -> cancelled

Os status das amostras são queued, generating, ready_to_score, scoring, running, completed e failed.

Etapa 1 - Fazer upload de um conjunto de dados

Faça upload de arquivos JSONL ou CSV com purpose=evals. JSONL preserva objetos e arrays aninhados. Os valores CSV são analisados como strings.

eval-smoke.jsonl

{"question":"Repeat exactly: MKA1_EVAL_SMOKE_OK","answer":"MKA1_EVAL_SMOKE_OK"}

const form = new FormData();
form.append('purpose', 'evals');
form.append('file', new Blob([
  '{"question":"Repeat exactly: MKA1_EVAL_SMOKE_OK","answer":"MKA1_EVAL_SMOKE_OK"}\n',
], { type: 'application/jsonl' }), 'eval-smoke.jsonl');

const fileRes = await fetch('https://apigw.mka1.com/api/v1/llm/files', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MKA1_API_KEY}`,
    'X-On-Behalf-Of': '<end-user-id>',
  },
  body: form,
});

const datasetFile = await fileRes.json();
console.log(datasetFile.id);

curl https://apigw.mka1.com/api/v1/llm/files \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --form 'purpose=evals' \
  --form 'file=@./eval-smoke.jsonl;type=application/jsonl'

Armazene o ID file-... retornado.

Etapa 2 - Fazer upload de um arquivo de avaliador Python

Você pode inserir o código-fonte do avaliador diretamente no manifesto. Para avaliadores reutilizáveis, faça upload de arquivos Python com purpose=evals.

exact_match_grader.py

def grade(sample, item):
    output = (sample.get("extracted_output") or "").strip()
    target = (item.get("target") or "").strip()
    return {
        "scores": {
            "exact_match": 1.0 if output == target else 0.0
        },
        "judge": {
            "output": output,
            "target": target
        }
    }

Bash

curl https://apigw.mka1.com/api/v1/llm/files \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --form 'purpose=evals' \
  --form 'file=@./exact_match_grader.py;type=text/x-python'

Armazene o ID file-... do avaliador retornado.

Etapa 3 - Criar uma suíte

Um manifesto de suíte define uma ou mais tarefas. Cada tarefa renderiza um prompt a partir de uma linha do conjunto de dados, envia o prompt a cada modelo da execução, extrai a saída do modelo e avalia a amostra.

Bash

curl https://apigw.mka1.com/api/v1/llm/evals/suites \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "name": "Production smoke eval",
    "description": "A minimal uploaded JSONL and Python grader eval.",
    "manifest": {
      "schema_version": "2026-05-27",
      "tasks": [
        {
          "id": "repeat_exactly",
          "type": "custom",
          "dataset": {
            "file_id": "file_dataset123",
            "format": "jsonl"
          },
          "prompt_template": "{{question}}",
          "target_template": "{{answer}}",
          "output_extraction": {
            "type": "none"
          },
          "metrics": [
            { "id": "exact_match" }
          ],
          "grader": {
            "type": "python",
            "contract": "sample",
            "file_id": "file_grader123",
            "timeout_seconds": 120
          }
        }
      ]
    },
    "metadata": {
      "owner": "eval-team"
    }
  }'

A resposta retorna um objeto eval.suite. Use o id da suíte ao iniciar uma execução.

Etapa 4 - Iniciar uma execução

Uma execução escolhe o modelo ou os modelos a testar. Ela também pode escolher um subconjunto de tarefas, modelo juiz, modelo de embeddings, configurações de geração, concorrência e limite de amostras.

Bash

curl https://apigw.mka1.com/api/v1/llm/evals/runs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "suite_id": "eval_suite_abc123",
    "models": [
      "openai:gpt-4.1-mini"
    ],
    "task_ids": [
      "repeat_exactly"
    ],
    "generation": {
      "temperature": 0,
      "max_output_tokens": 32,
      "max_retries": 1,
      "max_empty_retries": 1,
      "timeout_seconds": 120
    },
    "generation_concurrency": 1,
    "grader_concurrency": 1,
    "max_samples_per_task": 1,
    "metadata": {
      "experiment": "smoke"
    }
  }'

Campos úteis da execução:

Campo	Finalidade
`suite_id`	Suíte a executar.
`suite_version`	Número de versão imutável opcional. O padrão é a versão ativa da suíte.
`models`	IDs dos modelos candidatos. Máximo de 20 por execução. IDs de modelo duplicados são rejeitados.
`task_ids`	Subconjunto opcional de IDs de tarefa. Omita-o para executar todas as tarefas na versão da suíte.
`judge_model`	Modelo usado quando o código do avaliador Python chama `ctx.responses_create(model="meetkai:functionary-pt", ...)`.
`embedding_model`	Modelo usado quando o código do avaliador Python chama `ctx.embeddings_create(model="meetkai:functionary-pt", ...)`.
`generation`	Configurações do modelo candidato e controles de execução da avaliação.
`generation_concurrency`	Número de amostras a gerar simultaneamente. O intervalo é de 1 a 256.
`grader_concurrency`	Número de amostras a avaliar simultaneamente. O intervalo é de 1 a 256.
`max_samples_per_task`	Limite opcional para testes de fumaça ou execuções parciais.

Etapa 5 - Consultar a execução

Bash

curl https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123 \
  --header 'Authorization: Bearer <mka1-api-key>'

Enquanto uma execução está ativa, metrics é null ou está vazio. Quando ela é concluída, as métricas são agrupadas por modelo e por tarefa:

{
  "status": "completed",
  "request_counts": {
    "total": 3,
    "completed": 3,
    "failed": 0
  },
  "metrics": {
    "by_model": {
      "openai:gpt-4.1-mini": {
        "sample_count": 3,
        "failed_count": 0,
        "metrics": {
          "exact_match": 1
        }
      }
    },
    "by_task": {
      "repeat_exactly": {
        "openai:gpt-4.1-mini": {
          "sample_count": 1,
          "failed_count": 0,
          "metrics": {
            "exact_match": 1
          }
        }
      }
    }
  }
}

Etapa 6 - Inspecionar amostras

Liste as amostras quando precisar depurar cada linha. Você pode filtrar por task_id, model ou status.

Bash

curl 'https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123/samples?limit=10&task_id=repeat_exactly' \
  --header 'Authorization: Bearer <mka1-api-key>'

Você também pode:

Filtrar por uma faixa de pontuação numérica usando score_metric + score_min/score_max.
Ignorar linhas grandes (como áudio embutido) definindo include_dataset_row=false (as amostras retornarão dataset_row: null).
Buscar apenas índices de amostra específicos usando sample_index (índices separados por vírgulas).

Cada amostra inclui a linha de origem, o prompt renderizado, o destino, o response_id armazenado de Responses, a saída bruta do modelo, a saída extraída, as pontuações, os detalhes do juiz e os detalhes de erro.

{
  "object": "eval.sample",
  "task_id": "repeat_exactly",
  "model": "openai:gpt-4.1-mini",
  "status": "completed",
  "dataset_row": {
    "question": "Repeat exactly: MKA1_EVAL_SMOKE_OK",
    "answer": "MKA1_EVAL_SMOKE_OK"
  },
  "prompt": "Repeat exactly: MKA1_EVAL_SMOKE_OK",
  "target": "MKA1_EVAL_SMOKE_OK",
  "response_id": "resp_...",
  "output_text": "MKA1_EVAL_SMOKE_OK",
  "extracted_output": "MKA1_EVAL_SMOKE_OK",
  "scores": {
    "exact_match": 1
  },
  "judge": {
    "output": "MKA1_EVAL_SMOKE_OK",
    "target": "MKA1_EVAL_SMOKE_OK"
  },
  "error": null
}

Buscar áudio de amostra (tarefas de transcrição)

Para avaliações de transcrição, as listas de amostras podem ocultar blobs de áudio data: embutidos em dataset_row. Para buscar a referência do clipe de uma única amostra, chame: GET /api/v1/llm/evals/runs/{run_id}/samples/{sample_index}/audio Se uma execução incluir mais de uma tarefa de transcrição e o mesmo sample_index puder corresponder a várias tarefas, passe task_id ou a API retornará 400.

Bash

curl 'https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123/samples/0/audio?task_id=Common_voice' \
  --header 'Authorization: Bearer <mka1-api-key>'

A resposta inclui { object, audio, sample_index, task_id, model }, em que audio é uma URI data: em base64 ou uma URL.

Etapa 7 - Buscar artefatos

Execuções concluídas criam arquivos de resultado com purpose=evals. Use o endpoint de artefatos para localizar os IDs dos arquivos de artefato de resultado e de amostras.

Bash

curl https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123/artifacts \
  --header 'Authorization: Bearer <mka1-api-key>'

Depois, baixe os arquivos por meio da API Files:

Bash

curl https://apigw.mka1.com/api/v1/llm/files/file_result123/content \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --output eval-result.json

O artefato de resultado resume os metadados da execução e as métricas finais. O artefato de amostras preserva detalhes por amostra para análise offline.

Editar uma suíte

As suítes são versionadas. Crie uma nova versão imutável ao alterar um manifesto. Defina make_active como false quando quiser preparar uma versão de rascunho sem torná-la o padrão para novas execuções.

Bash

curl https://apigw.mka1.com/api/v1/llm/evals/suites/eval_suite_abc123/versions \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "make_active": true,
    "manifest": {
      "schema_version": "2026-05-27",
      "tasks": [
        {
          "id": "repeat_exactly",
          "type": "custom",
          "dataset": { "file_id": "file_dataset456", "format": "jsonl" },
          "prompt_template": "{{question}}",
          "target_template": "{{answer}}",
          "metrics": [{ "id": "exact_match" }],
          "grader": {
            "type": "python",
            "contract": "sample",
            "file_id": "file_grader456"
          }
        }
      ]
    },
    "metadata": {
      "change": "larger validation split"
    }
  }'

As execuções mantêm a versão da suíte com a qual foram criadas. Alterar a versão ativa não modifica execuções históricas.

Cancelar uma execução

Cancele uma execução quando ela estiver na fila, em andamento ou em finalização.

Bash

curl https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123/cancel \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>'

O cancelamento é realizado conforme possível. Amostras que já estão em execução podem terminar antes que o fluxo de trabalho alcance cancelled.

Excluir suítes, execuções, agendamentos e arquivos

Avaliações e agendamentos oferecem suporte à exclusão lógica. Os arquivos são excluídos do armazenamento.

Excluir uma execução de avaliação

Exclui logicamente uma execução de avaliação para que ela não apareça mais em listas de execuções, detalhes ou classificações de pontuação.

Bash

curl https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123 \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>'

Excluir uma suíte de avaliação

Exclui logicamente uma suíte de avaliação e todas as suas execuções de avaliação para que não apareçam mais em leituras voltadas ao usuário.

Bash

curl https://apigw.mka1.com/api/v1/llm/evals/suites/eval_suite_abc123 \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>'

Excluir um agendamento de avaliação

Exclui logicamente um agendamento de avaliação e remove seu agendamento Temporal. As execuções históricas são preservadas.

Bash

curl https://apigw.mka1.com/api/v1/llm/evals/schedules/eval_sched_abc123 \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>'

Excluir um arquivo

Exclui um arquivo do armazenamento. Isso também o removerá de quaisquer armazenamentos vetoriais.

Bash

curl https://apigw.mka1.com/api/v1/llm/files/file-abc123 \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>'

Paginação e filtragem

Os endpoints de listagem usam paginação por cursor.

Endpoint	Filtros
`GET /evals/suites`	`after`, `limit`
`GET /evals/suites/{suite_id}/versions`	`after`, `limit`
`GET /evals/runs`	`after`, `limit`, `suite_id`, `suite_version`, `status` (Observação: `suite_version` deve ser combinado com `suite_id`.)
`GET /evals/schedules`	`after`, `limit`, `suite_id`, `enabled`
`GET /evals/schedules/{schedule_id}/runs`	`after`, `limit`, `suite_id`, `suite_version`, `status`
`GET /evals/runs/{run_id}/samples`	`after`, `limit`, `task_id`, `model`, `status`, `score_metric`, `score_min`, `score_max`, `include_dataset_row`, `sample_index`

Exemplo:

Bash

curl 'https://apigw.mka1.com/api/v1/llm/evals/runs?status=completed&limit=20' \
  --header 'Authorization: Bearer <mka1-api-key>'

O que ler em seguida

Projetar suítes de tarefas de avaliação aborda conjuntos de dados, manifestos de tarefas, modelos, exemplos few-shot, extração de saída, controles de geração e métricas.
Escrever avaliadores Python para avaliações aborda contratos Python de amostra, lote e baseados em modelo.
Use os caminhos de endpoint deste guia com os objetos de solicitação e resposta gerados retornados pela API.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Executar avaliações

Antes de começar

Fluxo de trabalho

Etapa 1 - Fazer upload de um conjunto de dados

Etapa 2 - Fazer upload de um arquivo de avaliador Python

Etapa 3 - Criar uma suíte

Etapa 4 - Iniciar uma execução

Etapa 5 - Consultar a execução

Etapa 6 - Inspecionar amostras

Buscar áudio de amostra (tarefas de transcrição)

Etapa 7 - Buscar artefatos

Editar uma suíte

Cancelar uma execução

Excluir suítes, execuções, agendamentos e arquivos

Excluir uma execução de avaliação

Excluir uma suíte de avaliação

Excluir um agendamento de avaliação

Excluir um arquivo

Paginação e filtragem

O que ler em seguida

​Antes de começar

​Fluxo de trabalho

​Etapa 1 - Fazer upload de um conjunto de dados

​Etapa 2 - Fazer upload de um arquivo de avaliador Python

​Etapa 3 - Criar uma suíte

​Etapa 4 - Iniciar uma execução

​Etapa 5 - Consultar a execução

​Etapa 6 - Inspecionar amostras

​Buscar áudio de amostra (tarefas de transcrição)

​Etapa 7 - Buscar artefatos

​Editar uma suíte

​Cancelar uma execução

​Excluir suítes, execuções, agendamentos e arquivos

​Excluir uma execução de avaliação

​Excluir uma suíte de avaliação

​Excluir um agendamento de avaliação

​Excluir um arquivo

​Paginação e filtragem

​O que ler em seguida

Antes de começar

Fluxo de trabalho

Etapa 1 - Fazer upload de um conjunto de dados

Etapa 2 - Fazer upload de um arquivo de avaliador Python

Etapa 3 - Criar uma suíte

Etapa 4 - Iniciar uma execução

Etapa 5 - Consultar a execução

Etapa 6 - Inspecionar amostras

Buscar áudio de amostra (tarefas de transcrição)

Etapa 7 - Buscar artefatos

Editar uma suíte

Cancelar uma execução

Excluir suítes, execuções, agendamentos e arquivos

Excluir uma execução de avaliação

Excluir uma suíte de avaliação

Excluir um agendamento de avaliação

Excluir um arquivo

Paginação e filtragem

O que ler em seguida