Hugging Face Spaces: o que é e como usar ?

#Hugging Face Spaces: o que é exatamente?

Um Space é um pequeno aplicativo web hospedado pelo Hugging Face. Tecnicamente, é um repositório git, como os de modelos e datasets do Hub: ele contém o código do aplicativo, um arquivo de dependências e um README cujo cabeçalho YAML descreve a configuração. A cada commit enviado a esse repositório, o Hugging Face reconstrói e reinicia o aplicativo. O visitante, por sua vez, só vê uma página com campos, botões e um resultado.

Se você está conhecendo o Hugging Face agora, guarde a diferença em relação a uma página de modelo: a página de modelo contém arquivos (pesos, tokenizer, configuração) que você baixa; um Space executa código em um servidor para mostrar a você o que o modelo sabe fazer. O guia « Hugging Face: c'est quoi, et comment s'en servir? » aborda o Hub em geral; aqui, falamos apenas dos Spaces.

A documentação oficial oferece três tipos de Spaces, chamados SDKs, a serem escolhidos na criação:

Gradio

O caso mais comum. Gradio é uma biblioteca Python que gera uma interface web a partir de uma função: uma caixa de texto na entrada, uma imagem na saída etc. A maioria das demos de LLMs e de modelos de imagem são Spaces Gradio.

Docker

O Space é construído a partir de um Dockerfile. Portanto, ele pode rodar qualquer aplicação web: uma interface de chat completa, um servidor de API, uma ferramenta escrita em outra linguagem que não seja Python.

HTML estático

Uma página simples em HTML, CSS e JavaScript, sem servidor de processamento. Útil para documentação, visualização ou uma demo que roda inteiramente no navegador.

Cada Space tem um endereço no Hub, no formato huggingface.co/spaces/proprietário/nome, e um endereço direto do aplicativo, no formato proprietário-nome.hf.space. Os Spaces podem ser públicos (código e aplicativo visíveis para todos), protegidos (código privado, aplicativo acessível) ou privados (restritos ao proprietário e seus colaboradores).

#Etapa 1: usar uma demo no navegador

Para testar um Space, na maioria dos casos não é necessário ter conta. A página inicial dos Spaces (huggingface.co/spaces) permite pesquisar por palavra-chave ou por tarefa e ordenar por tendência ou por número de “likes”. Muitas páginas de modelos também exibem, na coluna da direita, a lista de Spaces que usam esse modelo.

1. 01
   Encontrar o Space certo

   Dê preferência aos Spaces publicados pelo desenvolvedor do modelo (a conta oficial da organização) ou muito seguidos. Um Space recente de uma conta desconhecida pode funcionar muito bem, mas você não sabe o que o código dele faz com os dados enviados.
2. 02
   Ler o status exibido

   No topo da página, um selo indica o status: em execução (Running), em construção (Building), em suspensão (Sleeping), pausado ou com erro. Um Space em suspensão é reativado quando alguém o acessa, o que pode levar algum tempo enquanto o aplicativo reinicia.
3. 03
   Enviar uma requisição

   Preencha os campos e confirme. Em um Space que compartilha uma GPU entre todos os visitantes, pode aparecer uma fila de espera antes do processamento.
4. 04
   Verificar o que você está testando

   Abra a aba Files para ler o arquivo principal (geralmente app.py) e o README. Lá você verá qual modelo é carregado, com qual precisão (FP16, quantização de 4 bits…) e com quais parâmetros. Uma demo nem sempre é a versão completa do modelo anunciado.

#Etapa 2: chamar um Space Gradio via API

Um Space Gradio não é só uma página web: ele também expõe uma API. O link “Use via API”, na parte inferior do aplicativo, mostra os endpoints disponíveis e exemplos de código. Em Python, a biblioteca oficial gradio_client permite chamar um Space como uma função, o que é prático para testar um modelo em uma série de exemplos sem clicar manualmente.

pip install gradio_client

from gradio_client import Client

# Remplacez par l'identifiant du Space (propriétaire/nom)
client = Client("proprietaire/nom-du-space")

# Affiche les points d'entrée et leurs paramètres
client.view_api()

Depois de conhecer os parâmetros, o método client.predict() envia uma requisição com os argumentos esperados e um api_name indicado por view_api(). As cotas e filas de espera do Space se aplicam a essas chamadas assim como às visitas pelo navegador: não é uma solução para processar grandes volumes. Para um Space privado ou para se identificar (e aproveitar a cota de ZeroGPU da sua conta), passe um token de acesso do Hugging Face para Client().

#Etapa 3: duplicar um Space

Duplicar um Space cria uma cópia completa na sua conta. Isso é útil para partir de uma demo existente e modificá-la, ou para ter sua própria instância sem dividir a fila de espera com todos os visitantes. Isso é feito pelo menu de três pontos no canto superior direito da página, opção "Duplicate this Space".

