Name: Potato
Author: Potato

Potato liest Eingabedaten und schreibt Annotationen in JSON und JSONL. Viel dahinter steckt nicht, aber die Details zählen, sobald dein Datensatz wächst oder du Text mit Bildern und Audio mischst. Dieser Leitfaden geht die Formate durch, mit einem lauffähigen Beispiel für jeden Datentyp.

Formate für Eingabedaten

JSON Lines (JSONL)

Ein JSON-Objekt pro Zeile. Nach diesem Format greifst du zuerst:

json

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

Warum JSONL: Du kannst zeilenweise streamen, statt die ganze Datei in den Speicher zu laden, ein neuer Datensatz ist bloß eine zusätzliche Zeile, und eine kaputte Zeile reißt nicht den Rest der Datei mit.

JSON-Array

Ein normales JSON-Array:

json

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

Konfiguration:

yaml

data_files:
  - data/items.json

Daten für Textannotation

Einfacher Text

json

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

Mit Metadaten

json

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

Mit Vorannotationen

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

Konfiguration:

yaml

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

Daten für Bildannotation

Lokale Bilder

json

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

Bilder über eine URL

json

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

Mit Bounding Boxes

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

Konfiguration:

yaml

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

Daten für Audioannotation

Lokale Audiodateien

json

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

Mit Segmenten

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

Konfiguration:

yaml

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

Multimodale Daten

Text + Bild

json

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

Text + Audio

json

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

Format der ausgegebenen Annotationen

Einfache Ausgabe

json

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

Span-Annotationen

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

Mehrere Annotierende

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

Referenz zur Konfiguration

yaml

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

Ein paar Gewohnheiten, die Ärger ersparen

Gib jeder Instanz eine eindeutige ID; du brauchst sie in dem Moment, in dem du eine Annotation zurück zu ihrer Quelle verfolgen willst. Wechsle zu JSONL, sobald die Datei groß wird. Prüfe das JSON, bevor du es lädst, denn ein einzelnes verirrtes Komma fällt spät und schwer nachvollziehbar auf. Behalte Metadaten wie Quelle, Datum und Autor bei, auch wenn du sie gerade nicht brauchst, denn sie machen die Fehlersuche später viel einfacher. Und leg dich auf Feldnamen fest und bleib dabei, damit nachgelagerte Skripte nicht für jede Datei einen Sonderfall brauchen.

Die vollständige Liste der unterstützten Schlüssel steht in der Dokumentation zum Datenformat.

Vollständige Dokumentation zu den Datenformaten unter Datenformate.