Carga de Datos desde un Directorio

En lugar de especificar archivos de datos individuales con data_files, puedes apuntar Potato a un directorio que contenga tus archivos de datos. Todos los archivos compatibles se cargarán automáticamente, con monitoreo en vivo opcional para archivos nuevos o modificados.

Descripción General

Esto es útil cuando:

• Tienes muchos archivos de datos y no quieres listarlos individualmente
• Quieres agregar nuevos archivos dinámicamente mientras el servidor está en ejecución
• Estás recibiendo datos de un proceso externo que escribe en un directorio compartido

Configuración

Uso Básico (Carga Estática)

Para cargar todos los archivos de un directorio al iniciar:

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

Monitoreo en Vivo del Directorio

Para detectar y cargar automáticamente archivos nuevos o modificados mientras el servidor está en ejecución:

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"

Opciones de Configuración

Formatos de Archivo Compatibles

El monitor de directorio admite los mismos formatos que data_files:

• JSON (.json) - Un objeto JSON por línea, o un arreglo JSON
• JSONL (.jsonl) - Formato JSON Lines, un objeto por línea
• CSV (.csv) - Valores separados por comas con fila de encabezado
• TSV (.tsv) - Valores separados por tabulaciones con fila de encabezado

Cómo Funciona

Al Iniciar

1. Se escanean todos los archivos con extensiones compatibles en data_directory
2. Cada archivo se analiza según su extensión
3. Las instancias se agregan a la cola de anotación
4. Si watch_data_directory está habilitado, un hilo en segundo plano comienza a monitorear

Durante la Ejecución (cuando el monitoreo está habilitado)

1. Cada watch_poll_interval segundos, se escanea el directorio
2. Los archivos nuevos se analizan y sus instancias se agregan
3. Los archivos modificados se vuelven a analizar:
   • Las instancias nuevas se agregan
   • Las instancias existentes se actualizan (las anotaciones se preservan)
4. Archivos eliminados: las instancias permanecen en el sistema (para preservar las anotaciones)

Ejemplo de Estructura de Directorio

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

Ejemplos de Archivos de Datos

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

Combinación con data_files

Puedes usar tanto data_directory como data_files juntos:

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

Actualización de Instancias

Cuando un archivo se modifica mientras el monitoreo está habilitado:

• Instancias nuevas (IDs nuevos) se agregan a la cola de anotación
• Instancias existentes (mismos IDs) se actualizan, pero las anotaciones se preservan
• Instancias eliminadas permanecen en el sistema para preservar las anotaciones

Esto significa que los anotadores no perderán su trabajo si actualizas un archivo de datos.

Manejo de Errores

• Los archivos que no se pueden analizar se registran en el log y se omiten (los demás archivos se cargan normalmente)
• Falta id_key en una instancia: esa instancia se omite con una advertencia
• Falta text_key en una instancia: la instancia se carga con una advertencia
• Los errores de permisos del directorio se registran en el log

Consideraciones de Rendimiento

• Intervalo de sondeo: Valores más altos reducen el uso de CPU pero retrasan la detección de nuevos archivos
• Directorios grandes: Los archivos se escanean en cada intervalo; considera organizar los archivos en subdirectorios
• Archivos grandes: Los archivos se vuelven a analizar completamente cuando se modifican; considera usar archivos de lote más pequeños

Registro de Actividad

El monitor de directorio registra su actividad a nivel 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

Habilita el registro DEBUG para ver los detalles del procesamiento de archivos individuales.

Lectura Adicional

• Formatos de datos - Formatos de datos compatibles
• Conceptos básicos de configuración - Configuración general

Para detalles de implementación, consulta la documentación fuente.