Guía del Agente: Ganando en la Arena

MT Eval Arena es una plataforma abierta de evaluación comparativa para métodos de traducción automática. Construya un método que traduzca mejor que lo que existe, pruébelo con puntuación reproducible, y el método ganador se implementa en producción — con ingresos fluyendo hacia la comunidad de idiomas a la que sirve.

:::tip Por qué esto importa Los servicios de traducción comerciales cubren ~130 idiomas. OMT-1600 de Meta afirma 1.600 más — pero para los ~1.300 en sus niveles de recursos más bajos, la calidad no está verificada por evaluación independiente y los pesos del modelo no están disponibles. La Arena proporciona la infraestructura de pruebas independiente. Si su método funciona, puede llegar a producción para idiomas donde no existe MT verificada independientemente. :::

---

Configuración del Entorno

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

Clave API — el arnés utiliza OpenRouter para llamar modelos LLM. Establezca su clave:

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

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

Obtenga una clave en openrouter.ai/keys. Los modelos de nivel gratuito funcionan para experimentación.

---

Ejecute su Primer Evaluación Comparativa

# 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

El arnés produce un registro de ejecución — un archivo JSON guardado en eval/logs/ que contiene cada traducción, cada puntuación de métrica, y una huella digital criptográfica vinculando resultados a la configuración exacta del experimento.

Banderas útiles:

Bandera	Qué hace
-m <model>	Slug del modelo OpenRouter (separar con comas para ejecuciones paralelas de múltiples modelos)
--condition <name>	Etiqueta para su método (aparece en la tabla de clasificación)
--temperature <float>	Temperatura de muestreo (menor = más determinista)
--batch-size <n>	Entradas por llamada API (predeterminado: 25)
--dry-run	Validar configuración sin hacer llamadas API
--ids 0,1,2,3	Ejecutar solo IDs de entrada específicos

# 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

Otros comandos: mt-eval test <log.json> (puntuar una ejecución completada), mt-eval compare <log1> <log2> (comparar ejecuciones), mt-eval dashboard <logs/*.json> (generar panel HTML), mt-eval list models --live (examinar modelos disponibles).

---

Construya Su Propio Método

El arnés acepta cualquier clase Python que implemente el protocolo 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

Tipificación estructural — su clase no necesita heredar de nada. Si tiene la firma de método translate correcta, funciona. Esto significa que los canales existentes pueden adaptarse con un envoltorio delgado.

Conéctelo al arnés:

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

---

Ideas de Métodos

Cada una de estas tiene un libro de recetas completo con orientación de implementación:

Enfoque	Descripción	Libro de Recetas
Tubería controlada por FST	La validación morfológica detecta lo que los LLM pierden	Tutorial
LLM entrenado	Inyecte reglas gramaticales y diccionarios en indicaciones	Tutorial
Aumentado por diccionario	Forzar consistencia terminológica	Tutorial
Indicación de pocos ejemplos	Incluya traducciones de ejemplo en la indicación	Tutorial
Modelo ajustado	Entrenar en datos paralelos (solo no en el conjunto de evaluación)	Tutorial
Modelos encadenados	Multipaso: borrador → refinar → validar	Tutorial
Híbrido basado en reglas	Combinar reglas deterministas con flexibilidad LLM	Tutorial

---

Entendiendo Sus Puntuaciones

Después de una ejecución de evaluación comparativa, verá una salida como:

══════════════════════════════════════════════════
  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étricas clave:

Métrica	Qué mide	Peso
chrF++	Precisión de traducción a nivel de caracteres	30%
Aceptación FST	Validez morfológica (para idiomas con FST)	25%
Coincidencia exacta	Coincidencias de cadena perfectas contra referencia	15%
Precisión morfológica	Corrección de lema + características	15%
Puntuación semántica	Preservación de significado independientemente de la forma superficial	15%

Niveles de calidad:

Nivel	Rango Compuesto	Qué significa
Línea base	0.00–0.30	Por debajo de la probabilidad aleatoria para el idioma
Emergente	0.30–0.50	Muestra promesa pero no es utilizable
Funcional	0.50–0.70	Utilizable con posedición
Implementable	0.70–0.85	Listo para producción con revisión de hablantes
Fluido	0.85–1.00	Calidad casi nativa

Detalles completos: Especificación de Puntuación

---

Envíe a la Tabla de Clasificación

Cuando esté satisfecho con su puntuación:

1. Puntúe su ejecución — mt-eval test eval/logs/your_run.json produce un TestReport puntuado
2. Revise sus puntuaciones — mt-eval dashboard eval/logs/your_run.json genera un panel visual
3. Envíe — siga la guía Envíe un Método

Cada envío está marcado con huella digital a una configuración específica y versión de conjunto de datos. Sin ambigüedad sobre qué fue probado.

---

Implemente en Producción

Los métodos probados pueden implementarse a través de champollion, la CLI de traducción de producción. La misma interfaz que el arnés evalúa se convierte en un complemento que traduce contenido real.

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

→ Implemente en Producción — lleve su método de la Arena a producción.

---

Solución de Problemas

Problema	Solución
OPENROUTER_API_KEY not set	Exporte la clave o agréguela a .env (vea la configuración anterior)
Model not found	Ejecute mt-eval list models --live para examinar modelos disponibles
Todas las traducciones están vacías	Verifique que su clave API tenga créditos. Intente --dry-run primero
ModuleNotFoundError	Asegúrese de haber activado el venv y ejecutado pip install -e .
Registro de ejecución no guardado	Verifique eval/logs/ — los registros se nombran por marca de tiempo

---

Véase También

• Envíe un Método — guía de envío paso a paso
• Especificación de Puntuación — definiciones de métricas completas y pesos
• Especificación del Arnés — referencia de arquitectura y configuración
• Reglas de la Tabla de Clasificación — requisitos de envío
• Soberanía de Datos — OCAP, CARE, y gobernanza comunitaria
• ¿Desea usar un método existente? Vea la Guía del Agente de champollion — instale y traduzca con un comando.