@precisa-saude/medbench-harness
v2.7.0
Published
Harness reproduzível de avaliação de LLMs em provas médicas brasileiras
Maintainers
Readme
@precisa-saude/medbench-harness
Harness reproduzível de avaliação de LLMs em provas médicas brasileiras.
Sobre
Pipeline de avaliação que roda uma questão por requisição HTTP, três execuções por modelo, sem ferramentas, sem few-shot, com log bruto (raw.jsonl) persistido para re-scoring determinístico. Acompanha providers para Anthropic, OpenAI, Google e qualquer backend compatível com a API do OpenAI (Ollama local, Maritaca, Together, OpenRouter).
É o pipeline por trás do leaderboard em medbench-brasil.ia.br. Depende de @precisa-saude/medbench-dataset.
Garantias de integridade
Seguem literalmente o ADR-0002 — alterar qualquer uma exige novo ADR e aprovação do mantenedor:
- System prompt literal e fixo:
Responda a seguinte questão de múltipla escolha selecionando a letra correta (A, B, C ou D). - Single-turn absoluto — uma questão por requisição, sem histórico, sem few-shot, sem contexto de outras questões.
- Zero tools, zero connectors, zero web search, zero code interpreter, zero RAG em qualquer provider.
- Três execuções independentes por modelo; intervalo de confiança 95% pelo método de Wilson.
- Todos os parâmetros de API registrados em
results/<edition>/<model>.raw.jsonl(uma linha por requisição). - Modelos locais em completion puro, sem scaffolding de ferramentas.
Instalação
pnpm add @precisa-saude/medbench-harness
# ou
npm install @precisa-saude/medbench-harnessA CLI fica disponível como o binário medbench. Requer Node ≥ 20.
Uso como CLI
Compatibilidade dos novos candidatos
Os IDs exatos gpt-6.1-terra, claude-haiku-5-5 e gemini-4-argon
possuem parâmetros específicos de raciocínio alto, sem sampling. Terra e
Haiku usam limite de 8.192 tokens; Argon usa 32.768 e timeout de 15 minutos.
Essas regras não alteram os requests dos modelos anteriores. OpenAI e Google
também registram o motivo de parada quando declarado pela API.
O piloto operacional separado da CLI está documentado em
plano-shortlist-pilots.md.
Ele não publica scores e interrompe cada modelo na primeira falha, sem retry.
O argumento final openrouter seleciona somente Terra e Argon nessa rota,
com OPENROUTER_API_KEY, logs separados e fallback desabilitado:
node packages/eval-harness/scripts/shortlist-pilots.mjs /caminho/.env.local openrouterExecute a partir da raiz após o build. O script recusa repetir um piloto cujos arquivos de saída já existem, preservando as tentativas anteriores.
A avaliação completa das duas novas edições está especificada em
plano-shortlist-evaluations.md.
O executor operacional não reutiliza pilotos nem sobrescreve resultados:
node packages/eval-harness/scripts/shortlist-evaluations.mjs --dry-run
node packages/eval-harness/scripts/shortlist-evaluations.mjs /caminho/.env.localSão seis combinações, 1.494 respostas esperadas e três runs por questão. Falhas transitórias seguem o retry canônico, com cada tentativa no ledger. Parsing inválido ou parada anormal interrompem a combinação sem publicar um score parcial. Uma retomada após interrupção exige revisar os logs primeiro.
A retomada específica autorizada de Argon 2026/1 usa
scripts/resume-argon.mjs. Ela preserva cópias dos arquivos interrompidos,
registra hashes e a exclusão operacional em um manifesto, reutiliza 44
respostas e limita a continuação a 208 chamadas sem retries. Não é um comando
genérico de restart e recusa repetir uma retomada já iniciada.
Dois subcomandos: smoke (pré-flight, ~8 amostras estratificadas) e eval (run completo).
medbench smoke — validação de provider e parser
Sempre rode antes de queimar créditos num modelo novo: valida que o provider responde e que o parser reconhece o formato emitido. Aborta com código não-zero se a taxa de parse correto fica abaixo do threshold.
medbench smoke \
--backend anthropic \
--model claude-opus-4-7 \
--edition revalida-2025-1 \
--samples 8 \
--threshold 0.7medbench eval — avaliação completa
medbench eval \
--backend openrouter \
--model google/gemini-3.1-pro-preview \
--cutoff 2025-11-01 \
--edition revalida-2025-1 \
--runs 3Flags
Comuns a smoke e eval:
| Flag | Valor | Padrão |
| --------------- | ------------------------------------------------------------------------------------------- | --------------------- |
| --backend | anthropic | openai | google | ollama | maritaca | together | openrouter | obrigatório |
| --model | identificador do modelo (ex.: claude-opus-4-7, gpt-5, google/gemini-3.1-pro-preview) | obrigatório |
| --edition | revalida-2025-1, revalida-2024-2, etc. | revalida-2025-1 |
| --label | nome legível exibido no site | derivado do modelo |
| --cutoff | data de corte de treino do modelo (YYYY-MM-DD) | — |
| --concurrency | requisições simultâneas | 10 (APIs), 1 (ollama) |
| --apiKey | chave explícita (sobrescreve variável de ambiente) | — |
| --baseUrl | endpoint custom (ollama, maritaca, together, openrouter) | padrão do backend |
Específicas de eval:
| Flag | Valor | Padrão |
| -------------- | ---------------------------------------- | ---------- |
| --runs | execuções por questão | 3 |
| --out | diretório de saída | results/ |
| --no-raw-log | desabilita JSONL bruto | ativado |
| --restart | descarta JSONL prévio e recomeça do zero | retoma |
Específicas de smoke:
| Flag | Valor | Padrão |
| ------------- | ------------------------------------------- | ------ |
| --samples | número de questões estratificadas | 8 |
| --threshold | taxa mínima de parses corretos para aprovar | 0.7 |
Uso como biblioteca
Consumo e auditoria de chamadas
Novas respostas incluem usage quando a API informa tokens válidos:
inputTokens inclui cache e outputTokens inclui raciocínio. Nunca somar
reasoningTokens novamente à saída. O score inclui o agregado e a cobertura
callsWithUsage/totalCalls; ausência significa desconhecido, não gratuito.
Raws antigos continuam legíveis e não recebem estimativas de tokens.
Com cobertura completa, o agregado também inclui maxInputTokensPerCall,
calculado dos tokens de entrada observados por chamada (incluindo cache).
Ele permite confirmar a faixa de preço por tamanho do prompt. Em cobertura
parcial, fica ausente. rescore --from-raw o deriva offline de raws com usage,
sem nova inferência; rescore de scored JSON apenas preserva o que já existe.
eval e smoke registram cada tentativa em
results/<edition>/<model>.<eval|smoke>.requests.jsonl, inclusive retries e
erros. O ledger não é truncado por --restart e permanece ativo com
--no-raw-log. Use --out DIR para mudar o destino. A CLI imprime somente
o consumo novo da invocação; o agregado do score também inclui respostas
reutilizadas por resume. rescore preserva consumo sem criar gasto novo.
Para a biblioteca, persista RunConfig.onRequestAttempt além de
onRawResponse; o primeiro recebe um evento por tentativa. observeRequest
permite instrumentar chamadas individuais, como pilotos. UUIDs de tentativa
ligam o ledger aos raws. Falha ao persistir auditoria interrompe o lote.
O ledger mede consumo observado, não faturamento completo: tentativas sem
usage, respostas perdidas ou processos interrompidos podem ter sido cobrados.
Não somar raw e ledger. Para concatenar ledgers copiados, deduplicar por
attemptId. Preços e custos em USD não são gravados nos resultados;
estimativa por tabela e cobrança conciliada são conceitos distintos.
Ver ADR 0005.
import { runEvaluation, anthropicProvider, SYSTEM_PROMPT } from '@precisa-saude/medbench-harness';
import type { Provider, RunConfig } from '@precisa-saude/medbench-harness';
const provider = anthropicProvider({
model: 'claude-opus-4-7',
trainingCutoff: '2025-03-01',
});
const result = await runEvaluation(provider, {
editions: ['revalida-2025-1'],
runsPerQuestion: 3,
concurrency: 10,
excludeImages: true,
excludeTables: true,
onRawResponse: (record) => {
// persista `record` onde quiser — ele tem requestParams, rawResponse, parsed, correct
},
});
console.log(result.accuracy, result.ci95, result.contaminationSplit);Se você só quer o system prompt literal (por exemplo, para citar no seu próprio site de metodologia), use a export secundária:
import { SYSTEM_PROMPT } from '@precisa-saude/medbench-harness/prompt';Exports
Funções: runEvaluation, scoreRun, parseLetter.
Providers: anthropicProvider, openAiProvider, googleProvider, openAiCompatProvider (usado por ollama, maritaca, together, openrouter).
Constante: SYSTEM_PROMPT.
Tipos: Provider, ProviderResponse, RunConfig, EvaluationResult, RawResponseRecord.
Formato de saída
Cada medbench eval produz, em results/<edition>/<model-slug>.*:
<model>.json— agregado comaccuracy,ci95,perQuestion[],perSpecialty,contaminationSplit: { clean, contaminated }, parâmetros da run.<model>.raw.jsonl— uma linha por requisição, comrequestParams(inclusive system prompt verbatim),rawResponse,modelId,editionId,questionId,run,elapsedMs,parsed,correct. Re-scoring determinístico a partir deste arquivo.
Variáveis de ambiente
Conforme o --backend escolhido:
| Backend | Variável |
| ------------ | -------------------- |
| anthropic | ANTHROPIC_API_KEY |
| openai | OPENAI_API_KEY |
| google | GOOGLE_API_KEY |
| openrouter | OPENROUTER_API_KEY |
| maritaca | MARITACA_API_KEY |
| together | TOGETHER_API_KEY |
| ollama | — (roda local) |
Carregadas automaticamente via dotenv a partir de .env.local (preferido) ou .env no cwd — não é preciso export no shell. Para começar, copie o .env.example da raiz do repo para .env.local e preencha as chaves dos backends que vai usar.
Licença
Links
- Site: medbench-brasil.ia.br
- Repositório: github.com/Precisa-Saude/medbench-brasil
- ADR-0002 (protocolo de integridade): docs/development/adr/0002-integridade-do-benchmark.md
- Dataset:
@precisa-saude/medbench-dataset
