# إنشاء ملف eval_manifest.json

> الملف الموجود في جذر المجموعة المرجعية والذي يحدد أي المقاطع ينتمي إلى أي تشغيل من تشغيلات التقييم.
>
> جرى التحقق من المحتوى مقابل تطبيق RoughCut الحالي بتاريخ 28 أغسطس 2026
> https://www.roughcuteditor.com/ar/docs/eval-manifest

يوجد ملف eval_manifest.json في جذر المجموعة المرجعية، وهو يربط أسماء التشغيل بقوائم من المقاطع. مفاتيحه في المستوى الأعلى هي أسماء التشغيل، وكل قيمة يجب أن تكون مصفوفة. ووضعا التشغيل القياسيان smoke و full هما ما يقف خلف زري اللوحة، وأي اسم مصفوفة صالح آخر — arabic مثلا — يظهر في قائمة Subsets ويكتب ملف ملخص خاصا به. والمدخل إما اسم مجلد المقطع مجردا، وإما كائن يحمل clip_id مع خيارات مثل language التي تقبل en أو ar أو auto. ويجب أن يكون اسم التشغيل غير فارغ، وبطول 40 حرفا كحد أقصى، ومكوّنا من حروف ASCII وأرقام وشرطة سفلية وشرطة فقط. وقائمة مفقودة أو مشوّهة أو ملف JSON غير صالح تُفشل التشغيل بصوت عالٍ قبل احتساب أي مقطع، أما مجلد مذكور غير موجود فيُتخطى بسبب clip_dir_missing.

> ! **متقدم.** هذا الملف لا يهمّ إلا إذا كنت تشغّل تقييمات. فإن لم تكن لديك مجموعة مرجعية، فلا حاجة بك إلى ملف بيان — والخيار الآمن هو ألا يكون لديك واحد. وملف البيان لا يكلّفك شيئا إذا أخطأت فيه بالمعنى التدميري: فالملف السيئ يفشل أو يتخطى بصوت عالٍ، ولا يتلف مقاطعك أبدا. لكن ما قد يكلّفك إياه هو إنفاق عند المزود، إذا أدرجت من المقاطع أكثر مما قصدت بكثير ثم شغّلت تقييما كاملا.

## أين يوضع

يوجد `eval_manifest.json` في **جذر** مجلد المجموعة المرجعية — المجلد نفسه الذي ربطته عبر `اختيار مجلد المجموعة المرجعية...`، إلى جانب المجلدات الفرعية للمقاطع. راجع [بناء مجموعة مرجعية](/ar/docs/golden-set).

## شكل الملف

الملف كائن JSON. وكل مفتاح في المستوى الأعلى هو **اسم تشغيل**، وكل قيمة **مصفوفة من مدخلات المقاطع**.

| اسم التشغيل | الحالة | أين يظهر |
|---|---|---|
| `smoke` | وضع قياسي | `Run smoke eval (5)` |
| `full` | وضع قياسي | `Run full evaluation` |
| أي اسم صالح آخر | مجموعة فرعية يعرّفها المستخدم | قائمة `Subsets`، بصيغة `Run <name> subset` |

تتصرف المجموعة الفرعية تماما كأي تشغيل قياسي وتكتب ملف ملخص خاصا بها، فلا تستبدل قائمة `arabic` وقائمة `full` نتائج بعضهما أبدا. ولا تظهر قائمة `Subsets` إلا حين يعرّف ملف البيان لديك قائمة إضافية فعلا.

أما المفاتيح الإضافية في المستوى الأعلى التي ليست قوائم تشغيل فيتسامح معها التطبيق — إذ لا يقرأ المشغّل إلا مفتاح الوضع الذي طلبته.

## مثال كامل

```json
{
  "smoke": [
    "my_clip_01",
    "my_clip_02",
    "my_clip_03",
    "my_clip_04",
    "my_clip_05"
  ],
  "full": [
    {"clip_id": "my_clip_01"},
    {"clip_id": "my_clip_02", "language": "en"},
    {"clip_id": "my_clip_03"},
    {"clip_id": "my_clip_04"},
    {"clip_id": "my_clip_05"},
    {"clip_id": "my_clip_ar_01", "language": "ar"}
  ],
  "arabic": [
    {"clip_id": "my_clip_ar_01", "language": "ar"},
    {"clip_id": "my_clip_ar_02", "language": "ar"}
  ]
}
```

يعرّف ذلك الملف خمسة مقاطع للتشغيل السريع، وستة مقاطع للتشغيل الكامل، ومجموعة فرعية واحدة تظهر في اللوحة باسم `Run arabic subset`.

## المدخلات

المدخل أحد شيئين.

**سلسلة نصية مجردة** — اسم مجلد المقطع، تماما كما هو على القرص:

```json
"my_clip_01"
```

**كائن** يحمل `clip_id` وحقولا اختيارية:

```json
{"clip_id": "my_clip_ar_01", "language": "ar"}
```

| الحقل | النوع | المعنى |
|---|---|---|
| `clip_id` | نص | اسم مجلد المقطع. مطلوب عمليا — فالكائن الذي يخلو منه لا مجلد له ليُعثر عليه |
| `language` | نص | لغة التفريغ النصي لهذا المقطع: `en` أو `ar` أو `auto` |
| `duration_s` | رقم | قيمة تسجيلية اختيارية تُحمل في ملف البيان |
| `coverage` | رقم | قيمة تسجيلية اختيارية تُحمل في ملف البيان |
| `gold_source` | نص | قيمة تسجيلية اختيارية تُحمل في ملف البيان |

