Naar hoofdinhoud gaan

Run Card Specificatie

Samenvatting. De run card is de atomaire eenheid van benchmarking — een JSON-document dat de volledige configuratie, resultaten per invoer en geaggregeerde scores van één evaluatierun vastlegt. Deze pagina documenteert het schema, de velden, het vingerafdruksmechanisme en de scorestructuur. Zie de Benchmark Specificatie voor canonieke definities.

De run card is het volledige verslag van één enkele evaluatierun. Het bevat alles wat nodig is om het experiment te begrijpen, te reproduceren en te verifiëren: configuratie, scores, individuele resultaten, tokengebruik en omgevingsmetadata.

Schemaversie: 2.0

:::info Gezaghebbend Schema De Benchmark Specificatie is de enige bron van waarheid voor het run card-schema. Voor metriekdefinities, samengestelde gewichten en kwaliteitsniveaus, zie de Scoring Specificatie. Deze pagina documenteert de huidige implementatie. :::

Velden op het hoogste niveau​

VeldTypeBeschrijving
run_idstringUUID v4 gegenereerd bij de start van de run
harness_versionstringSemantische versie van de harness die deze card heeft geproduceerd (bijv. 2.0)
model_slugstringModel-slug gebruikt voor de run (bijv. google/gemini-3.1-pro)
model_idstringOpgelost modelidentificator teruggegeven door de API (bijv. gemini-3.1-pro-001)
conditionstringExperimentlabel (bijv. baseline, coached-v3, few-shot)
timestampstringISO 8601 UTC-tijdstempel van het moment waarop de run is gestart
elapsed_secondsnumberWandkloktijd van de volledige run
{
  "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​

Identificeert de evaluatiedataset en koppelt deze aan een specifieke inhoudsversie via SHA-256.

VeldTypeBeschrijving
idstringDataset-identificator (bijv. edtekla-dev-v1)
versionstringVersietekenreeks van de dataset
language_pairstringWeergavelabel (bijv. EN→CRK)
sha256stringSHA-256-hash van de bestandsinhoud van de dataset. Garandeert de exacte gebruikte gegevens
entry_countnumberAantal invoeren in de 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​

De API- en batchconfiguratie die voor deze run is gebruikt.

VeldTypeBeschrijving
api_providerstringNaam van de API-provider (bijv. openrouter)
temperaturenumberSamplingtemperatuur
max_tokensnumberMaximum aantal tokens per aanvulling
batch_sizenumberInvoeren per gelijktijdige batch
concurrencynumberMaximum aantal parallelle API-verzoeken
coaching_filestringPad naar het coaching-promptbestand, indien gebruikt
method_pathstringPad naar de methode-pluginmap, indien gebruikt
fst_retriesnumberAantal FST-pogingen bij herhaalde aanvragen
{
  "config": {
    "api_provider": "openrouter",
    "temperature": 0.0,
    "max_tokens": 32768,
    "batch_size": 25,
    "concurrency": 8
  }
}

:::info Gepubliceerde Run Cards bevatten method_config Wanneer een run card wordt gepubliceerd via mt-eval publish, injecteert publish.py een method_config-blok met de canonieke 8-veld MethodConfig. Dit maakt installatie via het leaderboard zonder wrijving mogelijk — iedereen kan de methode rechtstreeks vanuit de gepubliceerde card reproduceren.

{
  "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"
  }
}

Alle velden gebruiken camelCase en volgen het canonieke MethodConfig-schema (zie Een methode bouwen). :::

system_prompt_sha256 / system_prompt_used​

VeldTypeBeschrijving
system_prompt_sha256stringSHA-256-hash van de systeemprompt. Opgenomen in de vingerafdruk
system_prompt_usedstringDe volledige tekst van de systeemprompt die naar het model is verzonden

De prompthash maakt deel uit van de vingerafdruk — twee runs met verschillende prompts hebben verschillende vingerafdrukken, zelfs als alle andere instellingen overeenkomen.

fingerprint​

Een reproduceerbaar identificatiemiddel. Twee runs met identieke vingerafdrukken hebben dezelfde experimentele opzet gebruikt.

VeldTypeBeschrijving
hashstringSHA-256-hash van de gesorteerde componenten
componentsobjectDe invoerwaarden die zijn gehasht

Vingerafdrukcomponenten​

