目錄資料載入

除了使用 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 日誌可檢視單個檔案處理詳情。

延伸閱讀

• 資料格式 - 支援的資料格式
• 配置基礎 - 通用配置

有關實現細節，請參閱原始碼文件。