Hugging Face Spaces

Quando Usar

Use esta habilidade quando precisar construir, implantar e manter aplicações no Hugging Face Spaces — Gradio / Docker / SDKs Estáticos, ZeroGPU e hardware dedicado, carregamento de modelos, depuração, buckets, provedores de inferência, subsídios da comunidade. Use sempre que o usuário pedir para criar ou hospedar um aplicativo no Hugging Face, portar código para...

O Hugging Face Spaces hospeda aplicações de machine learning. Existem mais de 1 milhão hoje; cada Space é um repositório git. Esta habilidade cobre a criação, construção, depuração e manutenção deles.

0. Preparando-se

Antes de mais nada:

1. Verifique se a CLI hf está instalada: which hf. Se não estiver, pip install -U huggingface_hub.
2. Verifique se o usuário está logado: hf auth whoami. Se não estiver, peça para ele executar ! hf auth login nesta sessão — ele precisará de um token com escopo de escrita de https://huggingface.co/settings/tokens.
3. Anote as flags whoami e canPay da isPro — elas controlam as escolhas de hardware abaixo.

A habilidade hf-cli ensina a um agente todos os comandos hf e é a companheira recomendada para esta. Instale-a com hf skills add hf-cli (adicione --claude --global para instalar também para Claude Code, em nível de usuário).

1. O que é um Space

Um Space é um repositório git com três SDKs possíveis:

• Gradio — a maioria dos Spaces. Python, iteração rápida, suporta ZeroGPU.
• Docker — contêiner arbitrário. Use quando precisar de uma pilha não-Python ou um modelo pré-construído (Streamlit, Argilla, Shiny, etc. — lista completa em https://huggingface.co/docs/hub/spaces-sdks-docker). Não suporta ZeroGPU.
• Estático — HTML puro, ou um projeto React/Svelte/Vue construído no momento da implantação. Use para ML no navegador (transformers.js / WebGPU / WebAssembly / onnxruntime-web), páginas de projeto, relatórios interativos ou Spaces que orquestram outros Spaces. Não precisa de hardware.

Níveis de Hardware

Gratuito, sem custo para o criador: cpu-basic e zero-a10g (ZeroGPU). Spaces Estáticos também são gratuitos e não precisam de hardware.

cpu-basic — 2 vCPU / 16 GB. Para visualização de dados, Spaces de proxy de API, pequenos modelos limitados por CPU.

ZeroGPU (zero-a10g) — alocação dinâmica de GPU por solicitação em NVIDIA RTX PRO 6000 Blackwell (sm_120). Dois tamanhos: large (metade MIG, 48 GB, 1× cota) e xlarge (completo, 96 GB, 2× cota). Gratuito para o criador do Space; visitantes do Space consomem sua própria cota diária (~5 min grátis / 40 min Pro / 60 min Enterprise). Apenas Gradio, PyTorch-first. Requer que o criador esteja em um plano PRO / Team / Enterprise.

GPU Dedicada (T4, L4, A10G, L40S, A100, H200) — cobrado do criador do Space por hora. Lista + preços: hf spaces hardware. Apenas o criador pode anexar essas GPUs, e apenas se canPay=True. Use quando ZeroGPU genuinamente não for adequado — modelo principal não-PyTorch com inicialização pesada, inferência de modelo muito grande com contexto longo, etc.

Se um usuário não-PRO tiver um caso de uso que deseje ZeroGPU, você ainda pode construí-lo: crie um Space cpu-basic, codifique o aplicativo para ZeroGPU, envie, e então solicite um subsídio da comunidade. Veja references/grants.md.

Para a referência autoritativa: https://huggingface.co/docs/hub/spaces-overview

2. Procure por uma demonstração existente primeiro

Antes de decidir como construir qualquer coisa, pesquise por trabalhos anteriores:

hf spaces search "<model name or task>" --sdk gradio --limit 10

Se alguém construiu um Space semelhante, leia seu app.py e requirements.txt — isso lhe dará o padrão de funcionamento. Economiza muita iteração às cegas. Mencione ao usuário o que você encontrou antes de se comprometer com uma abordagem.

3. Decida o SDK e o hardware

Siga a solicitação explícita do usuário primeiro. Se ele foi vago:

• Padrão para uma demonstração pública de ML: Gradio + ZeroGPU. Use isso a menos que algo abaixo se aplique.
• O único caminho de inferência do modelo é não-PyTorch (ONNX / TF / JAX / vLLM como o modelo PRINCIPAL, com inicialização pesada): GPU dedicada.
  • Mas: ferramentas marginais não-torch (um pequeno pré-processador ONNX, uma utilidade TF) dentro de um pipeline com o principal em torch são aceitáveis no ZeroGPU. O "hijack" apenas modifica o torch; inicialize a biblioteca não-torch dentro de @spaces.GPU e pague o curto custo de inicialização por chamada.
• Modelo pequeno / limitado por CPU, ou Space de proxy de API: cpu-basic (hardware-grátis não se aplica ao Gradio).
• ML no lado do navegador ou página de projeto: Estático.
• Contêiner com pilha não-Python: Docker.

Obtenção do modelo

…