Daten aus einem Verzeichnis laden

Anstatt einzelne Datendateien mit data_files anzugeben, können Sie Potato auf ein Verzeichnis mit Ihren Datendateien verweisen. Alle unterstützten Dateien werden automatisch geladen, mit optionalem Live-Watching für neue oder geänderte Dateien.

Übersicht

Dies ist nützlich, wenn:

• Sie viele Datendateien haben und diese nicht einzeln auflisten möchten
• Sie neue Dateien dynamisch hinzufügen möchten, während der Server läuft
• Sie Daten von einem externen Prozess empfangen, der in ein gemeinsames Verzeichnis schreibt

Konfiguration

Grundlegende Verwendung (Statisches Laden)

Um beim Start alle Dateien aus einem Verzeichnis zu laden:

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

Live-Verzeichnisüberwachung

Um neue oder geänderte Dateien automatisch zu erkennen und zu laden, während der Server läuft:

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"

Konfigurationsoptionen

Unterstützte Dateiformate

Der Verzeichnisbeobachter unterstützt dieselben Formate wie data_files:

• JSON (.json) - Ein JSON-Objekt pro Zeile oder ein JSON-Array
• JSONL (.jsonl) - JSON Lines-Format, ein Objekt pro Zeile
• CSV (.csv) - Kommagetrennte Werte mit Kopfzeile
• TSV (.tsv) - Tabulatorgetrennte Werte mit Kopfzeile

Funktionsweise

Beim Start

1. Alle Dateien mit unterstützten Erweiterungen in data_directory werden gescannt
2. Jede Datei wird gemäß ihrer Erweiterung geparst
3. Instanzen werden der Annotationswarteschlange hinzugefügt
4. Wenn watch_data_directory aktiviert ist, startet ein Hintergrundthread mit der Überwachung

Während der Laufzeit (wenn Überwachung aktiviert ist)

1. Alle watch_poll_interval Sekunden wird das Verzeichnis gescannt
2. Neue Dateien werden geparst und ihre Instanzen hinzugefügt
3. Geänderte Dateien werden neu geparst:
   • Neue Instanzen werden hinzugefügt
   • Bestehende Instanzen werden aktualisiert (Annotationen bleiben erhalten)
4. Entfernte Dateien: Instanzen verbleiben im System (um Annotationen zu erhalten)

Beispiel-Verzeichnisstruktur

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

Beispiel-Datendateien

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

JSON-Format (batch_002.json)

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

CSV-Format (batch_003.csv)

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

Kombination mit data_files

Sie können sowohl data_directory als auch data_files zusammen verwenden:

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

Instanzaktualisierungen

Wenn eine Datei bei aktivierter Überwachung geändert wird:

• Neue Instanzen (neue IDs) werden der Annotationswarteschlange hinzugefügt
• Bestehende Instanzen (gleiche IDs) werden aktualisiert, aber Annotationen bleiben erhalten
• Entfernte Instanzen verbleiben im System, um Annotationen zu erhalten

Das bedeutet, dass Annotatoren ihre Arbeit nicht verlieren, wenn Sie eine Datendatei aktualisieren.

Fehlerbehandlung

• Dateien, die nicht geparst werden können, werden protokolliert und übersprungen (andere Dateien werden trotzdem geladen)
• Fehlender id_key in einer Instanz: Diese Instanz wird mit einer Warnung übersprungen
• Fehlender text_key in einer Instanz: Instanz wird mit einer Warnung geladen
• Verzeichnisberechtigungsfehler werden protokolliert

Leistungsüberlegungen

• Poll-Intervall: Höhere Werte reduzieren die CPU-Auslastung, verzögern aber die Erkennung neuer Dateien
• Große Verzeichnisse: Dateien werden bei jedem Intervall gescannt; erwägen Sie, Dateien in Unterverzeichnisse zu organisieren
• Große Dateien: Dateien werden bei Änderungen vollständig neu geparst; erwägen Sie kleinere Batch-Dateien

Protokollierung

Der Verzeichnisbeobachter protokolliert seine Aktivität auf INFO-Ebene:

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

Aktivieren Sie DEBUG-Protokollierung, um Details zur einzelnen Dateiverarbeitung zu sehen.

Weiterführende Informationen

• Data Formats - Unterstützte Datenformate
• Configuration Basics - Allgemeine Konfiguration

Implementierungsdetails finden Sie in der Quelldokumentation.