Datenformate

Potato liest Annotationseingaben aus JSON-, JSON-Lines-, CSV- und TSV-Dateien. Diese Anleitung erklärt, wie Sie diese Daten strukturieren, welche Felder Potato aus jedem Datensatz benötigt und wo die Annotationen gespeichert werden.

Von der Eingabedatei zu exportierten Labels

Unterstützte Formate

JSON-Format

Das gängigste Format. Ihre Daten sollten ein Array von Objekten sein:

[
  {
    "id": "doc_001",
    "text": "This is the first document to annotate.",
    "source": "twitter",
    "date": "2024-01-15"
  },
  {
    "id": "doc_002",
    "text": "This is the second document.",
    "source": "reddit",
    "date": "2024-01-16"
  }
]

JSON-Lines-Format

Jede Zeile ist ein separates JSON-Objekt. Nützlich für große Datensätze:

{"id": "doc_001", "text": "First document"}
{"id": "doc_002", "text": "Second document"}
{"id": "doc_003", "text": "Third document"}

CSV/TSV-Format

Tabellarische Daten mit Kopfzeilen:

id,text,source
doc_001,"This is the first document",twitter
doc_002,"This is the second document",reddit

Konfiguration

Grundeinrichtung

Konfigurieren Sie Datendateien und Feldzuordnungen in Ihrer YAML-Datei:

data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id      # Field name for unique ID
  text_key: text  # Field name for content to annotate

Mehrere Datendateien

Mehrere Datenquellen kombinieren:

data_files:
  - "data/batch_1.json"
  - "data/batch_2.json"
  - "data/batch_3.jsonl"

Dateien werden der Reihe nach verarbeitet und zusammengeführt.

Datentypen

Einfacher Text

Einfacher Textinhalt:

{
  "id": "1",
  "text": "The product arrived quickly and works great!"
}

Mediendateien

Ein Bild-, Video- oder Audioelement nennt seine Datei in einem Feld des Datensatzes, und ein Feld in instance_display zeigt sie auf der Seite an:

{
  "id": "1",
  "image_path": "photo_001.jpg"
}

media_directory: media    # the default, relative to task_dir
 
instance_display:
  fields:
    - key: image_path
      type: image

Potato stellt die Dateien in media_directory unter /media/ bereit. Der Ordner ist standardmäßig media/ unterhalb von task_dir, und ein absoluter Pfad lässt ihn auf einen beliebigen Ordner des Rechners zeigen. In einem Medien-Anzeigefeld (z. B. image, video, audio, pdf) wird ein bloßer Dateiname wie photo_001.jpg zu /media/photo_001.jpg, wenn die Datei in diesem Ordner liegt, und eine vollständige URL wird unverändert verwendet. item_properties.image_key bringt kein Bild auf die Seite. Der Schlüssel teilt der AI-Unterstützung und der Duplikaterkennung mit, welches Feld das Bild enthält.

Dialog/Listen

Ein text-Feld, das eine JSON-Liste enthält, wird mit einem Element pro Zeile dargestellt, weil sich vertikales Lesen für einen Dialog eignet. Setzen Sie list_as_text.horizontal, um die Elemente für einen paarweisen Vergleich nebeneinander anzuordnen:

{
  "id": "1",
  "text": ["Option A", "Option B", "Option C"]
}

Textpaare

Ein text-Feld, das ein JSON-Objekt enthält, wird von dem Anzeigetyp gerendert, den die Konfiguration deklariert (conversation_tree, web_agent_trace und ähnliche). Ist kein Anzeigetyp deklariert, erscheint es als formatiertes JSON. Deklarieren Sie für eine Vergleichsaufgabe daher einen:

{
  "id": "pair_001",
  "text": {
    "A": "Response from Model A",
    "B": "Response from Model B"
  }
}

HTML-Dateien

Legen Sie die .html-Dateien in einem Ordner unter task_dir ab und verweisen Sie im normalen text-Feld darauf, da Potato keine eigene Element-Property für HTML hat. Die mitgelieferte Aufgabe examples/advanced/html-annotation bettet jede Datei ein:

{
  "id": "1",
  "text": "<embed width=\"1020\" height=\"440\" src=\"data/html_data/1.html\" type=\"text/html\">"
}

Kontextuelle Annotation

Kontext neben dem Haupttext einschließen:

{
  "id": "1",
  "text": "This is great!",
  "context": "Previous message: How do you like the new feature?"
}

Felder außer der ID und dem Text gelangen über kwargs auf die Seite. Dort werden die zusätzlichen Schlüssel aufgeführt, die aus jedem Element übernommen werden:

item_properties:
  id_key: id
  text_key: text
  kwargs:
    - context

Anzeigeeinstellungen

Optionen für die Listendarstellung

Steuern Sie, wie ein Feld mit einer Liste als Wert dargestellt wird. Der Schlüssel akzeptiert drei Unterschlüssel, und list_as_text: true aktiviert ihn mit den Standardwerten:

list_as_text:
  # Prefix each item so an annotator can refer to one by name.
  text_list_prefix_type: alphabet   # alphabet, number, bullet, or none
 
  # Side-by-side suits a pairwise comparison. The default is vertical.
  horizontal: true
 
  # Shade alternate turns, which keeps a long dialogue readable.
  alternating_shading: true

