Skip to content

صيغ البيانات

صيغ البيانات المدعومة وكيفية هيكلة بيانات التوسيم.

صيغ البيانات

يدعم Potato صيغ بيانات متعددة جاهزة للاستخدام. يشرح هذا الدليل كيفية هيكلة بياناتك للتوسيم.

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

الصيغةالامتدادالوصف
JSON.jsonمصفوفة من الكائنات
JSON Lines.jsonlكائن JSON واحد لكل سطر
CSV.csvقيم مفصولة بفواصل
TSV.tsvقيم مفصولة بعلامات جدولة

صيغة JSON

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

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 منفصل. مفيدة لمجموعات البيانات الكبيرة:

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

صيغة CSV/TSV

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

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

الإعدادات

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

قم بإعداد ملفات البيانات وتعيينات الحقول في ملف YAML:

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

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

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

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

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

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

نص عادي

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

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

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

الإشارة إلى صور أو فيديوهات أو ملفات صوتية:

json
{
  "id": "1",
  "image_path": "images/photo_001.jpg"
}
yaml
item_properties:
  id_key: id
  image_key: image_path

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

يتم عرض القوائم أفقيًا تلقائيًا:

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

أزواج النصوص

لمهام المقارنة:

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

ملفات HTML

الإشارة إلى ملفات HTML مخزنة في مجلدات:

json
{
  "id": "1",
  "html_file": "html/document_001.html"
}

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

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

json
{
  "id": "1",
  "text": "This is great!",
  "context": "Previous message: How do you like the new feature?"
}
yaml
item_properties:
  id_key: id
  text_key: text
  context_key: context

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

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

تحكم في كيفية عرض القوائم والقواميس:

yaml
list_as_text:
  # Add prefixes to items
  text_prefix: "A"  # A., B., C. (or "1" for 1., 2., 3.)
 
  # Display orientation
  horizontal: true  # Side-by-side (false for vertical)
 
  # Randomization
  randomize_values: true   # Shuffle list items
  randomize_keys: true     # Shuffle dictionary keys

محتوى HTML

تفعيل عرض HTML في النص:

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

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

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

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

yaml
output_annotation_dir: "output/"

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

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

yaml
output_annotation_format: "json"  # json, jsonl, csv, or tsv

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

تتضمن التوسيمات معرّف المستند والردود:

json
{
  "id": "doc_001",
  "user": "annotator_1",
  "annotations": {
    "sentiment": "Positive",
    "confidence": 4
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

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

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

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

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

حجج مخصصة

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

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

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

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

yaml
database:
  type: mysql
  host: localhost
  database: potato_db
  user: ${DB_USER}
  password: ${DB_PASSWORD}

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

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

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

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

مثال كامل

yaml
task_name: "Document Classification"
task_dir: "."
port: 8000
 
# Data configuration
data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id
  text_key: text
  context_key: metadata
 
# Display settings
list_as_text:
  text_prefix: "1"
  horizontal: false
 
# Output
output_annotation_dir: "output/"
output_annotation_format: "json"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "Select the document category"
    labels:
      - News
      - Opinion
      - Tutorial
      - Other
 
allow_all_users: true

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

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

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

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

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

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

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

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

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

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

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

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

python
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:

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

قراءة إضافية

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