1. 01
   Escolher o proprietário e o nome

   A cópia pode ir para a sua conta pessoal ou para uma organização em que você tenha permissão de escrita.
2. 02
   Ajustar a visibilidade

   A cópia é privada por padrão. Mantenha-a privada se você pretende processar seus próprios dados nela.
3. 03
   Escolher o hardware

   Por padrão, a cópia roda em CPU Basic. Uma GPU paga pode ser escolhida nesse momento ou depois, nas configurações (Settings).
4. 04
   Preencher os segredos

   As variáveis públicas do Space original são copiadas automaticamente. Os secrets (tokens, chaves de API) nunca são: a interface avisa você se for preciso fornecê-los. Sem eles, o aplicativo pode iniciar e depois falhar na primeira requisição.

Acima do CPU Basic, o hardware é cobrado por hora. A documentação indica, por exemplo, US$ 0,40 por hora para uma NVIDIA T4 small, em 26/10/2026; a tabela completa e atualizada está na página de preços do Hugging Face. Um Space pago pode ser pausado nas configurações dele: o tempo em pausa não é cobrado.

#Etapa 4: executar um Space do Hugging Face localmente

Como o código de um Space público pode ser lido e clonado, você pode executá-lo na sua própria máquina. Há dois métodos: obter a imagem Docker construída pelo Hugging Face ou clonar o repositório e iniciar o aplicativo você mesmo.

#Método A: a imagem Docker do Space

A documentação indica que a maioria dos Spaces pode ser executada com Docker. O botão “Run with Docker”, no menu no canto superior direito da página do Space, mostra o comando exato a ser copiado. Ele geralmente tem o seguinte formato, com a imagem hospedada no registro registry.hf.space:

docker run -it -p 7860:7860 --platform=linux/amd64 \
  registry.hf.space/proprietaire-nom-du-space:latest python app.py

Sempre copie o comando fornecido pelo botão em vez de montá-lo por conta própria: o nome da imagem, o comando de inicialização e as eventuais variáveis (opção -e, por exemplo para um token HF_TOKEN) dependem do Space. Alguns Spaces exigem login no registro com seu nome de usuário do Hugging Face e um token de acesso no lugar da senha:

docker login registry.hf.space

Para que um contêiner use uma placa NVIDIA, o Docker precisa do NVIDIA Container Toolkit na máquina host, e a opção --gpus all deve ser adicionada ao comando docker run. As imagens são construídas para a arquitetura x86_64 (linux/amd64): em um Mac com Apple Silicon, elas rodam por emulação, sem acesso à GPU do Mac. Nesse caso, o método B costuma ser mais adequado.

#Método B: clonar o repositório e iniciar o aplicativo

O menu do Space também oferece “Clone repository”, via HTTPS ou SSH. Para um Space Gradio, a sequência clássica consiste em clonar, criar um ambiente Python isolado, instalar as dependências listadas em requirements.txt e, em seguida, executar o arquivo principal:

git clone https://huggingface.co/spaces/proprietaire/nom-du-space
cd nom-du-space
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install gradio
python app.py

Em seguida, o Gradio exibe o endereço local da interface, por padrão http://127.0.0.1:7860. Alguns pontos a verificar antes de executar:

Cabeçalho do README

As chaves sdk_version, app_file e, às vezes, python_version indicam a versão do Gradio, o arquivo a ser executado e a versão do Python usadas online. Instalar a mesma versão do Gradio (pip install "gradio==X.Y.Z") evita muitos erros de interface.

Arquivos grandes

Um Space pode conter arquivos grandes armazenados pelo sistema de armazenamento do Hub. Se, após a clonagem, alguns arquivos aparecerem como pequenos ponteiros de texto, instale a extensão do git recomendada pelo Hugging Face (git-xet ou Git LFS) e refaça o download.

Decorador @spaces.GPU

Os Spaces ZeroGPU importam o módulo spaces e decoram suas funções com @spaces.GPU. A documentação especifica que esse decorador não tem nenhum efeito fora do ZeroGPU: basta instalar o pacote spaces (pip install spaces) para que o código seja executado na sua própria GPU.

Secrets

Se o código lê variáveis de ambiente (os.getenv), defina-as no seu terminal antes de executar o app.py. Um modelo com acesso condicionado exige um token do Hugging Face associado a uma conta que tenha aceitado a licença.

Para um Space Docker, o repositório clonado contém um Dockerfile: basta rodar docker build e depois docker run, publicando a porta declarada por app_port no README (7860 por padrão).

#Limitações dos Hugging Face Spaces: computação e privacidade

