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.

Este guia leva você de uma instalação nova até a anotação de dados em menos de 5 minutos. Ele mostra como escrever uma tarefa por conta própria. A outra forma de começar é descrever o estudo a um agente de programação e deixar que o potato-skill o projete e construa, como explica o Início rápido com um agente de programação.

O Potato em cinco passos: instalar, configurar, iniciar o servidor, anotar no navegador e exportarO Potato em cinco passos

Pré-requisitos

  • Python 3.9 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 2.10.3 impresso na tela. A partir da versão 2.9, potato --version informa o mesmo número e acrescenta o commit quando você executa a partir de um checkout.

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. Aponte para um arquivo com a extensão correspondente e o Potato escolhe o leitor a partir dela.

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/"
 
# Also write a periodic flat export, because the per-user state files are
# awkward to analyze. No exporter is named "json", so use "jsonl".
export_annotation_format: "jsonl"
 
# 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 CLI de Pré-visualização. É 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 com -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 username. Digite qualquer coisa (por exemplo, alice) e clique em Continue, e você já 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, execute o CLI de exportação do Potato, descrito na documentação de exportação. Execute python -m potato.export --list-formats para ver todos os formatos que ele registra.

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.

Perguntas frequentes

As perguntas abaixo tratam da instalação do Potato, de como rodá-lo no Docker e de como verificar uma configuração antes que os anotadores a vejam.

Como instalar o Potato?

Instale o Potato a partir do PyPI com pip install potato-annotation, no Python 3.9 ou superior. Instalá-lo em um ambiente virtual mantém as dependências do Potato separadas do Python do seu sistema, e potato --version confirma a instalação exibindo o número da versão.

Dá para rodar o Potato no Docker?

Sim. O Potato publica uma imagem pré-construída, ghcr.io/davidjurgens/potato, no GitHub Container Registry. A pasta do seu projeto é montada no contêiner em /app e o servidor escuta na porta 7860 dentro dele, então uma única imagem atende a qualquer tarefa. Defina POTATO_SECRET_KEY para que as sessões dos anotadores sobrevivam a uma reinicialização. Implantando o Potato em um Servidor traz o comando docker run completo.

Como verificar uma configuração do Potato antes que os anotadores a vejam?

Execute potato validate config.yaml --strict, que verifica a configuração do mesmo jeito que o servidor faz na inicialização e transforma avisos, como uma chave não reconhecida, em falhas. Em seguida, potato preview config.yaml mostra o que a configuração declara e renderiza a interface em um navegador, para que você veja a tarefa como um anotador vai vê-la antes que alguém faça login.

E Agora?

Ferramentas e Utilitários

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