تصنيفات مسبقة ودرجات عناصر محجوزة من نموذج تشغّله أصلاً

جديد في v2.14.0

هذا الدرس للفرق التي تشغّل أصلاً نموذجاً خارج Potato وتريد أن تعرف مدى اتفاق النموذج مع معلّقي الفريق قبل عرض إجاباته على أي أحد. يضم تدريب النماذج في Potato خمسة مُدرِّبات، تسمى الجسور، لا تدرّب شيئاً. يرسل الجسر العناصر المحجوزة في الدراسة إلى نموذج يُخدَّم في مكان آخر، ويقيّم الإجابات مقابل تصنيفات الدراسة، ويكتبها راجعةً تصنيفاتٍ مسبقة للمراجعة، كما تفعل تشغيلة نموذج مدرَّب. تغطي الخطوات أدناه نموذجاً بصرياً لغوياً خلف API متوافق مع OpenAI، ونموذج Roboflow، ودالة CVAT بلا خادم، ونموذج Hugging Face، وخلفية ML في Label Studio، مع تهيئة مُتحقَّق منها لكل منها.

ما يرسله تشغيل الجسر وما يقيّمه

الجسر مُدرِّب لا تفعل خطوة الضبط فيه سوى التحقق من أن الخدمة تجيب. ثم ترسل التشغيلة إلى الخدمة العناصر الموجودة في قسمي val وtest للتشغيلة، ومعها العناصر التي لم يصنّفها أحد حين يكون writeback.include_unlabeled: true. يحوّل Potato الإجابات إلى أشكال المخطط نفسه، أي المقاطع أو الاختيارات، ويقيّمها على العناصر المحجوزة مقابل التصنيفات البشرية المحسومة، بـمقاييس العناصر المحجوزة نفسها التي يحصل عليها نموذج مدرَّب (mAP50 للصناديق، وF1 للمقاطع، وmacro-F1 للاختيارات المفردة). وتعمل الكتابة الراجعة وطابور المراجعة ومعرّف تشغيلة كل تصنيف مسبق كما بعد أي تشغيلة أخرى.

لا يعتمد قسم العنصر إلا على معرّفه وعلى model_training.split_seed، ولذلك تُقيَّم تشغيلة الجسر وتشغيلة النموذج المدرَّب على عناصر val وtest نفسها ما دامت البذرة ثابتة. فيضع جدول التشغيلات في /admin/training نموذجاً تملكه أصلاً بجانب نموذج مدرَّب على تصنيفات الدراسة. ولا تحصل عناصر قسم train على تنبؤ من الجسر، ولا تضع الكتابة الراجعة تصنيفاً مسبقاً على عنصر من قسم train أبداً. وعند التقسيم الافتراضي 70/15/15 يُقيَّم الجسر إذن على نحو 30% من العناصر المصنّفة.

قبل أن تبدأ

تحتاج الجسور الأربعة غير label-studio-ml إلى requests وPillow على خادم Potato، وتسرد صفحة التدريب الجسر بعبارة "not installed" إلى أن تُستورد الحزمتان. ولا يحتاج label-studio-ml إلى شيء يتجاوز Potato. ولا يثبّت أي من الجسور الخمسة نموذجاً أو مكتبة GPU أو torch، لأن النموذج يعمل في الخدمة.

يجب أن تكون الصور ملفات محلية داخل المشروع، كما في كل مُدرِّب صور. يستبعد الجسر العنصر الذي صورته عنوان http(s) بعيد، ويُحتسب العنصر الذي له تصنيف ولا تنبؤ له خاطئاً في درجة العناصر المحجوزة. وتبلّغ التشغيلة عن نسبة العناصر المحجوزة التي حصلت على تنبؤ في val_coverage وtest_coverage، فتشير التغطية المنخفضة إلى صور لم يستطع الجسر إرسالها.

المفاتيح تبقى في متغيرات البيئة

