Agent-Leitfaden: Die Arena gewinnen

Die MT Eval Arena ist eine offene Benchmarking-Plattform für maschinelle Übersetzungsmethoden. Entwickeln Sie eine Methode, die besser übersetzt als alles Bestehende, belegen Sie dies mit reproduzierbarer Bewertung, und die siegreiche Methode wird in Produktion überführt — wobei die Einnahmen an die Sprachgemeinschaft fließen, der sie dient.

:::tip Warum das wichtig ist Kommerzielle Übersetzungsdienste decken ~130 Sprachen ab. Metas OMT-1600 beansprucht 1.600 weitere — doch für die ~1.300 Sprachen in den niedrigsten Ressourcenstufen ist die Qualität durch keine unabhängige Evaluierung verifiziert, und die Modellgewichte sind nicht verfügbar. Die Arena stellt die unabhängige Testinfrastruktur bereit. Wenn Ihre Methode funktioniert, kann sie für Sprachen, für die keine unabhängig verifizierte MT existiert, in Produktion gelangen. :::

Einrichtung der Umgebung

# 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 .

API-Schlüssel — das Harness verwendet OpenRouter, um LLM-Modelle aufzurufen. Legen Sie Ihren Schlüssel fest:

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

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

Einen Schlüssel erhalten Sie unter openrouter.ai/keys. Modelle der kostenlosen Stufe eignen sich für Experimente.

Führen Sie Ihren ersten Benchmark aus

# 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

Das Harness erzeugt ein Lauf-Protokoll — eine JSON-Datei, die unter eval/logs/ gespeichert wird und jede Übersetzung, jeden Metrikwert sowie einen kryptografischen Fingerabdruck enthält, der die Ergebnisse mit der exakten Experimentkonfiguration verknüpft.

Nützliche Flags:

Flag	Funktion
`-m <model>`	OpenRouter-Modell-Slug (kommagetrennt für parallele Läufe mit mehreren Modellen)
`--condition <name>`	Bezeichnung für Ihre Methode (erscheint im Leaderboard)
`--temperature <float>`	Sampling-Temperatur (niedriger = deterministischer)
`--batch-size <n>`	Einträge pro API-Aufruf (Standard: 25)
`--dry-run`	Konfiguration validieren, ohne API-Aufrufe durchzuführen
`--ids 0,1,2,3`	Nur bestimmte Eintrags-IDs ausführen

# 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

