دليل الوكيل: الفوز في الـ Arena

تُعد MT Eval Arena منصة مفتوحة لقياس أداء أساليب الترجمة الآلية. ابنِ أسلوبًا يترجم بشكل أفضل مما هو موجود، وأثبت ذلك من خلال تقييم قابل لإعادة الإنتاج، وسيتم نشر الأسلوب الفائز في بيئة الإنتاج — مع تدفق الإيرادات إلى المجتمع اللغوي الذي يخدمه.

:::tip لماذا هذا مهم تغطي خدمات الترجمة التجارية نحو 130 لغة. ويدّعي نموذج OMT-1600 من Meta تغطية 1,600 لغة إضافية — لكن بالنسبة لنحو 1,300 لغة في أدنى مستويات الموارد، فإن الجودة غير مُتحقَّق منها عبر تقييم مستقل، كما أن أوزان النموذج غير متاحة. توفر الـ Arena البنية التحتية للاختبار المستقل. إذا كان أسلوبك يعمل بنجاح، فيمكنه الوصول إلى بيئة الإنتاج للغات لا توجد لها ترجمة آلية مُتحقَّق منها بشكل مستقل. :::

---

إعداد البيئة

# 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

يُنتج إطار الاختبار سجل تشغيل — وهو ملف JSON يُحفظ في eval/logs/ ويحتوي على كل ترجمة، وكل درجة مقياس، وبصمة تشفيرية تربط النتائج بتكوين التجربة الدقيق.

أعلام مفيدة:

العلم	ما يفعله
-m <model>	معرّف النموذج في OpenRouter (افصل بفواصل للتشغيل المتوازي متعدد النماذج)
--condition <name>	تسمية لأسلوبك (تظهر في لوحة الصدارة)
--temperature <float>	درجة حرارة أخذ العينات (الأقل = أكثر حتمية)
--batch-size <n>	عدد الإدخالات لكل استدعاء API (الافتراضي: 25)
--dry-run	التحقق من صحة التكوين دون إجراء استدعاءات API
--ids 0,1,2,3	تشغيل معرّفات إدخالات محددة فقط

# 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 (استعراض النماذج المتاحة).

---

ابنِ أسلوبك الخاص

يقبل إطار الاختبار أي صنف (class) في Python ينفّذ بروتوكول 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

التحديد البنيوي للأنواع (Structural typing) — لا يحتاج صنفك إلى الوراثة من أي شيء. إذا كان يمتلك توقيع التابع 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	الصحة الصرفية (للغات التي تتوفر لها FSTs)	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	جودة قريبة من المتحدث الأصلي

التفاصيل الكاملة: مواصفات التقييم

---

أرسل أسلوبك إلى لوحة الصدارة

عندما تكون راضيًا عن درجتك:

1. قيّم تشغيلك — ينتج mt-eval test eval/logs/your_run.json تقرير اختبار مُقيَّمًا (TestReport)
2. راجع درجاتك — يُنشئ mt-eval dashboard eval/logs/your_run.json لوحة معلومات مرئية
3. أرسل — اتبع دليل إرسال أسلوب

تُربط كل عملية إرسال ببصمة لتكوين محدد وإصدار محدد من مجموعة البيانات. لا غموض حول ما تم اختباره.

---

النشر في بيئة الإنتاج

يمكن نشر الأساليب المُثبتة عبر champollion، وهي واجهة سطر الأوامر (CLI) للترجمة في بيئة الإنتاج. فالواجهة نفسها التي يقيّمها إطار الاختبار تصبح ملحقًا (plugin) يترجم محتوى حقيقيًا.

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

← النشر في بيئة الإنتاج — انقل أسلوبك من الـ Arena إلى بيئة الإنتاج.

---

استكشاف الأخطاء وإصلاحها

المشكلة	الحل
OPENROUTER_API_KEY not set	صدّر المفتاح أو أضفه إلى .env (انظر الإعداد أعلاه)
Model not found	شغّل mt-eval list models --live لاستعراض النماذج المتاحة
جميع الترجمات فارغة	تحقق من أن مفتاح API لديك يملك رصيدًا. جرّب --dry-run أولًا
ModuleNotFoundError	تأكد من أنك فعّلت البيئة الافتراضية (venv) وشغّلت pip install -e .
لم يُحفظ سجل التشغيل	تحقق من eval/logs/ — تُسمى السجلات حسب الطابع الزمني

---

انظر أيضًا

• إرسال أسلوب — دليل الإرسال خطوة بخطوة
• مواصفات التقييم — التعريفات الكاملة للمقاييس وأوزانها
• مواصفات إطار الاختبار — مرجع البنية والتكوين
• قواعد لوحة الصدارة — متطلبات الإرسال
• سيادة البيانات — OCAP وCARE وحوكمة المجتمع
• هل تريد استخدام أسلوب موجود؟ انظر دليل وكيل champollion — التثبيت والترجمة بأمر واحد.