لا يوضع مفتاح في التهيئة أبداً. يأخذ كل جسر يرسل مفتاحاً معاملاً يسمّي متغير البيئة الذي يحمل المفتاح (api_key_env، أو token_env لـHugging Face، أو الاسمين basic_auth_*_env لـLabel Studio)، ويجب أن يكون المتغير مضبوطاً في بيئة خادم Potato قبل بدء الخادم. ولا يرسل cvat-nuclio مفتاحاً ولا يأخذ معاملاً كهذا. وترفض الجسور الأربعة التي تأخذ مفتاحاً قيمةً ليست اسم متغير، ولا يكرّر الخطأ القيمة، لأن القيمة في هذا الموضع هي على الأرجح المفتاح نفسه. وحين يردّد متن خطأ من الخدمة أو خطأ اتصال الطلب، تستبدل الجسور قيمة المفتاح بـ[redacted] قبل عرض الخطأ. وتُنظَّف متون الأخطاء من /predict في خلفية ML في Label Studio بالطريقة نفسها. ويُستبدل كذلك كل ما يشبه مفتاحاً في سلسلة استعلام أو ترويسة Authorization.

تشغيلات hf-inference وroboflow محلية فقط. يقرأ الجسران المفتاح على خادم Potato، وتشغيلة على خلفية ssh أو SLURM أو وكيل ستضطر إلى شحن المفتاح إلى ذلك المضيف، ولذلك يرفض Potato بدء تشغيلة كهذه هناك. أما openai-vlm-boxes وcvat-nuclio وlabel-studio-ml فتعمل على أي خلفية تصل إلى الخدمة، مع ضبط متغير المفتاح على مضيف تلك الخلفية.

الخطوة 1: دراسة صور بثلاثة جسور

تُعدّ التهيئة أدناه دراسة لصور مواقع بناء يرسم فيها المعلّقون صندوقاً حول كل خوذة وكل رأس مكشوف. تحمل model_training.trainer_params قيماً افتراضية لعدة مُدرِّبات معاً، فتحمل التهيئة الواحدة إعدادات الجسور الثلاثة للصور كلها، وتستخدم كل تشغيلة كتلة مُدرِّبها. ويمتلئ حقل Parameters في صفحة التدريب من هذه القيم الافتراضية حين تختار مُدرِّباً.

annotation_task_name: "Hard hats on site photos"
task_dir: .
media_directory: media
output_annotation_dir: annotation_output
admin_api_key: "replace-with-a-long-random-string"
 
data_files:
  - data/photos.jsonl
 
item_properties:
  id_key: id
  text_key: image_url
 
annotation_schemes:
  - annotation_type: image_annotation
    name: ppe
    description: "Box every hard hat and every bare head."
    source_field: image_url
    tools: [bbox, polygon]
    labels:
      - name: helmet
      - name: head
 
model_training:
  enabled: true
  writeback:
    schemas: [ppe]
    include_unlabeled: true
  trainer_params:
    openai-vlm-boxes:
      url: http://localhost:8000/v1
      model: Qwen/Qwen2.5-VL-7B-Instruct
      coordinate_format: pixels
    roboflow:
      model_id: site-safety/3        # your Roboflow project and version
      url: https://detect.roboflow.com
      api_key_env: ROBOFLOW_API_KEY
      confidence: 0.4
      label_map: {hardhat: helmet, no-hardhat: head}   # the model's class names on the left
    cvat-nuclio:
      url: http://localhost:32768
      threshold: 0.5
      label_map: {person: null}

يسمّي كل سطر في data/photos.jsonl صورة واحدة تحت media/:

{"id": "site_001", "image_url": "media/site_001.jpg"}

writeback.schemas هو ما يجعل صناديق النموذج مرئية للمعلّقين، ويرسل include_unlabeled إلى الخدمة الصور التي لم يصنّفها أحد أيضاً. اترك المفتاحين كليهما في التشغيلة الأولى إن أردت درجة العناصر المحجوزة قبل أن يرى أحد تصنيفاً مسبقاً. يربط label_map أسماء فئات الخدمة بتصنيفات المخطط، وتُسقَط الفئة المربوطة بـnull. والفئة بلا مدخل تذهب إلى التصنيف الذي يحمل الاسم نفسه، ولا تراعي المطابقة حالة الأحرف. وتُستبعد الصناديق تحت أي فئة أخرى، ويعدّ سجل التشغيلة الصناديق المستبعدة.

الخطوة 2: نموذج بصري لغوي باستخدام openai-vlm-boxes

