سطر أوامر محرّك الوسم وواجهة REST API وأدوات MCP وSDK

يشغّل خادم التوسيم، وسطر الأوامر، وواجهة REST API، وأدوات MCP، وPython SDK كلها محرّك الوسم نفسه على ملف engine.sqlite نفسه في مجلد المهمة. فيمكنك أن تبدأ دراسة من سطر الأوامر، وتقدّم الطلبات البشرية بالخادم، وتُشهِد من دفتر ملاحظات (notebook).

لا تشغّل الدراسةَ إلا عمليةٌ واحدة في كل مرة. فالمخطِّط في الخادم العامل يحمل قفل الكتابة الخاص بالدراسة، وما دام يحمله يرفض potato label run وpotato label certify وStudy.run() العمل ويذكر ذلك. أشهِد عبر الخادم بدلاً من ذلك، باستخدام POST /api/engine/v1/certify أو صفحة الإدارة. والقفل موجود لأن مشغّلَين اثنين سيسحبان عيّنتي معايرة ويُشهِد كل منهما مقابل وسوم الآخر. ويُحرَّر القفل حين يخرج حامله. والحامل الذي قُتلت عمليته على الجهاز نفسه يُنتزع منه القفل فوراً، والحامل على جهاز آخر بعد دقيقتين دون نبضة حياة (heartbeat). أما أوامر القراءة فقط (status، certificate، calls، export) فتعمل في أي وقت.

سطر الأوامر

يأخذ كل أمر من أوامر المحرّك ملف إعداد الدراسة:

potato label <command> <config.yaml> [options]

تغطي الأوامر التسعة الدراسة من أول استدعاء للنموذج إلى مجموعة البيانات المصدَّرة:

لا تنفق متابعة التقدم شيئاً، لأن status وcertificate وصفحة الإدارة تقرأ النتائج المخزّنة. أما كل اختبار جديد، سواء أكان من certify على وسوم جديدة أم من certify --retest، فينفق جزءاً من ميزانية الخطأ الخاصة بالعقد.

الملفات التي يكتبها التصدير

يكتب potato label export أربعة أنواع من الملفات في مجلد المخرجات:

تُصدِّر أدوات التصدير العادية (python -m potato.export والتصدير من صفحة الإدارة) توسيمات البشر، وتسردها صفحة صيغ التصدير. ومن بينها صيغة labeling_engine، التي تكتب الملفات نفسها التي يكتبها potato label export، وترفض العمل حين لا يكون المحرّك مفعّلاً. وحين يكون المحرّك مفعّلاً، تضيف تصديرات CSV وParquet وHugging Face عمودين يذكران طلب المحرّك الذي أجاب عنه كل توسيم. يحمل engine_purpose الغرض، مثل calibration، ويحمل engine_request بيانات JSON فيها الغرض واحتمال الإدراج والظهور والقسم ومعرّف الطلب. استخدم هذين العمودين لفصل العيّنة العشوائية العمياء عن إجابات التحقق.

REST API

كل مسارات المحرّك تحت /api/engine/v1 وتعيد JSON. استوثق بمفتاح المسؤول في الترويسة X-API-Key أو بجلسة مسؤول. تحتاج القراءة إلى صلاحية لوحة تحكم المسؤول، ويحتاج certify وplan إلى صلاحية إدارة الإسناد، وتحتاج الشهادة إلى صلاحية التصدير.

تجيب المسارات بـ 404 حين يكون المحرّك معطّلاً للدراسة. وتجيب بـ 400 مع خطأ JSON عن معامل غير صالح، مثل limit ليس رقماً، أو purpose أو status غير معروفين، أو format غير json وmd وhtml.

مثلاً، يجلب هذا الطلب الشهادة الحالية بصيغة Markdown من خادم على المنفذ 8000:

curl -H "X-API-Key: $ADMIN_API_KEY" \
  "http://localhost:8000/api/engine/v1/certificate?format=md"

أدوات MCP

يتيح خادم MCP خمس أدوات للمحرّك، بالصلاحيات نفسها التي لمسارات REST:

• engine_status
• engine_requests
• engine_run، الذي يشغّل تمريرة واحدة للمخطِّط
• engine_certify، الذي يأخذ retest
• engine_certificate، بصيغة json أو md أو html

منح هذه الأدوات والمحرّك معطّل تحذير تحقّق. وعبر potato mcp connect، يعود الاستدعاء المرفوض (صلاحية ناقصة، أو معامل خاطئ) خطأَ أداة يحمل رسالة الخادم. ويشرح توثيق خادم MCP منح الأدوات وربط عميل.

Python SDK

يشغّل الصنف Study المحرّك من Python، في دفتر ملاحظات مثلاً:

from potato.labeling_engine.sdk import Study
 
study = Study("examples/labeling-engine/text-certified-sentiment/config.yaml")
study.run()                                   # label, sample, certify, resolve
for req in study.requests(status="open")[:5]:
    study.label(req.item_id, req.schema, "positive", user="me")
study.certify()
print(study.certificate(fmt="md"))
study.export("out/")

تقابل كل طريقة أمراً أو مساراً:

يَسِم المثال كل طلب مفتوح بـ "positive" فقط لعرض الاستدعاءات. والوسم المسجَّل عبر Study.label الذي لا يجيب عن أي طلب يُحتفظ به وسماً عضوياً، والوسوم العضوية لا تُشهِد أبداً، لذا فإن السكربت الذي يَسِم عناصر لم يطلبها المحرّك يضيف وسوماً لا يقرؤها أي عقد.

قراءة إضافية

• محرّك الوسم
• إعداد محرّك الوسم
• عقود محرّك الوسم
• لوحة تحكم المسؤول، التي ترتبط بصفحة إدارة المحرّك

للاطلاع على تفاصيل التنفيذ، راجع الوثائق المصدرية.