صيغ البيانات
صيغ البيانات المدعومة وكيفية هيكلة بيانات التوسيم.
صيغ البيانات
يدعم Potato صيغ بيانات متعددة جاهزة للاستخدام. يشرح هذا الدليل كيفية هيكلة بياناتك للتوسيم.
الصيغ المدعومة
| الصيغة | الامتداد | الوصف |
|---|---|---|
| JSON | .json | مصفوفة من الكائنات |
| JSON Lines | .jsonl | كائن JSON واحد لكل سطر |
| CSV | .csv | قيم مفصولة بفواصل |
| TSV | .tsv | قيم مفصولة بعلامات جدولة |
صيغة 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!"
}ملفات الوسائط
الإشارة إلى صور أو فيديوهات أو ملفات صوتية:
{
"id": "1",
"image_path": "images/photo_001.jpg"
}item_properties:
id_key: id
image_key: image_pathالحوارات/القوائم
يتم عرض القوائم أفقيًا تلقائيًا:
{
"id": "1",
"text": "Option A,Option B,Option C"
}أزواج النصوص
لمهام المقارنة:
{
"id": "pair_001",
"text": {
"A": "Response from Model A",
"B": "Response from Model B"
}
}ملفات HTML
الإشارة إلى ملفات HTML مخزنة في مجلدات:
{
"id": "1",
"html_file": "html/document_001.html"
}التوسيم السياقي
تضمين سياق بجانب النص الرئيسي:
{
"id": "1",
"text": "This is great!",
"context": "Previous message: How do you like the new feature?"
}item_properties:
id_key: id
text_key: text
context_key: contextإعدادات العرض
خيارات عرض القوائم
تحكم في كيفية عرض القوائم والقواميس:
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 في النص:
html_content: true{
"id": "1",
"text": "<p>This is <strong>formatted</strong> text.</p>"
}إعدادات المخرجات
مجلد المخرجات
حدد مكان حفظ التوسيمات:
output_annotation_dir: "output/"صيغة المخرجات
اختر صيغة المخرجات:
output_annotation_format: "json" # json, jsonl, csv, or tsvهيكل المخرجات
تتضمن التوسيمات معرّف المستند والردود:
{
"id": "doc_001",
"user": "annotator_1",
"annotations": {
"sentiment": "Positive",
"confidence": 4
},
"timestamp": "2024-01-15T10:30:00Z"
}أنواع بيانات خاصة
مقياس الأفضل-الأسوأ
لمهام الترتيب، استخدم عناصر مفصولة بفواصل:
{
"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
database: potato_db
user: ${DB_USER}
password: ${DB_PASSWORD}ينشئ Potato الجداول المطلوبة تلقائيًا عند التشغيل الأول.
التحقق من البيانات
يتحقق Potato من بياناتك عند بدء التشغيل:
- حقل المعرّف مفقود - جميع العناصر تحتاج معرّفات فريدة
- حقل النص مفقود - العناصر تحتاج محتوى للتوسيم
- معرّفات مكررة - يجب أن تكون جميع المعرّفات فريدة
- ملف غير موجود - تحقق من مسارات ملفات البيانات
مثال كامل
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. استخدم معرّفات ذات معنى
يسهّل التتبع وتصحيح الأخطاء:
{"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قراءة إضافية
- تحميل من مجلد البيانات - التحميل من المجلدات مع المراقبة المباشرة
- توسيم الحوار - عرض بيانات متعددة العناصر
- صيغ التصدير - خيارات صيغ المخرجات
لمزيد من التفاصيل التقنية، راجع الوثائق المصدرية.