从目录加载数据

除了使用 data_files 指定单个数据文件外，你还可以将 Potato 指向一个包含数据文件的目录。所有支持的文件将自动加载，并可选择实时监控新增或修改的文件。

概述

这在以下情况下非常有用：

• 你有很多数据文件，不想逐个列出
• 你希望在服务器运行时动态添加新文件
• 你正在从写入共享目录的外部进程接收数据

配置

基本用法（静态加载）

在启动时加载目录中的所有文件：

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

实时目录监控

在服务器运行时自动检测并加载新增或修改的文件：

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"

配置选项

支持的文件格式

目录监控器支持与 data_files 相同的格式：

• JSON（.json）- 每行一个 JSON 对象，或 JSON 数组
• JSONL（.jsonl）- JSON Lines 格式，每行一个对象
• CSV（.csv）- 逗号分隔值，带标题行
• TSV（.tsv）- 制表符分隔值，带标题行

工作原理

启动时

1. 扫描 data_directory 中所有支持扩展名的文件
2. 根据扩展名解析每个文件
3. 将实例添加到标注队列
4. 如果启用了 watch_data_directory，启动后台线程进行监控

运行时（启用监控时）

1. 每隔 watch_poll_interval 秒扫描目录
2. 新文件被解析，其实例被添加
3. 修改的文件被重新解析：
   • 新实例被添加
   • 现有实例被更新（标注被保留）
4. 删除的文件：实例保留在系统中（以保留标注）

示例目录结构

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

示例数据文件

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

JSON 格式（batch_002.json）

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

CSV 格式（batch_003.csv）

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

与 data_files 组合使用

你可以同时使用 data_directory 和 data_files：

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

实例更新

当启用监控时文件被修改：

• 新实例（新 ID）被添加到标注队列
• 现有实例（相同 ID）被更新，但标注被保留
• 已删除实例保留在系统中以保留标注

这意味着如果你更新数据文件，标注者不会丢失他们的工作。

错误处理

• 解析失败的文件被记录并跳过（其他文件仍然加载）
• 实例中缺少 id_key：该实例被跳过并发出警告
• 实例中缺少 text_key：实例加载但发出警告
• 目录权限错误被记录

性能注意事项

• 轮询间隔：较高的值降低 CPU 使用率，但延迟新文件的检测
• 大型目录：每个间隔都会扫描文件；考虑将文件组织到子目录中
• 大型文件：修改时文件会被完全重新解析；考虑使用较小的批量文件

日志记录

目录监控器以 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

启用 DEBUG 日志可查看单个文件处理详情。

延伸阅读

• 数据格式 - 支持的数据格式
• 配置基础 - 通用配置

有关实现细节，请参阅源代码文档。