إعداد محرّك الوسم

كل مفاتيح كتلة labeling_engine، وتشمل المصادر وطرق تقدير الثقة، ومجموعات البشر، والإنفاق على التعهيد الجماعي، والميزانيات، وحدود التشغيل، والميزات، وما يرفضه التحقق.

كل ما يفعله محرّك الوسم يُضبط في كتلة labeling_engine واحدة. والكتلة غير الصالحة توقف الخادم عند بدء التشغيل وتسرد كل المشكلات دفعة واحدة. ولكي تُقدَّم طلبات المحرّك إلى المُعلِّقين، اضبط أيضاً assignment_strategy: engine. وضبط هذه الاستراتيجية دون محرّك مفعّل خطأ تحقّق.

تضم الكتلة الأقسام التالية، ويتناول كلاً منها ما يلي:

yaml

assignment_strategy: engine
 
labeling_engine:
  enabled: true
  schemas: [sentiment]            # default: every scheme a source can label
  sources: []
  cascade: [laya, gemma]          # default: the first source alone
  contracts: []
  humans: {}
  crowd: {}
  budgets: {}
  runtime: {}
  features: {}
  redaction: {}
  distill: {}

مفاتيح المستوى الأعلى

تقع خمسة مفاتيح مباشرة تحت labeling_engine:

المفتاح	الافتراضي	المعنى
`enabled`	`false`	تفعيل المحرّك. والمحرّك المفعّل يحتاج إلى مصدر واحد على الأقل.
`schemas`	الكل	مخططات التوسيم التي يَسِمها المحرّك. في ظل `assignment_strategy: engine`، لا يُجاب عن المخطط المستبعد إلا على العناصر التي يرسلها المحرّك إلى البشر من أجل مخططاته هو، لا على كل عنصر، ويحذّر التحقق من ذلك. والمخطط الذي لا يستطيع أي مصدر وسمه (النص الحر مثلاً) لا يمكن أن يكون في المحرّك، لذا لا يُجاب عنه أبداً على كل عنصر في ظل هذه الاستراتيجية. استخدم استراتيجية إسناد أخرى إن كان ذلك لازماً.
`sources`	`[]`	النماذج. انظر المصادر.
`cascade`	المصدر الأول	معرّفات المصادر بالترتيب الذي تُجرَّب به. ويأتي البشر بعد آخرها.
`contracts`	`[]`	ما يجب أن تستوفيه الوسوم. انظر العقود.

المصادر

المصدر نموذج، أو مجموعة وسوم موجودة أصلاً، يقترح وسماً ودرجة ثقة لكل عنصر. لكل مصدر id فريد وkind، والمفتاح غير المعروف على مصدر خطأ:

المفتاح	الافتراضي	المعنى
`id`	إلزامي	الاسم المستخدم في `cascade` وسجل الاستدعاءات والشهادة.
`kind`	إلزامي	واحد من `llm`، `vlm`، `decision`، `detector`، `judge`، `jury`، `trained`، `static`، `fixture`، `asr`، `lf`، `simulator`.
`endpoint_type`	إلزامي لـ `llm` و`vlm` و`decision` و`judge`	نقطة نهاية الذكاء الاصطناعي، مثل `vllm` أو `openai` أو `anthropic` أو `gemini` أو `ollama` أو `openrouter` أو `openai_vision` أو `ollama_vision` أو `laya` أو `systemone`. وقيمته الافتراضية لـ `detector` هي `yolo`.
`model`	افتراضي نقطة النهاية	اسم النموذج.
`base_url`	لا شيء	عنوان URL للخادم في نقاط النهاية المستضافة ذاتياً أو المتوافقة مع OpenAI.
`api_key`	لا شيء	لا يدخل أبداً في تجزئة الإصدار ولا يُصدَّر أبداً. ويُستبدل `${ENV_VAR}` بقيمته.
`temperature`	`0.0`	من 0 إلى 2.
`max_tokens`	`256`	حد رموز المخرجات لكل استدعاء.
`timeout`	افتراضي نقطة النهاية	الثواني لكل استدعاء.
`prompt`	يُبنى من المخطط	قالب الموجّه. وتغييره ينشئ إصداراً جديداً من المصدر.
`confidence`	`{method: auto}`	كيف يحدّد المصدر ثقته. انظر طرق تقدير الثقة.
`concurrency`	`runtime.concurrency`	الاستدعاءات المتوازية لهذا المصدر.
`schemas`	كل مخططات المحرّك	قصر المصدر على هذه المخططات.
`options`	`{}`	خيارات خاصة بالنوع، مسرودة أدناه.
`judge`	`{}`	لـ `judge` فقط. الخيارات نفسها التي في `options`، تحت مفتاحها الخاص، ويتغلّب `options` حيث يضبط كلاهما الخيار نفسه.
`members`	لا شيء	لـ `jury` فقط. معرّفا مصدرين آخرين على الأقل.
`aggregation`	`plurality`	لـ `jury` فقط. الأغلبية النسبية هي القاعدة الوحيدة.
`field` / `predictions_file`	لا شيء	لـ `static` فقط. مكان الوسوم الموجودة. يحمل الحقل `{scheme: label}`، أو وسماً مجرّداً حين يَسِم المصدر مخططاً واحداً. والحقل ذو الشكل الخاطئ على كل عنصر يُفشل التشغيل برسالة تسمّيه.
`error_rate`، `seed`	لا شيء	لـ `fixture` فقط. مصدر اصطناعي بمعدل خطأ معروف، للاختبارات.
`revision`	لا شيء	مراجعة للنموذج تُسجَّل في الإصدار، مثل تجزئة نقطة حفظ.

