Coloque seu estudo do Potato no ar

Para colocar um estudo do Potato no ar, você executa a tarefa em um computador que os anotadores alcançam por um endereço web, mantém as anotações seguras enquanto o estudo roda e baixa as anotações no final. Pedir à equipe de TI da sua instituição e clicar em um botão de implantação que um colega preparou são os dois caminhos que não exigem terminal da sua parte.

Implantar um estudo significa levar a tarefa do Potato que você montou do seu próprio computador para um servidor, um computador que fica ligado e conectado à internet. Os anotadores então abrem a tarefa em um navegador de qualquer lugar, e o Potato salva cada resposta no servidor conforme os anotadores trabalham. A prévia do Study Designer roda o Potato dentro do seu próprio navegador, e ninguém mais consegue acessar essa cópia. Um estudo montado no Designer ainda precisa de um dos caminhos abaixo.

Todo caminho parte da mesma pasta de projeto. No Study Designer, o botão Download project (.zip) salva o config.yaml (o arquivo que descreve a sua tarefa), um arquivo de dados de exemplo e um README. O arquivo de exemplo contém três itens de teste. Substitua o arquivo de exemplo pelos seus próprios itens antes de implantar, no formato que Formatos de Dados descreve.

Escolhendo um caminho

Os caminhos diferem em quem faz o trabalho técnico, no custo do servidor e em quanto tempo o estudo pode ficar no ar. Os custos abaixo vêm das tabelas de preços dos hosts e das estimativas do próprio Potato em 2026-11-04, e as esperas são referências aproximadas, e não medições:

Se você tem dúvida, comece pela sua equipe de TI. Um servidor dentro da sua instituição mantém os dados em equipamentos que a instituição já administra, e a equipe de TI pode assumir as atualizações de segurança e os backups.

Peça à equipe de TI ou de computação de pesquisa

Muitas universidades e hospitais mantêm um serviço de computação de pesquisa que hospeda aplicações web para estudos. Para uma equipe assim, o Potato é uma aplicação web comum, e a equipe pode partir de um resumo de uma página sobre o que o Potato precisa.

1. Baixe o projeto no Study Designer e substitua o arquivo de dados de exemplo pelos seus itens.
2. Envie à sua equipe de TI a pasta do projeto e um link para Requisitos de servidor do Potato para a sua equipe de TI.
3. Diga à equipe quem são os seus anotadores, quantos vão participar e quanto tempo o estudo dura.
4. Diga como os anotadores devem entrar. Colegas com contas institucionais podem usar o login único (SSO), o login que a sua instituição já mantém, e anotadores externos podem usar nomes de usuário que você lista.
5. Diga se os itens ou as respostas contêm informações pessoais ou sensíveis e informe a aprovação ética sob a qual o estudo roda.
6. Peça à equipe o endereço web do estudo, a chave de administrador que abre o painel do administrador do Potato e um plano para os backups e para a entrega dos dados quando o estudo terminar.

Quando o endereço chegar, percorra Antes de convidar os anotadores antes de enviar o endereço a qualquer pessoa.

Clique em um botão de implantação preparado por um colega

Um botão de implantação é um link na página de um repositório de código que cria uma cópia de uma tarefa do Potato nos servidores de uma empresa de hospedagem, inteiramente por formulários no seu navegador. Um colega que usa git e um terminal cria o botão uma vez, a partir de um repositório que contém a pasta do seu projeto, com o comando potato deploy button. Executar o Potato localmente ou na nuvem é a página a enviar a esse colega.

O botão funciona com três hosts, que cobram de formas diferentes:

• Render executa o estudo em um plano gratuito, sem forma de pagamento. Um serviço gratuito do Render entra em repouso após 15 minutos sem visitantes e leva cerca de um minuto para acordar quando o próximo anotador chega.
• Heroku cobra $7 por mês pelo servidor que o botão cria. O Heroku exige uma conta verificada, em geral por cartão de crédito, antes de você poder criar um app.
• AWS executa um servidor Lightsail por $12 por mês. O botão da AWS lê a tarefa de um repositório público, de modo que o botão da AWS serve apenas para itens que possam ser públicos.

O Render e o Heroku apagam o disco do servidor sempre que o servidor reinicia. Por isso, o botão copia as anotações a cada cinco minutos para um conjunto de dados privado no Hugging Face, um site para compartilhar dados e modelos, e copia as anotações de volta sempre que o servidor inicia. Você dá o nome a esse conjunto de dados quando clica, e o conjunto de dados pertence à sua conta.

Antes de clicar, reúna três coisas:

• uma conta no host, Render ou Heroku;
• uma conta gratuita no Hugging Face, com um token de acesso que tenha permissão de escrita, criado em huggingface.co/settings/tokens; e
• acesso ao repositório, se o repositório for privado. O Heroku pede que você vincule a sua conta do GitHub para um repositório privado.

Depois, implante:

1. Clique no botão no README do repositório e entre no host.
2. Dê um nome ao app. O nome passa a fazer parte do endereço web do estudo.
3. Em POTATO_BACKUP_HF_REPO, digite um nome de conjunto de dados formado pelo seu nome de usuário do Hugging Face e por um nome para o estudo, como your-username/my-study-annotations. Quando o nome é novo, o Potato cria o conjunto de dados e o torna privado.
4. Cole o seu token do Hugging Face em HF_TOKEN. Deixe todos os outros campos com o valor que o botão preencheu.
5. Inicie a implantação e espere o host informar que o app está em execução. Abra o endereço web que o host mostra.
6. Encontre a chave de administrador, uma senha que o host gerou durante a implantação. No Heroku, a chave é a entrada POTATO_ADMIN_API_KEY na aba Settings do app, e no Render a mesma entrada fica na página Environment do serviço.
7. Abra o endereço do estudo com /admin no final e cole a chave de administrador para abrir o painel do administrador.

O repositório fixa a tarefa, os itens e a lista de anotadores. Conclua a tarefa antes de clicar, porque qualquer mudança posterior passa pelo colega que criou o botão. Mantenha o repositório privado, a menos que os itens possam ser públicos.

Compartilhe um link a partir do seu próprio computador

O seu próprio computador pode servir um piloto por uma tarde. Os anotadores abrem um link web temporário, as anotações vão para a pasta do seu projeto, e o link deixa de funcionar quando você fecha o comando. O caminho exige um terminal, um programa para digitar comandos, que é o Terminal no Mac (em Aplicativos, depois Utilitários) e o PowerShell no Windows (pesquise "PowerShell" no menu Iniciar).

1. Instale o Python 3.9 ou mais recente a partir de python.org/downloads. No Windows, o download é o Python install manager. No Mac, o download é o instalador do macOS.

2. Abra o terminal e instale o Potato. No Mac, digite:

   bashCopiar

   python3 -m pip install potato-annotation

   No Windows, digite:

   powershellCopiar

   py -m pip install potato-annotation

3. Descompacte o projeto que você baixou do Study Designer. No Mac, clique duas vezes no arquivo .zip. No Windows, clique com o botão direito no arquivo e escolha Extract All. Substitua o arquivo de dados de exemplo pelos seus itens.

4. Leve o terminal até a pasta do projeto e inicie o Potato. O nome da pasta abaixo é um exemplo, então use o nome da sua própria pasta. No Mac:

   bashCopiar

   cd ~/Downloads/my-task
   python3 -m potato start config.yaml

   No Windows:

   powershellCopiar

   cd $HOME\Downloads\my-task
   py -m potato start config.yaml

5. Abra http://localhost:8000 no seu navegador. Somente o seu computador alcança esse endereço. Pressione Ctrl-C no terminal para parar o Potato.

6. Para deixar outras pessoas entrarem, instale o cloudflared, um programa gratuito da Cloudflare que não exige conta. No Mac com o Homebrew, execute brew install cloudflared. No Windows, baixe o instalador do Windows na página de downloads da Cloudflare.

7. Execute potato share no lugar de potato start:

   bashCopiar

   python3 -m potato share config.yaml

   No Windows, digite py -m potato share config.yaml. O Potato mostra quem poderá entrar e pergunta antes de publicar qualquer coisa. Digite y, e o Potato mostra um link https:// para enviar aos seus anotadores.

O link funciona somente enquanto o comando roda. Fechar o terminal, suspender o computador ou trocar de rede encerra o link, e uma nova execução mostra um novo link. Algumas redes universitárias bloqueiam os links trycloudflare.com que o cloudflared cria. Se um anotador relatar um link bloqueado, potato share config.yaml --backend tailscale usa o Tailscale no lugar. O Tailscale exige uma conta gratuita. Se potato share informar No tunnel backend found, o Potato não encontrou o cloudflared no seu computador, e a mensagem lista os comandos de instalação.

Instalação cobre ambientes virtuais e recursos opcionais, e Executar o Potato localmente ou na nuvem cobre potato share com mais detalhes.

Alugue um servidor com um comando

potato deploy up aluga um servidor de uma empresa de nuvem, obtém um certificado HTTPS (o cadeado na barra de endereço do navegador), envia a pasta do seu projeto, inicia o estudo e mostra o endereço web. O comando exige a configuração de terminal dos passos 1 a 3 acima, uma conta na empresa de nuvem e um token de API, uma chave semelhante a uma senha que permite a um programa agir na sua conta. O guia de cada host cobre a conta e o token desde o início:

Todo host usa os mesmos dois comandos, e o guia de cada host informa o nome do provedor e o comando de instalação do host. O primeiro comando mostra o plano e o custo mensal e não cria nada, e o segundo cria o servidor depois que você confirma:

potato deploy up config.yaml --provider aws --dry-run
potato deploy up config.yaml --provider aws

O botão Duplicate this Space, do próprio Hugging Face, copia um Space no navegador, mas uma cópia de um Space do Potato mantém as configurações de backup do dono original e perde os segredos do original. Implante um Space do Potato com potato deploy up --provider huggingface.

Antes de convidar os anotadores

Percorra esta lista assim que o estudo tiver um endereço web, qualquer que seja o caminho escolhido:

• Decida quem pode entrar. A configuração fechada mais simples é uma lista de nomes de usuário. No Study Designer, desligue Allow All Users e adicione cada anotador em Authorized Users. Cada anotador listado escolhe uma senha ao se cadastrar na primeira visita, e o Potato recusa quem não está na lista. Envie o nome de usuário diretamente a cada anotador, porque a primeira pessoa a cadastrar um nome de usuário listado fica com essa conta. Para contas institucionais, veja Autenticação SSO e OAuth, e para trabalhadores de crowdsourcing, veja Integração com Crowdsourcing. Com Allow All Users ligado, qualquer pessoa que encontre o endereço pode criar uma conta. Mantenha essa configuração para demonstrações públicas.
• Saiba onde ficam as anotações. O Potato salva as respostas de cada anotador enquanto ele trabalha, em um arquivo chamado user_state.json dentro de uma pasta por anotador. As pastas ficam na pasta de saída que a configuração nomeia, que o Study Designer chama de output. No seu próprio computador, essa pasta fica dentro da pasta do projeto. Em uma implantação por botão, o conjunto de dados do Hugging Face guarda a cópia que sobrevive a uma reinicialização. Em um servidor alugado, potato deploy pull baixa a pasta. Em um servidor institucional, pergunte à TI como é feito o backup do servidor.
• Teste com um segundo navegador. Abra o endereço do estudo em uma janela privada, que é Anônima no Chrome, Janela Privada no Safari e no Firefox e InPrivate no Edge. Adicione à lista um nome de usuário como pilot-test, cadastre-se com esse nome e responda a três itens. Feche a janela, entre de novo e confira se as respostas continuam lá. Depois abra o painel do administrador e confira se o anotador de teste aparece. Experimente o endereço em um celular se os anotadores puderem trabalhar em celulares.
• Mantenha a chave de administrador em sigilo. A chave de administrador abre o painel do administrador em /admin. O painel mostra as respostas de todos os anotadores. No seu próprio computador, o Potato salva a chave em admin_api_key.txt, na pasta do projeto, na primeira vez que você abre /admin.
• Escreva o convite. Envie a cada anotador o endereço, o nome de usuário, quanto tempo a tarefa leva e a quem recorrer quando algo der errado.

Obtendo seus resultados

O painel do administrador baixa os resultados para o seu computador sem terminal. Abra /admin, digite a chave de administrador e escolha Publish Dataset. Em Target, escolha Local archive, defina Data format como CSV para uma planilha e clique em Publish. Quando o arquivo estiver pronto, clique em Download archive.

O arquivo contém as respostas de cada anotador, os itens e os rótulos combinados por voto majoritário. Um README no arquivo informa a contagem de rótulos e a concordância entre os anotadores. Os nomes dos anotadores são substituídos por A1, A2 e assim por diante, a menos que você desmarque Anonymize annotators. As respostas de questionários ficam fora do arquivo, a menos que você marque Include survey / phase responses, porque essas respostas podem conter informações pessoais.

Em um terminal, python -m potato.export grava as mesmas anotações em uma pasta, em qualquer um dos formatos de exportação do Potato:

python -m potato.export --config config.yaml --format csv --output results

Em um servidor criado com potato deploy up, potato deploy pull config.yaml baixa tudo o que o servidor coletou, inclusive os bancos de dados.

Encerrando o estudo para o servidor parar de custar dinheiro

Baixe os resultados antes de remover qualquer coisa e abra o download para conferir se as respostas do último anotador estão lá. Depois desligue o servidor do modo que o caminho exige:

• Seu próprio computador. Pressione Ctrl-C no terminal. Nada foi cobrado.
• Sua equipe de TI. Avise a equipe de que o estudo terminou, peça uma cópia da pasta de saída e pergunte por quanto tempo a cópia do servidor será mantida.
• Um botão de implantação. Exclua o app na aba Settings do app, no Heroku, ou exclua o serviço na página Settings dele, no Render. O conjunto de dados do Hugging Face guarda uma cópia completa das anotações. Quando você não precisar mais do backup, exclua o conjunto de dados na página de configurações dele.
• Um servidor alugado. Execute potato deploy pull config.yaml, confira a pasta baixada e depois execute potato deploy destroy config.yaml. O Potato se recusa a destruir um servidor cujos dados nunca foram baixados.

Perguntas comuns

Como crio um servidor do Potato para o meu estudo?

Você cria um servidor do Potato executando a sua tarefa em um computador que os anotadores alcançam por um endereço web. A equipe de TI da sua instituição pode executar a tarefa por você, um colega pode preparar um botão de implantação em que você clica, potato share pode servir um piloto do seu notebook e potato deploy up pode alugar um servidor para você. A tabela em Escolhendo um caminho compara os caminhos por custo e pelo trabalho de terminal que cada um exige.

Como instalo o Potato no meu PC?

Instale o Python 3.9 ou mais recente a partir de python.org e depois digite py -m pip install potato-annotation no PowerShell, no Windows, ou python3 -m pip install potato-annotation no Terminal, em um Mac. Depois da instalação, py -m potato start config.yaml no Windows ou python3 -m potato start config.yaml em um Mac inicia uma tarefa. Instalação cobre os recursos opcionais.

Palavras usadas nesta página

• Servidor. Um servidor é um computador que fica ligado e conectado à internet para que outras pessoas usem um programa dele por um navegador.
• URL, ou endereço web. Uma URL é o endereço que os anotadores digitam ou clicam, como https://my-study.example.edu. Um domínio é a parte do nome do endereço, aqui my-study.example.edu.
• HTTPS. O HTTPS criptografa tudo entre o navegador do anotador e o servidor, inclusive senhas e respostas. Os navegadores mostram um cadeado para um endereço HTTPS.
• Porta. Uma porta é um ponto de entrada numerado em um computador. O Potato escuta na porta 8000, a menos que a configuração nomeie outra porta, e o endereço local http://localhost:8000 termina nesse número.
• Terminal. Um terminal é um programa para digitar comandos, chamado Terminal no Mac e PowerShell no Windows.
• Chave de administrador. A chave de administrador é uma senha longa que abre o painel do administrador do Potato.
• Token de API. Um token de API é uma chave semelhante a uma senha que permite a um programa, como o comando de implantação do Potato, agir na sua conta em uma empresa de hospedagem.

Leitura adicional

• Requisitos de servidor do Potato para a sua equipe de TI, a página a enviar à sua equipe de TI
• Executar o Potato localmente ou na nuvem, para todos os hosts, botões de implantação e backups
• Implantar um servidor de anotação, para escolher um host para um estudo longo
• Executar o Potato no Docker, para servidores que executam contêineres
• Painel do Administrador, para acompanhar o progresso enquanto o estudo roda