에이전트 가이드: 아레나에서 승리하기
MT Eval Arena는 기계 번역 방법을 위한 오픈 벤치마킹 플랫폼이에요. 기존보다 더 나은 번역을 수행하는 방법을 구축하고, 재현 가능한 점수로 이를 증명하면, 승리한 방법이 프로덕션에 배포돼요 — 수익은 해당 방법이 서비스하는 언어 커뮤니티로 흘러가게 돼요.
:::tip 이것이 중요한 이유 상용 번역 서비스는 약 130개 언어를 지원해요. Meta의 OMT-1600은 1,600개 언어를 더 지원한다고 주장하지만, 가장 자원이 부족한 등급에 속하는 약 1,300개 언어의 경우 독립적인 평가로 품질이 검증되지 않았고 모델 가중치도 제공되지 않아요. 아레나는 독립적인 테스트 인프라를 제공해요. 여러분의 방법이 작동한다면, 독립적으로 검증된 MT가 존재하지 않는 언어에 대해 프로덕션까지 도달할 수 있어요. :::
환경 설정
# 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 키 — 이 하니스는 OpenRouter를 사용해 LLM 모델을 호출해요. 키를 설정하세요:
# Option 1: export (session only)
export OPENROUTER_API_KEY="sk-or-..."
# Option 2: .env file (persistent, gitignored)
echo 'OPENROUTER_API_KEY=sk-or-...' > .env
키는 openrouter.ai/keys에서 발급받으세요. 무료 등급 모델로도 실험이 가능해요.
첫 번째 벤치마크 실행하기
# 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
이 하니스는 실행 로그(run log) 를 생성해요 — eval/logs/에 저장되는 JSON 파일로, 모든 번역, 모든 메트릭 점수, 그리고 결과를 정확한 실험 구성에 연결하는 암호화 지문이 담겨 있어요.
유용한 플래그:
| 플래그 | 기능 |
|---|---|
-m <model> | OpenRouter 모델 슬러그 (다중 모델 병렬 실행 시 쉼표로 구분) |
--condition <name> | 방법에 대한 라벨 (리더보드에 표시됨) |
--temperature <float> | 샘플링 온도 (낮을수록 더 결정론적) |
--batch-size <n> | API 호출당 항목 수 (기본값: 25) |
--dry-run | API 호출 없이 구성 검증 |
--ids 0,1,2,3 | 특정 항목 ID만 실행 |
# 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
기타 명령어: mt-eval test <log.json> (완료된 실행에 점수 매기기), mt-eval compare <log1> <log2> (실행 비교), mt-eval dashboard <logs/*.json> (HTML 대시보드 생성), mt-eval list models --live (사용 가능한 모델 탐색).
나만의 방법 구축하기
이 하니스는 TranslationMethod 프로토콜을 구현하는 모든 Python 클래스를 허용해요:
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
구조적 타이핑 — 여러분의 클래스는 무언가를 상속받을 필요가 없어요. 올바른 translate 메서드 시그니처만 갖추고 있다면 작동해요. 즉, 기존 파이프라인을 얇은 래퍼로 적응시킬 수 있다는 의미예요.
하니스에 연결하기:
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())
방법 아이디어
다음 각 항목에는 구현 지침이 담긴 전체 쿡북이 있어요:
| 접근 방식 | 설명 | 쿡북 |
|---|---|---|
| FST-gated pipeline | 형태론적 검증으로 LLM이 놓치는 부분을 잡아내요 | 튜토리얼 |
| Coached LLM | 문법 규칙과 사전을 프롬프트에 주입해요 | 튜토리얼 |
| Dictionary-augmented | 용어 일관성을 강제해요 | 튜토리얼 |
| Few-shot prompting | 프롬프트에 예시 번역을 포함해요 | 튜토리얼 |
| Fine-tuned model | 병렬 데이터로 학습해요 (단, 평가 세트는 제외) | 튜토리얼 |
| Chained models | 다중 패스: 초안 → 정제 → 검증 | 튜토리얼 |
| Rule-based hybrid | 결정론적 규칙과 LLM의 유연성을 결합해요 | 튜토리얼 |
점수 이해하기
벤치마크 실행 후, 다음과 같은 출력을 보게 돼요:
══════════════════════════════════════════════════
Composite Score: 0.67 (Functional)
──────────────────────────────────────────────────
chrF++: 0.72
FST acceptance: 0.82
Exact match: 0.31
Morphological acc.: 0.88
Semantic score: 0.64
══════════════════════════════════════════════════
주요 메트릭:
| 메트릭 | 측정 항목 | 가중치 |
|---|---|---|
| chrF++ | 문자 단위 번역 정확도 | 30% |
| FST acceptance | 형태론적 유효성 (FST가 있는 언어의 경우) | 25% |
| Exact match | 참조 대비 완벽한 문자열 일치 | 15% |
| Morphological accuracy | 표제어 + 자질 정확성 | 15% |
| Semantic score | 표면 형태와 무관한 의미 보존 | 15% |
품질 등급:
| 등급 | composite score 범위 | 의미 |
|---|---|---|
| Baseline | 0.00–0.30 | 해당 언어에서 무작위 확률 이하 |
| Emerging | 0.30–0.50 | 가능성은 보이나 사용 불가 |
| Functional | 0.50–0.70 | 포스트 에디팅을 거치면 사용 가능 |
| Deployable | 0.70–0.85 | 화자 검토를 거치면 프로덕션 준비 완료 |
| Fluent | 0.85–1.00 | 원어민에 가까운 품질 |
자세한 내용: Scoring Specification
리더보드에 제출하기
점수에 만족하셨다면:
- 실행에 점수 매기기 —
mt-eval test eval/logs/your_run.json가 점수가 매겨진 TestReport를 생성해요 - 점수 검토하기 —
mt-eval dashboard eval/logs/your_run.json가 시각적 대시보드를 생성해요 - 제출하기 — 방법 제출하기 가이드를 따르세요
모든 제출은 특정 구성과 데이터셋 버전에 지문이 매겨져요. 무엇이 테스트되었는지에 대한 모호함이 없어요.
프로덕션에 배포하기
검증된 방법은 프로덕션 번역 CLI인 champollion을 통해 배포할 수 있어요. 하니스가 평가하는 동일한 인터페이스가 실제 콘텐츠를 번역하는 플러그인이 돼요.
# Export your benchmark as a champollion plugin
mt-eval export --report eval/logs/report.json --name crk-v1 --type llm-coached --locales crk
→ 프로덕션에 배포하기 — 여러분의 방법을 아레나에서 프로덕션으로 가져가세요.
문제 해결
| 문제 | 해결 방법 |
|---|---|
OPENROUTER_API_KEY not set | 키를 export하거나 .env에 추가하세요 (위 설정 참조) |
Model not found | mt-eval list models --live을 실행해 사용 가능한 모델을 탐색하세요 |
| 모든 번역이 비어 있음 | API 키에 크레딧이 있는지 확인하세요. 먼저 --dry-run을 시도해 보세요 |
ModuleNotFoundError | venv를 활성화하고 pip install -e .을 실행했는지 확인하세요 |
| 실행 로그가 저장되지 않음 | eval/logs/을 확인하세요 — 로그는 타임스탬프로 이름이 지정돼요 |
함께 보기
- 방법 제출하기 — 단계별 제출 가이드
- Scoring Specification — 전체 메트릭 정의 및 가중치
- Harness Specification — 아키텍처 및 구성 참조
- Leaderboard Rules — 제출 요건
- Data Sovereignty — OCAP, CARE, 그리고 커뮤니티 거버넌스
- 기존 방법을 사용하고 싶으신가요? champollion 에이전트 가이드를 참조하세요 — 명령어 하나로 설치하고 번역하세요.