Ir para o conteúdo principal

Especificação de Run Card

Resumo Executivo. O run card é a unidade atômica de benchmarking — um documento JSON que registra a configuração completa, resultados por entrada e pontuações agregadas de uma execução de avaliação. Esta página documenta o esquema, campos, mecanismo de fingerprinting e estrutura de pontuação. Veja a Especificação de Benchmark para definições canônicas.

O run card é o registro completo de uma única execução de avaliação. Ele contém tudo o que você precisa para entender, reproduzir e verificar o experimento: configuração, pontuações, resultados individuais, uso de tokens e metadados de ambiente.

Versão do esquema: 2.0

:::info Esquema Autoritativo A Especificação de Benchmark é a fonte única de verdade para o esquema do run card. Para definições de métricas, pesos compostos e níveis de qualidade, veja a Especificação de Pontuação. Esta página documenta a implementação atual. :::

Campos de Nível Superior​

CampoTipoDescrição
run_idstringUUID v4 gerado no início da execução
harness_versionstringVersão semântica do harness que produziu este card (ex: 2.0)
model_slugstringSlug do modelo usado na execução (ex: google/gemini-3.1-pro)
model_idstringIdentificador de modelo resolvido retornado pela API (ex: gemini-3.1-pro-001)
conditionstringRótulo do experimento (ex: baseline, coached-v3, few-shot)
timestampstringTimestamp ISO 8601 UTC quando a execução começou
elapsed_secondsnumberDuração de tempo real de toda a execução
{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "harness_version": "2.0",
  "model_slug": "google/gemini-3.1-pro",
  "model_id": "gemini-3.1-pro-001",
  "condition": "baseline",
  "timestamp": "2026-06-01T03:22:41Z",
  "elapsed_seconds": 142.7
}

dataset​

Identifica o dataset de avaliação e o fixa a uma versão de conteúdo específica via SHA-256.

CampoTipoDescrição
idstringIdentificador do dataset (ex: edtekla-dev-v1)
versionstringString de versão do dataset
language_pairstringRótulo de exibição (ex: EN→CRK)
sha256stringHash SHA-256 do conteúdo do arquivo do dataset. Garante os dados exatos usados
entry_countnumberNúmero de entradas no dataset
// Example using master_corpus.json (62 gold + 342 textbook = 404)
{
  "dataset": {
    "id": "edtekla-dev-v1",
    "version": "1.0",
    "language_pair": "EN→CRK",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "entry_count": 404
  }
}

config​

A configuração de API e batching usada para esta execução.

CampoTipoDescrição
api_providerstringNome do provedor de API (ex: openrouter)
temperaturenumberTemperatura de amostragem
max_tokensnumberMáximo de tokens por conclusão
batch_sizenumberEntradas por lote concorrente
concurrencynumberMáximo de requisições paralelas à API
coaching_filestringCaminho para arquivo de prompt de coaching, se usado
method_pathstringCaminho para diretório de plugin de método, se usado
fst_retriesnumberNúmero de tentativas de retry FST
{
  "config": {
    "api_provider": "openrouter",
    "temperature": 0.0,
    "max_tokens": 32768,
    "batch_size": 25,
    "concurrency": 8
  }
}

:::info Run Cards Publicados Incluem method_config Quando um run card é publicado via mt-eval publish, publish.py injeta um bloco method_config contendo o MethodConfig canônico de 8 campos. Isso permite instalação sem atrito no leaderboard — qualquer pessoa pode reproduzir o método diretamente do card publicado.

{
  "method_config": {
    "model": "gemini-pro",
    "temperature": 0.0,
    "batchSize": 25,
    "register": "Formal Plains Cree. Use SRO orthography.",
    "coachingFile": "prompts/crk-coaching-v8.txt",
    "coachingPrompt": null,
    "promptContext": "champollion",
    "qualityTier": "verified"
  }
}