يصغّر openai-vlm-boxes كل صورة إلى 1280 بكسل على الأكثر على الضلع الأطول (max_image_side) ويرسلها إلى مسار إكمال الدردشة مع موجِّه يسمّي تصنيفات المخطط. ويقرأ Potato الرد صناديقَ بصيغة JSON. يصلح أي خادم بواجهة API متوافقة مع OpenAI. يخدم الأمر أدناه Qwen2.5-VL بـvLLM، وتصل وثائقه العملاء عند http://localhost:8000/v1:

vllm serve Qwen/Qwen2.5-VL-7B-Instruct

مع vLLM على المنفذ 8000، شغّل Potato على منفذ آخر:

potato start config.yaml -p 9000

تجيب النماذج البصرية اللغوية بعُرفها الإحداثي الخاص أياً كان ما يطلبه الموجِّه، ويخبر معاملان Potato كيف يقرأ الأرقام. فـcoordinate_format هو fraction (من 0 إلى 1 من الصورة)، أو per_mille (من 0 إلى 1000)، أو pixels للصورة كما أُرسلت. وbox_order هو xyxy لـ[x0, y0, x1, y1] أو yxyx لـ[y0, x0, y1, x1]. يجيب Qwen2.5-VL بالبكسلات، ولذلك تضبط التهيئة أعلاه coordinate_format: pixels. وفي auto يخمّن Potato الصيغة مرة واحدة لكل رد من حجم الأرقام. فالقيم حتى 1.05 تُقرأ كسوراً، والقيم التي تتجاوز حجم الصورة المرسلة تُقرأ بالألف، وكل ما عدا ذلك يُقرأ بكسلات. والصندوق بالألف الذي يتسع داخل صورة كبيرة يُقرأ إذن بكسلات، فسمِّ الصيغة متى عرفت عُرف النموذج.

يجيب Gemma وGemini بصناديق بالألف مع y أولاً، [ymin, xmin, ymax, xmax]، حتى حين يطلب الموجِّه كسوراً. ومع ضبط المعاملين كليهما على auto يقرأ Potato صناديق نموذج يحتوي اسمه على gemma أو gemini بالألف مع y أولاً. وفي مشروع اختبار من مربعات حمراء وزرقاء لنموذج Gemma 4 12B، قاس فريق Potato درجة mAP50 فبلغت 0.0 مع قراءة الصناديق x أولاً و1.0 مع قراءتها y أولاً. يخدم Ollama نموذج Gemma 3 باسم يحتوي على gemma، فينطبق auto:

ollama run gemma3:12b

استبدل كتلة openai-vlm-boxes في التهيئة بالكتلة أدناه:

model_training:
  trainer_params:
    openai-vlm-boxes:
      url: http://localhost:11434/v1
      model: gemma3:12b
      json_mode: object

ويحصل ضبط دقيق لـGemma أو Gemini يُخدَّم باسم لا يحتوي على أي من الكلمتين على قراءة x أولاً في auto. اضبط coordinate_format: per_mille وbox_order: yxyx لنموذج كهذا. ويطلب json_mode: object من Ollama JSON بـresponse_format: json_object. أما الافتراضي schema فيرسل مخطط JSON تكون التصنيفات فيه تعداداً. يحترم vLLM وOpenAI المخطط. والتشغيلة التي لا يُحلَّل فيها أي رد بوصفه JSON تفشل، ويقترح الخطأ json_mode: object أو موجِّهاً أبسط (prompt، حيث يصبح {labels} تصنيفات المخطط).

لا يعطي النموذج البصري اللغوي درجة مع صناديقه، فلا ثقة للصناديق. ويمرّر writeback.min_confidence كل تنبؤ من openai-vlm-boxes، ولا تستطيع مراجعة النموذج ترتيب التنبؤات من الأقل ثقة إلى الأعلى. ويسرد مرجع openai-vlm-boxes المعامل api_key_env لواجهة API مستضافة وإعدادات الرمز والمهلة.

الخطوة 3: ابدأ تشغيلة واقرأ الدرجة

افتح http://localhost:9000/admin/training، واختر openai-vlm-boxes والمخطط ppe، وانقر Train now. وتبدأ التشغيلة نفسها من API:

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  http://localhost:9000/admin/training/api/runs \
  -d '{"trainer": "openai-vlm-boxes", "schemas": ["ppe"]}'

تسرد خطوة الضبط نماذج الخادم عبر /models، وتسجّل أي نموذج تسأله التشغيلة وكيف تقرأ صناديقه. ثم يرسل مرور التنبؤ صورة واحدة في كل طلب. وحين تنتهي التشغيلة تظهر mAP50 للعناصر المحجوزة في جدول التشغيلات، وتسرد صفحة التشغيلة val_map_50 وtest_map_50 وأرقام التغطية وتحذير "Not used" الذي يعدّ الردود التي لم تكن JSON والصناديق تحت تصنيفات ليست في المخطط والصناديق خارج الصورة. وحين تقارب الدرجة 0 والتغطية مرتفعة والتحذير فارغ، افحص coordinate_format وbox_order أولاً.

نماذج Roboflow

يرسل roboflow كل صورة بطلب POST إلى <url>/<model_id>، حيث model_id هو المشروع والإصدار بالشكل project/version. يوضع المفتاح في ROBOFLOW_API_KEY افتراضياً (api_key_env)، وترفض التشغيلة البدء دونه:

export ROBOFLOW_API_KEY=...   # in the shell that starts Potato
potato start config.yaml -p 9000

url الافتراضي في Potato هو https://detect.roboflow.com، وتسمّي التهيئة أعلاه الافتراضي. وتضبط التشغيلة لتقسيم المثيلات url: https://outline.roboflow.com. وurl معامل، فيمكن لتشغيلة أن تسمّي أيضاً https://serverless.roboflow.com، وهو المضيف الذي يذكره مرجع كشف الكائنات في Roboflow لمسار project/version نفسه. ولم يختبر فريق Potato هذا المضيف مع هذا الجسر. ويستمع خادم Roboflow Inference المستضاف ذاتياً إلى المنفذ 9001 افتراضياً (url: http://localhost:9001).

يأخذ API في Roboflow المفتاح في سلسلة الاستعلام. ولا يكتب Potato عنوان الطلب في سجل التشغيلة ولا في رسالة خطأ. ويرسل Potato confidence وoverlap (القيمتان الافتراضيتان 0.4 و0.3) إلى API بوصفهما نسبتين مئويتين، وتوثّق مراجع Roboflow كليهما على مقياس من 0 إلى 100. ويكتب shapes: auto محيطاً حيث يعيد النموذج محيطاً ويكون في المخطط أداة مضلّع، وصندوقاً فيما عدا ذلك. ويرسل فحص الصحة صورة بيضاء 8 × 8، وتحتسب Roboflow الطلب على استخدام الحساب.

دوال CVAT بلا خادم

يستخدم cvat-nuclio كاشفاً منشوراً أصلاً لـCVAT بوصفه دالة Nuclio، مثل دالتي YOLOv7 أو Faster R-CNN في cvat/serverless. يرسل Potato كل صورة إلى عنوان الدالة نفسه بالشكل {"image": <base64>, "threshold": t}، دون المرور بـCVAT. يسرد nuctl get functions الدوال المنشورة مع منافذها، والأمر أدناه هو الصيغة التي تذكرها وثائق CVAT:

nuctl get functions --platform local

تجيب الدالة بأشكال بالبكسلات. يصبح rectangle صندوقاً، ويصبح polygon مضلّعاً، أو الصندوق المحيط بالمضلّع حين لا تكون في المخطط أداة مضلّع. وتُستبعد أشكال mask وتُعدّ. وتُسقط الدالة الأشكال التي تقل درجتها عن threshold (الافتراضي 0.5). ولا تصنيف للأشخاص في المخطط، فيُسقط label_map: {person: null} في التهيئة الأشخاص الذين يكتشفهم كاشف COCO.

نماذج Hugging Face باستخدام hf-inference

يستدعي hf-inference نموذجاً منشوراً على Hugging Face، إما Inference Endpoint مخصصاً بعنوان https:// الخاص به (endpoint_url) أو معرّف نموذج على API الخدمة اللامركزية HF Inference (model). اضبط endpoint_url أو model، وليس كليهما. وتتبع المهمةُ نوعَ المخطط:

• تصنيف النصوص لـradio وselect وmultiselect. يأخذ مخطط الاختيار المفرد أعلى تصنيف للنموذج. وحين لا يكون ذلك التصنيف من تصنيفات المخطط بعد label_map، لا يحصل العنصر على تنبؤ بدلاً من التصنيف التالي. ويأخذ مخطط multiselect كل تصنيف تبلغ درجته threshold على الأقل (الافتراضي 0.5).
• تصنيف الرموز لـspan، مع تجميع أجزاء الكلمات في كيانات بحسب aggregation_strategy (simple أو first أو average أو max) وأخذ إزاحات الأحرف من النموذج.
• كشف الكائنات لـimage_annotation. تُسقط الصناديق التي تقل درجتها عن threshold.

تسأل التهيئة أدناه dslim/bert-base-NER عن المقاطع. تصف بطاقة النموذج نموذج BERT مضبوطاً ضبطاً دقيقاً للكيانات المسمّاة على CoNLL-2003 الإنجليزية. ويخدم HF Inference جزءاً من نماذج Hub، فتحقق من أن صفحة النموذج تسرد HF Inference قبل الاعتماد على API الخدمة اللامركزية.

annotation_task_name: "Named entities in news sentences"
task_dir: .
output_annotation_dir: annotation_output
admin_api_key: "replace-with-a-long-random-string"
 
data_files:
  - data/sentences.jsonl
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: span
    name: entities
    description: "Highlight every person, organization, and place."
    labels: [person, organization, location]
 
model_training:
  enabled: true
  writeback:
    schemas: [entities]
    include_unlabeled: true
  trainer_params:
    hf-inference:
      model: dslim/bert-base-NER
      token_env: HF_TOKEN
      aggregation_strategy: simple
      label_map: {PER: person, ORG: organization, LOC: location, MISC: null}

تُربط كيانات النموذج PER وORG وLOC بتصنيفات المخطط، ويُسقط MISC لأنه لا تصنيف كهذا في المخطط. وحين لا يطابق الاسم الكامل للكيان شيئاً، يُسقط Potato البادئة B- أو I- ويحاول من جديد. ويحتاج مصنِّف مشاعر يجيب بـLABEL_0 وLABEL_1 إلى label_map: {LABEL_0: negative, LABEL_1: positive} بالطريقة نفسها. وفحص الصحة طلب حقيقي واحد، جملة قصيرة أو صورة 8 × 8، ويجعل wait_for_model: true (الافتراضي) الطلبَ ينتظر أثناء تحميل نموذج لامركزي بدلاً من الفشل بخطأ 503.

خلفية ML في Label Studio

يستخدم label-studio-ml خلفية ML في Label Studio قيد التشغيل. تخدم الخلفية المبدوءة من أمثلة المستودع بـdocker-compose up نموذجاً عبر HTTP عند http://localhost:9090. تفحص التشغيلة GET /health في الخلفية، وترسل العناصر إلى POST /predict في دفعات من 16 (batch_size)، وتقرأ المناطق المعادة بالمحوِّل نفسه الذي يستخدمه potato import -f label_studio. وتصبح إزاحات المقاطع UTF-16 في Label Studio نقاطَ رموز، وتصبح الإحداثيات النسبية المئوية إحداثيات عنصر واجهة الصورة.

annotation_task_name: "Review sentiment"
task_dir: .
output_annotation_dir: annotation_output
admin_api_key: "replace-with-a-long-random-string"
 
data_files:
  - data/reviews.jsonl
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "Is this review positive or negative?"
    labels: [positive, negative]
 
model_training:
  enabled: true
  writeback:
    schemas: [sentiment]
    include_unlabeled: true
    min_confidence: 0.6
  trainer_params:
    label-studio-ml:
      url: http://localhost:9090
      basic_auth_user_env: LS_ML_USER
      basic_auth_pass_env: LS_ML_PASS

