Caricamento dati da una directory

Invece di specificare singoli file di dati con data_files, puoi indirizzare Potato verso una directory contenente i tuoi file di dati. Tutti i file supportati verranno caricati automaticamente, con monitoraggio live opzionale per file nuovi o modificati.

Panoramica

Questo è utile quando:

• Hai molti file di dati e non vuoi elencarli singolarmente
• Vuoi aggiungere dinamicamente nuovi file mentre il server è in esecuzione
• Stai ricevendo dati da un processo esterno che scrive in una directory condivisa

Configurazione

Uso di base (Caricamento statico)

Per caricare tutti i file da una directory all'avvio:

# Load all supported files from this directory
data_directory: "./data/incoming"
 
# data_files can be empty when using data_directory
data_files: []
 
# Required: item_properties must still be configured
item_properties:
  id_key: "id"
  text_key: "text"

Monitoraggio live della directory

Per rilevare e caricare automaticamente file nuovi o modificati mentre il server è in esecuzione:

data_directory: "./data/incoming"
data_files: []
 
# Enable live watching (default: false)
watch_data_directory: true
 
# Optional: how often to check for changes in seconds (default: 5.0)
watch_poll_interval: 10.0
 
item_properties:
  id_key: "id"
  text_key: "text"

Opzioni di configurazione

Formati di file supportati

Il monitor della directory supporta gli stessi formati di data_files:

• JSON (.json) - Un oggetto JSON per riga, o un array JSON
• JSONL (.jsonl) - Formato JSON Lines, un oggetto per riga
• CSV (.csv) - Valori separati da virgole con riga di intestazione
• TSV (.tsv) - Valori separati da tabulazione con riga di intestazione

Come funziona

All'avvio

1. Tutti i file con estensioni supportate in data_directory vengono scansionati
2. Ogni file viene analizzato in base alla sua estensione
3. Le istanze vengono aggiunte alla coda di annotazione
4. Se watch_data_directory è abilitato, un thread in background inizia il monitoraggio

Durante l'esecuzione (quando il monitoraggio è abilitato)

1. Ogni watch_poll_interval secondi, la directory viene scansionata
2. I nuovi file vengono analizzati e le loro istanze aggiunte
3. I file modificati vengono rianalizzati:
   • Le nuove istanze vengono aggiunte
   • Le istanze esistenti vengono aggiornate (le annotazioni sono preservate)
4. File rimossi: le istanze rimangono nel sistema (per preservare le annotazioni)

Struttura di directory di esempio

my_project/
├── configs/
│   └── config.yaml
└── data/
    └── incoming/
        ├── batch_001.jsonl
        ├── batch_002.jsonl
        └── new_data.json    # Added while server is running

File di dati di esempio

Formato JSONL (batch_001.jsonl)

{"id": "item_001", "text": "First document to annotate."}
{"id": "item_002", "text": "Second document to annotate."}
{"id": "item_003", "text": "Third document to annotate."}

Formato JSON (batch_002.json)

[
  {"id": "item_004", "text": "Fourth document."},
  {"id": "item_005", "text": "Fifth document."}
]

Formato CSV (batch_003.csv)

id,text,category
item_006,Sixth document to annotate.,news
item_007,Seventh document to annotate.,blog

Combinazione con data_files

Puoi usare sia data_directory che data_files insieme:

# Load specific files first
data_files:
  - "data/important_batch.jsonl"
 
# Then load everything from the directory
data_directory: "./data/incoming"
watch_data_directory: true

Aggiornamenti delle istanze

Quando un file viene modificato mentre il monitoraggio è abilitato:

• Nuove istanze (nuovi ID) vengono aggiunte alla coda di annotazione
• Istanze esistenti (stesso ID) vengono aggiornate, ma le annotazioni sono preservate
• Istanze rimosse rimangono nel sistema per preservare le annotazioni

Ciò significa che gli annotatori non perderanno il loro lavoro se aggiorni un file di dati.

Gestione degli errori

• I file che non riescono ad essere analizzati vengono registrati e saltati (gli altri file vengono comunque caricati)
• id_key mancante in un'istanza: quella istanza viene saltata con un avviso
• text_key mancante in un'istanza: l'istanza viene caricata con un avviso
• Gli errori di permesso della directory vengono registrati

Considerazioni sulle prestazioni

• Intervallo di polling: Valori più alti riducono l'uso della CPU ma ritardano il rilevamento di nuovi file
• Directory grandi: I file vengono scansionati ad ogni intervallo; considera di organizzare i file in sottodirectory
• File grandi: I file vengono completamente rianalizzati quando modificati; considera l'uso di file batch più piccoli

Registrazione

Il monitor della directory registra la sua attività al livello INFO:

INFO: Loaded 150 instances from data_directory: ./data/incoming
INFO: Directory watching enabled (poll interval: 5.0s)
INFO: Directory scan: 25 instances added, 0 updated
INFO: Directory watcher stopped

Abilita la registrazione DEBUG per vedere i dettagli dell'elaborazione dei singoli file.

Ulteriori letture

• Data Formats - Formati di dati supportati
• Configuration Basics - Configurazione generale

Per i dettagli di implementazione, consulta la documentazione sorgente.