Skip to content

Progettare i formati dei dati per l'annotazione

Come strutturare i dati in ingresso (JSON, JSONL, CSV) per un progetto di annotazione, quali campi si aspetta Potato e come preparare un export pulito verso le pipeline di addestramento.

Una buona annotazione parte da dati in ingresso ben strutturati. Ogni elemento ha bisogno di un identificatore univoco stabile e del contenuto da etichettare; tutto il resto è contesto facoltativo. Farlo bene all'inizio evita ripartenze dolorose più avanti, perché le annotazioni sono legate agli ID degli elementi.

I formati di scambio più comuni sono JSON, JSON Lines (un oggetto per riga, ideale per dataset grandi) e CSV. Potato li legge tutti e tre. Per il riferimento completo vedi Formati dei dati.

Il minimo che serve a ogni elemento

  • Un ID univoco che non cambia mai. Le annotazioni sono salvate su questo ID, quindi se rinumeri gli elementi a metà progetto perdi il collegamento con le etichette già raccolte.
  • Il contenuto da annotare: un campo di testo, l'URL di un'immagine, il percorso di un audio, una trascrizione allineata nel tempo o una traccia strutturata.

Un file JSONL per un task testuale si presenta così:

json
{"id": "rev_001", "text": "The battery lasts all day. Highly recommend."}
{"id": "rev_002", "text": "Stopped working after a week."}

Indichi a Potato quali chiavi usare:

yaml
item_properties:
  id_key: id
  text_key: text
 
data_files:
  - "data/reviews.jsonl"

Porta con te il contesto, ma tienilo separato dalle etichette

Campi aggiuntivi come un URL di origine, un timestamp o il nome di un modello possono viaggiare insieme a ogni elemento ed essere mostrati agli annotatori senza diventare etichette. Dai loro nomi chiari, così l'export resterà leggibile a distanza di tempo.

Anche i file di trascrizione sono dati in ingresso

Se il tuo contenuto è parlato, non devi appiattirlo in un campo di testo prima di iniziare. Potato legge 21 formati di trascrizione e sottotitoli, tra cui Whisper e WhisperX JSON, Deepgram, AssemblyAI, AWS Transcribe, SRT, WebVTT, TTML, Praat TextGrid ed ELAN EAF. Un file di dati può puntare direttamente ai file scritti dal tuo strumento di ASR:

json
{"id": "int_001", "conversation": {"audio": "media/int_001.mp3",
                                   "transcript": "media/int_001.srt"}}

Il riconoscimento si basa sul contenuto del file e non sull'estensione, quindi la stessa trascrizione funziona sia incorporata sia come file affiancato. Vedi Formati di trascrizione per l'elenco completo e per il modello normalizzato dei turni in cui tutto viene convertito.

Pensa all'export prima di etichettare

Decidi presto come i dati etichettati alimenteranno la tua pipeline. Potato esporta in JSON, JSONL e CSV, e in formati nativi per il machine learning come CoNLL per il sequence labeling, Hugging Face Datasets, spaCy e COCO/YOLO per la visione. Scegliere subito il formato di destinazione ti dice quali campi e quale schema di ID adottare fin da ora. Vedi Esportare le annotazioni per il machine learning.

yaml
output_annotation_dir: "annotation_output/"
output_annotation_format: "jsonl"

Approfondimenti