Guia do Agente: Vencendo a Arena

O MT Eval Arena é uma plataforma aberta de benchmarking para métodos de tradução automática. Construa um método que traduza melhor do que o que existe, prove com pontuação reproduzível, e o método vencedor é implantado em produção — com receita fluindo para a comunidade de linguagem que ele serve.

:::tip Por que isso importa Serviços comerciais de tradução cobrem ~130 idiomas. O OMT-1600 da Meta afirma 1.600 mais — mas para os ~1.300 nos seus níveis de recursos mais baixos, a qualidade não é verificada por avaliação independente e os pesos do modelo não estão disponíveis. A Arena fornece a infraestrutura de testes independente. Se seu método funcionar, ele pode chegar à produção para idiomas onde nenhuma MT verificada independentemente existe. :::

---

Configuração do Ambiente

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

Chave de API — o harness usa OpenRouter para chamar modelos LLM. Defina sua chave:

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

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

Obtenha uma chave em openrouter.ai/keys. Modelos de camada gratuita funcionam para experimentação.

---

Execute Seu Primeiro 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

O harness produz um run log — um arquivo JSON salvo em eval/logs/ contendo cada tradução, cada pontuação de métrica e uma impressão digital criptográfica vinculando resultados à configuração exata do experimento.

Flags úteis:

Flag	O que faz
-m <model>	Slug do modelo OpenRouter (separe com vírgula para execuções paralelas multi-modelo)
--condition <name>	Rótulo para seu método (aparece no leaderboard)
--temperature <float>	Temperatura de amostragem (menor = mais determinístico)
--batch-size <n>	Entradas por chamada de API (padrão: 25)
--dry-run	Valide a configuração sem fazer chamadas de API
--ids 0,1,2,3	Execute apenas 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

Outros comandos: mt-eval test <log.json> (pontue uma execução concluída), mt-eval compare <log1> <log2> (compare execuções), mt-eval dashboard <logs/*.json> (gere dashboard HTML), mt-eval list models --live (navegue modelos disponíveis).

---

Construa Seu Próprio Método

O harness aceita qualquer classe Python que implemente o 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

Tipagem estrutural — sua classe não precisa herdar de nada. Se tiver a assinatura de método translate correta, funciona. Isso significa que pipelines existentes podem ser adaptados com um wrapper fino.

Conecte ao harness:

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

---

Ideias de Método

Cada uma delas tem um cookbook completo com orientação de implementação:

Abordagem	Descrição	Cookbook
Pipeline com gate FST	Validação morfológica captura o que LLMs perdem	Tutorial
LLM treinado	Injete regras de gramática e dicionários nos prompts	Tutorial
Aumentado por dicionário	Force consistência de terminologia	Tutorial
Few-shot prompting	Inclua traduções de exemplo no prompt	Tutorial
Modelo fine-tuned	Treine em dados paralelos (apenas não no conjunto de avaliação)	Tutorial
Modelos encadeados	Multi-pass: rascunho → refine → valide	Tutorial
Híbrido baseado em regras	Combine regras determinísticas com flexibilidade de LLM	Tutorial

---

Entendendo Suas Pontuações

Após uma execução de benchmark, você verá uma saída 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 principais:

Métrica	O que mede	Peso
chrF++	Precisão de tradução em nível de caractere	30%
FST acceptance	Validade morfológica (para idiomas com FSTs)	25%
Exact match	Correspondências de string perfeitas com referência	15%
Morphological accuracy	Correção de lema + características	15%
Semantic score	Preservação de significado independentemente da forma de superfície	15%

Níveis de qualidade:

Nível	Intervalo Composto	O que significa
Baseline	0.00–0.30	Abaixo da chance aleatória para o idioma
Emerging	0.30–0.50	Mostra promessa mas não é utilizável
Functional	0.50–0.70	Utilizável com pós-edição
Deployable	0.70–0.85	Pronto para produção com revisão de falante
Fluent	0.85–1.00	Qualidade quase nativa

Detalhes completos: Especificação de Pontuação

---

Envie para o Leaderboard

Quando estiver satisfeito com sua pontuação:

1. Pontue sua execução — mt-eval test eval/logs/your_run.json produz um TestReport pontuado
2. Revise suas pontuações — mt-eval dashboard eval/logs/your_run.json gera um dashboard visual
3. Envie — siga o guia Envie um Método

Cada envio é marcado com impressão digital para uma configuração específica e versão de dataset. Sem ambiguidade sobre o que foi testado.

---

Implante em Produção

Métodos comprovados podem ser implantados via champollion, a CLI de tradução de produção. A mesma interface que o harness avalia se torna um plugin que traduz conteúdo real.

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

→ Implante em Produção — leve seu método da Arena para produção.

---

Solução de Problemas

Problema	Solução
OPENROUTER_API_KEY not set	Exporte a chave ou adicione-a a .env (veja configuração acima)
Model not found	Execute mt-eval list models --live para navegar modelos disponíveis
Todas as traduções estão vazias	Verifique se sua chave de API tem créditos. Tente --dry-run primeiro
ModuleNotFoundError	Certifique-se de que ativou o venv e executou pip install -e .
Run log não salvo	Verifique eval/logs/ — logs são nomeados por timestamp

---

Veja Também

• Envie um Método — guia de envio passo a passo
• Especificação de Pontuação — definições completas de métricas e pesos
• Especificação do Harness — referência de arquitetura e configuração
• Regras do Leaderboard — requisitos de envio
• Soberania de Dados — OCAP, CARE e governança comunitária
• Quer usar um método existente? Veja o Guia do Agente champollion — instale e traduza com um comando.