Weitere Befehle: mt-eval test <log.json> (einen abgeschlossenen Lauf bewerten), mt-eval compare <log1> <log2> (Läufe vergleichen), mt-eval dashboard <logs/*.json> (HTML-Dashboard erzeugen), mt-eval list models --live (verfügbare Modelle durchsuchen).

Entwickeln Sie Ihre eigene Methode

Das Harness akzeptiert jede Python-Klasse, die das Protokoll TranslationMethod implementiert:

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

Strukturelle Typisierung — Ihre Klasse muss von nichts erben. Wenn sie die korrekte Signatur der Methode translate besitzt, funktioniert sie. Das bedeutet, dass bestehende Pipelines mit einem schlanken Wrapper angepasst werden können.

Binden Sie sie in das Harness ein:

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())

Methodenideen

Zu jeder dieser Ideen gibt es ein vollständiges Cookbook mit Implementierungsanleitung:

Ansatz	Beschreibung	Cookbook
FST-gesteuerte Pipeline	Morphologische Validierung erfasst, was LLMs übersehen	Tutorial
Gecoachtes LLM	Grammatikregeln und Wörterbücher in Prompts einbinden	Tutorial
Wörterbuch-gestützt	Terminologische Konsistenz erzwingen	Tutorial
Few-shot-Prompting	Beispielübersetzungen in den Prompt aufnehmen	Tutorial
Feinabgestimmtes Modell	Auf Paralleldaten trainieren (nur nicht auf dem Eval-Set)	Tutorial
Verkettete Modelle	Mehrstufig: Entwurf → Verfeinerung → Validierung	Tutorial
Regelbasierter Hybrid	Deterministische Regeln mit LLM-Flexibilität kombinieren	Tutorial

Ihre Bewertungen verstehen

Nach einem Benchmark-Lauf sehen Sie eine Ausgabe wie diese:

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

Zentrale Metriken:

Metrik	Was sie misst	Gewichtung
chrF++	Übersetzungsgenauigkeit auf Zeichenebene	30 %
FST acceptance	Morphologische Validität (für Sprachen mit FSTs)	25 %
Exact match	Perfekte String-Übereinstimmungen mit der Referenz	15 %
Morphologische Genauigkeit	Korrektheit von Lemma + Merkmalen	15 %
Semantischer Wert	Bedeutungserhalt unabhängig von der Oberflächenform	15 %

Qualitätsstufen:

Stufe	Composite-Bereich	Bedeutung
Baseline	0,00–0,30	Unter dem Zufallsniveau für die Sprache
Emerging	0,30–0,50	Vielversprechend, aber nicht nutzbar
Functional	0,50–0,70	Mit Nachbearbeitung nutzbar
Deployable	0,70–0,85	Produktionsreif mit Sprecherprüfung
Fluent	0,85–1,00	Nahezu muttersprachliche Qualität

Vollständige Details: Bewertungsspezifikation

Im Leaderboard einreichen

Wenn Sie mit Ihrer Bewertung zufrieden sind:

Bewerten Sie Ihren Lauf — mt-eval test eval/logs/your_run.json erzeugt einen bewerteten TestReport
Prüfen Sie Ihre Bewertungen — mt-eval dashboard eval/logs/your_run.json erzeugt ein visuelles Dashboard
Einreichen — folgen Sie dem Leitfaden Eine Methode einreichen

Jede Einreichung wird mit einem Fingerabdruck einer bestimmten Konfiguration und Datensatzversion versehen. Keine Mehrdeutigkeit darüber, was getestet wurde.

In Produktion überführen

Bewährte Methoden können über champollion, das Produktions-Übersetzungs-CLI, in Produktion überführt werden. Dieselbe Schnittstelle, die das Harness evaluiert, wird zu einem Plugin, das reale Inhalte übersetzt.

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

→ In Produktion überführen — bringen Sie Ihre Methode von der Arena in die Produktion.

Fehlerbehebung

Problem	Lösung
`OPENROUTER_API_KEY not set`	Exportieren Sie den Schlüssel oder fügen Sie ihn in `.env` ein (siehe Einrichtung oben)
`Model not found`	Führen Sie `mt-eval list models --live` aus, um verfügbare Modelle zu durchsuchen
Alle Übersetzungen sind leer	Prüfen Sie, ob Ihr API-Schlüssel über Guthaben verfügt. Versuchen Sie zunächst `--dry-run`
`ModuleNotFoundError`	Stellen Sie sicher, dass Sie die venv aktiviert und `pip install -e .` ausgeführt haben
Lauf-Protokoll nicht gespeichert	Prüfen Sie `eval/logs/` — Protokolle werden nach Zeitstempel benannt

Siehe auch

Eine Methode einreichen — Schritt-für-Schritt-Anleitung zur Einreichung
Bewertungsspezifikation — vollständige Metrikdefinitionen und Gewichtungen
Harness-Spezifikation — Architektur- und Konfigurationsreferenz
Leaderboard-Regeln — Einreichungsanforderungen
Datensouveränität — OCAP, CARE und Community-Governance
Möchten Sie eine bestehende Methode verwenden? Siehe den champollion Agent-Leitfaden — mit einem einzigen Befehl installieren und übersetzen.

Einrichtung der Umgebung​

Führen Sie Ihren ersten Benchmark aus​

Entwickeln Sie Ihre eigene Methode​

Methodenideen​

Ihre Bewertungen verstehen​

Im Leaderboard einreichen​

In Produktion überführen​

Fehlerbehebung​

Siehe auch​