Skip to content

التطوير المحلي

ثبّت Potato وشغّله محليًا للتطوير والاختبار. يغطي التثبيت عبر pip وإعداد ملف الإعداد وتشغيل الخادم وتشخيص مشاكل بدء التشغيل الشائعة.

شغّل Potato على جهازك المحلي للتطوير والاختبار.

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

  • Python 3.9 أو أعلى
  • مدير الحزم pip
  • Git (اختياري، لاستنساخ الأمثلة)

التثبيت

باستخدام pip (موصى به)

bash
pip install potato-annotation

من المصدر

bash
git clone https://github.com/davidjurgens/potato.git
cd potato
pip install -e .

مع التبعيات الاختيارية

bash
# Local speech-to-text and diarization for transcript projects
pip install "potato-annotation[transcribe]"
 
# Hosted model providers for AI support and active learning
pip install "potato-annotation[ai]"
 
# Everything except the multi-gigabyte server-side vision stack
pip install "potato-annotation[all]"

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

البدء السريع

1. إنشاء ملف إعداد

أنشئ config.yaml:

yaml
annotation_task_name: "My First Annotation Task"
task_dir: "."
port: 8000
 
data_files:
  - data.json
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels:
      - Positive
      - Negative
      - Neutral
 
output_annotation_dir: "annotations/"

task_dir هو الجذر الذي تُحل بالنسبة إليه جميع المسارات النسبية الأخرى، ويرفض Potato القراءة من خارجه. ضبطه على . يُبقي ملف الإعداد وملف البيانات ومجلد المخرجات في مجلد واحد، وهذا ما يتيح نقل المشروع إلى خادم لاحقًا.

2. تحضير بيانات نموذجية

أنشئ data.json:

json
[
  {"id": "1", "text": "I love this product!"},
  {"id": "2", "text": "This is terrible."},
  {"id": "3", "text": "It's okay, nothing special."}
]

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

bash
potato start config.yaml

4. الوصول إلى الواجهة

افتح متصفحك على http://localhost:8000

وضع التطوير

وضع التصحيح

يفعّل وضع التصحيح السجلات المفصّلة، ويوقف مهلة خمول الجلسة، ويفتح صفحات المسؤول دون مفتاح للطلبات الآتية من جهازك. تبقى صفحة تسجيل الدخول، ويتخطاها --debug-phase (أدناه):

bash
potato start config.yaml --debug

لا تفعّل وضع التصحيح أبدًا على خادم منشور. فالنفق أو الوكيل العكسي على الجهاز نفسه الذي لا يضيف ترويسة تمرير يجعل كل متصل يبدو محليًا، و--debug-phase يُدخل كل زائر بوصفه المستخدم نفسه debug_user. ترفض إصدارات Potato من 2.8.2 حتى 2.11.0 البدء في وضع التصحيح على العنوان الافتراضي 0.0.0.0، لذا أضف --host 127.0.0.1 على هذه الإصدارات.

سجلات التصحيح

اختر الجانب الذي يكتب السجلات من التطبيق:

bash
potato start config.yaml --debug-log server

القيم المقبولة هي all وui وserver وnone. استخدم ui عندما تتصرف صفحة التعليق التوضيحي بشكل خاطئ، وserver عندما يفشل تحميل عنصر.

الإخراج المفصل

اعرض كل نشاط الخادم:

bash
potato start config.yaml --verbose

الانتقال إلى مرحلة

مع تفعيل --debug، تخطَّ تسجيل الدخول وانتقل مباشرة إلى المرحلة التي تعمل عليها بدلًا من المرور بصفحتي الموافقة والتعليمات عند كل إعادة تشغيل:

bash
potato start config.yaml --debug --debug-phase annotation

هيكل المجلد

التخطيط الموصى به للمشروع:

text
my-annotation-project/
├── config.yaml           # Main configuration, inside task_dir
├── data/
│   ├── training.json     # Practice items for the training phase
│   └── main.json         # Annotation data
├── annotations/          # output_annotation_dir
├── media/                # media_directory, served at /media/
└── templates/            # site_dir, if you override the default templates

