مرجع التهيئة

كل حقل في oloproof.yaml وrelease.yaml، مع نوعه وقيمته الافتراضية والقيم التي يقبلها ومثال عليه، مأخوذًا من النماذج التي تقرأ الملفين. استخدمه للبحث عن حقل؛ واقرأ صفحتَي البدء السريع والبوابة لتتعلم سير العمل.

يُتحقَّق من الملفين قبل تشغيل أي شيء. فالحقل المجهول، أو الحقل المكتوب خطأً، أو القيمة من نوع خاطئ، خطأ تهيئة ويخرج الأمر بالرمز 2 دون تنفيذ أي حالة. ولكلا الملفين مخطط JSON Schema، يمكن لمحرر يقرأ JSON Schema أن يستخدمه للإكمال التلقائي. وتكتبهما الحزمة المثبّتة، مع مخططات النتائج، في schemas/v1/ تحت المجلد الحالي: python -m oloproof_core.models.schema_export (والاثنان هما project_config.schema.json وrelease_policy.schema.json).

في الجداول أدناه، تعني "مطلوب" أن الملف يُرفض دون الحقل؛ وأي حقل آخر يعرض القيمة المستخدمة حين يُترك.

نظرة سريعة على oloproof.yaml

مشروع صغير كامل. يشغّل دالة Python محليًا، ولا يحتاج إلى شبكة ولا إلى مفاتيح، وهو الشكل الذي ينشئه oloproof init.

# oloproof.yaml
version: 1
project: support-bot
dataset: datasets/support.jsonl
system:
  name: support-bot
  callable: app.bot:answer
evaluators:
  - type: exact_match
    criterion: correct_label
    field: label

الحقول العليا

concurrency

إدخالات pricing

لا يأتي Oloproof بجدول أسعار. يسمّي كل إدخال نموذجًا تمامًا كما يسمّيه model: في المُقيِّم.

# oloproof.yaml
version: 1
project: support-bot
dataset: datasets/support.jsonl
system:
  name: support-bot
  callable: app.bot:answer
evaluators:
  - type: exact_match
    criterion: correct_label
    field: label
pricing:
  - model: my-judge-model
    input_per_mtok: 0.15
    output_per_mtok: 0.6
egress: [raw_outputs]

system

يحتاج النظام إلى واحد بالضبط من callable أو http أو rag.

system.http

# oloproof.yaml
version: 1
project: support-api
dataset: datasets/support.jsonl
system:
  name: support-api
  version: "2026-10-08"
  http:
    url: http://localhost:8000/answer
    output_path: answer
    artifacts:
      retrieval/v1: debug.retrieval
evaluators:
  - type: hit_rate
    k: 5

عقد الطلب والاستجابة، وما يحدث عند انتهاء المهلة وأخطاء HTTP، موجودان في النتائج والتنفيذ.

system.rag

الإعدادات المعطاة هنا تتجاوز ما يعلنه الصنف. ويسجّل النظام المرحلي مُخرَجاته الفنية retrieval/v1 وcontext/v1 وcitations/v1 بنفسه، لذا يُرفض records بجانبه. انظر RAG.

evaluators

يأخذ كل إدخال type وهذين الحقلين المشتركين:

لا ينطبق fail إلا على مُقيِّمات النجاح/الإخفاق؛ ومُقيِّم الدرجة معه خطأ تهيئة. وon_execution_error حقل في YAML؛ ولا تأخذ أصناف المُقيِّمات في SDK وسيطًا كهذا، وتُحتسب الحالة التي وقع فيها خطأ مفقودة.

أنواع المُقيِّمات

يسرد "يقرأ" ما يعتمد عليه حكم المُقيِّم، وهو أيضًا مفتاح حكمه المخزَّن مؤقتًا. ويسمّي "SDK" الصنف في oloproof.evaluators.

الحَكَم الذي يستدعي نموذجًا مستضافًا يرسل محتوى الحالة إلى ذلك المزوِّد ويحاسبه عليه. وتُقرأ المفاتيح من متغير البيئة المسمّى في api_key_env؛ ولا يخزّنها Oloproof في هذه الملفات أبدًا.

المُقيِّمات الحتمية

حُكّام النماذج

يشترك rubric_judge وgroundedness_judge وcitation_support_judge في هذه الحقول. ويتطلب rubric_judge واحدًا بالضبط من rubric_file أو rubric_text؛ ويأخذ حَكَما RAG واحدًا على الأكثر ويستخدمان خلاف ذلك معيارًا مدمجًا. وcriterion فيهما افتراضيًا groundedness وcitation_support.

يطرح probability_judge سؤالًا ذا نوع ويقرأ احتمالات النموذج:

يشغّل cascade حَكَمًا رخيصًا أولًا ويصعّد الحالات غير المؤكدة:

تحكم المرحلتان على criterion الخاص بالتتالي نفسه؛ والمرحلة التي تسمّي معيارًا مختلفًا تُرفض.

يعطي model_classifier درجة للنص بنموذج مُدرَّب على خادم متوافق مع TEI:

مُقيِّمات RAG

مُقيِّمات الوكلاء