Todos os campos usam camelCase e seguem o esquema MethodConfig canônico (veja Construindo um Método). :::

system_prompt_sha256 / system_prompt_used​

CampoTipoDescrição
system_prompt_sha256stringHash SHA-256 do prompt do sistema. Incluído no fingerprint
system_prompt_usedstringO texto completo do prompt do sistema enviado ao modelo

O hash do prompt faz parte do fingerprint — duas execuções com prompts diferentes terão fingerprints diferentes mesmo que todas as outras configurações correspondam.

fingerprint​

Um identificador de reprodutibilidade. Duas execuções com fingerprints idênticos usaram a mesma configuração experimental.

CampoTipoDescrição
hashstringHash SHA-256 dos componentes ordenados
componentsobjectOs valores de entrada que foram hashados

Componentes do Fingerprint​

ComponenteDescrição
dataset_sha256Hash do arquivo do dataset
model_slugModelo usado
conditionRótulo da condição do experimento
system_prompt_sha256Hash do prompt do sistema
temperatureTemperatura de amostragem
harness_versionVersão do harness
{
  "fingerprint": {
    "hash": "7f83b1657ff1fc53b92dc18148a1d65dfc2d4b1fa3d677284addd200126d9069",
    "components": {
      "dataset_sha256": "e3b0c44298fc1c14...",
      "model_slug": "google/gemini-3.1-pro",
      "condition": "baseline",
      "system_prompt_sha256": "abc123...",
      "temperature": 0.0,
      "harness_version": "2.0"
    }
  }
}

:::info Fingerprint ≠ Hash do Run Card O fingerprint identifica a configuração do experimento. O run_card_hash verifica a integridade do arquivo de resultado. Veja Fingerprint vs Hash do Run Card para detalhes. :::

scores​

Métricas agregadas para toda a execução.

Pontuações de Nível Superior​

CampoTipoDescrição
totalnumberTotal de entradas avaliadas
exact_matchesnumberEntradas onde a saída correspondeu exatamente ao padrão ouro
exact_match_ratenumberexact_matches / total (0.0–1.0)
fst_acceptednumberEntradas onde o analisador FST aceitou a saída
fst_acceptance_ratenumberfst_accepted / total (0.0–1.0). null se nenhum analisador FST foi usado
chrf_plus_plusnumberPontuação chrF++ em nível de corpus (0–100)
errorsnumberEntradas que falharam (erro de API, timeout, etc.)
avg_latency_secondsnumberTempo médio de resposta em todas as entradas
median_latency_secondsnumberTempo mediano de resposta
p95_latency_secondsnumberTempo de resposta do 95º percentil

by_difficulty​

Pontuações divididas por nível de dificuldade. Cada chave (inteiro 1–5) contém os mesmos campos de métricas das pontuações de nível superior.

{
  "by_difficulty": {
    "1": {
      "total": 20,
      "exact_matches": 8,
      "exact_match_rate": 0.40,
      "chrf_plus_plus": 68.2,
      "fst_accepted": 18,
      "fst_acceptance_rate": 0.90
    },
    "2": { ... },
    "3": { ... },
    "4": { ... },
    "5": { ... }
  }
}

by_provenance​

Pontuações divididas por proveniência de entrada. Cada chave (ex: gold_standard, textbook) contém os mesmos campos de métricas.

{
  "by_provenance": {
    "gold_standard": {
      "total": 80,
      "exact_matches": 10,
      "exact_match_rate": 0.125,
      "chrf_plus_plus": 44.8
    },
    "textbook": { ... }
  }
}

totals​

Rastreamento de uso de tokens e custo para toda a execução.

CampoTipoDescrição
prompt_tokensnumberTotal de tokens de entrada em todas as chamadas de API
completion_tokensnumberTotal de tokens de saída
reasoning_tokensnumberTokens usados para raciocínio chain-of-thought (dependente do modelo, 0 para a maioria dos modelos)
cached_tokensnumberTokens servidos do cache de prompt do provedor
total_cost_usdnumberCusto total em USD (conforme relatado pela API)
cost_per_entry_usdnumbertotal_cost_usd / entry_count
reasoning_rationumberreasoning_tokens / completion_tokens (0.0–1.0)
{
  "totals": {
    "prompt_tokens": 48200,
    "completion_tokens": 3100,
    "reasoning_tokens": 0,
    "cached_tokens": 12000,
    "total_cost_usd": 0.42,
    "cost_per_entry_usd": 0.0034,
    "reasoning_ratio": 0.0
  }
}

environment​

Metadados de ambiente de tempo de execução para reprodutibilidade.

CampoTipoDescrição
harness_versionstringVersão do harness (espelha harness_version de nível superior)
harness_git_commitstringSHA do commit Git do harness no tempo de execução
python_versionstringVersão do interpretador Python
sacrebleu_versionstringVersão da biblioteca sacrebleu (usada para pontuação chrF++)
osstringIdentificador do sistema operacional
{
  "environment": {
    "harness_version": "2.0",
    "harness_git_commit": "a1b2c3d",
    "python_version": "3.11.9",
    "sacrebleu_version": "2.4.0",
    "os": "macOS-14.5-arm64"
  }
}

results[]​

O array de resultados por entrada. Um objeto por entrada do dataset, em ordem de índice.

CampoTipoDescrição
entry_idintegerID desta entrada no corpus (corresponde a entries[].id)
sourcestringO texto de origem que foi traduzido
referencestringA referência padrão ouro do corpus
predictedstringA saída real do método
exact_matchbooleanSe predicted corresponde exatamente a reference após normalização
entry_chrfnumberPontuação chrF++ em nível de sentença para esta entrada (0–100)
fst_acceptedboolean | nullSe o analisador FST aceitou a saída. null se nenhum analisador foi configurado
fst_analysisstring[]Strings de análise FST para a saída (array vazio se não analisado ou rejeitado)
difficultyintegerNível de dificuldade do corpus (1–5)
provenancestringTag de proveniência do corpus
latency_secondsnumberTempo de resposta para esta entrada individual
usageobjectUso de tokens por entrada: { prompt_tokens, completion_tokens, reasoning_tokens }
errorstring | nullMensagem de erro se esta entrada falhou. null em caso de sucesso
{
  "results": [
    {
      "entry_id": 1,
      "source": "Hello",
      "reference": "tânisi",
      "predicted": "tânisi",
      "exact_match": true,
      "entry_chrf": 100.0,
      "fst_accepted": true,
      "fst_analysis": ["tânisi+V+AI+Ind+2Sg"],
      "difficulty": 1,
      "provenance": "gold_standard",
      "latency_seconds": 0.82,
      "usage": {
        "prompt_tokens": 385,
        "completion_tokens": 12,
        "reasoning_tokens": 0
      },
      "error": null
    }
  ]
}

run_card_hash​

CampoTipoDescrição
run_card_hashstringHash SHA-256 de todo o JSON do run card, com o campo run_card_hash definido como "" durante o hashing

Este é o selo de detecção de adulteração. O leaderboard recalcula este hash na submissão e rejeita cards onde não corresponde.

Computando o hash:

  1. Serialize o run card para JSON com run_card_hash definido como ""
  2. Compute SHA-256 da string serializada
  3. Defina run_card_hash como o digest hexadecimal resultante
import hashlib, json

card["run_card_hash"] = ""
card_json = json.dumps(card, sort_keys=True, ensure_ascii=False)
card["run_card_hash"] = hashlib.sha256(card_json.encode()).hexdigest()

:::info Drill-Down por Entrada Run cards publicados também preenchem a tabela Supabase run_card_entries, que armazena resultados por entrada para análise de drill-down no leaderboard. Esta tabela é preenchida automaticamente durante mt-eval publish. :::

Veja Também​