صنّف نتائج CLI محلياً باستعمال Verdict

شنو كيدير Verdict

Verdict هو معاينة بحثية لطبقة دلالية للنتائج موجهة لوكلاء البرمجة، ومشغلات CI، وأنظمة أخرى كتستعمل الأدوات. بلا ما نعتابرو كود الخروج ديال العملية دليل نهائي، كيدرس الأمر، وكود الخروج، والمخرجات العادية، والمخرجات ديال الأخطاء مجموعين.

الموديل كيرجع واحد من أربعة ديال التصنيفات: success، أو failure، أو blocked، أو unknown. هاد التمييز مفيد حيث الأمر يقدر يخرج بكود صفر وهو ما شغّل حتى اختبار، أو رجّع استجابة HTTP 500، أو بقى كيتسنى واحد العامل، أو خرج مخرجات ناقصة. وبالمثل، كود خروج مختلف عن الصفر يقدر يشير لعائق فـالبيئة، ماشي لفشل فـاختبار.

مهم: Verdict مصنّف استشاري. ما كيبرهنش أن المهمة سالات أو أن البيئة تبدلات بالطريقة المقصودة. خَلّي الفحوصات الحتمية والتحقق من الحالة الموثوقة هما المصدر الحقيقي للحقيقة.

الميزات الرئيسية

• استدلال محلي: المعطيات كتتعالج فـالمعالج المحلي بلا اتصالات بالشبكة ولا تيليمترية.
• موديل صغير بزاف: الموديل المكمّم الحجم ديالو تقريباً 197 KB.
• تشغيل بلا تبعيات: الاستدلال كيستعمل مكتبة Python القياسية وما كيحتاجش ملفات tokenizer، ولا GPU، ولا تبعيات ديال Python خارج الحزمة نفسها.
• تصنيف دلالي: الموديل كياخذ بعين الاعتبار الأمر، وكود الخروج، وstdout، وstderr، عوض الاعتماد على كود الخروج بوحدو.
• تنبؤات سريعة: المستودع كيصرّح بوقت استدلال وسيط قدره 0.54 ms فبيئة الاختبار الموثقة ديالو: Windows 11 وAMD64 وPython 3.12.
• واجهات Python وCLI: استعمل الموديل داخل تطبيق أو مباشرة من pipeline ديال shell.
• عرض فالمتصفح: صفحة المشروع كتشغّل نفس الأوزان المكمّمة فالمتصفح بلا ما ترفع السجلات.

Verdict كيستعمل 3–5-grams ديال الحروف و1–3-grams ديال الكلمات بعد التجزئة بالتجزئة، مع الانحدار اللوجستي متعدد التصنيفات. المدخلات ديالو نص UTF-8، وكل stream ديال المخرجات محدود فـ12,288 حرف بواسطة قص صريح من البداية والنهاية.

فهم التصنيفات الأربعة

• success: المخرجات فيها دليل إيجابي على أن العملية سالات.
• failure: العملية تخدمات وصرّحات بفشل ملموس.
• blocked: الصلاحيات، أو التبعيات، أو الشبكة، أو حدود الحصة، أو البيئة منعو التنفيذ.
• unknown: الدليل غايب، أو ناقص، أو تم تخطيه، أو محدود فـتشغيل تجريبي، أو غير حاسم بطريقة أخرى.

الاحتمالات الراجعة جاية من موديل خطي متعدد التصنيفات. ما خاصهاش تتفسر على أنها ثقة معايرة فقرارات كتهم السلامة الحرجة.

تثبيت Verdict

نسخ المستودع، دخل للمجلد ديالو، وثبّت الحزمة باستعمال pip:

git clone https://github.com/Balanov/verdict.git
cd verdict
python -m pip install .

هاد الشي كيثبّت حزمة Python المسماة verdict_tiny وواجهة سطر الأوامر verdict.

شغّل أول تنبؤ بـPython

صايب instance من Verdict ودوز ليه نفس الدليل اللي لاحظ مشغّل الأدوات ديالك. هاد المثال كيمثل عملية pytest ناجحة، ولكن ما شغّلات حتى اختبار فعلياً:

from verdict_tiny import Verdict

model = Verdict()
result = model.predict(
    command="pytest tests/",
    exit_code=0,
    stdout="collected 0 items\nno tests ran in 0.01s",
)
print(result)

مخرجات الموديل الموثقة كتصنّف هاد الدليل على أنه unknown، رغم أن كود الخروج هو صفر:

{
  "label": "unknown",
  "confidence": 0.999981,
  "probabilities": {
    "success": 0.000019,
    "failure": 0.0,
    "blocked": 0.0,
    "unknown": 0.999981
  },
  "advisory": true
}

label هو النتيجة المختارة. الكائن probabilities كيكشف النقطة ديال كل تصنيف، بينما advisory كيأكد أن التنبؤ ماشي برهان موثوق ونهائي.

استعمل Verdict من سطر الأوامر

تقدر تدوز مخرجات الأمر عبر Verdict، مع تزويدو بالأمر الأصلي وكود الخروج:

printf 'collected 0 items\nno tests ran\n' | verdict \
  --command 'pytest tests/' --exit-code 0

بالنسبة للمخرجات اللي محفوظة من قبل فملفات، استعمل --stdout و--stderr:

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log

وتقدر حتى تحمّل الأوزان من موقع محدد:

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log \
  --weights /path/to/verdict-q8.bin

دمج Verdict بأمان

الدمج العملي خاصو يتعامل مع Verdict على أنه إشارة إضافية لاتخاذ القرار، ماشي الحكم النهائي. وكيل برمجة أو مشغّل CI يقدر يستعمل التصنيف باش يقرر واش يفحص أدلة إضافية، يعاود العملية، أو يطلب مراجعة بشرية.

1. شغّل الأمر الأصلي واحتافظ بكود الخروج ديالو، وstdout، وstderr.
2. دوز جميع الأدلة المتوفرة لـVerdict.
3. فحص التصنيف المتوقع واحتمالات التصنيفات بجوج.
4. طبّق عتبات خاصة بالتطبيق قبل ما تاخذ قرارات عندها عواقب.
5. تحقق من الاكتمال بفحوصات حتمية، بحال عدد الاختبارات، والملفات المتولدة، وحالة API، أو سجلات قاعدة البيانات.

مثلاً، نتيجة unknown خاصها عموماً تفعّل مزيد من البحث عوض الادعاء بأن المهمة سالات. ونتيجة blocked تقدر تبرر فحص بيانات الاعتماد، والتبعيات، والاتصال، والصلاحيات، أو الحصص قبل إعادة المحاولة. وحتى نتيجة success كتبقى محتاجة للتحقق الموثوق والنهائي ملي كتكون الصحة مهمة.

نصائح متقدمة

حافظ على سياق التنفيذ كامل

وفّر الأمر الفعلي، ورمز الخروج، وstdout، وstderr كلما أمكن. حذف تدفقات الإخراج يقدر يحيد أدلة كتفرّق بين فشل واضح، أو عائق مرتبط بالبيئة، أو تشغيل ما عطاش نتيجة حاسمة.

خد بعين الاعتبار اقتطاع الإدخال

كل تدفق إخراج محدود فـ12,288 حرف باستعمال اقتطاع من البداية والنهاية. ملي كتكون السجلات كبار بزاف، تأكد بلي الرسائل الحاسمة كاينة قرب البداية ولا النهاية، أو دير فحص إضافي وحتمي للسجلات كاملة.

حدّد عتبات قرار محافظة

الاحتمالات ماشي معايرة باش تكون ثقة بالمعنى ديال الأنظمة الحرجة للسلامة. استعمل عتبات مناسبة لسير العمل ديالك، ووجّه الحالات غير المؤكدة أو المؤثرة لمراجعات حتمية أو لمراجعة بشرية.

استعمل الأوزان المخصّصة أو المحمّلة

الأوزان الكمية المُصدرة مخزّنة فـweights/verdict-q8.bin، وكاينة حتى فـHugging Face. الـCLI كيقبل مسار بديل للأوزان عبر --weights.

جرّب العرض التوضيحي فالمتصفح

صفحة مشروع Verdict كتشغّل نفس الأوزان الكمية فالمتصفح. وحسب توثيق المشروع، السجلات ما كتترفعش.

عاود إنتاج التدريب والتقييم

ثبّت الإضافات ديال التدريب والتطوير، عاود ولّد corpus اصطناعي، درّب النموذج، صدّر أوزان int8، قيّم artifact، وشغّل الاختبارات:

python -m pip install -e '.[train,dev]'
python training/train.py
pytest -q

المعيار العلني كيستعمل 192 مثال اصطناعي من 48 عائلة ديال CLI ما كانتش فالتدريب. التدريب كيستعمل 1,440 مثال اصطناعي من 60 عائلة مختلفة. النموذج الكمي المعلن حقق دقة 93.2% وmacro-F1 بنسبة 93.2%، مقارنةً بدقة 47.9% وmacro-F1 بنسبة 31.9% لخط أساس مبني على رمز الخروج.

الـcorpus اصطناعي ومنحاز للإنجليزية. هاد القياسات كتقيّم قوالب محجوزة للاختبار، وماشي الموثوقية على آثار الوكلاء فالإنتاج، ونتائج زمن الاستجابة ماشي وعود صالحة على جميع الأجهزة.

عرف حدود المشروع

Verdict محدود عن قصد. كيصنّف الأدلة اللي كيبانَت فإخراج CLI، ولكن ما كيحدّدش واش مهمة أوسع سالات. وما كيبرهنش حتى على صحة الكود، ولا السلامة، ولا صدق المعطيات.

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

الخلاصة

Verdict كيوفّر طريقة صغيرة، سريعة، ومحلية باش تفسّر نتائج CLI بعناية أكثر من فحص كيعتمد غير على رمز الخروج. ثبّتو كحزمة Python، وفّر سياق التنفيذ كامل، واستعمل التسميات الأربعة ديالو باش توجّه الإجراءات اللاحقة. ولأتمتة موثوقة، ديما جمع النتيجة الإرشادية ديالو مع تحقق حتمي وموثوق.