لكل نوع من أنواع الوكلاء criterion افتراضي، لذا يجوز تركه: اسم نوعه نفسه، أو اسم مبني من إعداده (agent_steps_le_8، agent_tool_lookup_called، agent_handoffs_le_2). انظر الوكلاء.

المُقيِّمات التنبؤية

المُقيِّم التنبؤي الذي لا يكتب positive أو field أو expected_field يأخذها من كتلة predictive:؛ والقيمة التي يكتبها تُحفظ.

predictive

metrics

كل معيار مُقيِّم هو مقياس أصلًا. ويضيف إدخال metrics: مقياسًا آخر، يُميَّز بـ type.

# oloproof.yaml
version: 1
project: support-bot
dataset: datasets/support.jsonl
system:
  name: support-bot
  callable: app.bot:answer
evaluators:
  - type: exact_match
    criterion: correct_label
    field: label
metrics:
  - id: latency_p95
    type: quantile
    source: latency_ms
    quantile: 0.95

release.yaml

سياسة الإصدار: أي القواعد تقرر، وأي القرارات تحجب. الإعدادات المتروكة تحتفظ بقيمها الافتراضية، لذا فالسياسة التي لا تسمّي إلا قواعدها تظل تحجب على FAIL وINSUFFICIENT_EVIDENCE وMANUAL_REVIEW.

# release.yaml
version: 1
rules:
  - id: label_accuracy
    metric: correct_label
    min: 0.8

rules

قائمة واحدة تحمل النوعين. تأخذ قاعدة التشغيل واحدًا بالضبط من min أو max أو max_failures. وتسمّي قاعدة المقارنة kind الخاص بها وتحسم فرقًا بين تشغيلين؛ انظر قواعد المقارنة.

families

# release.yaml
version: 1
warn_on: [INSUFFICIENT_EVIDENCE]
block_on: [FAIL, MANUAL_REVIEW]
rules:
  - id: label_accuracy
    metric: correct_label
    min: 0.8
    max_missing_fraction: 0.05
  - id: no_regression
    metric: correct_label
    kind: non_inferiority
    margin: 0.02

أنواع المُخرَجات الفنية

المُخرَج الفني سجل ذو نوع يكتبه النظام بجانب مُخرَجه، مثل ما استرجعه. والنوع اسم بحروف صغيرة مع نسخة اختيارية، يطابق ^[a-z][a-z0-9_]*(/v[1-9][0-9]*)?$. والمُقيِّمات التي تحتاج إلى مُخرَج فني تسمّيه، والتشغيل الذي لا يعلن نظامه نوعًا مطلوبًا يُرفض قبل أن يبدأ، بدلًا من احتساب كل حالة مفقودة.

يعلن النظام القابل للاستدعاء الأنواع التي يسجّلها في records: (أو @system(records=...))؛ ونظام HTTP في http.artifacts؛ والنظام المرحلي لـ RAG يسجّل أنواعه بنفسه.

النسخ ومفاتيح التخزين المؤقت والإبطال

يعيد Oloproof استخدام العمل الذي لم تتغير مدخلاته، ويحدد معنى "لم يتغير" من بصمات المحتوى. ويحسب المحرك كلًّا منها ويسجّلها مع التشغيل.

ما لا يستطيع Oloproof رؤيته عليك أنت أن تعلنه:

• سلوك نظام HTTP موجود على الخادم. غيّر system.version كلما تغيّر ما وراء عنوان URL، وإلا فسيمثّل مُخرَج قديم مخزَّن مؤقتًا النظامَ الجديد.
• لا تُحسب بصمة الوحدات المساعدة للكائن القابل للاستدعاء إلا حين يطابقها code_paths. ومن دونه، لا يغيّر تعديل وحدة مساعدة النسخة.
• يجب أن يعلن التابع أو الكائن القابل للاستدعاء نسخة، ويجب أن تتغير النسخة حين تتغير حالة الكائن.
• يُعرَّف فهرس RAG بـ index_version؛ غيّره حين يُعاد بناء الفهرس.
• هوية حَكَم النموذج هي إعداداته، لا أوزان المزوِّد. وتحديث المزوِّد للنموذج خلف الاسم نفسه لا يكتشفه التخزين المؤقت.
• يحسب @evaluator المخصّص بصمة ملف الوحدة الذي يعرّفه، ولا يُعاد استخدام أحكامه عبر التشغيلات إلا حين يعلن cacheable=True. وحُكّام المعايير المدمجة قابلة للتخزين المؤقت؛ أما المُقيِّمات الحتمية فيُعاد حسابها، وهذا رخيص.

يقيم العمل المخزَّن مؤقتًا في المخزن المحلي للمشروع، .oloproof/store.sqlite بجانب oloproof.yaml (أو تحت OLOPROOF_HOME). وحذف المخزن يتخلص من كل ذاكرة تخزين مؤقت ومن كل تشغيل. وفي مساحة العمل المستضافة لا يعيد المحرك استخدام عمليات التنفيذ أو الأحكام أو التحليلات المخزّنة مؤقتًا، لأن الإرسال يستطيع كتابتها؛ بل يعيد الحساب.