Accéder au contenu principal

Spécification de la Carte d'Exécution

Résumé exécutif. La carte d'exécution est l'unité atomique de l'évaluation comparative — un document JSON enregistrant la configuration complète, les résultats par entrée et les scores agrégés d'une exécution d'évaluation. Cette page documente le schéma, les champs, le mécanisme d'empreinte et la structure des scores. Consultez la Spécification d'Évaluation Comparative pour les définitions canoniques.

La carte d'exécution est l'enregistrement complet d'une seule exécution d'évaluation. Elle contient tout ce qui est nécessaire pour comprendre, reproduire et vérifier l'expérience : configuration, scores, résultats individuels, utilisation des jetons et métadonnées d'environnement.

Version du schéma : 2.0

:::info Schéma Faisant Autorité La Spécification d'Évaluation Comparative est l'unique source de vérité pour le schéma de la carte d'exécution. Pour les définitions des métriques, les poids composites et les niveaux de qualité, consultez la Spécification de Notation. Cette page documente l'implémentation actuelle. :::

Champs de Niveau Supérieur​

ChampTypeDescription
run_idstringUUID v4 généré au démarrage de l'exécution
harness_versionstringVersion sémantique du harnais qui a produit cette carte (p. ex., 2.0)
model_slugstringSlug du modèle utilisé pour l'exécution (p. ex., google/gemini-3.1-pro)
model_idstringIdentifiant du modèle résolu retourné par l'API (p. ex., gemini-3.1-pro-001)
conditionstringÉtiquette d'expérience (p. ex., baseline, coached-v3, few-shot)
timestampstringHorodatage ISO 8601 UTC du démarrage de l'exécution
elapsed_secondsnumberDurée d'exécution réelle de l'ensemble de l'exécution
{
  "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​

Identifie l'ensemble de données d'évaluation et l'épingle à une version de contenu spécifique via SHA-256.

ChampTypeDescription
idstringIdentifiant de l'ensemble de données (p. ex., edtekla-dev-v1)
versionstringChaîne de version de l'ensemble de données
language_pairstringÉtiquette d'affichage (p. ex., EN→CRK)
sha256stringHachage SHA-256 du contenu du fichier d'ensemble de données. Garantit les données exactes utilisées
entry_countnumberNombre d'entrées dans l'ensemble de données
// 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​

La configuration de l'API et du traitement par lots utilisée pour cette exécution.

ChampTypeDescription
api_providerstringNom du fournisseur d'API (p. ex., openrouter)
temperaturenumberTempérature d'échantillonnage
max_tokensnumberJetons maximaux par complément
batch_sizenumberEntrées par lot concurrent
concurrencynumberRequêtes API parallèles maximales
coaching_filestringChemin du fichier d'invite de coaching, s'il est utilisé
method_pathstringChemin du répertoire du plugin de méthode, s'il est utilisé
fst_retriesnumberNombre de tentatives de réessai FST
{
  "config": {
    "api_provider": "openrouter",
    "temperature": 0.0,
    "max_tokens": 32768,
    "batch_size": 25,
    "concurrency": 8
  }
}

:::info Les Cartes d'Exécution Publiées Incluent method_config Lorsqu'une carte d'exécution est publiée via mt-eval publish, publish.py injecte un bloc method_config contenant la MethodConfig canonique à 8 champs. Cela permet une installation sans friction du classement — n'importe qui peut reproduire la méthode directement à partir de la carte publiée.

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

Tous les champs utilisent camelCase et suivent le schéma MethodConfig canonique (voir Construire une Méthode). :::

system_prompt_sha256 / system_prompt_used​

ChampTypeDescription
system_prompt_sha256stringHachage SHA-256 de l'invite système. Inclus dans l'empreinte
system_prompt_usedstringLe texte complet de l'invite système envoyé au modèle

Le hachage de l'invite fait partie de l'empreinte — deux exécutions avec des invites différentes auront des empreintes différentes même si tous les autres paramètres correspondent.

fingerprint​

Un identifiant de reproductibilité. Deux exécutions avec des empreintes identiques ont utilisé la même configuration expérimentale.

ChampTypeDescription
hashstringHachage SHA-256 des composants triés
componentsobjectLes valeurs d'entrée qui ont été hachées

Composants de l'Empreinte​

ComposantDescription
dataset_sha256Hachage du fichier d'ensemble de données
model_slugModèle utilisé
conditionÉtiquette de condition d'expérience
system_prompt_sha256Hachage de l'invite système
temperatureTempérature d'échantillonnage
harness_versionVersion du harnais
{
  "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 Empreinte ≠ Hachage de Carte d'Exécution L'empreinte identifie la configuration de l'expérience. Le run_card_hash vérifie l'intégrité du fichier de résultats. Consultez Empreinte vs Hachage de Carte d'Exécution pour plus de détails. :::

scores​

Métriques agrégées pour l'ensemble de l'exécution.

Scores de Niveau Supérieur​

ChampTypeDescription
totalnumberNombre total d'entrées évaluées
exact_matchesnumberEntrées où la sortie correspondait exactement à l'étalon-or
exact_match_ratenumberexact_matches / total (0,0–1,0)
fst_acceptednumberEntrées où l'analyseur FST a accepté la sortie
fst_acceptance_ratenumberfst_accepted / total (0,0–1,0). null si aucun analyseur FST n'a été utilisé
chrf_plus_plusnumberScore chrF++ au niveau du corpus (0–100)
errorsnumberEntrées qui ont échoué (erreur API, délai d'attente, etc.)
avg_latency_secondsnumberTemps de réponse moyen sur toutes les entrées
median_latency_secondsnumberTemps de réponse médian
p95_latency_secondsnumberTemps de réponse au 95e percentile

by_difficulty​

Scores ventilés par niveau de difficulté. Chaque clé (entier 1–5) contient les mêmes champs de métriques que les scores de niveau supérieur.

{
  "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 ventilés par provenance d'entrée. Chaque clé (p. ex., gold_standard, textbook) contient les mêmes champs de métriques.

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

totals​

Suivi de l'utilisation des jetons et des coûts pour l'ensemble de l'exécution.

ChampTypeDescription
prompt_tokensnumberNombre total de jetons d'entrée sur tous les appels API
completion_tokensnumberNombre total de jetons de sortie
reasoning_tokensnumberJetons utilisés pour le raisonnement en chaîne de pensée (dépendant du modèle, 0 pour la plupart des modèles)
cached_tokensnumberJetons servis à partir du cache d'invite du fournisseur
total_cost_usdnumberCoût total en USD (tel que rapporté par l'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​

Métadonnées d'environnement d'exécution pour la reproductibilité.

ChampTypeDescription
harness_versionstringVersion du harnais (reflète le harness_version de niveau supérieur)
harness_git_commitstringSHA du commit Git du harnais au moment de l'exécution
python_versionstringVersion de l'interpréteur Python
sacrebleu_versionstringVersion de la bibliothèque sacrebleu (utilisée pour la notation chrF++)
osstringIdentifiant du système d'exploitation
{
  "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[]​

Le tableau des résultats par entrée. Un objet par entrée d'ensemble de données, dans l'ordre des index.

ChampTypeDescription
entry_idintegerID de cette entrée dans le corpus (correspond à entries[].id)
sourcestringLe texte source qui a été traduit
referencestringLa référence étalon-or du corpus
predictedstringLa sortie réelle de la méthode
exact_matchbooleanSi predicted correspond exactement à reference après normalisation
entry_chrfnumberScore chrF++ au niveau de la phrase pour cette entrée (0–100)
fst_acceptedboolean | nullSi l'analyseur FST a accepté la sortie. null si aucun analyseur n'a été configuré
fst_analysisstring[]Chaînes d'analyse FST pour la sortie (tableau vide si non analysé ou rejeté)
difficultyintegerNiveau de difficulté du corpus (1–5)
provenancestringÉtiquette de provenance du corpus
latency_secondsnumberTemps de réponse pour cette entrée individuelle
usageobjectUtilisation des jetons par entrée : { prompt_tokens, completion_tokens, reasoning_tokens }
errorstring | nullMessage d'erreur si cette entrée a échoué. null en cas de succès
{
  "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​

ChampTypeDescription
run_card_hashstringHachage SHA-256 de l'ensemble de la carte d'exécution JSON, avec le champ run_card_hash lui-même défini à "" lors du hachage

C'est le sceau de détection de falsification. Le classement recalcule ce hachage lors de la soumission et rejette les cartes où il ne correspond pas.

Calcul du hachage :

  1. Sérialiser la carte d'exécution en JSON avec run_card_hash défini à ""
  2. Calculer SHA-256 de la chaîne sérialisée
  3. Définir run_card_hash au résumé hexadécimal résultant
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 Analyse Détaillée par Entrée Les cartes d'exécution publiées remplissent également la table Supabase run_card_entries, qui stocke les résultats par entrée pour l'analyse détaillée sur le classement. Cette table est remplie automatiquement lors de mt-eval publish. :::

Voir Aussi​