الأدلة الإرشادية

مرجع النتائج والتنفيذ

ما يرسله التشغيل إلى نظام HTTP وما يتوقع أن يتلقاه، وكيف تدخل كل حالة في مقام المقياس، وحالات القرار ورموز الأسباب التي تفسّرها، ورموز الخروج، وما البيانات التي تبقى محلية أو تنتقل إلى مساحة عمل مستضافة. للأفكار التي تقف وراءها اقرأ المفاهيم؛ ولحقول السياسة اقرأ مرجع التهيئة.

عقد نظام HTTP

يُستدعى نظام HTTP (system.http في oloproof.yaml) مرة واحدة لكل حالة، ومرة واحدة لكل تكرار.

الجانب	السلوك
الطلب	POST افتراضيًا (يُقبل GET وPUT). والجسم هو قيمة input للحالة بصيغة JSON.
الترويسات والمصادقة	لا يمكن تهيئة أي منها. لا يحمل الطلب إلا الإعدادات الافتراضية لعميل HTTP. ونقطة النهاية التي تحتاج إلى مفتاح مكانها خلف نظام Python قابل للاستدعاء يضيفه.
الاستجابة	يجب أن تكون JSON. يختار output_path المُخرَج بمسار منقوط، مثل result.answer؛ ومن دونه يكون الجسم كله هو المُخرَج. ويُسجَّل غياب حقل output_path بوصفه خطأ تنفيذ لتلك الحالة.
المُخرَجات الفنية	يقرأ كل إدخال في http.artifacts مسارًا منقوطًا من الاستجابة. وغياب حقل مُعلَن عن استجابة ما خطأ في العقد، ويتوقف التشغيل برمز الخروج 2.
المهلة	http.timeout_s لكل طلب، 30 ثانية افتراضيًا.
إعادة المحاولة	تُعاد محاولة انتهاء المهلة وإخفاقات الاتصال وHTTP 408 و429 و5xx، حتى أربع محاولات إجمالًا، مع تراجع أسّي بتذبذب عشوائي يحترم Retry-After. ولا تُعاد محاولة استجابات 4xx الأخرى.
بعد المحاولة الأخيرة	يُسجَّل تنفيذ الحالة بوصفه خطأ وتُحتسب الحالة مفقودة (أو مُخفِقة، في ظل on_execution_error: fail). ويستمر التشغيل.
التزامن	على الأكثر concurrency.system طلبًا قيد التنفيذ في آن واحد، 8 افتراضيًا.

يدخل عنوان URL والطريقة ومسار المُخرَج وتعيين المُخرَجات الفنية في نسخة النظام، أما ما يفعله الخادم فلا يدخل. غيّر system.version كلما تغيّر سلوك الخادم؛ وانظر مرجع التهيئة لمعرفة السبب.

ثلاث مفردات مختلفة

للنتيجة ثلاثة أنواع من الحالات، ولا ينوب أحدها عن الآخر أبدًا.

النوع	القيم	يجيب عن
حالة القرار	PASS، FAIL، INSUFFICIENT_EVIDENCE، MANUAL_REVIEW	ما تقوله الأدلة عن قاعدة واحدة.
حالة التنفيذ	حالة التشغيل RUN_ERROR أو CANCELLED؛ اكتمال التشغيل PARTIAL؛ تنفيذ الحالة ERROR أو TIMEOUT	ما حدث للتشغيل أو لاستدعاء حالة واحدة. ليست نتيجة جودة.
إجراء الإصدار	ALLOW، WARN، BLOCK	ما تفعله سياستك بكل قرار: حالات block_on تحجب، وحالات warn_on تحذّر، والبقية تسمح.

التشغيل الذي ينتهي نهاية طبيعية يكون DECIDED، أو DECIDED_EARLY حين أنهاه الإيقاف المبكر. والتشغيل الذي قاطعه Ctrl-C أو إلغاء المهمة يكون CANCELLED؛ والذي رفعت أداة تشغيله استثناءً يكون RUN_ERROR. وكلاهما يترك التشغيل PARTIAL، ويحتفظ بالحالات التي انتهت، ويتيح للتشغيل التالي إعادة استخدام سجلاتها المخزّنة مؤقتًا. انظر الأخطاء.

