Formats de données

Formats de données supportés et comment structurer vos données d'annotation.

Formats de données

Potato prend en charge plusieurs formats de données nativement. Ce guide explique comment structurer vos données pour l'annotation.

Formats supportés

Format	Extension	Description
JSON	`.json`	Tableau d'objets
JSON Lines	`.jsonl`	Un objet JSON par ligne
CSV	`.csv`	Valeurs séparées par des virgules
TSV	`.tsv`	Valeurs séparées par des tabulations

Format JSON

Le format le plus courant. Vos données doivent être un tableau d'objets :

json

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

Format JSON Lines

Chaque ligne est un objet JSON séparé. Utile pour les grands ensembles de données :

jsonl

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

Format CSV/TSV

Données tabulaires avec en-têtes :

csv

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

Configuration

Configuration de base

Configurez les fichiers de données et les correspondances de champs dans votre YAML :

yaml

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

Fichiers de données multiples

Combinez plusieurs sources de données :

yaml

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

Les fichiers sont traités dans l'ordre et combinés.

Types de données

Texte brut

Contenu textuel simple :

json

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

Fichiers média

Référencez des images, vidéos ou audio :

json

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

yaml

item_properties:
  id_key: id
  image_key: image_path

Dialogues/Listes

Les listes sont automatiquement affichées horizontalement :

json

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

Paires de texte

Pour les tâches de comparaison :

json

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

Fichiers HTML

Référencez des fichiers HTML stockés dans des dossiers :

json

{
  "id": "1",
  "html_file": "html/document_001.html"
}

Annotation contextuelle

Incluez du contexte aux côtés du texte principal :

json

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

yaml

item_properties:
  id_key: id
  text_key: text
  context_key: context

Configuration de l'affichage

Options d'affichage des listes

Contrôlez l'affichage des listes et dictionnaires :

yaml

list_as_text:
  # Add prefixes to items
  text_prefix: "A"  # A., B., C. (or "1" for 1., 2., 3.)
 
  # Display orientation
  horizontal: true  # Side-by-side (false for vertical)
 
  # Randomization
  randomize_values: true   # Shuffle list items
  randomize_keys: true     # Shuffle dictionary keys

Contenu HTML

Activez le rendu HTML dans le texte :

yaml

html_content: true

json

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

Configuration de la sortie

Répertoire de sortie

Spécifiez où les annotations sont sauvegardées :

yaml

output_annotation_dir: "output/"

Format de sortie

Choisissez le format de sortie :

yaml

output_annotation_format: "json"  # json, jsonl, csv, or tsv

Structure de la sortie

Les annotations incluent l'identifiant du document et les réponses :

json

{
  "id": "doc_001",
  "user": "annotator_1",
  "annotations": {
    "sentiment": "Positive",
    "confidence": 4
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Types de données spéciaux

Classement Best-Worst

Pour les tâches de classement, utilisez des éléments séparés par des virgules :

json

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

Arguments personnalisés

Incluez des champs supplémentaires pour l'affichage ou le filtrage :

json

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

Backend de base de données

Pour les grands ensembles de données, utilisez MySQL :

yaml

database:
  type: mysql
  host: localhost
  database: potato_db
  user: ${DB_USER}
  password: ${DB_PASSWORD}

Potato crée automatiquement les tables nécessaires au premier démarrage.

Validation des données

Potato valide vos données au démarrage :

Champ ID manquant - Tous les éléments nécessitent des identifiants uniques
Champ texte manquant - Les éléments nécessitent du contenu à annoter
Identifiants en double - Tous les identifiants doivent être uniques
Fichier introuvable - Vérifiez les chemins des fichiers de données

Exemple complet

yaml

task_name: "Document Classification"
task_dir: "."
port: 8000
 
# Data configuration
data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id
  text_key: text
  context_key: metadata
 
# Display settings
list_as_text:
  text_prefix: "1"
  horizontal: false
 
# Output
output_annotation_dir: "output/"
output_annotation_format: "json"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "Select the document category"
    labels:
      - News
      - Opinion
      - Tutorial
      - Other
 
allow_all_users: true

Bonnes pratiques

1. Utilisez des identifiants significatifs

Facilite le suivi et le débogage :

json

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

2. Gardez le texte concis

Les textes longs ralentissent l'annotation. Considérez :

Tronquer aux parties essentielles
Fournir des résumés
Utiliser des conteneurs avec défilement

3. Incluez des métadonnées

Aide au filtrage et à l'analyse :

json

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

4. Validez avant le chargement

Vérifiez vos données hors ligne :

python

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. Sauvegardez les données originales

Conservez les données brutes séparément des annotations pour la reproductibilité.

6. Utilisez JSON Lines pour les gros fichiers

Plus efficace en mémoire que les tableaux JSON :

bash

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

Pour aller plus loin

Chargement par répertoire de données - Chargement depuis des répertoires avec surveillance en direct
Annotation de dialogues - Affichage de données multi-éléments
Formats d'exportation - Options de format de sortie

Pour les détails d'implémentation, voir la documentation source.