Skip to content

البدء السريع

شغّل Potato في أقل من 5 دقائق. ثبّته باستخدام pip، واكتب ملف إعدادات YAML، وشغّل الخادم، ووسِّم أول مجموعة بيانات لك دون كتابة أي شيفرة.

ينقلك هذا الدليل من تثبيت جديد إلى توسيم البيانات في أقل من 5 دقائق. وهو يوضّح كيف تكتب مهمة بنفسك. والطريقة الأخرى للبدء هي أن تصف الدراسة لوكيل برمجة وتترك potato-skill يصمّمها ويبنيها، وهذا ما تشرحه صفحة البدء السريع مع وكيل برمجة.

Potato في خمس خطوات: التثبيت، والإعداد، وتشغيل الخادم، والتوسيم في المتصفح، والتصديرPotato في خمس خطوات

المتطلبات الأساسية

  • Python 3.9 أو أعلى
  • مدير الحزم pip
  • طرفية

التثبيت

نوصي بتثبيت Potato داخل بيئة افتراضية حتى لا يتعارض مع Python الخاص بالنظام:

bash
python -m venv potato-env
source potato-env/bin/activate   # Windows: potato-env\Scripts\activate
pip install potato-annotation

تحقّق من التثبيت:

bash
python -c "import potato; print(potato.__version__)"

يجب أن ترى الرقم 2.12.1 مطبوعًا. بدءًا من الإصدار 2.9، يعرض الأمر potato --version الرقم نفسه، ويضيف إليه معرّف الإيداع (commit) عندما تشغّل Potato من نسخة مستنسخة من المستودع.

إنشاء مشروعك الأول

1. إنشاء مجلد المشروع

bash
mkdir my-annotation-task
cd my-annotation-task

2. إنشاء ملف البيانات

أنشئ مجلدًا باسم data وداخله ملفًا باسم data.json:

bash
mkdir data
json
[
  {"id": "1", "text": "I love this product! It's amazing."},
  {"id": "2", "text": "This is the worst experience ever."},
  {"id": "3", "text": "It's okay, nothing special."}
]

يقبل Potato أيضًا في data_files ملفات .jsonl (كائن JSON واحد في كل سطر) و.csv و.tsv. أشِر إلى ملف بالامتداد المناسب، وسيختار Potato القارئ بناءً عليه.

3. إنشاء ملف الإعدادات

أنشئ ملفًا باسم config.yaml في مجلد مشروعك:

عزل المسارات: تُحسب أي مسارات نسبية داخل ملف الإعدادات (مثل data_files أو output_annotation_dir) نسبةً إلى task_dir، ويجب أن تبقى داخله. يرفض Potato المسارات التي تشير إلى موضع خارج task_dir لمنع اجتياز المسارات (path traversal).

yaml
annotation_task_name: "Sentiment Analysis"
 
# All relative paths below are resolved against task_dir.
task_dir: "."
 
# Data configuration
data_files:
  - "data/data.json"
 
# Tell Potato which fields in each record to use.
# id_key = unique identifier; text_key = the text shown to annotators.
item_properties:
  id_key: id
  text_key: text
 
# Where per-user annotation state is stored (relative to task_dir).
output_annotation_dir: "annotation_output/"
 
# Also write a periodic flat export, because the per-user state files are
# awkward to analyze. No exporter is named "json", so use "jsonl".
export_annotation_format: "jsonl"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"   # required for radio schemes
    labels:
      - Positive
      - Negative
      - Neutral
 
# Skip password authentication so anyone can log in with just a username.
require_password: false

نصيحة: يمكنك التحقق من ملف الإعدادات دون تشغيل الخادم الكامل باستخدام أداة المعاينة عبر سطر الأوامر. إنها أسرع طريقة لاكتشاف الأخطاء المطبعية قبل أن تبدأ التوسيم.

4. تشغيل الخادم

bash
potato start config.yaml -p 8000

الصيغة الطويلة المكافئة:

bash
python -m potato start config.yaml -p 8000

إذا كان المنفذ 8000 مستخدمًا بالفعل، فاختر منفذًا آخر باستخدام -p 8001. لإيقاف الخادم، اضغط Ctrl+C في الطرفية.

