مرجع SDK

كل اسم تصدّره الحزمتان oloproof وoloproof.evaluators، مع توقيعه، وهل هو متزامن أم غير متزامن، وما يعيده. للحصول على مقدمة موجَّهة اقرأ واجهة Python البرمجية أولًا.

هاتان الحزمتان وحدهما هما الواجهة العامة. وأي شيء يُستورد من oloproof_core هو من داخليات المحرك وقد يتغير دون إشعار. وكل دالة أدناه تعمل محليًا على مخزن المشروع؛ ولا ترسل أيٌّ منها بيانات إلى أي مكان ما لم يستدعِ مُقيِّمٌ تمرره مزوِّدَ نماذج.

تشغيل تقييم

evaluate وaevaluate

def evaluate(*, system, dataset, evaluators, policy=None, **kwargs) -> EvaluationResult
async def aevaluate(*, system, dataset, evaluators, policy=None, **kwargs) -> EvaluationResult

evaluate متزامنة. إذا استُدعيت دون حلقة أحداث قيد التشغيل فإنها تستخدم asyncio.run؛ وإذا استُدعيت من داخل حلقة قيد التشغيل (دفتر ملاحظات، اختبار غير متزامن) فإنها تشغّل التقييم في خيط منفصل وتنتظر حتى ينتهي، فهي آمنة في الموضعين. وaevaluate هي الروتين المشترك؛ استخدم await معها من الشيفرة غير المتزامنة.

وسائط الكلمات المفتاحية الباقية (metrics، store، predictive، event_sink، retry_policy، traffic_draw_id) تأخذ أنواعًا من المحرك من oloproof_core وليست جزءًا من الواجهة المستقرة.

from oloproof import evaluate, system, current_case
from oloproof.evaluators import ExactMatch, evaluator

@system(name="support-bot", version="1")
def answer(case):
    current_case().usage(input_tokens=12, output_tokens=3)
    return {"label": "refund" if "refund" in case["question"].lower() else "other"}

@evaluator(criterion="short_label")
def short_label(case):
    return len(case.output["label"]) <= 6

result = evaluate(
    system=answer,
    dataset="cases.jsonl",
    evaluators=[ExactMatch(criterion="correct_label", field="label"), short_label],
)
for metric in result.metrics:
    print(metric.metric, metric.estimate, metric.interval, metric.n_observed, metric.n_missing)

عند تشغيله على مجموعة اختبار من حالتين دون سياسة، طبع هذا:

correct_label 1.0 lower=0.15811388300841903 upper=1.0 2 0
short_label 1.0 lower=0.15811388300841903 upper=1.0 2 0

EvaluationResult

معنى الحالات ورموز الأسباب والأعداد موجود في النتائج والتنفيذ.

evaluate_comparison وaevaluate_comparison

def evaluate_comparison(*, candidate_system, baseline_system, dataset, evaluators, policy, **kwargs) -> ComparisonEvaluationResult
async def aevaluate_comparison(*, candidate_system, baseline_system, dataset, evaluators, policy, **kwargs) -> ComparisonEvaluationResult

يشغّل النظامين على مجموعة الاختبار نفسها بترتيب واحد مبنيّ على بذرة ويحسم قواعد المقارنة في السياسة. policy مطلوب ويجب أن يحتوي على قاعدة superiority أو non_inferiority أو equivalence واحدة على الأقل، وإلا رفع الاستدعاء خطأ تهيئة. وسائط كلمات مفتاحية إضافية: concurrency، وreplicates، وmetrics وstore وretry_policy ذات أنواع المحرك. والسلوك المتزامن وغير المتزامن كما في evaluate.

يحتوي ComparisonEvaluationResult على candidate وbaseline (كل منهما EvaluationResult) وcomparison، الذي يحمل الفروق المزدوجة وقراراتها. انظر مقارنة نسختين.

إعلان نظام

@system

def system(func=None, *, name=None, version=None, config=None, timeout_s=None, records=())

يُستخدم مجردًا (@system) أو مع وسائط (@system(name=..., version=...))، أو يُستدعى على كائن (system(model.answer, version="v2")). تتلقى الدالة كائن input الخاص بالحالة، لا الحالة كلها، وتعيد المُخرَج الذي تقرؤه المُقيِّمات. ويجوز أن تكون def أو async def؛ والدالة المتزامنة تعمل في خيط عامل.

تدخل الشيفرة المصدرية لوحدة الدالة نفسها في بصمة النسخة، فتعديلها يُبطل عمليات التنفيذ المخزّنة مؤقتًا. انظر مرجع التهيئة لمعرفة ما يُبطلها أيضًا وما لا يُبطلها.

current_case

def current_case() -> CaseRecorder

متاحة فقط بينما يستدعي Oloproof نظامك؛ وفي أي مكان آخر ترفع RuntimeError. توابع المُسجِّل:

يعيد كل منها ArtifactRef (باستثناء usage، الذي لا يعيد شيئًا). وتُصدَّر الحمولات ذات الأنواع لبناء هذه السجلات: Retrieval، Passage، Context، ContextItem، DroppedItem، Citations، StageTimings، AgentTrajectory، AgentStep، AgentCheckpoint، AgentConstraintCheck، واسم النوع CONVERSATION (conversation/v1).

@rag_system

def rag_system(*, name, depth, top_k, token_budget=None, index_version=None, version=None, config=None, citations_path="citations")

مُزخرِف أصناف. يوفّر الصنف retrieve(input, depth) وgenerate(input, context)، إضافة إلى count_tokens(passage) حين يضبط token_budget. وcontext هو قائمة كائنات Passage التي اجتازت top_k والميزانية، بترتيب الرتبة. يسجّل Oloproof بنفسه retrieval/v1 وcontext/v1 وcitations/v1 وstage_timings/v1، ويخزّن كل مرحلة مؤقتًا على حدة. ويسمّي citations_path حقل المُخرَج الذي يحمل المعرّفات التي تستشهد بها الإجابة. انظر RAG.

المُقيِّمات

كل الأصناف موجودة في oloproof.evaluators. ويسمّي criterion في كل منها المقياس الذي ينتجه. وأي المُخرَجات الفنية يقرؤها كل منها، وما يقابله في YAML، موجودان في جدول المُقيِّمات في مرجع التهيئة.

provider هو "anthropic" أو "openai" أو "openai_compatible". يقرأ الحَكَم مفتاحه من متغير البيئة الذي يسمّيه api_key_env (ANTHROPIC_API_KEY أو OPENAI_API_KEY افتراضيًا) ويحاسبه ذلك المزوِّد. ويأخذ Groundedness وCitationSupport بقية إعدادات RubricJudge عبر **options. وليس للحَكَم الاحتمالي ولمُصنِّف النموذج وللتتالي صنفٌ في SDK؛ فهي موجودة في YAML فقط.

يقرأ ConversationCompleted وConversationJudge مُخرَجًا فنيًا من نوع conversation/v1 يسجّله نظامك. ولا يقود Oloproof المحادثة: يشغّل تطبيقك كل دور ويسجّل النص الكامل. انظر الوكلاء.

@evaluator

def evaluator(*, criterion, reads=("output", "expected"), cacheable=False, version=None, value_type="binary", score_range=None)

يغلّف دالة ذات وسيط واحد، هو الحالة، في CustomEvaluator. للحالة output وexpected وscenario، ويعيد artifacts(name) حمولات نوع مسجَّل. ويجوز أن تكون الدالة def أو async def. يعيد المُقيِّم الثنائي True أو False؛ ويعلن مُقيِّم الدرجة value_type="score" وscore_range=(low, high) ويعيد رقمًا. والاستثناء الذي ترفعه الدالة يسجّل الحالة مفقودة لذلك المعيار، لا إخفاقًا أبدًا.

يجب أن يسرد reads كل حقل تقرؤه الدالة (input، output، expected، metadata، metadata.<key>، أو artifacts.<name>)، لأن الحكم المخزَّن مؤقتًا مفتاحه هذه الحقول بالضبط. ولا يُعاد استخدام الأحكام عبر التشغيلات إلا مع cacheable=True. وتدخل الشيفرة المصدرية للوحدة المعرِّفة في النسخة، فتعديلها يُبطلها. ولا يستطيع YAML تسمية مُقيِّم مخصّص.

التشخيص

diagnose وadiagnose

def diagnose(run_id, **kwargs) -> InterventionResult
async def adiagnose(run_id, *, system, evaluators, intervention, criterion, control=True, top_k=None, reranker=None, reranker_root=None, store=None, concurrency=None) -> InterventionResult

يعيد تنفيذ الحالات المُخفِقة لتشغيل مخزَّن تحت تدخّل واحد: "gold-context"، أو "top-k" (مع top_k)، أو "reranker" (مع reranker). يجب أن يكون system وevaluators النسختين اللتين استخدمهما التشغيل؛ والنسخة المختلفة تُرفض قبل تنفيذ أي شيء. ومع control=True تُشغَّل عيّنة ضابطة جديدة بجانب التدخل، كي يمكن تمييز التغيير عن التباين بين تشغيل وآخر. وdiagnose هي الصيغة المتزامنة وتتصرف داخل حلقة قيد التشغيل كما تفعل evaluate. انظر RAG لسير العمل.

يحمل InterventionResult معرّف التشغيل الأصل، والتدخل، وهل كان مدعومًا، وتشغيلَي التدخل والضابط، ونتيجة لكل حالة، وDiagnosisReport من إدخالات CaseDiagnosis حين يُنتَج.

إعادة تشغيل الوكيل

def supports_replay(system) -> bool
def checkpoint_for(trajectory, step_index) -> AgentCheckpoint | None
async def replay_case(system, *, scenario_id, trajectory, checkpoint, change) -> ReplayOutcome
def label_case(outcome) -> CaseDiagnosis
def label_cases(outcomes) -> tuple[CaseDiagnosis, ...]
def unnecessary_steps(labels) -> tuple[UnnecessaryStep, ...]

إعادة التشغيل شيء يفعله نظامك، لا شيء يحاكيه Oloproof. ولا يدعمها النظام إلا بتنفيذ async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory، الذي يعيد ما فعله الوكيل من نقطة الحفظ فصاعدًا؛ ويلصق Oloproof ذلك على البادئة المسجَّلة ويقارن. ويملك تطبيقك حالته وجلساته والآثار الجانبية لأدواته، بما في ذلك إعادة ضبطها قبل إعادة التشغيل. ويُبلغ supports_replay عمّا إذا كان النظام يعلن هذا التابع.

replay_case روتين مشترك: استخدم await معه، أو استدعِه عبر asyncio.run. وهو يشغّل ضابطًا (نقطة الحفظ نفسها مع ReplayChange(kind="resume")) قبل إعادة التشغيل، ولا يحاول إعادة التشغيل حين لا يعيد الضابط إنتاج التسجيل. وchange هو ReplayChange(kind="drop_step", step_index=...) أو ReplayChange(kind="resume"). ويختار checkpoint_for آخر نقطة حفظ مسجَّلة تقع قبل خطوة ما تمامًا، أو None، وفي هذه الحالة تُستبعد النتيجة بوصفها no_checkpoint_recorded دون لمس النظام.

يحمل ReplayOutcome القيم scenario_id وchange، والحالات النهائية لإعادة التشغيل والضابط، وdiscarded مع سبب حين لا تعطي الحالة أي دليل. والحالة المستبعدة ليست حالة مُخفِقة. ويحوّل label_case النتيجة إلى CaseDiagnosis مع FailureLabel وLabelReason الخاص به؛ ويسرد unnecessary_steps الخطوات التي ترك حذفُها النتيجةَ سليمة. انظر الوكلاء.

الوسوم البشرية والثقة بالمُقيِّم

def record_label(*, run_id, scenario_id, criterion, passed, labelled_by, note=None, purpose="measurement", sample_index=0, config="oloproof.yaml", store=None, ...) -> HumanLabel

يخزّن حكم نجاح/إخفاق لشخص واحد على حالة واحدة من تشغيل مخزَّن. وتغذّي الوسوم oloproof evaluators validate، الذي يقيس اتفاق الحَكَم معها (AgreementResult) ويسجّل حالته (RegistryEntry). وتربط وسائط measurement_sample_* الإضافية الوسمَ بعيّنة قياس؛ ويملؤها لك oloproof labels export وoloproof labels import في CLI. انظر الحُكّام.

السياسات في الشيفرة

تبني ReleasePolicy وIntervalThresholdRule وObservedCountRule وDecisionRule (اتحاد الاثنتين) سياسةً دون ملف. وحقولها هي حقول release.yaml في مرجع التهيئة؛ وتأخذ قاعدة الفترة direction (min أو max) وthreshold بدلًا من min: أو max:. وليس لقواعد المقارنة صنف مُصدَّر؛ اكتبها في release.yaml ومرّر مساره.

from oloproof import IntervalThresholdRule, ReleasePolicy

policy = ReleasePolicy(
    rules=(IntervalThresholdRule(id="accuracy", metric="correct_label", direction="min", threshold=0.8),),
)

صادرات أخرى