Carregamento de Diretório de Dados

Em vez de especificar arquivos de dados individuais com data_files, você pode apontar o Potato para um diretório que contém seus arquivos de dados. Todos os arquivos suportados serão carregados automaticamente, com monitoramento ao vivo opcional de arquivos novos ou modificados.

Visão geral

Isso é útil quando:

• Você tem muitos arquivos de dados e não quer listá-los individualmente
• Você quer adicionar novos arquivos dinamicamente enquanto o servidor está em execução
• Você está recebendo dados de um processo externo que grava em um diretório compartilhado

Configuração

Uso básico (carregamento estático)

Para carregar todos os arquivos de um diretório na inicialização:

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

Monitoramento de diretório ao vivo

Para detectar e carregar automaticamente arquivos novos ou modificados enquanto o servidor está em execução:

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"

Opções de configuração

Formatos de arquivo suportados

O monitor de diretório suporta os mesmos formatos que data_files:

• JSON (.json) - Um objeto JSON por linha, ou um array JSON
• JSONL (.jsonl) - Formato JSON Lines, um objeto por linha
• CSV (.csv) - Valores separados por vírgula com linha de cabeçalho
• TSV (.tsv) - Valores separados por tabulação com linha de cabeçalho

Como funciona

Na inicialização

1. Todos os arquivos com extensões suportadas em data_directory são varridos
2. Cada arquivo é analisado de acordo com sua extensão
3. As instâncias são adicionadas à fila de anotação
4. Se watch_data_directory estiver habilitado, uma thread em segundo plano inicia o monitoramento

Durante a execução (quando o monitoramento está habilitado)

1. A cada watch_poll_interval segundos, o diretório é varrido
2. Novos arquivos são analisados e suas instâncias são adicionadas
3. Arquivos modificados são reanalisados:
   • Novas instâncias são adicionadas
   • Instâncias existentes são atualizadas (as anotações são preservadas)
4. Arquivos removidos: as instâncias permanecem no sistema (para preservar as anotações)

Exemplo de estrutura de diretório

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

Exemplos de arquivos de dados

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

Combinando com data_files

Você pode usar data_directory e 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

Atualizações de instâncias

Quando um arquivo é modificado com o monitoramento habilitado:

• Novas instâncias (novos IDs) são adicionadas à fila de anotação
• Instâncias existentes (mesmos IDs) são atualizadas, mas as anotações são preservadas
• Instâncias removidas permanecem no sistema para preservar as anotações

Isso significa que os anotadores não perderão seu trabalho se você atualizar um arquivo de dados.

Tratamento de erros

• Arquivos que falham na análise são registrados em log e ignorados (os demais arquivos ainda são carregados)
• id_key ausente em uma instância: essa instância é ignorada com um aviso
• text_key ausente em uma instância: a instância é carregada com um aviso
• Erros de permissão de diretório são registrados em log

Considerações de desempenho

• Intervalo de varredura: valores maiores reduzem o uso de CPU, mas atrasam a detecção de novos arquivos
• Diretórios grandes: os arquivos são varridos a cada intervalo; considere organizar os arquivos em subdiretórios
• Arquivos grandes: os arquivos são totalmente reanalisados quando modificados; considere usar arquivos de lote menores

Registro em log

O monitor de diretório registra sua atividade no nível 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

Habilite o registro em log DEBUG para ver os detalhes do processamento de cada arquivo.

Leitura adicional

• Formatos de Dados - Formatos de dados suportados
• Noções Básicas de Configuração - Configuração geral

Para detalhes de implementação, consulte a documentação de origem.