डेटा प्रारूप

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/ पर परोसता है। डिफ़ॉल्ट फ़ोल्डर task_dir के अंदर media/ है, और पूर्ण (absolute) पथ देने पर यह मशीन पर कहीं भी मौजूद किसी फ़ोल्डर की ओर इशारा करता है। मीडिया डिस्प्ले फ़ील्ड (जैसे image, video, audio, pdf) में photo_001.jpg जैसा केवल फ़ाइल-नाम, फ़ाइल उस फ़ोल्डर में होने पर /media/photo_001.jpg बन जाता है, और पूरा URL जैसा लिखा है वैसा ही इस्तेमाल होता है। item_properties.image_key पेज पर छवि नहीं दिखाता। यह AI सपोर्ट और डुप्लिकेट पहचान को बताता है कि छवि किस फ़ील्ड में है।

संवाद/सूचियाँ

जिस 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 के लिए अलग आइटम प्रॉपर्टी नहीं है। Potato के साथ आने वाला 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?"
}

id और text के अलावा बाकी फील्ड kwargs के ज़रिए पेज तक पहुँचते हैं। 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> और सूची से बाहर की हर चीज़ एस्केप होकर निष्क्रिय रहती है। स्पैन हाइलाइट आइटम में मार्कअप के रूप में जोड़े जाते हैं, इसीलिए पूरे फील्ड को एस्केप करना संभव नहीं है।

{
  "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 में उस एनोटेटर के लेबल इंस्टेंस के अनुसार रखे जाते हैं, और स्पैन अलग से दर्ज होते हैं:

{
  "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"}
      ]
    }
  }
}

विशेष डेटा प्रकार

Best-Worst Scaling

रैंकिंग कार्यों के लिए, अल्पविराम-पृथक आइटम उपयोग करें:

{
  "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 स्टार्टअप पर आपके डेटा को मान्य करता है:

• गुम ID फील्ड: सभी आइटम में अद्वितीय पहचानकर्ता होने चाहिए
• गुम पाठ फील्ड: आइटम में एनोटेट करने के लिए सामग्री होनी चाहिए
• डुप्लिकेट ID: सभी ID अद्वितीय होनी चाहिए
• फ़ाइल नहीं मिली: डेटा फ़ाइल पथ जाँचें

पूर्ण उदाहरण

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 का उपयोग करें

ट्रैकिंग और डीबगिंग आसान होती है:

{"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

आगे पढ़ें

• डेटा डायरेक्टरी लोडिंग: लाइव वॉचिंग के साथ डायरेक्टरी से लोड करें
• संवाद एनोटेशन: मल्टी-आइटम डेटा डिस्प्ले
• निर्यात प्रारूप: आउटपुट प्रारूप विकल्प

कार्यान्वयन विवरण के लिए स्रोत दस्तावेज़ देखें।