ComponentBeschrijving
dataset_sha256Hash van het datasetbestand
model_slugGebruikt model
conditionLabel van de experimentele conditie
system_prompt_sha256Hash van de systeemprompt
temperatureSamplingtemperatuur
harness_versionHarnessversie
{
  "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 Vingerafdruk ≠ Run Card-hash De vingerafdruk identificeert de experimentconfiguratie. De run_card_hash verifieert de integriteit van het resultatenbestand. Zie Vingerafdruk versus Run Card-hash voor meer informatie. :::

scores​

Geaggregeerde metriekwaarden voor de volledige run.

Scores op het hoogste niveau​

VeldTypeBeschrijving
totalnumberTotaal aantal geëvalueerde invoeren
exact_matchesnumberInvoeren waarbij de uitvoer exact overeenkwam met de gouden standaard
exact_match_ratenumberexact_matches / total (0,0–1,0)
fst_acceptednumberInvoeren waarbij de FST-analysator de uitvoer heeft geaccepteerd
fst_acceptance_ratenumberfst_accepted / total (0,0–1,0). null als er geen FST-analysator is gebruikt
chrf_plus_plusnumberchrF++-score op corpusniveau (0–100)
errorsnumberInvoeren die zijn mislukt (API-fout, time-out, enz.)
avg_latency_secondsnumberGemiddelde responstijd over alle invoeren
median_latency_secondsnumberMediane responstijd
p95_latency_secondsnumber95e-percentiel responstijd

by_difficulty​

Scores uitgesplitst naar moeilijkheidsgraad. Elke sleutel (geheel getal 1–5) bevat dezelfde metriekvelden als de scores op het hoogste niveau.

{
  "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​

Scores uitgesplitst naar herkomst van de invoer. Elke sleutel (bijv. gold_standard, textbook) bevat dezelfde metriekvelden.

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

totals​

Tokengebruik en kostenbewaking voor de volledige run.

VeldTypeBeschrijving
prompt_tokensnumberTotaal aantal invoertokens over alle API-aanroepen
completion_tokensnumberTotaal aantal uitvoertokens
reasoning_tokensnumberTokens gebruikt voor chain-of-thought-redenering (modelafhankelijk, 0 voor de meeste modellen)
cached_tokensnumberTokens geserveerd vanuit de promptcache van de provider
total_cost_usdnumberTotale kosten in USD (zoals gerapporteerd door de 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​

Metadata van de runtime-omgeving ten behoeve van reproduceerbaarheid.

VeldTypeBeschrijving
harness_versionstringHarnessversie (spiegelt het veld harness_version op het hoogste niveau)
harness_git_commitstringGit-commit-SHA van de harness ten tijde van de run
python_versionstringVersie van de Python-interpreter
sacrebleu_versionstringVersie van de sacrebleu-bibliotheek (gebruikt voor chrF++-scoring)
osstringBesturingssysteemidentificator
{
  "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[]​

De resultatenarray per invoer. Één object per dataset-invoer, in indexvolgorde.

VeldTypeBeschrijving
entry_idintegerID van deze invoer in het corpus (komt overeen met entries[].id)
sourcestringDe brontekst die is vertaald
referencestringDe gouden-standaardreferentie uit het corpus
predictedstringDe werkelijke uitvoer van de methode
exact_matchbooleanOf predicted na normalisatie exact overeenkomt met reference
entry_chrfnumberchrF++-score op zinsniveau voor deze invoer (0–100)
fst_acceptedboolean | nullOf de FST-analysator de uitvoer heeft geaccepteerd. null als er geen analysator is geconfigureerd
fst_analysisstring[]FST-analysestrings voor de uitvoer (lege array als niet geanalyseerd of afgewezen)
difficultyintegerMoeilijkheidsgraad uit het corpus (1–5)
provenancestringHerkomsttag uit het corpus
latency_secondsnumberResponstijd voor deze individuele invoer
usageobjectTokengebruik per invoer: { prompt_tokens, completion_tokens, reasoning_tokens }
errorstring | nullFoutmelding als deze invoer is mislukt. null bij succes
{
  "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​

VeldTypeBeschrijving
run_card_hashstringSHA-256-hash van de volledige run card-JSON, waarbij het veld run_card_hash zelf tijdens het hashen is ingesteld op ""

Dit is het manipulatiedetectiemechanisme. Het leaderboard herberekent deze hash bij indiening en wijst cards af waarbij de hash niet overeenkomt.

De hash berekenen:

  1. Serialiseer de run card naar JSON met run_card_hash ingesteld op ""
  2. Bereken de SHA-256 van de geserialiseerde tekenreeks
  3. Stel run_card_hash in op de resulterende hexadecimale samenvatting
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 Detailanalyse per invoer Gepubliceerde run cards vullen ook de Supabase-tabel run_card_entries in, die resultaten per invoer opslaat voor detailanalyse op het leaderboard. Deze tabel wordt automatisch gevuld tijdens mt-eval publish. :::

Zie ook​