تشغيل أول أسرع: أضف --debug --debug-phase=annotation لتخطي صفحتي تسجيل الدخول والموافقة أثناء التجربة: potato start config.yaml --debug --debug-phase=annotation. عندها يُسجَّل دخول كل زائر بوصفه مستخدمًا واحدًا مشتركًا هو debug_user، لذا لا تستخدمه إلا على جهازك.

5. افتح المتصفح

انتقل إلى http://localhost:8000. سترى شاشة تسجيل دخول فيها حقل واحد هو username. اكتب أي اسم (مثل alice) وانقر Continue، وستبدأ التوسيم مباشرة.

في كل مرة تختار فيها تسمية وتنقر Next، يُحفَظ توسيمك تلقائيًا. لا يوجد زر "حفظ" منفصل.

أين تُحفَظ توسيماتك

يكتب Potato حالة كل مستخدم أثناء التوسيم:

text
my-annotation-task/
├── config.yaml
├── data/
│   └── data.json
└── annotation_output/              # created automatically
    └── alice/
        └── user_state.json         # one folder per username

يحتوي user_state.json على حالة التوسيم الكاملة لذلك المستخدم. لإنتاج ملف مسطّح موحّد يجمع كل الموسِّمين، شغّل أداة التصدير في Potato عبر سطر الأوامر، وهي موصوفة في توثيق التصدير. شغّل python -m potato.export --list-formats لترى كل الصيغ التي تسجّلها.

مشكلات شائعة عند التشغيل الأول

  • Address already in use. المنفذ 8000 مشغول. استخدم -p 8001 (أو أي منفذ متاح).
  • KeyError: 'description'. مخطط من نوع radio (أو نوع مشابه) ينقصه الحقل الإلزامي description. يحتاج كل مخطط إلى هذا الحقل.
  • Path ... is outside the task directory. أحد مسارات data_files أو output_annotation_dir يخرج عن task_dir. أبقِ كل شيء داخل مجلد المشروع، أو اضبط task_dir على مسار مطلق يحتويها.
  • تعرض صفحة تسجيل الدخول حقلًا لكلمة المرور. نسيت إضافة require_password: false، أو أنك تستخدم تبويبًا مخزّنًا مؤقتًا في المتصفح. أعد تشغيل الخادم وحدّث الصفحة تحديثًا كاملًا.

الأسئلة الشائعة

تتناول الأسئلة التالية تثبيت Potato وتشغيله في Docker والتحقق من ملف الإعدادات قبل أن يراه الموسِّمون.

كيف أثبّت Potato؟

ثبّت Potato من PyPI باستخدام pip install potato-annotation، على Python 3.9 أو أعلى. يؤدي التثبيت داخل بيئة افتراضية إلى إبقاء اعتماديات Potato منفصلة عن Python الخاص بالنظام، ويؤكد الأمر potato --version نجاح التثبيت بطباعة رقم الإصدار.

هل يمكن تشغيل Potato في Docker؟

نعم. ينشر Potato صورة جاهزة مسبقًا، هي ghcr.io/davidjurgens/potato، على GitHub Container Registry. يُركَّب مجلد مشروعك داخل الحاوية على المسار /app ويستمع الخادم على المنفذ 7860 داخلها، ولذلك تخدم صورة واحدة كل مهمة. اضبط POTATO_SECRET_KEY حتى تبقى جلسات الموسِّمين قائمة بعد إعادة التشغيل. يقدّم دليل نشر Potato على خادم أمر docker run كاملًا.

كيف أتحقق من ملف إعدادات Potato قبل أن يراه الموسِّمون؟

شغّل potato validate config.yaml --strict، الذي يتحقق من ملف الإعدادات بالطريقة التي يتحقق بها الخادم عند الإقلاع، ويحوّل التحذيرات، مثل مفتاح غير معروف، إلى أخطاء. بعد ذلك يعرض potato preview config.yaml ما يصرّح به ملف الإعدادات ويعرض الواجهة في متصفح، فترى المهمة كما سيراها الموسِّم قبل أن يسجّل أي شخص الدخول.

ما التالي؟

الأدوات والمرافق

بعد أن تعتاد على الأساسيات، اطّلع على هذه الأدوات المفيدة: