Hugging Face ZeroGPU

Quando Usar

Use esta habilidade quando precisar de demonstrações de IA e computação com GPU usando Gradio Spaces e Hugging Face Spaces ZeroGPU. Use ao escrever ou revisar código que utiliza @spaces.GPU, configurar python_version ou requirements.txt para um Space ZeroGPU, ou lidar com restrições de código específicas do ZeroGPU — processo baseado em pickle...

Regras e padrões para demonstrações de ML no Hugging Face Spaces com hardware ZeroGPU. Abrange @spaces.GPU, ajuste de duração e cota, isolamento de processos, o modelo de disponibilidade CUDA, segurança de concorrência e restrições de compilação CUDA.

Escopo

Esta habilidade é para Spaces do SDK Gradio usando hardware ZeroGPU. Docker e Static Spaces não podem ser agendados no ZeroGPU, e aplicativos Streamlit agora rodam como Docker Spaces — então esta habilidade se aplica apenas ao Gradio. Para codificação Gradio geral (componentes, layouts, ouvintes de eventos), consulte a habilidade huggingface-gradio neste repositório. A documentação oficial do ZeroGPU está em https://huggingface.co/docs/hub/spaces-zerogpu — consulte-a para obter a GPU de suporte atual, listas de versões de runtime e limites de nível, todos os quais mudam com o tempo.

Arquivos de Referência

Hardware

ZeroGPU expõe dois tamanhos de GPU que mapeiam para uma fração da placa de suporte:

O large padrão fornece metade de uma GPU física, então a largura de banda de memória e a computação são significativamente menores do que as especificações da placa completa. Use xlarge apenas quando a carga de trabalho realmente precisar da memória ou computação extra.

A GPU de suporte muda sem aviso. ZeroGPU já migrou entre gerações de GPU várias vezes; artigos mais antigos podem mencionar A100 ou H200, mas eles estão desatualizados. Para a GPU de suporte atual e VRAM exata por tamanho, sempre verifique a documentação do ZeroGPU antes de dimensionar cargas de trabalho.

Padrão Básico

import spaces
import torch
from transformers import pipeline

pipe = pipeline("text-generation", model="...", device="cuda")

@spaces.GPU
def generate(prompt: str) -> str:
    return pipe(prompt, max_new_tokens=100)[0]["generated_text"]

Regras principais:

1. Instancie modelos no escopo do módulo e chame .to("cuda") de forma antecipada. ZeroGPU lida com o mapeamento real do dispositivo de forma transparente (veja o modelo de disponibilidade CUDA abaixo).
2. Decore funções de GPU com @spaces.GPU. O decorador é um no-op fora do ZeroGPU, então é seguro mantê-lo em todos os ambientes.
3. Defina duration para corresponder à pior carga de trabalho realista (padrão 60s). A plataforma pré-verifica requested duration contra a remaining quota do usuário — não contra o tempo de execução real — então uma tarefa de 10 segundos deixada no padrão de 60s falha com quota exceeded assim que a cota restante do usuário cair abaixo de 60s. Declarações de duration menores também classificam mais alto na fila em nível de nó. Veja "Duração e Cota" abaixo.
4. torch.compile NÃO é suportado. Use a compilação ahead-of-time (AoTI) do PyTorch ahead-of-time compilation (AoTI) (torch 2.8+) em vez disso.
5. Use size="xlarge" com moderação. Ele aloca a GPU de suporte completa, mas custa 2x a cota e tende a ter filas mais longas.

@spaces.GPU(duration=120)
def generate_image(prompt: str):
    return pipe(prompt).images[0]

Modelo de Disponibilidade CUDA

O acesso real à GPU está apenas disponível dentro de funções decoradas com @spaces.GPU. Fora dessas funções, a GPU não está conectada ao processo.

No entanto, import spaces monkey-patches torch para que:

• torch.cuda.is_available() retorne True globalmente.
• Chamadas de .to("cuda") / device="cuda" no escopo do módulo sejam bem-sucedidas sem erro.

…