Name: Potato
Author: Potato

Potato legge i dati in ingresso e scrive le annotazioni in JSON e JSONL. Non c'è molto da sapere, ma i dettagli iniziano a pesare quando il dataset cresce o quando mescoli testo, immagini e audio. Questa guida ripercorre i formati con esempi funzionanti per ogni tipo di dato.

Formati dei dati in ingresso

JSON Lines (JSONL)

Un oggetto JSON per riga. È il formato da provare per primo:

json

{"id": "001", "text": "First document text here."}
{"id": "002", "text": "Second document text here."}
{"id": "003", "text": "Third document text here."}

Perché JSONL: puoi leggerlo riga per riga invece di caricare tutto il file in memoria, aggiungere un record significa aggiungere una riga, e una riga malformata non compromette il resto del file.

Array JSON

Un normale array JSON:

json

[
  {"id": "001", "text": "First document."},
  {"id": "002", "text": "Second document."},
  {"id": "003", "text": "Third document."}
]

Configurazione:

yaml

data_files:
  - data/items.json

Dati per l'annotazione di testo

Testo semplice

json

{"id": "doc_001", "text": "The product quality exceeded my expectations."}

Con metadati

json

{
  "id": "review_001",
  "text": "Great product, fast shipping!",
  "metadata": {
    "source": "amazon",
    "date": "2024-01-15",
    "author": "user123",
    "rating": 5
  }
}

Con pre-annotazioni

json

{
  "id": "ner_001",
  "text": "Apple announced new products in Cupertino.",
  "pre_annotations": {
    "entities": [
      {"start": 0, "end": 5, "label": "ORG", "text": "Apple"},
      {"start": 31, "end": 40, "label": "LOC", "text": "Cupertino"}
    ]
  }
}

Configurazione:

yaml

data_files:
  - data/texts.json
 
item_properties:
  id_key: id
  text_key: text

Dati per l'annotazione di immagini

Immagini locali

json

{
  "id": "img_001",
  "image_path": "/data/images/photo_001.jpg",
  "caption": "Street scene in Paris"
}

Immagini remote

json

{
  "id": "img_002",
  "image_url": "https://example.com/images/photo.jpg"
}

Con bounding box

json

{
  "id": "detection_001",
  "image_path": "/images/street.jpg",
  "pre_annotations": {
    "objects": [
      {"bbox": [100, 150, 200, 300], "label": "person"},
      {"bbox": [350, 200, 450, 280], "label": "car"}
    ]
  }
}

Configurazione:

yaml

data_files:
  - data/images.json
 
item_properties:
  id_key: id
  image_key: image_path  # or image_url

Dati per l'annotazione audio

Audio locale

json

{
  "id": "audio_001",
  "audio_path": "/data/audio/recording.wav",
  "duration": 45.5,
  "transcript": "Hello, how are you today?"
}

Con segmenti

json

{
  "id": "audio_002",
  "audio_path": "/audio/meeting.mp3",
  "segments": [
    {"start": 0.0, "end": 5.5, "speaker": "Speaker1"},
    {"start": 5.5, "end": 12.0, "speaker": "Speaker2"}
  ]
}

Configurazione:

yaml

data_files:
  - data/audio.json
 
item_properties:
  audio_key: audio_path
  text_key: transcript

Dati multimodali

Testo + immagine

json

{
  "id": "mm_001",
  "text": "What is shown in this image?",
  "image_path": "/images/scene.jpg"
}

Testo + audio

json

{
  "id": "mm_002",
  "text": "Transcribe this audio:",
  "audio_path": "/audio/clip.wav",
  "reference_transcript": "Expected transcription here"
}

Formato delle annotazioni in uscita

Output di base

json

{
  "id": "doc_001",
  "text": "Great product!",
  "annotations": {
    "sentiment": "Positive",
    "confidence": 5
  },
  "annotator": "user123",
  "timestamp": "2024-11-05T10:30:00Z"
}

Annotazioni a span

json

{
  "id": "ner_001",
  "text": "Apple CEO Tim Cook visited Paris.",
  "annotations": {
    "entities": [
      {"start": 0, "end": 5, "label": "ORG", "text": "Apple"},
      {"start": 10, "end": 18, "label": "PERSON", "text": "Tim Cook"},
      {"start": 27, "end": 32, "label": "LOC", "text": "Paris"}
    ]
  }
}

Più annotatori

json

{
  "id": "item_001",
  "text": "Sample text",
  "annotations": [
    {
      "annotator": "ann1",
      "labels": {"sentiment": "Positive"},
      "timestamp": "2024-11-05T10:00:00Z"
    },
    {
      "annotator": "ann2",
      "labels": {"sentiment": "Positive"},
      "timestamp": "2024-11-05T11:00:00Z"
    }
  ],
  "aggregated": {
    "sentiment": "Positive",
    "agreement": 1.0
  }
}

Riferimento della configurazione

yaml

data_files:
  - data/items.json
 
item_properties:
  id_key: id
  text_key: text
  image_key: image_path
  audio_key: audio_path

Qualche abitudine che risparmia grattacapi

Dai a ogni elemento un ID univoco: ti servirà nel momento in cui dovrai risalire dall'annotazione alla sua origine. Passa a JSONL quando il file diventa grande. Convalida il JSON prima di caricarlo, perché una virgola di troppo fallisce tardi e in modo poco chiaro. Tieniti i metadati come origine, data e autore anche se ora non li usi, perché rendono il debug molto più semplice in seguito. E scegli dei nomi per i campi e mantienili, così gli script a valle non hanno bisogno di un caso speciale per ogni file.

Per l'elenco completo delle chiavi supportate, vedi la documentazione sui formati dei dati.

Documentazione completa sui formati dei dati su Formati di Dati.