HTML-Inhalt

Markup in einem text-Feld wird ohne Konfigurationsschlüssel gerendert. Potato bereinigt es, statt es zu escapen. Tags auf einer Allowlist (<b>, <i>, <span> und ähnliche) werden zu Formatierung, während <script> und alles, was nicht auf der Liste steht, escaped und damit wirkungslos wird. Span-Hervorhebungen werden als Markup in das Element eingefügt, deshalb kommt es nicht in Frage, das ganze Feld zu escapen.

{
  "id": "1",
  "text": "<p>This is <strong>formatted</strong> text.</p>"
}

Ausgabekonfiguration

Ausgabeverzeichnis

Angeben, wo Annotationen gespeichert werden:

output_annotation_dir: "output/"

Ausgabeformat

Annotationen werden immer als user_state.json-Dateien pro Benutzer gespeichert. export_annotation_format schreibt zusätzlich regelmäßig einen flachen Export nach <output_annotation_dir>/exports/<format>/, und diese Form eignet sich für die Analyse. Kein Exporter heißt json:

export_annotation_format: "jsonl"   # or csv, tsv, parquet, coco, conll_2003, ...

Führen Sie python -m potato.export --list-formats aus, um die vollständige Liste zu sehen.

Ausgabestruktur

Jede user_state.json enthält die Labels dieses Annotators, nach Instanz geordnet, wobei Spans getrennt erfasst werden:

{
  "user_id": "annotator_1",
  "instance_id_to_label_to_value": {
    "doc_001": {
      "sentiment": {"labels": {"positive": true}}
    }
  },
  "instance_id_to_span_to_value": {
    "doc_001": {
      "ner": [
        {"start": 0, "end": 5, "label": "PERSON", "text": "Alice"}
      ]
    }
  }
}

Spezielle Datentypen

Best-Worst Scaling

Für Rangordnungsaufgaben verwenden Sie durch Komma getrennte Elemente:

{
  "id": "1",
  "text": "Item A,Item B,Item C,Item D"
}

Benutzerdefinierte Argumente

Zusätzliche Felder für Anzeige oder Filterung einschließen:

{
  "id": "1",
  "text": "Document content",
  "category": "news",
  "priority": "high",
  "custom_field": "any value"
}

Datenbank-Backend

Verwenden Sie für große Datensätze MySQL:

database:
  type: mysql
  host: localhost
  port: 3306
  database: potato_db
  username: ${DB_USER}
  password: ${DB_PASSWORD}

Potato erstellt beim ersten Start automatisch die erforderlichen Tabellen.

Datenvalidierung

Potato validiert Ihre Daten beim Start:

• Fehlendes ID-Feld - Alle Elemente benötigen eindeutige Bezeichner
• Fehlendes Textfeld - Elemente benötigen zu annotierenden Inhalt
• Doppelte IDs - Alle IDs müssen eindeutig sein
• Datei nicht gefunden - Überprüfen Sie die Pfade der Datendateien

Vollständiges Beispiel

annotation_task_name: "Document Classification"
task_dir: "."
port: 8000
 
# Data configuration
data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id
  text_key: text
 
# Display settings
list_as_text:
  text_list_prefix_type: number
  horizontal: false
 
# Output
output_annotation_dir: "output/"
export_annotation_format: "jsonl"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "Select the document category"
    labels:
      - News
      - Opinion
      - Tutorial
      - Other
 
user_config:
  allow_all_users: true
  users: []

Bewährte Vorgehensweisen

1. Aussagekräftige IDs verwenden

Erleichtert Nachverfolgung und Fehlerbehebung:

{"id": "twitter_2024_001", "text": "..."}

2. Text prägnant halten

Lange Texte verlangsamen die Annotation. Erwägen Sie:

• Kürzung auf die wesentlichen Abschnitte
• Bereitstellung von Zusammenfassungen
• Verwendung von Scroll-Containern

3. Metadaten einschließen

Hilft bei der Filterung und Analyse:

{
  "id": "1",
  "text": "Content",
  "source": "twitter",
  "date": "2024-01-15",
  "language": "en"
}

4. Vor dem Laden validieren

Überprüfen Sie Ihre Daten offline:

import json
 
with open('data.json') as f:
    data = json.load(f)
 
# Check for required fields
for item in data:
    assert 'id' in item, f"Missing id: {item}"
    assert 'text' in item, f"Missing text: {item}"
 
# Check for duplicates
ids = [item['id'] for item in data]
assert len(ids) == len(set(ids)), "Duplicate IDs found"
 
print(f"Validated {len(data)} items")

5. Originaldaten sichern

Halten Sie Rohdaten für die Reproduzierbarkeit getrennt von den Annotationen.

6. JSON Lines für große Dateien verwenden

Speichereffizienter als JSON-Arrays:

# Convert JSON array to JSON Lines
cat data.json | jq -c '.[]' > data.jsonl

Weiterführende Informationen

• Datenverzeichnis laden - Aus Verzeichnissen mit Live-Überwachung laden
• Dialog-Annotation - Anzeige von Daten mit mehreren Elementen
• Exportformate - Optionen für Ausgabeformate

Implementierungsdetails finden Sie in der Quelldokumentation.