صيغ البيانات

يقرأ Potato مدخلات التوسيم من ملفات JSON وJSON Lines وCSV وTSV. يشرح هذا الدليل كيفية هيكلة هذه البيانات، والحقول التي يحتاجها Potato من كل سجل، والمكان الذي تُحفظ فيه التوسيمات.

من ملف الإدخال إلى التسميات المُصدَّرة

الصيغ المدعومة

صيغة JSON

الصيغة الأكثر شيوعًا. يجب أن تكون بياناتك مصفوفة من الكائنات:

[
  {
    "id": "doc_001",
    "text": "This is the first document to annotate.",
    "source": "twitter",
    "date": "2024-01-15"
  },
  {
    "id": "doc_002",
    "text": "This is the second document.",
    "source": "reddit",
    "date": "2024-01-16"
  }
]

صيغة JSON Lines

كل سطر هو كائن JSON منفصل. مفيدة لمجموعات البيانات الكبيرة:

{"id": "doc_001", "text": "First document"}
{"id": "doc_002", "text": "Second document"}
{"id": "doc_003", "text": "Third document"}

صيغة CSV/TSV

بيانات جدولية مع ترويسات:

id,text,source
doc_001,"This is the first document",twitter
doc_002,"This is the second document",reddit

الإعدادات

الإعداد الأساسي

اضبط ملفات البيانات وتعيينات الحقول في ملف YAML:

data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id      # Field name for unique ID
  text_key: text  # Field name for content to annotate

ملفات بيانات متعددة

ادمج مصادر بيانات متعددة:

data_files:
  - "data/batch_1.json"
  - "data/batch_2.json"
  - "data/batch_3.jsonl"

تتم معالجة الملفات بالترتيب ودمجها.

أنواع البيانات

نص عادي

محتوى نصي بسيط:

{
  "id": "1",
  "text": "The product arrived quickly and works great!"
}

ملفات الوسائط

يذكر عنصر الصورة أو الفيديو أو الصوت ملفه في حقل من حقول السجل، ويعرضه حقل في instance_display على الصفحة:

{
  "id": "1",
  "image_path": "photo_001.jpg"
}

media_directory: media    # the default, relative to task_dir
 
instance_display:
  fields:
    - key: image_path
      type: image

يقدّم Potato الملفات الموجودة في media_directory على المسار /media/. المجلد الافتراضي هو media/ داخل task_dir، ويجعله مسار مطلق يشير إلى مجلد في أي مكان على الجهاز. في حقل عرض وسائط (مثل image وvideo وaudio وpdf) يتحول اسم الملف المجرد مثل photo_001.jpg إلى /media/photo_001.jpg إذا كان الملف في ذلك المجلد، أما عنوان URL الكامل فيُستخدم كما كُتب. لا يضع item_properties.image_key الصورة على الصفحة. فهو يخبر دعم الذكاء الاصطناعي وكشف التكرار بالحقل الذي يحمل الصورة.

الحوارات/القوائم

يُعرض حقل text الذي يحتوي على قائمة JSON بعنصر واحد في كل سطر، لأن القراءة العمودية تناسب الحوار. اضبط list_as_text.horizontal لوضع العناصر جنبًا إلى جنب في مقارنة زوجية:

{
  "id": "1",
  "text": ["Option A", "Option B", "Option C"]
}

أزواج النصوص

يُعرض حقل text الذي يحتوي على كائن JSON بواسطة نوع العرض الذي تعلنه الإعدادات (conversation_tree وweb_agent_trace وما شابههما). وإذا لم يُعلَن أي نوع عرض، يُعرض الحقل بصيغة JSON منسقة، لذا أعلن نوع عرض لمهمة المقارنة:

{
  "id": "pair_001",
  "text": {
    "A": "Response from Model A",
    "B": "Response from Model B"
  }
}

ملفات HTML

احفظ ملفات .html في مجلد داخل task_dir وأشر إليها من حقل text المعتاد، إذ لا توجد في Potato خاصية عنصر منفصلة لـ HTML. تضمّن المهمة المرفقة examples/advanced/html-annotation كل ملف منها:

{
  "id": "1",
  "text": "<embed width=\"1020\" height=\"440\" src=\"data/html_data/1.html\" type=\"text/html\">"
}

التوسيم السياقي

تضمين سياق بجانب النص الرئيسي:

{
  "id": "1",
  "text": "This is great!",
  "context": "Previous message: How do you like the new feature?"
}

تصل الحقول الأخرى غير المعرّف والنص إلى الصفحة عبر kwargs، الذي يسمّي المفاتيح الإضافية التي تُنقل من كل عنصر:

item_properties:
  id_key: id
  text_key: text
  kwargs:
    - context

إعدادات العرض

خيارات عرض القوائم

تحكم في طريقة عرض حقل قيمته قائمة. يقبل المفتاح ثلاثة مفاتيح فرعية، وlist_as_text: true يفعّله بالقيم الافتراضية:

list_as_text:
  # Prefix each item so an annotator can refer to one by name.
  text_list_prefix_type: alphabet   # alphabet, number, bullet, or none
 
  # Side-by-side suits a pairwise comparison. The default is vertical.
  horizontal: true
 
  # Shade alternate turns, which keeps a long dialogue readable.
  alternating_shading: true

محتوى HTML

تُعرض الوسوم الموجودة في حقل text دون أي مفتاح إعدادات. يعقّم Potato هذه الوسوم بدلًا من تهريبها، فتتحول الوسوم الموجودة في قائمة مسموح بها (<b> و<i> و<span> وما شابهها) إلى تنسيق، بينما يُهرَّب <script> وكل ما هو خارج القائمة فيصبح بلا أثر. تُحقن تمييزات المقاطع (spans) في العنصر على هيئة وسوم، ولهذا لا يمكن تهريب الحقل كله.

{
  "id": "1",
  "text": "<p>This is <strong>formatted</strong> text.</p>"
}

إعدادات المخرجات

مجلد المخرجات

حدد مكان حفظ التوسيمات:

output_annotation_dir: "output/"

صيغة المخرجات

تُحفظ التوسيمات دائمًا في ملفات user_state.json لكل مستخدم. ويكتب export_annotation_format إضافة إلى ذلك تصديرًا مسطحًا دوريًا في <output_annotation_dir>/exports/<format>/، وهو الشكل المناسب للتحليل. لا يوجد مُصدِّر باسم json:

export_annotation_format: "jsonl"   # or csv, tsv, parquet, coco, conll_2003, ...

شغّل python -m potato.export --list-formats للاطلاع على السجل الكامل.

هيكل المخرجات

يحتوي كل ملف user_state.json على تسميات ذلك الموسِّم مفهرسة حسب النسخة، مع تسجيل المقاطع (spans) بشكل منفصل:

{
  "user_id": "annotator_1",
  "instance_id_to_label_to_value": {
    "doc_001": {
      "sentiment": {"labels": {"positive": true}}
    }
  },
  "instance_id_to_span_to_value": {
    "doc_001": {
      "ner": [
        {"start": 0, "end": 5, "label": "PERSON", "text": "Alice"}
      ]
    }
  }
}

أنواع بيانات خاصة

مقياس الأفضل-الأسوأ

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

{
  "id": "1",
  "text": "Item A,Item B,Item C,Item D"
}

حجج مخصصة

تضمين حقول إضافية للعرض أو التصفية:

{
  "id": "1",
  "text": "Document content",
  "category": "news",
  "priority": "high",
  "custom_field": "any value"
}

قاعدة البيانات الخلفية

لمجموعات البيانات الكبيرة، استخدم MySQL:

database:
  type: mysql
  host: localhost
  port: 3306
  database: potato_db
  username: ${DB_USER}
  password: ${DB_PASSWORD}

ينشئ Potato الجداول المطلوبة تلقائيًا عند التشغيل الأول.

التحقق من البيانات

يتحقق Potato من بياناتك عند بدء التشغيل:

• حقل المعرّف مفقود - جميع العناصر تحتاج معرّفات فريدة
• حقل النص مفقود - العناصر تحتاج محتوى للتوسيم
• معرّفات مكررة - يجب أن تكون جميع المعرّفات فريدة
• ملف غير موجود - تحقق من مسارات ملفات البيانات

مثال كامل

annotation_task_name: "Document Classification"
task_dir: "."
port: 8000
 
# Data configuration
data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id
  text_key: text
 
# Display settings
list_as_text:
  text_list_prefix_type: number
  horizontal: false
 
# Output
output_annotation_dir: "output/"
export_annotation_format: "jsonl"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "Select the document category"
    labels:
      - News
      - Opinion
      - Tutorial
      - Other
 
user_config:
  allow_all_users: true
  users: []

أفضل الممارسات

1. استخدم معرّفات ذات معنى

يسهّل التتبع وتصحيح الأخطاء:

{"id": "twitter_2024_001", "text": "..."}

2. اجعل النص موجزًا

النصوص الطويلة تبطئ التوسيم. فكّر في:

• الاقتصار على الأجزاء الرئيسية
• تقديم ملخصات
• استخدام حاويات قابلة للتمرير

3. أضف البيانات الوصفية

تساعد في التصفية والتحليل:

{
  "id": "1",
  "text": "Content",
  "source": "twitter",
  "date": "2024-01-15",
  "language": "en"
}

4. تحقق قبل التحميل

تحقق من بياناتك دون اتصال:

import json
 
with open('data.json') as f:
    data = json.load(f)
 
# Check for required fields
for item in data:
    assert 'id' in item, f"Missing id: {item}"
    assert 'text' in item, f"Missing text: {item}"
 
# Check for duplicates
ids = [item['id'] for item in data]
assert len(ids) == len(set(ids)), "Duplicate IDs found"
 
print(f"Validated {len(data)} items")

5. احتفظ بنسخة احتياطية من البيانات الأصلية

احتفظ بالبيانات الخام منفصلة عن التوسيمات لضمان قابلية إعادة الإنتاج.

6. استخدم JSON Lines للملفات الكبيرة

أكثر كفاءة في استخدام الذاكرة من مصفوفات JSON:

# Convert JSON array to JSON Lines
cat data.json | jq -c '.[]' > data.jsonl

قراءة إضافية

• تحميل من مجلد البيانات - التحميل من المجلدات مع المراقبة المباشرة
• توسيم الحوار - عرض بيانات متعددة العناصر
• صيغ التصدير - خيارات صيغ المخرجات

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