كل ما يمكن أن يغيّر إجابة (النموذج، والموجّه، ودرجة الحرارة، والخيارات) يدخل في تجزئة إصدار المصدر. والإصدار الجديد يجعل كل عقد يعتمد على المصدر stale.

الإجابة التي ليست قيمة يمكن أن يحملها المخطط، كوسم ليس في قائمته، أو حقل رقمي ليس رقماً، أو قائمة في مخطط اختيار واحد من N، تُسجَّل خطأً ولا تُسجَّل وسماً أبداً، وتعدّ رسالة التشغيل هذه الأخطاء. والعنصر الذي تفشل استدعاءاته يُطلب من جديد في عمليات التشغيل اللاحقة، ثلاث مرات على الأكثر لكل إصدار من المصدر، وبعد ذلك ينتظر مصدراً متغيّراً (المفتاح أو الموجّه المصحَّح إصدار جديد). والتشغيل الذي يفشل فيه مصدر واحد لا يوقف المستويات الأخرى. فالمستوى التالي يَسِم كل عنصر، ويخرج potato label run بالحالة 1 ويسمّي المصدر الفاشل.

طرق تقدير الثقة

تضع قواعد القبول في المحرّك عتبةً على ثقة كل تنبؤ، لذا فإن الطريقة التي يحدّد بها المصدر ثقته تقرّر كم يستطيع المحرّك أن يقبل. ويأخذ confidence.method واحدة من خمس قيم:

`confidence.method`	ينطبق على	ما يفعله
`verbalized`	`llm`، `vlm`، `judge`	يذكر النموذج قيمة من 0 إلى 100 في ردّه. استدعاء واحد، وهي أقل الطرق موثوقية.
`k_sample`	`llm`	`samples` ردود (5 افتراضياً) عند `sample_temperature` (0.7 افتراضياً). الوسم هو الإجابة الأكثر تكراراً، والثقة هي نسبتها. تكلّف k استدعاءات.
`logprob`	`llm`	تُرقَّم الوسوم بحروف ويجيب النموذج بحرف واحد، وتُقرأ الثقة من احتمالات الرمز الأول. استدعاء واحد، وعادةً ما تكون الأفضل معايرةً. تحتاج إلى واجهة خلفية تعيد logprobs (vLLM، والمتوافقة مع OpenAI) وإلى 20 وسماً على الأكثر، والمخطط الذي فيه أكثر من ذلك خطأ تحقّق.
`native`	`decision`، `detector`، `trained`	احتمالات النموذج نفسه. وعلى مصدر `llm` هي خطأ تحقّق.
`auto`	الكل	`native` حيث يملكها المصدر، وإلا `verbalized`.

خيارات خاصة بالنوع

