Guide de l'agent : Remporter l'Arena

MT Eval Arena est une plateforme d'évaluation comparative ouverte pour les méthodes de traduction automatique. Développez une méthode qui traduit mieux que ce qui existe, prouvez-le avec une notation reproductible, et la méthode gagnante sera déployée en production — avec des revenus versés à la communauté linguistique qu'elle sert.

:::tip Pourquoi cela importe Les services de traduction commerciaux couvrent ~130 langues. OMT-1600 de Meta en revendique 1 600 de plus — mais pour les ~1 300 aux niveaux de ressources les plus faibles, la qualité n'est pas vérifiée par une évaluation indépendante et les poids du modèle ne sont pas disponibles. L'Arena fournit l'infrastructure de test indépendante. Si votre méthode fonctionne, elle peut atteindre la production pour les langues où aucune traduction automatique indépendamment vérifiée n'existe. :::

---

Configuration de l'environnement

# Clone the harness
git clone https://github.com/gamedaysuits/arena.git
cd arena

# Create a virtual environment (do NOT install into global Python)
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows

# Install dependencies
pip install -e .

Clé API — le harnais utilise OpenRouter pour appeler les modèles LLM. Définissez votre clé :

# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..."

# Option 2: .env file (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env

Obtenez une clé sur openrouter.ai/keys. Les modèles de niveau gratuit fonctionnent pour l'expérimentation.

---

Exécutez votre premier benchmark

# Run a baseline LLM against the Cree evaluation corpus
mt-eval run --corpus data/edtekla-dev-v1.json

# Or specify a model explicitly
mt-eval run --corpus data/edtekla-dev-v1.json -m google/gemini-2.5-flash

Le harnais produit un journal d'exécution — un fichier JSON enregistré dans eval/logs/ contenant chaque traduction, chaque score de métrique, et une empreinte cryptographique liant les résultats à la configuration exacte de l'expérience.

Drapeaux utiles :

Drapeau	Ce qu'il fait
-m <model>	Slug du modèle OpenRouter (séparez par des virgules pour les exécutions parallèles multi-modèles)
--condition <name>	Étiquette pour votre méthode (apparaît sur le classement)
--temperature <float>	Température d'échantillonnage (inférieur = plus déterministe)
--batch-size <n>	Entrées par appel API (par défaut : 25)
--dry-run	Valider la configuration sans effectuer d'appels API
--ids 0,1,2,3	Exécuter uniquement des ID d'entrée spécifiques

# Multi-model comparison (runs in parallel)
mt-eval run --corpus data/edtekla-dev-v1.json -m gemini-2.5-flash,claude-sonnet-4,gpt-4.1

# Dry run to validate config
mt-eval run --corpus data/edtekla-dev-v1.json --dry-run

