Zum Hauptinhalt springen

Run-Card-Spezifikation

Zusammenfassung. Die Run-Card ist die atomare Einheit des Benchmarkings — ein JSON-Dokument, das die vollständige Konfiguration, die Ergebnisse pro Eintrag und die aggregierten Bewertungen eines Evaluierungslaufs aufzeichnet. Diese Seite dokumentiert das Schema, die Felder, den Fingerprinting-Mechanismus und die Struktur der Bewertungen. Siehe die Benchmark-Spezifikation für die kanonischen Definitionen.

Die Run-Card ist die vollständige Aufzeichnung eines einzelnen Evaluierungslaufs. Sie enthält alles, was zum Verständnis, zur Reproduktion und zur Verifikation des Experiments erforderlich ist: Konfiguration, Bewertungen, einzelne Ergebnisse, Token-Verbrauch und Umgebungs-Metadaten.

Schema-Version: 2.0

:::info Maßgebliches Schema Die Benchmark-Spezifikation ist die einzige verbindliche Quelle für das Run-Card-Schema. Für Metrik-Definitionen, Gewichtungen des composite score und Qualitätsstufen siehe die Scoring-Spezifikation. Diese Seite dokumentiert die aktuelle Implementierung. :::

Felder der obersten Ebene​

FeldTypBeschreibung
run_idstringUUID v4, die zu Beginn des Laufs generiert wird
harness_versionstringSemantische Version des Harness, das diese Card erzeugt hat (z. B. 2.0)
model_slugstringFür den Lauf verwendeter Model-Slug (z. B. google/gemini-3.1-pro)
model_idstringAufgelöste Modellkennung, die von der API zurückgegeben wird (z. B. gemini-3.1-pro-001)
conditionstringExperiment-Label (z. B. baseline, coached-v3, few-shot)
timestampstringISO-8601-UTC-Zeitstempel des Laufbeginns
elapsed_secondsnumberTatsächliche Gesamtdauer (Wall-Clock) des gesamten Laufs
{
  "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​

Identifiziert den Evaluierungsdatensatz und bindet ihn über SHA-256 an eine bestimmte Inhaltsversion.

FeldTypBeschreibung
idstringDatensatzkennung (z. B. edtekla-dev-v1)
versionstringVersions-String des Datensatzes
language_pairstringAnzeigelabel (z. B. EN→CRK)
sha256stringSHA-256-Hash des Inhalts der Datensatzdatei. Garantiert die exakt verwendeten Daten
entry_countnumberAnzahl der Einträge im Datensatz
// 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​

Die für diesen Lauf verwendete API- und Batching-Konfiguration.

FeldTypBeschreibung
api_providerstringName des API-Anbieters (z. B. openrouter)
temperaturenumberSampling-Temperatur
max_tokensnumberMaximale Anzahl Tokens pro Completion
batch_sizenumberEinträge pro gleichzeitigem Batch
concurrencynumberMaximale Anzahl paralleler API-Anfragen
coaching_filestringPfad zur Coaching-Prompt-Datei, falls verwendet
method_pathstringPfad zum Verzeichnis des Methoden-Plugins, falls verwendet
fst_retriesnumberAnzahl der FST-Wiederholungsversuche
{
  "config": {
    "api_provider": "openrouter",
    "temperature": 0.0,
    "max_tokens": 32768,
    "batch_size": 25,
    "concurrency": 8
  }
}

:::info Veröffentlichte Run-Cards enthalten method_config Wenn eine Run-Card über mt-eval publish veröffentlicht wird, fügt publish.py einen method_config-Block ein, der die kanonische MethodConfig mit 8 Feldern enthält. Dies ermöglicht eine reibungslose Leaderboard-Installation — jede Person kann die Methode direkt aus der veröffentlichten Card reproduzieren.

{
  "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 Felder verwenden camelCase und folgen dem kanonischen MethodConfig-Schema (siehe Eine Methode erstellen). :::

system_prompt_sha256 / system_prompt_used​

FeldTypBeschreibung
system_prompt_sha256stringSHA-256-Hash des System-Prompts. Im Fingerprint enthalten
system_prompt_usedstringDer vollständige System-Prompt-Text, der an das Modell gesendet wird

Der Prompt-Hash ist Teil des Fingerprints — zwei Läufe mit unterschiedlichen Prompts erhalten unterschiedliche Fingerprints, selbst wenn alle anderen Einstellungen übereinstimmen.

fingerprint​

Eine Kennung zur Reproduzierbarkeit. Zwei Läufe mit identischen Fingerprints verwendeten dasselbe experimentelle Setup.

FeldTypBeschreibung
hashstringSHA-256-Hash der sortierten Komponenten
componentsobjectDie Eingabewerte, die gehasht wurden

Fingerprint-Komponenten​

KomponenteBeschreibung
dataset_sha256Hash der Datensatzdatei
model_slugVerwendetes Modell
conditionLabel der Experimentbedingung
system_prompt_sha256Hash des System-Prompts
temperatureSampling-Temperatur
harness_versionHarness-Version
{
  "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 ≠ Run-Card-Hash Der Fingerprint identifiziert die Experimentkonfiguration. Der run_card_hash verifiziert die Integrität der Ergebnisdatei. Siehe Fingerprint vs. Run-Card-Hash für Details. :::

scores​

Aggregierte Metriken für den gesamten Lauf.

Bewertungen der obersten Ebene​

FeldTypBeschreibung
totalnumberGesamtzahl der evaluierten Einträge
exact_matchesnumberEinträge, bei denen die Ausgabe exakt mit dem Goldstandard übereinstimmte
exact_match_ratenumberexact_matches / total (0.0–1.0)
fst_acceptednumberEinträge, bei denen der FST-Analyzer die Ausgabe akzeptierte
fst_acceptance_ratenumberfst_accepted / total (0.0–1.0). null, wenn kein FST-Analyzer verwendet wurde
chrf_plus_plusnumberchrF++-Bewertung auf Korpusebene (0–100)
errorsnumberEinträge, die fehlgeschlagen sind (API-Fehler, Timeout usw.)
avg_latency_secondsnumberMittlere Antwortzeit über alle Einträge
median_latency_secondsnumberMedian der Antwortzeit
p95_latency_secondsnumberAntwortzeit im 95. Perzentil

by_difficulty​

Nach Schwierigkeitsstufe aufgeschlüsselte Bewertungen. Jeder Schlüssel (Ganzzahl 1–5) enthält dieselben Metrikfelder wie die Bewertungen der obersten Ebene.

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

Nach Herkunft des Eintrags aufgeschlüsselte Bewertungen. Jeder Schlüssel (z. B. gold_standard, textbook) enthält dieselben Metrikfelder.

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

totals​

Token-Verbrauch und Kostenverfolgung für den gesamten Lauf.

FeldTypBeschreibung
prompt_tokensnumberGesamtzahl der Eingabe-Tokens über alle API-Aufrufe
completion_tokensnumberGesamtzahl der Ausgabe-Tokens
reasoning_tokensnumberTokens, die für Chain-of-Thought-Reasoning verwendet wurden (modellabhängig, 0 bei den meisten Modellen)
cached_tokensnumberTokens, die aus dem Prompt-Cache des Anbieters bereitgestellt wurden
total_cost_usdnumberGesamtkosten in USD (wie von der API gemeldet)
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​

Metadaten zur Laufzeitumgebung für die Reproduzierbarkeit.

FeldTypBeschreibung
harness_versionstringHarness-Version (spiegelt harness_version der obersten Ebene wider)
harness_git_commitstringGit-Commit-SHA des Harness zum Zeitpunkt des Laufs
python_versionstringVersion des Python-Interpreters
sacrebleu_versionstringVersion der sacrebleu-Bibliothek (verwendet für chrF++-Bewertung)
osstringBetriebssystemkennung
{
  "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[]​

Das Array mit den Ergebnissen pro Eintrag. Ein Objekt pro Datensatzeintrag, in Indexreihenfolge.

FeldTypBeschreibung
entry_idintegerID dieses Eintrags im Korpus (entspricht entries[].id)
sourcestringDer übersetzte Quelltext
referencestringDie Goldstandard-Referenz aus dem Korpus
predictedstringDie tatsächliche Ausgabe der Methode
exact_matchbooleanOb predicted nach Normalisierung exakt mit reference übereinstimmt
entry_chrfnumberchrF++-Bewertung auf Satzebene für diesen Eintrag (0–100)
fst_acceptedboolean | nullOb der FST-Analyzer die Ausgabe akzeptierte. null, wenn kein Analyzer konfiguriert war
fst_analysisstring[]FST-Analyse-Strings für die Ausgabe (leeres Array, wenn nicht analysiert oder abgelehnt)
difficultyintegerSchwierigkeitsstufe aus dem Korpus (1–5)
provenancestringHerkunfts-Tag aus dem Korpus
latency_secondsnumberAntwortzeit für diesen einzelnen Eintrag
usageobjectToken-Verbrauch pro Eintrag: { prompt_tokens, completion_tokens, reasoning_tokens }
errorstring | nullFehlermeldung, falls dieser Eintrag fehlgeschlagen ist. null bei Erfolg
{
  "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​

FeldTypBeschreibung
run_card_hashstringSHA-256-Hash der gesamten Run-Card-JSON, wobei das Feld run_card_hash selbst während des Hashings auf "" gesetzt wird

Dies ist das Siegel zur Manipulationserkennung. Das Leaderboard berechnet diesen Hash bei der Einreichung neu und weist Cards zurück, bei denen er nicht übereinstimmt.

Berechnung des Hashs:

  1. Serialisieren Sie die Run-Card als JSON mit run_card_hash auf "" gesetzt
  2. Berechnen Sie SHA-256 des serialisierten Strings
  3. Setzen Sie run_card_hash auf den resultierenden Hex-Digest
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 pro Eintrag Veröffentlichte Run-Cards füllen außerdem die Supabase-Tabelle run_card_entries, die Ergebnisse pro Eintrag für die Drill-Down-Analyse auf dem Leaderboard speichert. Diese Tabelle wird während mt-eval publish automatisch befüllt. :::

Siehe auch​