Um Space é perfeito para uma primeira impressão. Para uso regular, suas limitações aparecem rapidamente. As que seguem vêm da documentação oficial consultada em 26/10/2026.

Hardware gratuito modesto

O hardware padrão, CPU Basic, oferece 2 vCPUs, 16 GB de RAM e 50 GB de disco, sem GPU. Um LLM de vários bilhões de parâmetros roda lentamente nele, quando cabe na memória.

Disco não persistente

Os 50 GB de disco são apagados na reinicialização. Os arquivos enviados ou gerados não são mantidos, a menos que o proprietário tenha configurado armazenamento persistente.

Hibernação

No hardware gratuito, um Space sem uso entra em suspensão depois de certo tempo e precisa reiniciar na visita seguinte. O proprietário também pode pausá-lo ou até excluí-lo: uma demo disponível hoje pode sumir amanhã.

Cotas do ZeroGPU

O tempo diário de GPU é limitado por conta (veja acima), e cada requisição é limitada por padrão a 60 segundos de GPU, a menos que o autor defina uma duração maior. A cota é redefinida 24 horas após o primeiro uso.

Rede restrita

Um Space só pode fazer conexões de saída pelas portas 80, 443 e 8080. Um aplicativo que precise acessar um serviço em outra porta não funcionará do jeito que está.

Quanto à privacidade, a regra é simples: tudo o que você digita em um Space é enviado a um servidor que executa o código de outra pessoa. Esse código pode registrar as requisições, repassá-las a uma API de terceiros ou manter os arquivos enviados durante a sessão. Em um Space público, você pode verificar isso lendo o app.py; em um Space protegido, o código não fica visível. Portanto, não cole em uma demo nenhum documento de cliente, dado pessoal, código proprietário ou credencial.

#Quando preferir a execução local

O ideal é usar os Spaces para decidir e depois passar para a execução local para trabalhar. Algumas situações em que a execução local leva clara vantagem:

Dados sensíveis

Contratos, prontuários médicos, código da empresa: com um modelo local, nada sai da sua máquina.

Uso diário ou em volume

As cotas do ZeroGPU e as filas de espera tornam um Space inadequado para uso intenso. Localmente, o único limite é o seu hardware.

Necessidade de estabilidade

Um Space pode mudar de modelo, de versão ou desaparecer. Um modelo baixado e congelado gera resultados reproduzíveis.

Integração com suas ferramentas

Ollama expõe uma API local em http://localhost:11434, que pode ser usada por Open WebUI, por scripts ou por automações, sem depender de um serviço remoto.

Aliás, no caso de um LLM, migrar para o local não exige necessariamente clonar o Space. Muitas demos carregam o modelo completo no formato safetensors, em FP16: nesse caso, os pesos de um modelo 7B ocupam cerca de 14 GB, mais do que a maioria das placas de consumo suporta. A versão quantizada do mesmo modelo no formato GGUF, em Q4_K_M, exige cerca de 5 GB de VRAM e roda em uma RTX 3060 de 12 GB. Muitas vezes, o mais simples é anotar o nome do modelo usado pelo Space, procurar a versão GGUF dele no Hub e importá-la no Ollama.

3B em Q4

cerca de 2 GB de VRAM

7B em Q4

cerca de 5 GB

14B em Q4

cerca de 9 GB (RTX 4070 12 GB)

32B em Q4

cerca de 19 GB (RTX 4090 24 GB ou Mac M4 Pro com 24 a 48 GB de memória unificada)

70B em Q4

cerca de 40 GB

#Solução de problemas

“Runtime error” na página

O Space travou na inicialização. A aba Logs, quando está acessível, mostra a causa. Se o Space for de outra pessoa, você só pode esperar, procurar outro Space ou relatar o problema na aba Community.

Mensagem de cota de GPU excedida

Sua cota diária do ZeroGPU se esgotou. Faça login, se ainda não fez, aguarde a redefinição ou execute o modelo localmente.

Erro de import après pip install

A versão do Gradio ou de alguma dependência é diferente da usada pelo Space. Use as mesmas sdk_version e python_version do README, em um ambiente virtual novo.

CUDA não encontrado localmente

O código espera uma GPU NVIDIA. Verifique se o PyTorch foi instalado com suporte a CUDA ou adapte o código para usar a CPU (ou mps no Mac), ao custo de uma execução mais lenta.

Imagem Docker recusada ou não encontrada

Faça login no registro com docker login registry.hf.space e, em seguida, verifique se o nome da imagem corresponde ao fornecido pelo botão “Run with Docker”.

#Para se aprofundar

Este guia aborda os Spaces. Para entender o Hub como um todo, distinguir os formatos de arquivo ou passar de uma demo para um modelo que roda na sua máquina, estes guias dão continuidade.