# Spaces ZeroGPU: Alocação Dinâmica de GPU para Spaces

ZeroGPU é uma infraestrutura compartilhada que otimiza o uso de GPUs para modelos e demonstrações de IA nos Hugging Face Spaces. Ele aloca e libera dinamicamente GPUs NVIDIA RTX Pro 6000 Blackwell conforme necessário, oferecendo:

1. **Acesso gratuito a GPUs**: permite o uso de GPUs de forma econômica para os Spaces.
2. **Suporte a múltiplas GPUs**: Permite que os Spaces utilizem várias GPUs simultaneamente em um único aplicativo.

Diferentemente das alocações tradicionais em uma única GPU, o sistema eficiente do ZeroGPU reduz as barreiras para que desenvolvedores, pesquisadores e organizações implantem modelos de IA, maximizando o uso de recursos e a eficiência energética.

## Usando e hospedando Spaces ZeroGPU

- **Usando Spaces ZeroGPU existentes**
  - Os Spaces ZeroGPU estão disponíveis gratuitamente para todos os usuários. (Visite [a lista curada](https://huggingface.co/spaces/enzostvs/zero-gpu-spaces)).
  - Usuários [PRO](https://huggingface.co/subscribe/pro) têm 8x mais cota de uso diário, a maior prioridade nas filas de GPU e podem exceder sua cota diária usando créditos pré-pagos ao utilizar qualquer Space ZeroGPU.
- **Hospedando seus próprios Spaces ZeroGPU**
  - Contas pessoais gratuitas: contas em dia (e-mail verificado, conta com mais de 30 dias) podem hospedar até 2 Spaces ZeroGPU gratuitamente.
  - Contas PRO: [Assine o PRO](https://huggingface.co/settings/billing/subscription) para hospedar até 10 Spaces ZeroGPU em sua conta.
  - Organizações: [Assine um plano Team ou Enterprise](https://huggingface.co/enterprise) para habilitar Spaces ZeroGPU para todos os membros da organização.

## Especificações Técnicas

ZeroGPU suporta dois tamanhos de GPU

| Tamanho da GPU            | Hardware de suporte                   | Vram | Custo de cota |
|---------------------|------------------------------------|------|------------|
| `large` *(padrão)* | Metade de uma NVIDIA RTX Pro 6000 Blackwell | 48GB | 1×         |
| `xlarge`            | NVIDIA RTX Pro 6000 Blackwell completo | 96GB | 2×         |

> [!NOTE]
> Veja [seleção do tamanho da GPU](#gpu-size-selection) para aprender a usar os tamanhos

## Compatibilidade

Os Spaces ZeroGPU foram projetados para serem compatíveis com a maioria dos Spaces de GPU baseados em PyTorch. Embora a compatibilidade seja aprimorada para bibliotecas de alto nível do Hugging Face, como `transformers` e `diffusers`, os usuários devem estar cientes de que:

- Atualmente, os Spaces ZeroGPU são compatíveis exclusivamente com o **Gradio SDK**.
- Os Spaces ZeroGPU podem ter compatibilidade limitada em comparação com os Spaces GPU padrão.
- Problemas inesperados podem surgir em alguns cenários.

### Versões Suportadas

- **Gradio**: 4+
- **PyTorch**: Quase todas as versões de **2.8.0** até a **latest** são suportadas
  
    Veja a lista completa

    - 2.8.0  
    - 2.9.1  
    - 2.10.0  
    - 2.11.0  
    - 2.12.1  
    - 2.13.0  

  
- **Python**:
  - 3.12.12  
  - 3.10.13  

## Começando com o ZeroGPU

Para utilizar o ZeroGPU no seu Space, siga estas etapas:

1. Certifique-se de que o hardware ZeroGPU esteja selecionado nas configurações do seu Space.
2. Importe o módulo `spaces`.
3. Decore as funções dependentes de GPU com `@spaces.GPU`.

Esse processo de decoração permite que o Space solicite uma GPU quando a função é chamada e a libere ao término.

> [!NOTE]
> O decorador `@spaces.GPU` foi projetado para ser sem efeitos em ambientes não-ZeroGPU, garantindo compatibilidade entre diferentes configurações.

### Exemplo de uso

```python
import spaces
from diffusers import DiffusionPipeline

pipe = DiffusionPipeline.from_pretrained(...)
pipe.to('cuda')

@spaces.GPU
def generate(prompt):
    return pipe(prompt).images

gr.Interface(
    fn=generate,
    inputs=gr.Text(),
    outputs=gr.Gallery(),
).launch()
```

### Carregamento de modelos

Embora uma GPU real só esteja disponível dentro de funções `@spaces.GPU`, os modelos devem ser colocados em `cuda` no nível do módulo raiz (como mostrado no exemplo acima).

Carregar modelos de forma preguiçosa ou movê-los para a CUDA dentro de `@spaces.GPU` é desencorajado, pois é significativamente menos eficiente (as transferências de CUDA são otimizadas para posicionamentos feitos durante a inicialização).

> [!NOTE]
> Carregar modelos em `cuda` no nível do módulo funciona porque um modo de emulação de CUDA do PyTorch é ativado fora das funções `@spaces.GPU`, permitindo operações de CUDA sem uma GPU real. Dentro de `@spaces.GPU`, o CUDA real é utilizado.

## Seleção do tamanho da GPU

O tamanho padrão usado por `@spaces.GPU` é `large` (metade de uma NVIDIA RTX Pro 6000 Blackwell).

Você pode solicitar explicitamente um NVIDIA RTX Pro 6000 Blackwell completo especificando `size="xlarge"`:

``` python
@spaces.GPU(size="xlarge")
def generate(prompt):
    return pipe(prompt).images
```

> [!NOTE]
> - `xlarge` consome **2×** mais cota diária do que `large` (por exemplo, uma duração de tarefa **efetiva** de 45s consome 90s de cota) - `xlarge` geralmente significa maior probabilidade de fila e tempos de espera mais longos - Use `xlarge` apenas quando sua carga de trabalho se beneficiar genuinamente do compute ou da memória adicionais

## Gestão de Duração

Para funções que se espera exceder o tempo de execução padrão de 60 segundos na GPU, você pode especificar uma duração personalizada:

```python
@spaces.GPU(duration=120)
def generate(prompt):
   return pipe(prompt).images
```

Isso define o tempo máximo de execução da função em 120 segundos. Especificar durações mais curtas para funções mais rápidas melhorará a prioridade da fila para os visitantes do Space.

### Duração dinâmica

`@spaces.GPU` também suporta durações dinâmicas.

Em vez de passar diretamente uma duração, basta passar uma função chamável que recebe as mesmas entradas da sua função decorada e retorna um valor de duração:

```python
def get_duration(prompt, steps):
    step_duration = 3.75
    return steps * step_duration

@spaces.GPU(duration=get_duration)
def generate(prompt, steps):
   return pipe(prompt, num_inference_steps=steps).images
```

## Compilação

ZeroGPU não suporta `torch.compile`, mas você pode usar a compilação **ahead-of-time** do PyTorch (requer torch `2.8+`)

Confira este [blogpost](https://huggingface.co/blog/zerogpu-aoti) para um guia completo sobre compilação antecipada no ZeroGPU.

## Níveis de Uso

O uso de GPU está sujeito a cotas **diárias**, por nível de conta:

| Tipo de conta                   | Cota diária de GPU incluída | Prioridade da fila  |
| ------------------------------ | ------------------------ | --------------- |
| Não autenticado                | 2 minutos                | Baixo             |
| Conta gratuita                   | 5 minutos                | Médio          |
| Conta PRO                    | 40 minutos (extensível)  | Mais alto         |
| Membro da organização da equipe       | 40 minutos (extensível)  | Mais alto         |
| Membro de organização empresarial | 60 minutos (extensível)  | Mais alto         |

A cota diária incluída é redefinida exatamente 24 horas após o primeiro uso da sua GPU.

> [!NOTE]
> A cota restante impacta diretamente a prioridade nas filas do ZeroGPU.

### Estendendo a cota com créditos

Usuários PRO, Team e Enterprise podem continuar usando Spaces ZeroGPU além da cota diária incluída, consumindo créditos pré-pagos na taxa de **US$ 1 por 10 minutos** de tempo de GPU. Assim que sua cota diária for esgotada, qualquer uso adicional de GPU será cobrado automaticamente do seu saldo de créditos.

Você pode adicionar créditos em suas [configurações de faturamento](https://huggingface.co/settings/billing).

## Limitações de Hospedagem

- **Contas pessoais gratuitas**: Máximo de 2 Spaces ZeroGPU, para contas em bom estado (e-mail verificado, conta com mais de 30 dias).
- **Contas pessoais ([assinantes PRO](https://huggingface.co/subscribe/pro))**: Máximo de 10 Spaces ZeroGPU.
- **Contas de organização ([Team & Enterprise](https://huggingface.co/enterprise))**: Máximo de 50 Spaces ZeroGPU.

Ao aproveitar o ZeroGPU, os desenvolvedores podem criar Spaces mais eficientes e escaláveis, maximizando o uso da GPU e minimizando os custos.

## Recomendações

Se a sua demonstração utiliza um modelo grande, recomendamos o uso de otimizações como compilação antecipada (ahead-of-time) e flash-attention 3. Você pode aprender a aproveitar esses recursos com o ZeroGPU em [este post](https://huggingface.co/blog/zerogpu-aoti). Essas otimizações ajudarão você a maximizar as vantagens das horas de ZeroGPU e a oferecer uma melhor experiência ao usuário.

## Feedback

Você pode compartilhar seu feedback sobre o Spaces ZeroGPU diretamente no HF Hub: https://huggingface.co/spaces/zero-gpu-explorers/README/discussions