Skip to content

Início Rápido

Coloque o Potato no ar em menos de 5 minutos. Instale via pip, escreva um config YAML, inicie o servidor e anote seu primeiro conjunto de dados — sem precisar programar.

Coloque o Potato em funcionamento em poucos passos. Este guia vai te deixar anotando dados em menos de 5 minutos.

Pré-requisitos

  • Python 3.7 ou superior
  • Gerenciador de pacotes pip
  • Um terminal

Instalação

Recomendamos instalar o Potato em um ambiente virtual para que ele não entre em conflito com o Python do seu sistema:

bash
python -m venv potato-env
source potato-env/bin/activate   # Windows: potato-env\Scripts\activate
pip install potato-annotation

Verifique a instalação:

bash
python -c "import potato; print(potato.__version__)"

Você deve ver uma versão como 2.4.4 impressa na tela. O Potato não oferece uma flag potato --version — a linha em Python é a verificação canônica.

Crie Seu Primeiro Projeto

1. Crie um diretório de projeto

bash
mkdir my-annotation-task
cd my-annotation-task

2. Crie seu arquivo de dados

Crie uma pasta data e um arquivo chamado data.json dentro dela:

bash
mkdir data
json
[
  {"id": "1", "text": "I love this product! It's amazing."},
  {"id": "2", "text": "This is the worst experience ever."},
  {"id": "3", "text": "It's okay, nothing special."}
]

O Potato também aceita .jsonl (um objeto JSON por linha), .csv e .tsv para data_files — basta apontar para um arquivo com a extensão correspondente.

3. Crie sua configuração

Crie um arquivo chamado config.yaml no diretório do seu projeto:

Sandbox de caminhos: Qualquer caminho relativo dentro da sua configuração (como data_files ou output_annotation_dir) é resolvido em relação ao task_dir e deve permanecer dentro dele. Caminhos que resolvem para fora do task_dir são rejeitados para evitar travessia de diretórios.

yaml
annotation_task_name: "Sentiment Analysis"
 
# All relative paths below are resolved against task_dir.
task_dir: "."
 
# Data configuration
data_files:
  - "data/data.json"
 
# Tell Potato which fields in each record to use.
# id_key = unique identifier; text_key = the text shown to annotators.
item_properties:
  id_key: id
  text_key: text
 
# Where per-user annotation state is stored (relative to task_dir).
output_annotation_dir: "annotation_output/"
export_annotation_format: "json"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment of this text?"   # required for radio schemes
    labels:
      - Positive
      - Negative
      - Neutral
 
# Skip password authentication so anyone can log in with just a username.
require_password: false

Dica: Você pode validar sua configuração sem iniciar o servidor completo usando o Preview CLI. É a forma mais rápida de detectar erros de digitação antes de começar a anotar.

4. Inicie o servidor

bash
potato start config.yaml -p 8000

Forma longa equivalente:

bash
python -m potato start config.yaml -p 8000

Se a porta 8000 já estiver em uso, escolha outra: potato start config.yaml -p 8001.

Para parar o servidor, pressione Ctrl+C no terminal.

Primeira execução mais rápida: Adicione --debug para pular a tela de login por completo enquanto está experimentando: potato start config.yaml --debug.

5. Abra seu navegador

Acesse http://localhost:8000. Você verá uma tela de login com um único campo de nome de usuário — digite qualquer coisa (por exemplo, alice) e clique em Continue. Agora você está anotando.

Cada vez que você seleciona um rótulo e clica em Next, sua anotação é salva automaticamente. Não existe um botão de "salvar" separado.

Para Onde Vão Suas Anotações

O Potato grava o estado de cada usuário conforme você anota:

text
my-annotation-task/
├── config.yaml
├── data/
│   └── data.json
└── annotation_output/              # created automatically
    └── alice/
        └── user_state.json         # one folder per username

O user_state.json guarda o estado completo de anotação daquele usuário. Para gerar um arquivo consolidado e plano com todos os anotadores, use o CLI de exportação do Potato — consulte a documentação de exportação para mais detalhes.

Problemas Comuns na Primeira Execução

  • Address already in use — a porta 8000 está ocupada. Use -p 8001 (ou qualquer porta livre).
  • KeyError: 'description' — um esquema radio (ou similar) está sem o campo obrigatório description. Todo esquema precisa de um.
  • Path ... is outside the task directory — um caminho de data_files ou output_annotation_dir escapa do task_dir. Mantenha tudo dentro da pasta do projeto, ou defina task_dir como um caminho absoluto que os contenha.
  • A página de login mostra um campo de senha — você esqueceu de require_password: false, ou está em uma aba do navegador em cache. Reinicie o servidor e force a atualização da página.

E Agora?

Ferramentas e Utilitários

Quando estiver à vontade com o básico, confira estas ferramentas úteis: