Skip to content

Implantar o Potato em um Space do Hugging Face

Rode uma tarefa de anotação do Potato em um Docker Space do Hugging Face com o potato deploy e backup das anotações em um dataset privado a cada cinco minutos.

potato deploy up --provider huggingface executa uma tarefa de anotação em um Docker Space do Hugging Face, com HTTPS em um endereço hf.space e nada a configurar em um servidor. Ele serve para uma demonstração pública de uma tarefa e para um laboratório cujos dados e modelos já estão no Hugging Face Hub. O disco de um Space é apagado a cada reinicialização, então o Potato guarda as anotações em um dataset privado do Hugging Face que ele cria junto com o Space. Ele faz backup das anotações no dataset a cada cinco minutos e as restaura quando o Space inicia. Esta página exige o Potato 2.10 ou posterior e uma configuração que você já executou com potato start.

Requisitos e limites de um Space

Os Spaces do Potato são Docker Spaces, e criar um Docker Space exige um plano pago do Hugging Face: PRO para uma conta pessoal, ou Team ou Enterprise para uma organização. Uma conta ou organização no plano gratuito do Hugging Face também executa no máximo três Spaces ao mesmo tempo. Um quarto fica PAUSED e, ao contrário de um Space em suspensão, um Space pausado nunca acorda quando um visitante o abre.

Para um estudo que dura semanas com anotadores nominais, uma máquina virtual como o AWS Lightsail, o Jetstream2 ou a Hetzner mantém o disco entre reinicializações, então os dados não dependem de um backup. Um Space é mais adequado quando as pessoas que você quer alcançar já têm contas no Hugging Face, ou quando a tarefa é uma demonstração cujas anotações você pode se dar ao luxo de perder.

Configurando um token do Hugging Face

O Potato cria o Space e o dataset com o seu token do Hugging Face. Crie um token com acesso de escrita nas configurações do Hugging Face, depois instale o extra do Hugging Face e coloque o token no seu ambiente:

bash
pip install 'potato-annotation[huggingface]'
export HF_TOKEN=hf_...
potato deploy providers --verify

providers --verify exibe a conta à qual o token pertence. O Potato passa o token ao Space como segredo do Space, para que o backup possa gravar no dataset, e nunca o envia por commit ao repositório do Space.

Decidindo quem pode fazer login

potato deploy não altera as suas configurações de login, e um Space público pode ser aberto por qualquer pessoa que tenha o endereço. Se a configuração permite que qualquer pessoa se cadastre, a simulação abaixo informa o aviso D003, "Anyone who finds the URL can register and annotate." (Qualquer pessoa que encontrar a URL pode se cadastrar e anotar.) O cadastro aberto costuma servir para uma demonstração. Para anotadores nominais, liste-os em user_config.users com allow_all_users: false (Gerenciamento de Senhas), ou faça com que entrem com as próprias contas do Hugging Face, que o Potato aceita como provedor embutido em authentication.providers (Autenticação SSO e OAuth).

Conferindo o plano e implantando

Uma simulação não cria nada e exibe o que a implantação criaria:

bash
potato deploy up myproject/config.yaml --provider huggingface --dry-run

O plano cria o dataset privado <account>/<name>-annotations, depois um Docker Space <account>/<name>, define a chave de sessão, a chave de administrador e o token como segredos do Space e envia o seu projeto com um Dockerfile e um README. O Dockerfile parte da imagem publicada do Potato para a versão que você tem instalada, então o Space guarda apenas os arquivos do seu projeto. --owner implanta sob uma organização, --private torna o próprio Space privado e --name substitui o nome tirado da tarefa.

Execute o comando sem --dry-run e confirme o plano:

bash
potato deploy up myproject/config.yaml --provider huggingface

A implantação espera até o Space estar rodando e exibe o endereço dele, https://<account>-<name>.hf.space, e o caminho do arquivo da chave de administrador, .potato/secrets.json, ao lado da sua configuração. A chave de administrador abre o painel do administrador em /admin. Um Space em hardware gratuito entra em suspensão depois de 48 horas sem visitantes e acorda quando alguém o abre, e as anotações voltam do dataset a cada vez.

Encerrando o estudo

potato deploy pull baixa o dataset de backup, que guarda tudo o que o Space salvou, em vez de ler o próprio Space:

bash
potato deploy pull myproject/config.yaml
potato deploy destroy myproject/config.yaml

destroy apaga o Space e mantém o dataset, porque apagar um Space pode ser desfeito implantando de novo, e apagar as anotações não pode. Quando você não precisar mais do dataset, apague-o na página de configurações dele no Hub.

Implantando sem backup

--demo implanta o Space sem dataset, para uma demonstração cujas anotações não importam. A simulação então avisa que tudo o que for coletado se perde na próxima reinicialização. Sem dataset, pull lê o Space em execução pela exportação do administrador, o que só funciona enquanto o Space está no ar.

Solução de problemas

Um erro de pagamento na criação significa que a conta ou organização não tem plano pago. Docker Spaces exigem PRO para uma conta pessoal, ou Team ou Enterprise para uma organização.

O Space fica PAUSED quando uma conta do plano gratuito já executa três Spaces. Pause outro e depois reinicie este pela página de configurações dele. Reiniciar um Space existente não exige plano pago.

Faltam anotações depois de um rebuild quando o Space não conseguiu restaurar a partir do dataset. O log do Space mostra uma linha RESTORED quando a restauração dá certo, e a ausência dela geralmente significa que o segredo HF_TOKEN do Space está faltando ou não tem acesso de escrita.

BUILD_ERROR é explicado no log de build em https://huggingface.co/spaces/<account>/<name>?logs=build.

Leitura adicional