تقرأ خمسة أنواع من المصادر خيارات خاصة بها:

decision يشمل Laya داخل العملية، أو أي خادم /v1/systemone مثل Jev المستضاف أو OpenJev. تعيد تمريرة أمامية واحدة احتمالاً لكل خيار، ويعمل على مخططات radio وselect وlikert وslider. يجب أن يكون endpoint_type إما laya أو systemone، ويحتاج systemone إلى base_url، وهو جذر الخادم (ويُقبل أيضاً عنوان URL ينتهي بـ /v1/systemone). وتُرسل الحالة بصيغة {"text": ...} في الحالتين، فتعطي نقطة الحفظ نفسها الإجابات نفسها داخل العملية وخلف laya-serve، ويرسل options: {state_key: ""} السلسلة النصية المجرّدة بدلاً من ذلك. وعلى مقاييس التقدير (likert، slider) بالكاد تتبع درجات Laya المقياس، فافحص بضعة عناصر قبل الاعتماد عليه. وتحتاج نقطة النهاية laya داخل العملية إلى pip install 'potato-annotation[decision]'.
detector يقرأ الصناديق من كاشف كائنات على مخططات image_annotation. يحدّد keep_threshold (0.35) الدرجة التي يكون الصندوق عندها أو فوقها جزءاً من التنبؤ. والصناديق بين candidate_threshold (0.05) وkeep_threshold تخفض ثقة الصورة. ويربط label_map فئات الكاشف بوسوم المخطط، وتُتجاهل الفئات غير المربوطة. ويسمّي image_field حقل العنصر الذي يحمل مسار الصورة أو عنوان URL الخاص بها. وتُحلّ المسارات كما تحلّها صفحة التوسيم، فيكون /media/x.jpg تحت media_directory الخاص بالمهمة، والمسار النسبي تحت task_dir.
judge يأخذ rubric (وصف المخطط افتراضياً)، وfields (حقول العنصر المعروضة على الحَكَم، بالترتيب)، وswap_order، الذي يسأل مرتين مع عكس ترتيب الوسوم ويحوّل الحكم الذي ينقلب إلى امتناع. وعلى مخططات آثار الوكلاء (process_reward، trajectory_eval، ...) يَسِم الحَكَم كل خطوة.
vlm يستخدم نقطة نهاية للرؤية (openai_vision، anthropic_vision، ollama_vision). ولنموذج مستضاف ذاتياً خلف خادم متوافق مع OpenAI، استخدم openai_vision مع base_url.
trained يأخذ artifact_dir وtrainer (sklearn-text افتراضياً) وrun_id. وفي العادة ينشئ التقطير هذا المصدر، لا إعداد مكتوب يدوياً.

humans

تحدّد كتلة humans من يَسِم وكيف يسحب المحرّك عيّناتهم:

المفتاح	الافتراضي	المعنى
`pools`	`[team]`	من يَسِم: `team`، `crowd`، `solo`.
`calibration_rate`	`auto`	نسبة العناصر المسحوبة للمعايرة العمياء. يختار `auto` معدلاً من إسقاطات العقود، يكفي من الوسوم لكل فئة ليكون قابلاً للاختبار، على ألا يتجاوز نصف الدراسة الصغيرة وخُمس الدراسة التي تزيد على 1,000 عنصر.
`dev_fraction`	`0.5`	نسبة وسوم المعايرة المستخدمة لاختيار العتبات. والباقي يختبرها.
`min_calibration_per_class`	`10`	الحد الأدنى لكل فئة قبل اختبار العقود القائمة على الفئات.
`audit_rate`	`0.02`	نسبة الوسوم الآلية المقبولة حديثاً التي تُعاد إلى البشر، بشكل أعمى، لمراقبة الانجراف.
`overlap`	`0.0`	نسبة عناصر المعايرة التي يَسِمها عدة أشخاص.
`overlap_k`	`3`	عدد الأشخاص لكل عنصر متداخل. ويحتاج العقد `no_worse_than_human` إلى 3.
`distribution_k`	`5`	عدد الأشخاص لكل عنصر في عقود `distributional`.
`truth`	`majority`	كيف تصير وسوم عدة أشخاص على عنصر واحد الوسمَ الذي تُختبر العقود مقابله، `majority` أو `dawid_skene`.
`verify_visibility`	`shown`	هل يعرض طلب التحقق إجابة الآلة (`shown`) أم لا (`blind`).

