데이터 디렉터리 로딩

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 로깅을 활성화하십시오.

추가 자료

• 데이터 형식 - 지원되는 데이터 형식
• 구성 기초 - 일반 구성

구현 세부 사항은 원본 문서를 참조하십시오.