ディレクトリからのデータ読み込み

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）- 1行に1つのJSONオブジェクト、またはJSON配列
• JSONL（.jsonl）- JSON Lines形式、1行に1つのオブジェクト
• 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ログを有効にすると、個々のファイル処理の詳細を確認できます。

関連情報

• データ形式 - サポートされるデータ形式
• 設定の基本 - 一般的な設定

実装の詳細については、ソースドキュメントを参照してください。