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)
(الرقم نفسه هو الدرجة).
رسائل الفشل تخبرك بالضبط بما ظهر:
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 التي تحته):
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 منها على الأقل:
refund flow [refund flow #1]، …) وله
cassette خاص. timeoutMs يغطي كل runs الـ case، فارفعه مع repeat.
Datasets
مرّرcases فتعمل test مرة لكل case، وتظهر كل case في التقرير وحدها.
الـ case أي object؛ والـ label الخاص بها (أو name، أو input) هو الذي يسمّيها.
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 ينسخه إليها.
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 الواحد أن يضبط حده الخاص، وهذا يتقدّم على الاثنين:
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. أعطِ كل caselabelفريدًا لكي تبقى الأسماء ثابتة: الـ 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 داخل العملية:
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.