Formatos de Dados

O Potato lê a entrada de anotação a partir de arquivos JSON, JSON Lines, CSV e TSV. Este guia explica como estruturar esses dados, quais campos o Potato precisa de cada registro e onde as anotações são gravadas.

Do arquivo de entrada aos rótulos exportados

Formatos Suportados

Formato JSON

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

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

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

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:

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:

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:

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

Arquivos de Mídia

Referencie imagens, vídeos ou áudio:

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

item_properties:
  id_key: id
  image_key: image_path

Diálogos/Listas

Um campo text que contém uma lista JSON é exibido com um item por linha, porque a leitura vertical combina com um diálogo. Defina list_as_text.horizontal para colocar os itens lado a lado em uma comparação par a par:

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

Pares de Texto

Um campo text que contém um objeto JSON é renderizado pelo tipo de exibição que a configuração declarar (conversation_tree, web_agent_trace e similares). Sem nenhum tipo de exibição declarado, ele aparece como JSON formatado, então declare um para uma tarefa de comparação:

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

Arquivos HTML

Mantenha os arquivos .html em uma pasta dentro de task_dir e aponte para eles a partir do campo text comum, já que o Potato não tem uma propriedade de item separada para HTML. A tarefa incluída examples/advanced/html-annotation incorpora cada um deles:

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

Anotação Contextual

Inclua contexto ao lado do texto principal:

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

Campos que não sejam o id e o texto chegam à página por meio de kwargs, que lista as chaves extras a serem trazidas de cada item:

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

Configuração de Exibição

Opções de Exibição de Listas

Controle como um campo cujo valor é uma lista é disposto. A chave aceita três subchaves, e list_as_text: true a ativa com os valores padrão:

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

Conteúdo HTML

Marcação em um campo text é renderizada sem nenhuma chave de configuração. O Potato a sanitiza em vez de escapá-la, então as tags de uma lista de permissões (<b>, <i>, <span> e similares) viram formatação, enquanto <script> e tudo o que não está na lista é escapado e fica inerte. Os destaques de spans são inseridos no item como marcação, e por isso escapar o campo inteiro não é uma opção.

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

output_annotation_dir: "output/"

Formato de Saída

As anotações são sempre mantidas em arquivos user_state.json por usuário. Além disso, export_annotation_format grava periodicamente uma exportação plana em <output_annotation_dir>/exports/<format>/, que é a forma adequada para análise. Nenhum exportador se chama json:

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

Execute python -m potato.export --list-formats para ver o registro completo.

Estrutura da Saída

Cada user_state.json guarda os rótulos daquele anotador indexados por instância, com os spans registrados separadamente:

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

Tipos de Dados Especiais

Escalonamento Melhor-Pior

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

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

Argumentos Personalizados

Inclua campos extras para exibição ou filtragem:

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

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

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

Melhores Práticas

1. Use IDs Significativos

Facilita o rastreamento e a depuração:

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

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

4. Valide Antes de Carregar

Verifique seus dados 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. 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:

# 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.