Desenvolvimento local

Instale e execute o Potato localmente para desenvolvimento e testes. Aborda a instalação via pip, a configuração, a inicialização do servidor e a depuração de problemas comuns de inicialização.

Coloque o Potato em execução na sua máquina local para desenvolvimento e testes.

Pré-requisitos

Python 3.9 ou superior
Gerenciador de pacotes pip
Git (opcional, para clonar exemplos)

Instalação

Usando pip (recomendado)

bash

pip install potato-annotation

A partir do código-fonte

bash

git clone https://github.com/davidjurgens/potato.git
cd potato
pip install -e .

Com dependências opcionais

bash

# Local speech-to-text and diarization for transcript projects
pip install "potato-annotation[transcribe]"
 
# Hosted model providers for AI support and active learning
pip install "potato-annotation[ai]"
 
# Everything except the multi-gigabyte server-side vision stack
pip install "potato-annotation[all]"

Coloque o extra entre aspas para que o shell não interprete os colchetes como um padrão glob. all deixa vision de fora de propósito, porque esse grupo instala o torch e nada na experiência padrão precisa dele.

Início rápido

1. Crie um arquivo de configuração

Crie config.yaml:

yaml

annotation_task_name: "My First Annotation Task"
task_dir: "."
port: 8000
 
data_files:
  - data.json
 
item_properties:
  id_key: id
  text_key: text
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment?"
    labels:
      - Positive
      - Negative
      - Neutral
 
output_annotation_dir: "annotations/"

task_dir é a raiz contra a qual todos os outros caminhos relativos são resolvidos, e o Potato se recusa a ler fora dela. Defini-la como . mantém a configuração, o arquivo de dados e o diretório de saída em uma única pasta, e é isso que permite mover o projeto para um servidor depois.

2. Prepare dados de exemplo

Crie data.json:

json

[
  {"id": "1", "text": "I love this product!"},
  {"id": "2", "text": "This is terrible."},
  {"id": "3", "text": "It's okay, nothing special."}
]

3. Inicie o servidor

bash

potato start config.yaml

4. Acesse a interface

Abra seu navegador em http://localhost:8000

Modo de desenvolvimento

Modo de depuração

O modo de depuração ativa o log detalhado, desliga o tempo limite de inatividade da sessão e abre as páginas de administração sem chave para requisições vindas da sua própria máquina. A página de login continua, e --debug-phase (abaixo) a pula:

bash

potato start config.yaml --debug

Nunca ative o modo de depuração em um servidor implantado. Um túnel ou proxy reverso na mesma máquina que não adiciona nenhum cabeçalho de encaminhamento faz todo chamador parecer local, e --debug-phase faz todo visitante entrar como o mesmo debug_user. As versões 2.8.2 a 2.11.0 do Potato se recusam a iniciar em modo de depuração no endereço padrão 0.0.0.0, então nessas versões adicione --host 127.0.0.1.

Log de depuração

Escolha qual lado da aplicação gera os logs:

bash

potato start config.yaml --debug-log server

Os valores aceitos são all, ui, server e none. Use ui quando a página de anotação se comportar de forma estranha e server quando um item não carregar.

Saída detalhada

Veja toda a atividade do servidor:

bash

potato start config.yaml --verbose

Pular para uma fase

Com --debug ativado, pule o login e vá direto para a fase em que você está trabalhando em vez de passar pelo consentimento e pelas instruções a cada reinício:

bash

potato start config.yaml --debug --debug-phase annotation

Estrutura de diretórios

Layout de projeto recomendado:

text

my-annotation-project/
├── config.yaml           # Main configuration, inside task_dir
├── data/
│   ├── training.json     # Practice items for the training phase
│   └── main.json         # Annotation data
├── annotations/          # output_annotation_dir
├── media/                # media_directory, served at /media/
└── templates/            # site_dir, if you override the default templates

Apenas config.yaml e o arquivo de dados são obrigatórios. O Potato traz seus próprios templates, então defina site_dir e adicione uma pasta templates/ somente quando for substituí-los, e aponte site_file para um arquivo específico com o qual renderizar a página de anotação.

Testando sua configuração

Validar a configuração

Verifique a configuração do mesmo jeito que o servidor a verifica na inicialização, antes de gastar uma inicialização com ela:

bash

potato validate config.yaml

Adicione --strict para que avisos, como uma chave não reconhecida, façam a execução falhar em vez de serem impressos e deixarem passar.

Modo de pré-visualização

Mostre o que uma configuração declara e renderize-a em um navegador sem iniciar um servidor completo:

bash

potato preview config.yaml

Capturas de tela precisam do extra do navegador headless, pip install "potato-annotation[preview]":

bash

potato preview config.yaml --screenshot preview.png

Problemas comuns

Porta já em uso

bash

# Use a different port
potato start config.yaml -p 8080

Ou defina a porta em config.yaml, que a opção -p então sobrescreve:

yaml

port: 8080

Arquivo de dados não encontrado

Garanta que os caminhos sejam relativos à localização do arquivo de configuração:

yaml

# If data is in a subdirectory
data_files:
  - data/main.json

Os caminhos são resolvidos contra task_dir, e o Potato se recusa a carregar um arquivo fora dele, então mova os dados para dentro do diretório da tarefa em vez de apontar para um caminho absoluto em outro lugar da máquina.

Permissão negada

Verifique as permissões dos arquivos:

bash

chmod 755 annotations/
chmod 644 data/*.json

Vários usuários localmente

Para testar cenários multiusuário:

yaml

user_config:
  allow_all_users: true
 
login:
  type: url_direct
  url_argument: user_id

url_direct lê o nome de usuário diretamente da URL e não pede senha, então você pode abrir dois perfis de navegador e anotar como duas pessoas sem registrar contas:

http://localhost:8000/?user_id=annotator1
http://localhost:8000/?user_id=annotator2

Redefinir anotações

O Potato grava um diretório por anotador dentro de output_annotation_dir, cada um com o user_state.json daquela pessoa:

bash

# Remove one annotator's work
rm -rf annotations/annotator1
 
# Or clear every annotator
rm -rf annotations/*
 
# Restart server
potato start config.yaml

Remover o diretório de um usuário remove as atribuições dele junto com as respostas, então uma nova execução atribui os itens novamente do zero.

Variáveis de ambiente

Configure via ambiente:

bash

# Keeps sessions valid across restarts; required for OAuth
export POTATO_SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
 
# Fixes the shared admin key instead of letting Potato generate one per task
export POTATO_ADMIN_API_KEY="your-admin-key"
 
potato start config.yaml

Sem POTATO_SECRET_KEY, o Potato gera uma chave de assinatura aleatória a cada inicialização, o que desconecta todo mundo a cada reinício.

Usando com ambientes virtuais

venv

bash

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

Conda

bash

conda create -n potato python=3.10
conda activate potato
pip install potato-annotation

Integração com IDE

VS Code

Instale a extensão YAML para suporte ao arquivo de configuração:

json

// settings.json
{
  "yaml.schemas": {
    "https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json": "config.yaml"
  }
}

Configurações baixadas do playground já trazem esse esquema em uma linha # yaml-language-server:, então são validadas no editor sem essa configuração.

PyCharm

Crie uma configuração de execução:

Add → Python
Script: potato
Parâmetros: start config.yaml
Diretório de trabalho: o caminho do seu projeto

Próximos passos

Noções básicas de configuração - Conheça todas as opções de configuração
Formatos de dados - Entenda a estrutura dos dados
Configuração de produção - Faça a implantação para uso real