Autres commandes : mt-eval test <log.json> (noter une exécution terminée), mt-eval compare <log1> <log2> (comparer les exécutions), mt-eval dashboard <logs/*.json> (générer un tableau de bord HTML), mt-eval list models --live (parcourir les modèles disponibles).

---

Construisez votre propre méthode

Le harnais accepte toute classe Python qui implémente le protocole TranslationMethod :

from mt_eval_harness.config import RunConfig

class YourMethod:
    """Build whatever you want inside. The harness only sees this interface."""

    async def translate(
        self,
        entries: list[dict],
        config: RunConfig,
    ) -> list[dict]:
        """
        Args:
            entries: [{"id": 1, "source": "Hello"}, ...]
            config:  RunConfig with source_locale, target_locale, model, etc.

        Returns: one result dict per entry, each containing:
            - id: int          — entry ID from the corpus
            - predicted: str   — the translated text
            - latency_s: float — time taken in seconds
            - usage: dict      — token usage {prompt_tokens, completion_tokens}
            - error: str|None  — error message if failed
            - metadata: dict   — any process-specific metadata
        """
        results = []
        for entry in entries:
            # Your translation logic here — LLM prompting, FST pipeline,
            # dictionary lookup, fine-tuned model, anything.
            translated = await self._my_translate(entry["source"])
            results.append({
                "id": entry["id"],
                "predicted": translated,
                "latency_s": 0.5,
                "usage": {"prompt_tokens": 100, "completion_tokens": 20},
                "error": None,
                "metadata": {"method": "my-custom-pipeline"},
            })
        return results

Typage structurel — votre classe n'a pas besoin d'hériter de quoi que ce soit. Si elle a la bonne signature de méthode translate, cela fonctionne. Cela signifie que les pipelines existants peuvent être adaptés avec un wrapper fin.

Intégrez-le au harnais :

import asyncio
from mt_eval_harness.config import RunConfig
from mt_eval_harness.runner import execute_run

async def main():
    config = RunConfig(
        corpus_path="data/edtekla-dev-v1.json",
        model="google/gemini-2.5-flash",
        condition="my-method-v1",
    )
    results = await execute_run(config, method=YourMethod())
    print(f"Composite: {results['scores']['composite']}")

asyncio.run(main())

---

Idées de méthodes

Chacune d'entre elles dispose d'un guide complet avec des conseils de mise en œuvre :

Approche	Description	Guide
Pipeline contrôlé par FST	La validation morphologique détecte ce que les LLM manquent	Tutoriel
LLM entraîné	Injectez des règles de grammaire et des dictionnaires dans les invites	Tutoriel
LLM augmenté par dictionnaire	Forcez la cohérence terminologique	Tutoriel
Prompting few-shot	Incluez des exemples de traductions dans l'invite	Tutoriel
Modèle affiné	Entraînez sur des données parallèles (simplement pas sur l'ensemble d'évaluation)	Tutoriel
Modèles chaînés	Multi-passe : brouillon → affinage → validation	Tutoriel
Hybride basé sur des règles	Combinez des règles déterministes avec la flexibilité du LLM	Tutoriel

---

Comprendre vos scores

Après une exécution de benchmark, vous verrez une sortie comme :

══════════════════════════════════════════════════
  Composite Score: 0.67 (Functional)
──────────────────────────────────────────────────
  chrF++:              0.72
  FST acceptance:      0.82
  Exact match:         0.31
  Morphological acc.:  0.88
  Semantic score:      0.64
══════════════════════════════════════════════════

Métriques clés :

Métrique	Ce qu'elle mesure	Poids
chrF++	Précision de la traduction au niveau des caractères	30 %
Acceptation FST	Validité morphologique (pour les langues avec FST)	25 %
Correspondance exacte	Correspondances de chaînes parfaites par rapport à la référence	15 %
Précision morphologique	Correction du lemme + des traits	15 %
Score sémantique	Préservation du sens indépendamment de la forme de surface	15 %

Niveaux de qualité :

Niveau	Plage composite	Ce que cela signifie
Baseline	0,00–0,30	Sous le hasard aléatoire pour la langue
Émergent	0,30–0,50	Montre des promesses mais non utilisable
Fonctionnel	0,50–0,70	Utilisable avec post-édition
Déployable	0,70–0,85	Prêt pour la production avec examen par des locuteurs
Fluide	0,85–1,00	Qualité quasi-native

Détails complets : Spécification de notation

---

Soumettez au classement

Quand vous êtes satisfait de votre score :

1. Notez votre exécution — mt-eval test eval/logs/your_run.json produit un TestReport noté
2. Examinez vos scores — mt-eval dashboard eval/logs/your_run.json génère un tableau de bord visuel
3. Soumettez — suivez le guide Soumettre une méthode

Chaque soumission est empreinte à une configuration spécifique et à une version d'ensemble de données. Aucune ambiguïté sur ce qui a été testé.

---

Déployez en production

Les méthodes éprouvées peuvent être déployées via champollion, l'interface CLI de traduction en production. La même interface que le harnais évalue devient un plugin qui traduit le contenu réel.

# Export your benchmark as a champollion plugin
mt-eval export --report eval/logs/report.json --name crk-v1 --type llm-coached --locales crk

→ Déployer en production — faites passer votre méthode de l'Arena à la production.

---

Dépannage

Problème	Solution
OPENROUTER_API_KEY not set	Exportez la clé ou ajoutez-la à .env (voir la configuration ci-dessus)
Model not found	Exécutez mt-eval list models --live pour parcourir les modèles disponibles
Toutes les traductions sont vides	Vérifiez que votre clé API a des crédits. Essayez d'abord --dry-run
ModuleNotFoundError	Assurez-vous d'avoir activé le venv et exécuté pip install -e .
Journal d'exécution non enregistré	Vérifiez eval/logs/ — les journaux sont nommés par horodatage

---

Voir aussi

• Soumettre une méthode — guide de soumission étape par étape
• Spécification de notation — définitions complètes des métriques et poids
• Spécification du harnais — référence d'architecture et de configuration
• Règles du classement — exigences de soumission
• Souveraineté des données — OCAP, CARE et gouvernance communautaire
• Vous voulez utiliser une méthode existante ? Consultez le Guide de l'agent champollion — installez et traduisez en une seule commande.