crowd

تنطبق كتلة crowd حين يكون crowd ضمن humans.pools، وProlific هي منصة التعهيد الجماعي الوحيدة التي يستطيع المحرّك تشغيلها:

المفتاح	الافتراضي	المعنى
`provider`	`prolific`	منصة التعهيد الجماعي.
`study_id`	لا شيء	دراسة Prolific المراد تغيير حجمها.
`reward_usd`	لا شيء	المكافأة لكل مكان، لإسقاطات التكلفة.
`per_worker_quota`	`20`	الطلبات لكل عامل. وعدد الأماكن هو `ceil(open requests / quota)`.

التوظيف الجماعي تشغيل تجريبي افتراضياً، ويُبلغ المخطِّط عما كان سيفعله. وإنفاق المال يحتاج إلى features.crowd_live_spend: true وإلى سقف budgets.human_usd، ويُرفض الإعداد الذي يفعّل الإنفاق الفعلي دون السقف. وتشرح صفحة التعهيد الجماعي إعداد دراسة Prolific نفسها.

budgets

توقف كتلة budgets الإنفاق قبل تجاوز الحد:

المفتاح	المعنى
`model_usd`	التوقف عن استدعاء النماذج المسعّرة بعد إنفاق هذا المبلغ. يحجز كل استدعاء تكلفته المتوقعة أولاً. ولا يقيّد هذا الحد النماذج التي لا سعر لها، ولا النماذج المستضافة ذاتياً على `localhost`.
`human_usd`	سقف الإنفاق على التعهيد الجماعي. وهو إلزامي للإنفاق الفعلي على التعهيد الجماعي.
`human_labels`	الحد الأقصى للطلبات البشرية التي يجوز للمحرّك فتحها، وتُعدّ عند فتح كل طلب.

runtime

تتحكم كتلة runtime في التجميع على دفعات، والتوازي، والمدة التي يجوز لشخص أن يحمل فيها طلباً:

المفتاح	الافتراضي	المعنى
`batch_size`	`32`	العناصر لكل جزء مثبَّت. ويستأنف التشغيل الذي قُطع من الجزء التالي دون تكرار الاستدعاءات.
`concurrency`	`4`	الاستدعاءات المتوازية لكل مصدر، ويتجاوزها `concurrency` الخاص بالمصدر.
`cache`	`true`	إعادة استخدام الردود على الطلبات المتطابقة من إصدار المصدر نفسه.
`retries`	`2`	محاولات إضافية بعد انتهاء المهلة، أو خطأ الاتصال، أو 429، أو 5xx. وتُسجَّل كل محاولة.
`planner_interval`	`30`	الثواني بين تمريرات المخطِّط في الخادم.
`hold_minutes`	`60`	الدقائق التي يجوز لشخص أن يحمل فيها طلباً دون أن يجيب عنه قبل أن يعود إلى المجمّع. ويختفي العنصر أيضاً من صفحته، فلا يستطيع تبويب متروك مفتوحاً أن يجيب عنه لاحقاً.

features

كل ميزة معطّلة افتراضياً عدا drift:

