> ## 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. # Executar avaliações > Crie suítes de avaliação reutilizáveis, execute-as em modelos roteados por MKA1 e inspecione resultados, métricas e artefatos por amostra. 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 é: 1. Faça upload do conjunto de dados e dos arquivos Python opcionais por meio de `/files`. 2. Crie uma suíte de avaliação com um manifesto. 3. Inicie uma execução de avaliação para um ou mais modelos. 4. Consulte a execução até que ela alcance um status terminal. 5. Inspecione as linhas das amostras e baixe os arquivos de artefato gerados. 6. Crie uma nova versão da suíte ao editar o manifesto. Os status da execução de avaliação passam por: ```text theme={null} 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. ```json eval-smoke.jsonl theme={null} {"question":"Repeat exactly: MKA1_EVAL_SMOKE_OK","answer":"MKA1_EVAL_SMOKE_OK"} ``` ```ts TypeScript SDK theme={null} 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': '', }, body: form, }); const datasetFile = await fileRes.json(); console.log(datasetFile.id); ``` ```bash Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/files \ --request POST \ --header 'Authorization: Bearer ' \ --header 'X-On-Behalf-Of: ' \ --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`. ```python exact_match_grader.py theme={null} 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 Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/files \ --request POST \ --header 'Authorization: Bearer ' \ --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 Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/evals/suites \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --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 Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/evals/runs \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --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 Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123 \ --header 'Authorization: Bearer ' ``` 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: ```json theme={null} { "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 Bash theme={null} curl 'https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123/samples?limit=10&task_id=repeat_exactly' \ --header 'Authorization: Bearer ' ``` 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. ```json theme={null} { "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 Bash theme={null} curl 'https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123/samples/0/audio?task_id=Common_voice' \ --header 'Authorization: Bearer ' ``` 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 Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123/artifacts \ --header 'Authorization: Bearer ' ``` Depois, baixe os arquivos por meio da API Files: ```bash Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/files/file_result123/content \ --header 'Authorization: Bearer ' \ --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 Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/evals/suites/eval_suite_abc123/versions \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --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 Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123/cancel \ --request POST \ --header 'Authorization: Bearer ' ``` 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 Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/evals/runs/eval_run_abc123 \ --request DELETE \ --header 'Authorization: Bearer ' ``` ### 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 Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/evals/suites/eval_suite_abc123 \ --request DELETE \ --header 'Authorization: Bearer ' ``` ### 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 Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/evals/schedules/eval_sched_abc123 \ --request DELETE \ --header 'Authorization: Bearer ' ``` ### Excluir um arquivo Exclui um arquivo do armazenamento. Isso também o removerá de quaisquer armazenamentos vetoriais. ```bash Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/files/file-abc123 \ --request DELETE \ --header 'Authorization: Bearer ' ``` ## 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 Bash theme={null} curl 'https://apigw.mka1.com/api/v1/llm/evals/runs?status=completed&limit=20' \ --header 'Authorization: Bearer ' ``` ## O que ler em seguida * [Projetar suítes de tarefas de avaliação](/pt/docs/evals-task-suites) 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](/pt/docs/evals-python-graders) 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.