صيغ البيانات
صيغ البيانات المدعومة وكيفية هيكلة بيانات التوسيم.
يدعم Potato صيغ بيانات متعددة جاهزة للاستخدام. يشرح هذا الدليل كيفية هيكلة بياناتك للتوسيم.
From input file to exported labels
الصيغ المدعومة
| الصيغة | الامتداد | الوصف |
|---|---|---|
| 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قراءة إضافية
- تحميل من مجلد البيانات - التحميل من المجلدات مع المراقبة المباشرة
- توسيم الحوار - عرض بيانات متعددة العناصر
- صيغ التصدير - خيارات صيغ المخرجات
لمزيد من التفاصيل التقنية، راجع الوثائق المصدرية.