Chargement depuis un dossier de données

Plutôt que de lister les fichiers un par un avec data_files, vous pouvez indiquer à Potato un dossier contenant vos données. Tous les fichiers pris en charge y seront chargés automatiquement, avec une surveillance facultative des fichiers ajoutés ou modifiés.

Vue d'ensemble

C'est utile quand :

• Vous avez beaucoup de fichiers de données et ne voulez pas tous les énumérer
• Vous voulez ajouter de nouveaux fichiers pendant que le serveur tourne
• Vos données arrivent d'un processus externe qui écrit dans un dossier partagé

Configuration

Utilisation de base (chargement statique)

Pour charger tous les fichiers d'un dossier au démarrage :

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

Surveillance en direct du dossier

Pour détecter et charger automatiquement les fichiers ajoutés ou modifiés pendant que le serveur tourne :

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"

Options de configuration

Formats de fichiers pris en charge

Le surveillant de dossier accepte les mêmes formats que data_files :

• JSON (.json) - Un objet JSON par ligne, ou un tableau JSON
• JSONL (.jsonl) - Format JSON Lines, un objet par ligne
• CSV (.csv) - Valeurs séparées par des virgules avec ligne d'en-tête
• TSV (.tsv) - Valeurs séparées par des tabulations avec ligne d'en-tête

Fonctionnement

Au démarrage

1. Tous les fichiers du dossier data_directory ayant une extension prise en charge sont parcourus
2. Chaque fichier est analysé selon son extension
3. Les instances sont ajoutées à la file d'annotation
4. Si watch_data_directory est activé, un fil d'exécution en arrière-plan démarre la surveillance

Pendant l'exécution (si la surveillance est activée)

1. Toutes les watch_poll_interval secondes, le dossier est parcouru
2. Les nouveaux fichiers sont analysés et leurs instances ajoutées
3. Les fichiers modifiés sont réanalysés :
   • Les nouvelles instances sont ajoutées
   • Les instances existantes sont mises à jour (les annotations sont conservées)
4. Fichiers supprimés : les instances restent dans le système (pour préserver les annotations)

Exemple d'arborescence

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

Exemples de fichiers de données

Format 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."}

Format JSON (batch_002.json)

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

Format CSV (batch_003.csv)

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

Combiner avec data_files

Vous pouvez utiliser data_directory et data_files ensemble :

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

Mise à jour des instances

Quand un fichier est modifié alors que la surveillance est active :

• Les nouvelles instances (identifiants inédits) sont ajoutées à la file d'annotation
• Les instances existantes (mêmes identifiants) sont mises à jour, mais les annotations sont conservées
• Les instances supprimées restent dans le système pour préserver les annotations

Les annotateurs ne perdent donc pas leur travail si vous mettez à jour un fichier de données.

Gestion des erreurs

• Les fichiers qui ne s'analysent pas sont journalisés et ignorés (les autres se chargent quand même)
• id_key absent d'une instance : cette instance est ignorée avec un avertissement
• text_key absent d'une instance : l'instance se charge avec un avertissement
• Les erreurs de permissions sur le dossier sont journalisées

Points de performance

• Intervalle de scrutation : une valeur élevée réduit la charge CPU mais retarde la détection des nouveaux fichiers
• Gros dossiers : les fichiers sont parcourus à chaque intervalle ; pensez à répartir les fichiers dans des sous-dossiers
• Gros fichiers : un fichier modifié est réanalysé entièrement ; préférez des lots plus petits

Journalisation

Le surveillant de dossier journalise son activité au niveau 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

Activez la journalisation DEBUG pour voir le détail du traitement de chaque fichier.

Pour aller plus loin

• Formats de données - Formats de données pris en charge
• Bases de la configuration - Configuration générale

Pour les détails d'implémentation, consultez la documentation source.