Formatos de Dados

Formatos de entrada do Potato: texto, JSON, JSONL, CSV, imagens, áudio e vídeo. Saída para CoNLL, HuggingFace Datasets, spaCy, COCO, YOLO, Parquet e outros.

O Potato oferece suporte nativo a múltiplos formatos de dados. Este guia explica como estruturar seus dados para anotação.

Formatos Suportados

Formato	Extensão	Descrição
JSON	`.json`	Array de objetos
JSON Lines	`.jsonl`	Um objeto JSON por linha
CSV	`.csv`	Valores separados por vírgulas
TSV	`.tsv`	Valores separados por tabulações

Formato JSON

O formato mais comum. Seus dados devem ser um array de objetos:

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

Formato JSON Lines

Cada linha é um objeto JSON separado. Útil para grandes conjuntos de dados:

jsonl

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

Formato CSV/TSV

Dados tabulares com cabeçalhos:

csv

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

Configuração

Configuração Básica

Configure os arquivos de dados e os mapeamentos de campos no seu 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

Múltiplos Arquivos de Dados

Combine várias fontes de dados:

yaml

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

Os arquivos são processados em ordem e combinados.

Tipos de Dados

Texto Simples

Conteúdo de texto simples:

json

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

Arquivos de Mídia

Referencie imagens, vídeos ou áudio:

json

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

yaml

item_properties:
  id_key: id
  image_key: image_path

Diálogos/Listas

As listas são exibidas automaticamente na horizontal:

json

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

Pares de Texto

Para tarefas de comparação:

json

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

Arquivos HTML

Referencie arquivos HTML armazenados em pastas:

json

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

Anotação Contextual

Inclua contexto ao lado do texto 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

Configuração de Exibição

Opções de Exibição de Listas

Controle como listas e dicionários são exibidos:

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

Conteúdo HTML

Habilite a renderização de HTML no texto:

yaml

html_content: true

json

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

Configuração de Saída

Diretório de Saída

Especifique onde as anotações são salvas:

yaml

output_annotation_dir: "output/"

Formato de Saída

Escolha o formato de saída:

yaml

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

Estrutura da Saída

As anotações incluem o ID do documento e as respostas:

json

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

Tipos de Dados Especiais

Escalonamento Melhor-Pior

Para tarefas de ranqueamento, use itens separados por vírgulas:

json

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

Argumentos Personalizados

Inclua campos extras para exibição ou filtragem:

json

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

Backend de Banco de Dados

Para grandes conjuntos de dados, use MySQL:

yaml

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

O Potato cria automaticamente as tabelas necessárias na primeira inicialização.

Validação de Dados

O Potato valida seus dados na inicialização:

Campo de ID ausente - Todos os itens precisam de identificadores únicos
Campo de texto ausente - Os itens precisam de conteúdo para anotar
IDs duplicados - Todos os IDs devem ser únicos
Arquivo não encontrado - Verifique os caminhos dos arquivos de dados

Exemplo Completo

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

Melhores Práticas

1. Use IDs Significativos

Facilita o rastreamento e a depuração:

json

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

2. Mantenha o Texto Conciso

Textos longos tornam a anotação mais lenta. Considere:

Truncar para as partes essenciais
Fornecer resumos
Usar contêineres com rolagem

3. Inclua Metadados

Ajuda na filtragem e na análise:

json

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

4. Valide Antes de Carregar

Verifique seus dados offline:

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. Faça Backup dos Dados Originais

Mantenha os dados brutos separados das anotações para garantir a reprodutibilidade.

6. Use JSON Lines para Arquivos Grandes

Mais eficiente em memória do que arrays JSON:

bash

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

Leitura Complementar

Carregamento por Diretório de Dados - Carregue a partir de diretórios com monitoramento em tempo real
Anotação de Diálogos - Exibição de dados com múltiplos itens
Formatos de Exportação - Opções de formato de saída

Para detalhes de implementação, consulte a documentação fonte.