بالنسبة إلى عتبة دنيا T وفترة [L, U]، تكون القاعدة PASS حين L >= T، وFAIL حين U < T، وINSUFFICIENT_EVIDENCE فيما عدا ذلك. والعتبة القصوى متناظرة. وقبل قراءة الفترة، تتحقق القاعدة مما إذا كان ينبغي لها أن تقرر أصلًا: أولًا أسباب MANUAL_REVIEW، ثم أسباب INSUFFICIENT_EVIDENCE. وأول مستوى فيه سبب هو الذي يقرر، ويسرد كل سبب وجده.

رموز الأسباب

يحمل كل قرار رمز سبب واحدًا أو أكثر.

MANUAL_REVIEW

الرمز	المعنى
policy_requires_review	تضبط القاعدة requires_manual_review: true.
unsupported_method	لا توجد فترة معتمدة لهذا المقياس في هذا الوضع. انظر أدناه.
unsupported_dependence_structure	تُعلن مجموعة الاختبار عناقيد (group_id) ولا تعالجها أي طريقة معتمدة لهذا المقياس.
approximate_method_not_permitted	الفترة الوحيدة تقريبية، والسياسة لا تضبط allow_approximate_methods: true.
evaluator_retired	أُحيل مُقيِّم يستند إليه المقياس إلى التقاعد.

INSUFFICIENT_EVIDENCE

الرمز	المعنى
no_observations	لم تُرصد أي حالة لهذا المقياس.
missingness_exceeds_policy	المفقود من الحالات المؤهَّلة أكثر مما يسمح به max_missing_fraction في القاعدة.
missingness_unbounded	تُسقط الطريقة الحالات المفقودة بدلًا من حصرها بحدود، ولا تُعلن القاعدة max_missing_fraction.
evaluator_not_validated	لم يُتحقَّق من حَكَم نموذج يستند إليه المقياس مقابل وسوم بشرية، وrequire_validated_evaluators مفعَّل (الافتراضي).
evaluator_recalibration_required	تُحقِّق من الحَكَم على نموذج مُقدَّم لم تأتِ منه أحكام هذا التشغيل.
interval_unavailable	ليس للمقياس فترة تُقرأ.
insufficient_clusters	العناقيد أقل من min_clusters في السياسة.
interval_monte_carlo_uncertain	تقع العتبة داخل عدم اليقين الناتج عن المحاكاة لحدٍّ عنقودي.
interval_overlaps_threshold	تحتوي الفترة على العتبة. والمزيد من الحالات يضيّقها.
interval_unbounded	ليس للفترة حد في الجهة التي تقرؤها القاعدة.
missing_could_change_outcome	قاعدة observed_count: قد تدفع الحالات المفقودة الإخفاقات إلى تجاوز max_failures.
interval_overlaps_zero، interval_overlaps_margin، interval_overlaps_margins	مقارنة تمتد فترة فرقها على جانبي الصفر أو هامش ما.
insufficient_support	قاعدة مقارنة شريحة حالاتها أقل من min_support الخاص بها.
family_correction_withheld	قاعدة في إدخال families: أوقف تصحيح Holm قبل بلوغها.

PASS وFAIL

الرمز	الحالة
lower_bound_meets_minimum، upper_bound_meets_maximum	PASS
upper_bound_below_minimum، lower_bound_above_maximum	FAIL
observed_failures_within_limit	PASS
observed_failures_exceed_limit	FAIL
difference_above_zero، lower_bound_above_margin، interval_within_margins	PASS (مقارنة)
difference_below_zero، upper_bound_below_margin، interval_outside_margins	FAIL (مقارنة)
cost_ceiling_exceeded	يُذكر بجانب حالة قاعدة تكلفة تجاوز تنفيذٌ مسجَّل سقفَها المُعلَن

مساحة العمل المستضافة فقط

يمكن لمساحة العمل التي تقرر بنفسها بشأن تشغيل مُرسَل إليها أن تحجب القرار بـ ppi_not_verified (لم تتحقق من الفترة التي يستند إليها القرار)، أو execution_not_verified (لم تأتِ المُخرَجات من مُشغِّل مسجَّل)، أو workspace_cannot_decide (لا تحمل نسخة من السياسة، أو تعذّرت عليها قراءة الأدلة). انظر البوابة.

كيف تدخل كل حالة في المقام