ومعرّف المقطع هو اسم المجلد لا غير — فلا حل للمسارات، ولا استخدام لأنماط البدل، ولا مطابقة تقريبية.

## كيف تُختار اللغة

لكل مقطع، يأخذ RoughCut أول ما يجده من هذه:

1. قيمة `language` في مدخل ملف البيان.
2. قيمة `language` في ملف `manifest.json` الخاص بمجلد ذلك المقطع، إن كنت تحتفظ بواحد.
3. `auto`.

وضبط اللغة صراحة يستحق العناء في مجموعة متعددة اللغات: فهو يزيل مصدرا من مصادر التفاوت بين تشغيل وآخر في قياسك. راجع [ضبط لغة التفريغ النصي](/ar/docs/language).

## قواعد أسماء التشغيل

يجب أن يكون اسم التشغيل:

- **غير فارغ**،
- **بطول 40 حرفا كحد أقصى**،
- **مكوّنا من حروف ASCII وأرقام وشرطة سفلية وشرطة فقط**.

وأي شيء غير ذلك يُرفض بالرسالة `mode must be 'smoke', 'full', or a subset list defined in eval_manifest.json (letters, digits, _ and - only)`. فاسم فيه مسافة أو حركة أو حروف عربية لن يعمل، ولن يُعرض في قائمة `Subsets` أيضا.

## ما الذي قد يعطب، وكيف يخبرك التطبيق

| المشكلة | ما الذي يحدث |
|---|---|
| الملف ليس JSON صالحا | يفشل فك الترميز ويتوقف التشغيل قبل احتساب أي مقطع. ولا يُحتسب عليك شيء |
| الملف مفقود | يفشل التشغيل برسالة تسمّي المسار المتوقع وتشير إلى توثيق الصيغة |
| اسم التشغيل المطلوب بلا قائمة | يفشل التشغيل بالرسالة `Eval manifest has no '<mode>' list` |
| قيمة اسم التشغيل ليست مصفوفة | القائمة مشوّهة، ويفشل التشغيل بصوت عالٍ بدل أن يخمّن. كما أنها لا تظهر أبدا في `Subsets` |
| مدخل يسمّي مجلدا غير موجود | يُتخطى ذلك المقطع بسبب `clip_dir_missing`، ويكمل باقي التشغيل |
| مدخل من نوع كائن بلا `clip_id` | لا يوجد مجلد يمكن حله، فيُتخطى بسبب `clip_dir_missing` |
| مجلد المقطع موجود لكن بلا وسائط | يُتخطى بسبب `missing_media` |
| مجلد المقطع بلا `gold_v2.json` | يُتخطى بسبب `missing_gold` |
| طلب اسم تشغيل غير معروف | يُرفض بموجب قواعد أسماء التشغيل أعلاه |
| macOS يمنع الوصول إلى المجلد | يفشل التشغيل برسالة أذونات صريحة، لا بنتيجة فارغة صامتة |

وحالات التخطي تُبلَّغ دائما لكل مقطع مع سببها، فملف بيان ناقص يظل يعطيك تشغيلا عاملا على المقاطع الصحيحة.

## التكرارات والترتيب

تُعالج المقاطع بالترتيب الذي تظهر به في القائمة، ويطبّق التشغيل الكامل حده الأقصى بأخذ المدخلات الأولى — فترتيب قائمة `full` هو ما يقرر أي المقاطع ينجو من حد قدره 15.

ولا تدرج المقطع نفسه مرتين في تشغيل واحد. فهذا لا يعطيك معلومة جديدة، ويعطي ذلك المقطع وزنا مضاعفا في متوسطات التشغيل.

## إبقاء الملف مقروءا

- أبقِ كل عيّنة برمجية وكل معرّف مقطع بحروف ASCII خالصة ومن اليسار إلى اليمين، حتى حين تكون المقاطع نفسها عربية. فمفاتيح JSON وأسماء المجلدات معرّفات تقنية لا نصوص عرض.
- التعليقات ليست جزءا من JSON. لا تضفها — فسيتوقف الملف عن التحليل.
- والفواصل الزائدة في نهاية القوائم ليست JSON صالحا أيضا. وهذا أشيع سبب منفرد لتوقّف ملف بيان محرَّر باليد عن العمل.

## أخطاء شائعة

- **تحرير ملف البيان بمحرر يضيف علامات اقتباس ذكية.** فـ JSON يحتاج إلى علامات اقتباس مستقيمة.
- **إدراج مسار بدل اسم مجلد.** فـ `clips/my_clip_01` ليس معرّف مقطع.
- **افتراض أن `full` تعني كل شيء.** فالتشغيل الكامل مقيَّد بالإعداد `Full eval max clips` وقيمته الافتراضية 15. اضبط ذلك الإعداد على 0 لتشغيل القائمة كاملة. راجع [مرجع الإعدادات المتقدمة](/ar/docs/advanced-settings-reference).
- **توقّع ظهور مجموعة فرعية دون تعريفها.** فقائمة `Subsets` تُبنى من ملف البيان الخاص بك، ومن القوائم التي تجتاز أسماؤها قواعد أسماء التشغيل فقط.
- **إعادة تسمية مجلد مقطع دون تحديث ملف البيان.** فتلك حالة `clip_dir_missing` فورية.

## الخطوات التالية

- [إنشاء مونتاجات مرجعية بصيغة gold_v2.json](/ar/docs/gold-reference-edit)
- [قراءة مقاييس التقييم قراءة صحيحة](/ar/docs/evaluation-metrics)
- [بناء مجموعة مرجعية](/ar/docs/golden-set)