Potato는 입력 데이터를 읽고 어노테이션을 JSON과 JSONL로 씁니다. 별로 복잡하지 않지만, 데이터셋이 커지거나 텍스트에 이미지와 오디오를 섞기 시작하면 세부 사항이 중요해집니다. 이 가이드는 각 데이터 유형에 대한 동작하는 예시와 함께 형식들을 살펴봅니다.

입력 데이터 형식

JSON Lines (JSONL)

한 줄에 하나의 JSON 객체. 가장 먼저 손이 가야 할 형식입니다.

json

{"id": "001", "text": "First document text here."}
{"id": "002", "text": "Second document text here."}
{"id": "003", "text": "Third document text here."}

JSONL을 쓰는 이유: 파일 전체를 메모리에 올리는 대신 한 줄씩 스트리밍할 수 있고, 새 레코드를 추가하는 일은 줄 하나를 더하는 것뿐이며, 잘못된 줄 하나가 나머지 파일을 망가뜨리지 않습니다.

JSON 배열

표준 JSON 배열:

json

[
  {"id": "001", "text": "First document."},
  {"id": "002", "text": "Second document."},
  {"id": "003", "text": "Third document."}
]

구성:

yaml

data_files:
  - data/items.json

텍스트 어노테이션 데이터

기본 텍스트

json

{"id": "doc_001", "text": "The product quality exceeded my expectations."}

메타데이터 포함

json

{
  "id": "review_001",
  "text": "Great product, fast shipping!",
  "metadata": {
    "source": "amazon",
    "date": "2024-01-15",
    "author": "user123",
    "rating": 5
  }
}

사전 어노테이션 포함

json

{
  "id": "ner_001",
  "text": "Apple announced new products in Cupertino.",
  "pre_annotations": {
    "entities": [
      {"start": 0, "end": 5, "label": "ORG", "text": "Apple"},
      {"start": 31, "end": 40, "label": "LOC", "text": "Cupertino"}
    ]
  }
}

구성:

yaml

data_files:
  - data/texts.json
 
item_properties:
  id_key: id
  text_key: text

이미지 어노테이션 데이터

로컬 이미지

json

{
  "id": "img_001",
  "image_path": "/data/images/photo_001.jpg",
  "caption": "Street scene in Paris"
}

원격 이미지

json

{
  "id": "img_002",
  "image_url": "https://example.com/images/photo.jpg"
}

경계 상자 포함

json

{
  "id": "detection_001",
  "image_path": "/images/street.jpg",
  "pre_annotations": {
    "objects": [
      {"bbox": [100, 150, 200, 300], "label": "person"},
      {"bbox": [350, 200, 450, 280], "label": "car"}
    ]
  }
}

구성:

yaml

data_files:
  - data/images.json
 
item_properties:
  id_key: id
  image_key: image_path  # or image_url

오디오 어노테이션 데이터

로컬 오디오

json

{
  "id": "audio_001",
  "audio_path": "/data/audio/recording.wav",
  "duration": 45.5,
  "transcript": "Hello, how are you today?"
}

세그먼트 포함

json

{
  "id": "audio_002",
  "audio_path": "/audio/meeting.mp3",
  "segments": [
    {"start": 0.0, "end": 5.5, "speaker": "Speaker1"},
    {"start": 5.5, "end": 12.0, "speaker": "Speaker2"}
  ]
}

구성:

yaml

data_files:
  - data/audio.json
 
item_properties:
  audio_key: audio_path
  text_key: transcript

멀티모달 데이터

텍스트 + 이미지

json

{
  "id": "mm_001",
  "text": "What is shown in this image?",
  "image_path": "/images/scene.jpg"
}

텍스트 + 오디오

json

{
  "id": "mm_002",
  "text": "Transcribe this audio:",
  "audio_path": "/audio/clip.wav",
  "reference_transcript": "Expected transcription here"
}

출력 어노테이션 형식

기본 출력

json

{
  "id": "doc_001",
  "text": "Great product!",
  "annotations": {
    "sentiment": "Positive",
    "confidence": 5
  },
  "annotator": "user123",
  "timestamp": "2024-11-05T10:30:00Z"
}

스팬 어노테이션

json

{
  "id": "ner_001",
  "text": "Apple CEO Tim Cook visited Paris.",
  "annotations": {
    "entities": [
      {"start": 0, "end": 5, "label": "ORG", "text": "Apple"},
      {"start": 10, "end": 18, "label": "PERSON", "text": "Tim Cook"},
      {"start": 27, "end": 32, "label": "LOC", "text": "Paris"}
    ]
  }
}

다중 어노테이터

json

{
  "id": "item_001",
  "text": "Sample text",
  "annotations": [
    {
      "annotator": "ann1",
      "labels": {"sentiment": "Positive"},
      "timestamp": "2024-11-05T10:00:00Z"
    },
    {
      "annotator": "ann2",
      "labels": {"sentiment": "Positive"},
      "timestamp": "2024-11-05T11:00:00Z"
    }
  ],
  "aggregated": {
    "sentiment": "Positive",
    "agreement": 1.0
  }
}

구성 레퍼런스

yaml

data_files:
  - data/items.json
 
item_properties:
  id_key: id
  text_key: text
  image_key: image_path
  audio_key: audio_path

골칫거리를 덜어주는 몇 가지 습관

모든 인스턴스에 고유한 ID를 부여하세요. 어노테이션을 출처까지 거슬러 추적해야 하는 순간 바로 필요해집니다. 파일이 커지면 JSONL을 쓰세요. 로드하기 전에 JSON을 검증하세요. 떠도는 쉼표 하나가 뒤늦게 헷갈리게 실패하기 때문입니다. 출처, 날짜, 작성자 같은 메타데이터는 지금 쓰지 않더라도 곁에 두세요. 나중에 디버깅이 훨씬 쉬워집니다. 그리고 필드 이름을 정해 일관되게 쓰세요. 그래야 다운스트림 스크립트가 파일마다 특수 처리를 두지 않아도 됩니다.

지원되는 키의 전체 목록은 데이터 형식 문서를 참고하세요.

전체 데이터 형식 문서는 /docs/core-concepts/data-formats에서 확인하세요.