الملفان المطلوبان فقط هما config.yaml وملف البيانات. يأتي Potato بقوالبه الخاصة، لذا لا تضبط site_dir ولا تضف مجلد templates/ إلا عند استبدالها، ووجّه site_file إلى ملف محدد لعرض صفحة التعليق التوضيحي به.

اختبار الإعداد الخاص بك

التحقق من الإعداد

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

bash
potato validate config.yaml

أضف --strict لتجعل التحذيرات، مثل مفتاح غير معروف، تُفشل التشغيل بدلًا من طباعتها وتمريره.

وضع المعاينة

اعرض ما يعلنه ملف الإعداد، واعرضه في متصفح دون تشغيل خادم كامل:

bash
potato preview config.yaml

تحتاج لقطات الشاشة إلى الحزمة الإضافية الخاصة بالمتصفح عديم الواجهة، pip install "potato-annotation[preview]":

bash
potato preview config.yaml --screenshot preview.png

المشاكل الشائعة

المنفذ مستخدم بالفعل

bash
# Use a different port
potato start config.yaml -p 8080

أو اضبطه في config.yaml، ويتجاوز الخيار -p هذه القيمة عندئذ:

yaml
port: 8080

ملف البيانات غير موجود

تأكد من أن المسارات نسبية بالنسبة لموقع ملف الإعداد:

yaml
# If data is in a subdirectory
data_files:
  - data/main.json

تُحل المسارات بالنسبة إلى task_dir، ويرفض Potato تحميل ملف خارجه، لذا انقل البيانات إلى داخل مجلد المهمة بدلًا من الإشارة إلى مسار مطلق في مكان آخر على الجهاز.

رفض الإذن

تحقق من أذونات الملفات:

bash
chmod 755 annotations/
chmod 644 data/*.json

مستخدمون متعددون محليًا

لاختبار سيناريوهات المستخدمين المتعددين:

yaml
user_config:
  allow_all_users: true
 
login:
  type: url_direct
  url_argument: user_id

يقرأ url_direct اسم المستخدم مباشرة من عنوان URL ولا يطلب كلمة مرور، لذا يمكنك فتح ملفَّي تعريف في المتصفح والتعليق بصفتك شخصين دون تسجيل حسابات:

  • http://localhost:8000/?user_id=annotator1
  • http://localhost:8000/?user_id=annotator2

إعادة تعيين التعليقات التوضيحية

يكتب Potato مجلدًا لكل مُعلِّق داخل output_annotation_dir، ويحتوي كل مجلد على ملف user_state.json الخاص بذلك الشخص:

bash
# Remove one annotator's work
rm -rf annotations/annotator1
 
# Or clear every annotator
rm -rf annotations/*
 
# Restart server
potato start config.yaml

حذف مجلد مستخدم يحذف تعييناته مع إجاباته، لذا يعيد التشغيل الجديد تعيين العناصر من البداية.

متغيرات البيئة

الإعداد عبر البيئة:

bash
# Keeps sessions valid across restarts; required for OAuth
export POTATO_SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
 
# Fixes the shared admin key instead of letting Potato generate one per task
export POTATO_ADMIN_API_KEY="your-admin-key"
 
potato start config.yaml

بدون POTATO_SECRET_KEY يولّد Potato مفتاح توقيع عشوائيًا عند كل تشغيل، مما يسجّل خروج الجميع عند كل إعادة تشغيل.

استخدام البيئات الافتراضية

venv

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

Conda

bash
conda create -n potato python=3.10
conda activate potato
pip install potato-annotation

تكامل بيئة التطوير

VS Code

ثبّت إضافة YAML لدعم ملفات الإعداد:

json
// settings.json
{
  "yaml.schemas": {
    "https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json": "config.yaml"
  }
}

تحمل ملفات الإعداد التي تُنزَّل من مصمم الدراسات هذا المخطط بالفعل في سطر # yaml-language-server:، لذا يتحقق المحرر منها دون هذا الإعداد.

PyCharm

أنشئ تهيئة تشغيل:

  1. Add → Python
  2. Script: potato
  3. Parameters: start config.yaml
  4. Working directory: مسار مشروعك

الخطوات التالية