الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
الـ evals هي regression tests لـ سلوك الـ agent: أي tools استدعى، وبأي ترتيب، وبأي arguments، وكم خطوة أخذ، وماذا قال. تكتبها بـ defineEval()، وتوجد في ملفات *.eval.ts، وتعمل على vitest. أفضل مكان لتشغيلها هو CI عبر lousho eval، الذي يطبع ملخصًا ويكتب تقارير JUnit وJSON.
vitest مطلوب. lousho eval لا يشغّل ملفات الـ eval بنفسه: يشغّل ملفات *.eval.ts الخاصة بك عبر vitest، ويجده في node_modules الخاص بمشروعك (Lousho لا يضمّنه معه). ثبّته أولًا كـ dev dependency؛ ودونه يخرج lousho eval بـ 1 مع vitest was not found from <dir> وأمر التثبيت.

كتابة trajectory eval

مرّر لـ defineEval() agent (من createAgent()) ودالة test. أرسل الرسائل بـ t.send()، ثم نفّذ assert على الـ run. إذا جعلت mockModel هو الـ provider الخاص بالـ agent، يصبح الـ eval deterministic: لا شبكة، لا API key، لا flakiness. هذه هي الطريقة الافتراضية لكتابة eval؛ استخدم model حقيقي فقط في judge evals بالأسفل.
defineEval() تقبل أيضًا الصيغة الأصلية ({ name, agent, input, provider, score, threshold }): تعمل كما هي دون تغيير، ونتيجتها تظهر في lousho eval كـ assertion واحدة على score.

Assertions

كل assertion يُسجَّل. تفشل الـ case في النهاية وتعدّ كل gate فاشلة، فترى كل المشكلات من run واحد. الـ checks المتاحة لـ t.check() وt.soft(): includes(text) وmatches(regex) وequals(value) (نعم/لا، درجة 1 أو 0)، وatLeast(n) وatMost(n) (الرقم نفسه هو الدرجة). رسائل الفشل تخبرك بالضبط بما ظهر:
بقية أعضاء الـ context: t.reply (نص آخر رد)، وt.result (آخر ExecutionResult)، وt.toolCalls (كل الـ calls حتى الآن، مع arguments محلّلة). تستطيع استدعاء send() أكثر من مرة؛ وتتراكم الخطوات والـ tokens والـ tool calls.

الـ sub-agents

عندما يفوّض الـ agent عبر subagents، تصبح الـ calls التي يجريها الـ sub-agent جزءًا من t.toolCalls. كل واحدة منها تأتي بعد call الـ task الذي بدأها وتحمل subagentPath (['researcher']، أو ['researcher', 'fetcher'] عندما يفوّض هو بدوره)؛ والـ calls الخاصة بالـ agent الرئيسي ليس فيها هذا الحقل. تبحث الـ assertions في الشجرة كلها افتراضيًا، فتفشل t.notCalledTool('delete_repo') إذا استدعاها أي sub-agent. مرّر { subagent: 'researcher' } لكي تنظر في sub-agent واحد فقط (والـ sub-agents التي تحته):
الـ calls تأتي من أحداث tool.start في الـ run، التي يجمعها t.send() عبر send(message, { onEvent }). الـ target البعيد (--url) لا يبث أحداث sub-agent، فلا يظهر فيه إلا calls الـ agent الرئيسي. والصيغة الكلاسيكية ({ agent, input, provider, score }) تمرّر كل خيارات AgentExecutor.execute()، ومنها subagents وskills، وEvalResult.toolCalls فيها يتضمن calls الـ sub-agents أيضًا.

تكرار الـ case (pass@k)

الـ model ليس deterministic، فلا يخبرك run واحد بالكثير. repeat: n يشغّل كل case عدد n مرات؛ وتنجح الـ case عندما تنجح كل الـ n runs، أو عندما ينجح passAt: k منها على الأقل:
كل run له سطر خاص في التقرير (refund flow [refund flow #1]، …) وله cassette خاص. timeoutMs يغطي كل runs الـ case، فارفعه مع repeat.

Datasets

مرّر cases فتعمل test مرة لكل case، وتظهر كل case في التقرير وحدها. الـ case أي object؛ والـ label الخاص بها (أو name، أو input) هو الذي يسمّيها.
مرّر factory (agent: () => createAgent(...)) لكي تأخذ كل case agent جديدًا وسكربت mockModel جديدًا. مع agent واحد مشترك، تنفد الـ turns من الـ scripted model عند الـ case الثانية.

من الـ daemon

يمكن أيضًا أن تكون الـ cases في سجل الـ datasets الخاص بالـ observe daemon (انظر Datasets، /api/v1/datasets): أنشئ dataset، وأضف إليها أمثلة يدويًا أو انسخها من trace أعجبك، ثم مرّر dataset: 'name' بدلًا من cases. في Studio، شاشة Datasets تنشئ الـ datasets وتعرض أمثلتها، وزر Add to dataset في الـ trace ينسخه إليها.
عندما يجمع vitest الملف، يجلب defineEval() كل أمثلة الـ dataset من الـ daemon الذي يشير إليه LOUSHO_OBSERVE (ويرسل LOUSHO_OBSERVE_TOKEN إذا كان مضبوطًا) ويسجّل test واحدًا لكل مثال، الأقدم أولًا: refunds [#1]، refunds [#2]، … وكل c هو DatasetCase: { input, expected, label, example_id, source_trace_id }، حيث input وexpected هما أي JSON موجود في المثال (قيمة expected هي null إذا لم يُضبط). وLOUSHO_OBSERVE يُقرأ لحظة استدعاء defineEval(). يفشل الـ eval بـ LOUSHO_DATASET_UNAVAILABLE عندما لا يكون LOUSHO_OBSERVE مضبوطًا، أو لا يمكن الوصول إلى الـ daemon خلال 10 ثوانٍ، أو لا تكون الـ dataset موجودة، أو لا تحتوي أمثلة: الـ eval الذي لا يشغّل شيئًا لا ينجح أبدًا. وتمرير cases وdataset معًا يرمي LOUSHO_EVALS_INVALID. والـ dataset eval الذي يستبعده lousho eval --tag يُتخطّى دون جلب.

Judge evals

t.judge(rubric) يقيّم آخر رد بـ LLM ويعيد درجة من 0 إلى 1. يحتاج provider للـ judge، ولا يستدعي lousho أي LLM حقيقي إلا إذا ضبطت واحدًا: دون judge، يرمي t.judge() خطأً يشرح لك كيف تصلحه.
judge.model اختياري: دونه يعمل الـ judge على الـ model الخاص بالـ provider الخاص به. يرى الـ judge الـ rubric وطلب المستخدم ورد الـ agent، ويعمل على temperature 0 إلا إذا ضبطت temperature، ويُطلب منه أن ينهي رده بسطر SCORE: <0..1>. يُقرأ رده من آخر رقم عليه label اسمه score (SCORE: 0.9، **Score:** 8/10، {"score": 0.8})، فيُتجاهل أي رقم داخل استدلاله (“1 of 5 criteria”). ودون label يجب أن يكون الرد كله رقمًا واحدًا (0.9، **0.9**). يتحوّل الرقم إلى نطاق 0 إلى 1 عندما يكون مكتوبًا كـ 8/10 أو 8 out of 10 أو 85% أو عددًا صحيحًا مجردًا من 2 إلى 100 (8 يُقرأ 8/10، و85 يُقرأ 85/100). والرد الذي ليس فيه رقم عليه label ولا رقم مجرد درجته 0. وparseJudgeScore(text) تعطيك طريقة التحليل نفسها. ملفات *.judge.eval.ts لا يلتقطها الـ run العادي أبدًا (ولا npm test)؛ لا يشغّلها إلا lousho eval --judge (أو npm run test:evals:judge في هذا الـ repo).

lousho eval

يشغّل الأمر نسخة vitest المثبّتة في مشروعك (vitest dependency تخصك أنت؛ إذا كانت مفقودة، يطبع الأمر npm install --save-dev vitest ويخرج بـ 1)، ثم يطبع سطرًا لكل case بدرجاتها ومدتها، ثم المجاميع، ثم إخفاقات الـ gate وإخفاقات الـ soft كلًّا على حدة. مجموع “with soft failures” (softFailed في ملخص الـ JSON) يعدّ كل case فيها assertion soft فاشلة، ومنها الـ cases التي فشلت في gate أيضًا. رمز الخروج: 1 عند أي إخفاق gate (أو إخفاق soft مع --strict، أو حين يفشل vitest نفسه، مثل ملف لا يُحمَّل، أو vitest غير مثبّت، أو تقرير --junit/--json لا يمكن كتابته، أو حين لا تعمل أي case أصلًا: لا يوجد ملف eval مطابق، أو لم يطابق --tag أي case)، و2 لخطأ في الاستخدام (arguments خاطئة)، و0 فيما عدا ذلك. والـ case التي يُفشلها vitest بعد أن انتهت هي نفسها (تجاوزت حد الوقت الخاص بها) تُبلَّغ كفشل لتلك الـ case. كيف تُجمَع النتائج: كل case تضيف سطر JSON واحدًا إلى ملف محدّد اسمه في env var LOUSHO_EVAL_RESULTS، التي يضبطها lousho eval ثم يعود فيقرؤها. هذا أثبت من reporter مخصص لـ vitest: يعمل عبر إصدارات vitest المختلفة وworker pools، ولا يحتاج إلى تحميل أي module من مشروعك. مع ضبط LOUSHO_OBSERVE (أو lousho eval --observe)، يُرسل الـ span eval الخاص بكل case وصفوف الدرجات (score rows) الخاصة بها إلى الـ collector عندما تنتهي الـ case، وحدّ كل انتظار ثانية واحدة؛ الـ collector المتوقف أو الصامت لا يُفشل الـ case أبدًا ولا يبطئها بشكل ملحوظ. صفوف الدرجات تسير في الطابور نفسه مع الـ spans: تخرج بعد span الـ case، وعندما يكون الـ collector متوقفًا تُحفظ ويُعاد إرسالها معه (وتُرسل عند الخروج أو الـ crash) بدلًا من أن تضيع. وعندما تنتهي مهلة انتظار، تتخطّى الـ cases في الـ 30 ثانية التالية الانتظار (تظل صفوفها تُضاف إلى الطابور)، ثم تحاول الـ case التالية من جديد. وبجانب صف درجة <eval>/<check> لكل assertion، تُخرج كل case صف درجة <eval> واحدًا، قيمته 1 عندما تنجح كل فحوص الـ gate ولا ترمي الـ case خطأً، و0 خلاف ذلك (يسرد التعليق الخاص به فحوص الـ gate الفاشلة أو الخطأ؛ وإخفاقات الـ soft تظهر فقط في صفوفها هي)؛ واسم الـ case هو الـ attribute lousho.eval.case على الـ span eval الذي يملك الـ trace، وليس attribute على الدرجة. شاشة Scores في Studio تعرض هذه الصفوف لكل eval (نسب النجاح، الاتجاه، الفحوص الفاشلة)، بجانب درجات online من قواعد الـ evaluators ودرجات human من الـ feedback وطوابير الـ annotation.

حدود الوقت

الـ run على model حقيقي يستغرق وقتًا أطول بكثير من الـ timeout الافتراضي للـ test في vitest وهو 5 ثوانٍ. الـ config الذي يولّده lousho eval يعطي كل case عشر دقائق، إلا مع --replay، الذي يُبقي على افتراضي vitest لأنه لا يوجد ما ينتظر model. --timeout ms يضبط الحد لكل case (0 يلغيه). ومع --config، يُطبَّق testTimeout من الـ config الخاص بك إلا إذا مرّرت --timeout. ويستطيع الـ eval الواحد أن يضبط حده الخاص، وهذا يتقدّم على الاثنين:
الـ case التي ينتهي وقتها تُبلَّغ كـ error يذكر الحد، في الملخص وفي تقارير JUnit وJSON.

JUnit

تقرير JUnit قياسي: testsuite واحد لكل eval، وtestcase واحد لكل case. الـ gate الفاشلة تصبح <failure message="..."> تحمل رسالة التشخيص؛ والـ case التي رمت خطأً أو انتهى وقتها تصبح <error>؛ وإخفاقات الـ soft تكون ملاحظات <system-out> (أو failures مع --strict)، حتى على case فشلت في gate. وعندما يُفشل vitest شيئًا لم تُبلغ عنه أي eval case، مثل ملف eval لا يُحمَّل أو test() عادي يفشل، يأخذ التقرير testcase من نوع <error> له تحت suite اسمها vitest، واحدة لكل ملف (أو واحدة للـ run كله عندما تستخدم --config ولا يسمّي vitest ملفًا)، لكي لا يكتب الـ run المعطوب أبدًا تقريرًا فارغًا يبدو أخضر.

في CI

شغّل --tag smoke على كل pull request والمجموعة الكاملة كل ليلة؛ و--judge شغّله فقط حيث تقبل calls حقيقية لـ LLM وتكلفتها.

متغيرات البيئة

lousho eval يمرّر الـ flags الخاصة به إلى عملية vitest التي تشغّل ملفات الـ eval عبر متغيرات بيئة. لا تضبطها أنت بنفسك؛ وهي مذكورة هنا لكي تتعرف عليها في log الـ CI أو في runner مخصص:

Record, replay and drift

الـ eval على model حقيقي بطيء ومكلف ويحتاج مفتاحًا؛ والـ eval نفسه على mockModel لا يختبر إلا السكربت الذي كتبته أنت. lousho eval يقف في المنتصف: يسجّل كل case مرة واحدة على الـ provider الحقيقي عبر recordReplay ويعيد تشغيل التسجيل في CI. ملفات الـ eval الخاصة بك لا تتغير.
  • --record يشغّل كل case بالـ provider الحقيقي للـ agent الخاص بها ويكتب cassette واحدًا لكل case بجانب ملف الـ eval: __cassettes__/<eval-name>/<case>-<hash>.json. الاسم هو label الـ case بعد تحويله إلى slug مع hash قصير للـ label الكامل، مثل refund-flow/polite-1f3a9c2e.json، فحتى الـ cases التي يتشابه الـ slug أو الاختصار الخاص بها تأخذ كل واحدة ملفها؛ والـ eval دون cases يكتب default.json. أعطِ كل case label فريدًا لكي تبقى الأسماء ثابتة: الـ cases التي لا تزال تتشارك cassette (الـ label نفسه مرتين) تفشل وقت التسجيل بدلًا من أن تكتب إحداها فوق الأخرى. والـ case التي يستخدم الـ agent الخاص بها أكثر من provider (sub-agent على model آخر) تأخذ ملفًا باسم الـ sub-agent، <case>-<hash>.<agent>.json (والملفات القديمة .2.json لا تزال تُعاد). يطابق الـ replay كل call بالـ request الخاص به، لا بموقعه، فتُعاد الـ tasks المتوازية للـ sub-agents بأي ترتيب أجاب به الـ model الحقيقي؛ وأي mismatch يوقف الـ run بـ LOUSHO_CASSETTE_INVALID حتى لو حدث داخل sub-agent. تستخدم الملفات صيغة الـ cassette العادية، مع إخفاء مفاتيح الـ API؛ راجعها وأجرِ لها commit. إعادة تسجيل case لم تتغيّر الـ exchanges الخاصة بها تترك ملفها كما هو (recordedAt يبقى)، فلا يظهر في الـ diff إلا التغييرات الحقيقية. والـ cassettes المسجّلة بـ SDK أقدم تحت الاسم دون hash <case>.json لا تزال تُعاد؛ وأول --record بعد ذلك يكتب الاسم الجديد، ثم تستطيع حذف الملف القديم.
  • --replay لا يستدعي الـ model أبدًا. الـ case دون cassette تفشل بـ no cassette for "<eval> [<case>]" at ... مع أمر --record المطلوب تشغيله (مع --config الخاص بك إذا أعطيته)؛ وإذا تغيّرت طلبات الـ agent، يفشل الـ model call المُعاد بـ CassetteMismatchError يسمّي أول اختلاف وأمر lousho eval --record نفسه. أما lousho eval العادي مع ضبط CI فيعيد تشغيل كل case لها cassette ويشغّل الباقي live؛ ودون CI يعمل live كالمعتاد.
  • --drift يعيد تسجيل كل case في مجلد مؤقت (لا تُمَسّ الـ cassettes التي أُجري لها commit) ويقارن كل واحدة بالـ cassette المودعة: أسماء الـ tools بترتيبها، وarguments كل call (بعد تطبيع JSON، فلا يُعتدّ بترتيب المفاتيح)، وعدد الخطوات، وسبب الانتهاء. استهلاك الـ tokens يتغير في كل run حقيقي، فلا يُقارن إلا مع --drift-usage. يأخذ الملخص جدول Drift: (eval، case، field، committed، current)؛ وكل case انحرفت تأخذ assertion soft اسمها drift، فتظهر كـ PASS (soft fail) وكملاحظة <system-out> في تقرير JUnit. مع --strict يصبح الـ drift إخفاق gate: تفشل الـ case، ويحتوي JUnit على <failure>، ويخرج الـ run بـ 1.
شغّل --drift كل ليلة أو قبل ترقية الـ model، و--replay (أو lousho eval العادي في CI) على كل pull request. الـ judges لا تُسجَّل: قيّم بـ judge حقيقي فقط في ملفات *.judge.eval.ts. كيف يعمل ذلك: الـ run loop يمرّر كل model call (generate أو stream، سواء من run عادي، أو run مبثوث، أو sub-agent، أو استئناف بعد approval) عبر seam واحدة لاعتراض الـ provider: setProviderInterceptor() (مُصدَّرة من lousho/testing؛ وsrc/providers/interception.ts في المصدر). لا شيء مثبّت فيها افتراضيًا، فهي بلا كلفة. وما دامت الـ case تعمل في أحد هذه الأوضاع، يجيبها lousho eval بالـ provider مغلّفًا بـ recordReplay() لـ cassette تلك الـ case. وتستطيع استخدام الـ seam بنفسك لتضع أي wrapper عند حدود الـ model: الـ interceptor يستقبل provider الـ run ويعيد الـ provider المطلوب استدعاؤه (يجب أن يعيد الـ wrapper نفسه للـ provider نفسه، وألا يمس provider سبق أن غلّفه). وأي فشل cassette يُخرجه - mismatch في الـ replay أو cassette مفقودة - يصل إلى send() بشكل typed (CassetteMismatchError، LOUSHO_CASSETTE_INVALID)، وليس كخطأ provider مضغوط.

تشغيل evals على deployment

ملف الـ eval نفسه الذي يحرس CI داخل العملية يستطيع أن يُجري smoke test لـ agent منشور (سيرفر node أو Cloudflare Worker). وجّه lousho eval إلى الـ base URL الخاص به فتعمل كل case على الـ deployment بدلًا من الـ agent داخل العملية:
كل case تأخذ session بعيدة خاصة بها (POST /chat { sessionId, input }، session واحدة لكل case، تتشاركها كل استدعاءات t.send() فيها) ويُقرأ الـ SSE stream حتى run.done. تتحول الأحداث إلى النتيجة نفسها التي ينتجها الـ run داخل العملية: الـ tool calls، والرد النهائي، وسبب الانتهاء، والخطوات، والاستهلاك. فتعمل t.calledTool() وt.completed() والـ scorers وt.judge() والملخص و--junit دون تغيير. الـ agent في الملف لا يُستخدم؛ اجعل model الـ deployment والـ tools الخاصة به على السلوك الذي تريد فحصه.
  • الـ check الذي يحتاج بيانات لا يحملها الـ stream يفشل ويذكر ذلك (مثل maxTokens حين لا يحتوي run.done على usage)؛ وmaxCostUsd يفشل حين لا توجد تكلفة، إلا إذا مرّرت { unknownCost: 'skip' }.
  • --url لا يجتمع مع --record أو --replay أو --drift (LOUSHO_CONFIG_CONFLICTING_OPTIONS): الـ cassettes تسجّل provider داخل العملية. وevals الـ score/threshold (صيغة score:) تحتاج أيضًا provider داخل العملية وتفشل بالكود نفسه؛ استخدم trajectory evals.
  • الـ deployment الذي لا يمكن الوصول إليه، أو الرد غير 2xx، أو الـ stream المنقطع يُفشل تلك الـ case بـ LOUSHO_REMOTE_REQUEST_FAILED، و401 بـ LOUSHO_REMOTE_UNAUTHORIZED؛ ويستمر الـ run. لا يُطبع الـ token أبدًا ولا يُكتب في أي تقرير.
في الكود، مرّر target (يتقدّم على agent؛ و--url يتقدّم على الاثنين):
remoteTarget({ url, auth?, fetch? }) تقبل fetch تحقنها بنفسك، وبهذه الطريقة تشغّل اختبارات الـ SDK نفسها الـ routes الحقيقية داخل العملية دون socket.