يُبلغ كل مقياس عن أربعة أعداد: n_total (الحالات في مجموعة الاختبار)، وn_eligible، وn_observed، وn_missing، مع n_eligible = n_observed + n_missing. وتُسرد الحالات الواقعة خارج n_eligible تحت exclusions مع سبب.

ما حدث للحالة	تُحتسب	في المقام
أعاد المُقيِّم نجاحًا أو إخفاقًا	مرصودة، نجاحًا أو إخفاقًا	نعم
أعلن المُقيِّم أنه لا ينطبق (مثلًا، لا قيمة متوقعة للمقارنة)	مستبعدة، مع السبب	لا
وقع خطأ في استدعاء النظام أو انتهت مهلته	مفقودة، أو مُخفِقة في ظل on_execution_error: fail	نعم
رفع المُقيِّم استثناءً، أو تعذّرت قراءة رد الحَكَم	مفقودة	نعم
لم تُشغَّل الحالة قط لأن التشغيل قوطع	مفقودة، ويكون التشغيل PARTIAL	نعم

الحالة المفقودة تُحصَر بحدود ولا تُسقَط. في معدل النجاح يعامل الحد الأدنى للفترة كل حالة مفقودة بوصفها إخفاقًا ويعاملها الحد الأعلى بوصفها نجاحًا، فيكون للتشغيل الذي فيه حالات مفقودة كثيرة فترة واسعة لا تستطيع اجتياز قاعدة صارمة؛ ويستبدل المتوسط المحدود طرفي مداه المُعلَن بالطريقة نفسها. والطريقة التي لا تستطيع حصر الحالات المفقودة (إحصاء ترتيبي، مثلًا) تُسقطها وتسجّل الافتراض، وتقرأ القاعدة المبنية عليها missingness_unbounded حتى تُعلن max_missing_fraction.

تَعُدّ قاعدة observed_count الإخفاقات على مجموعة الاختبار المنفَّذة ولا تقرأ أي فترة. ولا تنجح إلا حين تظل الإخفاقات المرصودة مضافًا إليها كل حالة مفقودة ضمن max_failures.

مقاييس بلا فترة معتمدة

لا تقرر القاعدة إلا بناءً على فترة اعتُمدت طريقتها بالتدقيق. وحيث لا توجد واحدة، يظل المقياس يُحسب ويُعرض، ولا تستعير القاعدة المبنية عليه طريقة غير مُتحقَّق منها:

الوضع	ما تقرؤه القاعدة المبنية عليه
مقياس درجة (متوسط) بلا مدى مُعلَن، مثل مُقيِّم درجة مخصّص دون score_range	MANUAL_REVIEW، unsupported_method
مقياس متوسط أو مِئين أو ترتيب أو تكلفة على مجموعة اختبار تُعلن group_id	MANUAL_REVIEW، unsupported_dependence_structure
معدل نجاح على مجموعة اختبار عنقودية	فترة تقريبية: MANUAL_REVIEW ما لم يُضبط allow_approximate_methods: true، ثم فحوص العناقيد أعلاه
مقياس مِئين أو ترتيب مع replicates أكبر من 1	MANUAL_REVIEW، unsupported_method
أي مقياس على مجموعة اختبار فيها group_id وتكرارات معًا	MANUAL_REVIEW، unsupported_dependence_structure
مقارنة على مجموعة اختبار عنقودية	MANUAL_REVIEW
شريحة دون min_slice_support	لا فترة، لكن الشرائح لا تبلغ البوابة أبدًا
مقاييس human_score أو human_preference أو cost_per_accepted	تُرفض عند قراءة الملف، الخروج 2

رموز الخروج

يستخدم oloproof gate، وoloproof run مع سياسة، والأوامر الأخرى التي تقرر، الرموزَ نفسها كلها.

الرمز	المعنى
0	لا شيء مما تحجب عليه السياسة: نجحت كل قاعدة، أو أن التي لم تنجح خارج block_on.
1	أخفقت قاعدة في block_on.
2	كانت التهيئة أو الاستدعاء خاطئًا، أو أخلّ نظام بعقده؛ ولم يُقرَّر شيء.
3	قرأت قاعدة في block_on الحالة INSUFFICIENT_EVIDENCE.
4	قرأت قاعدة في block_on الحالة MANUAL_REVIEW.
5	لم يكتمل التشغيل وblock_on_partial_run مفعَّل (الافتراضي).