المصادقة الوحيدة في الخلفية القياسية هي HTTP Basic، وتُضبط بـBASIC_AUTH_USER وBASIC_AUTH_PASS على الخلفية. ويسمّي basic_auth_user_env وbasic_auth_pass_env المتغيرين على خادم Potato اللذين يحملان القيمتين نفسيهما، ويأتي المعاملان معاً. ويرسل api_key_env بدلاً من ذلك Authorization: Token <value>، لخلفية خلف وكيل ينتظر رمزاً. وترد الخلفية القياسية على هذه الترويسة بخطأ 500. ويولّد Potato تهيئة الوسم المرسلة مع كل طلب من المخطط (Choices أو Labels أو RectangleLabels أو PolygonLabels)، ويستبدل label_config الـXML المولَّد بما تكتبه أنت.

وتحتاج خلفية الصور إلى إعداد إضافي. فبدون media_url_prefix يرسل Potato كل صورة مساراً مطلقاً على جهاز Potato، وتقرأ الخلفية المبنية على Label Studio SDK الحقل data.image عنواناً وتفشل أمام مسار مجرّد. ولخلفية على الجهاز نفسه، أضف البادئة أدناه وابدأ الخلفية مع ضبط LOCAL_FILES_DOCUMENT_ROOT على مجلد المهمة:

model_training:
  trainer_params:
    label-studio-ml:
      url: http://localhost:9090
      media_url_prefix: /data/local-files/?d=

ولخلفية على جهاز آخر، قدّم مجلد المهمة عبر HTTP وأعطِ عنوان ذلك الخادم بادئةً. والصورة خارج مجلد المهمة لا مسار لها نسبةً إلى المجلد، ولذلك لا يرسلها Potato، ويسمّي سجل التشغيلة عدد ما استُبعد.

يرسل Potato إلى الخلفية طلبات تنبؤ ولا يرسل أحداث تعليق، ولذلك لا يبدأ تدريب الخلفية نفسها في معالج /webhook من Potato. ويستورد potato import -f label_studio مشروع Label Studio كاملاً إلى Potato بتهيئة وسمه وإجابات المعلّقين والتنبؤات المخزَّنة (استيراد المشاريع). ويتناول الانتقال من Label Studio إلى Potato الوسوم التي يتركها المستورِد.

راجع التصنيفات المسبقة

تمر تنبؤات الجسر عبر فحوص الكتابة الراجعة نفسها لنموذج مدرَّب. تتخطى الكتابة الراجعة عناصر قسم train والمخططات الغائبة عن writeback.schemas، وتتخطى أزواج العنصر والمخطط التي رفضها مراجع، وتحجب التنبؤات التي دون writeback.min_confidence. وفي الصناديق والمقاطع، ثقة التنبؤ هي ثقة أقل الأشكال أو المقاطع ثقةً، فيحجب الحدّ الأدنى تنبؤ العنصر كله حين تقل درجة أي صندوق أو مقطع واحد في العنصر. أما confidence في Roboflow وthreshold في CVAT فيعملان لكل صندوق، عند الخدمة، ويعمل threshold في hf-inference لكل صندوق أو لكل تصنيف multiselect. ويتناول درس النموذج في الحلقة طابور المراجعة وأحكام القبول والرفض وإعادة التدريب. ويعمل الطابور والأحكام بالطريقة نفسها مع الجسر.

يُحفظ تنبؤ واحد لكل عنصر ومخطط، ولذلك تحلّ تشغيلة لاحقة لجسر آخر أو لنموذج مدرَّب محل التصنيفات المسبقة للتشغيلة السابقة. ولسحب التصنيفات المسبقة لتشغيلة، أرسل DELETE /admin/training/api/runs/<run_id>/predictions. ويسرد مرجع جسور الاستدلال كل معاملات الجسور الأربعة، ويسرد مرجع label-studio-ml معاملات Label Studio.

قراءات إضافية

• تدريب النماذج يتناول الحلقة وصفحة التدريب.
• المُدرِّبات تسرد المُدرِّبات الـ 38 بحسب المهمة، لنموذج مدرَّب على تصنيفات الدراسة تقارنه بدرجة جسر.
• التهيئة توثّق التقسيمات والكتابة الراجعة والمسارات.
• التعليق التوضيحي للصور والتعليق التوضيحي للمقاطع توثّقان المخططات التي تملؤها الجسور.
• دعم الذكاء الاصطناعي البصري يعرض على المعلّق اقتراحات نموذج بصري عند الطلب، دون درجة عناصر محجوزة.