Formats de données

Potato lit les données d'annotation en entrée depuis des fichiers JSON, JSON Lines, CSV et TSV. Ce guide explique comment structurer ces données, quels champs Potato attend de chaque enregistrement et où les annotations sont enregistrées.

Du fichier d'entrée aux étiquettes exportées

Formats supportés

Format JSON

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

[
  {
    "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 :

{"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 :

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 :

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 :

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 :

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

Fichiers média

Un élément image, vidéo ou audio indique son fichier dans un champ de l'enregistrement, et un champ de instance_display l'affiche sur la page :

{
  "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 sert les fichiers de media_directory sous /media/. Par défaut, le dossier est media/ dans task_dir, et un chemin absolu le fait pointer vers un dossier situé n'importe où sur la machine. Dans un champ d'affichage de média (p. ex. image, video, audio, pdf), un simple nom de fichier comme photo_001.jpg devient /media/photo_001.jpg lorsque le fichier se trouve dans ce dossier, et une URL complète est utilisée telle qu'elle est écrite. item_properties.image_key n'affiche pas d'image sur la page. Cette clé indique au support IA et à la détection des doublons quel champ contient l'image.

Dialogues/Listes

Un champ text contenant une liste JSON est affiché avec un élément par ligne, car la lecture verticale convient à un dialogue. Définissez list_as_text.horizontal pour placer les éléments côte à côte dans une comparaison par paires :

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

Paires de texte

Un champ text contenant un objet JSON est rendu par le type d'affichage que déclare la configuration (conversation_tree, web_agent_trace et similaires). Si aucun type d'affichage n'est déclaré, il s'affiche en JSON formaté ; déclarez-en donc un pour une tâche de comparaison :

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

Fichiers HTML

Placez les fichiers .html dans un dossier sous task_dir et pointez vers eux depuis le champ text habituel, car Potato n'a pas de propriété d'élément distincte pour le HTML. La tâche fournie examples/advanced/html-annotation intègre chacun d'eux :

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

Annotation contextuelle

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

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

Les champs autres que l'id et le texte parviennent à la page via kwargs, qui nomme les clés supplémentaires à reprendre de chaque élément :

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

Configuration de l'affichage

Options d'affichage des listes

Contrôlez la disposition d'un champ dont la valeur est une liste. La clé accepte trois sous-clés, et list_as_text: true l'active avec les valeurs par défaut :

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

Contenu HTML

Le balisage dans un champ text est rendu sans aucune clé de configuration. Potato le nettoie au lieu de l'échapper : les balises d'une liste autorisée (<b>, <i>, <span> et similaires) deviennent de la mise en forme, tandis que <script> et tout ce qui ne figure pas sur la liste est échappé et reste inerte. Les surlignages de spans sont injectés dans l'élément sous forme de balisage, c'est pourquoi échapper tout le champ n'est pas envisageable.

{
  "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 :

output_annotation_dir: "output/"

Format de sortie

Les annotations sont toujours conservées dans des fichiers user_state.json par utilisateur. export_annotation_format écrit en plus un export plat périodique dans <output_annotation_dir>/exports/<format>/, qui est la forme à utiliser pour l'analyse. Aucun exportateur ne s'appelle json :

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

Exécutez python -m potato.export --list-formats pour obtenir le registre complet.

Structure de la sortie

Chaque user_state.json contient les étiquettes de cet annotateur indexées par instance, les spans étant enregistrés séparément :

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

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 :

{
  "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 :

{
  "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 :

database:
  type: mysql
  host: localhost
  port: 3306
  database: potato_db
  username: ${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

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: []

Bonnes pratiques

1. Utilisez des identifiants significatifs

Facilite le suivi et le débogage :

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

2. Gardez le texte concis

Les textes longs ralentissent l'annotation. Envisagez de :

• 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 :

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

4. Validez avant le chargement

Vérifiez vos données hors ligne :

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 :

# 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 à plusieurs éléments
• Formats d'exportation - Options de format de sortie

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