المفتاح	ما يفعّله
`drift`	مفعّل افتراضياً. يتصرف بناءً على نتائج التدقيق. حين يُظهر التدقيق أن معدل خطأ الوسوم المقبولة أعلى من الهدف، تصير حالة العقد `violated`، ويتوقف قبول الوسوم الآلية على ذلك المخطط، وتُسحب وسوم معايرة جديدة. ويبدأ كل إشهاد سلسلة تدقيق جديدة، لذا فإن الإشهاد من جديد بعد الإصلاح يعيد القبول. اضبطه على `false` للاكتفاء بالإبلاغ عن الخرق، وعندها تصير حالة العقد "met, audits breached".
`distill`	تدريب نموذج على وسوم الدراسة ووضعه أولاً في السلسلة المتتالية (انظر distill).
`optimize`	جعل كل تمريرة للمخطِّط تقيّم كل مجموعة جزئية من السلسلة المتتالية على وسوم dev، وتُبلغ عن أرخصها الذي يحافظ على تغطية العقود، على `GET /api/engine/v1/schemes/<name>/optimize`. ولا يُطبَّق شيء، لأن اعتماد سلسلة متتالية تغيير في الإعداد وإشهاد جديد.
`crowd_recruit`	السماح للمخطِّط بتحديد حجم دراسة Prolific، تشغيلاً تجريبياً ما لم يكن `crowd_live_spend` مفعّلاً.
`crowd_live_spend`	تغيير دراسة Prolific فعلياً. يحتاج إلى مجموعة `crowd` وإلى `budgets.human_usd`.
`pii_redaction`	إخفاء عناوين البريد الإلكتروني وعناوين URL وعناوين IP وأرقام البطاقات وأرقام الضمان الاجتماعي وأرقام الهواتف ومعرّفات @ قبل أن يذهب النص إلى واجهة API تابعة لطرف ثالث. ويسجّل سجل الاستدعاءات ما أُخفي في صورة فئات وتجزئات، ولا يسجّل النص أبداً.
`payload_capture`	الاحتفاظ بالموجّهات والردود كاملة تحت `<task_dir>/engine_payloads/`. معطّل افتراضياً، ولا يحتفظ سجل الاستدعاءات إلا بالتجزئات.

redaction

يسرد redaction.categories ما يُخفى من email وurl وip وcard وssn وphone وhandle، وقيمته الافتراضية كلها. ولا ينطبق الإخفاء إلا مع features.pii_redaction، وعلى واجهات API التابعة لأطراف ثالثة فقط. ولا تُخفى البيانات في أنواع نقاط النهاية المستضافة ذاتياً (vllm، ollama، laya، yolo، ...) أينما كانت تعمل، ولا في أي نقطة نهاية يكون base_url الخاص بها على الجهاز نفسه.

distill

مع تفعيل features.distill، يدرّب المحرّك نموذجاً رخيصاً على وسوم الدراسة ويضعه أولاً في السلسلة المتتالية:

المفتاح	الافتراضي	المعنى
`trainer`	`sklearn-text`	أداة تدريب من `potato/training`.
`min_labels`	`200`	لا يبدأ التدريب إلا بعد وجود هذا العدد من الوسوم.
`include_silver`	`true`	التدريب أيضاً على الوسوم الآلية التي أشهد عليها عقد، مع وسمها بالفضية.
`every`	`2.0`	إعادة التدريب حين يكون عدد الوسوم قد زاد بهذا المعامل.

لا تدخل عناصر قسمي cert والتدقيق أبداً في مجموعة التدريب، لذا لا يُختبر النموذج المقطَّر أبداً على وسوم دُرّب عليها.

التحقق

يفحص potato validate config.yaml كتلة labeling_engine مع بقية الإعداد، ويسمّي كل خطأ مفتاحه، مثل labeling_engine.sources[1].kind must be one of ... أو labeling_engine.contracts[0].error is required for selective_risk. ويرفض التحقق أيضاً:

مفتاح عقد لا يقرؤه نوع العقد، مثل خطأ إملائي في error؛
عقداً على مخطط لا يستطيع أي مصدر في السلسلة المتتالية وسمه، مع سبب كل مصدر؛
عقداً على مخطط لا يستطيع المحرّك تقييمه (النص الحر، والمقارنة الزوجية)؛
مصدر decision لا يكون endpoint_type الخاص به نموذج قرار، ومصدر llm أو vlm أو judge يكون endpoint_type الخاص به نموذج قرار؛
وno_worse_than_human مع humans.overlap_k أقل من 3.

ويحذّر التحقق أيضاً حين تكون budgets.human_labels أصغر من أن تكفي للإشهاد على عقد selective_risk حتى لو كانت كل إجابة آلية صحيحة. ارفع الميزانية، أو خفّف error، حتى يختفي هذا التحذير.

قراءة إضافية

محرّك الوسم
عقود محرّك الوسم
سطر الأوامر وواجهة REST API وأدوات MCP وSDK
دعم الذكاء الاصطناعي، لأنواع نقاط النهاية التي تتشاركها المصادر مع بقية Potato

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