حين ينطبق أكثر من رمز، يكون الرمز المُبلَغ عنه أولَ ما ينطبق من 1، 5، 4، 3. والحالة غير المذكورة في block_on لا تستطيع تغيير رمز الخروج: مع block_on: [FAIL] وwarn_on: [INSUFFICIENT_EVIDENCE]، تحذّر القاعدة غير المحسومة وتخرج البوابة بالرمز 0. لذا لا يعني الخروج 0 إلا أنه لم يقع شيء مما تحجب عليه سياستك، لا أن كل قاعدة نجحت. انظر البوابة.

أين يجري العمل وإلى أين تذهب البيانات

محليًا، وهو الافتراضي

يعمل oloproof run وoloproof gate وSDK على جهازك. ويُكتب كل سجل (الحالات، والمُخرَجات، والمُخرَجات الفنية، والأحكام، والمقاييس، والقرارات) في .oloproof/store.sqlite بجانب oloproof.yaml، أو تحت OLOPROOF_HOME حين يُضبط. ولا يُرسَل شيء إلى Oloproof. وحركة الشبكة الوحيدة هي ما تسببه تهيئتك: استدعاءات عنوان URL لنظام HTTP لديك، واستدعاءات يجريها حَكَم نموذج أو مُصنِّف نموذج إلى مزوِّده، الذي يتلقى محتوى الحالات التي يحكم عليها ويحاسبك عليه.

الإرسال إلى مساحة عمل مستضافة

يرسل oloproof push أدلة تشغيل إلى مساحة العمل التي اتصلت بها عبر oloproof login. وهو يرسل افتراضيًا المقاييس والفترات والقرارات والشرائح المجمَّعة، وهوية كل سجل وحالته وتوقيتاته واستهلاكه، لكن لا يرسل محتواه. ويُحجب المحتوى الخام حقلًا حقلًا قبل أن يغادر أي شيء الجهاز، والسجل المحجوب يذكر الفئات التي حُجبت. ولا تُرسَل فئة إلا حين يسردها egress: في oloproof.yaml:

الفئة	ما تغطيه
raw_inputs	مدخلات السيناريو، والقيم المتوقعة، والبيانات الوصفية للحالة: صفوف مجموعة البيانات
raw_outputs	ما أعاده النظام قيد الاختبار لكل حالة
judge_rationales	النص الذي كتبه الحَكَم لتفسير حكمه، والذي يقتبس المُخرَج
artifacts	سياق الاسترجاع والاستشهادات والمسارات المسجَّلة أثناء التشغيل
error_detail	رسائل الاستثناءات وتفاصيلها، التي كثيرًا ما تحمل المُدخَل حرفيًا
system_config	التهيئة المُعلَنة للنظام قيد الاختبار ولمُقيِّماته
label_notes	الملاحظة التي كتبها شخص بجانب وسم، والتي كثيرًا ما تقتبس المُخرَج
span_names	أسماء التتبّعات والامتدادات والأدوات والوكلاء التي سجّلتها أداة القياس

لا تُعاد حساب بصمات السجلات بعد الحجب، لذا يظل السجل المستضاف يسمّي الأدلة الأصلية، التي تبقى على جهازك. والحجب ليس تشفيرًا، ويمكن لمقياس على شريحة صغيرة جدًا أن يكشف هوية الحالات التي وراءه.

حين يضع المراجعون وسومًا على الحالات في قائمة المراجعة المستضافة، يجلب متصفحهم محتوى الحالات من oloproof collect العامل على جانبك؛ ولا يمر عبر مساحة العمل. وتُخزَّن مفاتيح المزوِّدين التي تستخدمها مساحة العمل بـ oloproof credentials set، ويعرض oloproof credentials list أسماءها، لا قيمها أبدًا. وتعمل المهمة المُدارة على عامل يشغّله Oloproof، ولا يشغّل شيفرة Python الخاصة بك؛ ويُبلغ oloproof job عن نتيجتها ويخرج وفق بوابتها.

في مساحة العمل المستضافة لا يعيد المحرك أبدًا استخدام عمليات التنفيذ أو الأحكام أو التحليلات المخزّنة مؤقتًا، لأن الإرسال يستطيع الكتابة في ذاكرات التخزين المؤقت تلك؛ بل يعيد حسابها.